Changes between Initial Version and Version 1 of Developer/Makefile


Ignore:
Timestamp:
01/12/16 10:56:05 (7 years ago)
Author:
Tan Gemicioglu
Comment:

Merged TBR/Delete/Makefile and TBR/Delete/Makefile.am and reformatted page.

Legend:

Unmodified
Added
Removed
Modified
  • Developer/Makefile

    v1 v1  
     1= Makefile =
     2
     3
     4Excerpted from
     5/opt/rtems-4.11/share/rtems-4.11/make/README
     6
     7This file describes the layout and conventions of the application
     8makefile support for RTEMS applications.  Internally, RTEMS uses
     9GNU-style autoconf/automake Makefiles as much as possible to
     10ease integration with other GNU tools.
     11
     12All of these "make" trees are substantially similar; however this
     13file documents the current state of the RTEMS Application Makefile
     14support.
     15This Makefile system has evolved into its present form and as it
     16exists in RTEMS today, its sole goal is to build RTEMS applications.
     17The use of these Makefiles hides the complexity of producing
     18executables for a wide variety of embedded CPU families and target
     19BSPs.  Switching between RTEMS BSPs is accomplished via setting
     20the environment variable "RTEMS_MAKEFILE_PATH."
     21==  Historical Goals  ==
     22
     23This make tree is based on a build system originally developed
     24to simplify porting projects between various OS's.  The primary
     25goals were:
     26
     27 *  simple ''and'' customizable individual makefiles
     28 *  use widely available GNU make.  There is no pre-processing or automatic generation of Makefiles.
     29 *  Same makefiles work on ''many'' host OS's due to portability of GNU make and the host OS config files.
     30 *  Support for different compilers and operating systemson a per-user basis.  Using the same sources (including Makefiles) one developer can develop and test under SVR4, another under 4.x, another under HPUX.
     31 *  Builtin support for compiling "variants" such as debug versions.  These variants can be built recursively.
     32 *  Control of system dependencies. 
     33  *  "hidden" dependencies on environment variables (such as PATH) have been removed whenever possible.
     34  *  No matter what your PATH variable is set to, you should get the same thing when you 'make' as everyone else on the project.
     35==  Description  ==
     36
     37
     38This description covers aspects of the Makefile tree.  Most of what is described here is maintained automatically by the configuration files.
     39
     40The example makefiles in make/Templates should be used as a starting point for new directories.
     41==  Types of Makefiles  ==
     42
     43There are 2 main types of Makefile:
     44directory and leaf.
     45===  Directory Makefiles  ===
     46
     47A Makefile in a source directory with sub-directories is called a
     48"directory" Makefile.
     49
     50Directory Makefile's are simply responsible for acting as "middle-men"
     51and recursing into their sub-directories and propagating the make.
     52
     53For example, directory src/bin will contain only a Makefile and
     54sub-directories.  No actual source code will reside in the directory.
     55The following commands:
     56
     57            $ cd src/bin
     58            $ make all
     59
     60would descend into all the subdirectories of 'src/bin' and recursively
     61perform a 'make all'.
     62
     63A 'make debug' will recurse thru sub-directories as a debug build.
     64
     65A template directory Makefile which should work in almost all
     66cases is in make/Templates/Makefile.dir
     67
     68===  Leaf Makefiles  ===
     69
     70
     71Source directories that contain source code for libraries or
     72programs use a "leaf" Makefile.
     73
     74These makefiles contain the rules necessary to build programs
     75(or libraries).
     76
     77A template leaf Makefile is in Templates/Makefile.leaf .  A template
     78leaf Makefile for building libraries is in Templates/Makefile.lib .
     79
     80
     81'''NOTE:''' To simplify nested makefile's and source maintenance, we disallow
     82combining source and directories (that make(1) would be expected to
     83recurse into) in one source directory.  Ie., a directory in the source
     84tree may contain EITHER source files OR recursive sub directories, but NOT
     85both.  This assumption is generally shared with GNU automake.
     86=  Variants (where objects go)  =
     87
     88All binary targets are placed in a sub-directory whose name is (for
     89example):
     90
     91            o-optimize/       -- optimized binaries
     92            o-debug/          -- debug binaries
     93
     94Using the template Makefiles, this will all happen automatically.
     95The contents of these directories are specific to a BSP.
     96
     97Within a Makefile, the ${ARCH} variable is set to o-optimize,
     98o-debug, etc., as appropriate.
     99
     100''HISTORICAL NOTE:'' Prior to version 4.5, the name of the sub-directory
     101in which objects were placed included the BSP name.
     102=  Invoking make and make debug  =           
     103Typing 'make' will place objects in o-optimize.
     104'make debug' will place objects in o-debug.
     105
     106The debug targets are equivalent to 'all' except that
     107CFLAGS and/or LDFLAGS are modified as per the compiler config file for
     108debug and profile support.
     109
     110The targets debug etc., can be invoked recursively at
     111the directory make level.  So from the top of a tree, one could
     112install a debug version of everything under that point by:
     113
     114            $ cd src/lib
     115            $ gmake debug
     116            $ gmake install
     117==  Linking Libraries  ==
     118
     119When building a command that is linked with a generated library, the
     120appropriate version of the library will be linked in.
     121
     122For example, the following fragments link the normal, debug, or
     123version of "libmine.a" as appropriate:
     124
     125            LD_LIBS   += $(LIBMINE)
     126            LIBMINE = ../libmine/${ARCH}/libmine.a
     127
     128            ${ARCH}/pgm: $(LIBMINE) ${OBJS}
     129                $(make-exe)
     130
     131If we do 'gmake debug', then the library in
     132../libmine/o-debug/libmine.a will be linked in.  If $(LIBMINE)
     133might not exist (or might be out of date) at this point, we could add
     134
     135            ${LIBMINE}: FORCEIT
     136                cd ../libmine; ${MAKE} ${VARIANT_VA}
     137
     138The above would generate the following command to build libmine.a:
     139
     140            cd ../libmine; gmake debug
     141
     142The macro reference ${VARIANT_VA} converts ${ARCH} to the word 'debug'
     143(in this example) and thus ensures the proper version of the library
     144is built.
     145
     146==  Targets  ==
     147
     148All Makefile's support the following targets:
     149
     150            all                     -- make "everything"
     151            install                 -- install "everything"
     152
     153The following targets are provided automatically by
     154the included config files:
     155
     156            clean                   -- delete all targets
     157            depend                  -- build a make dependency file
     158            "variant targets"       -- special variants, see below
     159
     160
     161All directory Makefiles automatically propagate all these targets.  If
     162you don't wish to support 'all' or 'install' in your source directory,
     163you must leave the rules section empty, as the parent directory Makefile
     164will attempt it on recursive make's.
     165
     166===  Configuration  ===
     167
     168All the real work described here happens in file(s) included
     169from your Makefile.
     170
     171        All Makefiles include a customization file which is used to select
     172        compiler and host operating system.  The environment variable
     173        RTEMS_MAKEFILE_PATH must point to the directory containing this file; eg:
     174
     175                export RTEMS_MAKEFILE_PATH=/.../pc386/
     176
     177        All leaf Makefile's also include either 'make/leaf.cfg' (or
     178        'make/lib.cfg' for building libraries).  These config files provide
     179        default rules and set up the command macros as appropriate.
     180
     181        All directory Makefiles include 'make/directory.cfg'.  directory.cfg
     182        provides all the rules for recursing through sub directories.
     183
     184        The Makefile templates already perform these include's.
     185
     186        'make/leaf.cfg' (or directory.cfg) in turn includes:
     187
     188            a file specifying general purpose rules appropriate for
     189                both leaf and directory makefiles.
     190                ( make/main.cfg )
     191
     192            personality modules specified by the customization file for:
     193                compiler            ( make/compilers/??.cfg )
     194
     195
     196        ==== Generic Rules File ====
     197
     198            [ make/main.cfg ]
     199            included by leaf.cfg or directory.cfg.
     200
     201            This file contains some standard rules and variable assignments
     202            that all Makefiles need.
     203
     204            It also includes the FORCEIT: pseudo target.
     205
     206
     207        ==== OS config file for host machine ====
     208
     209            [ make/os/OS-NAME.cfg ]
     210            included by main.cfg
     211
     212            Figures out the target architecture and specifies command names
     213            for the OS tools including RCS/CVS (but NOT for the compiler tools).
     214
     215
     216        ==== Compiler configuration for the target ====
     217
     218            [ compilers/COMPILER-NAME.cfg ]
     219            included by leaf.cfg
     220
     221            Specifies the names of tools for compiling programs.
     222            Names in here should be fully qualified, and NOT depend on $PATH.
     223
     224            Also specifies compiler flags to be used to generate optimized,
     225            debugging versions, as well as rules to compile
     226            assembly language and make makefile dependencies.
     227
     228
     229    ==== Configuration Variables ====
     230
     231        Variables you have to set in the environment or in your Makefile.
     232        Note: the RTEMS module files set RTEMS_ROOT and RTEMS_CUSTOM
     233        for you.
     234
     235        ==== Makefile Variables ====
     236
     237            RTEMS_BSP        -- name of your 'bsp' eg: pc386, mvme136
     238
     239            RTEMS_CPU        -- CPU architecture e.g.: i386, m68k
     240
     241            RTEMS_CPU_FAMILY -- CPU model e.g.: i486dx, m68020
     242
     243            RTEMS_ROOT     -- The root of your source tree.
     244                              All other file names are derived from this.
     245                              [ eg: % setenv RTEMS_ROOT $HOME/work/RTEMS ]
     246
     247            RTEMS_CUSTOM   -- name of your config files in make/custom
     248                              Example:
     249                                 $(RTEMS_ROOT)/make/custom/$(RTEMS_BSP).cfg
     250
     251            The value RTEMS_ROOT is used in the custom
     252            files to generate the make(1) variables:
     253
     254                PROJECT_RELEASE
     255                PROJECT_BIN
     256                PROJECT_INCLUDE
     257                PROJECT_TOOLS
     258
     259            etc., which are used within the make config files themselves.
     260            (The files in make/*.cfg try to avoid use of word RTEMS so
     261            they can be more easily shared by other projects)
     262
     263        ==== Preset variables ====
     264
     265            Aside from command names set by the OS and compiler config files,
     266            a number of MAKE variables are automatically set and maintained by
     267            the config files.
     268
     269            PROJECT_RELEASE
     270                        -- release/install directory
     271                           [ $(PROJECT_ROOT) ]
     272
     273            PROJECT_BIN
     274                        -- directory for installed binaries
     275                           [ $(PROJECT_ROOT)/bin ]
     276
     277            PROJECT_TOOLS
     278                        -- directory for build environment commands
     279                           [ eg: $(PROJECT_ROOT)/build-tools ]
     280
     281            ARCH        -- target sub-directory for object code
     282                           [ eg: o-optimize or o-debug ]
     283
     284            VARIANTS    -- full list of all possible values for $(ARCH);
     285                           used mainly for 'make clean'
     286                           [ eg: "o-optimize o-debug" ]
     287
     288            VARIANT_VA  -- Variant name.
     289                           Normally "", but for 'make debug' it is "debug".
     290
     291                           see make/leaf.cfg for more info.
     292
     293
     294        ==== Preset compilation variables ====
     295
     296          This is a list of some of the compilation variables.
     297          Refer to the compiler config files for the complete list.
     298
     299            CFLAGS_OPTIMIZE_V   -- value of optimize flag for compiler
     300                                   [ eg: -O ]
     301
     302            CFLAGS_DEBUG_V      -- value of debug flag for compiler
     303                                   [ eg: -g ]
     304
     305            CFLAGS_DEBUG_OPTIMIZE_V
     306                                -- optimize flag if compiling for debug
     307                                     [ eg: "" ]
     308
     309            CFLAGS_DEBUG
     310            CFLAGS_OPTIMIZE     -- current values for each depending
     311                                    on make variant.
     312
     313            LDFLAGS_STATIC_LIBRARIES_V
     314                                -- ld option for static libraries
     315                                    -Bstatic or -dy (svr4)
     316
     317            LDFLAGS_SHARED_LIBRARIES_V
     318                                -- ld option for dynamic libraries
     319                                    -Bdynamic or -dn (svr4)
     320
     321            ==== Makefile Variables ====
     322
     323                The following variables may be set in a typical Makefile.
     324
     325                C_PIECES    -- File names of your .c files without '.c' suffix.
     326                               [ eg: C_PIECES=main funcs stuff ]
     327
     328                CC_PIECES   -- ditto, except for .cc files
     329
     330                S_PIECES    -- ditto, except for .S files.
     331
     332                LIB         -- target library name in leaf library makefiles.
     333                               [ eg: LIB=${ARCH}/libmine.a ]
     334
     335                H_FILES     -- your .h files in this directory.
     336                               [ eg: H_FILES=stuff.h extra.h ]
     337
     338                DEFINES     -- cc -D items.  Included in CPPFLAGS.
     339                               leaf Makefiles.
     340                               [ eg: DEFINES += -DUNIX ]
     341
     342                CPPFLAGS    -- -I include directories.
     343                               leaf Makefiles.
     344                               [ eg: CPPFLAGS += -I../include ]
     345
     346                LD_PATHS    -- arguments to -L for ld.
     347                               Will be prefixed with '-L' or '-L ' as appropriate
     348                               and included in LDFLAGS.
     349
     350                LDFLAGS     -- -L arguments to ld; more may be ADDed.
     351
     352                LD_LIBS     -- libraries to be linked in.
     353                               [ eg: LDLIBS += ../libfoo/${ARCH}/libfoo.a ]
     354
     355                XCFLAGS     -- "extra" CFLAGS for special needs.  Pre-pended
     356                               to CFLAGS.
     357                               Not set or used by Makefiles.
     358                               Can be set on command line to pass extra flags
     359                               to the compiler.
     360
     361                XCPPFLAGS   -- ditto for CPPFLAGS
     362                               Can be set on command line to pass extra flags
     363                               to the preprocessor.
     364
     365                XCCPPFLAGS  -- same as XCPPFLAGS for C++.
     366
     367                XCCFLAGS    -- same as XCFLAGS for C++.
     368
     369                SUBDIRS    -- list of sub directories for make recursion.
     370                               directory Makefiles only.
     371                               [ eg: SUBDIRS=cpu bsp ]
     372
     373                CLEAN_ADDITIONS
     374                            -- list of files or directories that should
     375                               be deleted by 'make clean'
     376                               [ eg: CLEAN_ADDITIONS += y.tab.c ]
     377
     378                               See 'leaf.cfg' for the 'clean:' rule and its
     379                               default deletions.
     380
     381                CLOBBER_ADDITIONS
     382                            -- list of files or directories that should
     383                               be deleted by 'make clobber'
     384                               Since 'make clobber' includes 'make clean',
     385                               you don't need to duplicate items in both.
     386
     387            ==== Command names ====
     388
     389                The following commands should only be called
     390                as make variables:
     391
     392                    MAKE,INSTALL,INSTALL_VARIANT,SHELL
     393
     394                    ECHO,CAT,CP,MV,LN,MKDIR,CHMOD
     395
     396                    SED
     397
     398                    CC,CPP,AS,AR,LD,NM,SIZE,RANLIB,MKLIB,
     399                    YACC,LEX,LINT,CTAGS,ETAGS
     400
     401                 In addition, the following commands specifically support
     402                 the installation of libraries, executables, header files,
     403                 and other things that need to be installed:
     404
     405                    INSTALL_CHANGE  - install a file only if the source
     406                                      file is actually different than
     407                                      the installed copy or if there is
     408                                      no installed copy.  USAGE:
     409
     410      usage: install-if-change [ -vmV ] file [ file ... ] dest-directory-or-file
     411        -v          -- verbose
     412        -V suffix   -- suffix to append to targets (before any . suffix)
     413                        eg: -V _g would change 'foo' to 'foo_g' and
     414                                               'libfoo.a' to 'libfoo_g.a'
     415        -m mode     -- mode for new file(s)
     416
     417                    INSTALL_VARIANT - installs the built file using the
     418                                      proper variant suffix (e.g. _g
     419                                      for debug turns libmine.a into libmine_g.a)
     420                                      This is implemented as a macro that
     421                                      invokes install-if-change with the
     422                                      appropriate -V argument setting.
     423
     424            ==== Special Directory Makefile Targets ====
     425
     426                all_WRAPUP
     427                clean_WRAPUP
     428                install_WRAPUP
     429                clean_WRAPUP
     430                clobber_WRAPUP
     431                depend_WRAPUP
     432                            -- Specify additional commands for recursive
     433                               (directory level) targets.
     434
     435                               This is handy in certain cases where you need
     436                               to do bit of work *after* a recursive make.
     437
     438    ==== make/Templates ====
     439
     440        This directory contains Makefile and source file templates that
     441        should help in creating or converting makefiles.
     442
     443        Makefile.leaf
     444            Template leaf Makefiles.
     445
     446        Makefile.lib
     447            Template leaf library Makefiles.
     448
     449        Makefile.dir
     450            Template "directory" makefile.
     451
     452= Detailed Explanations =
     453
     454
     455To lower the learning curve and speed up development time for RTEMS applications, below is an example Makefile.am that is explained in painful detail
     456Please add explanations for other RTEMS Makefile.am's
     457==  cpukit/librpc/Makefile.am  ==
     458
     459
     460Explanation of an RTEMS cpukit Makefile.am.
     461
     462The first two lines of code tell the cross-compiler what flags to use to compile multiple board support packages at once.
     463
     464{{{
     465...
     466## $(top_srcdir) is /rtems/cpukit (the directory of the nearest configure script)
     467## rtems/cpukit/automake/multilib.am tells the compiler how to make more than one board at a time
     4685       include $(top_srcdir)/automake/multilib.am
     469
     470## rtems/cpukit/automake/compile.am tells the compiler and assembler which flags to use
     4716       include $(top_srcdir)/automake/compile.am
     472}}}
     473
     474The next line of interest is the conditional (you will have to have rtems/cpukit/configure.ac explicitly set this)
     475{{{
     476## a conditional determined by the configure script
     47710      if LIBRPC
     478}}}
     479==  Headers  ==
     480
     481Headers define functions, and are used across multiple source files.
     482
     483===  Include Directory  ===
     484
     485include_rpcdir tells the autotools where to place the header files.
     486$(includedir)/rpc means put the rpc headers in a subdirectory of where the all the headers go.
     487When I compiled my project it was more expedient to put: include_aprdir = $(includedir) instead of include_aprdir = $(includedir)/apr
     488Although it may be possible to add a preprocessor flag to the Makefile.am to link to the desired subdirectory
     489{{{
     490## the include dir is the prefix for all headers in the library in this case, it's RPC
     49111      include_rpcdir = $(includedir)/rpc
     492}}}
     493
     494===  Include Header Files  ===
     495
     496Header files are needed by source files to to know how to link functions together.  To make header files available to source files, they must be added to the preprocessor and linker flags.  include_HEADERS does  this.
     497 
     498The format for adding headers to a cpukit project is:
     499include_"your project prefix"_HEADERS
     500{{{
     501## prepend all library headers with which library they are included in, include paths
     502## these headers are available to the entire library
     50313      include_rpc_HEADERS = include/rpc/auth.h include/rpc/auth_unix.h
     504}}}
     505
     506==  The Project Libraries  ==
     507
     508Libraries are the binary linked against a program full of helper functions.  In an RTEMS application these are linked against using the -l flag. 
     509
     510===  Declaring the Libraries  ===
     511
     512To make these libraries available to an application, use project_lib_LIBRARIES instead of noinst_LIBRARIES (which is for use with the libcpukit and not application libraries)
     513{{{
     514## Tells the build system which libraries to build
     515## for applications being ported use
     516## project_lib_LIBRARIES instead
     517## so you can link against them
     51826      noinst_LIBRARIES = libxdr.a
     519XX      project_lib_LIBRARIES = libxdr.a
     520}}}
     521==  Making the headers available to the Sources: CPP Flags  ==
     522
     523You must explicitly tell auto-tools to make the library's headers available to the sources
     524{{{
     525## make the all the existing preprocessor flags available to the library
     52627      libxdr_a_CPPFLAGS = $(AM_CPPFLAGS) $(rpc_CPPFLAGS)
     527}}}
     528
     529===  Library Source files  ===
     530
     531Use the library name replacing all special characters with an underscore and adding _SOURCES at the end.
     532Include the relative path to the source file.
     533{{{
     534## source files for the library         
     53529      libxdr_a_SOURCES = src/xdr/xdr.c src/xdr/xdr_array.c src/xdr/xdr_float.c \
     536}}}
     537
     538==  Closing out the Makefile.am  ==
     539
     540===  Make the internal flags available to your project  ===
     541
     542There are libc, libshell, and libnetworking flags that your project will probably need.
     543{{{
     544## including these flags in your project are very helpful
     54557      librpc_CPPFLAGS = -D_RPC_read=read -D_RPC_write=write -D_RPC_close=close \
     54658      -D_RTEMS_RPC_INTERNAL_
     547}}}
     548
     549===  Closing out Conditionals  ===
     550
     551Although in the example, there are many calls to the conditional, using it once towards the beginning and end is okay.
     552{{{
     553## close out the conditional
     55432      endif
     555}}}
     556
     557===  RTEMS directory recursion method  ===
     558
     559Preinstall.am is an RTEMS auto-generated file that adds the library into the rest of the RTEMS build system.
     560{{{
     561## Connect this project with the rest of RTEMS
     56290      include $(srcdir)/preinstall.am
     56391      include $(top_srcdir)/automake/local.am
     564}}}