diff options
Diffstat (limited to '')
-rw-r--r-- | bsp-howto/makefiles.rst | 194 |
1 files changed, 0 insertions, 194 deletions
diff --git a/bsp-howto/makefiles.rst b/bsp-howto/makefiles.rst deleted file mode 100644 index cd0feaf..0000000 --- a/bsp-howto/makefiles.rst +++ /dev/null @@ -1,194 +0,0 @@ -.. 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: - -Makefiles -********* - -.. warning:: - - This chapter contains outdated and confusing information. - -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: - -- ``bootstrap`` - -- ``configure`` - -- ``build`` - -- ``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-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-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``. - -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-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 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-block:: makefile - - # 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. |