Desktop Factory Getting Started Guide

The Timesys Factory build system provides an integrated means of defining, developing, and maintaining a custom Linux based platform.

For more information on the Factory features refer to the Factory Feature List.

Obtaining the Factory Build System

The recommended method is to use the Factory Installer from the output of the Timesys Web Factory build. The Factory Installer installs a pre-configured Factory for the selected board. It uses the pre-built initial toolchain and the Workorder associated with the build. The installed Factory (aka the Desktop Factory) uses the initial toolchain to build the cross-toolchain for your board and installs it in your development environment.

The latest Factory can be also obtained from LinuxLink Download Page, and other versions are available from the Timesys Git repository (additionally see HOWTO Clone a Timesys Git Repository). Cloning Timesys Git is useful for updating the Desktop Factory.

Host Setup

Timesys currently recommends the newest releases of Fedora and Ubuntu for a host environment.

Unpack the downloaded Factory archive on the host work station. Timesys recommends a new Factory copy for each project or major configuration change.

Before getting started with the Timesys Factory, make sure the host system has all of the required software packages. Run the checksystem make target from within the factory directory to scan your host system for required software. This utility will inform you of any missing host requirements and how to resolve them.

$ make checksystem

The Factory does not require root privileges. Running the build environment as the root user is discouraged in order to ensure the safety of the host work station.

Refer to Factory Host Requirements for common distribution specific packages.

Initial Configuration

Factory Configuration System Overview

The Timesys Factory uses the Linux Kernel Configuration system for the platform definition stored in the .config configuration file (our Factory workorder).

The menuconfig make target is the most commonly-used configuration interface.

$ make menuconfig

The other standard kernel-like configuration interfaces are also available for starting the platform configuration utility:

• config for a line based, non-menu version of the configuration editor
• gconfig for a graphical Gtk based version of the configuration editor
• xconfig for a graphical Qt based version of the configuration editor

For configuration maintenance, the update make target provides a way to move your platform configuration .config forward to a newer release. This does not change your specific selections, but does fill in new values defined in the newer build system and prompt for updated options not already set in the current configuration.

$ make update

Timesys provides in-line help text for each option that describes the option along with any additional rationale that goes along with the selection.

Search is available using the "/" key in menuconfig. You can specify a name or token. The results give the location of any matches in the menu hierarchy.

Refer to the Factory Kconfig description for more information.

The platform configuration is broken down into three major sections:

• Target configuration
• Toolchain configuration
• Target software

Target Configuration

The target configuration is the first step in defining a custom platform. The target reference platform selection affects other choices throughout the platform configuration. Timesys provides default values and options that are the most appropriate for the chosen target. General options that are used throughout the platform build are provided, including:

• Compiler flags for the target built software
• Root file system formats and size optimization options
• Custom file system content "overlay"
• Packaging formats for software selections
• Platform functional templates that can be combined to help in the later software selections

Toolchain Configuration

The toolchain configuration menu provides a default toolchain build mechanism or the ability to fetch a prebuilt Factory toolchain. If built, an option to also build a native toolchain for the target is provided. The default compiler flags for the host utilities are exposed for customization.

The toolchain components each provide their own custom configuration sub-menus. Default values are provided based on the chosen target, including recommended versions and configuration flags. These can all be further customized to the specific needs of the platform.

The C library choice exposes a sub-menu for each supported C library. Timesys recommends a different Factory copy and configuration if the C library is to be changed after the initial definition, as the C library choice affects subsequent selections and default values.

The GDB debugger advanced configuration provides a mechanism for building and including a target binary of the GDBserver for remote debugging.

Common, useful host utilities can also be selected to be included in the toolchain. Several are required for specific file-system generation and packaging of the target software.

Additional toolchains are provided for building non-Linux elf targets and for cross building the Linux kernel under Cygwin.

Target Software

The target software menu provides sub-menus for all of the target software that can be included in the platform.

Default selections for the kernel and boot loader are target specific.

Default selections for the software packages follow the template definitions from the previous target configuration menu.

Kernel

The Linux kernel configuration menu provides a selection for the desired Linux kernel version. Timesys' default version includes a kernel configuration and a series of patches as required for that kernel version.

The Factory defines two types of kernel build options, "internal" or "external". The internal kernel is a copy of the Linux kernel source, configuration, and packages provided by Timesys. An external kernel is an existing kernel source tree from which the path is provided along with whether or not to use an existing kernel .config configuration file present in the existing kernel soure tree.

General advanced options include the kernel make target, the resulting kernel image file name, and whether or not to include the built kernel image and modules in the final root file system. Target specific kernel configuration options are also available as required by the target.

Bootloader

The bootloader menu allows for the selection and customization of the default boot loader as available for the specified target. Timesys provides a default recommendation on the version, configuration, and patches (if applicable) for the target. If no applicable bootloaders are available, this menu is empty.

Software Packages

The target software packages are broken into major categories, with subcategories in each category menu. The software selections available depend on the previously-selected target and C library. Each package contains a sub-menu for advanced configuration that exposes the source, patches, and configuration applied at build time.

Dependent packages are automatically selected, and these dependencies are described in the help text for each package.

Hypervisor

For supported targets, available hypervisor frameworks and utilities are made available in the Hypervisor menu.

Platform Software

For supported targets, available non-Linux software and applications are made available in the Platform Software menu.

Building

The Timesys Factory build system is implemented with GNU make that uses the Kconfig definitions as input which is then passed along to the specific make targets and general build framework.

The most generic invocation of the build system is invoking make with no targets specified. This invokes several core Factory targets:

target	Description
checkupdates	Check for updates from Timesys
showpackages	Show summary of packages selected in current .config
sources	Download all sources and patches required to build selections
toolchain	Build and package the cross toolchain
rfs	Compile all selections and kernel and create RFS output
rfs-images	Generate RFS images (Called by RFS)
packages	Generate packages for all selections
installer	Generate the installer for the custom target SDK
showoutput	Show summary of the build output

Each of the above targets can be invoked individually.

Each target application selection exposes a series of make targets for itself that follow along the same lines.

target	Description
[application]-clean	Purge application build directory
[application]-distclean	Purge application build and source directories
[application]-fetch	Fetch source, patches, and files
[application]-unpack	Unpack into the application working directory
[application]-patch	Apply patches to the application
[application]-configure	Configure the application
[application]-build	Build the application
[application]-package	Generate a package from the application
[application]-rfs-install	Install the application into the RFS working directory
[application]-host-install	Install the application into the Host Toolchain
[application]-show	display application information
[application]-select	add application to current configuration
[application]-restage	reset build status to unbuilt
[application]-reconfigure	reset build status to unconfigured

The targets for each selected application are called during the the appropriate core target runs.

Refer to the output of make help or the Factory Make document for more information.

Using the Build Output

The showoutput target describes the output of the Factory build and the location of the output files relative to the current build directory. Refer to the Timesys Recommended Workflow, Factory Best Practices Cookbook, and Navigating the Factory Build Output documents for more information.

Using the Toolchain

The toolchain sub-directory within build is immediately exportable via the PATH environment variable for use as a cross toolchain. For the best results, set PATH to the full path to the toolchain/ccache and toolchain/bin directories within your build directory before the rest of your path. For example, using the shell expansion of $PWD for the current working directory:

export PATH=$PWD/build_[arch]-timesys-linux-[libc]/toolchain/ccache:$PWD/build_[arch]-timesys-linux-[libc]/toolchain/bin:$PATH

Building the Linux kernel is then just:

make ARCH=[your architecture] CROSS_COMPILE=[arch]-timesys-linux-[libc]- [image target]

Also included within the toolchain are a series of helper scripts to make dealing with software packages that use standard build systems such as Qmake, Cmake, and GNU Autotools easier. These helper scripts wrap the typical commands and correctly invoke the cross tools while passing along any arguments provided to the tool they wrap.

For software that uses Qmake:

# instead of qmake && make
cross_qmake && cross_make

For software that uses CMake:

# instead of cmake && make
cross_cmake && cross_make

For software that uses GNU Autotools:

# instead of ./configure --prefix... && make
cross_configure && cross_make

To install a library built using the above into your cross toolchain, you can use the cross_install_to_toolchain utility which is equivalent to calling:

cross_make install DESTDIR=/path/to/build-[arch]-timesys-linux-[libc]/toolchain

A copy of the bare toolchain is available an an archive named toolchain-initial within the build directory. The toolchain-final contains the bare toolchain along with all of the libraries required to build the current platform installed with via the -host-install target.

Sharing the toolchain with the SDK installer

One of the outputs of the factory platform build is a self-extracting installer that provides a copy of the platform root filesystem, the kernel image, the kernel source tree, and a relocatable copy of the cross toolchain. This is always found in build_*/*development-environment.sh after the build.

Command line development only requires setting the $PATH as prompted by the installation output. The installer automatically registers the cross toolchain with Timestorm.

Using the RFS

The rfs staging area within the build directory is not directly exportable as it is missing several final configuration steps that occur during the rfs-images target. The final RFS configuration steps include creating the basic device files required to boot the platform.

The images/rfs sub-directory within build contains the final RFS images in the selected formats.

Using Packages

The packages sub-directory within build contains individual packages in the desired packaging format, if enabled. These can be installed/exploded into an existing RFS or used to create a new RFS. Each package contains the unstripped, full output of the individual application. The packages also includes include files, static libraries, and documentation/data that may be stripped from the RFS by the build system if depending on the pruning options that had been selected.

Upgrading the Factory

Timesys is constantly putting out updated releases of the factory that include new applications as well as updates and fixes for existing applications.

The Timesys factory checks for updates using the checkupdates target.

$ make checkupdates

Upgrading the Factory Build Engine

The build engine itself has regular releases available from the Timesys Git repository.

Once a newer release is available, Timesys recommends backing up the existing factory directory before extracting the new release. The existing platform configuration can then be copied over from the old directory to the new directory. All of the configuration is stored in the Timesys Factory work order. Once copied over, the new factory release will build the existing, unchanged platform definition.

Upgrading the Platform Configuration

The checkupdates target generates a report of what is different between the current platform configuration and the recommended defaults from Timesys. These defaults are updated with each new Factory release to include additional patches, configuration files, and build time configuration options.

Each change can be individually imported into the platform configuration by running the update target. This steps through each item reported by checkupdates and identifies what has changed along with helpful information on why it is relevant to the current configuration.

To accept all of the updated Timesys defaults, run the update-noprompt make target.

Customizing and Extending the Factory Build System

It is important for the same environment to support the initial reference platform prototyping work as well as the full custom production and maintenance phases. The Factory comes with the tools used by Timesys to add applications to the configuration menu and the easy-to-use make based build framework. For custom hardware, the target definition framework can also be used to add custom targets to the factory beyond those provided by Timesys.

More information

Getting Started Guides for Supported Reference Platforms
Timesys Recommended Workflow
Factory Best Practices Cookbook
Navigating the Factory Build Output
Factory Troubleshooting
Hacking the Factory