OpenCores
URL https://opencores.org/ocsvn/openrisc/openrisc/trunk

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [rtos/] [ecos-2.0/] [doc/] [html/] [cdl-guide/] [build.make.html] - Blame information for rev 588

Go to most recent revision | Details | Compare with Previous | View Log

Line No. Rev Author Line
1 28 unneback
<!-- 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.               -->
9
<HTML
10
><HEAD
11
><TITLE
12
>Building eCos</TITLE
13
><meta name="MSSmartTagsPreventParsing" content="TRUE">
14
<META
15
NAME="GENERATOR"
16
CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
17
"><LINK
18
REL="HOME"
19
TITLE="The eCos Component Writer's Guide"
20
HREF="cdl-guide.html"><LINK
21
REL="UP"
22
TITLE="The Build Process"
23
HREF="build.html"><LINK
24
REL="PREVIOUS"
25
TITLE="Configuration Header File Generation"
26
HREF="build.headers.html"><LINK
27
REL="NEXT"
28
TITLE="Building Test Cases"
29
HREF="build.tests.html"></HEAD
30
><BODY
31
CLASS="SECT1"
32
BGCOLOR="#FFFFFF"
33
TEXT="#000000"
34
LINK="#0000FF"
35
VLINK="#840084"
36
ALINK="#0000FF"
37
><DIV
38
CLASS="NAVHEADER"
39
><TABLE
40
SUMMARY="Header navigation table"
41
WIDTH="100%"
42
BORDER="0"
43
CELLPADDING="0"
44
CELLSPACING="0"
45
><TR
46
><TH
47
COLSPAN="3"
48
ALIGN="center"
49
>The <SPAN
50
CLASS="APPLICATION"
51
>eCos</SPAN
52
> Component Writer's Guide</TH
53
></TR
54
><TR
55
><TD
56
WIDTH="10%"
57
ALIGN="left"
58
VALIGN="bottom"
59
><A
60
HREF="build.headers.html"
61
ACCESSKEY="P"
62
>Prev</A
63
></TD
64
><TD
65
WIDTH="80%"
66
ALIGN="center"
67
VALIGN="bottom"
68
>Chapter 4. The Build Process</TD
69
><TD
70
WIDTH="10%"
71
ALIGN="right"
72
VALIGN="bottom"
73
><A
74
HREF="build.tests.html"
75
ACCESSKEY="N"
76
>Next</A
77
></TD
78
></TR
79
></TABLE
80
><HR
81
ALIGN="LEFT"
82
WIDTH="100%"></DIV
83
><DIV
84
CLASS="SECT1"
85
><H1
86
CLASS="SECT1"
87
><A
88
NAME="BUILD.MAKE">Building eCos</H1
89
><P
90
>The primary goal of an eCos build is to produce the library
91
<TT
92
CLASS="FILENAME"
93
>libtarget.a</TT
94
>. A typical <SPAN
95
CLASS="APPLICATION"
96
>eCos</SPAN
97
> build will also
98
generate a number of other targets: <TT
99
CLASS="FILENAME"
100
>extras.o</TT
101
>,
102
startup code <TT
103
CLASS="FILENAME"
104
>vectors.o</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
109
><DIV
110
CLASS="INFORMALTABLE"
111
><A
112
NAME="AEN2457"><P
113
></P
114
><TABLE
115
BORDER="1"
116
CLASS="CALSTABLE"
117
><THEAD
118
><TR
119
><TH
120
WIDTH="50%"
121
ALIGN="RIGHT"
122
VALIGN="TOP"
123
>Priority</TH
124
><TH
125
WIDTH="50%"
126
ALIGN="LEFT"
127
VALIGN="TOP"
128
>Action</TH
129
></TR
130
></THEAD
131
><TBODY
132
><TR
133
><TD
134
WIDTH="50%"
135
ALIGN="RIGHT"
136
VALIGN="TOP"
137
>0</TD
138
><TD
139
WIDTH="50%"
140
ALIGN="LEFT"
141
VALIGN="TOP"
142
>Export header files</TD
143
></TR
144
><TR
145
><TD
146
WIDTH="50%"
147
ALIGN="RIGHT"
148
VALIGN="TOP"
149
>100</TD
150
><TD
151
WIDTH="50%"
152
ALIGN="LEFT"
153
VALIGN="TOP"
154
>Process <SPAN
155
CLASS="PROPERTY"
156
>compile</SPAN
157
> properties</TD
158
></TR
159
><TR
160
><TD
161
WIDTH="50%"
162
ALIGN="RIGHT"
163
VALIGN="TOP"
164
>&nbsp;</TD
165
><TD
166
WIDTH="50%"
167
ALIGN="LEFT"
168
VALIGN="TOP"
169
>and most <SPAN
170
CLASS="PROPERTY"
171
>make_object</SPAN
172
> custom build steps</TD
173
></TR
174
><TR
175
><TD
176
WIDTH="50%"
177
ALIGN="RIGHT"
178
VALIGN="TOP"
179
>200</TD
180
><TD
181
WIDTH="50%"
182
ALIGN="LEFT"
183
VALIGN="TOP"
184
>Generate libraries</TD
185
></TR
186
><TR
187
><TD
188
WIDTH="50%"
189
ALIGN="RIGHT"
190
VALIGN="TOP"
191
>300</TD
192
><TD
193
WIDTH="50%"
194
ALIGN="LEFT"
195
VALIGN="TOP"
196
>Process <SPAN
197
CLASS="PROPERTY"
198
>make</SPAN
199
> custom build steps</TD
200
></TR
201
></TBODY
202
></TABLE
203
><P
204
></P
205
></DIV
206
><P
207
>Generation of the <TT
208
CLASS="FILENAME"
209
>extras.o</TT
210
> file, the startup code
211
and the linker script actually happens via <SPAN
212
CLASS="PROPERTY"
213
>make</SPAN
214
> custom build steps,
215
typically defined in appropriate HAL packages. The component framework
216
has no special knowledge of these targets.</P
217
><P
218
>By default custom build steps for a <SPAN
219
CLASS="PROPERTY"
220
>make_object</SPAN
221
> property happen
222
during the same phase as most compilations, but this can be changed
223
using a <TT
224
CLASS="LITERAL"
225
>-priority</TT
226
> option. Similarly custom build
227
steps for a <SPAN
228
CLASS="PROPERTY"
229
>make</SPAN
230
> property happen at the end of a build, but this can
231
also be changed with a <TT
232
CLASS="LITERAL"
233
>-priority</TT
234
> option. For
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
238
><P
239
>Some build systems may run several commands of the same priority in
240
parallel. For example files listed in <SPAN
241
CLASS="PROPERTY"
242
>compile</SPAN
243
> properties may get
244
compiled in parallel, concurrently with <SPAN
245
CLASS="PROPERTY"
246
>make_object</SPAN
247
> custom build
248
steps with default priorities. Since most of the time for an <SPAN
249
CLASS="APPLICATION"
250
>eCos</SPAN
251
>
252
build involves processing <SPAN
253
CLASS="PROPERTY"
254
>compile</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
258
><DIV
259
CLASS="SECT2"
260
><H2
261
CLASS="SECT2"
262
><A
263
NAME="BUILD.MAKE.UPDATE">Updating the Build Tree</H2
264
><P
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
268
<TT
269
CLASS="FILENAME"
270
>ecos.ecc</TT
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
276
<TT
277
CLASS="LITERAL"
278
>--enable-maintainer-mode</TT
279
> option provide by the
280
<SPAN
281
CLASS="APPLICATION"
282
>autoconf</SPAN
283
> and <SPAN
284
CLASS="APPLICATION"
285
>automake</SPAN
286
> programs. At present no <SPAN
287
CLASS="APPLICATION"
288
>eCos</SPAN
289
>
290
build system implements this functionality, but it is likely to be
291
added in a future release.</P
292
></DIV
293
><DIV
294
CLASS="SECT2"
295
><H2
296
CLASS="SECT2"
297
><A
298
NAME="BUILD.MAKE.EXPORT">Exporting Public Header Files</H2
299
><P
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
310
CLASS="LITERAL"
311
>-I</TT
312
> header file
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
316
CLASS="FILENAME"
317
>include</TT
318
> subdirectory of the install tree.
319
The process involves the following:</P
320
><P
321
></P
322
><OL
323
TYPE="1"
324
><LI
325
><P
326
>The install tree, for example <TT
327
CLASS="FILENAME"
328
>/usr/local/ecos/install</TT
329
>, and its <TT
330
CLASS="FILENAME"
331
>include</TT
332
> subdirectory <TT
333
CLASS="FILENAME"
334
>/usr/local/ecos/install/include</TT
335
> will typically be
336
created when the build tree is generated or updated. At the same time
337
configuration header files will be written to the <TT
338
CLASS="FILENAME"
339
>pkgconf</TT
340
> subdirectory, for example
341
<TT
342
CLASS="FILENAME"
343
>/usr/local/ecos/include/pkgconf</TT
344
>, so that
345
the configuration data is visible to all the packages and to
346
application code that may wish to examine some of the configuration
347
options.</P
348
></LI
349
><LI
350
><P
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
354
><P
355
></P
356
><OL
357
TYPE="a"
358
><LI
359
><P
360
>If the package has an <A
361
HREF="ref.include-files.html"
362
><SPAN
363
CLASS="PROPERTY"
364
>include_files</SPAN
365
></A
366
> property then this
367
lists all the exported header files:</P
368
><TABLE
369
BORDER="5"
370
BGCOLOR="#E0E0F0"
371
WIDTH="70%"
372
><TR
373
><TD
374
><PRE
375
CLASS="PROGRAMLISTING"
376
>cdl_package &lt;some_package&gt; {
377
    &#8230;
378
    include_files header1.h header2.h
379
}    </PRE
380
></TD
381
></TR
382
></TABLE
383
><P
384
>If no arguments are given then the package does not export any header
385
files.</P
386
><TABLE
387
BORDER="5"
388
BGCOLOR="#E0E0F0"
389
WIDTH="70%"
390
><TR
391
><TD
392
><PRE
393
CLASS="PROGRAMLISTING"
394
>cdl_package &lt;some_package&gt; {
395
    &#8230;
396
    include_files
397
}    </PRE
398
></TD
399
></TR
400
></TABLE
401
><P
402
>The listed files may be in an <TT
403
CLASS="FILENAME"
404
>include</TT
405
> subdirectory within the package's
406
hierarchy, or they may be relative to the package's toplevel
407
directory. The <SPAN
408
CLASS="PROPERTY"
409
>include_files</SPAN
410
> property is intended mainly for very
411
simple packages. It can also be useful when converting existing code
412
to an <SPAN
413
CLASS="APPLICATION"
414
>eCos</SPAN
415
> package, to avoid rearranging the sources.</P
416
></LI
417
><LI
418
><P
419
>If there is no <SPAN
420
CLASS="PROPERTY"
421
>include_files</SPAN
422
> property then the component framework
423
will look for an <TT
424
CLASS="FILENAME"
425
>include</TT
426
>
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
430
CLASS="FILENAME"
431
>include/math.h</TT
432
> and <TT
433
CLASS="FILENAME"
434
>include/sys/ieeefp.h</TT
435
>, both of which will
436
be exported to the install tree.</P
437
></LI
438
><LI
439
><P
440
>As a last resort, if there is neither an <SPAN
441
CLASS="PROPERTY"
442
>include_files</SPAN
443
> property nor
444
an <TT
445
CLASS="FILENAME"
446
>include</TT
447
> subdirectory, the
448
component framework will search the package's toplevel directory and
449
all of its subdirectories for files with one of the following
450
suffixes: <TT
451
CLASS="LITERAL"
452
>.h</TT
453
>, <TT
454
CLASS="LITERAL"
455
>.hxx</TT
456
>,
457
<TT
458
CLASS="LITERAL"
459
>.inl</TT
460
> or <TT
461
CLASS="LITERAL"
462
>.inc</TT
463
>. All such files
464
will be interpreted as exported header files.</P
465
><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
472
CLASS="PROPERTY"
473
>include_files</SPAN
474
> property
475
with no arguments.</P
476
></LI
477
></OL
478
></LI
479
><LI
480
><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
484
CLASS="FILENAME"
485
>include</TT
486
> subdirectory. For example the
487
math library's <TT
488
CLASS="FILENAME"
489
>math.h</TT
490
> header
491
would end up as <TT
492
CLASS="FILENAME"
493
>/usr/local/ecos/include/math.h</TT
494
>,
495
and the <TT
496
CLASS="FILENAME"
497
>sys/ieeefp.h</TT
498
> header
499
would end up as
500
<TT
501
CLASS="FILENAME"
502
>/usr/local/ecos/include/sys/ieeefp.h</TT
503
>. This
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"
508
><SPAN
509
CLASS="PROPERTY"
510
>include_dir</SPAN
511
></A
512
> property should be used
513
to avoid this:</P
514
><TABLE
515
BORDER="5"
516
BGCOLOR="#E0E0F0"
517
WIDTH="70%"
518
><TR
519
><TD
520
><PRE
521
CLASS="PROGRAMLISTING"
522
>cdl_package CYGPKG_KERNEL {
523
    include_dir cyg/kernel
524
}</PRE
525
></TD
526
></TR
527
></TABLE
528
><P
529
>This means that the kernel's exported header file
530
<TT
531
CLASS="FILENAME"
532
>include/kapi.h</TT
533
> should be copied to
534
<TT
535
CLASS="FILENAME"
536
>/usr/local/ecos/include/cyg/kernel/kapi.h</TT
537
>, where
538
it is very unlikely to clash with a header file from some other
539
package.</P
540
></LI
541
><LI
542
><P
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
551
></LI
552
><LI
553
><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
563
></LI
564
><LI
565
><P
566
>When updating the install tree's <TT
567
CLASS="FILENAME"
568
>include</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
572
delete them.</P
573
></LI
574
></OL
575
><DIV
576
CLASS="NOTE"
577
><BLOCKQUOTE
578
CLASS="NOTE"
579
><P
580
><B
581
>Note: </B
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
589
></BLOCKQUOTE
590
></DIV
591
></DIV
592
><DIV
593
CLASS="SECT2"
594
><H2
595
CLASS="SECT2"
596
><A
597
NAME="BUILD.MAKE.COMPILES">Compiling</H2
598
><P
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
602
CLASS="PROPERTY"
603
>compile</SPAN
604
> properties in the <SPAN
605
CLASS="APPLICATION"
606
>CDL</SPAN
607
>
608
scripts for the various packages, for example:</P
609
><TABLE
610
BORDER="5"
611
BGCOLOR="#E0E0F0"
612
WIDTH="70%"
613
><TR
614
><TD
615
><PRE
616
CLASS="PROGRAMLISTING"
617
>cdl_package CYGPKG_ERROR {
618
    display       "Common error code support"
619
    compile       strerror.cxx
620
    &#8230;
621
}</PRE
622
></TD
623
></TR
624
></TABLE
625
><P
626
><SPAN
627
CLASS="PROPERTY"
628
>compile</SPAN
629
> properties may appear in the body of a <TT
630
CLASS="LITERAL"
631
>cdl_package</TT
632
>,
633
<TT
634
CLASS="LITERAL"
635
>cdl_component</TT
636
>, <TT
637
CLASS="LITERAL"
638
>cdl_option</TT
639
> or <TT
640
CLASS="LITERAL"
641
>cdl_interface</TT
642
>. If the option or
643
other <SPAN
644
CLASS="APPLICATION"
645
>CDL</SPAN
646
> entity is active and enabled, the property takes effect.
647
If the option is inactive or disabled the property is ignored. It is
648
possible for a <SPAN
649
CLASS="PROPERTY"
650
>compile</SPAN
651
> property to list multiple source files, and
652
it is also possible for a given <SPAN
653
CLASS="APPLICATION"
654
>CDL</SPAN
655
> entity to contain multiple
656
<SPAN
657
CLASS="PROPERTY"
658
>compile</SPAN
659
> properties. The following three examples are equivalent:</P
660
><TABLE
661
BORDER="5"
662
BGCOLOR="#E0E0F0"
663
WIDTH="70%"
664
><TR
665
><TD
666
><PRE
667
CLASS="PROGRAMLISTING"
668
>cdl_option &lt;some_option&gt; {
669
    &#8230;
670
    compile file1.c file2.c file3.c
671
}
672
 
