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 | |
---|