source: rtems/make/README @ 4d20133

4.104.114.84.95
Last change on this file since 4d20133 was 98100d2, checked in by Joel Sherrill <joel.sherrill@…>, on Jun 27, 1998 at 5:09:47 PM

Monstrous patch from Ralf Corsepius <corsepiu@…>. I have
made no attempt to divide the comments up and place them with just
the appropriate files. Here is an excerpt from Ralf's email:

Changes including comments on changes I made after cycling through
all the targets:

  • Added ranlib support. Now all targets use "ranlib" instead of "ar -s" to build an index for a library. If ranlib isn't detected during configuration, check if ar -s is working and try "ar -s" instead of
  • Removed $(XXX_FOR_TARGET) from make/target.cfg.in, use $(XXX) instead now.
  • gcc-target-default.cfg: LINK_XXXX-defines reworked to solve the -l problem under posix (cf gcc-target-default.cfg)
  • rtems-glom replaced by Makefile-rules inside of the wrapup/Makefile.in that has been using rtems-glom until now.
  • Removed CCC and friends in gcc-target-default.cfg, as they have been breaking CXX support.
  • Removed CONFIG.$(TARGET_ARCH).CC lines from several custom/*.cfg files, because this is now set in custom/default.cfg.
  • Added aclocal/ar-s.m4, check whether "ar -s" is working
  • Added aclocal/cygwin.m4 and aclocal/exeext.m4.
  • Reworked aclocal/canonicalize-tools.m4: Added ar -s check; fixes for problems when XXX_FOR_TARGET is given via environment variables (didn't work for gcc until now), adding cygwin check, improved autoconf-cache handling.
  • Removed -l from make rule dependencies. LINK_LIBS is now allowed to contain -L and -l. LINK_OBJS and LINK_FILES must not contain -L or -l. gcc28 make-exe rules now link using $(LINK_OBJS) $(LINK_LIBS) => Almost all custom/*.cfg are modified. This is very likely to break something because of typos or having missed to edit a file.

Open problems, known bugs, things I didn't do:

  • custom/p4000.cfg seems to be out of date and requires to be reviewed.

(JRS NOTE: It is subordinate p4650 and p4600 -- both of which build ok

after minor changes.)

  • custom/psim.cfg needs to be reviewed, I added some changes to it, I am insecure about.

(JRS NOTE: psim had a minor problem endif/endef swapped but runs fine.)

  • rtems-glom.in can now be removed.
  • gcc*.cfg files "make depend" rules don't honor language specific flags (e.g CXXFLAGS is ignored for *.cc) - Nothing to worry about now, but may cause problems for hosts/targets not using gcc or rtems-add-ons that use external packages.
  • AFAIS, the no_bsp BSP can't be build anymore, i.e. configure refused to configure for it whatever I tried.
  • The toplevel and toplevel+1 README files are quite out-dated
  • cygwin.m4 isn't of much use for rtems. In most cases (cf. aclocal/*.m4) it is worked around by directly using $host_os. I think I'll remove it soon after the next snapshot
  • Before release the cygwin patch needs to be tested under cygwin. I may have broken/missed something (esp. the sed-pattern to convert
    into / may be broken).
  • You should try to build/run the posix-BSP under solaris - I don't expect problems, but I am not 100% sure, esp. with regard to ranlib/ar -s.
  • You should consider to convert all make/compilers/*.cfg files into make/compilers/*.cfg.in files and let autoconf generate the *.cfg. This may help getting rid of some if/then/else statements and help hard-coding some defines into those files in future and shouldn't disturb now.
  • Not having installed libc.a/libm.a on a host may still break building rtems, esp. when using -disable-gcc28 as the gcc27-configuration scheme directly accesses libc.a and libm.a. The problem should not appear when using gcc28 because it references libc/libm only through -lc and -lm which may be static or dynamic (I didn't test this).
  • shgen is not yet included (I didn't yet have enough time to integrate it).
  • I know about a few more configure-probs (esp. cross-checking --enable-* flags).

+ warn/refuse to configure when --enable-libcdir and

--enable-gcc28 are given.

+ force --enable-libcdir when --disable-gcc28 is given

  • Replaced KSHELL with @KSH@ in some shell scripts generated by configure.in.
  • Added a dependency to aclocal/*.m4 in the toplevel Makefile => configure and aclocal.m4 will now be rebuild when any aclocal/*.m4 file is changed
  • Some changes to aclocal/gcc-pipe.m4 and aclocal/gcc-specs.m4
  • Replaced i3456?86-unknown-freebsd2.12? with i3456?86-*freebsd2.* in configure.in, as I suppose there might exist a variety of valid vendors (2nd field of the name-tripple)
  • Disabled override MAKEFLAGS in toplevel Makefile.in - Potential side-effects are not really clear to me.
  • In mvme162.cfg, $(LINK_LIBS) is missing in the CC line in gcc28's make-exe rule (yet another one I missed to edit). Just append $(LINK_LIBS) to the "CC" line, like I hopefully did to ALL other custom/*.cfg files.
  • the problem with mvme162lx.cfg is a follow-up problem of the mvme162.cfg-bug.
  • mvme162/console and idp/console had variables named Buffer which conflicted with similarly named variables in some tests.
  • Property mode set to 100644
File size: 18.6 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
214
215        private customization files
216        ---------------------------
217
218            [ $(RTEMS_CUSTOM) ]
219
220            Your own private configuration file.  Specifies which of the above
221            files you want to include.
222
223            Example: custom/force386.cfg
224
225               CONFIG.$(HOST_ARCH).OS = $(RTEMS_ROOT)/make/os/HPUX-9.0.cfg
226
227               # HOST Compiler config file
228               # You may also want to specify where the compiler resides here.
229               CC_$(HOST_ARCH)_DIR=/usr/local
230               CONFIG.$(HOST_ARCH).CC   = $(RTEMS_ROOT)/make/compilers/gcc.cfg
231
232               ## Target compiler config file, if any
233               CC_$(TARGET_ARCH)_DIR=$(RTEMS_GNUTOOLS)
234               CONFIG.$(TARGET_ARCH).CC = $(RTEMS_ROOT)/make/compilers/gcc-force386.cfg
235
236        generic rules file
237        ------------------
238
239            [ make/main.cfg ]
240            included by leaf.cfg or directory.cfg.
241
242            This file contains some standard rules and variable assignments
243            that all Makefiles need.
244
245            It also includes the FORCEIT: pseudo target.
246
247
248        OS config file for host machine
249        -------------------------------
250
251            [ make/os/OS-NAME.cfg ]
252            included by main.cfg
253
254            Figures out the target architecture and specifies command names
255            for the OS tools including RCS/CVS (but NOT for the compiler tools).
256
257
258        Compiler configuration for the target
259        -------------------------------------
260
261            [ compilers/COMPILER-NAME.cfg ]
262            included by leaf.cfg
263
264            Specifies the names of tools for compiling programs.
265            Names in here should be fully qualified, and NOT depend on $PATH.
266
267            Also specifies compiler flags to be used to generate optimized,
268            debugging and profile versions, as well as rules to compile
269            assembly language and make makefile dependencies.
270
271
272    Configuration Variables
273    -----------------------
274
275        Variables you have to set in the environment or in your Makefile.
276        Note: the rtems module files set RTEMS_ROOT and RTEMS_CUSTOM
277        for you.
278
279        Environment Variables
280        ---------------------
281
282            RTEMS_BSP      -- name of your 'bsp' eg: force386
283
284            RTEMS_ROOT     -- The root of your source tree.
285                              All other file names are derived from this.
286                              [ eg: % setenv RTEMS_ROOT $HOME/work/rtems ]
287
288            RTEMS_CUSTOM   -- name of your config files in make/custom
289                              Example:
290                                 $(RTEMS_ROOT)/make/custom/$(RTEMS_BSP).cfg
291
292            RTEMS_GNUTOOLS -- root of the gcc tools for the target
293
294            The value RTEMS_ROOT is used in the custom
295            files to generate the make(1) variables:
296
297                PROJECT_ROOT
298                PROJECT_RELEASE
299                PROJECT_TOOLS
300
301            etc., which are used within the make config files themselves.
302            (The files in make/*.cfg try to avoid use of word RTEMS so
303            they can be more easily shared by other projects)
304
305        Preset variables
306        ----------------
307
308            Aside from command names set by the os and compiler config files,
309            a number of MAKE variables are automatically set and maintained by
310            the config files.
311
312            CONFIG.$(HOST_ARCH).CC
313                        -- full path of C compilation config file, set by custom
314                           config file.
315
316            PROJECT_RELEASE
317                        -- release/install directory
318                           [ $(PROJECT_ROOT) ]
319
320            PROJECT_BIN
321                        -- directory for installed binaries
322                           [ $(PROJECT_ROOT)/bin ]
323
324            PROJECT_TOOLS
325                        -- directory for build environment commands
326                           [ eg: $(PROJECT_ROOT)/build-tools ]
327
328            TARCH       -- ${TARGET_ARCH}
329                           [ eg: o-forc386 ]
330                           obsolete and should not be referenced
331
332            ARCH        -- target sub-directory for object code
333                           [ eg: o-force386 or o-force386-debug ]
334
335            HOST_ARCH
336                        -- host machine architecture name
337                           [ eg: sun4, sparc on SVR4 ]
338
339            VARIANTS    -- full list of all possible values for $(ARCH);
340                           used mainly for 'make clean'
341                           [ eg: "o-force386 o-force386-debug o-force386-profile" ]
342
343            VARIANT_VA  -- Variant name.
344                           Normally "", but for 'make debug' it is "debug",
345                           for 'make profile', "profile, etc.
346
347                           see make/leaf.cfg for more info.
348
349
350        Preset compilation variables
351        ----------------------------
352
353          This is a list of some of the compilation variables.
354          Refer to the compiler config files for the complete list.
355
356            CFLAGS_OPTIMIZE_V   -- value of optimize flag for compiler
357                                   [ eg: -O ]
358
359            CFLAGS_DEBUG_V      -- value of debug flag for compiler
360                                   [ eg: -g ]
361
362            CFLAGS_PROFILE_V    -- compiler profile flags
363                                   [ eg: -pg ]
364
365            CFLAGS_DEBUG_OPTIMIZE_V
366                                -- optimize flag if compiling for debug
367                                     [ eg: "" ]
368
369            CFLAGS_DEBUG
370            CFLAGS_PROFILE
371            CFLAGS_OPTIMIZE     -- current values for each depending
372                                    on make variant.
373
374            LDFLAGS_STATIC_LIBRARIES_V
375                                -- ld option for static libraries
376                                    -Bstatic or -dy (svr4)
377
378            LDFLAGS_SHARED_LIBRARIES_V
379                                -- ld option for dynamic libraries
380                                    -Bdynamic or -dn (svr4)
381
382            LIB_SOCKET
383                                -- ld(1) -l option(s) to provide
384                                    socket support.
385
386            LIB_MATH            -- ld(1) -l option(s) to provide
387                                    math library.
388
389
390            Makefile Variables
391            ------------------
392
393                The following variables may be set in a typical Makefile.
394
395                C_PIECES    -- File names of your .c files without '.c' suffix.
396                               [ eg: C_PIECES=main funcs stuff ]
397
398                CC_PIECES   -- ditto, except for .cc files
399
400                S_PIECES    -- ditto, except for .S files.
401
402                LIB         -- target library name in leaf library makefiles.
403                               [ eg: LIB=${ARCH}/libmine.a ]
404
405                H_FILES     -- your .h files in this directory.
406                               [ eg: H_FILES=stuff.h extra.h ]
407
408                DEFINES     -- cc -D items.  Included in CPPFLAGS.
409                               leaf Makefiles.
410                               [ eg: DEFINES += -DUNIX ]
411
412                CPPFLAGS    -- -I include directories.
413                               leaf Makefiles.
414                               [ eg: CPPFLAGS += -I../include ]
415
416                YFLAGS      -- Yacc flags.
417                               leaf Makefiles.
418                               [ eg: YFLAGS += -v ]
419
420                LD_PATHS    -- arguments to -L for ld.
421                               Will be prefixed with '-L' or '-L ' as appropriate
422                               and included in LDFLAGS.
423
424                LDFLAGS     -- -L arguments to ld; more may be ADDed.
425
426                LD_LIBS     -- libraries to be linked in.
427                               [ eg: LDLIBS += ../libfoo/${ARCH}/libfoo.a ]
428
429                XCFLAGS     -- "extra" CFLAGS for special needs.  Pre-pended
430                               to CFLAGS.
431                               Not set or used by Makefiles.
432                               Can be set on command line to pass extra flags
433                               to the compiler.
434
435                XCPPFLAGS   -- ditto for CPPFLAGS
436                               Can be set on command line to pass extra flags
437                               to the preprocessor.
438
439                XCCPPFLAGS  -- same as XCPPFLAGS for C++.
440
441                XCCFLAGS    -- same as XCFLAGS for C++.
442
443                SUB_DIRS    -- list of sub directories for make recursion.
444                               directory Makefiles only.
445                               [ eg: SUB_DIRS=cpu bsp ]
446
447                CLEAN_ADDITIONS
448                            -- list of files or directories that should
449                               be deleted by 'make clean'
450                               [ eg: CLEAN_ADDITIONS += y.tab.c ]
451
452                               See 'leaf.cfg' for the 'clean:' rule and its
453                               default deletions.
454
455                CLOBBER_ADDITIONS
456                            -- list of files or directories that should
457                               be deleted by 'make clobber'
458                               Since 'make clobber' includes 'make clean',
459                               you don't need to duplicate items in both.
460
461                TARGET_ARCH -- target architecture (eg: o-force386)
462                               leaf makefiles only.
463                               Should be specified before 'include leaf.cfg'.
464                               Only needs to be specified if your target is
465                               different from output of `arch`.
466
467            Command names
468            -------------
469
470                The following commands should only be called
471                as make variables:
472
473                    MAKE,INSTALL,SHELL
474
475                    ECHO,CAT,RM,CP,MV,LN,MKDIR,CHMOD
476
477                    ED,SED
478
479                    CC,CPP,AS,AR,LD,NM,SIZE,RANLIB,MKLIB,
480                    YACC,LEX,LINT,CTAGS,ETAGS
481
482            Special Directory Makefile Targets
483            ----------------------------------
484
485                all_WRAPUP
486                clean_WRAPUP
487                install_WRAPUP
488                clean_WRAPUP
489                clobber_WRAPUP
490                depend_WRAPUP
491                            -- Specify additional commands for recursive
492                               (directory level) targets.
493
494                               This is handy in certain cases where you need
495                               to do bit of work *after* a recursive make.
496
497    make/Templates
498    --------------
499
500        This directory contains Makefile and source file templates that
501        should help in creating or converting makefiles.
502
503        Makefile.leaf
504            Template leaf Makefiles.
505
506        Makefile.lib
507            Template leaf library Makefiles.
508
509        Makefile.dir
510            Template "directory" makefile.
511
512
513
Note: See TracBrowser for help on using the repository browser.