HOWTO Build Additional Packages
Table of Contents
Summary
This HOWTO covers the various methods for building packages in addition to those available within Desktop Factory.
NOTE: This HOWTO assumes that the Desktop Factory has been configured and built prior to building the new package. If these Factory configuration and build steps have not been completed yet, please do so before continuing with this HOWTO.
There are a few methods for building packages not included in Factory by default.
Introduction
While Factory has access to more than 1000 libraries and packages available in the Timesys Source Repository for use with builds, new or custom packages are easy to build for your target system as well. Building new or custom applications for the selected target can also be completed with ease. This can be accomplished with nothing more than the Factory-provided toolchain in a semi-manual manner, or directly within the Desktop Factory BSP/SDK build process after some initial setup.
Using Factory-generated Toolchain
The toolchain built by Factory during the BSP/SDK build process contains a set of helper scripts allowing for the easy cross-configuration and cross-building of various Autotools enabled packages. While this remains a somewhat manual process, the toolchain generated during the Factory BSP/SDK build process contains a set of Cross-Scripts aiming to make this manual process easier.
Add Cross-Toolchain to PATH
The first step is to set the development host PATH environment variable to include the appropriate toolchain directories to cross-build the package. This is done with the export command from the Linux terminal window in which the package will be built.
export PATH=/PATH/TO/toolchain/bin:$PATH
for example, a with a toolchain installed via the SDK Installer from a completed Factory build
export PATH=/home/<user>/timesys/<board>/toolchain/bin:$PATH
This allows the development host machine to find the various cross-tools as well as the cross scripts to be able to appropriately build the package for the target system.
Cross-Configure Package
Now that the development host's PATH has been updated to include the cross-toolchain, we can cross-configure the new package for the target system. To help with this, the cross-configure script included in the toolchain's bin/ directory automatically sets up and passes the appropriate configuration flags and configures the Autotools enabled application. Simply change directory to the location of the patched source code for the new package and run the cross_configure script.
Note Any arguments supplied to the cross_configure script are passed onto the ./configure invocation.
cd to package directory cross_configure [optional arguments]
This process can also be completed without use of the cross_configure script as follows:
./configure \
--prefix=/usr \
--target=$TARGET \
--host=$TARGET \
--build=`gcc -dumpmachine`
Cross-build Package
Assuming that the development host PATH contains the cross-toolchain and that the package has been configured for the target system, it needs to be built using the cross-toolchain. Similar to the cross_configure script, a cross_make script is also provided in the toolchin's bin/ directory. This cross_make script automatically sets the appropriate target-specific build tools (cc, ld, as, etc) necessary to build the Autotools enabled application for the target system. This is run from the package source directory after it has been cross-configured.
Note Any arguments supplied to the cross_make script are passed onto the make invocation.
cd to package directory cross_make [optional arguments]
Install Package to Target RFS
Once the Autotools enabled package has been configured and built for the target system, installation is typically as simple as:
make install DESTDIR=/path/to/target/RFS/
After installation to the target RFS, the package should be tested on the running system.
Deploy RFS and Test
Once installed to the target RFS, the new package can be tested on the running target system by deploying the RFS and booting the target. Please refer to the board-specific Getting Started Guide for additional information on how to boot the target system.
Install Library to Toolchain (optional)
The cross_install_to_toolchian script is available in the Timesys-provided toolchain, which when used with the appropriate DESTDIR (for the toolchain directory), will install libraries built with the new package to the toolchain.
cd to package directory cross_install_to_toolchain DESTDIR=/path/to/toolchain/
Adding a Package to Desktop Factory
Desktop Factory is designed to be flexible and scalable, and has the ability to be extended to accommodate additional packages beyond those offered through the Timesys Source Repository. In order to add a new package to the Desktop Factory buildsystem, two files must be created. These two files are the package Kconfig entry (Config.in) and the package's recipe ([package].mk). Once these files are properly defined, the package will be selectable though the typical webui or menuconfig interfaces for building with Desktop Factory.
Generate Kconfig and Package Recipe Files
The new_pkg script packaged with Desktop Factory (found in the top-level Factory directory under bin/) is used to set up template Config.in and .mk files to be modified. These files are automatically created from the templates and placed in the appropriate directory (according to the Package Category parameter passed at execution) to provide the necessary instructions for building the new package. It can be used with packages enabled for autoconf, cmake, and qmake.
new_pkg Script
Run from within Factory's bin/ directory, the new_pkg script takes several parameters:
- package_name: name of the package used as entry in menuconfig and as application-specific make targets within factory
- package_category: software category in under which the package is added
- package_configuration_type: package configuration scheme
- external
- <source_archive>:
Note if no parameters are passed, the usage text is displayed
The two files needed by Desktop Factory to define a selectable package are the Kconfig file and the Package Recipe file. The new_pkg script copies both the .template_in and .template_mk from target/software/ to the appropriate target/software/<Category>/<package_name>/ directory (automatically created) and opens them for edit in a text editor (sequentially checking for vim, nano, vi, emacs).
Kconfig file
The Kconfig file (Config.in) is stored in the target/software/<Category>/<package_name>/ directory. The new_pkg script automatically creates this directory structure and saves the Config.in file here. The location of the Config.in file dictates where it can be found in the menuconfig and webui configuration interfaces. Factory config tokens and options as well as attributes for each are defined here. The package's Config.in determines what is displayed in the menuconfig or webui interface when selecting the package as well as default values and help text. Additionally any dependencies are coded into the buildsystem within this file.
Package Recipe file
The Package Recipe file (<package_name>.mk) is stored in the target/software/<Category>/<package_name>/ directory. The new_pkg script automatically creates this directory structure and saves the <package_name>.mk file here. It contains the rules for each stage of the Desktop Factory build process for the package (fetch, unpack, patch, configure, build, rfs-install, host-install, package). The rules for each of these stages should reflect the steps needed to complete the stage, and any unnecessary stages removed from the .mk file.
Click here for more info on these files and further recommendations.
Select Package via Menuconfig
Once the new package has been added, it can be selected via the menuconfig or webui Factory configuration tools to be included in the BSP/SDK build process. Simply locate the new package and select it to be built. Note The package should be located under Target Software -> <Category> (-> Sub-category) -> <package_name> as defined in target/<Category>/Config.in.
Build BSP/SDK
After the newly added package is selected, rebuilding the BSP/SDK should build the new package and install it to the target RFS per the rules defined in the <package_name>.mk file.
Note It is recommended to verify the proper building of the new package by logging and reviewing the build process. It can be captured with the following:
make 2>&1 | tee log-BuildNewPackage
Deploy RFS and Test
With the new package built and installed to the target RFS, all that is left is to verify proper functionality of the package on the running system. Please refer to the board-specific Getting Started Guide for additional information on how to boot the target system.
