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

4.104.114.84.9
Last change on this file since 9608320 was 9608320, checked in by Joel Sherrill <joel.sherrill@…>, on Nov 22, 1999 at 1:41:11 PM

Patch rtems-rc-19991117-4.diff from Ralf Corsepius <corsepiu@…>:

.. a major configuration cleanup
... major enhancement of automake support.

... and it contains a *major* breakthough:

Automake support for libchip and libmisc *LEAF* directories.

To implement this I have used several nasty tricks

  • The basical trick is to wrap an old Makefile.in's contents into a Makefile.am and still continue to use (i.e include) the old *.cfg files.
  • Replaced each INSTALL_IF_CHANGE and INSTALL_VARIANT with make dependencies
  • Add a gnu-make ifdef AUTOMAKE to main.cfg to avoid conflicts between automake and RTEMS make rules
  • Replaced each install:: and preinstall:: rule with make dependencies
  • Replaced SUB_DIRS with SUBDIRS in all Makefile.ins (Automake convention)
  • Removed each manually added autoconf substitution which automake performs automatically.

This is not yet full automake support, because using the temporary
installation directory, preinstallation in general and building variants
are in contradiction to automake's basic working principles ...

... the new Makefile.ams work still somewhat clumsy
... nevertheless they work (quite well).

WARNING:

At first glance this patch is small, but

  • it affects the whole configuration system.
  • it opens the road to introducing automake to all Makefile.ins currently not being under automake control.

JOEL> Does this remove or add any files?

Both, all Makefile.ins below libchip and libmisc get replaced with
Makefile.ams.

  • Property mode set to 100644
