OpenCores
URL https://opencores.org/ocsvn/openrisc/openrisc/trunk

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [rtos/] [rtems/] [make/] [README] - Blame information for rev 173

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 30 unneback
#
2
#  $Id: README,v 1.2 2001-09-27 12:02:50 chris Exp $
3
#
4
 
5
    make/README
6
 
7
    This file describes the layout and conventions of the application
8
    makefile support for RTEMS applications.  Internally, RTEMS uses
9
    GNU-style autoconf/automake Makefiles as much as possible to
10
    ease integration with other GNU tools.
11
 
12
    All of these "make" trees are substantially similar; however this
13
    file documents the current state of the RTEMS Application Makefile
14
    support.
15
 
16
    This make tree is based on a build system originally developed
17
    to simplify porting projects between various OS's.  The primary
18
    goals were:
19
 
20
        .  simple *and* customizable individual makefiles
21
 
22
        .  use widely available GNU make.  There is no pre-processing or
23
            automatic generation of Makefiles.
24
 
25
        .  Same makefiles work on *many* host OS's due to portability
26
            of GNU make and the host OS config files.
27
 
28
        .  Support for different compilers and operating systems
29
            on a per-user basis.  Using the same sources (including
30
            Makefiles) one developer can develop and test under SVR4,
31
            another under 4.x, another under HPUX.
32
 
33
        .  Builtin support for compiling "variants" such as debug,
34
            profile, and tcov versions.  These variants can be built
35
            recursively.
36
 
37
        .  Control of system dependencies.  "hidden" dependencies on
38
            environment variables (such as PATH)
39
            have been removed whenever possible.  No matter what your
40
            PATH variable is set to, you should get the same thing
41
            when you 'make' as everyone else on the project.
42
 
43
    This Makefile system has evolved into its present form and as it
44
    exists in RTEMS today, its sole goal is to build RTEMS applications.
45
    The use of these Makefiles hides the complexity of producing
46
    executables for a wide variety of embedded CPU families and target
47
    BSPs.  Switching between RTEMS BSPs is accomplished via setting
48
    the environment variable "RTEMS_MAKEFILE_PATH."
49
 
50
    This description attempts to cover all aspects of the Makefile tree.  Most
51
    of what is described here is maintained automatically by the configuration
52
    files.
53
 
54
    The example makefiles in make/Templates should be used as a starting
55
    point for new directories.
56
 
57
    There are 2 main types of Makefile:
58
 
59
        directory and leaf.
60
 
61
    Directory Makefiles
62
    -------------------
63
 
64
        A Makefile in a source directory with sub-directories is called a
65
        "directory" Makefile.
66
 
67
        Directory Makefile's are simply responsible for acting as "middle-men"
68
        and recursing into their sub-directories and propagating the make.
69
 
70
        For example, directory src/bin will contain only a Makefile and
71
        sub-directories.  No actual source code will reside in the directory.
72
        The following commands:
73
 
74
            $ cd src/bin
75
            $ make all
76
 
77
        would descend into all the subdirectories of 'src/bin' and recursively
78
        perform a 'make all'.
79
 
80
        A 'make debug' will recurse thru sub-directories as a debug build.
81
 
82
        A template directory Makefile which should work in almost all
83
        cases is in make/Templates/Makefile.dir
84
 
85
 
86
    Leaf Makefiles
87
    --------------
88
 
89
        Source directories that contain source code for libraries or
90
        programs use a "leaf" Makefile.
91
 
92
        These makefiles contain the rules necessary to build programs
93
        (or libraries).
94
 
95
        A template leaf Makefile is in Templates/Makefile.leaf .  A template
96
        leaf Makefile for building libraries is in Templates/Makefile.lib .
97
 
98
 
99
    NOTE: To simplify nested makefile's and source maintenance, we disallow
100
    combining source and directories (that make(1) would be expected to
101
    recurse into) in one source directory.  Ie., a directory in the source
102
    tree may contain EITHER source files OR recursive sub directories, but NOT
103
    both.  This assumption is generally shared with GNU automake.
104
 
105
    Variants (where objects go)
106
    ---------------------------
107
 
108
        All binary targets are placed in a sub-directory whose name is (for
109
        example):
110
 
