The design of the software distribution

This document describes the organization of the software distribution. The software distribution is a subset of the development environment used at Axis Communications AB. Consequently the design of the software distribution follows what happens in the internal CVS repository at Axis. Somewhat simplified one can say that the software distribution comprise the basic Linux system used in almost all Axis products.

The main focus of Axis is network video (cameras, video servers, etc) and traces of this can be seen in the software distribution, especially in the configure-files/common/ directory. One effect of this is that some directories and files are somewhat strangely named. Please note that the software distribution does not include any software related to network video products.

Readers advice

This document is written with 2.10 and 2.20 versions of the software distribution in mind. However, most of the concepts discussed should apply for earlier versions as well.

The AXIS Product Configuration tool

To manage the composition of the software distribution the AXIS Product Configuration tool is used. This tool makes it possible to select which standard C library (gclibc or uClibc), which programs to include, partition sizes, and much more. The AXIS Product Configure tool can be run in several different modes. From a terminal window run make menuconfig to get a menu in the terminal, run make xconfig to get a GUI menu in X or run make config to answer questions in the terminal.

Makefiles for applications, libraries and the kernel

The software distribution is organized in a modular way making it adaptable for various configurations. The source code is organized in directories in the software distribution root directory according to their type; apps for applications, libs for libraries, and os for the Linux kernel. Each application is located in a directory under the apps directory and each library is located in a directory under the lib directory. In most cases each application or library has its own preconfigured Makefile in the source code directory, but some applications and libraries use another method.

The other method makes use of a wrapper Makefile to configure and compile an application or a library. Typically this method is used when the application or library has to be configured via a configure script prior to compile time. Two of the packages that use this wrapper method are the vftpd application and the Linux kernel. Wrapper Makefiles are in many cases located in the packages directory. For example, the wrapper Makefile configuring and compiling vftpd is located in the packages/apps/vftpd/platoon directory while the wrapper Makefile configuring and compiling the Linux kernel is located in the packages/os/linux-2.6 directory. In some cases the wrapper Makefile resides in the apps/<application> or libs/<library> directory. For example, that is the case for the dash shell located in the apps/shells/dash direcory. In this directory you will find a wrapper Makefile and a dash directory that contains the source code.

When building a program that has a wrapper Makefile the wrapper Makefile should be used. For example when configuring or building the Linux kernel it should be interfaced using the wrapper Makefile located in packages/os/linux-2.6. Save yourself for a lot of trouble and use the wrapper Makefile if it exists.

The top-level Makefile

The top-level Makefile 1) is generated by the configure-files/source/functions script that is invoked by the configure script. Since the top-level Makefile is automatically generated it should not be edited by hand. Always run the configure script to regenerate the Makefile.

To add own programs, libraries, scripts, etc. make use of the configure-files/post file.

When executing the make command in the software distribution root directory the complete firmware image is built according to the rules set by the top-level Makefile. More specifically the following will occur:

  1. The init_env file is created.
  2. All tools are built.
  3. The .config file is updated.
  4. The buildtype is configured for each package. This makes the build system aware of the architecture and c-library to be used in the next step. The build type could for example be crisv32-axis-linux-gnuuclibc saying that the system is built for the CRIS v322) architecture and use the uClibc c-library.
  5. All packages (applications, libraries, the kernel, init scripts, etc) are built and installed in the target/<buildtype> directory.
  6. The firmware images are created from the files found in the target/<buildtype> directory.

Important files and directories

Below you find a description of important files and directories found in the software distribution root directory.

.config

File that stores the configuration for the AXIS Product Configure tool, hence the configuration for the product that the software distribution is currently configured for. Observe that this file is overwritten when changing product to develop for. Manage this file by using the AXIS Product Configure tool.

configure

The configure script uses functions in the configure-files/source/functions script to download and install needed packages as well as creating a top-level Makefile. The created Makefile is configured to build the product firmware images according to the configuration files found in the software distribution. This is what happens:

  • If the file “configure-files/pre” exists, it gets sourced. Intended for user specific code.
  • Configure reads the configuration found in the .config file.
  • Configure runs configure-files/common/common and configure-files/devboard/devboard. Both these files are basically a set of if cases selecting (using fetch and sub) which packets to be included based on the configuration in the .config file.
  • If the file “configure-files/post” exists, it gets sourced. Intended for user specific code, mainly for adding applications and libraries to the firmware images.
  • The Makefile is generated.

configure-files/common/common

A file mostly populated with if statements that select which packages to be download and used when building the firmware image. This file is sourced from the configure script and heavily make use of the sub and fetch functions in the configure-files/source/functions script. Under normal circumstances users of the software distribution shouldn't edit these files. If you would like to add applications to the software distribution use the configure-files/post file.

configure-files/devboard/devboard

About the same as the configure-files/common/common file.

configure-files/devboard/products/<product>

The product folders store the default configuration files for the preconfigured products. In each folder the following files are found.

  • .devboard_platform - Description of the product.
  • defconfig - Configuration for the AXIS configure tool.
  • kernelconfig.in3) - The product specific part of the kernel configuration for the Linux 2.6 kernel. The common parts is located in the kernel, in os/linux-2.6/axis_config/.
  • kernelconfig-2.64) - Kernel configuration for the Linux 2.6 kernel.

When a product is configured, usually during the installation of the software distribution, all these files except the .devboard_platform file are copied to the software distribution root directory (the defconfig file is copied to <software distribution root>/.config). And a soft link is created from the software distribution root to the configure-files/devboard/products/<product>/.devboard_platform file.

configure-files/post

This files is intended to be created by the user that needs to add applications, libraries, or other things that previously had to be entered in the configure script or in the configure-files/devboard/devboard or configure-files/common/common files. Making changes in the above mentioned files are not a good idea since updates of the software distribution overwrites them.

The post file is sourced from the configure script just before the creation of the top level Makefile. This is the ideal place for adding custom packages that should be included in the firmware. For example, if an application, my_app, that reside in apps/my_app should be added to the firmware image the following line should be added to the post file.

sub apps/my_app

Read more about how to use sub and fetch in the functions guide.

configure-files/pre

About the same as the configure-files/post file but get sourced very early in the configure script. Therefore it is not suitable for adding custom packages but rather for good for other things, e.g., defining variables.

configure-files/source/functions

The functions script contains all shell functions that can be used by shell scripts to generate a Makefile for building products using GNU make. The most commonly used functions are: fetch and sub. To be brief fetch fetches a package and extract it into the software distribution directory, sub runs fetch and adds the package to the list of packages that shall be compiled (the SUBDIRS variable in the top-level Makefile). For a detailed description on each function consult the functions guide.

init_env

A small script created when running make the first time. The purpose of this file is to set up environment variables needed by the software distribution. As a rule of thumb you should always source this file before starting to work with the SDK in a new shell.

source init_env

or

. init_env

A great deal of effort has gone into making this documentation as correct as possible. The information here is provided “as is”, without warranty or guarantee of any kind. To be on the safe side, always contact us if you are in doubt.

1) The Makefile in the software distribution root directory
2) the architecture that for example ETRAX FS use
3) Applies to 2.20
4) Applies to 2.10 and older
 
axis/software_distribution_design.txt · Last modified: 2009/02/03 15:58 by jesper
 
All text is available under the terms of the GNU Free Documentation License (see Copyrights for details).