673
cdl_option &lt;some_option&gt; {
674
    &#8230;
675
    compile file1.c
676
    compile file2.c
677
    compile file3.c
678
}
679
 
680
cdl_option &lt;some_option&gt; {
681
    &#8230;
682
    compile file1.c file2.c
683
    compile file3.c
684
}</PRE
685
></TD
686
></TR
687
></TABLE
688
><P
689
>Packages that follow the directory layout conventions should have a
690
subdirectory <TT
691
CLASS="FILENAME"
692
>src</TT
693
>, and the
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
697
file <TT
698
CLASS="FILENAME"
699
>strerror.cxx</TT
700
> then the following two lines
701
are equivalent:</P
702
><TABLE
703
BORDER="5"
704
BGCOLOR="#E0E0F0"
705
WIDTH="70%"
706
><TR
707
><TD
708
><PRE
709
CLASS="PROGRAMLISTING"
710
>    compile strerror.cxx
711
    compile src/strerror.cxx</PRE
712
></TD
713
></TR
714
></TABLE
715
><P
716
>In the first case the component framework will find the file
717
immediately in the packages <TT
718
CLASS="FILENAME"
719
>src</TT
720
>
721
subdirectory. In the second case the framework will first look for a
722
file <TT
723
CLASS="FILENAME"
724
>src/src/strerror.cxx</TT
725
>, and then for
726
<TT
727
CLASS="FILENAME"
728
>str/strerror.cxx</TT
729
> relative to the package's root
730
directory. The result is the same.</P
731
><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
734
file <TT
735
CLASS="FILENAME"
736
>src/sync/mutex.cxx</TT
737
> then the corresponding
738
<SPAN
739
CLASS="APPLICATION"
740
>CDL</SPAN
741
> entry would be:</P
742
><TABLE
743
BORDER="5"
744
BGCOLOR="#E0E0F0"
745
WIDTH="70%"
746
><TR
747
><TD
748
><PRE
749
CLASS="PROGRAMLISTING"
750
>    compile sync/mutex.cxx</PRE
751
></TD
752
></TR
753
></TABLE
754
><P
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
759
><TABLE
760
BORDER="5"
761
BGCOLOR="#E0E0F0"
762
WIDTH="70%"
763
><TR
764
><TD
765
><PRE
766
CLASS="PROGRAMLISTING"
767
>&lt;object file&gt; : &lt;source file&gt;
768
        $(CC) -c $(INCLUDE_PATH) $(CFLAGS) -o $@ $&#60;</PRE
