doc: epub and mobi support
[openafs.git] / doc / xml / QuickStartUnix / auqbg008.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <appendix id="HDRWQ163">
3   <title>Appendix A. Building OpenAFS from Source Code</title>
4
5   <para>This chapter describes how to build OpenAFS from source code. <indexterm>
6       <primary>storing</primary>
7
8       <secondary>OpenAFS source in volume</secondary>
9     </indexterm> <indexterm>
10       <primary>creating</primary>
11
12       <secondary>volume</secondary>
13
14       <tertiary>for OpenAFS source</tertiary>
15     </indexterm> <indexterm>
16       <primary>volume</primary>
17
18       <secondary>for OpenAFS source</secondary>
19     </indexterm> <indexterm>
20       <primary>source (AFS)</primary>
21
22       <secondary>storing in AFS volume</secondary>
23     </indexterm> <indexterm>
24       <primary>files</primary>
25
26       <secondary>OpenAFS source</secondary>
27     </indexterm></para>
28
29   <sect1 id="HDRWQ164">
30     <title>Loading the Source Files</title>
31
32     <para>Working on an AFS client machine, login to AFS as a
33     administrative user, then perform these steps to load the OpenAFS
34     source tree from the OpenAFS Source Distribution.
35     <orderedlist>
36         <indexterm>
37           <primary>commands</primary>
38
39           <secondary>vos create</secondary>
40
41           <tertiary>src.afs volume</tertiary>
42         </indexterm>
43
44         <indexterm>
45           <primary>vos commands</primary>
46
47           <secondary>create</secondary>
48
49           <tertiary>src.afs volume</tertiary>
50         </indexterm>
51
52         <indexterm>
53           <primary>src.afs volume</primary>
54         </indexterm>
55
56         <indexterm>
57           <primary>volume</primary>
58
59           <secondary>creating</secondary>
60
61           <tertiary>src.afs</tertiary>
62         </indexterm>
63
64         <indexterm>
65           <primary>creating</primary>
66
67           <secondary>src.afs volume</secondary>
68         </indexterm>
69
70         <listitem>
71           <para>Create and mount a volume for housing the OpenAFS source tree. These instructions name the volume <emphasis
72           role="bold">src.afs</emphasis> and mount it at the <emphasis
73           role="bold">/afs/</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/afs/src</emphasis> directory.</para>
74
75           <para>Setting the <emphasis role="bold">-maxquota</emphasis> argument to <emphasis role="bold">0</emphasis> (zero) sets an
76           unlimited quota on the volume, which enables you to copy all of the files into the volume without exceeding its quota. If
77           you wish, you can set the volume's quota to a finite value after you complete the copying operation. At that point, use
78           the <emphasis role="bold">vos examine</emphasis> command to determine how much space the volume is occupying. Then issue
79           the <emphasis role="bold">fs setquota</emphasis> command to set a quota that is slightly larger.</para>
80
81           <programlisting>
82    # <emphasis role="bold">vos create</emphasis> &lt;<replaceable>machine name</replaceable>&gt; &lt;<replaceable>partition name</replaceable>&gt; <emphasis
83               role="bold">src.afs -maxquota 0</emphasis> 
84    # <emphasis role="bold">cd /afs/.</emphasis><replaceable>cellname</replaceable>
85    # <emphasis role="bold">mkdir afs</emphasis>
86    # <emphasis role="bold">fs mkmount afs/src src.afs</emphasis>
87    # <emphasis role="bold">vos release root.cell</emphasis>
88    # <emphasis role="bold">fs checkvolumes</emphasis>
89 </programlisting>
90         </listitem>
91
92         <listitem>
93           <para>Download the latest stable OpenAFS source distribution
94           (openafs-src.<replaceable>X.Y.Z</replaceable>.tar.gz)
95           from <ulink url="http://www.openafs.org/release/latest.html">openafs.org</ulink>
96           to the local <emphasis role="bold">/tmp</emphasis> directory.
97           <indexterm>
98               <primary>downloading</primary>
99
100               <secondary>source files from openafs.org</secondary>
101             </indexterm>
102             </para>
103         </listitem>
104
105         <listitem>
106           <para>In the local <emphasis role="bold">/tmp</emphasis> directory, unpack the source archive. <programlisting>
107    # <emphasis role="bold">cd /tmp</emphasis>
108    # <emphasis role="bold">gzip -dc openafs-src-<replaceable>X.Y.Z</replaceable>.tar.gz | tar xvf -</emphasis>
109 </programlisting>
110           <indexterm>
111               <primary>unpacking</primary>
112
113               <secondary>source files from the archive</secondary>
114             </indexterm>
115             </para>
116         </listitem>
117
118         <listitem>
119           <para>Copy the source files from the unpacked archive into the newly created volume. <programlisting>
120    # <emphasis role="bold">cd /tmp/openafs-<replaceable>X.Y.Z</replaceable></emphasis>
121    # <emphasis role="bold">cp -rp  *  /afs/.</emphasis><replaceable>cellname</replaceable>/<emphasis role="bold">afs/src</emphasis>
122 </programlisting></para>
123         </listitem>
124       </orderedlist></para>
125
126     <indexterm>
127       <primary>source (AFS)</primary>
128
129       <secondary>compiling</secondary>
130     </indexterm>
131
132     <indexterm>
133       <primary>compiling AFS from source</primary>
134     </indexterm>
135
136     <indexterm>
137       <primary>building</primary>
138
139       <secondary>AFS from source</secondary>
140     </indexterm>
141   </sect1>
142
143   <sect1 id="HDRWQ165">
144     <title>Compiling OpenAFS Binaries Using Configure and Make</title>
145
146     <para>The OpenAFS distribution uses the <emphasis role="bold">autoconf</emphasis> program and Makefiles for compiling the OpenAFS software.<orderedlist>
147         <listitem>
148           <para>Create a subdirectory under the <emphasis role="bold">/afs/.</emphasis><replaceable>cellname</replaceable><emphasis
149           role="bold">/afs</emphasis> directory for each system type for which you will build AFS binaries. Creating and mounting a
150           volume for each system type is recommended, but you can also simply use the <emphasis role="bold">mkdir</emphasis>
151           command. If you create a new volume, grant it an unlimited quota to avoid running out of space during the build process.
152           <programlisting>
153    # <emphasis role="bold">cd /afs/.</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/afs</emphasis>    
154 </programlisting></para>
155
156           <para>If creating a new volume:</para>
157
158           <programlisting>
159    # <emphasis role="bold">vos create</emphasis> &lt;<replaceable>machine name</replaceable>&gt; &lt;<replaceable>partition name</replaceable>&gt; <replaceable>sysname</replaceable> <emphasis
160               role="bold">-maxquota 0</emphasis>
161    # <emphasis role="bold">fs mkmount</emphasis> <replaceable>sysname</replaceable> <replaceable>sysname</replaceable>    
162 </programlisting>
163
164           <para>If not creating a new volume:</para>
165
166           <programlisting>
167    # <emphasis role="bold">mkdir</emphasis> <replaceable>sysname</replaceable>
168 </programlisting>
169         </listitem>
170
171         <listitem>
172           <para>In the directory for each system type, create subdirectories called <emphasis role="bold">dest</emphasis>, <emphasis
173           role="bold">dest/bin</emphasis>, and <emphasis role="bold">obj</emphasis>. If you plan to use the
174           <emphasis>@sys</emphasis> variable in pathnames that refer to these directories, then you must use the conventional system
175           names listed in the <emphasis>OpenAFS Release Notes</emphasis>. <programlisting>
176    # <emphasis role="bold">cd</emphasis> <replaceable>sysname</replaceable>
177    # <emphasis role="bold">mkdir dest</emphasis> 
178    # <emphasis role="bold">mkdir dest/bin</emphasis> 
179    # <emphasis role="bold">mkdir obj</emphasis>
180 </programlisting></para>
181         </listitem>
182
183         <listitem>
184           <para>Create the indicated directories and symbolic links in the <emphasis
185           role="bold">/afs/.</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/afs</emphasis> directory.
186           <programlisting>
187    # <emphasis role="bold">cd /afs/.</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/afs</emphasis>
188    # <emphasis role="bold">ln -s  @sys/dest  dest</emphasis>
189    # <emphasis role="bold">ln -s  @sys/obj  obj</emphasis>
190    # <emphasis role="bold">ln -s  .  PARENT</emphasis>
191    # <emphasis role="bold">ln -s  src/Makefile  Makefile</emphasis>   
192 </programlisting></para>
193
194           <para>The following is an example directory listing for the <emphasis
195           role="bold">/afs/.</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/afs</emphasis> directory after
196           completing the preceding steps. It includes two example system types.</para>
197
198           <programlisting>
199    lrwxr-xr-x admin   12 Jun 18 11:26 Makefile-&gt;src/Makefile
200    lrwxr-xr-x admin    1 Jun 18 11:26 PARENT -&gt; .
201    lrwxr-xr-x admin    9 Jun 18 11:25 dest -&gt; @sys/dest
202    lrwxr-xr-x admin    8 Jun 18 11:25 obj -&gt; @sys/obj
203    drwxrwxrwx admin 4096 Jun 18 11:24 rcs
204    drwxrwxrwx admin 2048 Jun 18 11:27 rs_aix42
205    drwxrwxrwx admin 2048 Jun 18 11:10 src
206    drwxrwxrwx admin 2048 Jun 18 11:27 sun4x_56
207 </programlisting>
208         </listitem>
209
210         <listitem>
211           <para><emphasis role="bold">(Optional)</emphasis> By default, the build procedure writes its results into a destination
212           directory for each system type called <emphasis role="bold">/afs/.</emphasis><replaceable>cellname</replaceable><emphasis
213           role="bold">/afs/</emphasis><replaceable>sysname</replaceable><emphasis role="bold">/dest</emphasis>. To write the results
214           to a different destination directory, create a link from the <emphasis role="bold">dest</emphasis> directory to it.
215           <programlisting>
216    # <emphasis role="bold">cd /afs/.</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/afs/</emphasis><replaceable>sysname</replaceable>
217    # <emphasis role="bold">ln -s</emphasis> <replaceable>full_path_of_alternate_directory</replaceable> <emphasis role="bold">dest</emphasis>
218 </programlisting> <indexterm>
219               <primary>commands</primary>
220
221               <secondary></secondary>
222             </indexterm></para>
223         </listitem>
224 <!--
225     % cd /afs/.rampaginggeek.com/src/afs/@sys
226     % ../src/configure
227     make
228     make dest
229     -->
230         
231         <listitem>
232           <para>For each system type you plan to build, run the following commands on a machine of that system type:</para>
233           <programlisting>
234    # <emphasis role="bold">cd  /afs/</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/</emphasis><replaceable>sysname</replaceable>
235    # <emphasis role="bold">../src/configure</emphasis>
236    # <emphasis role="bold">make</emphasis>
237    # <emphasis role="bold">make dest</emphasis>
238 </programlisting>
239
240           <indexterm>
241             <primary>commands</primary>
242
243             <secondary>make</secondary>
244           </indexterm>
245
246           <indexterm>
247             <primary>configure command</primary>
248           </indexterm>
249
250           <indexterm>
251             <primary>make command</primary>
252           </indexterm>
253
254           <indexterm>
255             <primary>commands</primary>
256
257             <secondary>configure</secondary>
258           </indexterm>
259
260         </listitem>
261
262         <listitem id="LIWQ166">
263           <para>Working in the <emphasis
264           role="bold">/afs/.</emphasis><replaceable>cellname</replaceable><emphasis role="bold">/afs</emphasis> directory on a
265           machine of the system type for which you are building AFS, issue the <emphasis role="bold">make install</emphasis>
266           command.</para>
267         </listitem>
268       </orderedlist></para>
269   </sect1>
270 </appendix>