1 <!-- Copyright (C) 2003 Red Hat, Inc. -->
2 <!-- This material may be distributed only subject to the terms -->
3 <!-- and conditions set forth in the Open Publication License, v1.0 -->
4 <!-- or later (the latest version is presently available at -->
5 <!-- http://www.opencontent.org/openpub/). -->
6 <!-- Distribution of the work or derivative of the work in any -->
7 <!-- standard (paper) book form is prohibited unless prior -->
8 <!-- permission is obtained from the copyright holder. -->
13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
19 TITLE="The eCos Component Writer's Guide"
20 HREF="cdl-guide.html"><LINK
22 TITLE="The Build Process"
23 HREF="build.html"><LINK
25 TITLE="Configuration Header File Generation"
26 HREF="build.headers.html"><LINK
28 TITLE="Building Test Cases"
29 HREF="build.tests.html"></HEAD
40 SUMMARY="Header navigation table"
52 > Component Writer's Guide</TH
60 HREF="build.headers.html"
68 >Chapter 4. The Build Process</TD
74 HREF="build.tests.html"
88 NAME="BUILD.MAKE">Building eCos</H1
90 >The primary goal of an eCos build is to produce the library
98 generate a number of other targets: <TT
105 >, and a linker script. Some
106 packages may cause additional libraries or targets to be generated.
107 The basic build process involves a number of different phases with
108 corresponding priorities. There are a number of predefined priorities:</P
110 CLASS="INFORMALTABLE"
142 >Export header files</TD
172 > custom build steps</TD
184 >Generate libraries</TD
199 > custom build steps</TD
207 >Generation of the <TT
210 > file, the startup code
211 and the linker script actually happens via <SPAN
214 > custom build steps,
215 typically defined in appropriate HAL packages. The component framework
216 has no special knowledge of these targets.</P
218 >By default custom build steps for a <SPAN
222 during the same phase as most compilations, but this can be changed
226 > option. Similarly custom build
230 > property happen at the end of a build, but this can
231 also be changed with a <TT
235 example a priority of 50 can be used to run a custom build step
236 between the header file export phase and the main compilation phase.
237 Custom build steps are discussed in more detail below.</P
239 >Some build systems may run several commands of the same priority in
240 parallel. For example files listed in <SPAN
244 compiled in parallel, concurrently with <SPAN
248 steps with default priorities. Since most of the time for an <SPAN
252 build involves processing <SPAN
255 > properties, this allows builds to
256 be speeded up on suitable host hardware. All build steps for a given
257 phase will complete before the next phase is started.</P
263 NAME="BUILD.MAKE.UPDATE">Updating the Build Tree</H2
265 >Some build systems may involve a phase before the header files get
266 exported, to update the build and install trees automatically when
267 there has been a change to the configuration savefile
271 >. This is useful mainly for application
272 developers using the command line tools: it would allow users to
273 create the build tree only once, and after any subsequent
274 configuration changes the tree would be updated automatically by the
275 build system. The facility would be analogous to the
278 >--enable-maintainer-mode</TT
279 > option provide by the
286 > programs. At present no <SPAN
290 build system implements this functionality, but it is likely to be
291 added in a future release.</P
298 NAME="BUILD.MAKE.EXPORT">Exporting Public Header Files</H2
300 >The first compulsory phase involves making sure that there is an up to
301 date set of header files in the install tree. Each package can contain
302 some number of header files defining the exported interface.
303 Applications should only use exported functionality. A package can
304 also contain some number of private header files which are only of
305 interest to the implementation, and which should not be visible to
306 application code. The various packages that go into a particular
307 configuration can be spread all over the component repository. In
308 theory it might be possible to make all the exported header files
309 accessible by having a lengthy <TT
313 search path, but this would be inconvenient both for building eCos and
314 for building applications. Instead all the relevant header files are
315 copied to a single location, the <TT
318 > subdirectory of the install tree.
319 The process involves the following:</P
326 >The install tree, for example <TT
328 >/usr/local/ecos/install</TT
334 >/usr/local/ecos/install/include</TT
336 created when the build tree is generated or updated. At the same time
337 configuration header files will be written to the <TT
340 > subdirectory, for example
343 >/usr/local/ecos/include/pkgconf</TT
345 the configuration data is visible to all the packages and to
346 application code that may wish to examine some of the configuration
351 >Each package in the configuration is examined for exported header
352 files. The exact order in which the packages are processed is not
353 defined, but should not matter.</P
360 >If the package has an <A
361 HREF="ref.include-files.html"
367 lists all the exported header files:</P
375 CLASS="PROGRAMLISTING"
376 >cdl_package <some_package> {
378 include_files header1.h header2.h
384 >If no arguments are given then the package does not export any header
393 CLASS="PROGRAMLISTING"
394 >cdl_package <some_package> {
402 >The listed files may be in an <TT
405 > subdirectory within the package's
406 hierarchy, or they may be relative to the package's toplevel
410 > property is intended mainly for very
411 simple packages. It can also be useful when converting existing code
415 > package, to avoid rearranging the sources.</P
419 >If there is no <SPAN
422 > property then the component framework
427 subdirectory in the package, as per the layout conventions. All files,
428 including those in subdirectories, will be treated as exported header
429 files. For example, the math library package contains files <TT
434 >include/sys/ieeefp.h</TT
435 >, both of which will
436 be exported to the install tree.</P
440 >As a last resort, if there is neither an <SPAN
448 component framework will search the package's toplevel directory and
449 all of its subdirectories for files with one of the following
464 will be interpreted as exported header files.</P
466 >This last resort rule could cause confusion for packages which have no
467 exported header files but which do contain one or more private header
468 files. For example a typical device driver simply implements an
469 existing interface rather than define a new one, so it does not need
470 to export a header file. However it may still have one or more private
471 header files. Such packages should use an <SPAN
475 with no arguments.</P
481 >If the package has one or more exported header files, the next step is
482 to determine where the files should end up. By default all exported
483 header files will just end up relative to the install tree's <TT
486 > subdirectory. For example the
493 >/usr/local/ecos/include/math.h</TT
502 >/usr/local/ecos/include/sys/ieeefp.h</TT
504 behaviour is correct for packages like the C library where the
505 interface is defined by appropriate standards. For other packages this
506 behaviour can lead to file name clashes, and the <A
507 HREF="ref.include-dir.html"
512 > property should be used
521 CLASS="PROGRAMLISTING"
522 >cdl_package CYGPKG_KERNEL {
523 include_dir cyg/kernel
529 >This means that the kernel's exported header file
533 > should be copied to
536 >/usr/local/ecos/include/cyg/kernel/kapi.h</TT
538 it is very unlikely to clash with a header file from some other
543 >For typical application developers there will be little or no need for
544 the installed header files to change after the first build. Changes
545 will be necessary only if packages are added to or removed from the
546 configuration. For component writers, the build system should detect
547 changes to the master copy of the header file source code and update
548 the installed copies automatically during the next build. The build
549 system is expected to perform a header file dependency analysis, so
550 any source files affected should get rebuilt as well.</P
554 >Some build systems may provide additional support for application
555 developers who want to make minor changes to a package, especially for
556 debugging purposes. A header file could be copied from the
557 component repository (which for application developers is assumed to
558 be a read-only resource) into the build tree and edited there. The
559 build system would detect a more recent version of such a header file
560 in the build tree and install it. Care would have to be taken to
561 recover properly if the modified copy in the build tree is
562 subsequently removed, in order to revert to the original behaviour.</P
566 >When updating the install tree's <TT
569 > subdirectory, the build tree may
570 also perform a clean-up operation. Specifically, it may check for any
571 files which do not correspond to known exported header files and
582 >At present there is no defined support in the build system for
583 defining custom build steps that generate exported header files. Any
584 attempt to use the existing custom build step support may fall foul of
585 unexpected header files being deleted automatically by the build
586 system. This limitation will be addressed in a future release of the
587 component framework, and may require changing the priority for
588 exporting header files so that a custom build step can happen first.</P
597 NAME="BUILD.MAKE.COMPILES">Compiling</H2
599 >Once there are up to date copies of all the exported header files in
600 the build tree, the main build can proceed. Most of this involves
601 compiling source files listed in <SPAN
604 > properties in the <SPAN
608 scripts for the various packages, for example:</P
616 CLASS="PROGRAMLISTING"
617 >cdl_package CYGPKG_ERROR {
618 display "Common error code support"
629 > properties may appear in the body of a <TT
646 > entity is active and enabled, the property takes effect.
647 If the option is inactive or disabled the property is ignored. It is
651 > property to list multiple source files, and
652 it is also possible for a given <SPAN
655 > entity to contain multiple
659 > properties. The following three examples are equivalent:</P
667 CLASS="PROGRAMLISTING"
668 >cdl_option <some_option> {
670 compile file1.c file2.c file3.c
673 cdl_option <some_option> {
680 cdl_option <some_option> {
682 compile file1.c file2.c
689 >Packages that follow the directory layout conventions should have a
694 component framework will first look for the specified files there.
695 Failing that it will look for the specified files relative to the
696 package's root directory. For example if a package contains a source
700 > then the following two lines
709 CLASS="PROGRAMLISTING"
710 > compile strerror.cxx
711 compile src/strerror.cxx</PRE
716 >In the first case the component framework will find the file
717 immediately in the packages <TT
721 subdirectory. In the second case the framework will first look for a
724 >src/src/strerror.cxx</TT
728 >str/strerror.cxx</TT
729 > relative to the package's root
730 directory. The result is the same.</P
732 >The file names may be relative paths, allowing the source code to be
733 split over multiple directories. For example if a package contains a
736 >src/sync/mutex.cxx</TT
737 > then the corresponding
749 CLASS="PROGRAMLISTING"
750 > compile sync/mutex.cxx</PRE
755 >All the source files relevant to the current configuration will be
756 identified when the build tree is generated or updated, and added to
757 the appropriate makefile (or its equivalent for other build systems).
758 The actual build will involve a rule of the form:</P
766 CLASS="PROGRAMLISTING"
767 ><object file> : <source file>
768 $(CC) -c $(INCLUDE_PATH) $(CFLAGS) -o $@ $<</PRE
773 >The component framework has built-in knowledge for processing source
774 files written in C, C++ or assembler. These should have a
785 > suffix respectively. The current implementation
786 has no simple mechanism for extending this with support for other
787 languages or for alternative suffixes, but this should be addressed in
790 >The compiler command that will be used is something like
794 >. This consists of a command prefix, in
798 >, and a specific command such as
802 >. The command prefix will depend on the target
803 architecture and is controlled by a configuration option in the
804 appropriate HAL package. It will have a sensible default value for the
805 current architecture, but users can modify this option when necessary.
806 The command prefix cannot be changed on a per-package basis, since
807 it is usually essential that all packages are built with a consistent
813 > header file search path
814 consists of at least the following:</P
825 install tree. This allows source files to access the various header
826 files exported by all the packages in the configuration, and also the
827 configuration header files.</P
831 >The current package's root directory. This ensures that all files in
832 the package are accessible at build time.</P
836 >The current package's <TT
840 subdirectory, if it is present. Generally all files to be compiled are
841 located in or below this directory. Typically this is used to access
842 private header files containing implementation details only.</P
846 >The compiler flags <TT
849 > are determined in two
850 steps. First the appropriate HAL package will provide a configuration
851 option defining the global flags. Typically this includes flags that
852 are needed for the target processor, for example
856 >, various flags related to warnings,
857 debugging and optimization, and flags such as
861 > which are needed by <SPAN
865 Users can modify the global flags option as required. In addition it
866 is possible for existing flags to be removed from and new flags to be
867 added to the current set on a per-package basis, again by means of
868 user-modifiable configuration options. More details are given below.</P
870 >Component writers can assume that the build system will perform full
871 header file dependency analysis, including dependencies on
872 configuration headers, but the exact means by which this happens is
873 implementation-defined. Typical application developers are unlikely to
874 modify exported or private header files, but configuration headers are
875 likely to change as the configuration is changed to better meet the
876 needs of the application. Full header file dependency analysis also
877 makes things easier for the component writers themselves.</P
879 >The current directory used during a compilation is an implementation
880 detail of the build system. However it can be assumed that each
881 package will have its own directory somewhere in the build tree, to
882 prevent file name clashes, that this will be the current directory,
883 and that intermediate object files will end up here.</P
890 NAME="BUILD.MAKE.LIBRARIES">Generating the Libraries</H2
898 > properties have been
899 processed and the required object files have been built or rebuilt,
900 these can be collected together in one or more libraries. The archiver
905 corresponding to the current architecture, for example <SPAN
907 >powerpc-eabi-ar</SPAN
908 >. By default al of the
909 object files will end up in a single library
913 >. This can be changed on a per-package
915 HREF="ref.library.html"
921 in the body of the corresponding <TT
924 > command, for example:</P
932 CLASS="PROGRAMLISTING"
933 >cdl_package <SOME_PACKAGE> {
935 library libSomePackage.a
941 >However using different libraries for each package should be avoided.
942 It makes things more difficult for application developers since they
943 now have to link the application code with more libraries, and
944 possibly even change this set of libraries when packages are added to
945 or removed from the configuration. The use of a single library
949 > avoids any complications.</P
951 >It is also possible to change the target library for individual files,
955 > option with the corresponding
962 > property. For example:</P
970 CLASS="PROGRAMLISTING"
971 > compile -library=libSomePackage.a hello.c
972 make_object -library=libSomePackage.a {
979 >Again this should be avoided because it makes application development
980 more difficult. There is one special library which can be used freely,
984 >, which is used to generate the
988 > file as described below.</P
990 >The order in which object files end up in a library is not defined.
991 Typically each library will be created directly in the install tree,
992 since there is little point in generating a file in the build tree and
993 then immediately copying it to the install tree.</P
1000 NAME="BUILD.EXTRAS">The <TT
1005 >Package sources files normally get compiled and then added to a
1006 library, by default <TT
1010 linked with the application code. Because of the usual rules for
1011 linking with libraries, augmented by the use of link-time garbage
1012 collection, this means that code will only end up in the final
1013 executable if there is a direct or indirect reference to it in the
1014 application. Usually this is the desired behaviour: if the application
1015 does not make any use of say kernel message boxes, directly or
1016 indirectly, then that code should not end up in the final executable
1017 taking up valuable memory space.</P
1019 >In a few cases it is desirable for package code to end up in the final
1020 executable even if there are no direct or indirect references. For
1021 example, device driver functions are often not called directly.
1022 Instead the application will access the device via the string
1026 > and call the device functions
1027 indirectly. This will be impossible if the functions have been
1028 removed at link-time.</P
1030 >Another example involves static C++ objects. It is possible to have a
1031 static C++ object, preferably with a suitable constructor priority,
1032 where all of the interesting work happens as a side effect of running
1033 the constructor. For example a package might include a monitoring
1034 thread or a garbage collection thread created from inside such a
1035 constructor. Without a reference by the application to the static
1036 object the latter will never get linked in, and the package will not
1037 function as expected.</P
1039 >A third example would be copyright messages. A package vendor may want
1040 to insist that all products shipped using that package include a
1041 particular message in memory, even though many users of that package
1042 will object to such a restriction.</P
1044 >To meet requirements such as these the build system provides support
1048 >, which always gets linked
1049 with the application code via the linker script. Because it is an
1050 object file rather than a library everything in the file will be
1054 > file is generated at the
1055 end of a build from a library <TT
1059 packages can put functions and variables in suitable source files and
1060 add them to that library explicitly:</P
1068 CLASS="PROGRAMLISTING"
1069 > compile -library=libextras.a xyzzy.c
1070 compile xyzzy_support.c</PRE
1075 >In this example <TT
1086 > and in the final executable.
1089 >xyzzy_support.o</TT
1094 > as usual, and is subject to linker
1095 garbage collection.</P
1102 NAME="BUILD.FLAGS">Compilers and Flags</H2
1122 >Some of the details of compiler selection and compiler flags described
1123 below are subject to change in future revisions of the component
1124 framework, although every reasonable attempt will be made to avoid
1125 breaking backwards compatibility.</P
1131 >The build system needs to know what compiler to use, what compiler
1132 flags should be used for different stages of the build and so on. Much
1133 of this information will vary from target to target, although users
1134 should be able to override this when appropriate. There may also be a
1135 need for some packages to modify the compiler flags. All platform HAL
1136 packages should define a number of options with well-known names,
1137 along the following lines (any existing platform HAL package can be
1138 consulted for a complete example):</P
1146 CLASS="PROGRAMLISTING"
1147 >cdl_component CYGBLD_GLOBAL_OPTIONS {
1152 cdl_option CYGBLD_GLOBAL_COMMAND_PREFIX {
1154 default_value { "arm-elf" }
1157 cdl_option CYGBLD_GLOBAL_CFLAGS {
1159 default_value "-Wall -g -O2 …"
1163 cdl_option CYGBLD_GLOBAL_LDFLAGS {
1165 default_value "-g -nostdlib -Wl,--gc-sections …"
1175 >CYGBLD_GLOBAL_OPTIONS</TT
1176 > component serves to
1177 collect together all global build-related options. It has the flavor
1181 > since disabling all of these options would
1182 make it impossible to build anything and hence is not useful. It is
1183 parented immediately below the root of the configuration hierarchy,
1184 thus making sure that it is readily accessible in the graphical
1185 configuration tool and, for command line users, in the
1197 >Currently the <SPAN
1200 > property lists a parent of
1204 >, rather than an empty string. This
1205 could be unfortunate if there was ever a package with that name. The
1206 issue will be addressed in a future release of the component
1213 >CYGBLD_GLOBAL_COMMAND_PREFIX</TT
1215 which tools should be used for the current target. Typically this is
1216 determined by the processor on the target hardware. In some cases a
1217 given target board may be able to support several different
1218 processors, in which case the <SPAN
1220 >default_value</SPAN
1221 > expression could select
1222 a different toolchain depending on some other option that is used to
1223 control which particular processor.
1226 >CYGBLD_GLOBAL_COMMAND_PREFIX</TT
1227 > is modifiable rather
1228 than calculated, so users can override this when necessary.</P
1230 >Given a command prefix such as <TT
1234 source files will be compiled with <TT
1238 C++ sources will be built using <TT
1245 > will be used to generate the
1246 library. This is in accordance with the usual naming conventions for
1247 GNU cross-compilers and similar tools. For the purposes of custom
1248 build steps, tokens such as <TT
1257 >The next option, <TT
1259 >CYGBLD_GLOBAL_CFLAGS</TT
1261 provide the initial value of <TT
1265 compiler flags such as <TT
1272 > are likely to be used on all targets. Other
1277 target-specific. Again this is a modifiable option, so the user can
1285 desired. The option <TT
1287 >CYGBLD_GLOBAL_LDFLAGS</TT
1289 the same purpose for <TT
1292 > and linking. It is
1293 used primarily when building test cases or possibly for some custom
1294 build steps, since building eCos itself generally involves building
1295 one or more libraries rather than executables.</P
1297 >Some packages may wish to add certain flags to the global set, or
1298 possibly remove some flags. This can be achieved by having
1299 appropriately named options in the package, for example:</P
1307 CLASS="PROGRAMLISTING"
1308 >cdl_component CYGPKG_KERNEL_OPTIONS {
1309 display "Kernel build options"
1313 cdl_option CYGPKG_KERNEL_CFLAGS_ADD {
1314 display "Additional compiler flags"
1316 default_value { "" }
1320 cdl_option CYGPKG_KERNEL_CFLAGS_REMOVE {
1321 display "Suppressed compiler flags"
1323 default_value { "" }
1327 cdl_option CYGPKG_KERNEL_LDFLAGS_ADD {
1328 display "Additional linker flags"
1330 default_value { "" }
1334 cdl_option CYGPKG_KERNEL_LDFLAGS_REMOVE {
1335 display "Suppressed linker flags"
1337 default_value { "" }
1345 >In this example the kernel does not modify the global compiler flags
1346 by default, but it is possible for the users to modify the options if
1347 desired. The value of <TT
1351 the compilations and custom build steps in a given package is
1352 determined as follows:</P
1359 >Start with the global settings from
1362 >CYGBLD_GLOBAL_CFLAGS</TT
1371 >Remove any flags specified in the per-package
1375 > option, if any. For example
1379 > should be removed for this package then
1383 > would now have a value of just
1391 >Then concatenate the flags specified by the per-package
1395 > option, if any. For example if
1399 > should be added for the current package then
1400 the final value of <TT
1414 > is determined in much the same way.</P
1422 >The way compiler flags are handled at present has numerous limitations
1423 that need to be addressed in a future release, although it should
1424 suffice for nearly all cases. For the time being custom build steps
1425 and in particular the <SPAN
1428 > property can be used to work
1429 around the limitations.</P
1431 >Amongst the issues, there is a specific problem with package
1432 encapsulation. For example the math library imposes some stringent
1433 requirements on the compiler in order to guarantee exact IEEE
1434 behavior, and may need special flags on a per-architecture basis. One
1435 way of handling this is to have
1438 >CYGPKG_LIBM_CFLAGS_ADD</TT
1442 >CYGPKG_LIBM_CFLAGS_REMOVE</TT
1445 >default_value</SPAN
1447 expressions which depend on the target architecture, but such
1448 expressions may have to updated for each new architecture. An
1449 alternative approach would allow the architectural HAL package to
1452 >default_value</SPAN
1453 > expressions for the math library, but this
1454 breaks encapsulation. A third approach would allow some architectural
1455 HAL packages to define one or more special options with well-known
1456 names, and the math library could check if these options were defined
1457 and adjust the default values appropriately. Other packages with
1458 floating point requirements could do the same. This approach also has
1459 scalability issues, in particular how many such categories of options
1460 would be needed? It is not yet clear how best to resolve such issues.</P
1470 >When generating a build tree it would be desirable for the component
1471 framework to output details of the tools and compiler flags in a
1472 format that can be re-used for application builds, for example a
1473 makefile fragment. This would make it easier for application
1474 developers to use the same set of flags as were used for building eCos
1475 itself, thus avoiding some potential problems with incompatible
1485 NAME="BUILD.CUSTOM">Custom Build Steps</H2
1505 >Some of the details of custom build steps as described below are
1506 subject to change in future revisions of the component framework,
1507 although every reasonable attempt will be made to avoid breaking
1508 backwards compatibility.</P
1514 >For most packages simply listing one or more source files in a
1518 > property is sufficient. These files will get built using the
1519 appropriate compiler and compiler flags and added to a library, which
1520 then gets linked with application code. A package that can be built in
1521 this way is likely to be more portable to different targets and build
1522 environments, since it avoids build-time dependencies. However some
1523 packages have special needs, and the component framework supports
1524 custom build steps to allow for these needs. There are two properties
1525 related to this, <SPAN
1531 >, and both take the following
1540 CLASS="PROGRAMLISTING"
1542 <target_filepath> : <dependency_filepath> …
1550 >Although this may look like makefile syntax, and although some build
1551 environments will indeed involve generating makefiles and running
1556 guaranteed. It is possible for the component framework to be
1557 integrated with some other build system, and custom build steps should
1558 be written with that possibility in mind. Each custom build step
1559 involves a target, some number of dependency files, and some number of
1560 commands. If the target is not up to date with respect to one or more
1561 of the dependencies then the commands need to be executed.</P
1568 >Only one target can be specified. For a <SPAN
1572 target must be an object file. For a <SPAN
1575 > property it can be any
1576 file. In both cases it must refer to a physical file, the use of
1577 phony targets is not supported. The target should not be an absolute
1578 path name. If the generated file needs to end up in the install tree
1579 then this can be achieved using a <TT
1583 token, for example:</P
1591 CLASS="PROGRAMLISTING"
1593 <PREFIX>/lib/mytarget : …
1600 >When the build tree is generated and the custom build step is added to
1601 the makefile (or whatever build system is used)
1605 > will be replaced with the absolute
1606 path to the install tree. </P
1610 >All the dependencies must also refer to physical files, not to phony
1611 targets. These files may be in the source tree. The
1614 ><PACKAGE></TT
1615 > token can be used to indicate this:
1616 when the build tree is generated this token will be replaced with the
1617 absolute path to the package's root directory in the component
1618 repository, for example:</P
1626 CLASS="PROGRAMLISTING"
1628 xyzzy.o : <PACKAGE>/src/xyzzy.c
1634 >If the component repository was installed in <TT
1636 >/usr/local/ecos</TT
1637 > and this custom build
1638 step existed in version 1_5 of the kernel,
1641 ><PACKAGE></TT
1642 > would be replaced with
1645 >/usr/local/ecos/packages/kernel/v1_5</TT
1648 >Alternatively the dependencies may refer to files that are generated
1649 during the build. These may be object files resulting from <SPAN
1653 properties or other <SPAN
1656 > properties, or they may be other
1657 files resulting from a <SPAN
1660 > property, for example:</P
1668 CLASS="PROGRAMLISTING"
1680 >No other token or makefile variables may be used in the target or
1681 dependency file names. Also conditionals such as
1685 > and similar makefile functionality must not
1691 Similarly the list of commands must not use any makefile conditionals
1692 or similar functionality. A number of tokens can be used to provide
1693 access to target-specific or environmental data. Note that these
1694 tokens look like makefile variables, unlike the
1701 ><PACKAGE></TT
1702 > tokens mentioned earlier:</P
1704 CLASS="INFORMALTABLE"
1739 >the GNU archiver</TD
1745 >mips-tx39-elf-ar</TT
1759 >the GNU compiler</TD
1794 >$(COMMAND_PREFIX)</TT
1799 >the triplet prefix</TD
1814 >$(INCLUDE_PATH></TT
1819 >header file search path</TD
1845 >-nostdlib -Wl,-static</TT
1859 >the objcopy utility</TD
1865 >arm-elf-objcopy</TT
1879 >location of the install tree</TD
1885 >/home/fred/ecos-install</TT
1899 >location of the component repository</TD
1905 >/home/fred/ecos/packages</TT
1914 >In addition commands in a custom build step may refer to the target
1915 and the dependencies using <TT
1929 >, all of which behave as per GNU make syntax. The
1930 commands will execute in a suitable directory in the build tree.</P
1934 >The current directory used during a custom build step is an
1935 implementation detail of the build system. However it can be assumed
1936 that each package will have its own directory somewhere in the build
1937 tree, to prevent file name clashes, and that this will be the current
1938 directory. In addition any object files generated as a result of
1942 > properties will be located here as well, which is useful for
1943 custom build steps that depend on a <TT
1947 previously generated.</P
1949 >Any temporary files created by a custom build step should be generated
1950 in the build tree (in or under the current directory). Such files
1951 should be given a <TT
1954 > file extension to ensure
1955 that they are deleted during a <TT
1957 >make clean</TT
1959 equivalent operation.</P
1961 >If a package contains multiple custom build steps with the same
1962 priority, it is possible that these build steps will be run
1963 concurrently. Therefore these custom build steps must not accidentally
1964 use the same file names for intermediate files.</P
1968 >Care has to be taken to make sure that the commands in a custom build
1969 step will run on all host platforms, including Windows NT as well as
1970 Linux and other Unix systems. For example, all file paths should use
1971 forward slashes as the directory separator. It can be assumed that
1972 Windows users will have a full set of CygWin tools installed and
1973 available on the path. The <A
1974 HREF="http://www.gnu.org/prep/standards.html"
1978 > provide some useful guidelines for writing portable
1983 >A custom build step must not make any assumptions concerning the
1984 version of another package. This enforces package encapsulation,
1985 preventing one package from accessing the internals of another.</P
1989 >No assumptions should be made about the target platform, unless the
1990 package is inherently specific to that platform. Even then it is
1991 better to use the various tokens whenever possible, rather than
1992 hard-coding in details such as the compiler. For example, given a
1993 custom build step such as:</P
2001 CLASS="PROGRAMLISTING"
2002 > arm-elf-gcc -c -mcpu=arm7di -o $@ $<</PRE
2007 >Even if this build step will only be invoked on ARM targets, it could
2008 cause problems. For example the toolchain may have been installed
2009 using a prefix other than <TT
2013 user changes the compiler flags then this would not be reflected in
2014 the build step. The correct way to write this rule would be:</P
2022 CLASS="PROGRAMLISTING"
2023 > $(CC) -c $(CFLAGS) -o $@ $<</PRE
2028 >Some commands such as the compiler, the archiver, and objcopy are
2029 required sufficiently often to warrant their own tokens, for example
2037 target-specific commands are needed only rarely and the
2040 >$(COMMAND_PREFIX)</TT
2041 > token can be used to construct
2042 the appropriate command name, for example:</P
2050 CLASS="PROGRAMLISTING"
2051 > $(COMMAND_PREFIX)size $< > $@</PRE
2058 >Custom build steps should not be used to build host-side executables,
2059 even if those executables are needed to build parts of the target side
2060 code. Support for building host-side executables will be added in a
2061 future version of the component framework, although it will not
2062 necessarily involve these custom build steps.</P
2066 >By default custom build steps defined in a <SPAN
2070 have a priority of 100, which means that they will be executed
2071 in the same phase as compilations resulting from a <SPAN
2075 It is possible to change the priority using a property option, for
2084 CLASS="PROGRAMLISTING"
2085 > make_object -priority 50 {
2092 >Specifying a priority smaller than a 100 means that the custom build
2093 step happens before the normal compilations. Priorities between 100
2094 and 200 happen after normal compilations but before the libraries are
2095 archived together. <SPAN
2098 > properties should not specify a
2099 priority of 200 or later. </P
2101 >Custom build steps defined in a <SPAN
2104 > property have a default
2105 priority of 300, and so they will happen after the libraries have been
2106 built. Again this can be changed using a <TT
2117 NAME="BUILD.STARTUP">Startup Code</H2
2119 >Linking an application requires the application code, a linker script,
2120 the eCos library or libraries, the <TT
2124 and some startup code. Depending on the target hardware and how the
2125 application gets booted, this startup code may do little more than
2129 >, or it may have to perform a
2130 considerable amount of hardware initialization. The startup code
2131 generally lives in a file <TT
2135 created by a custom build step in a HAL package. As far as application
2136 developers are concered the existence of this file is largely
2137 transparent, since the linker script ensures that the file is part of
2138 the final executable.</P
2140 >This startup code is not generally of interest to component writers,
2141 only to HAL developers who are referred to one of the existing HAL
2142 packages for specific details. Other packages are not expected to
2143 modify the startup in any way. If a package needs some work performed
2144 early on during system initialization, before the application's main
2145 entry point gets invoked, this can be achieved using a static object
2146 with a suitable constructor priority.</P
2154 >It is possible that the <TT
2158 conjunction with appropriate linker script directives, could be used
2159 to eliminate the need for a special startup file. The details are not
2169 NAME="BUILD.LINKERSCRIPT">The Linker Script</H2
2189 >This section is not finished, and the details are subject to change in
2190 a future release. Arguably linker script issues should be documented
2191 in the HAL documentation rather than in this guide.</P
2197 >Generating the linker script is the responsibility of the various HAL
2198 packages that are applicable to a given target. Developers of
2199 components other than HAL packages need not be concerned about what is
2200 involved. Developers of new HAL packages should use an existing HAL as
2209 >It may be desirable for some packages to have some control over the
2210 linker script, for example to add extra alignment details for a
2211 particular section. This can be risky because it can result in subtle
2212 portability problems, and the current component framework has no
2213 support for any such operations. The issue may be addressed in a
2224 SUMMARY="Footer navigation table"
2235 HREF="build.headers.html"
2244 HREF="cdl-guide.html"
2253 HREF="build.tests.html"
2263 >Configuration Header File Generation</TD
2277 >Building Test Cases</TD
projects / karo-tx-redboot.git / blob