769
></TD
770
></TR
771
></TABLE
772
><P
773
>The component framework has built-in knowledge for processing source
774
files written in C, C++ or assembler. These should have a
775
<TT
776
CLASS="LITERAL"
777
>.c</TT
778
>, <TT
779
CLASS="LITERAL"
780
>.cxx</TT
781
> and
782
<TT
783
CLASS="LITERAL"
784
>.S</TT
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
788
a future release.</P
789
><P
790
>The compiler command that will be used is something like
791
<TT
792
CLASS="LITERAL"
793
>arm-elf-gcc</TT
794
>. This consists of a command prefix, in
795
this case <TT
796
CLASS="LITERAL"
797
>arm-elf</TT
798
>, and a specific command such as
799
<TT
800
CLASS="LITERAL"
801
>gcc</TT
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
808
set of tools.</P
809
><P
810
>The <TT
811
CLASS="LITERAL"
812
>$(INCLUDE_PATH)</TT
813
> header file search path
814
consists of at least the following:</P
815
><P
816
></P
817
><OL
818
TYPE="1"
819
><LI
820
><P
821
>The <TT
822
CLASS="FILENAME"
823
>include</TT
824
> directory in the
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
828
></LI
829
><LI
830
><P
831
>The current package's root directory. This ensures that all files in
832
the package are accessible at build time.</P
833
></LI
834
><LI
835
><P
836
>The current package's <TT
837
CLASS="FILENAME"
838
>src</TT
839
>
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
843
></LI
844
></OL
845
><P
846
>The compiler flags <TT
847
CLASS="LITERAL"
848
>$(CFLAGS)</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
853
<TT
854
CLASS="LITERAL"
855
>-mcpu=arm9</TT
856
>, various flags related to warnings,
857
debugging and optimization, and flags such as
858
<TT
859
CLASS="LITERAL"
860
>-finit-priority</TT
861
> which are needed by <SPAN
862
CLASS="APPLICATION"
863
>eCos</SPAN
864
> itself.
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
869
><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
878
><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
884
></DIV
885
><DIV
886
CLASS="SECT2"
887
><H2
888
CLASS="SECT2"
889
><A
890
NAME="BUILD.MAKE.LIBRARIES">Generating the Libraries</H2
891
><P
892
>Once all the <SPAN
893
CLASS="PROPERTY"
894
>compile</SPAN
895
> and <SPAN
896
CLASS="PROPERTY"
897
>make_object</SPAN
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
901
will be the <SPAN
902
CLASS="APPLICATION"
903
>ar</SPAN
904
> command
905
corresponding to the current architecture, for example <SPAN
906
CLASS="APPLICATION"
907
>powerpc-eabi-ar</SPAN
908
>. By default al of the
909
object files will end up in a single library
910
<TT
911
CLASS="FILENAME"
912
>libtarget.a</TT
913
>. This can be changed on a per-package
914
basis using the <A
915
HREF="ref.library.html"
916
><SPAN
917
CLASS="PROPERTY"
918
>library</SPAN
919
></A
920
> property
921
in the body of the corresponding <TT
922
CLASS="LITERAL"
923
>cdl_package</TT
924
> command, for example:</P
925
><TABLE
926
BORDER="5"
927
BGCOLOR="#E0E0F0"
928
WIDTH="70%"
929
><TR
930
><TD
931
><PRE
932
CLASS="PROGRAMLISTING"
933
>cdl_package &lt;SOME_PACKAGE&gt; {
934
    &#8230;
935
    library  libSomePackage.a
936
}</PRE
937
></TD
938
></TR
939
></TABLE
940
><P
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
946
<TT
947
CLASS="FILENAME"
948
>libtarget.a</TT
949
> avoids any complications.</P
950
><P
951
>It is also possible to change the target library for individual files,
952
using a <TT
953
CLASS="LITERAL"
954
>-library</TT
955
> option with the corresponding
956
<SPAN
957
CLASS="PROPERTY"
958
>compile</SPAN
959
> or <SPAN
960
CLASS="PROPERTY"
961
>make_object</SPAN
962
> property. For example:</P
963
><TABLE
964
BORDER="5"
965
BGCOLOR="#E0E0F0"
966
WIDTH="70%"
967
><TR
968
><TD
969
><PRE
970
CLASS="PROGRAMLISTING"
971
>    compile -library=libSomePackage.a hello.c
972
    make_object -library=libSomePackage.a {
973
        &#8230;
974
    }</PRE
