wiki:Developer/Makefile

Version 1 (modified by Tan Gemicioglu, on Jan 12, 2016 at 10:56:05 AM) (diff)

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

Makefile

Excerpted from /opt/rtems-4.11/share/rtems-4.11/make/README

This file describes the layout and conventions of the application makefile support for RTEMS applications. Internally, RTEMS uses GNU-style autoconf/automake Makefiles as much as possible to ease integration with other GNU tools.

All of these "make" trees are substantially similar; however this file documents the current state of the RTEMS Application Makefile support. This Makefile system has evolved into its present form and as it exists in RTEMS today, its sole goal is to build RTEMS applications. The use of these Makefiles hides the complexity of producing executables for a wide variety of embedded CPU families and target BSPs. Switching between RTEMS BSPs is accomplished via setting the environment variable "RTEMS_MAKEFILE_PATH."

Historical Goals

This make tree is based on a build system originally developed to simplify porting projects between various OS's. The primary goals were:

  • simple and customizable individual makefiles
  • use widely available GNU make. There is no pre-processing or automatic generation of Makefiles.
  • Same makefiles work on many host OS's due to portability of GNU make and the host OS config files.
  • 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.
  • Builtin support for compiling "variants" such as debug versions. These variants can be built recursively.
  • Control of system dependencies.
    • "hidden" dependencies on environment variables (such as PATH) have been removed whenever possible.
    • No matter what your PATH variable is set to, you should get the same thing when you 'make' as everyone else on the project.

Description

This description covers aspects of the Makefile tree. Most of what is described here is maintained automatically by the configuration files.

The example makefiles in make/Templates should be used as a starting point for new directories.

Types of Makefiles

There are 2 main types of Makefile: directory and leaf.

Directory Makefiles

A Makefile in a source directory with sub-directories is called a "directory" Makefile.

Directory Makefile's are simply responsible for acting as "middle-men" and recursing into their sub-directories and propagating the make.

For example, directory src/bin will contain only a Makefile and sub-directories. No actual source code will reside in the directory. The following commands:

$ cd src/bin $ make all

would descend into all the subdirectories of 'src/bin' and recursively perform a 'make all'.

A 'make debug' will recurse thru sub-directories as a debug build.

A template directory Makefile which should work in almost all cases is in make/Templates/Makefile.dir

Leaf Makefiles

Source directories that contain source code for libraries or programs use a "leaf" Makefile.

These makefiles contain the rules necessary to build programs (or libraries).

A template leaf Makefile is in Templates/Makefile?.leaf . A template leaf Makefile for building libraries is in Templates/Makefile?.lib .

NOTE: To simplify nested makefile's and source maintenance, we disallow combining source and directories (that make(1) would be expected to recurse into) in one source directory. Ie., a directory in the source tree may contain EITHER source files OR recursive sub directories, but NOT both. This assumption is generally shared with GNU automake.

Variants (where objects go)

All binary targets are placed in a sub-directory whose name is (for example):

o-optimize/ -- optimized binaries o-debug/ -- debug binaries

Using the template Makefiles, this will all happen automatically. The contents of these directories are specific to a BSP.

Within a Makefile, the ${ARCH} variable is set to o-optimize, o-debug, etc., as appropriate.

HISTORICAL NOTE: Prior to version 4.5, the name of the sub-directory in which objects were placed included the BSP name.

Invoking make and make debug

Typing 'make' will place objects in o-optimize. 'make debug' will place objects in o-debug.

The debug targets are equivalent to 'all' except that CFLAGS and/or LDFLAGS are modified as per the compiler config file for debug and profile support.

The targets debug etc., can be invoked recursively at the directory make level. So from the top of a tree, one could install a debug version of everything under that point by:

$ cd src/lib $ gmake debug $ gmake install

Linking Libraries

When building a command that is linked with a generated library, the appropriate version of the library will be linked in.

For example, the following fragments link the normal, debug, or version of "libmine.a" as appropriate:

LD_LIBS += $(LIBMINE) LIBMINE = ../libmine/${ARCH}/libmine.a

${ARCH}/pgm: $(LIBMINE) ${OBJS}

