source: rtems/c/src/make/README @ 9b4422a2

4.11
Last change on this file since 9b4422a2 was 9b4422a2, checked in by Joel Sherrill <joel.sherrill@…>, on May 3, 2012 at 3:09:24 PM

Remove All CVS Id Strings Possible Using a Script

Script does what is expected and tries to do it as
smartly as possible.

+ remove occurrences of two blank comment lines

next to each other after Id string line removed.

+ remove entire comment blocks which only exited to

contain CVS Ids

+ If the processing left a blank line at the top of

a file, it was removed.

  • Property mode set to 100644
File size: 17.9 KB
Line 
1    make/README
2
3    This file describes the layout and conventions of the application
4    makefile support for RTEMS applications.  Internally, RTEMS uses
5    GNU-style autoconf/automake Makefiles as much as possible to
6    ease integration with other GNU tools.
7
8    All of these "make" trees are substantially similar; however this
9    file documents the current state of the RTEMS Application Makefile
10    support.
11
12    This make tree is based on a build system originally developed
13    to simplify porting projects between various OS's.  The primary
14    goals were:
15
16        .  simple *and* customizable individual makefiles
17
18        .  use widely available GNU make.  There is no pre-processing or
19            automatic generation of Makefiles.
20
21        .  Same makefiles work on *many* host OS's due to portability
22            of GNU make and the host OS config files.
23
24        .  Support for different compilers and operating systems
25            on a per-user basis.  Using the same sources (including
26            Makefiles) one developer can develop and test under SVR4,
27            another under 4.x, another under HPUX.
28
29        .  Builtin support for compiling "variants" such as debug
30            versions.  These variants can be built
31            recursively.
32
33        .  Control of system dependencies.  "hidden" dependencies on
34            environment variables (such as PATH)
35            have been removed whenever possible.  No matter what your
36            PATH variable is set to, you should get the same thing
37            when you 'make' as everyone else on the project.
38
39    This Makefile system has evolved into its present form and as it
40    exists in RTEMS today, its sole goal is to build RTEMS applications.
41    The use of these Makefiles hides the complexity of producing
42    executables for a wide variety of embedded CPU families and target
43    BSPs.  Switching between RTEMS BSPs is accomplished via setting
44    the environment variable "RTEMS_MAKEFILE_PATH."
45
46    This description attempts to cover all aspects of the Makefile tree.  Most
47    of what is described here is maintained automatically by the configuration
48    files.
49
50    The example makefiles in make/Templates should be used as a starting
51    point for new directories.
52
53    There are 2 main types of Makefile:
54
55        directory and leaf.
56
57    Directory Makefiles
58    -------------------
59
60        A Makefile in a source directory with sub-directories is called a
61        "directory" Makefile.
62
63        Directory Makefile's are simply responsible for acting as "middle-men"
64        and recursing into their sub-directories and propagating the make.
65
66        For example, directory src/bin will contain only a Makefile and
67        sub-directories.  No actual source code will reside in the directory.
68        The following commands:
69
70            $ cd src/bin
71            $ make all
72
73        would descend into all the subdirectories of 'src/bin' and recursively
74        perform a 'make all'.
75
76        A 'make debug' will recurse thru sub-directories as a debug build.
77
78        A template directory Makefile which should work in almost all
79        cases is in make/Templates/Makefile.dir
80
81
82    Leaf Makefiles
83    --------------
84
85        Source directories that contain source code for libraries or
86        programs use a "leaf" Makefile.
87
88        These makefiles contain the rules necessary to build programs
89        (or libraries).
90
91        A template leaf Makefile is in Templates/Makefile.leaf .  A template
92        leaf Makefile for building libraries is in Templates/Makefile.lib .
93
94
95    NOTE: To simplify nested makefile's and source maintenance, we disallow
96    combining source and directories (that make(1) would be expected to
97    recurse into) in one source directory.  Ie., a directory in the source
98    tree may contain EITHER source files OR recursive sub directories, but NOT
99    both.  This assumption is generally shared with GNU automake.
100
101    Variants (where objects go)
102    ---------------------------
103
104        All binary targets are placed in a sub-directory whose name is (for
105        example):
106
107            o-optimize/       -- optimized binaries
108            o-debug/          -- debug binaries
109
110        Using the template Makefiles, this will all happen automatically.
111        The contents of these directories are specific to a BSP.
112
113        Within a Makefile, the ${ARCH} variable is set to o-optimize,
114        o-debug, etc., as appropriate.
115
116        HISTORICAL NOTE: Prior to version 4.5, the name of the sub-directory
117          in which objects were placed included the BSP name.
118           
119        Typing 'make' will place objects in o-optimize.
120        'make debug' will place objects in o-debug.
121
122        The debug targets are equivalent to 'all' except that
123        CFLAGS and/or LDFLAGS are modified as per the compiler config file for
124        debug and profile support.
125
126        The targets debug etc., can be invoked recursively at
127        the directory make level.  So from the top of a tree, one could
128        install a debug version of everything under that point by:
129
130            $ cd src/lib
131            $ gmake debug
132            $ gmake install
133
134        When building a command that is linked with a generated library, the
135        appropriate version of the library will be linked in.
136
137        For example, the following fragments link the normal, debug, or
138        version of "libmine.a" as appropriate:
139
140            LD_LIBS   += $(LIBMINE)
141            LIBMINE = ../libmine/${ARCH}/libmine.a
142
143            ${ARCH}/pgm: $(LIBMINE) ${OBJS}
144                $(make-exe)
145
146        If we do 'gmake debug', then the library in
147        ../libmine/o-debug/libmine.a will be linked in.  If $(LIBMINE)
148        might not exist (or might be out of date) at this point, we could add
149
150            ${LIBMINE}: FORCEIT
151                cd ../libmine; ${MAKE} ${VARIANT_VA}
152
153        The above would generate the following command to build libmine.a:
154
155            cd ../libmine; gmake debug
156
157        The macro reference ${VARIANT_VA} converts ${ARCH} to the word 'debug'
158        (in this example) and thus ensures the proper version of the library
159        is built.
160
161
162    Targets
163    -------
164
165        All Makefile's support the following targets:
166
167            all                     -- make "everything"
168            install                 -- install "everything"
169
170        The following targets are provided automatically by
171        the included config files:
172
173            clean                   -- delete all targets
174            depend                  -- build a make dependency file
175            "variant targets"       -- special variants, see below
176
177
178        All directory Makefiles automatically propagate all these targets.  If
179        you don't wish to support 'all' or 'install' in your source directory,
180        you must leave the rules section empty, as the parent directory Makefile
181        will attempt it on recursive make's.
182
183
184    Configuration
185    -------------
186
187        All the real work described here happens in file(s) included
188        from your Makefile.
189
190        All Makefiles include a customization file which is used to select
191        compiler and host operating system.  The environment variable
192        RTEMS_MAKEFILE_PATH must point to the directory containing this file; eg:
193
194                export RTEMS_MAKEFILE_PATH=/.../pc386/
195
196        All leaf Makefile's also include either 'make/leaf.cfg' (or
197        'make/lib.cfg' for building libraries).  These config files provide
198        default rules and set up the command macros as appropriate.
199
200        All directory Makefiles include 'make/directory.cfg'.  directory.cfg
201        provides all the rules for recursing through sub directories.
202
203        The Makefile templates already perform these include's.
204
205        'make/leaf.cfg' (or directory.cfg) in turn includes:
206
207            a file specifying general purpose rules appropriate for
208                both leaf and directory makefiles.
209                ( make/main.cfg )
210
211            personality modules specified by the customization file for:
212                compiler            ( make/compilers/??.cfg )
213
214
215        generic rules file
216        ------------------
217
218            [ make/main.cfg ]
219            included by leaf.cfg or directory.cfg.
220
221            This file contains some standard rules and variable assignments
222            that all Makefiles need.
223
224            It also includes the FORCEIT: pseudo target.
225
226
227        OS config file for host machine
228        -------------------------------
229
230            [ make/os/OS-NAME.cfg ]
231            included by main.cfg
232
233            Figures out the target architecture and specifies command names
234            for the OS tools including RCS/CVS (but NOT for the compiler tools).
235
236
237        Compiler configuration for the target
238        -------------------------------------
239
240            [ compilers/COMPILER-NAME.cfg ]
241            included by leaf.cfg
242
243            Specifies the names of tools for compiling programs.
244            Names in here should be fully qualified, and NOT depend on $PATH.
245
246            Also specifies compiler flags to be used to generate optimized,
247            debugging versions, as well as rules to compile
248            assembly language and make makefile dependencies.
249
250
251    Configuration Variables
252    -----------------------
253
254        Variables you have to set in the environment or in your Makefile.
255        Note: the RTEMS module files set RTEMS_ROOT and RTEMS_CUSTOM
256        for you.
257
258        Makefile Variables
259        ------------------
260
261            RTEMS_BSP        -- name of your 'bsp' eg: pc386, mvme136
262
263            RTEMS_CPU        -- CPU architecture e.g.: i386, m68k
264
265            RTEMS_CPU_FAMILY -- CPU model e.g.: i486dx, m68020
266
267            RTEMS_ROOT     -- The root of your source tree.
268                              All other file names are derived from this.
269                              [ eg: % setenv RTEMS_ROOT $HOME/work/RTEMS ]
270
271            RTEMS_CUSTOM   -- name of your config files in make/custom
272                              Example:
273                                 $(RTEMS_ROOT)/make/custom/$(RTEMS_BSP).cfg
274
275            The value RTEMS_ROOT is used in the custom
276            files to generate the make(1) variables:
277
278                PROJECT_RELEASE
279                PROJECT_BIN
280                PROJECT_INCLUDE
281                PROJECT_TOOLS
282
283            etc., which are used within the make config files themselves.
284            (The files in make/*.cfg try to avoid use of word RTEMS so
285            they can be more easily shared by other projects)
286
287        Preset variables
288        ----------------
289
290            Aside from command names set by the OS and compiler config files,
291            a number of MAKE variables are automatically set and maintained by
292            the config files.
293
294            PROJECT_RELEASE
295                        -- release/install directory
296                           [ $(PROJECT_ROOT) ]
297
298            PROJECT_BIN
299                        -- directory for installed binaries
300                           [ $(PROJECT_ROOT)/bin ]
301
302            PROJECT_TOOLS
303                        -- directory for build environment commands
304                           [ eg: $(PROJECT_ROOT)/build-tools ]
305
306            ARCH        -- target sub-directory for object code
307                           [ eg: o-optimize or o-debug ]
308
309            VARIANTS    -- full list of all possible values for $(ARCH);
310                           used mainly for 'make clean'
311                           [ eg: "o-optimize o-debug" ]
312
313            VARIANT_VA  -- Variant name.
314                           Normally "", but for 'make debug' it is "debug".
315
316                           see make/leaf.cfg for more info.
317
318
319        Preset compilation variables
320        ----------------------------
321
322          This is a list of some of the compilation variables.
323          Refer to the compiler config files for the complete list.
324
325            CFLAGS_OPTIMIZE_V   -- value of optimize flag for compiler
326                                   [ eg: -O ]
327
328            CFLAGS_DEBUG_V      -- value of debug flag for compiler
329                                   [ eg: -g ]
330
331            CFLAGS_DEBUG_OPTIMIZE_V
332                                -- optimize flag if compiling for debug
333                                     [ eg: "" ]
334
335            CFLAGS_DEBUG
336            CFLAGS_OPTIMIZE     -- current values for each depending
337                                    on make variant.
338
339            LDFLAGS_STATIC_LIBRARIES_V
340                                -- ld option for static libraries
341                                    -Bstatic or -dy (svr4)
342
343            LDFLAGS_SHARED_LIBRARIES_V
344                                -- ld option for dynamic libraries
345                                    -Bdynamic or -dn (svr4)
346
347            Makefile Variables
348            ------------------
349
350                The following variables may be set in a typical Makefile.
351
352                C_PIECES    -- File names of your .c files without '.c' suffix.
353                               [ eg: C_PIECES=main funcs stuff ]
354
355                CC_PIECES   -- ditto, except for .cc files
356
357                S_PIECES    -- ditto, except for .S files.
358
359                LIB         -- target library name in leaf library makefiles.
360                               [ eg: LIB=${ARCH}/libmine.a ]
361
362                H_FILES     -- your .h files in this directory.
363                               [ eg: H_FILES=stuff.h extra.h ]
364
365                DEFINES     -- cc -D items.  Included in CPPFLAGS.
366                               leaf Makefiles.
367                               [ eg: DEFINES += -DUNIX ]
368
369                CPPFLAGS    -- -I include directories.
370                               leaf Makefiles.
371                               [ eg: CPPFLAGS += -I../include ]
372
373                LD_PATHS    -- arguments to -L for ld.
374                               Will be prefixed with '-L' or '-L ' as appropriate
375                               and included in LDFLAGS.
376
377                LDFLAGS     -- -L arguments to ld; more may be ADDed.
378
379                LD_LIBS     -- libraries to be linked in.
380                               [ eg: LDLIBS += ../libfoo/${ARCH}/libfoo.a ]
381
382                XCFLAGS     -- "extra" CFLAGS for special needs.  Pre-pended
383                               to CFLAGS.
384                               Not set or used by Makefiles.
385                               Can be set on command line to pass extra flags
386                               to the compiler.
387
388                XCPPFLAGS   -- ditto for CPPFLAGS
389                               Can be set on command line to pass extra flags
390                               to the preprocessor.
391
392                XCCPPFLAGS  -- same as XCPPFLAGS for C++.
393
394                XCCFLAGS    -- same as XCFLAGS for C++.
395
396                SUBDIRS    -- list of sub directories for make recursion.
397                               directory Makefiles only.
398                               [ eg: SUBDIRS=cpu bsp ]
399
400                CLEAN_ADDITIONS
401                            -- list of files or directories that should
402                               be deleted by 'make clean'
403                               [ eg: CLEAN_ADDITIONS += y.tab.c ]
404
405                               See 'leaf.cfg' for the 'clean:' rule and its
406                               default deletions.
407
408                CLOBBER_ADDITIONS
409                            -- list of files or directories that should
410                               be deleted by 'make clobber'
411                               Since 'make clobber' includes 'make clean',
412                               you don't need to duplicate items in both.
413
414            Command names
415            -------------
416
417                The following commands should only be called
418                as make variables:
419
420                    MAKE,INSTALL,INSTALL_VARIANT,SHELL
421
422                    ECHO,CAT,CP,MV,LN,MKDIR,CHMOD
423
424                    SED
425
426                    CC,CPP,AS,AR,LD,NM,SIZE,RANLIB,MKLIB,
427                    YACC,LEX,LINT,CTAGS,ETAGS
428
429                 In addition, the following commands specifically support
430                 the installation of libraries, executables, header files,
431                 and other things that need to be installed:
432
433                    INSTALL_CHANGE  - install a file only if the source
434                                      file is actually different than
435                                      the installed copy or if there is
436                                      no installed copy.  USAGE:
437
438      usage: install-if-change [ -vmV ] file [ file ... ] dest-directory-or-file
439        -v          -- verbose
440        -V suffix   -- suffix to append to targets (before any . suffix)
441                        eg: -V _g would change 'foo' to 'foo_g' and
442                                               'libfoo.a' to 'libfoo_g.a'
443        -m mode     -- mode for new file(s)
444
445                    INSTALL_VARIANT - installs the built file using the
446                                      proper variant suffix (e.g. _g
447                                      for debug turns libmine.a into libmine_g.a)
448                                      This is implemented as a macro that
449                                      invokes install-if-change with the
450                                      appropriate -V argument setting.
451
452            Special Directory Makefile Targets
453            ----------------------------------
454
455                all_WRAPUP
456                clean_WRAPUP
457                install_WRAPUP
458                clean_WRAPUP
459                clobber_WRAPUP
460                depend_WRAPUP
461                            -- Specify additional commands for recursive
462                               (directory level) targets.
463
464                               This is handy in certain cases where you need
465                               to do bit of work *after* a recursive make.
466
467    make/Templates
468    --------------
469
470        This directory contains Makefile and source file templates that
471        should help in creating or converting makefiles.
472
473        Makefile.leaf
474            Template leaf Makefiles.
475
476        Makefile.lib
477            Template leaf library Makefiles.
478
479        Makefile.dir
480            Template "directory" makefile.
481
482
483   
484
Note: See TracBrowser for help on using the repository browser.