975
></TD
976
></TR
977
></TABLE
978
><P
979
>Again this should be avoided because it makes application development
980
more difficult. There is one special library which can be used freely,
981
<TT
982
CLASS="FILENAME"
983
>libextras.a</TT
984
>, which is used to generate the
985
<TT
986
CLASS="FILENAME"
987
>extras.o</TT
988
> file as described below.</P
989
><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
994
></DIV
995
><DIV
996
CLASS="SECT2"
997
><H2
998
CLASS="SECT2"
999
><A
1000
NAME="BUILD.EXTRAS">The <TT
1001
CLASS="FILENAME"
1002
>extras.o</TT
1003
> file</H2
1004
><P
1005
>Package sources files normally get compiled and then added to a
1006
library, by default <TT
1007
CLASS="FILENAME"
1008
>libtarget.a</TT
1009
>, which is then
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
1018
><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
1023
<TT
1024
CLASS="LITERAL"
1025
>"/dev/xyzzy"</TT
1026
> and call the device functions
1027
indirectly. This will be impossible if the functions have been
1028
removed at link-time.</P
1029
><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
1038
><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
1043
><P
1044
>To meet requirements such as these the build system provides support
1045
for a file <TT
1046
CLASS="FILENAME"
1047
>extras.o</TT
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
1051
linked in. The <TT
1052
CLASS="FILENAME"
1053
>extras.o</TT
1054
> file is generated at the
1055
end of a build from a library <TT
1056
CLASS="FILENAME"
1057
>libextras.a</TT
1058
>, so
1059
packages can put functions and variables in suitable source files and
1060
add them to that library explicitly:</P
1061
><TABLE
1062
BORDER="5"
1063
BGCOLOR="#E0E0F0"
1064
WIDTH="70%"
1065
><TR
1066
><TD
1067
><PRE
1068
CLASS="PROGRAMLISTING"
1069
>    compile -library=libextras.a xyzzy.c
1070
    compile xyzzy_support.c</PRE
