diff options
author | Amar Takhar <amar@rtems.org> | 2016-01-17 00:47:50 -0500 |
---|---|---|
committer | Amar Takhar <verm@darkbeer.org> | 2016-05-02 20:51:23 -0400 |
commit | b35050917272ab536c8f4158e5c002f98a092796 (patch) | |
tree | 386dc0be827a10ff668e6d0b2b1ff52a1f49e9ed /bsp_howto/makefiles.rst | |
parent | Fix warnings. (diff) | |
download | rtems-docs-b35050917272ab536c8f4158e5c002f98a092796.tar.bz2 |
Split document into seperate files by section.
Diffstat (limited to '')
-rw-r--r-- | bsp_howto/makefiles.rst | 194 |
1 files changed, 194 insertions, 0 deletions
diff --git a/bsp_howto/makefiles.rst b/bsp_howto/makefiles.rst new file mode 100644 index 0000000..528617e --- /dev/null +++ b/bsp_howto/makefiles.rst @@ -0,0 +1,194 @@ +Makefiles +######### + +This chapter discusses the Makefiles associated with a BSP. It does not +describe the process of configuring, building, and installing RTEMS. +This chapter will not provide detailed information about this process. +Nonetheless, it is important to remember that the general process consists +of four phases as shown here: + +- .. code:: c + + bootstrap + +- .. code:: c + + configure + +- .. code:: c + + build + +- .. code:: c + + install + +During the bootstrap phase, you are using the ``configure.ac`` and``Makefile.am`` files as input to GNU autoconf and automake to +generate a variety of files. This is done by running the ``bootstrap`` +script found at the top of the RTEMS source tree. + +During the configure phase, a number of files are generated. These +generated files are tailored for the specific host/target combination +by the configure script. This set of files includes the Makefiles used +to actually compile and install RTEMS. + +During the build phase, the source files are compiled into object files +and libraries are built. + +During the install phase, the libraries, header files, and other support +files are copied to the BSP specific installation point. After installation +is successfully completed, the files generated by the configure and build +phases may be removed. + +Makefiles Used During The BSP Building Process +============================================== + +RTEMS uses the *GNU automake* and *GNU autoconf* automatic +configuration package. Consequently, there are a number of +automatically generated files in each directory in the RTEMS +source tree. The ``bootstrap`` script found in the top level +directory of the RTEMS source tree is executed to produce the +automatically generated files. That script must be run from +a directory with a ``configure.ac`` file in it. The ``bootstrap`` +command is usually invoked in one of the following manners: + +- ``bootstrap`` to regenerate all files that are generated by + autoconf and automake. + +- ``bootstrap -c`` to remove all files generated by autoconf and + automake. + +- ``bootstrap -p`` to regenerate ``preinstall.am`` files. + +There is a file named ``Makefile.am`` in each directory of +a BSP. This file is used by *automake* to produce the file named``Makefile.in`` which is also found in each directory of a BSP. +When modifying a ``Makefile.am``, you can probably find examples of +anything you need to do in one of the BSPs. + +The configure process specializes the ``Makefile.in`` files at the time that RTEMS +is configured for a specific development host and target. Makefiles +are automatically generated from the ``Makefile.in`` files. It is +necessary for the BSP developer to provide the ``Makefile.am`` +files and generate the ``Makefile.in`` files. Most of the +time, it is possible to copy the ``Makefile.am`` from another +similar directory and edit it. + +The ``Makefile`` files generated are processed when configuring +and building RTEMS for a given BSP. + +The BSP developer is responsible for generating ``Makefile.am`` +files which properly build all the files associated with their BSP. +Most BSPs will only have a single ``Makefile.am`` which details +the set of source files to build to compose the BSP support library +along with the set of include files that are to be installed. + +This single ``Makefile.am`` at the top of the BSP tree specifies +the set of header files to install. This fragment from the SPARC/ERC32 +BSP results in four header files being installed. +.. code:: c + + include_HEADERS = include/bsp.h + include_HEADERS += include/tm27.h + include_HEADERS += include/erc32.h + include_HEADERS += include/coverhd.h + +When adding new include files, you will be adding to the set of``include_HEADERS``. When you finish editing the ``Makefile.am`` +file, do not forget to run ``bootstrap -p`` to regenerate the``preinstall.am``. + +The ``Makefile.am`` also specifies which source files to build. +By convention, logical components within the BSP each assign their +source files to a unique variable. These variables which define +the source files are collected into a single variable which instructs +the GNU autotools that we are building ``libbsp.a``. This fragment +from the SPARC/ERC32 BSP shows how the startup related, miscellaneous +support code, and the console device driver source is managed +in the ``Makefile.am``. +.. code:: c + + startup_SOURCES = ../../sparc/shared/bspclean.c ../../shared/bsplibc.c \\ + ../../shared/bsppredriverhook.c \\ + ../../shared/bsppost.c ../../sparc/shared/bspstart.c \\ + ../../shared/bootcard.c ../../shared/sbrk.c startup/setvec.c \\ + startup/spurious.c startup/erc32mec.c startup/boardinit.S + clock_SOURCES = clock/ckinit.c + ... + noinst_LIBRARIES = libbsp.a + libbsp_a_SOURCES = $(startup_SOURCES) $(console_SOURCES) ... + +When adding new files to an existing directory, do not forget to add +the new files to the list of files to be built in the corresponding``XXX_SOURCES`` variable in the ``Makefile.am`` and run``bootstrap``. + +Some BSPs use code that is built in ``libcpu``. If you BSP does +this, then you will need to make sure the objects are pulled into your +BSP library. The following from the SPARC/ERC32 BSP pulls in the cache, +register window management and system call support code from the directory +corresponding to its ``RTEMS_CPU`` model. +.. code:: c + + libbsp_a_LIBADD = ../../../libcpu/@RTEMS_CPU@/cache.rel \\ + ../../../libcpu/@RTEMS_CPU@/reg_win.rel \\ + ../../../libcpu/@RTEMS_CPU@/syscall.rel + +*NOTE:* The ``Makefile.am`` files are ONLY processed by``bootstrap`` and the resulting ``Makefile.in`` files are only +processed during the configure process of a RTEMS build. Therefore, +when developing a BSP and adding a new file to a ``Makefile.am``, +the already generated ``Makefile`` will not automatically +include the new references unless you configured RTEMS with the``--enable-maintainer-mode`` option. Otherwise, the new file not +being be taken into account! + +Creating a New BSP Make Customization File +========================================== + +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 ``make/custom/BSP.cfg``. + +The configuration file is taken into account when building one’s +application using the RTEMS template Makefiles (``make/templates``). +These application template Makefiles have been included with the +RTEMS source distribution since the early 1990’s. However there is +a desire in the RTEMS user community to move all provided examples to +GNU autoconf. They are included in the 4.9 release series and used for +all examples provided with RTEMS. There is no definite time table for +obsoleting them. You are free to use these but be warned they have +fallen out of favor with many in the RTEMS community and may disappear +in the future. + +The following is a slightly shortened version of the make customization +file for the gen68340 BSP. The original source for this file can be +found in the ``make/custom`` directory. +.. code:: c + + # The RTEMS CPU Family and Model + RTEMS_CPU=m68k + RTEMS_CPU_MODEL=m68340 + include $(RTEMS_ROOT)/make/custom/default.cfg + # This is the actual bsp directory used during the build process. + RTEMS_BSP_FAMILY=gen68340 + # This contains the compiler options necessary to select the CPU model + # and (hopefully) optimize for it. + CPU_CFLAGS = -mcpu=cpu32 + # optimize flag: typically -O2 + CFLAGS_OPTIMIZE_V = -O2 -g -fomit-frame-pointer + +The make customization files have generally grown simpler and simpler +with each RTEMS release. Beginning in the 4.9 release series, the rules +for linking an RTEMS application are shared by all BSPs. Only BSPs which +need to perform a transformation from linked ELF file to a downloadable +format have any additional actions for program link time. In 4.8 and +older, every BSP specified the "make executable" or ``make-exe`` +rule and duplicated the same actions. + +It is generally easier to copy a ``make/custom`` file from a +BSP similar to the one being developed. + +.. COMMENT: COPYRIGHT (c) 1988-2002. + +.. COMMENT: On-Line Applications Research Corporation (OAR). + +.. COMMENT: All rights reserved. + |