From 6d7a4d2ee7053488f625faccc8bd4dc4d25d6460 Mon Sep 17 00:00:00 2001 From: Chris Johns Date: Fri, 17 Jun 2016 15:05:41 +1000 Subject: Update the BSP howto. Closes #2590. --- bsp_howto/makefiles.rst | 268 +++++++++++++++++++++++------------------------- 1 file changed, 130 insertions(+), 138 deletions(-) (limited to 'bsp_howto/makefiles.rst') diff --git a/bsp_howto/makefiles.rst b/bsp_howto/makefiles.rst index 3701e07..7932561 100644 --- a/bsp_howto/makefiles.rst +++ b/bsp_howto/makefiles.rst @@ -1,169 +1,169 @@ .. comment SPDX-License-Identifier: CC-BY-SA-4.0 +.. COMMENT: COPYRIGHT (c) 1988-2002. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: All rights reserved. + 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: +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`` - bootstrap +- ``configure`` -- .. code:: c +- ``build`` - configure +- ``install`` -- .. code:: c +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. - build +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. -- .. code:: c +During the build phase, the source files are compiled into object files and +libraries are built. - install +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. -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. +Makefiles Used During The BSP Building Process +============================================== -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. +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: -During the build phase, the source files are compiled into object files -and libraries are built. +- ``bootstrap`` to regenerate all files that are generated by autoconf and + automake. -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. +- ``bootstrap -c`` to remove all files generated by autoconf and automake. -Makefiles Used During The BSP Building Process -============================================== +- ``bootstrap -p`` to regenerate ``preinstall.am`` files. -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: +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. -- ``bootstrap`` to regenerate all files that are generated by - autoconf and automake. +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. -- ``bootstrap -c`` to remove all files generated by autoconf and - automake. +The ``Makefile`` files generated are processed when configuring and building +RTEMS for a given BSP. -- ``bootstrap -p`` to regenerate ``preinstall.am`` files. +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. -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 +.. code-block:: makefile 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 \\ +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-block:: makefile + + 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``. +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 +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. - libbsp_a_LIBADD = ../../../libcpu/@RTEMS_CPU@/cache.rel \\ - ../../../libcpu/@RTEMS_CPU@/reg_win.rel \\ +.. code-block:: makefile + + 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! +.. 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 will 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 +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-block:: makefile # The RTEMS CPU Family and Model RTEMS_CPU=m68k @@ -177,20 +177,12 @@ found in the ``make/custom`` directory. # 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. +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. -- cgit v1.2.3