1071
></TD
1072
></TR
1073
></TABLE
1074
><P
1075
>In this example <TT
1076
CLASS="FILENAME"
1077
>xyzzy.o</TT
1078
> will end up in
1079
<TT
1080
CLASS="FILENAME"
1081
>libextras.a</TT
1082
>, and hence in
1083
<TT
1084
CLASS="FILENAME"
1085
>extras.o</TT
1086
> and in the final executable.
1087
<TT
1088
CLASS="FILENAME"
1089
>xyzzy_support.o</TT
1090
> will end up in
1091
<TT
1092
CLASS="FILENAME"
1093
>libtarget.a</TT
1094
> as usual, and is subject to linker
1095
garbage collection.</P
1096
></DIV
1097
><DIV
1098
CLASS="SECT2"
1099
><H2
1100
CLASS="SECT2"
1101
><A
1102
NAME="BUILD.FLAGS">Compilers and Flags</H2
1103
><DIV
1104
CLASS="CAUTION"
1105
><P
1106
></P
1107
><TABLE
1108
CLASS="CAUTION"
1109
BORDER="1"
1110
WIDTH="100%"
1111
><TR
1112
><TD
1113
ALIGN="CENTER"
1114
><B
1115
>Caution</B
1116
></TD
1117
></TR
1118
><TR
1119
><TD
1120
ALIGN="LEFT"
1121
><P
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
1126
></TD
1127
></TR
1128
></TABLE
1129
></DIV
1130
><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
1139
><TABLE
1140
BORDER="5"
1141
BGCOLOR="#E0E0F0"
1142
WIDTH="70%"
1143
><TR
1144
><TD
1145
><PRE
1146
CLASS="PROGRAMLISTING"
1147
>cdl_component CYGBLD_GLOBAL_OPTIONS {
1148
    flavor  none
1149
    parent  CYGPKG_NONE
1150
    &#8230;
1151
 
1152
    cdl_option CYGBLD_GLOBAL_COMMAND_PREFIX {
1153
        flavor  data
1154
        default_value { "arm-elf" }
1155
        &#8230;
1156
    }
1157
    cdl_option CYGBLD_GLOBAL_CFLAGS {
1158
        flavor  data
1159
        default_value "-Wall -g -O2 &#8230;"
1160
        &#8230;
1161
    }
1162
 
1163
    cdl_option CYGBLD_GLOBAL_LDFLAGS {
1164
        flavor  data
1165
        default_value "-g -nostdlib -Wl,--gc-sections &#8230;"
1166
        &#8230;
1167
    }
1168
}</PRE
1169
></TD
1170
></TR
1171
></TABLE
1172
><P
1173
>The <TT
1174
CLASS="VARNAME"
1175
>CYGBLD_GLOBAL_OPTIONS</TT
1176
> component serves to
1177
collect together all global build-related options. It has the flavor
1178
<TT
1179
CLASS="LITERAL"
1180
>none</TT
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
1186
<TT
1187
CLASS="FILENAME"
1188
>ecos.ecc</TT
1189
> save file.</P
1190
><DIV
1191
CLASS="NOTE"
1192
><BLOCKQUOTE
1193
CLASS="NOTE"
1194
><P
1195
><B
1196
>Note: </B
1197
>Currently the <SPAN
1198
CLASS="PROPERTY"
1199
>parent</SPAN
1200
> property lists a parent of
1201
<TT
1202
CLASS="VARNAME"
1203
>CYGPKG_NONE</TT
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
1207
framework.</P
1208
></BLOCKQUOTE
1209
></DIV
1210
><P
1211
>The option <TT
1212
CLASS="VARNAME"
1213
>CYGBLD_GLOBAL_COMMAND_PREFIX</TT
1214
> defines
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
1219
CLASS="PROPERTY"
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.
1224
<TT
1225
CLASS="VARNAME"
1226
>CYGBLD_GLOBAL_COMMAND_PREFIX</TT
1227
> is modifiable rather
1228
than calculated, so users can override this when necessary.</P
1229
><P
1230
>Given a command prefix such as <TT
1231
CLASS="LITERAL"
1232
>arm-elf</TT
1233
>, all C
1234
source files will be compiled with <TT
1235
CLASS="LITERAL"
1236
>arm-elf-gcc</TT
1237
>, all
1238
C++ sources will be built using <TT
1239
CLASS="LITERAL"
1240
>arm-elf-g++</TT
1241
>,
1242
and <TT
1243
CLASS="LITERAL"
1244
>arm-elf-ar</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
1249
CLASS="LITERAL"
1250
>$(CC)</TT
1251
> will be set to
1252
<TT
1253
CLASS="LITERAL"
1254
>arm-elf-gcc</TT
1255
>.</P
1256
><P
1257
>The next option, <TT
1258
CLASS="VARNAME"
1259
>CYGBLD_GLOBAL_CFLAGS</TT
1260
>, is used to
1261
provide the initial value of <TT
1262
CLASS="LITERAL"
1263
>$(CFLAGS)</TT
1264
>. Some
1265
compiler flags such as <TT
1266
CLASS="LITERAL"
1267
>-Wall</TT
1268
> and
1269
<TT
1270
CLASS="LITERAL"
1271
>-g</TT
1272
> are likely to be used on all targets. Other
1273
flags such as <TT
1274
CLASS="LITERAL"
1275
>-mcpu=arm7tdmi</TT
1276
> will be
1277
target-specific. Again this is a modifiable option, so the user can
1278
switch from say <TT
1279
CLASS="LITERAL"
1280
>-O2</TT
1281
> to <TT
1282
CLASS="LITERAL"
1283
>-Os</TT
1284
> if
1285
desired. The option <TT
1286
CLASS="VARNAME"
1287
>CYGBLD_GLOBAL_LDFLAGS</TT
1288
> serves
1289
the same purpose for <TT
1290
CLASS="LITERAL"
1291
>$(LDFLAGS)</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
1296
><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
1300
><TABLE
1301
BORDER="5"
1302
BGCOLOR="#E0E0F0"
1303
WIDTH="70%"
1304
><TR
1305
><TD
1306
><PRE
1307
CLASS="PROGRAMLISTING"
1308
>cdl_component CYGPKG_KERNEL_OPTIONS {
1309
    display "Kernel build options"
1310
    flavor  none
1311
    &#8230;
1312
 
1313
    cdl_option CYGPKG_KERNEL_CFLAGS_ADD {
1314
        display "Additional compiler flags"
1315
        flavor  data
1316
        default_value { "" }
1317
        &#8230;
1318
    }
1319
 
1320
    cdl_option CYGPKG_KERNEL_CFLAGS_REMOVE {
1321
        display "Suppressed compiler flags"
1322
        flavor  data
1323
        default_value { "" }
1324
        &#8230;
1325
    }
1326
 
1327
    cdl_option CYGPKG_KERNEL_LDFLAGS_ADD {
1328
        display "Additional linker flags"
1329
        flavor  data
1330
        default_value { "" }
1331
        &#8230;
1332
    }
1333
 
1334
    cdl_option CYGPKG_KERNEL_LDFLAGS_REMOVE {
1335
        display "Suppressed linker flags"
1336
        flavor  data
1337
        default_value { "" }
1338
        &#8230;
1339
    }
1340
}</PRE
1341
></TD
1342
></TR
1343
></TABLE
1344
><P
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
1348
CLASS="LITERAL"
1349
>$(CFLAGS)</TT
1350
> that is used for
1351
the compilations and custom build steps in a given package is
1352
determined as follows:</P
1353
><P
1354
></P
1355
><OL
1356
TYPE="1"
1357
><LI
1358
><P
1359
>Start with the global settings from
1360
<TT
1361
CLASS="VARNAME"
1362
>CYGBLD_GLOBAL_CFLAGS</TT
1363
>, for example
1364
<TT
1365
CLASS="LITERAL"
1366
>-g&nbsp;-O2</TT
1367
>.</P
1368
></LI
1369
><LI
1370
><P
1371
>Remove any flags specified in the per-package
1372
<TT
1373
CLASS="LITERAL"
1374
>CFLAGS_REMOVE</TT
1375
> option, if any. For example
1376
if <TT
1377
CLASS="LITERAL"
1378
>-O2</TT
1379
> should be removed for this package then
1380
<TT
1381
CLASS="LITERAL"
1382
>$(CFLAGS)</TT
1383
> would now have a value of just
1384
<TT
1385
CLASS="LITERAL"
1386
>-g</TT
1387
>.</P
1388
></LI
1389
><LI
1390
><P
1391
>Then concatenate the flags specified by the per-package
1392
<TT
1393
CLASS="LITERAL"
1394
>CFLAGS_ADD</TT
1395
> option, if any. For example if
1396
<TT
1397
CLASS="LITERAL"
1398
>-Os</TT
1399
> should be added for the current package then
1400
the final value of <TT
1401
CLASS="LITERAL"
1402
>$(CFLAGS)</TT
1403
> will be
1404
<TT
1405
CLASS="LITERAL"
1406
>-g&nbsp;-Os</TT
1407
>.</P
1408
></LI
1409
></OL
1410
><P
1411
><TT
1412
CLASS="LITERAL"
1413
>$(LDFLAGS)</TT
1414
> is determined in much the same way.</P
1415
><DIV
1416
CLASS="NOTE"
1417
><BLOCKQUOTE
1418
CLASS="NOTE"
1419
><P
1420
><B
1421
>Note: </B
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
1426
CLASS="PROPERTY"
1427
>make_object</SPAN
1428
> property can be used to work
1429
around the limitations.</P
1430
><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
1436
<TT
1437
CLASS="VARNAME"
1438
>CYGPKG_LIBM_CFLAGS_ADD</TT
1439
> and
1440
<TT
1441
CLASS="VARNAME"
1442
>CYGPKG_LIBM_CFLAGS_REMOVE</TT
1443
> <SPAN
1444
CLASS="PROPERTY"
1445
>default_value</SPAN
1446
>
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
1450
modify the <SPAN
1451
CLASS="PROPERTY"
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
1461
></BLOCKQUOTE
1462
></DIV
1463
><DIV
1464
CLASS="NOTE"
1465
><BLOCKQUOTE
1466
CLASS="NOTE"
1467
><P
1468
><B
1469
>Note: </B
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
1476
compiler flags.</P
1477
></BLOCKQUOTE
1478
></DIV
1479
></DIV
1480
><DIV
1481
CLASS="SECT2"
1482
><H2
1483
CLASS="SECT2"
1484
><A
1485
NAME="BUILD.CUSTOM">Custom Build Steps</H2
1486
><DIV
1487
CLASS="CAUTION"
1488
><P
1489
></P
1490
><TABLE
1491
CLASS="CAUTION"
1492
BORDER="1"
1493
WIDTH="100%"
1494
><TR
1495
><TD
1496
ALIGN="CENTER"
1497
><B
1498
>Caution</B
1499
></TD
1500
></TR
1501
><TR
1502
><TD
1503
ALIGN="LEFT"
1504
><P
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
1509
></TD
1510
></TR
1511
></TABLE
1512
></DIV
1513
><P
1514
>For most packages simply listing one or more source files in a
1515
<SPAN
1516
CLASS="PROPERTY"
1517
>compile</SPAN
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
1526
CLASS="PROPERTY"
1527
>make</SPAN
1528
> and <SPAN
1529
CLASS="PROPERTY"
1530
>make_object</SPAN
1531
>, and both take the following
1532
form:</P
1533
><TABLE
1534
BORDER="5"
1535
BGCOLOR="#E0E0F0"
1536
WIDTH="70%"
1537
><TR
1538
><TD
1539
><PRE
1540
CLASS="PROGRAMLISTING"
1541
>    make {
1542
        &lt;target_filepath&gt; : &lt;dependency_filepath&gt; &#8230;
1543
            &lt;command&gt;
1544
            ...
1545
    }</PRE
