From 051ab3b1e9b5f8edee183fbe82f319e872d59fc1 Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Tue, 20 Oct 1998 19:27:13 +0000 Subject: Links between chapters up to Linker Script in place. First draft of chapters up to and include Makefiles written. --- doc/bsp_howto/makefiles.t | 151 +++++++++++++++++++++++++++++++++++----------- 1 file changed, 116 insertions(+), 35 deletions(-) (limited to 'doc/bsp_howto/makefiles.t') diff --git a/doc/bsp_howto/makefiles.t b/doc/bsp_howto/makefiles.t index 9490b977ca..fdcbc4a7be 100644 --- a/doc/bsp_howto/makefiles.t +++ b/doc/bsp_howto/makefiles.t @@ -10,17 +10,39 @@ @section Makefiles Used During The BSP Building Process -There's a makefile template in each directory of a BSP. They are called -"makefile.in" and are processed when building RTEMS for a given BSP. One -should specify the needed files and directories before the building -process. +There is a file named @code{Makefile.in} in each directory of a BSP. +RTEMS uses the @b{GNU autoconf} automatic configuration package. +This tool specializes the @code{Makefile.in} files at the time that RTEMS +is configured for a specific development host and target. Makefiles +are automatically generated from the @code{Makefile.in} files. It is +necessary for the BSP developer to provide these files. Most of the +time, it is possible to copy the @code{Makefile.in} from another +similar directory and edit it. + +The @code{Makefile} files generated are processed when building +RTEMS for a given BSP. + +The BSP developer is responsible for generating @code{Makefile.in} +files which properly build all the files associated with their BSP. +There are generally three types of Makefiles in a BSP source tree: + @itemize @bullet +@item Directory Makefiles +@item Source Directory Makefiles +@item Wrapup Makefile +@end itemize -@item the makefile.in at the BSP root specifies which folders have to be -included. For instance, +@subsection Directory Makefiles -@item We only build the networking device driver if HAS_NETWORKING was defined +The Directory class of Makefiles directs the build process through +a set of subdirectories in a particular order. This order is usually +chosen to insure that build dependencies are properly processed. +Most BSPs only have one Directory class Makefile. The @code{Makefile.in} +in the BSP root directory (@code{c/src/lib/libbsp/CPU/BSP}) specifies +which directories are to be built for this BSP. For example, the +following Makefile fragment shows how a BSP would only build the +networking device driver if HAS_NETWORKING was defined: @example NETWORKING_DRIVER_yes_V = network @@ -32,38 +54,93 @@ SUB_DIRS=include start340 startup clock console timer \ $(NETWORKING_DRIVER) wrapup @end example -states that all the directories have to be processed, except for the -network directory which is included only if the user asked for it when -building RTEMS. +This fragment states that all the directories have to be processed, +except for the @code{network} directory which is included only if the +user configured networking. -@item the makefile.in in each driver directory. It lists the files to be -included in the driver, so don't forget to add the reference to a new file -in the makefile.in of a given driver when it is created! - -@end itemize +@subsection Source Directory Makefiles +There is a @code{Makefile.in} in most of the directories in a BSP. This +class of Makefile lists the files to be built as part of the driver. +Do not forget to add the reference to a new file in the @code{Makefile.in} +it is created! -Rem : the makefile.in files are ONLY processed during the configure +@b{NOTE:} The @code{Makefile.in} files are ONLY processed during the configure process of a RTEMS build. It means that, when you're working on the design of your BSP, and that you're adding a file to a folder and to the -corresponding makefile.in, it will not be take n into account! You have to -run configure again or modify the makefile (result of the makefile.in -process, usually in your /c/src/lib/libbsp/// -directory) by hand. +corresponding makefile.in, it will not be taken into account! You have to +run configure again or modify the @code{Makefile} (the result of the +configure process) by hand. This file will be in a directory such as +the following: + +@example +MY_BUILD_DIR/c/src/lib/libbsp/CPU/BSP/DRIVER +@end example + +@subsection Wrapup Makefile + +This class of Makefiles produces a library. The BSP wrapup Makefile +is responsible for producing the library @code{libbsp.a} which is later +merged into the @code{librtemsall.a} library. This Makefile specifies +which BSP components are to be placed into the library as well as which +components from the CPU dependent support code library. For example, +this component may choose to use a default exception handler from the +CPU dependent support code or provide its own. + +This Makefile makes use of a neat construct in @b{GNU make} to pick +up the required components: + +@example +BSP_PIECES=startup clock console timer +CPU_PIECES= +GENERIC_PIECES= + +# bummer; have to use $foreach since % pattern subst rules only replace 1x +OBJS=$(foreach piece, $(BSP_PIECES), ../$(piece)/$(ARCH)/$(piece).rel) \ + $(foreach piece, $(CPU_PIECES), \ + ../../../../libcpu/$(RTEMS_CPU)/$(piece)/$(ARCH)/$(piece).rel) \ + $(wildcard \ + ../../../../libcpu/$(RTEMS_CPU)/$(RTEMS_CPU_MODEL)/fpsp/$(ARCH)/fpsp.rel) \ + $(foreach piece, $(GENERIC_PIECES), ../../../$(piece)/$(ARCH)/$(piece).rel) +@end example + +The variable @code{OBJS} is the list of "pieces" expanded to include +path information to the appropriate object files. The @code{wildcard} +function is used on pieces of @code{libbsp.a} which are optional and +may not be present based upon the configuration options. @section Makefiles Used Both During The BSP Design and its Use -A BSP must go with his configuration file. The configuration files can be -found under $RTEMS_ROOT/c/make/custom. The configuration file is taken -into account when building one's application using the template makefiles -($RTEMS_ROOT/c/make/templates), whic h is strongly advised. There are -templates for calling recursively the makefiles in the directories beneath -the current one, building a library or an executable. +When building a BSP or an application using that BSP, it is necessary +to tailor the compilation arguments to account for compiler flags, use +custom linker scripts, include the RTEMS libraries, etc.. The BSP +must be built using this information. Later, once the BSP is installed +with the toolset, this same information must be used when building the +application. So a BSP must include a build configuration file. The +configuration file is @code{make/custom/BSP.cfg}. + +The configuration file is taken into account when building one's +application using the RTEMS template Makefiles (@code{make/templates}). +It is strongly advised to use these template Makefiles since they +encapsulate a number of build rules along with the compile and link +time options necessary to execute on the target board. + +There are template Makefiles provided for each of the classes of RTEMS +Makefiles. This include Makefiles to: + +@itemize @bullet +@item call recursively the makefiles in the directories beneath +the current one, -The following is a hevaily commented version of the make customization -file for the gen68340 BSP. It can be found in the $RTEMS_ROOT/make/custom -directory. +@item build a library, or + +@item build an executable. + +@end itemize + +The following is a shortened and heavily commented version of the +make customization file for the gen68340 BSP. The original source +for this file can be found in the @code{make/custom} directory. @example @@ -110,17 +187,21 @@ define make-exe endif @end example +@subsection Creating a New BSP Make Customization File - -What you have to do: +The basic steps for creating a @code{make/custom} file for a new BSP +is as follows: @itemize @bullet -@item copy any .cfg file to .cfg +@item copy any @code{.cfg} file to @code{BSP.cfg} -@item modify RTEMS_CPU, TARGET_ARCH, RTEMS_CPU_MODEL, RTEMS_BSP_FAMILY, -RTEMS_BSP, CPU_CFLAGS, START_BASE accordingly. +@item modify RTEMS_CPU, RTEMS_CPU_MODEL, RTEMS_BSP_FAMILY, +RTEMS_BSP, CPU_CFLAGS, START_BASE, and make-exe rules. @end itemize +It is generally easier to copy a @code{make/custom} file which is for a +BSP close to your own. + -- cgit v1.2.3