source: rtems/c/src/make/README @ 81e0232

4.104.114.84.95
Last change on this file since 81e0232 was bffb938, checked in by Joel Sherrill <joel.sherrill@…>, on 01/20/98 at 19:30:30

Removed PROJECT_HOME and CONFIG_DIR variables.

  • Property mode set to 100644
File size: 18.8 KB
Line 
1#
2#  $Id$
3#
4
5    make/README
6
7    This file describes the layout and conventions of the make tree used in
8    the RTEMS software project and others.
9    All of these "make" trees are substantially similar; however this
10    file documents the current state of the rtems Makefile tree.
11
12    This make tree was developed originally to simplify porting projects
13    between various os's.  The primary goals are:
14
15        .  simple *and* customizable individual makefiles
16
17        .  use widely available GNU make.  There is no pre-processing or
18            automatic generation of Makefiles.
19
20        .  Same makefiles work on *many* host os's due to portability
21            of GNU make and the host os config files.
22
23        .  Support for different compilers and operating systems
24            on a per-user basis.  Using the same sources (including
25            Makefiles) one developer can develop and test under SVR4,
26            another under 4.x, another under HPUX.
27
28        .  Builtin support for compiling "variants" such as debug,
29            profile, and tcov versions.  These variants can be built
30            recursively.
31
32        .  Control of system dependencies.  "hidden" dependencies on
33            environment variables (such as PATH)
34            have been removed whenever possible.  No matter what your
35            PATH variable is set to, you should get the same thing
36            when you 'make' as everyone else on the project.
37
38    This description attempts to cover all aspects of the Makefile tree.  Most
39    of what is described here is maintained automatically by the configuration
40    files.
41
42    The example makefiles in make/Templates should be used as a starting
43    point for new directories.
44
45    There are 2 main types of Makefile:
46
47        directory and leaf.
48
49    Directory Makefiles
50    -------------------
51
52        A Makefile in a source directory with sub-directories is called a
53        "directory" Makefile.
54
55        Directory Makefile's are simply responsible for acting as "middle-men"
56        and recursing into their sub-directories and propagating the make.
57
58        For example, directory src/bin will contain only a Makefile and
59        sub-directories.  No actual source code will reside in the directory.
60        The following commands:
61
62            $ cd src/bin
63            $ make all
64
65        would descend into all the subdirectories of 'src/bin' and recursively
66        perform a 'make all'.
67
68        A 'make debug' will recurse thru sub-directories as a debug build.
69
70        A template directory Makefile which should work in almost all
71        cases is in make/Templates/Makefile.dir
72
73
74    Leaf Makefiles
75    --------------
76
77        Source directories that contain source code for libraries or
78        programs use a "leaf" Makefile.
79
80        These makefiles contain the rules necessary to build programs
81        (or libraries).
82
83        A template leaf Makefile is in Templates/Makefile.leaf .  A template
84        leaf Makefile for building libraries is in Templates/Makefile.lib .
85
86
87    NOTE: To simplify nested makefile's and source maintenance, we disallow
88    combining source and directories (that make(1) would be expected to
89    recurse into) in one source directory.  Ie., a directory in the source
90    tree may contain EITHER source files OR recursive sub directories, but NOT
91    both.
92
93    Variants (where objects go)
94    ---------------------------
95
96        All binary targets are placed in a sub-directory whose name is (for
97        example):
98
99            o-force386/                -- binaries (no debug, no profile)
100            o-force386-debug/          -- debug binaries
101            o-force386-profile/        -- profiling binaries
102
103        Using the template Makefiles, this will all happen automatically.
104
105        Within a Makefile, the ${ARCH} variable is set to o-force386,
106        o-force386-debug, etc., as appropriate.
107
108        Typing 'make' will place objects in o-force386.
109        'make debug' will place objects in o-force386-debug.
110        'make profile' will place objects in o-force386-profile.
111
112        NOTE:  For RTEMS work, the word 'force386' is the specified
113               RTEMS_BSP (specified in the modules file)
114
115        The debug and profile targets are equivalent to 'all' except that
116        CFLAGS and/or LDFLAGS are modified as per the compiler config file for
117        debug and profile support.
118
119        Targets debug_install and profile_install are equivalent to 'make
120        install' except that debug (or profile) variants are built and
121        installed.
122
123        The targets debug, profile, debug_install, profile_install, etc., can be
124        invoked recursively at the directory make level.  So from the top of a
125        tree, one could install a debug version of everything under that point
126        by:
127
128            $ cd src/lib
129            $ gmake debug_install
130
131        When building a command that is linked with a generated library, the
132        appropriate version of the library will be linked in.
133
134        For example, the following fragments link the normal, debug, or
135        profile version of "libmine.a" as appropriate:
136
137            LDLIBS   += $(LIBMINE)
138            LIBMINE = ../libmine/${ARCH}/libmine.a
139
140            ${ARCH}/pgm: $(LIBMINE) ${OBJS}
141                $(LINK.c) -o $@ ${OBJS} $(LDLIBS)
142
143        If we do 'gmake debug', then the library in
144        ../libmine/sparc-debug/libmine.a will be linked in.  If $(LIBMINE)
145        might not exist (or might be out of date) at this point, we could add
146
147            ${LIBMINE}: FORCEIT
148                cd ../libmine; ${MAKE} ${VARIANT_VA}
149
150        The above would generate the following command to build libmine.a:
151
152            cd ../libmine; gmake debug
153
154        The macro reference ${VARIANT_VA} converts ${ARCH} to the word 'debug'
155        (in this example) and thus ensures the proper version of the library
156        is built.
157
158
159    Targets
160    -------
161
162        All Makefile's support the following targets:
163
164            all                     -- make "everything"
165            install                 -- install "everything"
166
167        The following targets are provided automatically by
168        the included config files:
169
170            clean                   -- delete all targets
171            clobber                 -- 'clean' plus delete sccs'd files
172            lint                    -- run lint or lint-like tool
173            get                     -- "sccs get" all sources
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_CUSTOM must point to this file; eg:
193
194                /.../make/custom/force386.cfg
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                operating system    ( make/os/??.cfg )
214
215
216        private customization files
217        ---------------------------
218
219            [ $(RTEMS_CUSTOM) ]
220
221            Your own private configuration file.  Specifies which of the above
222            files you want to include.
223
224            Example: custom/force386.cfg
225
226               CONFIG.$(HOST_ARCH).OS = $(RTEMS_ROOT)/make/os/HPUX-9.0.cfg
227
228               # HOST Compiler config file
229               # You may also want to specify where the compiler resides here.
230               CC_$(HOST_ARCH)_DIR=/usr/local
231               CONFIG.$(HOST_ARCH).CC   = $(RTEMS_ROOT)/make/compilers/gcc.cfg
232
233               ## Target compiler config file, if any
234               CC_$(TARGET_ARCH)_DIR=$(RTEMS_GNUTOOLS)
235               CONFIG.$(TARGET_ARCH).CC = $(RTEMS_ROOT)/make/compilers/gcc-force386.cfg
236
237        generic rules file
238        ------------------
239
240            [ make/main.cfg ]
241            included by leaf.cfg or directory.cfg.
242
243            This file contains some standard rules and variable assignments
244            that all Makefiles need.
245
246            It also includes the FORCEIT: pseudo target.
247
248
249        OS config file for host machine
250        -------------------------------
251
252            [ make/os/OS-NAME.cfg ]
253            included by main.cfg
254
255            Figures out the target architecture and specifies command names
256            for the OS tools including RCS/CVS (but NOT for the compiler tools).
257
258
259        Compiler configuration for the target
260        -------------------------------------
261
262            [ compilers/COMPILER-NAME.cfg ]
263            included by leaf.cfg
264
265            Specifies the names of tools for compiling programs.
266            Names in here should be fully qualified, and NOT depend on $PATH.
267
268            Also specifies compiler flags to be used to generate optimized,
269            debugging and profile versions, as well as rules to compile
270            assembly language and make makefile dependencies.
271
272
273    Configuration Variables
274    -----------------------
275
276        Variables you have to set in the environment or in your Makefile.
277        Note: the rtems module files set RTEMS_ROOT and RTEMS_CUSTOM
278        for you.
279
280        Environment Variables
281        ---------------------
282
283            RTEMS_BSP      -- name of your 'bsp' eg: force386
284
285            RTEMS_ROOT     -- The root of your source tree.
286                              All other file names are derived from this.
287                              [ eg: % setenv RTEMS_ROOT $HOME/work/rtems ]
288
289            RTEMS_CUSTOM   -- name of your config files in make/custom
290                              Example:
291                                 $(RTEMS_ROOT)/make/custom/$(RTEMS_BSP).cfg
292
293            RTEMS_GNUTOOLS -- root of the gcc tools for the target
294
295            The value RTEMS_ROOT is used in the custom
296            files to generate the make(1) variables:
297
298                PROJECT_ROOT
299                PROJECT_RELEASE
300                PROJECT_TOOLS
301
302            etc., which are used within the make config files themselves.
303            (The files in make/*.cfg try to avoid use of word RTEMS so
304            they can be more easily shared by other projects)
305
306        Preset variables
307        ----------------
308
309            Aside from command names set by the os and compiler config files,
310            a number of MAKE variables are automatically set and maintained by
311            the config files.
312
313            CONFIG.$(HOST_ARCH).OS
314                        -- full path of OS config file, set by
315                           custom config file.
316
317            CONFIG.$(HOST_ARCH).CC
318                        -- full path of C compilation config file, set by custom
319                           config file.
320
321            PROJECT_RELEASE
322                        -- release/install directory
323                           [ $(PROJECT_ROOT) ]
324
325            PROJECT_BIN
326                        -- directory for installed binaries
327                           [ $(PROJECT_ROOT)/bin ]
328
329            PROJECT_TOOLS
330                        -- directory for build environment commands
331                           [ eg: $(PROJECT_ROOT)/build-tools ]
332
333            TARCH       -- ${TARGET_ARCH}
334                           [ eg: o-forc386 ]
335                           obsolete and should not be referenced
336
337            ARCH        -- target sub-directory for object code
338                           [ eg: o-force386 or o-force386-debug ]
339
340            HOST_ARCH
341                        -- host machine architecture name
342                           [ eg: sun4, sparc on SVR4 ]
343
344            VARIANTS    -- full list of all possible values for $(ARCH);
345                           used mainly for 'make clean'
346                           [ eg: "o-force386 o-force386-debug o-force386-profile" ]
347
348            VARIANT_VA  -- Variant name.
349                           Normally "", but for 'make debug' it is "debug",
350                           for 'make profile', "profile, etc.
351
352                           see make/leaf.cfg for more info.
353
354
355        Preset compilation variables
356        ----------------------------
357
358          This is a list of some of the compilation variables.
359          Refer to the compiler config files for the complete list.
360
361            CFLAGS_OPTIMIZE_V   -- value of optimize flag for compiler
362                                   [ eg: -O ]
363
364            CFLAGS_DEBUG_V      -- value of debug flag for compiler
365                                   [ eg: -g ]
366
367            CFLAGS_PROFILE_V    -- compiler profile flags
368                                   [ eg: -pg ]
369
370            CFLAGS_DEBUG_OPTIMIZE_V
371                                -- optimize flag if compiling for debug
372                                     [ eg: "" ]
373
374            CFLAGS_DEBUG
375            CFLAGS_PROFILE
376            CFLAGS_OPTIMIZE     -- current values for each depending
377                                    on make variant.
378
379            LDFLAGS_STATIC_LIBRARIES_V
380                                -- ld option for static libraries
381                                    -Bstatic or -dy (svr4)
382
383            LDFLAGS_SHARED_LIBRARIES_V
384                                -- ld option for dynamic libraries
385                                    -Bdynamic or -dn (svr4)
386
387            LIB_SOCKET
388                                -- ld(1) -l option(s) to provide
389                                    socket support.
390
391            LIB_MATH            -- ld(1) -l option(s) to provide
392                                    math library.
393
394
395            Makefile Variables
396            ------------------
397
398                The following variables may be set in a typical Makefile.
399
400                C_PIECES    -- File names of your .c files without '.c' suffix.
401                               [ eg: C_PIECES=main funcs stuff ]
402
403                CC_PIECES   -- ditto, except for .cc files
404
405                S_PIECES    -- ditto, except for .S files.
406
407                LIB         -- target library name in leaf library makefiles.
408                               [ eg: LIB=${ARCH}/libmine.a ]
409
410                H_FILES     -- your .h files in this directory.
411                               [ eg: H_FILES=stuff.h extra.h ]
412
413                DEFINES     -- cc -D items.  Included in CPPFLAGS.
414                               leaf Makefiles.
415                               [ eg: DEFINES += -DUNIX ]
416
417                CPPFLAGS    -- -I include directories.
418                               leaf Makefiles.
419                               [ eg: CPPFLAGS += -I../include ]
420
421                YFLAGS      -- Yacc flags.
422                               leaf Makefiles.
423                               [ eg: YFLAGS += -v ]
424
425                LD_PATHS    -- arguments to -L for ld.
426                               Will be prefixed with '-L' or '-L ' as appropriate
427                               and included in LDFLAGS.
428
429                LDFLAGS     -- -L arguments to ld; more may be ADDed.
430
431                LD_LIBS     -- libraries to be linked in.
432                               [ eg: LDLIBS += ../libfoo/${ARCH}/libfoo.a ]
433
434                XCFLAGS     -- "extra" CFLAGS for special needs.  Pre-pended
435                               to CFLAGS.
436                               Not set or used by Makefiles.
437                               Can be set on command line to pass extra flags
438                               to the compiler.
439
440                XCPPFLAGS   -- ditto for CPPFLAGS
441                               Can be set on command line to pass extra flags
442                               to the preprocessor.
443
444                XCCPPFLAGS  -- same as XCPPFLAGS for C++.
445
446                XCCFLAGS    -- same as XCFLAGS for C++.
447
448                SUB_DIRS    -- list of sub directories for make recursion.
449                               directory Makefiles only.
450                               [ eg: SUB_DIRS=cpu bsp ]
451
452                CLEAN_ADDITIONS
453                            -- list of files or directories that should
454                               be deleted by 'make clean'
455                               [ eg: CLEAN_ADDITIONS += y.tab.c ]
456
457                               See 'leaf.cfg' for the 'clean:' rule and its
458                               default deletions.
459
460                CLOBBER_ADDITIONS
461                            -- list of files or directories that should
462                               be deleted by 'make clobber'
463                               Since 'make clobber' includes 'make clean',
464                               you don't need to duplicate items in both.
465
466                TARGET_ARCH -- target architecture (eg: o-force386)
467                               leaf makefiles only.
468                               Should be specified before 'include leaf.cfg'.
469                               Only needs to be specified if your target is
470                               different from output of `arch`.
471
472            Command names
473            -------------
474
475                The following commands should only be called
476                as make variables:
477
478                    MAKE,INSTALL,SHELL
479
480                    ECHO,CAT,RM,CP,MV,LN,MKDIR,CHMOD
481
482                    ED,SED
483
484                    CC,CPP,AS,AR,LD,NM,SIZE,RANLIB,MKLIB,
485                    YACC,LEX,LINT,CTAGS,ETAGS
486
487            Special Directory Makefile Targets
488            ----------------------------------
489
490                all_WRAPUP
491                clean_WRAPUP
492                install_WRAPUP
493                clean_WRAPUP
494                clobber_WRAPUP
495                depend_WRAPUP
496                            -- Specify additional commands for recursive
497                               (directory level) targets.
498
499                               This is handy in certain cases where you need
500                               to do bit of work *after* a recursive make.
501
502    make/Templates
503    --------------
504
505        This directory contains Makefile and source file templates that
506        should help in creating or converting makefiles.
507
508        Makefile.leaf
509            Template leaf Makefiles.
510
511        Makefile.lib
512            Template leaf library Makefiles.
513
514        Makefile.dir
515            Template "directory" makefile.
516
517
518
Note: See TracBrowser for help on using the repository browser.