$(make-exe)

If we do 'gmake debug', then the library in ../libmine/o-debug/libmine.a will be linked in. If $(LIBMINE) might not exist (or might be out of date) at this point, we could add

${LIBMINE}: FORCEIT

cd ../libmine; ${MAKE} ${VARIANT_VA}

The above would generate the following command to build libmine.a:

cd ../libmine; gmake debug

The macro reference ${VARIANT_VA} converts ${ARCH} to the word 'debug' (in this example) and thus ensures the proper version of the library is built.

Targets

All Makefile's support the following targets:

all -- make "everything" install -- install "everything"

The following targets are provided automatically by the included config files:

clean -- delete all targets depend -- build a make dependency file "variant targets" -- special variants, see below

All directory Makefiles automatically propagate all these targets. If you don't wish to support 'all' or 'install' in your source directory, you must leave the rules section empty, as the parent directory Makefile will attempt it on recursive make's.

Configuration

All the real work described here happens in file(s) included from your Makefile.

All Makefiles include a customization file which is used to select compiler and host operating system. The environment variable RTEMS_MAKEFILE_PATH must point to the directory containing this file; eg:

export RTEMS_MAKEFILE_PATH=/.../pc386/

All leaf Makefile's also include either 'make/leaf.cfg' (or 'make/lib.cfg' for building libraries). These config files provide default rules and set up the command macros as appropriate.

All directory Makefiles include 'make/directory.cfg'. directory.cfg provides all the rules for recursing through sub directories.

The Makefile templates already perform these include's.

'make/leaf.cfg' (or directory.cfg) in turn includes:

a file specifying general purpose rules appropriate for

both leaf and directory makefiles. ( make/main.cfg )

personality modules specified by the customization file for:

compiler ( make/compilers/??.cfg )

Generic Rules File

[ make/main.cfg ] included by leaf.cfg or directory.cfg.

This file contains some standard rules and variable assignments that all Makefiles need.

It also includes the FORCEIT: pseudo target.

OS config file for host machine

[ make/os/OS-NAME.cfg ] included by main.cfg

Figures out the target architecture and specifies command names for the OS tools including RCS/CVS (but NOT for the compiler tools).

Compiler configuration for the target

[ compilers/COMPILER-NAME.cfg ] included by leaf.cfg

Specifies the names of tools for compiling programs. Names in here should be fully qualified, and NOT depend on $PATH.

Also specifies compiler flags to be used to generate optimized, debugging versions, as well as rules to compile assembly language and make makefile dependencies.

Configuration Variables

Variables you have to set in the environment or in your Makefile. Note: the RTEMS module files set RTEMS_ROOT and RTEMS_CUSTOM for you.

Makefile Variables

RTEMS_BSP -- name of your 'bsp' eg: pc386, mvme136

RTEMS_CPU -- CPU architecture e.g.: i386, m68k

RTEMS_CPU_FAMILY -- CPU model e.g.: i486dx, m68020

RTEMS_ROOT -- The root of your source tree.

All other file names are derived from this. [ eg: % setenv RTEMS_ROOT $HOME/work/RTEMS ]

RTEMS_CUSTOM -- name of your config files in make/custom

Example:

$(RTEMS_ROOT)/make/custom/$(RTEMS_BSP).cfg

The value RTEMS_ROOT is used in the custom files to generate the make(1) variables:

PROJECT_RELEASE PROJECT_BIN PROJECT_INCLUDE PROJECT_TOOLS

