source: rtems/c/src/make/README @ 0707bd20

4.104.114.84.9
Last change on this file since 0707bd20 was 0707bd20, checked in by Ralf Corsepius <ralf.corsepius@…>, on Jun 6, 2003 at 2:59:13 AM

2003-06-06 Ralf Corsepius <corsepiu@…>

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