Warning, /make/README.md is written in an unsupported language. File is not indexed.
0001 Make
0002 ====
0003 This file describes the layout and conventions of the application
0004 makefile support for RTEMS applications. Internally, RTEMS uses
0005 GNU-style autoconf/automake Makefiles as much as possible to
0006 ease integration with other GNU tools.
0007
0008 All of these "make" trees are substantially similar; however this
0009 file documents the current state of the RTEMS Application Makefile
0010 support.
0011
0012 This make tree is based on a build system originally developed
0013 to simplify porting projects between various OS's. The primary
0014 goals were:
0015
0016 . simple *and* customizable individual makefiles
0017
0018 . use widely available GNU make. There is no pre-processing or
0019 automatic generation of Makefiles.
0020
0021 . Same makefiles work on *many* host OS's due to portability
0022 of GNU make and the host OS config files.
0023
0024 . Support for different compilers and operating systems
0025 on a per-user basis. Using the same sources (including
0026 Makefiles) one developer can develop and test under SVR4,
0027 another under 4.x, another under HPUX.
0028
0029 . Builtin support for compiling "variants" such as debug
0030 versions. These variants can be built
0031 recursively.
0032
0033 . Control of system dependencies. "hidden" dependencies on
0034 environment variables (such as PATH)
0035 have been removed whenever possible. No matter what your
0036 PATH variable is set to, you should get the same thing
0037 when you 'make' as everyone else on the project.
0038
0039 This Makefile system has evolved into its present form and as it
0040 exists in RTEMS today, its sole goal is to build RTEMS applications.
0041 The use of these Makefiles hides the complexity of producing
0042 executables for a wide variety of embedded CPU families and target
0043 BSPs. Switching between RTEMS BSPs is accomplished via setting
0044 the environment variable "RTEMS_MAKEFILE_PATH."
0045
0046 This description attempts to cover all aspects of the Makefile tree. Most
0047 of what is described here is maintained automatically by the configuration
0048 files.
0049
0050 The example makefiles in make/Templates should be used as a starting
0051 point for new directories.
0052
0053 There are 2 main types of Makefile:
0054
0055 directory and leaf.
0056
0057
0058 Directory Makefiles
0059 -------------------
0060
0061 A Makefile in a source directory with sub-directories is called a
0062 "directory" Makefile.
0063
0064 Directory Makefile's are simply responsible for acting as "middle-men"
0065 and recursing into their sub-directories and propagating the make.
0066
0067 For example, directory src/bin will contain only a Makefile and
0068 sub-directories. No actual source code will reside in the directory.
0069 The following commands:
0070
0071 ```shell
0072 $ cd src/bin
0073 $ make all
0074 ```
0075
0076 would descend into all the subdirectories of 'src/bin' and recursively
0077 perform a 'make all'.
0078
0079 A 'make debug' will recurse thru sub-directories as a debug build.
0080
0081 A template directory Makefile which should work in almost all
0082 cases is in make/Templates/Makefile.dir
0083
0084
0085 Leaf Makefiles
0086 --------------
0087
0088 Source directories that contain source code for libraries or
0089 programs use a "leaf" Makefile.
0090
0091 These makefiles contain the rules necessary to build programs
0092 (or libraries).
0093
0094 A template leaf Makefile is in Templates/Makefile.leaf . A template
0095 leaf Makefile for building libraries is in Templates/Makefile.lib .
0096
0097
0098 NOTE: To simplify nested makefile's and source maintenance, we disallow
0099 combining source and directories (that make(1) would be expected to
0100 recurse into) in one source directory. Ie., a directory in the source
0101 tree may contain EITHER source files OR recursive sub directories, but NOT
0102 both. This assumption is generally shared with GNU automake.
0103
0104 Variants (where objects go)
0105 ---------------------------
0106
0107 All binary targets are placed in a sub-directory whose name is (for
0108 example):
0109
0110 o-optimize/ -- optimized binaries
0111 o-debug/ -- debug binaries
0112
0113 Using the template Makefiles, this will all happen automatically.
0114 The contents of these directories are specific to a BSP.
0115
0116 Within a Makefile, the ${ARCH} variable is set to o-optimize,
0117 o-debug, etc., as appropriate.
0118
0119 HISTORICAL NOTE: Prior to version 4.5, the name of the sub-directory
0120 in which objects were placed included the BSP name.
0121
0122 Typing 'make' will place objects in o-optimize.
0123 'make debug' will place objects in o-debug.
0124
0125 The debug targets are equivalent to 'all' except that
0126 CFLAGS and/or LDFLAGS are modified as per the compiler config file for
0127 debug and profile support.
0128
0129 The targets debug etc., can be invoked recursively at
0130 the directory make level. So from the top of a tree, one could
0131 install a debug version of everything under that point by:
0132
0133 ```shell
0134 $ cd src/lib
0135 $ gmake debug
0136 $ gmake install
0137 ```
0138
0139 When building a command that is linked with a generated library, the
0140 appropriate version of the library will be linked in.
0141
0142 For example, the following fragments link the normal, debug, or
0143 version of "libmine.a" as appropriate:
0144
0145 ```shell
0146 LD_LIBS += $(LIBMINE)
0147 LIBMINE = ../libmine/${ARCH}/libmine.a
0148
0149 ${ARCH}/pgm: $(LIBMINE) ${OBJS}
0150 $(make-exe)
0151 ```
0152
0153 If we do 'gmake debug', then the library in
0154 ../libmine/o-debug/libmine.a will be linked in. If $(LIBMINE)
0155 might not exist (or might be out of date) at this point, we could add
0156
0157 ```shell
0158 ${LIBMINE}: FORCEIT
0159 cd ../libmine; ${MAKE} ${VARIANT_VA}
0160 ```
0161
0162 The above would generate the following command to build libmine.a:
0163
0164 ```shell
0165 cd ../libmine; gmake debug
0166 ```
0167
0168 The macro reference ${VARIANT_VA} converts ${ARCH} to the word 'debug'
0169 (in this example) and thus ensures the proper version of the library
0170 is built.
0171
0172
0173 Targets
0174 -------
0175
0176 All Makefile's support the following targets:
0177
0178 all -- make "everything"
0179 install -- install "everything"
0180
0181 The following targets are provided automatically by
0182 the included config files:
0183
0184 clean -- delete all targets
0185 depend -- build a make dependency file
0186 "variant targets" -- special variants, see below
0187
0188
0189 All directory Makefiles automatically propagate all these targets. If
0190 you don't wish to support 'all' or 'install' in your source directory,
0191 you must leave the rules section empty, as the parent directory Makefile
0192 will attempt it on recursive make's.
0193
0194
0195 Configuration
0196 -------------
0197
0198 All the real work described here happens in file(s) included
0199 from your Makefile.
0200
0201 All Makefiles include a customization file which is used to select
0202 compiler and host operating system. The environment variable
0203 RTEMS_MAKEFILE_PATH must point to the directory containing this file; eg:
0204
0205 export RTEMS_MAKEFILE_PATH=/.../pc386/
0206
0207 All leaf Makefile's also include either 'make/leaf.cfg' (or
0208 'make/lib.cfg' for building libraries). These config files provide
0209 default rules and set up the command macros as appropriate.
0210
0211 All directory Makefiles include 'make/directory.cfg'. directory.cfg
0212 provides all the rules for recursing through sub directories.
0213
0214 The Makefile templates already perform these include's.
0215
0216 'make/leaf.cfg' (or directory.cfg) in turn includes:
0217
0218 a file specifying general purpose rules appropriate for
0219 both leaf and directory makefiles.
0220 ( make/main.cfg )
0221
0222 personality modules specified by the customization file for:
0223 compiler ( make/compilers/??.cfg )
0224
0225
0226 generic rules file
0227 ------------------
0228
0229 [ make/main.cfg ]
0230 included by leaf.cfg or directory.cfg.
0231
0232 This file contains some standard rules and variable assignments
0233 that all Makefiles need.
0234
0235 It also includes the FORCEIT: pseudo target.
0236
0237
0238 OS config file for host machine
0239 -------------------------------
0240
0241 [ make/os/OS-NAME.cfg ]
0242 included by main.cfg
0243
0244 Figures out the target architecture and specifies command names
0245 for the OS tools including RCS/CVS (but NOT for the compiler tools).
0246
0247
0248 Compiler configuration for the target
0249 -------------------------------------
0250
0251 [ compilers/COMPILER-NAME.cfg ]
0252 included by leaf.cfg
0253
0254 Specifies the names of tools for compiling programs.
0255 Names in here should be fully qualified, and NOT depend on $PATH.
0256
0257 Also specifies compiler flags to be used to generate optimized,
0258 debugging versions, as well as rules to compile
0259 assembly language and make makefile dependencies.
0260
0261
0262 Configuration Variables
0263 -----------------------
0264
0265 Variables you have to set in the environment or in your Makefile.
0266 Note: the RTEMS module files set RTEMS_ROOT and RTEMS_CUSTOM
0267 for you.
0268
0269 Makefile Variables
0270 ------------------
0271
0272 RTEMS_BSP -- name of your 'bsp' eg: pc386, mvme136
0273
0274 RTEMS_CPU -- CPU architecture e.g.: i386, m68k
0275
0276 RTEMS_CPU_FAMILY -- CPU model e.g.: i486dx, m68020
0277
0278 RTEMS_ROOT -- The root of your source tree.
0279 All other file names are derived from this.
0280 [ eg: % setenv RTEMS_ROOT $HOME/work/RTEMS ]
0281
0282 RTEMS_CUSTOM -- name of your config files in make/custom
0283 Example:
0284 $(RTEMS_ROOT)/make/custom/$(RTEMS_BSP).cfg
0285
0286 The value RTEMS_ROOT is used in the custom
0287 files to generate the make(1) variables:
0288
0289 PROJECT_RELEASE
0290 PROJECT_BIN
0291 PROJECT_INCLUDE
0292 PROJECT_TOOLS
0293
0294 etc., which are used within the make config files themselves.
0295 (The files in make/*.cfg try to avoid use of word RTEMS so
0296 they can be more easily shared by other projects)
0297
0298 Preset variables
0299 ----------------
0300
0301 Aside from command names set by the OS and compiler config files,
0302 a number of MAKE variables are automatically set and maintained by
0303 the config files.
0304
0305
0306 PROJECT_RELEASE
0307 -- release/install directory
0308 [ $(PROJECT_ROOT) ]
0309
0310 PROJECT_BIN
0311 -- directory for installed binaries
0312 [ $(PROJECT_ROOT)/bin ]
0313
0314 PROJECT_TOOLS
0315 -- directory for build environment commands
0316 [ eg: $(PROJECT_ROOT)/build-tools ]
0317
0318 ARCH -- target sub-directory for object code
0319 [ eg: o-optimize or o-debug ]
0320
0321 VARIANTS -- full list of all possible values for $(ARCH);
0322 used mainly for 'make clean'
0323 [ eg: "o-optimize o-debug" ]
0324
0325 VARIANT_VA -- Variant name.
0326 Normally "", but for 'make debug' it is "debug".
0327
0328 see make/leaf.cfg for more info.
0329 ```
0330
0331 Preset compilation variables
0332 ----------------------------
0333 This is a list of some of the compilation variables.
0334 Refer to the compiler config files for the complete list.
0335
0336 ```
0337 CFLAGS_OPTIMIZE_V -- value of optimize flag for compiler
0338 [ eg: -O ]
0339
0340 CFLAGS_DEBUG_V -- value of debug flag for compiler
0341 [ eg: -g ]
0342
0343 CFLAGS_DEBUG
0344 CFLAGS_OPTIMIZE -- current values for each depending
0345 on make variant.
0346
0347 LDFLAGS_STATIC_LIBRARIES_V
0348 -- ld option for static libraries
0349 -Bstatic or -dy (svr4)
0350
0351 LDFLAGS_SHARED_LIBRARIES_V
0352 -- ld option for dynamic libraries
0353 -Bdynamic or -dn (svr4)
0354
0355 Makefile Variables
0356 ------------------
0357
0358 The following variables may be set in a typical Makefile.
0359
0360 C_PIECES -- File names of your .c files without '.c' suffix.
0361 [ eg: C_PIECES=main funcs stuff ]
0362
0363 CC_PIECES -- ditto, except for .cc files
0364
0365 S_PIECES -- ditto, except for .S files.
0366
0367 LIB -- target library name in leaf library makefiles.
0368 [ eg: LIB=${ARCH}/libmine.a ]
0369
0370 H_FILES -- your .h files in this directory.
0371 [ eg: H_FILES=stuff.h extra.h ]
0372
0373 DEFINES -- cc -D items. Included in CPPFLAGS.
0374 leaf Makefiles.
0375 [ eg: DEFINES += -DUNIX ]
0376
0377 CPPFLAGS -- -I include directories.
0378 leaf Makefiles.
0379 [ eg: CPPFLAGS += -I../include ]
0380
0381 LD_PATHS -- arguments to -L for ld.
0382 Will be prefixed with '-L' or '-L ' as appropriate
0383 and included in LDFLAGS.
0384
0385 LDFLAGS -- -L arguments to ld; more may be ADDed.
0386
0387 LD_LIBS -- libraries to be linked in.
0388 [ eg: LDLIBS += ../libfoo/${ARCH}/libfoo.a ]
0389
0390 XCFLAGS -- "extra" CFLAGS for special needs. Pre-pended
0391 to CFLAGS.
0392 Not set or used by Makefiles.
0393 Can be set on command line to pass extra flags
0394 to the compiler.
0395
0396 XCPPFLAGS -- ditto for CPPFLAGS
0397 Can be set on command line to pass extra flags
0398 to the preprocessor.
0399
0400 XCCPPFLAGS -- same as XCPPFLAGS for C++.
0401
0402 XCCFLAGS -- same as XCFLAGS for C++.
0403
0404 SUBDIRS -- list of sub directories for make recursion.
0405 directory Makefiles only.
0406 [ eg: SUBDIRS=cpu bsp ]
0407
0408 CLEAN_ADDITIONS
0409 -- list of files or directories that should
0410 be deleted by 'make clean'
0411 [ eg: CLEAN_ADDITIONS += y.tab.c ]
0412
0413 See 'leaf.cfg' for the 'clean:' rule and its
0414 default deletions.
0415
0416 CLOBBER_ADDITIONS
0417 -- list of files or directories that should
0418 be deleted by 'make clobber'
0419 Since 'make clobber' includes 'make clean',
0420 you don't need to duplicate items in both.
0421 ```
0422
0423 Command names
0424 -------------
0425
0426 The following commands should only be called
0427 as make variables:
0428
0429 MAKE,INSTALL,INSTALL_VARIANT,SHELL
0430
0431 ECHO,CAT,CP,MV,LN,MKDIR,CHMOD
0432
0433 SED
0434
0435 CC,CPP,AS,AR,LD,NM,SIZE,RANLIB,MKLIB,
0436 YACC,LEX,LINT,CTAGS,ETAGS
0437
0438 In addition, the following commands specifically support
0439 the installation of libraries, executables, header files,
0440 and other things that need to be installed:
0441
0442 INSTALL_CHANGE - set to host "install" program by default
0443
0444 INSTALL_VARIANT - set to host "install" program by default
0445
0446
0447 Special Directory Makefile Targets
0448 ----------------------------------
0449
0450 all_WRAPUP
0451 clean_WRAPUP
0452 install_WRAPUP
0453 clean_WRAPUP
0454 clobber_WRAPUP
0455 depend_WRAPUP
0456 -- Specify additional commands for recursive
0457 (directory level) targets.
0458
0459 This is handy in certain cases where you need
0460 to do bit of work *after* a recursive make.
0461
0462 make/Templates
0463 --------------
0464
0465 This directory contains Makefile and source file templates that
0466 should help in creating or converting makefiles.
0467
0468 Makefile.leaf
0469 Template leaf Makefiles.
0470
0471 Makefile.lib
0472 Template leaf library Makefiles.
0473
0474 Makefile.dir
0475 Template "directory" makefile.
0476
0477
0478
0479