etc., which are used within the make config files themselves. (The files in make/*.cfg try to avoid use of word RTEMS so they can be more easily shared by other projects)

Preset variables

Aside from command names set by the OS and compiler config files, a number of MAKE variables are automatically set and maintained by the config files.

PROJECT_RELEASE

-- release/install directory

[ $(PROJECT_ROOT) ]

PROJECT_BIN

-- directory for installed binaries

[ $(PROJECT_ROOT)/bin ]

PROJECT_TOOLS

-- directory for build environment commands

[ eg: $(PROJECT_ROOT)/build-tools ]

ARCH -- target sub-directory for object code

[ eg: o-optimize or o-debug ]

VARIANTS -- full list of all possible values for $(ARCH);

used mainly for 'make clean' [ eg: "o-optimize o-debug" ]

VARIANT_VA -- Variant name.

Normally "", but for 'make debug' it is "debug".

see make/leaf.cfg for more info.

Preset compilation variables

This is a list of some of the compilation variables. Refer to the compiler config files for the complete list.

CFLAGS_OPTIMIZE_V -- value of optimize flag for compiler

[ eg: -O ]

CFLAGS_DEBUG_V -- value of debug flag for compiler

[ eg: -g ]

CFLAGS_DEBUG_OPTIMIZE_V

-- optimize flag if compiling for debug

[ eg: "" ]

CFLAGS_DEBUG CFLAGS_OPTIMIZE -- current values for each depending

on make variant.

LDFLAGS_STATIC_LIBRARIES_V

-- ld option for static libraries

-Bstatic or -dy (svr4)

LDFLAGS_SHARED_LIBRARIES_V

-- ld option for dynamic libraries

-Bdynamic or -dn (svr4)

Makefile Variables

The following variables may be set in a typical Makefile.

C_PIECES -- File names of your .c files without '.c' suffix.

[ eg: C_PIECES=main funcs stuff ]

CC_PIECES -- ditto, except for .cc files

S_PIECES -- ditto, except for .S files.

LIB -- target library name in leaf library makefiles.

[ eg: LIB=${ARCH}/libmine.a ]

H_FILES -- your .h files in this directory.

[ eg: H_FILES=stuff.h extra.h ]

DEFINES -- cc -D items. Included in CPPFLAGS.

leaf Makefiles. [ eg: DEFINES += -DUNIX ]

CPPFLAGS -- -I include directories.

leaf Makefiles. [ eg: CPPFLAGS += -I../include ]

LD_PATHS -- arguments to -L for ld.

Will be prefixed with '-L' or '-L ' as appropriate and included in LDFLAGS.

LDFLAGS -- -L arguments to ld; more may be ADDed.

LD_LIBS -- libraries to be linked in.

[ eg: LDLIBS += ../libfoo/${ARCH}/libfoo.a ]

XCFLAGS -- "extra" CFLAGS for special needs. Pre-pended

to CFLAGS. Not set or used by Makefiles. Can be set on command line to pass extra flags to the compiler.

XCPPFLAGS -- ditto for CPPFLAGS

Can be set on command line to pass extra flags to the preprocessor.

XCCPPFLAGS -- same as XCPPFLAGS for C++.

XCCFLAGS -- same as XCFLAGS for C++.

SUBDIRS -- list of sub directories for make recursion.

directory Makefiles only. [ eg: SUBDIRS=cpu bsp ]

CLEAN_ADDITIONS

-- list of files or directories that should

be deleted by 'make clean' [ eg: CLEAN_ADDITIONS += y.tab.c ]

See 'leaf.cfg' for the 'clean:' rule and its default deletions.

CLOBBER_ADDITIONS

-- list of files or directories that should

be deleted by 'make clobber' Since 'make clobber' includes 'make clean', you don't need to duplicate items in both.

Command names

The following commands should only be called as make variables:

MAKE,INSTALL,INSTALL_VARIANT,SHELL

ECHO,CAT,CP,MV,LN,MKDIR,CHMOD

SED

CC,CPP,AS,AR,LD,NM,SIZE,RANLIB,MKLIB, YACC,LEX,LINT,CTAGS,ETAGS

In addition, the following commands specifically support the installation of libraries, executables, header files, and other things that need to be installed:

INSTALL_CHANGE - install a file only if the source

file is actually different than the installed copy or if there is no installed copy. USAGE:

usage: install-if-change [ -vmV ] file [ file ... ] dest-directory-or-file

-v -- verbose -V suffix -- suffix to append to targets (before any . suffix)

eg: -V _g would change 'foo' to 'foo_g' and

'libfoo.a' to 'libfoo_g.a'

-m mode -- mode for new file(s)

INSTALL_VARIANT - installs the built file using the

proper variant suffix (e.g. _g for debug turns libmine.a into libmine_g.a) This is implemented as a macro that invokes install-if-change with the appropriate -V argument setting.

Special Directory Makefile Targets

all_WRAPUP clean_WRAPUP install_WRAPUP clean_WRAPUP clobber_WRAPUP depend_WRAPUP

-- Specify additional commands for recursive

(directory level) targets.

This is handy in certain cases where you need to do bit of work *after* a recursive make.

make/Templates

This directory contains Makefile and source file templates that should help in creating or converting makefiles.

Makefile.leaf

Template leaf Makefiles.

Makefile.lib

Template leaf library Makefiles.

Makefile.dir

Template "directory" makefile.

Detailed Explanations

To lower the learning curve and speed up development time for RTEMS applications, below is an example Makefile.am that is explained in painful detail Please add explanations for other RTEMS Makefile.am's

cpukit/librpc/Makefile.am

Explanation of an RTEMS cpukit Makefile.am.

The first two lines of code tell the cross-compiler what flags to use to compile multiple board support packages at once.

...
## $(top_srcdir) is /rtems/cpukit (the directory of the nearest configure script)
## rtems/cpukit/automake/multilib.am tells the compiler how to make more than one board at a time
5 	include $(top_srcdir)/automake/multilib.am

## rtems/cpukit/automake/compile.am tells the compiler and assembler which flags to use
6 	include $(top_srcdir)/automake/compile.am

The next line of interest is the conditional (you will have to have rtems/cpukit/configure.ac explicitly set this)

## a conditional determined by the configure script
10 	if LIBRPC

Headers

Headers define functions, and are used across multiple source files.

Include Directory

include_rpcdir tells the autotools where to place the header files. $(includedir)/rpc means put the rpc headers in a subdirectory of where the all the headers go. When I compiled my project it was more expedient to put: include_aprdir = $(includedir) instead of include_aprdir = $(includedir)/apr Although it may be possible to add a preprocessor flag to the Makefile.am to link to the desired subdirectory

## the include dir is the prefix for all headers in the library in this case, it's RPC
11 	include_rpcdir = $(includedir)/rpc

Include Header Files

Header 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. The format for adding headers to a cpukit project is: include_"your project prefix"_HEADERS

## prepend all library headers with which library they are included in, include paths
## these headers are available to the entire library
13 	include_rpc_HEADERS = include/rpc/auth.h include/rpc/auth_unix.h

The Project Libraries

Libraries are the binary linked against a program full of helper functions. In an RTEMS application these are linked against using the -l flag.

Declaring the Libraries

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

## Tells the build system which libraries to build
## for applications being ported use
## project_lib_LIBRARIES instead 
## so you can link against them
26 	noinst_LIBRARIES = libxdr.a
XX      project_lib_LIBRARIES = libxdr.a

Making the headers available to the Sources: CPP Flags

You must explicitly tell auto-tools to make the library's headers available to the sources

## make the all the existing preprocessor flags available to the library
27 	libxdr_a_CPPFLAGS = $(AM_CPPFLAGS) $(rpc_CPPFLAGS)

Library Source files

Use the library name replacing all special characters with an underscore and adding _SOURCES at the end. Include the relative path to the source file.

## source files for the library 	
29 	libxdr_a_SOURCES = src/xdr/xdr.c src/xdr/xdr_array.c src/xdr/xdr_float.c \

Closing out the Makefile.am

Make the internal flags available to your project

There are libc, libshell, and libnetworking flags that your project will probably need.

## including these flags in your project are very helpful
57 	librpc_CPPFLAGS = -D_RPC_read=read -D_RPC_write=write -D_RPC_close=close \
58 	-D_RTEMS_RPC_INTERNAL_

Closing out Conditionals

Although in the example, there are many calls to the conditional, using it once towards the beginning and end is okay.

## close out the conditional
32 	endif

RTEMS directory recursion method

Preinstall.am is an RTEMS auto-generated file that adds the library into the rest of the RTEMS build system.

## Connect this project with the rest of RTEMS
90 	include $(srcdir)/preinstall.am
91 	include $(top_srcdir)/automake/local.am