111
            o-optimize/       -- optimized binaries
112
            o-debug/          -- debug binaries
113
            o-profile/        -- profiling binaries
114
 
115
        Using the template Makefiles, this will all happen automatically.
116
        The contents of these directories are specific to a BSP.
117
 
118
        Within a Makefile, the ${ARCH} variable is set to o-optimize,
119
        o-debug, etc., as appropriate.
120
 
121
        HISTORICAL NOTE: Prior to version 4.5, the name of the sub-directory
122
          in which objects were placed included the BSP name.
123
 
124
        Typing 'make' will place objects in o-optimize.
125
        'make debug' will place objects in o-debug.
126
        'make profile' will place objects in o-profile.
127
 
128
        The debug and profile targets are equivalent to 'all' except that
129
        CFLAGS and/or LDFLAGS are modified as per the compiler config file for
130
        debug and profile support.
131
 
132
        The targets debug, profile, etc., can be invoked recursively at
133
        the directory make level.  So from the top of a tree, one could
134
        install a debug version of everything under that point by:
135
 
136
            $ cd src/lib
137
            $ gmake debug
138
            $ gmake install
139
 
140
        When building a command that is linked with a generated library, the
141
        appropriate version of the library will be linked in.
142
 
143
        For example, the following fragments link the normal, debug, or
144
        profile version of "libmine.a" as appropriate:
145
 
146
            LD_LIBS   += $(LIBMINE)
147
            LIBMINE = ../libmine/${ARCH}/libmine.a
148
 
149
            ${ARCH}/pgm: $(LIBMINE) ${OBJS}
150
                $(make-exe)
151
 
152
        If we do 'gmake debug', then the library in
153
        ../libmine/o-debug/libmine.a will be linked in.  If $(LIBMINE)
154
        might not exist (or might be out of date) at this point, we could add
155
 
156
            ${LIBMINE}: FORCEIT
157
                cd ../libmine; ${MAKE} ${VARIANT_VA}
158
 
159
        The above would generate the following command to build libmine.a:
160
 
161
            cd ../libmine; gmake debug
162
 
163
        The macro reference ${VARIANT_VA} converts ${ARCH} to the word 'debug'
164
        (in this example) and thus ensures the proper version of the library
165
        is built.
166
 
167
 
168
    Targets
169
    -------
170
 
171
        All Makefile's support the following targets:
172
 
173
            all                     -- make "everything"
174
            install                 -- install "everything"
175
 
176
        The following targets are provided automatically by
177
        the included config files:
178
 
179
            clean                   -- delete all targets
180
            depend                  -- build a make dependency file
181
            "variant targets"       -- special variants, see below
182
 
183
 
184
        All directory Makefiles automatically propagate all these targets.  If
185
        you don't wish to support 'all' or 'install' in your source directory,
186
        you must leave the rules section empty, as the parent directory Makefile
187
        will attempt it on recursive make's.
188
 
189
 
190
    Configuration
191
    -------------
192
 
193
        All the real work described here happens in file(s) included
194
        from your Makefile.
195
 
196
        All Makefiles include a customization file which is used to select
197
        compiler and host operating system.  The environment variable
198
        RTEMS_MAKEFILE_PATH must point to the directory containing this file; eg:
199
 
200
                export RTEMS_MAKEFILE_PATH=/.../pc386/
201
 
202
        All leaf Makefile's also include either 'make/leaf.cfg' (or
203
        'make/lib.cfg' for building libraries).  These config files provide
204
        default rules and set up the command macros as appropriate.
205
 
206
        All directory Makefiles include 'make/directory.cfg'.  directory.cfg
207
        provides all the rules for recursing through sub directories.
208
 
209
        The Makefile templates already perform these include's.
210
 
211
        'make/leaf.cfg' (or directory.cfg) in turn includes:
212
 
213
            a file specifying general purpose rules appropriate for
214
                both leaf and directory makefiles.
215
                ( make/main.cfg )
216
 
217
            personality modules specified by the customization file for:
218
                compiler            ( make/compilers/??.cfg )
219
 
220
 
221
        generic rules file
222
        ------------------
223
 
224
            [ make/main.cfg ]
225
            included by leaf.cfg or directory.cfg.
226
 
227
            This file contains some standard rules and variable assignments
