edk2/trunk/www/step-by-step-instructions.html:
[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   Work in progress...
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   Work in progress...
97 </h3>
98
99 <p class="build-step-details">
100   These instructions for Ubuntu 8.04 are currently under construction.&nbsp;
101   Please do not try to use them until this notice is removed!
102 </p>
103
104 <h3 class="build-step-title">
105   Getting started &amp; Instructions for the instructions
106 </h3>
107
108 <p class="build-step-details">
109   These instructions will be written as a series of commands executed from
110   a command terminal.&nbsp;
111   To open the command terminal application, open the "Applications" menu,
112   then open the "Accessories" sub-menu, and then select the "Terminal"
113   application.
114 </p>
115
116 <p class="build-step-details">
117   Often these instructions will contain a command which needs to be
118   executed in the terminal window.&nbsp; For example:
119 </p>
120
121 <pre class="build-step-code">
122 bash:~$ <b>echo this bold text is a sample command</b>
123 </pre>
124
125 <p class="build-step-details">
126   To execute this command, highlight the <b>bold</b> text of the 
127   command in your web browser.&nbsp;
128   After the text is highlighted, you can paste the text into the terminal
129   window with the middle mouse button.&nbsp;
130 </p>
131 <p class="build-step-details">
132   There may be other ways to copy and paste the text into the terminal.&nbsp;
133   For example, you can usually press 'Ctrl-C' within your web browser to copy
134   the text, and within the gnome-terminal program you can then press
135   'Ctrl-<b>Shift</b>-V' to paste the text.&nbsp;
136   After pasting the command into the shell, you may need to press the
137   enter or return key to execute the command.&nbsp;
138   If all else fails, you can type the command by hand.
139 </p>
140
141 <p class="build-step-details">
142   Some commands are very long, and we use the backslash character (\) to
143   tell the shell program that the line is not finished.&nbsp; For example:
144 </p>
145
146 <pre class="build-step-code">
147 bash:~$ <b>echo this bold text is a sample command \
148           which is broken into two lines</b>
149 </pre>
150
151 <p class="build-step-details">
152   When you copy and paste, make sure you include all lines of the command.&nbsp;
153   If you are typing the command, you can remove the backslash character (\)
154   and combine the lines into a single line if you prefer.
155 </p>
156
157 <p class="build-step-details">
158   If a command starts with the 'sudo' command, then you may be prompted for
159   your user password.&nbsp;
160   This will be the same password as you used to login to the system.
161 </p>
162
163 <p class="build-step-details">
164   For the purposes of this set of instructions, we will be using the following
165   paths.&nbsp;
166 </p>
167
168 <table class="build-step-details">
169   <tr>
170     <td>
171       <a href="https://edk2.tianocore.org">Edk2</a> source tree:
172     </td>
173     <td>
174       <b>~/src/edk2</b>
175     </td>
176   </tr>
177   <tr>
178     <td>
179       <a href="https://buildtools.tianocore.org">Buildtools</a> source tree:
180     </td>
181     <td>
182       <b>~/src/buildtools</b>
183     </td>
184   </tr>
185   <tr>
186     <td>
187       gcc x64 cross-compiler installation:
188     </td>
189     <td>
190       <b>~/programs/gcc/x64</b>
191     </td>
192   </tr>
193 </table>
194
195 <p class="build-step-details">
196   You will need to change the commands if you want to use different
197   locations, but this is not recommended unless you are sure that you
198   know what you are doing.
199 </p>
200
201 <h3 class="build-step-title">
202   Install tools from apt
203 </h3>
204
205 <p class="build-step-details">
206   Several ubuntu packages will be needed to fully set up an edk2 build
207   environment.&nbsp;
208   In order to easily install all the requirements, you need to run
209   this command.
210 </p>
211
212 <pre class="build-step-code">
213 bash:~$ <b>sudo apt-get install build-essentials uuid-dev \
214           python-setuptools texinfo bison flex libgmp3-dev \
215           libmpfr-dev</b>
216 </pre>
217
218 <h3 class="build-step-title">
219   Install python antlr module
220 </h3>
221
222 <p class="build-step-details">
223   In order to install the python antlr module, we use the 'easy_install'
224   command.&nbsp;
225   The following command is the latest version right now, but if
226   you encounter difficulties, you may want to confirm the version at
227   <a href="http://www.antlr.org/download/Python">http://www.antlr.org/download/Python</a>.
228 </p>
229
230 <pre class="build-step-code">
231 bash:~$ <b>sudo easy_install \
232   http://www.antlr.org/download/Python/antlr_python_runtime-3.0.1-py2.5.egg</b>
233 </pre>
234
235 <h3 class="build-step-title">
236   Get and build the edk2 BaseTools
237 </h3>
238
239 <p class="build-step-details">
240   We will now check out the BaseTools source code using subversion.&nbsp;
241   (If you are behind a web proxy, then you may need to configure your proxy
242   in the ~/.subversion/servers file.)&nbsp;
243 </p>
244
245 <pre class="build-step-code">
246 bash:~$ <b>mkdir ~/src</b>
247 bash:~$ <b>cd ~/src</b>
248 bash:~$ <b>svn co \
249   https://buildtools.tianocore.org/svn/buildtools/trunk/BaseTools</b>
250 bash:~$ <b>make -C BaseTools</b>
251 </pre>
252
253 <h3 class="build-step-title">
254   Build <a href="http://gcc.gnu.org">gcc</a> x64 UEFI cross compiler
255 </h3>
256
257 <p class="build-step-details">
258   In order to build UEFI images for x64, you will need to build a
259   cross-compiler build of gcc.&nbsp;
260   This can take quite a while to complete, possibly several hours on
261   older systems.&nbsp;
262   But, a Python script has been provided to automate this build process.&nbsp;
263   Please note that if your network is behind a firewall, you may need to
264   set the http_proxy environment variable:
265 </p>
266
267 <pre class="build-step-code">
268 Note: This is only needed if behind a internet firewall!
269 bash:~$ <b>export http_proxy=proxy.domain.com:proxy_port</b>
270 </pre>
271
272 <p class="build-step-details">
273   To build gcc for x64, use these commands (this will take quite a while
274   to complete):
275 </p>
276
277 <pre class="build-step-code">
278 bash:~$ <b>cd ~/src/BaseTools/gcc</b>
279 bash:~$ <b>./mingw-gcc-build.py --arch=x64 --prefix=~/programs/gcc/x64</b>
280 </pre>
281
282 <h3 class="build-step-title">
283   Get the edk2 source tree
284 </h3>
285
286 <pre class="build-step-code">
287 bash:~$ <b>cd ~/src</b>
288 bash:~$ <b>svn co https://edk2.tianocore.org/svn/edk2/trunk/edk2</b>
289 </pre>
290
291 <h3 class="build-step-title">
292   Setup build shell environment
293 </h3>
294
295 <pre class="build-step-code">
296 bash:~$ <b>cd ~/src/edk2</b>
297 bash:~$ <b>export EDK_TOOLS_PATH=~/src/BaseTools</b>
298 bash:~$ <b>. edksetup.sh BaseTools</b>
299 </pre>
300
301 <h3 class="build-step-title">
302   Modify Conf files
303 </h3>
304
305 <p class="build-step-details">
306   You will need to edit the Conf/tools_def.txt and Conf/target.txt files.&nbsp;
307 </p>
308
309 <p class="build-step-details">
310   For the <i>Conf/tools_def.txt</i> file, find the following lines:
311 </p>
312
313 <pre class="build-step-code">
314 *_UNIXGCC_X64_CC_PATH               = DEF(UNIXGCC_X64_PETOOLS_PREFIX)/gcc
315 *_UNIXGCC_X64_SLINK_PATH            = DEF(UNIXGCC_X64_PETOOLS_PREFIX)/ar
316 *_UNIXGCC_X64_DLINK_PATH            = DEF(UNIXGCC_X64_PETOOLS_PREFIX)/ld
317 *_UNIXGCC_X64_ASM_PATH              = DEF(UNIXGCC_X64_PETOOLS_PREFIX)/gcc
318 *_UNIXGCC_X64_PP_PATH               = DEF(UNIXGCC_X64_PETOOLS_PREFIX)/gcc
319 *_UNIXGCC_X64_VFRPP_PATH            = DEF(UNIXGCC_X64_PETOOLS_PREFIX)/gcc
320 </pre>
321
322 <p class="build-step-details">
323   And change the cooresponding lines to match these:
324 </p>
325
326 <pre class="build-step-code">
327 *_UNIXGCC_X64_CC_PATH               = ENV(HOME)/programs/gcc/x64/bin/x86_64-pc-mingw32-gcc
328 *_UNIXGCC_X64_SLINK_PATH            = ENV(HOME)/programs/gcc/x64/bin/x86_64-pc-mingw32-ar
329 *_UNIXGCC_X64_DLINK_PATH            = ENV(HOME)/programs/gcc/x64/bin/x86_64-pc-mingw32-ld
330 *_UNIXGCC_X64_ASM_PATH              = ENV(HOME)/programs/gcc/x64/bin/x86_64-pc-mingw32-gcc
331 *_UNIXGCC_X64_PP_PATH               = ENV(HOME)/programs/gcc/x64/bin/x86_64-pc-mingw32-gcc
332 *_UNIXGCC_X64_VFRPP_PATH            = ENV(HOME)/programs/gcc/x64/bin/x86_64-pc-mingw32-gcc
333 </pre>
334
335 <p class="build-step-details">
336   For the <i>Conf/target.txt</i> file, find the following lines:
337 </p>
338
339 <pre class="build-step-code">
340 ACTIVE_PLATFORM       = Nt32Pkg/Nt32Pkg.dsc
341 TARGET_ARCH           = IA32
342 TOOL_CHAIN_TAG        = MYTOOLS
343 </pre>
344
345 <p class="build-step-details">
346   And change the cooresponding lines to match these:
347 </p>
348
349 <pre class="build-step-code">
350 ACTIVE_PLATFORM       = MdeModulePkg/MdeModulePkg.dsc
351 TARGET_ARCH           = X64
352 TOOL_CHAIN_TAG        = UNIXGCC
353 </pre>
354
355 <h3 class="build-step-title">
356   Build Hello World!&nbsp; (and the rest of MdeModulePkg)
357 </h3>
358
359 <p class="build-step-details">
360   Now you should be able to simply run the 'build' command to compile
361   the MdeModulePkg.
362 </p>
363
364 <pre class="build-step-code">
365 bash:~$ <b>build</b>
366 </pre>
367
368 <p class="build-step-details">
369   As a tangible result of the build, you should have the HelloWorld UEFI
370   X64 application.&nbsp;
371   If you have a X64 UEFI system available to you, you ought to be able to
372   run this application under the shell.
373 </p>
374
375 <pre class="build-step-code">
376 bash:~$ <b>ls Build/MdeModule/DEBUG_UNIXGCC/X64/HelloWorld.efi</b>
377 </pre>
378