www/*:
[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-weight: bold;
23     margin-top: 0.19in;
24     margin-bottom: 0.19in
25   }
26   
27   .build-step-details {
28   }
29
30   .monospace, .build-step-code {
31     font-family: "courier new", "courier", "monospace";
32   }
33
34   .build-step-code {
35     border: 1px dashed;
36     margin-right: 0.25in;
37     padding: 2pt 4pt 2pt 4pt;
38     background-color: #F0F0F0;
39   }
40   
41   .build-step-details, .build-step-code, .build-step-title {
42     font-size: 12pt;
43     margin-left: 0.25in;
44   }
45   
46   table.build-step-details td {
47     border-style: hidden;
48   }
49   
50   img.in-text {
51     vertical-align: top;
52   }
53   -->
54 </style>
55
56 <h2 class="main-title">
57   Step-by-step (walk-throughs) for building with edk2
58 </h2>
59
60 <p class="main-details">
61   This page contains some step-by-step guides in an attempt to give
62   a highly detailed description of how to set up building on an edk2
63   system.&nbsp;
64   A few different operating systems are targeted.&nbsp;
65   It is hoped that these examples can either provide exact steps for
66   setting up an edk2 build environment.&nbsp;
67   If instructions are not available for your exact system configuration,
68   you may still be able to <i>tweak</i> the instructions to work on your
69   system.
70 </p>
71
72 <!--
73  #
74  # Getting started for unix-like systems
75  #
76 -->
77 <h2 class="main-title">
78   Getting started for UNIX-like operating systems
79 </h2>
80
81 <p class="build-step-details">
82   These instructions will be written as a series of commands executed from
83   a command terminal.
84 </p>
85
86 <p class="build-step-details">
87   Often these instructions will contain a command which needs to be
88   executed in the terminal window.&nbsp; For example:
89 </p>
90
91 <pre class="build-step-code">
92 bash$ <b>echo this bold text is a sample command</b>
93 </pre>
94
95 <p class="build-step-details">
96   To execute this command, highlight the
97   <font class="monospace"><b>bold</b></font>
98   text of the 
99   command in your web browser.&nbsp;
100   Most web browsers should be able to copy the text by selecting <i>Copy</i>
101   under the <i>Edit</i> menu.&nbsp;
102   Now, change back to the terminal application, and there should be a
103   <i>Paste</i> operation under the <i>Edit</i> menu.&nbsp;
104   After pasting the command into the shell, you may need to press the
105   <i>enter</i> or <i>return</i> key to execute the command.&nbsp;
106 </p>
107 <p class="build-step-details">
108   Of course, there may be other ways to copy and paste the command into
109   the terminal which are specific to the windowing environment and
110   applications that you are using.&nbsp;
111   If all else fails, however, you can type the command by hand.
112 </p>
113
114 <p class="build-step-details">
115   Some commands are very long, and we use the backslash character (\) to
116   tell the shell program that the command is not finished.&nbsp; For example:
117 </p>
118
119 <pre class="build-step-code">
120 bash$ <b>echo this bold text is a sample command \
121         which is broken into two lines</b>
122 </pre>
123
124 <p class="build-step-details">
125   When you copy and paste, make sure you include all lines of the command
126   (including the backslash (\) characters).&nbsp;
127   If you are typing the command, you can remove the backslash character (\)
128   and combine the lines into a single line if you prefer.
129 </p>
130
131 <p class="build-step-details">
132   If a command starts with the <font class="monospace"><b>sudo</b></font>
133   command, then you may be prompted for your user password.&nbsp;
134   This will be the same password as you used to login to the system.
135 </p>
136
137 <p class="build-step-details">
138   For the purposes of this set of instructions, we will be using the following
139   paths.&nbsp;
140 </p>
141
142 <table class="build-step-details">
143   <tr>
144     <td>
145       <a href="https://edk2.tianocore.org">Edk2</a> source tree:
146     </td>
147     <td>
148       <font class="monospace"><b>~/src/edk2</b></font>
149     </td>
150   </tr>
151   <tr>
152     <td>
153       <a href="https://buildtools.tianocore.org">Buildtools</a> source tree:
154     </td>
155     <td>
156       <font class="monospace"><b>~/src/buildtools</b></font>
157     </td>
158   </tr>
159   <tr>
160     <td>
161       gcc x64 cross-compiler installation:
162     </td>
163     <td>
164       <font class="monospace"><b>~/programs/gcc/x64</b></font>
165     </td>
166   </tr>
167 </table>
168
169 <p class="build-step-details">
170   You will need to change the commands if you want to use different
171   locations, but this is not recommended unless you are sure that you
172   know what you are doing.
173 </p>
174
175 <h2 class="main-title">
176   Internet proxies
177 </h2>
178
179 <p class="build-step-details">
180   If your network utilizes a firewall with a web proxy, then you may
181   need to configure your proxy information for various command line
182   applications to work.&nbsp;
183   You may need to consult with your network administrator to find
184   out the computer name and port to use for proxy setup.&nbsp;
185   The following commands are common examples of how you would configure
186   your proxy by setting an environment variable:
187 </p>
188
189 <pre class="build-step-code">
190 bash$ <b>export http_proxy=http://proxy.domain.com:proxy_port</b>
191 bash$ <b>export ftp_proxy=$http_proxy</b>
192 </pre>
193
194 <p class="build-step-details">
195   To utilize the subversion source control command behind an internet
196   firewall with a web proxy, you should configure the
197   <font class="monospace">~/.subversion/servers</font> file.
198 </p>
199
200 <h2 class="main-title">
201   Instructions for various UNIX-like systems
202 </h2>
203
204 <font size="2">
205   <ul>
206     <li><a href="#RHEL4">Red Hat Enterprise Linux 4 Desktop</a></li>
207     <li><a href="#MacOSX10.5">Mac OS X 10.5</a> (Leopard)</li>
208     <li><a href="#SLED10">SuSE Linux Enterprise 10 Desktop</a></li>
209     <li><a href="#Ubuntu8.04">Ubuntu 8.04</a></li>
210   </ul>
211 </font>
212
213 <!--
214  #
215  # Red Hat Enterprise Linux 4 Desktop
216  #
217 -->
218 <h2 class="main-title">
219   <a name="RHEL4"></a>
220   Red Hat Enterprise Linux 4 Desktop
221 </h2>
222
223 <h3 class="build-step-title">
224   Coming soon...
225 </h3>
226
227 <!--
228  #
229  # MAC OS X 10.5
230  #
231 -->
232 <h2 class="main-title">
233   <a name="MacOSX10.5"></a>
234   Mac OS X 10.5
235 </h2>
236
237 <h3 class="build-step-title">
238   Work in progress...
239 </h3>
240
241 <p class="build-step-details">
242   These instructions for OS X 10.5 are currently under construction.&nbsp;
243   Please do not try to use them until this notice is removed!
244 </p>
245
246 <h3 class="build-step-title">
247   Xcode Tools
248 </h3>
249
250 <p class="build-step-details">
251   The first step is to install the Apple Xcode
252   development environment:<br>
253   &nbsp;&nbsp;<a href="http://developer.apple.com/tools/xcode">http://developer.apple.com/tools/xcode</a>
254 </p>
255
256 <p class="build-step-details">
257   To install Xcode, you must register as an Apple developer, and
258   download the Xcode installation disk image (which is fairly large).&nbsp;
259   These instructions were verified with Xcode 3.0.&nbsp;
260   Within the Xcode Tools disk image, only the
261   <font class="monospace">Xcode&nbsp;Tools.mpkg</font> package
262   needs to be installed.
263 </p>
264
265 <h3 class="build-step-title">
266   Open OS X Terminal program
267 </h3>
268
269 <p class="build-step-details">
270   Past this point, the remaining instructions will utilize OS X's built in
271   command shell (bash) via the <i>Terminal</i> application.&nbsp;
272   To open the command terminal application, open <i>Finder</i>, then press the
273   <img src="apple-command-key.gif" class="in-text" alt="Cmd" title="Command/Apple key" />-Shift-U
274   key combination.&nbsp;
275   (This opens the <i>Applications</i> => <i>Utilities</i> folder.)&nbsp;
276   In the <i>Utilities</i> folder, you should see the <i>Terminal</i>
277   application.
278 </p>
279
280
281 <h3 class="build-step-title">
282   GMP &amp; MPFR (if behind a web proxy)
283 </h3>
284
285 <p class="build-step-details">
286   The <a href="http://gmplib.org/">gmp</a> and
287   <a href="http://www.mpfr.org/">mpfr</a> libraries are needed to build
288   the gcc cross compiler at a later point in these instructions.&nbsp;
289   Building these libraries on OS X can present some difficulties, so
290   if you are not behind a network firewall, then consider using the
291   macports project to install these libraries. (see below)&nbsp;
292   Be sure to set the http_proxy and ftp_proxy environment variables
293   before using the 'curl' commands below.
294 </p>
295
296 <pre class="build-step-code">
297 bash$ <b>mkdir ~/src</b>
298 bash$ <b>cd ~/src</b>
299 bash$ <b>curl --remote-name \
300   ftp://ftp.gnu.org/gnu/gmp/gmp-4.2.2.tar.bz2</b>
301 bash$ <b>tar jxvf gmp-4.2.2.tar.bz2</b>
302 bash$ <b>cd gmp-4.2.2</b>
303 bash$ <b>./configure --prefix=/usr</b>
304 bash$ <b>make</b>
305 bash$ <b>make check</b>
306 bash$ <b>sudo make install</b>
307
308 Note: This might be needed for 64-bit machines if
309       the MPFR configure fails below.
310 bash$ <b>export CFLAGS="-m64"</b>
311
312 bash$ <b>cd ~/src</b>
313 bash$ <b>curl --remote-name \
314   http://www.mpfr.org/mpfr-current/mpfr-2.3.1.tar.bz2</b>
315 bash$ <b>tar jxvf mpfr-2.3.1.tar.bz2</b>
316 bash$ <b>cd mpfr-2.3.1</b>
317 bash$ <b>./configure --prefix=/usr</b>
318 bash$ <b>make</b>
319 bash$ <b>make check</b>
320 bash$ <b>sudo make install</b>
321 </pre>
322
323
324 <h3 class="build-step-title">
325   GMP &amp; MPFR via Macports (if not behind web proxy)
326 </h3>
327
328 <p class="build-step-details">
329   If you are not behind a network firewall, then the
330   <a href="http://www.macports.org/">http://www.macports.org</a>
331   project can greatly simlify the installation of gmp &amp; mpfr.&nbsp;
332   (Macports does not work easily with web proxies at this time.)
333   After installing macports you should be able to simply run this
334   command at the shell prompt.
335 </p>
336
337 <pre class="build-step-code">
338 bash$ <b>sudo port install gmp mpfr</b>
339 </pre>
340
341 <h3 class="build-step-title">
342   Continue with common instructions
343 </h3>
344
345 <p class="build-step-details">
346   The remaining instructions are
347   <a href="#UnixCommon">common for most UNIX-like systems</a>.
348 </p>
349
350 <!--
351  #
352  # SuSE Linux Enterprise 10 Desktop
353  #
354 -->
355 <h2 class="main-title">
356   <a name="SLED10"></a>
357   SuSE Linux Enterprise 10 Desktop
358 </h2>
359
360 <h3 class="build-step-title">
361   Coming soon...
362 </h3>
363
364
365 <!--
366  #
367  # Ubuntu 8.04
368  #
369 -->
370 <h2 class="main-title">
371   <a name="Ubuntu8.04"></a>
372   Ubuntu 8.04
373 </h2>
374
375 <h3 class="build-step-title">
376   Please note
377 </h3>
378
379 <p class="build-step-details">
380   The Ubuntu platform is not officially supported or tested by the
381   <a href="index.html">edk2</a>
382   project at this time.
383 </p>
384
385 <h3 class="build-step-title">
386   Open the <a href="http://www.gnome.org">GNOME<a> Terminal program
387 </h3>
388
389 <p class="build-step-details">
390   These instructions will utilize Ubuntu's built in
391   command shell (bash) via the <i>GNOME Terminal</i> application.&nbsp;
392   To open the <i>Terminal</i> application, locate it under the
393   <i>Applications</i> menu and the <i>Accessories</i> sub-menu.
394 </p>
395
396 <h3 class="build-step-title">
397   Install required software from apt
398 </h3>
399
400 <p class="build-step-details">
401   Several ubuntu packages will be needed to fully set up an edk2 build
402   environment.&nbsp;
403   In order to easily install all the requirements, you need to run
404   this command.
405 </p>
406
407 <pre class="build-step-code">
408 bash$ <b>sudo apt-get install build-essential uuid-dev \
409         python-setuptools texinfo bison flex libgmp3-dev \
410         libmpfr-dev subversion</b>
411 </pre>
412
413 <h3 class="build-step-title">
414   Continue with common instructions
415 </h3>
416
417 <p class="build-step-details">
418   The remaining instructions are
419   <a href="#UnixCommon">common for most UNIX-like systems</a>.
420 </p>
421
422 <!--
423  #
424  # Common instruction unix-like systems
425  #
426 -->
427 <h2 class="main-title">
428   <a name="UnixCommon"></a>
429   Common instructions for UNIX-like systems
430 </h2>
431
432 <p class="build-step-details">
433   A significant portion of the steps are common on the various UNIX-like
434   platforms.&nbsp;
435   You should start with the instructions for the operating system that
436   most closely matches your platform, and it will direct you here at the
437   appropriate time.
438 </p>
439
440 <h3 class="build-step-title">
441   Install python antlr module
442 </h3>
443
444 <p class="build-step-details">
445   In order to install the python antlr module, we use the 'easy_install'
446   command.&nbsp;
447   The following command is the latest version right now, but if
448   you encounter difficulties, you may want to confirm the version at
449   <a href="http://www.antlr.org/download/Python">http://www.antlr.org/download/Python</a>.&nbsp;
450   Be sure to set the http_proxy and ftp_proxy environment variables
451   if you are behind a network firewall.
452 </p>
453
454 <pre class="build-step-code">
455 bash$ <b>sudo easy_install \
456   http://www.antlr.org/download/Python/antlr_python_runtime-3.0.1-py2.5.egg</b>
457 </pre>
458
459 <h3 class="build-step-title">
460   Get and build the edk2 BaseTools
461 </h3>
462
463 <p class="build-step-details">
464   We will now check out the BaseTools source code using subversion.&nbsp;
465   (If you are behind a web proxy, then you may need to configure your proxy
466   in the ~/.subversion/servers file.)&nbsp;
467   We will tell subversion to use the 'guest' username on tianocore.org.&nbsp;
468   The password for the 'guest' account is blank/empty.
469 </p>
470
471 <pre class="build-step-code">
472 bash$ <b>mkdir ~/src</b>
473 bash$ <b>cd ~/src</b>
474 bash$ <b>svn co \
475   https://buildtools.tianocore.org/svn/buildtools/trunk/BaseTools \
476   --username guest</b>
477 bash$ <b>make -C BaseTools</b>
478 </pre>
479
480 <h3 class="build-step-title">
481   Build <a href="http://gcc.gnu.org">gcc</a> x64 UEFI cross compiler
482 </h3>
483
484 <p class="build-step-details">
485   In order to build UEFI images for x64, you will need to build a
486   cross-compiler build of gcc.&nbsp;
487   This can take quite a while to complete, possibly several hours on
488   older systems.&nbsp;
489   But, a Python script has been provided to automate this build process.
490 </p>
491
492 <pre class="build-step-code">
493 Note: This is only needed if behind a internet firewall!
494 bash$ <b>export http_proxy=http://proxy.domain.com:proxy_port</b>
495 </pre>
496
497 <p class="build-step-details">
498   To build gcc for x64, use these commands (this will take quite a while
499   to complete):
500 </p>
501
502 <pre class="build-step-code">
503 bash$ <b>cd ~/src/BaseTools/gcc</b>
504 bash$ <b>./mingw-gcc-build.py --arch=x64 \
505   --prefix=~/programs/gcc/x64</b>
506 </pre>
507
508 <h3 class="build-step-title">
509   Get the edk2 source tree
510 </h3>
511
512 <pre class="build-step-code">
513 bash$ <b>cd ~/src</b>
514 bash$ <b>svn co \
515   https://edk2.tianocore.org/svn/edk2/trunk/edk2 \
516   --username guest</b>
517 </pre>
518
519 <h3 class="build-step-title">
520   Setup build shell environment
521 </h3>
522
523 <pre class="build-step-code">
524 bash$ <b>cd ~/src/edk2</b>
525 bash$ <b>export EDK_TOOLS_PATH=~/src/BaseTools</b>
526 bash$ <b>. edksetup.sh BaseTools</b>
527 </pre>
528
529 <h3 class="build-step-title">
530   Modify Conf files
531 </h3>
532
533 <p class="build-step-details">
534   You will need to edit the Conf/tools_def.txt and Conf/target.txt files.&nbsp;
535 </p>
536
537 <p class="build-step-details">
538   For the <i>Conf/tools_def.txt</i> file, find the following lines:
539 </p>
540
541 <pre class="build-step-code">
542 *_UNIXGCC_X64_CC_PATH               = DEF(UNIXGCC_X64_PETOOLS_PREFIX)/gcc
543 *_UNIXGCC_X64_SLINK_PATH            = DEF(UNIXGCC_X64_PETOOLS_PREFIX)/ar
544 *_UNIXGCC_X64_DLINK_PATH            = DEF(UNIXGCC_X64_PETOOLS_PREFIX)/ld
545 *_UNIXGCC_X64_ASM_PATH              = DEF(UNIXGCC_X64_PETOOLS_PREFIX)/gcc
546 *_UNIXGCC_X64_PP_PATH               = DEF(UNIXGCC_X64_PETOOLS_PREFIX)/gcc
547 *_UNIXGCC_X64_VFRPP_PATH            = DEF(UNIXGCC_X64_PETOOLS_PREFIX)/gcc
548 </pre>
549
550 <p class="build-step-details">
551   And change the cooresponding lines to match these:
552 </p>
553
554 <pre class="build-step-code">
555 *_UNIXGCC_X64_CC_PATH               = ENV(HOME)/programs/gcc/x64/bin/x86_64-pc-mingw32-gcc
556 *_UNIXGCC_X64_SLINK_PATH            = ENV(HOME)/programs/gcc/x64/bin/x86_64-pc-mingw32-ar
557 *_UNIXGCC_X64_DLINK_PATH            = ENV(HOME)/programs/gcc/x64/bin/x86_64-pc-mingw32-ld
558 *_UNIXGCC_X64_ASM_PATH              = ENV(HOME)/programs/gcc/x64/bin/x86_64-pc-mingw32-gcc
559 *_UNIXGCC_X64_PP_PATH               = ENV(HOME)/programs/gcc/x64/bin/x86_64-pc-mingw32-gcc
560 *_UNIXGCC_X64_VFRPP_PATH            = ENV(HOME)/programs/gcc/x64/bin/x86_64-pc-mingw32-gcc
561 </pre>
562
563 <p class="build-step-details">
564   For the <i>Conf/target.txt</i> file, find the following lines:
565 </p>
566
567 <pre class="build-step-code">
568 ACTIVE_PLATFORM       = Nt32Pkg/Nt32Pkg.dsc
569 TARGET_ARCH           = IA32
570 TOOL_CHAIN_TAG        = MYTOOLS
571 </pre>
572
573 <p class="build-step-details">
574   And change the cooresponding lines to match these:
575 </p>
576
577 <pre class="build-step-code">
578 ACTIVE_PLATFORM       = MdeModulePkg/MdeModulePkg.dsc
579 TARGET_ARCH           = X64
580 TOOL_CHAIN_TAG        = UNIXGCC
581 </pre>
582
583 <h3 class="build-step-title">
584   Build Hello World!&nbsp; (and the rest of MdeModulePkg)
585 </h3>
586
587 <p class="build-step-details">
588   Now you should be able to simply run the <i>build</i> command to compile
589   the MdeModulePkg.
590 </p>
591
592 <pre class="build-step-code">
593 bash$ <b>build</b>
594 </pre>
595
596 <p class="build-step-details">
597   As a tangible result of the build, you should have the HelloWorld UEFI
598   X64 application.&nbsp;
599   If you have a X64 UEFI system available to you, then this application
600   should be able to run successfully under the shell.
601 </p>
602
603 <pre class="build-step-code">
604 bash$ <b>ls Build/MdeModule/DEBUG_UNIXGCC/X64/HelloWorld.efi</b>
605 </pre>
606