1546
></TD
1547
></TR
1548
></TABLE
1549
><P
1550
>Although this may look like makefile syntax, and although some build
1551
environments will indeed involve generating makefiles and running
1552
<SPAN
1553
CLASS="APPLICATION"
1554
>make</SPAN
1555
>, this is not
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
1562
><P
1563
></P
1564
><OL
1565
TYPE="a"
1566
><LI
1567
><P
1568
>Only one target can be specified. For a <SPAN
1569
CLASS="PROPERTY"
1570
>make_object</SPAN
1571
> property this
1572
target must be an object file. For a <SPAN
1573
CLASS="PROPERTY"
1574
>make</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
1580
CLASS="LITERAL"
1581
>&lt;PREFIX&gt;</TT
1582
>
1583
token, for example:</P
1584
><TABLE
1585
BORDER="5"
1586
BGCOLOR="#E0E0F0"
1587
WIDTH="70%"
1588
><TR
1589
><TD
1590
><PRE
1591
CLASS="PROGRAMLISTING"
1592
>    make {
1593
        &lt;PREFIX&gt;/lib/mytarget : &#8230;
1594
            ...
1595
    }</PRE
1596
></TD
1597
></TR
1598
></TABLE
1599
><P
1600
>When the build tree is generated and the custom build step is added to
1601
the makefile (or whatever build system is used)
1602
<TT
1603
CLASS="LITERAL"
1604
>&lt;PREFIX&gt;</TT
1605
> will be replaced with the absolute
1606
path to the install tree. </P
1607
></LI
1608
><LI
1609
><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
1612
<TT
1613
CLASS="LITERAL"
1614
>&lt;PACKAGE&gt;</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
1619
><TABLE
1620
BORDER="5"
1621
BGCOLOR="#E0E0F0"
1622
WIDTH="70%"
1623
><TR
1624
><TD
1625
><PRE
1626
CLASS="PROGRAMLISTING"
1627
>    make_object {
1628
        xyzzy.o : &lt;PACKAGE&gt;/src/xyzzy.c
1629
            &#8230;</PRE
1630
></TD
1631
></TR
1632
></TABLE
1633
><P
1634
>If the component repository was installed in <TT
1635
CLASS="FILENAME"
1636
>/usr/local/ecos</TT
1637
> and this custom build
1638
step existed in version 1_5 of the kernel,
1639
<TT
1640
CLASS="LITERAL"
1641
>&lt;PACKAGE&gt;</TT
1642
> would be replaced with
1643
<TT
1644
CLASS="FILENAME"
1645
>/usr/local/ecos/packages/kernel/v1_5</TT
1646
>.</P
1647
><P
1648
>Alternatively the dependencies may refer to files that are generated
1649
during the build. These may be object files resulting from <SPAN
1650
CLASS="PROPERTY"
1651
>compile</SPAN
1652
>
1653
properties or other <SPAN
1654
CLASS="PROPERTY"
1655
>make_object</SPAN
1656
> properties, or they may be other
1657
files resulting from a <SPAN
1658
CLASS="PROPERTY"
1659
>make</SPAN
1660
> property, for example:</P
1661
><TABLE
1662
BORDER="5"
1663
BGCOLOR="#E0E0F0"
1664
WIDTH="70%"
1665
><TR
1666
><TD
1667
><PRE
1668
CLASS="PROGRAMLISTING"
1669
>    compile plugh.c
1670
    make_object {
1671
        xyzzy.o : plugh.o
1672
            &#8230;
1673
    }</PRE
1674
></TD
1675
></TR
1676
></TABLE
1677
></LI
1678
><LI
1679
><P
1680
>No other token or makefile variables may be used in the target or
1681
dependency file names. Also conditionals such as
1682
<TT
1683
CLASS="LITERAL"
1684
>ifneq</TT
1685
> and similar makefile functionality must not
1686
be used.</P
1687
></LI
1688
><LI
1689
><P
1690
>
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
1695
<TT
1696
CLASS="LITERAL"
1697
>&lt;PREFIX&gt;</TT
1698
> and
1699
<TT
1700
CLASS="LITERAL"
1701
>&lt;PACKAGE&gt;</TT
1702
> tokens mentioned earlier:</P
1703
><DIV
1704
CLASS="INFORMALTABLE"
1705
><A
1706
NAME="AEN2778"><P
1707
></P
1708
><TABLE
1709
BORDER="1"
1710
CLASS="CALSTABLE"
1711
><THEAD
1712
><TR
1713
><TH
1714
ALIGN="LEFT"
1715
VALIGN="TOP"
1716
>Token</TH
1717
><TH
1718
ALIGN="LEFT"
1719
VALIGN="TOP"
1720
>Purpose</TH
1721
><TH
1722
ALIGN="LEFT"
1723
VALIGN="TOP"
1724
>Example value</TH
1725
></TR
1726
></THEAD
1727
><TBODY
1728
><TR
1729
><TD
1730
ALIGN="LEFT"
1731
VALIGN="TOP"
1732
><TT
1733
CLASS="LITERAL"
1734
>$(AR)</TT
1735
></TD
1736
><TD
1737
ALIGN="LEFT"
1738
VALIGN="TOP"
1739
>the GNU archiver</TD
1740
><TD
1741
ALIGN="LEFT"
1742
VALIGN="TOP"
1743
><TT
1744
CLASS="LITERAL"
1745
>mips-tx39-elf-ar</TT
1746
></TD
1747
></TR
1748
><TR
1749
><TD
1750
ALIGN="LEFT"
1751
VALIGN="TOP"
1752
><TT
1753
CLASS="LITERAL"
1754
>$(CC)</TT
1755
></TD
1756
><TD
1757
ALIGN="LEFT"
1758
VALIGN="TOP"
1759
>the GNU compiler</TD
1760
><TD
1761
ALIGN="LEFT"
1762
VALIGN="TOP"
1763
><TT
1764
CLASS="LITERAL"
1765
>sh-elf-gcc</TT
1766
></TD
1767
></TR
1768
><TR
1769
><TD
1770
ALIGN="LEFT"
1771
VALIGN="TOP"
1772
><TT
1773
CLASS="LITERAL"
1774
>$(CFLAGS)</TT
1775
></TD
1776
><TD
1777
ALIGN="LEFT"
1778
VALIGN="TOP"
1779
>compiler flags</TD
1780
><TD
1781
ALIGN="LEFT"
1782
VALIGN="TOP"
1783
><TT
1784
CLASS="LITERAL"
1785
>-O2 -Wall</TT
1786
></TD
1787
></TR
1788
><TR
1789
><TD
1790
ALIGN="LEFT"
1791
VALIGN="TOP"
1792
><TT
1793
CLASS="LITERAL"
1794
>$(COMMAND_PREFIX)</TT
1795
></TD
1796
><TD
1797
ALIGN="LEFT"
1798
VALIGN="TOP"
1799
>the triplet prefix</TD
1800
><TD
1801
ALIGN="LEFT"
1802
VALIGN="TOP"
1803
><TT
1804
CLASS="LITERAL"
1805
>mn10300-elf-</TT
1806
></TD
1807
></TR
1808
><TR
1809
><TD
1810
ALIGN="LEFT"
1811
VALIGN="TOP"
1812
><TT
1813
CLASS="LITERAL"
1814
>$(INCLUDE_PATH&#62;</TT
1815
></TD
1816
><TD
1817
ALIGN="LEFT"
1818
VALIGN="TOP"
1819
>header file search path</TD
1820
><TD
1821
ALIGN="LEFT"
1822
VALIGN="TOP"
1823
><TT
1824
CLASS="LITERAL"
1825
>-I. -Isrc/misc</TT
1826
></TD
1827
></TR
1828
><TR
1829
><TD
1830
ALIGN="LEFT"
1831
VALIGN="TOP"
1832
><TT
1833
CLASS="LITERAL"
1834
>$(LDFLAGS)</TT
1835
></TD
1836
><TD
1837
ALIGN="LEFT"
1838
VALIGN="TOP"
1839
>linker flags</TD
1840
><TD
1841
ALIGN="LEFT"
1842
VALIGN="TOP"
1843
><TT
1844
CLASS="LITERAL"
1845
>-nostdlib -Wl,-static</TT
1846
></TD
1847
></TR
1848
><TR
1849
><TD
1850
ALIGN="LEFT"
1851
VALIGN="TOP"
1852
><TT
1853
CLASS="LITERAL"
1854
>$(OBJCOPY)</TT
1855
></TD
1856
><TD
1857
ALIGN="LEFT"
1858
VALIGN="TOP"
1859
>the objcopy utility</TD
1860
><TD
1861
ALIGN="LEFT"
1862
VALIGN="TOP"
1863
><TT
1864
CLASS="LITERAL"
1865
>arm-elf-objcopy</TT
1866
></TD
1867
></TR
1868
><TR
1869
><TD
1870
ALIGN="LEFT"
1871
VALIGN="TOP"
1872
><TT
1873
CLASS="LITERAL"
1874
>$(PREFIX)</TT
1875
></TD
1876
><TD
1877
ALIGN="LEFT"
1878
VALIGN="TOP"
1879
>location of the install tree</TD
1880
><TD
1881
ALIGN="LEFT"
1882
VALIGN="TOP"
1883
><TT
1884
CLASS="FILENAME"
1885
>/home/fred/ecos-install</TT
1886
></TD
1887
></TR
1888
><TR
1889
><TD
1890
ALIGN="LEFT"
1891
VALIGN="TOP"
1892
><TT
1893
CLASS="LITERAL"
1894
>$(REPOSITORY)</TT
1895
></TD
1896
><TD
1897
ALIGN="LEFT"
1898
VALIGN="TOP"
1899
>location of the component repository</TD
1900
><TD
1901
ALIGN="LEFT"
1902
VALIGN="TOP"
1903
><TT
1904
CLASS="FILENAME"
1905
>/home/fred/ecos/packages</TT
1906
></TD
1907
></TR
1908
></TBODY
1909
></TABLE
1910
><P
1911
></P
1912
></DIV
1913
><P
1914
>In addition commands in a custom build step may refer to the target
1915
and the dependencies using <TT
1916
CLASS="LITERAL"
1917
>$@</TT
1918
>,
1919
<TT
1920
CLASS="LITERAL"
1921
>$&#60;</TT
1922
>, <TT
1923
CLASS="LITERAL"
1924
>$^</TT
1925
> and
1926
<TT
1927
CLASS="LITERAL"
1928
>$*</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
1931
></LI
1932
><LI
1933
><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
1939
<SPAN
1940
CLASS="PROPERTY"
1941
>compile</SPAN
1942
> properties will be located here as well, which is useful for
1943
custom build steps that depend on a <TT
1944
CLASS="LITERAL"
1945
>.o</TT
1946
> file
1947
previously generated.</P
1948
><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
1952
CLASS="FILENAME"
1953
>.tmp</TT
1954
> file extension to ensure
1955
that they are deleted during a <TT
1956
CLASS="LITERAL"
1957
>make&nbsp;clean</TT
1958
> or
1959
equivalent operation.</P
1960
><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
1965
></LI
1966
><LI
1967
><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"
1975
TARGET="_top"
1976
>GNU coding
1977
standards</A
1978
> provide some useful guidelines for writing portable
1979
build rules.</P
1980
></LI
1981
><LI
1982
><P
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
1986
></LI
1987
><LI
1988
><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
1994
><TABLE
1995
BORDER="5"
1996
BGCOLOR="#E0E0F0"
1997
WIDTH="70%"
1998
><TR
1999
><TD
2000
><PRE
2001
CLASS="PROGRAMLISTING"
2002
>    arm-elf-gcc -c -mcpu=arm7di -o $@ $&lt;</PRE
2003
></TD
2004
></TR
2005
></TABLE
2006
><P
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
2010
CLASS="LITERAL"
2011
>arm-elf</TT
2012
>. Also, if the
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
2015
><TABLE
2016
BORDER="5"
2017
BGCOLOR="#E0E0F0"
2018
WIDTH="70%"
2019
><TR
2020
><TD
2021
><PRE
2022
CLASS="PROGRAMLISTING"
2023
>    $(CC) -c $(CFLAGS) -o $@ $&lt;</PRE
2024
></TD
2025
></TR
2026
></TABLE
2027
><P
2028
>Some commands such as the compiler, the archiver, and objcopy are
2029
required sufficiently often to warrant their own tokens, for example
2030
<TT
2031
CLASS="LITERAL"
2032
>$(CC)</TT
2033
> and <TT
2034
CLASS="LITERAL"
2035
>$(OBJCOPY)</TT
2036
>. Other
2037
target-specific commands are needed only rarely and the
2038
<TT
2039
CLASS="LITERAL"
2040
>$(COMMAND_PREFIX)</TT
2041
> token can be used to construct
2042
the appropriate command name, for example:</P
2043
><TABLE
2044
BORDER="5"
2045
BGCOLOR="#E0E0F0"
2046
WIDTH="70%"
2047
><TR
2048
><TD
2049
><PRE
2050
CLASS="PROGRAMLISTING"
2051
>&#13;    $(COMMAND_PREFIX)size $&lt; &gt; $@</PRE
2052
></TD
2053
></TR
2054
></TABLE
2055
></LI
2056
><LI
2057
><P
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
2063
></LI
2064
></OL
2065
><P
2066
>By default custom build steps defined in a <SPAN
2067
CLASS="PROPERTY"
2068
>make_object</SPAN
2069
> property
2070
have a priority of 100, which means that they will be executed
2071
in the same phase as compilations resulting from a <SPAN
2072
CLASS="PROPERTY"
2073
>compile</SPAN
2074
> property.
2075
It is possible to change the priority using a property option, for
2076
example:</P
2077
><TABLE
2078
BORDER="5"
2079
BGCOLOR="#E0E0F0"
2080
WIDTH="70%"
2081
><TR
2082
><TD
2083
><PRE
2084
CLASS="PROGRAMLISTING"
2085
>    make_object -priority 50 {
2086
        &#8230;
2087
    }</PRE
2088
></TD
2089
></TR
2090
></TABLE
2091
><P
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
2096
CLASS="PROPERTY"
2097
>make_object</SPAN
2098
> properties should not specify a
2099
priority of 200 or later. </P
2100
><P
2101
>Custom build steps defined in a <SPAN
2102
CLASS="PROPERTY"
2103
>make</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
2107
CLASS="LITERAL"
2108
>-priority</TT
2109
>
2110
property option.</P
2111
></DIV
2112
><DIV
2113
CLASS="SECT2"
2114
><H2
2115
CLASS="SECT2"
2116
><A
2117
NAME="BUILD.STARTUP">Startup Code</H2
2118
><P
2119
>Linking an application requires the application code, a linker script,
2120
the eCos library or libraries, the <TT
2121
CLASS="LITERAL"
2122
>extras.o</TT
2123
> file,
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
2126
branching to <TT
2127
CLASS="LITERAL"
2128
>main()</TT
2129
>, or it may have to perform a
2130
considerable amount of hardware initialization. The startup code
2131
generally lives in a file <TT
2132
CLASS="LITERAL"
2133
>vectors.o</TT
2134
> which is
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
2139
><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
2147
><DIV
2148
CLASS="NOTE"
2149
><BLOCKQUOTE
2150
CLASS="NOTE"
2151
><P
2152
><B
2153
>Note: </B
2154
>It is possible that the <TT
2155
CLASS="LITERAL"
2156
>extras.o</TT
2157
> support, in
2158
conjunction with appropriate linker script directives, could be used
2159
to eliminate the need for a special startup file. The details are not
2160
yet clear.</P
2161
></BLOCKQUOTE
2162
></DIV
2163
></DIV
2164
><DIV
2165
CLASS="SECT2"
2166
><H2
2167
CLASS="SECT2"
2168
><A
2169
NAME="BUILD.LINKERSCRIPT">The Linker Script</H2
2170
><DIV
2171
CLASS="CAUTION"
2172
><P
2173
></P
2174
><TABLE
2175
CLASS="CAUTION"
2176
BORDER="1"
2177
WIDTH="100%"
2178
><TR
2179
><TD
2180
ALIGN="CENTER"
2181
><B
2182
>Caution</B
2183
></TD
2184
></TR
2185
><TR
2186
><TD
2187
ALIGN="LEFT"
2188
><P
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
2192
></TD
2193
></TR
2194
></TABLE
2195
></DIV
2196
><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
2201
a template.</P
2202
><DIV
2203
CLASS="NOTE"
2204
><BLOCKQUOTE
2205
CLASS="NOTE"
2206
><P
2207
><B
2208
>Note: </B
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
2214
future release.</P
2215
></BLOCKQUOTE
2216
></DIV
2217
></DIV
2218
></DIV
2219
><DIV
2220
CLASS="NAVFOOTER"
2221
><HR
2222
ALIGN="LEFT"
2223
WIDTH="100%"><TABLE
2224
SUMMARY="Footer navigation table"
2225
WIDTH="100%"
2226
BORDER="0"
2227
CELLPADDING="0"
2228
CELLSPACING="0"
2229
><TR
2230
><TD
2231
WIDTH="33%"
2232
ALIGN="left"
2233
VALIGN="top"
2234
><A
2235
HREF="build.headers.html"
2236
ACCESSKEY="P"
2237
>Prev</A
2238
></TD
2239
><TD
2240
WIDTH="34%"
2241
ALIGN="center"
2242
VALIGN="top"
2243
><A
2244
HREF="cdl-guide.html"
2245
ACCESSKEY="H"
2246
>Home</A
2247
></TD
2248
><TD
2249
WIDTH="33%"
2250
ALIGN="right"
2251
VALIGN="top"
2252
><A
2253
HREF="build.tests.html"
2254
ACCESSKEY="N"
2255
>Next</A
2256
></TD
2257
></TR
2258
><TR
2259
><TD
2260
WIDTH="33%"
2261
ALIGN="left"
2262
VALIGN="top"
2263
>Configuration Header File Generation</TD
2264
><TD
2265
WIDTH="34%"
2266
ALIGN="center"
2267
VALIGN="top"
2268
><A
2269
HREF="build.html"
2270
ACCESSKEY="U"
2271
>Up</A
2272
></TD
2273
><TD
2274
WIDTH="33%"
2275
ALIGN="right"
2276
VALIGN="top"
2277
>Building Test Cases</TD
2278
></TR
2279
></TABLE
2280
></DIV
2281
></BODY
2282
></HTML
2283
>

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.