source: rtems/c/src/make/README @ c8f3e82

Last change on this file since c8f3e82 was df49c60, checked in by Joel Sherrill <joel.sherrill@…>, on 06/12/00 at 15:00:15

Merged from 4.5.0-beta3a

  • Property mode set to 100644
File size: 18.3 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            profile, and tcov 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            o-profile/        -- profiling binaries
114
115        Using the template Makefiles, this will all happen automatically.
116        The contents of these directories are specific to a BSP.
117
118        Within a Makefile, the ${ARCH} variable is set to o-optimize,
119        o-debug, etc., as appropriate.
120
121        HISTORICAL NOTE: Prior to version 4.5, the name of the sub-directory
122          in which objects were placed included the BSP name.
123           
124        Typing 'make' will place objects in o-optimize.
125        'make debug' will place objects in o-debug.
126        'make profile' will place objects in o-profile.
127
128        The debug and profile targets are equivalent to 'all' except that
129        CFLAGS and/or LDFLAGS are modified as per the compiler config file for
130        debug and profile support.
131
132        The targets debug, profile, etc., can be invoked recursively at
133        the directory make level.  So from the top of a tree, one could
134        install a debug version of everything under that point by:
135
136            $ cd src/lib
137            $ gmake debug
138            $ gmake install
139
140        When building a command that is linked with a generated library, the
141        appropriate version of the library will be linked in.
142
143        For example, the following fragments link the normal, debug, or
144        profile version of "libmine.a" as appropriate:
145
146            LD_LIBS   += $(LIBMINE)
147            LIBMINE = ../libmine/${ARCH}/libmine.a
148
149            ${ARCH}/pgm: $(LIBMINE) ${OBJS}
150                $(make-exe)
151
152        If we do 'gmake debug', then the library in
153        ../libmine/o-debug/libmine.a will be linked in.  If $(LIBMINE)
154        might not exist (or might be out of date) at this point, we could add
155
156            ${LIBMINE}: FORCEIT
157                cd ../libmine; ${MAKE} ${VARIANT_VA}
158
159        The above would generate the following command to build libmine.a:
160
161            cd ../libmine; gmake debug
162
163        The macro reference ${VARIANT_VA} converts ${ARCH} to the word 'debug'
164        (in this example) and thus ensures the proper version of the library
165        is built.
166
167
168    Targets
169    -------
170
171        All Makefile's support the following targets:
172
173            all                     -- make "everything"
174            install                 -- install "everything"
175
176        The following targets are provided automatically by
177        the included config files:
178
179            clean                   -- delete all targets
180            depend                  -- build a make dependency file
181            "variant targets"       -- special variants, see below
182
183
184        All directory Makefiles automatically propagate all these targets.  If
185        you don't wish to support 'all' or 'install' in your source directory,
186        you must leave the rules section empty, as the parent directory Makefile
187        will attempt it on recursive make's.
188
189
190    Configuration
191    -------------
192
193        All the real work described here happens in file(s) included
194        from your Makefile.
195
196        All Makefiles include a customization file which is used to select
197        compiler and host operating system.  The environment variable
198        RTEMS_MAKEFILE_PATH must point to the directory containing this file; eg:
199
200                export RTEMS_MAKEFILE_PATH=/.../pc386/
201
202        All leaf Makefile's also include either 'make/leaf.cfg' (or
203        'make/lib.cfg' for building libraries).  These config files provide
204        default rules and set up the command macros as appropriate.
205
206        All directory Makefiles include 'make/directory.cfg'.  directory.cfg
207        provides all the rules for recursing through sub directories.
208
209        The Makefile templates already perform these include's.
210
211        'make/leaf.cfg' (or directory.cfg) in turn includes:
212
213            a file specifying general purpose rules appropriate for
214                both leaf and directory makefiles.
215                ( make/main.cfg )
216
217            personality modules specified by the customization file for:
218                compiler            ( make/compilers/??.cfg )
219
220
221        generic rules file
222        ------------------
223
224            [ make/main.cfg ]
225            included by leaf.cfg or directory.cfg.
226
227            This file contains some standard rules and variable assignments
228            that all Makefiles need.
229
230            It also includes the FORCEIT: pseudo target.
231
232
233        OS config file for host machine
234        -------------------------------
235
236            [ make/os/OS-NAME.cfg ]
237            included by main.cfg
238
239            Figures out the target architecture and specifies command names
240            for the OS tools including RCS/CVS (but NOT for the compiler tools).
241
242
243        Compiler configuration for the target
244        -------------------------------------
245
246            [ compilers/COMPILER-NAME.cfg ]
247            included by leaf.cfg
248
249            Specifies the names of tools for compiling programs.
250            Names in here should be fully qualified, and NOT depend on $PATH.
251
252            Also specifies compiler flags to be used to generate optimized,
253            debugging and profile versions, as well as rules to compile
254            assembly language and make makefile dependencies.
255
256
257    Configuration Variables
258    -----------------------
259
260        Variables you have to set in the environment or in your Makefile.
261        Note: the RTEMS module files set RTEMS_ROOT and RTEMS_CUSTOM
262        for you.
263
264        Makefile Variables
265        ------------------
266
267            RTEMS_BSP        -- name of your 'bsp' eg: pc386, mvme136
268
269            RTEMS_CPU        -- CPU architecture e.g.: i386, m68k
270
271            RTEMS_CPU_FAMILY -- CPU model e.g.: i486dx, m68020
272
273            RTEMS_ROOT     -- The root of your source tree.
274                              All other file names are derived from this.
275                              [ eg: % setenv RTEMS_ROOT $HOME/work/RTEMS ]
276
277            RTEMS_CUSTOM   -- name of your config files in make/custom
278                              Example:
279                                 $(RTEMS_ROOT)/make/custom/$(RTEMS_BSP).cfg
280
281            The value RTEMS_ROOT is used in the custom
282            files to generate the make(1) variables:
283
284                PROJECT_RELEASE
285                PROJECT_BIN
286                PROJECT_INCLUDE
287                PROJECT_TOOLS
288
289            etc., which are used within the make config files themselves.
290            (The files in make/*.cfg try to avoid use of word RTEMS so
291            they can be more easily shared by other projects)
292
293        Preset variables
294        ----------------
295
296            Aside from command names set by the OS and compiler config files,
297            a number of MAKE variables are automatically set and maintained by
298            the config files.
299
300            PROJECT_RELEASE
301                        -- release/install directory
302                           [ $(PROJECT_ROOT) ]
303
304            PROJECT_BIN
305                        -- directory for installed binaries
306                           [ $(PROJECT_ROOT)/bin ]
307
308            PROJECT_TOOLS
309                        -- directory for build environment commands
310                           [ eg: $(PROJECT_ROOT)/build-tools ]
311
312            ARCH        -- target sub-directory for object code
313                           [ eg: o-optimize or o-debug ]
314
315            VARIANTS    -- full list of all possible values for $(ARCH);
316                           used mainly for 'make clean'
317                           [ eg: "o-optimize o-debug o-profile" ]
318
319            VARIANT_VA  -- Variant name.
320                           Normally "", but for 'make debug' it is "debug",
321                           for 'make profile', "profile, etc.
322
323                           see make/leaf.cfg for more info.
324
325
326        Preset compilation variables
327        ----------------------------
328
329          This is a list of some of the compilation variables.
330          Refer to the compiler config files for the complete list.
331
332            CFLAGS_OPTIMIZE_V   -- value of optimize flag for compiler
333                                   [ eg: -O ]
334
335            CFLAGS_DEBUG_V      -- value of debug flag for compiler
336                                   [ eg: -g ]
337
338            CFLAGS_PROFILE_V    -- compiler profile flags
339                                   [ eg: -pg ]
340
341            CFLAGS_DEBUG_OPTIMIZE_V
342                                -- optimize flag if compiling for debug
343                                     [ eg: "" ]
344
345            CFLAGS_DEBUG
346            CFLAGS_PROFILE
347            CFLAGS_OPTIMIZE     -- current values for each depending
348                                    on make variant.
349
350            LDFLAGS_STATIC_LIBRARIES_V
351                                -- ld option for static libraries
352                                    -Bstatic or -dy (svr4)
353
354            LDFLAGS_SHARED_LIBRARIES_V
355                                -- ld option for dynamic libraries
356                                    -Bdynamic or -dn (svr4)
357
358            Makefile Variables
359            ------------------
360
361                The following variables may be set in a typical Makefile.
362
363                C_PIECES    -- File names of your .c files without '.c' suffix.
364                               [ eg: C_PIECES=main funcs stuff ]
365
366                CC_PIECES   -- ditto, except for .cc files
367
368                S_PIECES    -- ditto, except for .S files.
369
370                LIB         -- target library name in leaf library makefiles.
371                               [ eg: LIB=${ARCH}/libmine.a ]
372
373                H_FILES     -- your .h files in this directory.
374                               [ eg: H_FILES=stuff.h extra.h ]
375
376                DEFINES     -- cc -D items.  Included in CPPFLAGS.
377                               leaf Makefiles.
378                               [ eg: DEFINES += -DUNIX ]
379
380                CPPFLAGS    -- -I include directories.
381                               leaf Makefiles.
382                               [ eg: CPPFLAGS += -I../include ]
383
384                LD_PATHS    -- arguments to -L for ld.
385                               Will be prefixed with '-L' or '-L ' as appropriate
386                               and included in LDFLAGS.
387
388                LDFLAGS     -- -L arguments to ld; more may be ADDed.
389
390                LD_LIBS     -- libraries to be linked in.
391                               [ eg: LDLIBS += ../libfoo/${ARCH}/libfoo.a ]
392
393                XCFLAGS     -- "extra" CFLAGS for special needs.  Pre-pended
394                               to CFLAGS.
395                               Not set or used by Makefiles.
396                               Can be set on command line to pass extra flags
397                               to the compiler.
398
399                XCPPFLAGS   -- ditto for CPPFLAGS
400                               Can be set on command line to pass extra flags
401                               to the preprocessor.
402
403                XCCPPFLAGS  -- same as XCPPFLAGS for C++.
404
405                XCCFLAGS    -- same as XCFLAGS for C++.
406
407                SUBDIRS    -- list of sub directories for make recursion.
408                               directory Makefiles only.
409                               [ eg: SUBDIRS=cpu bsp ]
410
411                CLEAN_ADDITIONS
412                            -- list of files or directories that should
413                               be deleted by 'make clean'
414                               [ eg: CLEAN_ADDITIONS += y.tab.c ]
415
416                               See 'leaf.cfg' for the 'clean:' rule and its
417                               default deletions.
418
419                CLOBBER_ADDITIONS
420                            -- list of files or directories that should
421                               be deleted by 'make clobber'
422                               Since 'make clobber' includes 'make clean',
423                               you don't need to duplicate items in both.
424
425            Command names
426            -------------
427
428                The following commands should only be called
429                as make variables:
430
431                    MAKE,INSTALL,INSTALL_VARIANT,SHELL
432
433                    ECHO,CAT,CP,MV,LN,MKDIR,CHMOD
434
435                    SED
436
437                    CC,CPP,AS,AR,LD,NM,SIZE,RANLIB,MKLIB,
438                    YACC,LEX,LINT,CTAGS,ETAGS
439
440                 In addition, the following commands specifically support
441                 the installation of libraries, executables, header files,
442                 and other things that need to be installed:
443
444                    INSTALL_CHANGE  - install a file only if the source
445                                      file is actually different than
446                                      the installed copy or if there is
447                                      no installed copy.  USAGE:
448
449      usage: install-if-change [ -vmV ] file [ file ... ] dest-directory-or-file
450        -v          -- verbose
451        -V suffix   -- suffix to append to targets (before any . suffix)
452                        eg: -V _g would change 'foo' to 'foo_g' and
453                                               'libfoo.a' to 'libfoo_g.a'
454        -m mode     -- mode for new file(s)
455
456                    INSTALL_VARIANT - installs the built file using the
457                                      proper variant suffix (e.g. _g
458                                      for debug turns libmine.a into libmine_g.a)
459                                      This is implemented as a macro that
460                                      invokes install-if-change with the
461                                      appropriate -V argument setting.
462
463            Special Directory Makefile Targets
464            ----------------------------------
465
466                all_WRAPUP
467                clean_WRAPUP
468                install_WRAPUP
469                clean_WRAPUP
470                clobber_WRAPUP
471                depend_WRAPUP
472                            -- Specify additional commands for recursive
473                               (directory level) targets.
474
475                               This is handy in certain cases where you need
476                               to do bit of work *after* a recursive make.
477
478    make/Templates
479    --------------
480
481        This directory contains Makefile and source file templates that
482        should help in creating or converting makefiles.
483
484        Makefile.leaf
485            Template leaf Makefiles.
486
487        Makefile.lib
488            Template leaf library Makefiles.
489
490        Makefile.dir
491            Template "directory" makefile.
492
493
494   
495
Note: See TracBrowser for help on using the repository browser.