Modify Ubuntu 8.04 instructions based on testing of the 'step-by-step'
[people/mcb30/edk2.git] / www / step-by-step-instructions.html
1 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
2
3 <style type="text/css">
4   <!--
5   .main-title, .main-details {
6     font-size: 11pt;
7   }
8   
9   .main-details {
10     margin-top: 0.19in;
11     margin-bottom: 0.19in
12   }
13   
14   .main-title {
15     font-weight: bold;
16     margin-top: 0in;
17     margin-bottom: 0.08in;
18     border-bottom: thin solid black;
19   }
20   
21   .build-step-title {
22     font-size: 11pt;
23     font-weight: bold;
24     margin-top: 0.19in;
25     margin-bottom: 0.19in
26   }
27   
28   .build-step-details {
29   }
30   
31   .build-step-code {
32     font-family: "courier new", "courier", "monospace";
33     border: 1px dashed;
34     margin-right: 0.25in;
35     padding: 2pt 4pt 2pt 4pt;
36     background-color: #F0F0F0;
37   }
38   
39   .build-step-details, .build-step-code, .build-step-title {
40     margin-left: 0.25in;
41   }
42   
43   table.build-step-details td {
44     border-style: hidden;
45   }
46   -->
47 </style>
48
49 <h2 class="main-title">
50   Step-by-step (walk-throughs) for building with edk2
51 </h2>
52
53 <p class="main-details">
54   <font size="2">
55     This page contains some step-by-step guides in an attempt to give
56     a highly detailed description of how to set up building on an edk2
57     system.&nbsp;
58     A few different operating systems are targeted.&nbsp;
59     It is hoped that these examples can either provide exact steps for
60     setting up an edk2 build environment.&nbsp;
61     If instructions are not available for your exact system configuration,
62     you may still be able to 'tweak' the instructions to work on your
63     system.
64   </font>
65 </p>
66
67 <font size="2">
68   <ul>
69     <li><a href="#MacOSX10.5">Mac OS X 10.5</a> (Leopard)</li>
70     <li><a href="#Ubuntu8.04">Ubuntu 8.04</a></li>
71   </ul>
72 </font>
73
74 <h2 class="main-title">
75   <a name="MacOSX10.5"></a>
76   Mac OS X 10.5
77 </h2>
78
79 <h3 class="build-step-title">
80   Coming soon...
81 </h3>
82
83 <!--
84 <p class="build-step-details">
85   These instructions for OS X 10.5 are currently under construction.&nbsp;
86   Please do not try to use them until this notice is removed!
87 </p>
88 -->
89
90 <h2 class="main-title">
91   <a name="Ubuntu8.04"></a>
92   Ubuntu 8.04
93 </h2>
94
95 <h3 class="build-step-title">
96   Getting started &amp; Instructions for the instructions
97 </h3>
98
99 <p class="build-step-details">
100   These instructions will be written as a series of commands executed from
101   a command terminal.&nbsp;
102   To open the command terminal application, open the "Applications" menu,
103   then open the "Accessories" sub-menu, and then select the "Terminal"
104   application.
105 </p>
106
107 <p class="build-step-details">
108   Often these instructions will contain a command which needs to be
109   executed in the terminal window.&nbsp; For example:
110 </p>
111
112 <pre class="build-step-code">
113 bash:~$ <b>echo this bold text is a sample command</b>
114 </pre>
115
116 <p class="build-step-details">
117   To execute this command, highlight the <b>bold</b> text of the 
118   command in your web browser.&nbsp;
119   After the text is highlighted, you can paste the text into the terminal
120   window with the middle mouse button.&nbsp;
121 </p>
122 <p class="build-step-details">
123   There may be other ways to copy and paste the text into the terminal.&nbsp;
124   For example, you can usually press 'Ctrl-C' within your web browser to copy
125   the text, and within the gnome-terminal program you can then press
126   'Ctrl-<b>Shift</b>-V' to paste the text.&nbsp;
127   After pasting the command into the shell, you may need to press the
128   enter or return key to execute the command.&nbsp;
129   If all else fails, you can type the command by hand.
130 </p>
131
132 <p class="build-step-details">
133   Some commands are very long, and we use the backslash character (\) to
134   tell the shell program that the command is not finished.&nbsp; For example:
135 </p>
136
137 <pre class="build-step-code">
138 bash:~$ <b>echo this bold text is a sample command \
139           which is broken into two lines</b>
140 </pre>
141
142 <p class="build-step-details">
143   When you copy and paste, make sure you include all lines of the command
144   (including the backslash (\) characters).&nbsp;
145   If you are typing the command, you can remove the backslash character (\)
146   and combine the lines into a single line if you prefer.
147 </p>
148
149 <p class="build-step-details">
150   If a command starts with the 'sudo' command, then you may be prompted for
151   your user password.&nbsp;
152   This will be the same password as you used to login to the system.
153 </p>
154
155 <p class="build-step-details">
156   For the purposes of this set of instructions, we will be using the following
157   paths.&nbsp;
158 </p>
159
160 <table class="build-step-details">
161   <tr>
162     <td>
163       <a href="https://edk2.tianocore.org">Edk2</a> source tree:
164     </td>
165     <td>
166       <b>~/src/edk2</b>
167     </td>
168   </tr>
169   <tr>
170     <td>
171       <a href="https://buildtools.tianocore.org">Buildtools</a> source tree:
172     </td>
173     <td>
174       <b>~/src/buildtools</b>
175     </td>
176   </tr>
177   <tr>
178     <td>
179       gcc x64 cross-compiler installation:
180     </td>
181     <td>
182       <b>~/programs/gcc/x64</b>
183     </td>
184   </tr>
185 </table>
186
187 <p class="build-step-details">
188   You will need to change the commands if you want to use different
189   locations, but this is not recommended unless you are sure that you
190   know what you are doing.
191 </p>
192
193 <h3 class="build-step-title">
194   Install tools from apt
195 </h3>
196
197 <p class="build-step-details">
198   Several ubuntu packages will be needed to fully set up an edk2 build
199   environment.&nbsp;
200   In order to easily install all the requirements, you need to run
201   this command.
202 </p>
203
204 <pre class="build-step-code">
205 bash:~$ <b>sudo apt-get install build-essential uuid-dev \
206           python-setuptools texinfo bison flex libgmp3-dev \
207           libmpfr-dev subversion</b>
208 </pre>
209
210 <h3 class="build-step-title">
211   Install python antlr module
212 </h3>
213
214 <p class="build-step-details">
215   In order to install the python antlr module, we use the 'easy_install'
216   command.&nbsp;
217   The following command is the latest version right now, but if
218   you encounter difficulties, you may want to confirm the version at
219   <a href="http://www.antlr.org/download/Python">http://www.antlr.org/download/Python</a>.
220 </p>
221
222 <pre class="build-step-code">
223 bash:~$ <b>sudo easy_install \
224   http://www.antlr.org/download/Python/antlr_python_runtime-3.0.1-py2.5.egg</b>
225 </pre>
226
227 <h3 class="build-step-title">
228   Get and build the edk2 BaseTools
229 </h3>
230
231 <p class="build-step-details">
232   We will now check out the BaseTools source code using subversion.&nbsp;
233   (If you are behind a web proxy, then you may need to configure your proxy
234   in the ~/.subversion/servers file.)&nbsp;
235   We will tell subversion to use the 'guest' username on tianocore.org.&nbsp;
236   The password for the 'guest' account is blank/empty.
237 </p>
238
239 <pre class="build-step-code">
240 bash:~$ <b>mkdir ~/src</b>
241 bash:~/src$ <b>cd ~/src</b>
242 bash:~/src$ <b>svn co \
243   https://buildtools.tianocore.org/svn/buildtools/trunk/BaseTools \
244   --username guest</b>
245 bash:~/src$ <b>make -C BaseTools</b>
246 </pre>
247
248 <h3 class="build-step-title">
249   Build <a href="http://gcc.gnu.org">gcc</a> x64 UEFI cross compiler
250 </h3>
251
252 <p class="build-step-details">
253   In order to build UEFI images for x64, you will need to build a
254   cross-compiler build of gcc.&nbsp;
255   This can take quite a while to complete, possibly several hours on
256   older systems.&nbsp;
257   But, a Python script has been provided to automate this build process.&nbsp;
258   Please note that if your network is behind a firewall, you may need to
259   set the http_proxy environment variable:
260 </p>
261
262 <pre class="build-step-code">
263 Note: This is only needed if behind a internet firewall!
264 bash:~/src$ <b>export http_proxy=proxy.domain.com:proxy_port</b>
265 </pre>
266
267 <p class="build-step-details">
268   To build gcc for x64, use these commands (this will take quite a while
269   to complete):
270 </p>
271
272 <pre class="build-step-code">
273 bash:~/src$ <b>cd ~/src/BaseTools/gcc</b>
274 bash:~/src/BaseTools/gcc$ <b>./mingw-gcc-build.py --arch=x64 \
275   --prefix=~/programs/gcc/x64</b>
276 </pre>
277
278 <h3 class="build-step-title">
279   Get the edk2 source tree
280 </h3>
281
282 <pre class="build-step-code">
283 bash:~/src/BaseTools/gcc$ <b>cd ~/src</b>
284 bash:~/src$ <b>svn co \
285   https://edk2.tianocore.org/svn/edk2/trunk/edk2 \
286   --username guest</b>
287 </pre>
288
289 <h3 class="build-step-title">
290   Setup build shell environment
291 </h3>
292
293 <pre class="build-step-code">
294 bash:~/src$ <b>cd ~/src/edk2</b>
295 bash:~/src/edk2$ <b>export EDK_TOOLS_PATH=~/src/BaseTools</b>
296 bash:~/src/edk2$ <b>. edksetup.sh BaseTools</b>
297 </pre>
298
299 <h3 class="build-step-title">
300   Modify Conf files
301 </h3>
302
303 <p class="build-step-details">
304   You will need to edit the Conf/tools_def.txt and Conf/target.txt files.&nbsp;
305 </p>
306
307 <p class="build-step-details">
308   For the <i>Conf/tools_def.txt</i> file, find the following lines:
309 </p>
310
311 <pre class="build-step-code">
312 *_UNIXGCC_X64_CC_PATH               = DEF(UNIXGCC_X64_PETOOLS_PREFIX)/gcc
313 *_UNIXGCC_X64_SLINK_PATH            = DEF(UNIXGCC_X64_PETOOLS_PREFIX)/ar
314 *_UNIXGCC_X64_DLINK_PATH            = DEF(UNIXGCC_X64_PETOOLS_PREFIX)/ld
315 *_UNIXGCC_X64_ASM_PATH              = DEF(UNIXGCC_X64_PETOOLS_PREFIX)/gcc
316 *_UNIXGCC_X64_PP_PATH               = DEF(UNIXGCC_X64_PETOOLS_PREFIX)/gcc
317 *_UNIXGCC_X64_VFRPP_PATH            = DEF(UNIXGCC_X64_PETOOLS_PREFIX)/gcc
318 </pre>
319
320 <p class="build-step-details">
321   And change the cooresponding lines to match these:
322 </p>
323
324 <pre class="build-step-code">
325 *_UNIXGCC_X64_CC_PATH               = ENV(HOME)/programs/gcc/x64/bin/x86_64-pc-mingw32-gcc
326 *_UNIXGCC_X64_SLINK_PATH            = ENV(HOME)/programs/gcc/x64/bin/x86_64-pc-mingw32-ar
327 *_UNIXGCC_X64_DLINK_PATH            = ENV(HOME)/programs/gcc/x64/bin/x86_64-pc-mingw32-ld
328 *_UNIXGCC_X64_ASM_PATH              = ENV(HOME)/programs/gcc/x64/bin/x86_64-pc-mingw32-gcc
329 *_UNIXGCC_X64_PP_PATH               = ENV(HOME)/programs/gcc/x64/bin/x86_64-pc-mingw32-gcc
330 *_UNIXGCC_X64_VFRPP_PATH            = ENV(HOME)/programs/gcc/x64/bin/x86_64-pc-mingw32-gcc
331 </pre>
332
333 <p class="build-step-details">
334   For the <i>Conf/target.txt</i> file, find the following lines:
335 </p>
336
337 <pre class="build-step-code">
338 ACTIVE_PLATFORM       = Nt32Pkg/Nt32Pkg.dsc
339 TARGET_ARCH           = IA32
340 TOOL_CHAIN_TAG        = MYTOOLS
341 </pre>
342
343 <p class="build-step-details">
344   And change the cooresponding lines to match these:
345 </p>
346
347 <pre class="build-step-code">
348 ACTIVE_PLATFORM       = MdeModulePkg/MdeModulePkg.dsc
349 TARGET_ARCH           = X64
350 TOOL_CHAIN_TAG        = UNIXGCC
351 </pre>
352
353 <h3 class="build-step-title">
354   Build Hello World!&nbsp; (and the rest of MdeModulePkg)
355 </h3>
356
357 <p class="build-step-details">
358   Now you should be able to simply run the <i>build</i> command to compile
359   the MdeModulePkg.
360 </p>
361
362 <pre class="build-step-code">
363 bash:~/src/edk2$ <b>build</b>
364 </pre>
365
366 <p class="build-step-details">
367   As a tangible result of the build, you should have the HelloWorld UEFI
368   X64 application.&nbsp;
369   If you have a X64 UEFI system available to you, then this application
370   should be able to run successfully under the shell.
371 </p>
372
373 <pre class="build-step-code">
374 bash:~/src/edk2$ <b>ls Build/MdeModule/DEBUG_UNIXGCC/X64/HelloWorld.efi</b>
375 </pre>
376