File size: 17.5 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        generic rules file
221        ------------------
222
223            [ make/main.cfg ]
224            included by leaf.cfg or directory.cfg.
225
226            This file contains some standard rules and variable assignments
227            that all Makefiles need.
228
229            It also includes the FORCEIT: pseudo target.
230
231
232        OS config file for host machine
233        -------------------------------
234
235            [ make/os/OS-NAME.cfg ]
236            included by main.cfg
237
238            Figures out the target architecture and specifies command names
239            for the OS tools including RCS/CVS (but NOT for the compiler tools).
240
241
242        Compiler configuration for the target
243        -------------------------------------
244
245            [ compilers/COMPILER-NAME.cfg ]
246            included by leaf.cfg
247
248            Specifies the names of tools for compiling programs.
249            Names in here should be fully qualified, and NOT depend on $PATH.
250
251            Also specifies compiler flags to be used to generate optimized,
252            debugging and profile versions, as well as rules to compile
253            assembly language and make makefile dependencies.
254
255
256    Configuration Variables
257    -----------------------
258
259        Variables you have to set in the environment or in your Makefile.
260        Note: the rtems module files set RTEMS_ROOT and RTEMS_CUSTOM
261        for you.
262
263        Environment Variables
264        ---------------------
265
266            RTEMS_BSP      -- name of your 'bsp' eg: pc386
267
268            RTEMS_ROOT     -- The root of your source tree.
269                              All other file names are derived from this.
270                              [ eg: % setenv RTEMS_ROOT $HOME/work/rtems ]
271
272            RTEMS_CUSTOM   -- name of your config files in make/custom
273                              Example:
274                                 $(RTEMS_ROOT)/make/custom/$(RTEMS_BSP).cfg
275
276            RTEMS_GNUTOOLS -- root of the gcc tools for the target
277
278            The value RTEMS_ROOT is used in the custom
279            files to generate the make(1) variables:
280
281                PROJECT_ROOT
282                PROJECT_RELEASE
283                PROJECT_TOOLS
284
285            etc., which are used within the make config files themselves.
286            (The files in make/*.cfg try to avoid use of word RTEMS so
287            they can be more easily shared by other projects)
288
289        Preset variables
290        ----------------
291
292            Aside from command names set by the os and compiler config files,
293            a number of MAKE variables are automatically set and maintained by
294            the config files.
295
296            PROJECT_RELEASE
297                        -- release/install directory
298                           [ $(PROJECT_ROOT) ]
299
300            PROJECT_BIN
301                        -- directory for installed binaries
302                           [ $(PROJECT_ROOT)/bin ]
303
304            PROJECT_TOOLS
305                        -- directory for build environment commands
306                           [ eg: $(PROJECT_ROOT)/build-tools ]
307
308            TARCH       -- ${TARGET_ARCH}
309                           [ eg: o-forc386 ]
310                           obsolete and should not be referenced
311
312            ARCH        -- target sub-directory for object code
313                           [ eg: o-pc386 or o-pc386-debug ]
314
315            VARIANTS    -- full list of all possible values for $(ARCH);
316                           used mainly for 'make clean'
317                           [ eg: "o-pc386 o-pc386-debug o-pc386-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            LIB_SOCKET
359                                -- ld(1) -l option(s) to provide
360                                    socket support.
361
362            LIB_MATH            -- ld(1) -l option(s) to provide
363                                    math library.
364
365
366            Makefile Variables
367            ------------------
368
369                The following variables may be set in a typical Makefile.
370
371                C_PIECES    -- File names of your .c files without '.c' suffix.
372                               [ eg: C_PIECES=main funcs stuff ]
373
374                CC_PIECES   -- ditto, except for .cc files
375
376                S_PIECES    -- ditto, except for .S files.
377
378                LIB         -- target library name in leaf library makefiles.
379                               [ eg: LIB=${ARCH}/libmine.a ]
380
381                H_FILES     -- your .h files in this directory.
382                               [ eg: H_FILES=stuff.h extra.h ]
383
384                DEFINES     -- cc -D items.  Included in CPPFLAGS.
385                               leaf Makefiles.
386                               [ eg: DEFINES += -DUNIX ]
387
388                CPPFLAGS    -- -I include directories.
389                               leaf Makefiles.
390                               [ eg: CPPFLAGS += -I../include ]
391
392                YFLAGS      -- Yacc flags.
393                               leaf Makefiles.
394                               [ eg: YFLAGS += -v ]
395
396                LD_PATHS    -- arguments to -L for ld.
397                               Will be prefixed with '-L' or '-L ' as appropriate
398                               and included in LDFLAGS.
399
400                LDFLAGS     -- -L arguments to ld; more may be ADDed.
401
402                LD_LIBS     -- libraries to be linked in.
403                               [ eg: LDLIBS += ../libfoo/${ARCH}/libfoo.a ]
404
405                XCFLAGS     -- "extra" CFLAGS for special needs.  Pre-pended
406                               to CFLAGS.
407                               Not set or used by Makefiles.
408                               Can be set on command line to pass extra flags
409                               to the compiler.
410
411                XCPPFLAGS   -- ditto for CPPFLAGS
412                               Can be set on command line to pass extra flags
413                               to the preprocessor.
414
415                XCCPPFLAGS  -- same as XCPPFLAGS for C++.
416
417                XCCFLAGS    -- same as XCFLAGS for C++.
418
419                SUBDIRS    -- list of sub directories for make recursion.
420                               directory Makefiles only.
421                               [ eg: SUBDIRS=cpu bsp ]
422
423                CLEAN_ADDITIONS
424                            -- list of files or directories that should
425                               be deleted by 'make clean'
426                               [ eg: CLEAN_ADDITIONS += y.tab.c ]
427
428                               See 'leaf.cfg' for the 'clean:' rule and its
429                               default deletions.
430
431                CLOBBER_ADDITIONS
432                            -- list of files or directories that should
433                               be deleted by 'make clobber'
434                               Since 'make clobber' includes 'make clean',
435                               you don't need to duplicate items in both.
436
437                TARGET_ARCH -- target architecture (eg: o-pc386)
438                               leaf makefiles only.
439                               Should be specified before 'include leaf.cfg'.
440                               Only needs to be specified if your target is
441                               different from output of `arch`.
442
443            Command names
444            -------------
445
446                The following commands should only be called
447                as make variables:
448
449                    MAKE,INSTALL,SHELL
450
451                    ECHO,CAT,RM,CP,MV,LN,MKDIR,CHMOD
452
453                    ED,SED
454
455                    CC,CPP,AS,AR,LD,NM,SIZE,RANLIB,MKLIB,
456                    YACC,LEX,LINT,CTAGS,ETAGS
457
458            Special Directory Makefile Targets
459            ----------------------------------
460
461                all_WRAPUP
462                clean_WRAPUP
463                install_WRAPUP
464                clean_WRAPUP
465                clobber_WRAPUP
466                depend_WRAPUP
467                            -- Specify additional commands for recursive
468                               (directory level) targets.
469
470                               This is handy in certain cases where you need
471                               to do bit of work *after* a recursive make.
472
473    make/Templates
474    --------------
475
476        This directory contains Makefile and source file templates that
477        should help in creating or converting makefiles.
478
479        Makefile.leaf
480            Template leaf Makefiles.
481
482        Makefile.lib
483            Template leaf library Makefiles.
484
485        Makefile.dir
486            Template "directory" makefile.
487
488
489
Note: See TracBrowser for help on using the repository browser.