228
            that all Makefiles need.
229
 
230
            It also includes the FORCEIT: pseudo target.
231
 
232
 
233
        OS config file for host machine
234
        -------------------------------
235
 
236
            [ make/os/OS-NAME.cfg ]
237
            included by main.cfg
238
 
239
            Figures out the target architecture and specifies command names
240
            for the OS tools including RCS/CVS (but NOT for the compiler tools).
241
 
242
 
243
        Compiler configuration for the target
244
        -------------------------------------
245
 
246
            [ compilers/COMPILER-NAME.cfg ]
247
            included by leaf.cfg
248
 
249
            Specifies the names of tools for compiling programs.
250
            Names in here should be fully qualified, and NOT depend on $PATH.
251
 
252
            Also specifies compiler flags to be used to generate optimized,
253
            debugging and profile versions, as well as rules to compile
254
            assembly language and make makefile dependencies.
255
 
256
 
257
    Configuration Variables
258
    -----------------------
259
 
260
        Variables you have to set in the environment or in your Makefile.
261
        Note: the RTEMS module files set RTEMS_ROOT and RTEMS_CUSTOM
262
        for you.
263
 
264
        Makefile Variables
265
        ------------------
266
 
267
            RTEMS_BSP        -- name of your 'bsp' eg: pc386, mvme136
268
 
269
            RTEMS_CPU        -- CPU architecture e.g.: i386, m68k
270
 
271
            RTEMS_CPU_FAMILY -- CPU model e.g.: i486dx, m68020
272
 
273
            RTEMS_ROOT     -- The root of your source tree.
274
                              All other file names are derived from this.
275
                              [ eg: % setenv RTEMS_ROOT $HOME/work/RTEMS ]
276
 
277
            RTEMS_CUSTOM   -- name of your config files in make/custom
278
                              Example:
279
                                 $(RTEMS_ROOT)/make/custom/$(RTEMS_BSP).cfg
280
 
281
            The value RTEMS_ROOT is used in the custom
282
            files to generate the make(1) variables:
283
 
284
                PROJECT_RELEASE
285
                PROJECT_BIN
286
                PROJECT_INCLUDE
287
                PROJECT_TOOLS
288
 
289
            etc., which are used within the make config files themselves.
