source: rtems/c/src/make/README @ 5ff9547a

Last change on this file since 5ff9547a was 5ff9547a, checked in by Sebastian Huber <sebastian.huber@…>, on Jun 15, 2018 at 5:53:42 AM

make: Remove CFLAGS_DEBUG_OPTIMIZE_V

Do not document CFLAGS_DEBUG_OPTIMIZE_V, since this flag is not used.

  • Property mode set to 100644
File size: 17.7 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
332            CFLAGS_OPTIMIZE     -- current values for each depending
333                                    on make variant.
334
335            LDFLAGS_STATIC_LIBRARIES_V
336                                -- ld option for static libraries
337                                    -Bstatic or -dy (svr4)
338
339            LDFLAGS_SHARED_LIBRARIES_V
340                                -- ld option for dynamic libraries
341                                    -Bdynamic or -dn (svr4)
342
343            Makefile Variables
344            ------------------
345
346                The following variables may be set in a typical Makefile.
347
348                C_PIECES    -- File names of your .c files without '.c' suffix.
349                               [ eg: C_PIECES=main funcs stuff ]
350
351                CC_PIECES   -- ditto, except for .cc files
352
353                S_PIECES    -- ditto, except for .S files.
354
355                LIB         -- target library name in leaf library makefiles.
356                               [ eg: LIB=${ARCH}/libmine.a ]
357
358                H_FILES     -- your .h files in this directory.
359                               [ eg: H_FILES=stuff.h extra.h ]
360
361                DEFINES     -- cc -D items.  Included in CPPFLAGS.
362                               leaf Makefiles.
363                               [ eg: DEFINES += -DUNIX ]
364
365                CPPFLAGS    -- -I include directories.
366                               leaf Makefiles.
367                               [ eg: CPPFLAGS += -I../include ]
368
369                LD_PATHS    -- arguments to -L for ld.
370                               Will be prefixed with '-L' or '-L ' as appropriate
371                               and included in LDFLAGS.
372
373                LDFLAGS     -- -L arguments to ld; more may be ADDed.
374
375                LD_LIBS     -- libraries to be linked in.
376                               [ eg: LDLIBS += ../libfoo/${ARCH}/libfoo.a ]
377
378                XCFLAGS     -- "extra" CFLAGS for special needs.  Pre-pended
379                               to CFLAGS.
380                               Not set or used by Makefiles.
381                               Can be set on command line to pass extra flags
382                               to the compiler.
383
384                XCPPFLAGS   -- ditto for CPPFLAGS
385                               Can be set on command line to pass extra flags
386                               to the preprocessor.
387
388                XCCPPFLAGS  -- same as XCPPFLAGS for C++.
389
390                XCCFLAGS    -- same as XCFLAGS for C++.
391
392                SUBDIRS    -- list of sub directories for make recursion.
393                               directory Makefiles only.
394                               [ eg: SUBDIRS=cpu bsp ]
395
396                CLEAN_ADDITIONS
397                            -- list of files or directories that should
398                               be deleted by 'make clean'
399                               [ eg: CLEAN_ADDITIONS += y.tab.c ]
400
401                               See 'leaf.cfg' for the 'clean:' rule and its
402                               default deletions.
403
404                CLOBBER_ADDITIONS
405                            -- list of files or directories that should
406                               be deleted by 'make clobber'
407                               Since 'make clobber' includes 'make clean',
408                               you don't need to duplicate items in both.
409
410            Command names
411            -------------
412
413                The following commands should only be called
414                as make variables:
415
416                    MAKE,INSTALL,INSTALL_VARIANT,SHELL
417
418                    ECHO,CAT,CP,MV,LN,MKDIR,CHMOD
419
420                    SED
421
422                    CC,CPP,AS,AR,LD,NM,SIZE,RANLIB,MKLIB,
423                    YACC,LEX,LINT,CTAGS,ETAGS
424
425                 In addition, the following commands specifically support
426                 the installation of libraries, executables, header files,
427                 and other things that need to be installed:
428
429                    INSTALL_CHANGE  - install a file only if the source
430                                      file is actually different than
431                                      the installed copy or if there is
432                                      no installed copy.  USAGE:
433
434      usage: install-if-change [ -vmV ] file [ file ... ] dest-directory-or-file
435        -v          -- verbose
436        -V suffix   -- suffix to append to targets (before any . suffix)
437                        eg: -V _g would change 'foo' to 'foo_g' and
438                                               'libfoo.a' to 'libfoo_g.a'
439        -m mode     -- mode for new file(s)
440
441                    INSTALL_VARIANT - installs the built file using the
442                                      proper variant suffix (e.g. _g
443                                      for debug turns libmine.a into libmine_g.a)
444                                      This is implemented as a macro that
445                                      invokes install-if-change with the
446                                      appropriate -V argument setting.
447
448            Special Directory Makefile Targets
449            ----------------------------------
450
451                all_WRAPUP
452                clean_WRAPUP
453                install_WRAPUP
454                clean_WRAPUP
455                clobber_WRAPUP
456                depend_WRAPUP
457                            -- Specify additional commands for recursive
458                               (directory level) targets.
459
460                               This is handy in certain cases where you need
461                               to do bit of work *after* a recursive make.
462
463    make/Templates
464    --------------
465
466        This directory contains Makefile and source file templates that
467        should help in creating or converting makefiles.
468
469        Makefile.leaf
470            Template leaf Makefiles.
471
472        Makefile.lib
473            Template leaf library Makefiles.
474
475        Makefile.dir
476            Template "directory" makefile.
477
478
479   
480
Note: See TracBrowser for help on using the repository browser.