summaryrefslogtreecommitdiffstats
path: root/make/README
blob: 6d4b7501b4a4732fb151754f135903b00393a4c1 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
#
#  $Id$
#

    make/README

    This file describes the layout and conventions of the make tree used in
    the RTEMS software project and others.
    All of these "make" trees are substantially similar; however this
    file documents the current state of the rtems Makefile tree.

    This make tree was developed originally to simplify porting projects
    between various os's.  The primary goals are:

        .  simple *and* customizable individual makefiles

        .  use widely available GNU make.  There is no pre-processing or
            automatic generation of Makefiles.

        .  Same makefiles work on *many* host os's due to portability
            of GNU make and the host os config files.

        .  Support for different compilers and operating systems
            on a per-user basis.  Using the same sources (including
            Makefiles) one developer can develop and test under SVR4,
            another under 4.x, another under HPUX.

        .  Builtin support for compiling "variants" such as debug,
            profile, and tcov versions.  These variants can be built
            recursively.

        .  Control of system dependencies.  "hidden" dependencies on
            environment variables (such as PATH)
            have been removed whenever possible.  No matter what your
            PATH variable is set to, you should get the same thing
            when you 'make' as everyone else on the project.

    This description attempts to cover all aspects of the Makefile tree.  Most
    of what is described here is maintained automatically by the configuration
    files.

    The example makefiles in make/Templates should be used as a starting
    point for new directories.

    There are 2 main types of Makefile:

        directory and leaf.

    Directory Makefiles
    -------------------

        A Makefile in a source directory with sub-directories is called a
        "directory" Makefile.

        Directory Makefile's are simply responsible for acting as "middle-men"
        and recursing into their sub-directories and propagating the make.

        For example, directory src/bin will contain only a Makefile and
        sub-directories.  No actual source code will reside in the directory.
        The following commands:

            $ cd src/bin
            $ make all

        would descend into all the subdirectories of 'src/bin' and recursively
        perform a 'make all'.

        A 'make debug' will recurse thru sub-directories as a debug build.

        A template directory Makefile which should work in almost all
        cases is in make/Templates/Makefile.dir


    Leaf Makefiles
    --------------

        Source directories that contain source code for libraries or
        programs use a "leaf" Makefile.

        These makefiles contain the rules necessary to build programs
        (or libraries).

        A template leaf Makefile is in Templates/Makefile.leaf .  A template
        leaf Makefile for building libraries is in Templates/Makefile.lib .


    NOTE: To simplify nested makefile's and source maintenance, we disallow
    combining source and directories (that make(1) would be expected to
    recurse into) in one source directory.  Ie., a directory in the source
    tree may contain EITHER source files OR recursive sub directories, but NOT
    both.

    Variants (where objects go)
    ---------------------------

        All binary targets are placed in a sub-directory whose name is (for
        example):

            o-force386/                -- binaries (no debug, no profile)
            o-force386-debug/          -- debug binaries
            o-force386-profile/        -- profiling binaries

        Using the template Makefiles, this will all happen automatically.

        Within a Makefile, the ${ARCH} variable is set to o-force386,
        o-force386-debug, etc., as appropriate.

        Typing 'make' will place objects in o-force386.
        'make debug' will place objects in o-force386-debug.
        'make profile' will place objects in o-force386-profile.

        NOTE:  For RTEMS work, the word 'force386' is the specified
               RTEMS_BSP (specified in the modules file)

        The debug and profile targets are equivalent to 'all' except that
        CFLAGS and/or LDFLAGS are modified as per the compiler config file for
        debug and profile support.

        Targets debug_install and profile_install are equivalent to 'make
        install' except that debug (or profile) variants are built and
        installed.

        The targets debug, profile, debug_install, profile_install, etc., can be
        invoked recursively at the directory make level.  So from the top of a
        tree, one could install a debug version of everything under that point
        by:

            $ cd src/lib
            $ gmake debug_install

        When building a command that is linked with a generated library, the
        appropriate version of the library will be linked in.

        For example, the following fragments link the normal, debug, or
        profile version of "libmine.a" as appropriate:

            LDLIBS   += $(LIBMINE)
            LIBMINE = ../libmine/${ARCH}/libmine.a

            ${ARCH}/pgm: $(LIBMINE) ${OBJS}
                $(LINK.c) -o $@ ${OBJS} $(LDLIBS)

        If we do 'gmake debug', then the library in
        ../libmine/sparc-debug/libmine.a will be linked in.  If $(LIBMINE)
        might not exist (or might be out of date) at this point, we could add

            ${LIBMINE}: FORCEIT
	        cd ../libmine; ${MAKE} ${VARIANT_VA}

        The above would generate the following command to build libmine.a:

            cd ../libmine; gmake debug

        The macro reference ${VARIANT_VA} converts ${ARCH} to the word 'debug'
        (in this example) and thus ensures the proper version of the library
        is built.


    Targets
    -------

        All Makefile's support the following targets:

            all                     -- make "everything"
            install                 -- install "everything"

        The following targets are provided automatically by
        the included config files:

            clean                   -- delete all targets
            clobber                 -- 'clean' plus delete sccs'd files
            lint                    -- run lint or lint-like tool
            get                     -- "sccs get" all sources
            depend                  -- build a make dependency file
            "variant targets"       -- special variants, see below


        All directory Makefiles automatically propagate all these targets.  If
        you don't wish to support 'all' or 'install' in your source directory,
        you must leave the rules section empty, as the parent directory Makefile
        will attempt it on recursive make's.


    Configuration
    -------------

        All the real work described here happens in file(s) included
        from your Makefile.

        All Makefiles include a customization file which is used to select
        compiler and host operating system.  The environment variable
        RTEMS_CUSTOM must point to this file; eg:

                /.../make/custom/force386.cfg

        All leaf Makefile's also include either 'make/leaf.cfg' (or
        'make/lib.cfg' for building libraries).  These config files provide
        default rules and set up the command macros as appropriate.

        All directory Makefiles include 'make/directory.cfg'.  directory.cfg
        provides all the rules for recursing through sub directories.

        The Makefile templates already perform these include's.

        'make/leaf.cfg' (or directory.cfg) in turn includes:

            a file specifying general purpose rules appropriate for
                both leaf and directory makefiles.
                ( make/main.cfg )

            personality modules specified by the customization file for:
                compiler            ( make/compilers/??.cfg )
                operating system    ( make/os/??.cfg )


        private customization files
        ---------------------------

            [ $(RTEMS_CUSTOM) ]

            Your own private configuration file.  Specifies which of the above
            files you want to include.

            Example: custom/force386.cfg

               CONFIG.$(HOST_ARCH).OS = $(RTEMS_ROOT)/make/os/HPUX-9.0.cfg

               # HOST Compiler config file
               # You may also want to specify where the compiler resides here.
               CC_$(HOST_ARCH)_DIR=/usr/local
               CONFIG.$(HOST_ARCH).CC   = $(RTEMS_ROOT)/make/compilers/gcc.cfg

               ## Target compiler config file, if any
               CC_$(TARGET_ARCH)_DIR=$(RTEMS_GNUTOOLS)
               CONFIG.$(TARGET_ARCH).CC = $(RTEMS_ROOT)/make/compilers/gcc-force386.cfg

        generic rules file
        ------------------

            [ make/main.cfg ]
            included by leaf.cfg or directory.cfg.

            This file contains some standard rules and variable assignments
            that all Makefiles need.

            It also includes the FORCEIT: pseudo target.


        OS config file for host machine
        -------------------------------

            [ make/os/OS-NAME.cfg ]
            included by main.cfg

            Figures out the target architecture and specifies command names
            for the OS tools including RCS/CVS (but NOT for the compiler tools).


        Compiler configuration for the target
        -------------------------------------

            [ compilers/COMPILER-NAME.cfg ]
            included by leaf.cfg

            Specifies the names of tools for compiling programs.
            Names in here should be fully qualified, and NOT depend on $PATH.

            Also specifies compiler flags to be used to generate optimized,
            debugging and profile versions, as well as rules to compile
            assembly language and make makefile dependencies.


    Configuration Variables
    -----------------------

        Variables you have to set in the environment or in your Makefile.
        Note: the rtems module files set RTEMS_ROOT and RTEMS_CUSTOM
        for you.

        Environment Variables
        ---------------------

            RTEMS_BSP      -- name of your 'bsp' eg: force386

            RTEMS_ROOT     -- The root of your source tree.
                              All other file names are derived from this.
                              [ eg: % setenv RTEMS_ROOT $HOME/work/rtems ]

            RTEMS_CUSTOM   -- name of your config files in make/custom
                              Example:
                                 $(RTEMS_ROOT)/make/custom/$(RTEMS_BSP).cfg

            RTEMS_GNUTOOLS -- root of the gcc tools for the target

            The value RTEMS_ROOT is used in the custom
            files to generate the make(1) variables:

                PROJECT_ROOT
                PROJECT_RELEASE
                PROJECT_TOOLS

            etc., which are used within the make config files themselves.
            (The files in make/*.cfg try to avoid use of word RTEMS so
            they can be more easily shared by other projects)

        Preset variables
        ----------------

            Aside from command names set by the os and compiler config files,
            a number of MAKE variables are automatically set and maintained by
            the config files.

            CONFIG.$(HOST_ARCH).OS
                        -- full path of OS config file, set by
                           custom config file.

            CONFIG.$(HOST_ARCH).CC
                        -- full path of C compilation config file, set by custom
                           config file.

            PROJECT_RELEASE
                        -- release/install directory
                           [ $(PROJECT_ROOT) ]

            PROJECT_BIN
                        -- directory for installed binaries
                           [ $(PROJECT_ROOT)/bin ]

            PROJECT_TOOLS
                        -- directory for build environment commands
                           [ eg: $(PROJECT_ROOT)/build-tools ]

            TARCH       -- ${TARGET_ARCH}
                           [ eg: o-forc386 ]
                           obsolete and should not be referenced

            ARCH        -- target sub-directory for object code
                           [ eg: o-force386 or o-force386-debug ]

            HOST_ARCH
                        -- host machine architecture name
                           [ eg: sun4, sparc on SVR4 ]

            VARIANTS    -- full list of all possible values for $(ARCH);
                           used mainly for 'make clean'
                           [ eg: "o-force386 o-force386-debug o-force386-profile" ]

            VARIANT_VA  -- Variant name.
                           Normally "", but for 'make debug' it is "debug",
                           for 'make profile', "profile, etc.

                           see make/leaf.cfg for more info.


        Preset compilation variables
        ----------------------------

          This is a list of some of the compilation variables.
          Refer to the compiler config files for the complete list.

            CFLAGS_OPTIMIZE_V   -- value of optimize flag for compiler
                                   [ eg: -O ]

            CFLAGS_DEBUG_V      -- value of debug flag for compiler
                                   [ eg: -g ]

            CFLAGS_PROFILE_V    -- compiler profile flags
                                   [ eg: -pg ]

            CFLAGS_DEBUG_OPTIMIZE_V
                                -- optimize flag if compiling for debug
                                     [ eg: "" ]

            CFLAGS_DEBUG
            CFLAGS_PROFILE
            CFLAGS_OPTIMIZE     -- current values for each depending
                                    on make variant.

            LDFLAGS_STATIC_LIBRARIES_V
                                -- ld option for static libraries
                                    -Bstatic or -dy (svr4)

            LDFLAGS_SHARED_LIBRARIES_V
                                -- ld option for dynamic libraries
                                    -Bdynamic or -dn (svr4)

            LIB_SOCKET
                                -- ld(1) -l option(s) to provide
                                    socket support.

            LIB_MATH            -- ld(1) -l option(s) to provide
                                    math library.


            Makefile Variables
            ------------------

                The following variables may be set in a typical Makefile.

                C_PIECES    -- File names of your .c files without '.c' suffix.
                               [ eg: C_PIECES=main funcs stuff ]

                CC_PIECES   -- ditto, except for .cc files

                S_PIECES    -- ditto, except for .S files.

                LIB         -- target library name in leaf library makefiles.
                               [ eg: LIB=${ARCH}/libmine.a ]

                H_FILES     -- your .h files in this directory.
                               [ eg: H_FILES=stuff.h extra.h ]

                DEFINES     -- cc -D items.  Included in CPPFLAGS.
                               leaf Makefiles.
                               [ eg: DEFINES += -DUNIX ]

                CPPFLAGS    -- -I include directories.
                               leaf Makefiles.
                               [ eg: CPPFLAGS += -I../include ]

                YFLAGS      -- Yacc flags.
                               leaf Makefiles.
                               [ eg: YFLAGS += -v ]

                LD_PATHS    -- arguments to -L for ld.
                               Will be prefixed with '-L' or '-L ' as appropriate
                               and included in LDFLAGS.

                LDFLAGS     -- -L arguments to ld; more may be ADDed.

                LD_LIBS     -- libraries to be linked in.
                               [ eg: LDLIBS += ../libfoo/${ARCH}/libfoo.a ]

                XCFLAGS     -- "extra" CFLAGS for special needs.  Pre-pended
                               to CFLAGS.
                               Not set or used by Makefiles.
                               Can be set on command line to pass extra flags
                               to the compiler.

                XCPPFLAGS   -- ditto for CPPFLAGS
                               Can be set on command line to pass extra flags
                               to the preprocessor.

                XCCPPFLAGS  -- same as XCPPFLAGS for C++.

                XCCFLAGS    -- same as XCFLAGS for C++.

                SUB_DIRS    -- list of sub directories for make recursion.
                               directory Makefiles only.
                               [ eg: SUB_DIRS=cpu bsp ]

                CLEAN_ADDITIONS
                            -- list of files or directories that should
                               be deleted by 'make clean'
                               [ eg: CLEAN_ADDITIONS += y.tab.c ]

                               See 'leaf.cfg' for the 'clean:' rule and its
                               default deletions.

                CLOBBER_ADDITIONS
                            -- list of files or directories that should
                               be deleted by 'make clobber'
                               Since 'make clobber' includes 'make clean',
                               you don't need to duplicate items in both.

                TARGET_ARCH -- target architecture (eg: o-force386)
                               leaf makefiles only.
                               Should be specified before 'include leaf.cfg'.
                               Only needs to be specified if your target is
                               different from output of `arch`.

            Command names
            -------------

                The following commands should only be called
                as make variables:

                    MAKE,INSTALL,SHELL

                    ECHO,CAT,RM,CP,MV,LN,MKDIR,CHMOD

                    ED,SED

                    CC,CPP,AS,AR,LD,NM,SIZE,RANLIB,MKLIB,
                    YACC,LEX,LINT,CTAGS,ETAGS

            Special Directory Makefile Targets
            ----------------------------------

                all_WRAPUP
                clean_WRAPUP
                install_WRAPUP
                clean_WRAPUP
                clobber_WRAPUP
                depend_WRAPUP
                            -- Specify additional commands for recursive
                               (directory level) targets.

                               This is handy in certain cases where you need
                               to do bit of work *after* a recursive make.

    make/Templates
    --------------

        This directory contains Makefile and source file templates that
        should help in creating or converting makefiles.

        Makefile.leaf
            Template leaf Makefiles.

        Makefile.lib
            Template leaf library Makefiles.

        Makefile.dir
            Template "directory" makefile.