290
            (The files in make/*.cfg try to avoid use of word RTEMS so
291
            they can be more easily shared by other projects)
292
 
293
        Preset variables
294
        ----------------
295
 
296
            Aside from command names set by the OS and compiler config files,
297
            a number of MAKE variables are automatically set and maintained by
298
            the config files.
299
 
300
            PROJECT_RELEASE
301
                        -- release/install directory
302
                           [ $(PROJECT_ROOT) ]
303
 
304
            PROJECT_BIN
305
                        -- directory for installed binaries
306
                           [ $(PROJECT_ROOT)/bin ]
307
 
308
            PROJECT_TOOLS
309
                        -- directory for build environment commands
310
                           [ eg: $(PROJECT_ROOT)/build-tools ]
311
 
312
            ARCH        -- target sub-directory for object code
313
                           [ eg: o-optimize or o-debug ]
314
 
315
            VARIANTS    -- full list of all possible values for $(ARCH);
316
                           used mainly for 'make clean'
317
                           [ eg: "o-optimize o-debug o-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
            Makefile Variables
359
            ------------------
360
 
361
                The following variables may be set in a typical Makefile.
362
 
363
                C_PIECES    -- File names of your .c files without '.c' suffix.
364
                               [ eg: C_PIECES=main funcs stuff ]
365
 
366
                CC_PIECES   -- ditto, except for .cc files
367
 
368
                S_PIECES    -- ditto, except for .S files.
369
 
370
                LIB         -- target library name in leaf library makefiles.
371
                               [ eg: LIB=${ARCH}/libmine.a ]
372
 
373
                H_FILES     -- your .h files in this directory.
374
                               [ eg: H_FILES=stuff.h extra.h ]
375
 
376
                DEFINES     -- cc -D items.  Included in CPPFLAGS.
377
                               leaf Makefiles.
378
                               [ eg: DEFINES += -DUNIX ]
379
 
380
                CPPFLAGS    -- -I include directories.
381
                               leaf Makefiles.
382
                               [ eg: CPPFLAGS += -I../include ]
383
 
384
                LD_PATHS    -- arguments to -L for ld.
385
                               Will be prefixed with '-L' or '-L ' as appropriate
386
                               and included in LDFLAGS.
387
 
388
                LDFLAGS     -- -L arguments to ld; more may be ADDed.
389
 
390
                LD_LIBS     -- libraries to be linked in.
391
                               [ eg: LDLIBS += ../libfoo/${ARCH}/libfoo.a ]
392
 
393
                XCFLAGS     -- "extra" CFLAGS for special needs.  Pre-pended
394
                               to CFLAGS.
395
                               Not set or used by Makefiles.
396
                               Can be set on command line to pass extra flags
397
                               to the compiler.
398
 
399
                XCPPFLAGS   -- ditto for CPPFLAGS
400
                               Can be set on command line to pass extra flags
401
                               to the preprocessor.
402
 
403
                XCCPPFLAGS  -- same as XCPPFLAGS for C++.
404
 
405
                XCCFLAGS    -- same as XCFLAGS for C++.
406
 
407
                SUBDIRS    -- list of sub directories for make recursion.
408
                               directory Makefiles only.
409
                               [ eg: SUBDIRS=cpu bsp ]
410
 
411
                CLEAN_ADDITIONS
412
                            -- list of files or directories that should
413
                               be deleted by 'make clean'
414
                               [ eg: CLEAN_ADDITIONS += y.tab.c ]
415
 
416
                               See 'leaf.cfg' for the 'clean:' rule and its
417
                               default deletions.
418
 
419
                CLOBBER_ADDITIONS
420
                            -- list of files or directories that should
421
                               be deleted by 'make clobber'
422
                               Since 'make clobber' includes 'make clean',
423
                               you don't need to duplicate items in both.
424
 
425
            Command names
426
            -------------
427
 
428
                The following commands should only be called
429
                as make variables:
430
 
431
                    MAKE,INSTALL,INSTALL_VARIANT,SHELL
432
 
433
                    ECHO,CAT,CP,MV,LN,MKDIR,CHMOD
434
 
435
                    SED
436
 
437
                    CC,CPP,AS,AR,LD,NM,SIZE,RANLIB,MKLIB,
438
                    YACC,LEX,LINT,CTAGS,ETAGS
439
 
440
                 In addition, the following commands specifically support
441
                 the installation of libraries, executables, header files,
442
                 and other things that need to be installed:
443
 
444
                    INSTALL_CHANGE  - install a file only if the source
445
                                      file is actually different than
446
                                      the installed copy or if there is
447
                                      no installed copy.  USAGE:
448
 
449
      usage: install-if-change [ -vmV ] file [ file ... ] dest-directory-or-file
450
        -v          -- verbose
451
        -V suffix   -- suffix to append to targets (before any . suffix)
452
                        eg: -V _g would change 'foo' to 'foo_g' and
453
                                               'libfoo.a' to 'libfoo_g.a'
454
        -m mode     -- mode for new file(s)
455
 
456
                    INSTALL_VARIANT - installs the built file using the
457
                                      proper variant suffix (e.g. _g
458
                                      for debug turns libmine.a into libmine_g.a)
459
                                      This is implemented as a macro that
460
                                      invokes install-if-change with the
461
                                      appropriate -V argument setting.
462
 
463
            Special Directory Makefile Targets
464
            ----------------------------------
465
 
466
                all_WRAPUP
467
                clean_WRAPUP
468
                install_WRAPUP
469
                clean_WRAPUP
470
                clobber_WRAPUP
471
                depend_WRAPUP
472
                            -- Specify additional commands for recursive
473
                               (directory level) targets.
474
 
475
                               This is handy in certain cases where you need
476
                               to do bit of work *after* a recursive make.
477
 
478
    make/Templates
479
    --------------
480
 
481
        This directory contains Makefile and source file templates that
482
        should help in creating or converting makefiles.
483
 
484
        Makefile.leaf
485
            Template leaf Makefiles.
486
 
487
        Makefile.lib
488
            Template leaf library Makefiles.
489
 
490
        Makefile.dir
491
            Template "directory" makefile.
492
 
493
 
494
 
495
 

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.