1<erl>
2
3box(Str) ->
4    {'div',[{class,"box"}],
5     {pre,[], yaws_api:htmlize(Str)}}.
6
7out(A) ->
8    [{ssi, "TAB.inc", "%%",[{"rebar_release", "choosen"}]}].
9
10</erl>
11
12<div id="entry">
13  <h1>Creating a Release with Rebar</h1>
14  <p>
15
16    One way to create an Erlang release for a project that depends on Yaws,
17    or a set of applications that includes Yaws, is to use the <a
18    href="https://github.com/rebar/rebar">rebar</a> build tool. This page
19    details the steps required to set up the proper directory structure for
20    such a project, create and generate the necessary release configuration
21    files, and how to package a release for later installation and
22    deployment.
23
24  </p>
25
26  <h2>Rebar Templates</h2>
27  <p>
28
29    The easiest way to build a release that uses Yaws is to use the rebar
30    template files found under the rebar-templates directory found at the
31    top-level of the Yaws repository. To do this, first copy all the files
32    in the rebar-templates directory into your $HOME/.rebar/templates
33    directory, creating it if necessary:
34
35  </p>
36
37  <p>
38    <div class="box">
39      <pre>
40$ mkdir -p ~/.rebar/templates
41$ cp rebar-templates/* ~/.rebar/templates
42      </pre>
43    </div>
44  </p>
45
46  <p>
47
48    Next, run rebar in your <code>foo</code> project directory to create a
49    release project skeleton, specifying the yawsnode template so rebar
50    knows what to create. Note also that we specify <code>foo</code> as the
51    nodeid and <code>myapp</code> as the appid:
52
53  </p>
54
55  <p>
56    <div class="box">
57      <pre>
58$ cd /path/to/foo
59$ rebar create template=yawsnode nodeid=foo appid=myapp
60      </pre>
61    </div>
62  </p>
63
64  <p>
65
66    This creates two subdirectories and a rebar.config file, described
67    below:
68
69  </p>
70  <p>
71    <dl>
72      <dt><code>apps</code></dt>
73      <dd>
74        holds directories for the applications that comprise the
75        <code>foo</code> project
76      </dd>
77      <dt><code>rebar.config</code></dt>
78      <dd>
79        build configuration for the <code>foo</code> project
80      </dd>
81      <dt><code>rel</code></dt>
82      <dd>
83        provides support files for creating project releases
84      </dd>
85    </dl>
86  </p>
87
88  <h3>The apps Directory</h3>
89  <p>
90
91    Let's assume we have a single application named <code>myapp</code> that
92    depends on Yaws, and <code>myapp</code> and Yaws together comprise the
93    <code>foo</code> project. The <code>apps</code> directory therefore
94    contains a <code>myapp</code> subdirectory, which is a normal Erlang
95    project directory that should contain its own <code>rebar.config</code>
96    file, a <code>src</code> directory containing Erlang source code,
97    etc. Since <code>myapp</code> depends on Yaws, its
98    <code>rebar.config</code> file should specify Yaws as a
99    dependency. Note that the yawsnode rebar template does not create any
100    of this for you; you're expected to create your own application files
101    yourself.
102
103  </p>
104
105  <h2>Building the Project</h2>
106  <p>
107
108    To build the <code>foo</code> project, use rebar:
109
110  </p>
111
112  <p>
113    <div class="box">
114      <pre>
115$ rebar get-deps compile
116      </pre>
117    </div>
118  </p>
119
120  <p>
121
122    This first fetches all dependencies for all the applications under the
123    <code>apps</code> directory, and the compiles them along with all the
124    apps.
125
126  </p>
127
128  <h2>Creating a Release</h2>
129  <p>
130
131    Once everything is compiled, you can change to the <code>rel</code>
132    directory and generate a release. Prior to that, though, you might want
133    to edit the rel/files/yaws.conf file to ensure Yaws will be configured
134    properly for your project when you run the generated release. That file
135    is copied into the generated release. Once you've done that, run "rebar
136    generate" in the rel directory:
137
138  </p>
139
140  <p>
141    <div class="box">
142      <pre>
143$ cd rel
144$ rebar generate
145      </pre>
146    </div>
147  </p>
148
149  <p>
150
151    Because we specified the nodeid as <code>foo</code> when we created the
152    project, the generation step creates a <code>foo</code> directory under
153    rel that holds the generated release. It contains an Erlang runtime
154    along with all the standard and application-specific modules and
155    support files needed to run your project, all in a relocatable
156    directory structure. To package it for deployment, just tar it up:
157
158  </p>
159
160  <p>
161    <div class="box">
162      <pre>
163$ cd foo
164$ tar zcf ../foo.tar.gz *
165      </pre>
166    </div>
167  </p>
168
169  <p>
170
171    This packs up the whole release into the file rel/foo.tar.gz.
172
173  </p>
174
175  <h2>Deploying the Project</h2>
176  <p>
177
178    To deploy your project release, copy the tar file onto the target host,
179    unpack it into an installation directory of your choice, and then run
180    the <code>install.sh</code> script to ensure any absolute paths in the
181    release reflect the chosen installation directory. You can then run the
182    node using the <code>bin/foo</code> script:
183
184  </p>
185
186  <p>
187    <div class="box">
188      <pre>
189$ &lt; login to target host, copy foo.tar.gz over &gt;
190$ cd /install/path
191$ tar zxf foo.tar.gz
192$ ./install.sh
193$ ./bin/foo console
194      </pre>
195    </div>
196  </p>
197
198  <p>
199
200    The final command above starts the node with an interactive shell. Once
201    it's running, Yaws and all the other applications that comprise the
202    project will be executing. You can alternatively start the node as a
203    daemon by running "./bin/foo start" and later stop it with "./bin/foo
204    stop". Run "./bin/foo" with no arguments to see all its other
205    command-line arguments.
206
207  </p>
208
209</div>
210