source: rtems/c/src/make/README @ 977623b

4.104.114.84.9
Last change on this file since 977623b was 977623b, checked in by Joel Sherrill <joel.sherrill@…>, on Oct 5, 1999 at 6:39:56 PM

Removed targets and configurations that are no longer functional
and not likely to become so. Comments on each configuration
are below.

+ Force CPU386 - This BSP was developed as part of the initial

port of RTEMS to the i386. This board has been unavailable
for a long time now.

+ GO32 - This BSP and some CPU code supported djgpp v1.x. This

version is now quite old. No one has stepped forward to
update the code to v2.x which may be technically impossible
anyway. More importantly, go32 has been superceded by the pc386 BSP.

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