Chapter 3 Building and Build Tools

This chapter describes how to build a ChorusOS system image from source code.

The ChorusOS Build Process

This section describes how to generate ChorusOS systems from unmodified source code. It is assumed here that you have already installed the source code version of the ChorusOS operating system.

The ChorusOS Build Process

The following procedure outlines the stages of the build process.

1. Create a build directory

   Create a build (working) directory where ChorusOS binaries are built

2. Create the Makefile

   Use the configure build tool in build_dir to create the build Makefile and supporting files.

   See "Component Configuration" for information about configure and "Makefile" for an example of a Makefile.

3. Make the Makefile target

   Make the default Makefile target defined in the build directory Makefile, using the make command. This creates configuration files for building the system image and associated executables.

4. Make other Makefile targets as necessary

   Use make to make any other Makefile targets required; for example, the ChorusOS system image or the target board root file system.

5. Configuration

   Configure the system image features, tunables and initialization files.

Building a Standard ChorusOS System

For full details of how to install a ChorusOS operating system, see the ChorusOS 5.0 Installation Guide. This section only addresses the build process after installation.

Source Path

Depending on your target family, you will use different source code products. Each product has different installation directories. See the ChorusOS 5.0 Installation Guide for further details. The default path for a source package is source_dir.

For your convenience, create an environment variable to shorten your source path.

host% setenv SOURCE = 
/opt/SUNWconn/SEW/5.0-processor_family/chorus-family/src/
host% 

Source File Organization

You receive source packages in read-only mode. Keeping source files in source_dir, separate from your work directory, has the following advantages:

• It prevents the source code from being corrupted during a build.

• It allows you to generate configurations for different target machines.

• It permits several users to use the same source code simultaneously.

If you need to modify the source code, use your own copy of the initial source package.

Families, Targets and Profiles

Table 3-1 gives the profile and board-dependent components (such as BSP and boot) to be used with the configure command. The paths are given relative to source_dir.

Components

Table 3-2 lists the main source components in a ChorusOS source delivery and the associated directories which are created in your source directory during the installation process.

System Generation

This section describes how to generate a standard ChorusOS system image. Standard system generation builds a non-customized version of the operating system.

During the build you use the following commands:

configure

Creates the build-tree Makefiles.

See the configure(1CC) man page for more information.

make

Makes the source, object and binary files.

See the make(1S) man page for more information.

imake

Configures features

mkmk

Configures features

Component Configuration

Components are configured using rhe configure command. The configure command features three options:

-f

Chooses the predefined profile for the PowerPC, ppc60x family, for example:

configure -f source_dir/mkernel/sys/ppc60x/ppc60x

This selects the NUCLEUS source component, containing a definition of the variables for the build.

-s

Selects the ChorusOS source components to be included in the build of your system image, for example:

configure -s source_dir/nucleus/bsp/powerpc/mcp7xx \
      source_dir/nucleus/bsp

The components included determine the identity of the image. In this case, you have included the boot and DRV components in source.

-b

Includes binary components in your system image.

The configure command searches the directories specified by the -s and -b options for the Makefile.src and Makefile.bin files and any file corresponding to Makefile.*.src or Makefile.*.bin. The command displays each component as it adds it to the configuration. The configure command creates two files in build_dir, Makefile and Paths.

System Image Generation

A system image is created from components you have configured using the configure command. The system image is created automatically, in four stages:

1. Selecting the System Image: Choose which of the configured components to include in your system. The system images are defined in:

   • The Makefile.bin file of the NUCLEUS component:

     source_dir/nucleus/sys/common/Makefile.bin

   • The conf directory:

     build_dir/conf/mkimage/mkimage.xml

   Once you have selected your system image, you can use the make command in two ways to build your system image:

   • Referencing the system image name:

     host% make system_image_name

   • Building all configured components in your work directory:

     host% make

   The make command automatically performs steps 2, 3 and 4.

2. Compilation: The default action of make is to compile everything in your work directory, but not to produce a bootable system image. This is because configure might be used to build components which are not directly related to ChorusOS systems.

   Compilation can last from 5 minutes to more than an hour, depending on the host you are using and the amount of new files being built. For the chorus system image, the make is as follows:

   host% make chorus
   

3. Rebuilding the configurable components: If the configuration of the system has changed since the last make, some actors might need to be re-linked. The make command checks if any configurable actors require re-linking.

   Running obj/act/pmm/Makefile
   build_dir/build-DEVTOOLS/host/bin/configurator -c build_dir/conf/
   ChorusOS.xml 
   -action configure
   Running obj/act/sysdump/Makefile
   Running obj/dbg/Makefile
   Running obj/kern/Makefile
   Running obj/chorus.sbin/cinit/hrCtrl/Makefile
   Running obj/chorus.sbin/cinit/rshd/Makefile
   Running obj/sys/Makefile
   

4. Building the System Image: Once the necessary actors have been re-linked, the make command calls mkimage. This generates the system image.

   Start mkdrv
   Finish mkdrv
   Start mkimage
     Brief log file: build_dir/image/RAM/chorus/log.brief
     Verbose log file: build_dir/image/RAM/chorus/log.verbose
     Layout file: build_dir/image/RAM/chorus/layout.xml
   Image file: build_dir/chorus.RAM
   Finish mkimage
   

Once you have built your system image, build_dir contains a build directory for each source component included in the build.

Build Makefile Targets

The table below covers the standard build makefile targets you can make without altering the source code, from the top level Makefile in the work directory.

host% make reconfigure NEWCONF='-s /home/user/chorus/my_app' 

Examples of Building a System Image

Here are two examples of how to create a system image using the steps outlined above. It is presumed that you have already installed the binary and source components for your chosen family.

Standard System Generation

1. Create a work directory:

   host% mkdir build_dir
   

2. Change to the work directory:

   host% cd build_dir
   

3. Use the configure command with a build profile and a selection of components:

   host% source_dir/dev_tools/configure  \
           -f source_dir/nucleus/sys/ppc60x/ppc60x \
           -s source_dir/nucleus/bsp/powerpc/mcp7xx \
           -s source_dir/nucleus/bsp \
           -s source_dir/os \
           -b DIST-CDS-powerpc-SOLARIS
   

4. Create a bootable system image:

   host% make
   [...]
   host% make chorus
   

Generation of a kernonly System

It is possible to generate a system containing only the generic microkernel code, board--specific drivers, and the generic microkernel driver component for a specific board. This system is called a kernonly System.

1. Create a work directory:

   host% mkdir build_dir
   

2. Change to the work directory:

   host% cd build_dir
   

3. Run the configure command:

   host% sh source_dir/dev_tools/configure  \
           -f source_dir/nucleus/sys/ppc60x/ppc60x \
           -s source_dir/nucleus/bsp/powerpc/mcp7xx \
           -s source_dir/nucleus/bsp \
           -b DIST-CDS-powerpc-SOLARIS
   

4. Create a bootable system image:

   host% make
   [...]
   host% make kernonly
   

Build Directory Layout

The following table describes the build directory layout resulting after a build of both a standard system image and a target root file system in the build_dir directory.

Build Directories

The make command creates a build directory, in build_dir, for each component included in the system image created. For example, build-BSP, build-NUCLEUS, and so on. Each build directory contains the binary code for the corresponding component.

Paths

The configure command creates the Paths file in build_dir. For each source component, the Paths file defines two subdirectories, one located in source_dir and one in build_dir.

The ChorusOS source code environment will not allow modification of any file outside your work directory. Consequently, regardless of where the source directories of a component are kept, they will be compiled in that component's subdirectory in build_dir. An example Paths file for UltraSPARC is shown in

Example 3-1 A Paths File

BUILD_DIR=build_dir
NUCLEUS=/install_dir/chorus-usparc/kernel
NUCLEUS_DIR=/install_dir/chorus-usparc/kernel
BSP=/source_dir/nucleus/bsp/usparc/cpxxxx
BSP_DIR=build_dir/build-BSP
DRV=/source_dir/nucleus/bsp
DRV_DIR=build_dir/build-DRV
OS=/install_dir/chorus-usparc/os
OS_DIR=/install_dir/chorus-usparc/os
FLITE=/install_dir/chorus-usparc/opt/Flite
FLITE_DIR=/install_dir/chorus-usparc/opt/Flite
DEVTOOLS=/install_dir/chorus-usparc/tools
DEVTOOLS_DIR=/install_dir/chorus-usparc/tools
CDS=/install_dir/chorus-usparc/tools
CDS_DIR=/install_dir/chorus-usparc/tools
CDS60=/install_dir/chorus-usparc/tools
CDS60_DIR=/install_dir/chorus-usparc/tools
CHSERVER=/install_dir/chorus-usparc/tools
CHSERVER_DIR=/install_dir/chorus-usparc/tools
CHTOOLS=/install_dir/chorus-usparc/tools
CHTOOLS_DIR=/install_dir/chorus-usparc/tools
EWS=/install_dir/chorus-usparc/tools
EWS_DIR=/install_dir/chorus-usparc/tools

Makefile

The Makefile produced using the configure command includes all the Makefiles for each component. An example of a Makefile for UltraSPARC is shown below:

Example 3-2 A Makefile

all:: DEVTOOLS.all
make = $(MAKE)

ROOT =

include Paths
include /install_dir/chorus-usparc/kernel/Makefile.bin
include
/source_dir/nucleus/bsp/usparc/cpxxxx/Makefile.bin
include
/source_dir/nucleus/bsp/usparc/cpxxxx/Makefile.src
include /source_dir/nucleus/bsp/Makefile.bin
include /source_dir/nucleus/bsp/Makefile.src
include /install_dir/chorus-usparc/os/Makefile.bin
include /install_dir/chorus-usparc/opt/Flite/Makefile.bin
include /install_dir/chorus-usparc/tools/Makefile.bin
include /install_dir/chorus-usparc/tools/Makefile.CDS.bin
include /install_dir/chorus-usparc/tools/Makefile.CHSERVER.bin
include /install_dir/chorus-usparc/tools/Makefile.CHTOOLS.bin
include /install_dir/chorus-usparc/tools/Makefile.EWS.bin

COMPONENTS =  NUCLEUS BSP DRV OS FLITE DEVTOOLS CDS CDS60 CHSERVER CHTOOLS
 EWS

CLEAN =  $(BSP_DIR) $(DRV_DIR)
clean:; rm -rf $(CLEAN)
DISTCLEAN =  $(BSP_DIST) $(DRV_DIST)
dist: BSP.dist DRV.dist
distclean:; rm -rf $(DISTCLEAN)
veryclean: clean distclean

reconfigure: ; cd /build_dir; sh
../install/5.0-UltraSPARC/chorus-usparc/tools/configure -s
../install/5.0-UltraSPARC/chorus-usparc/kernel
../install/5.0-UltraSPARC/chorus-usparc/src/nucleus/bsp/usparc/cpxxxx
../install/5.0-UltraSPARC/chorus-usparc/src/nucleus/bsp -b
../install/5.0-UltraSPARC/chorus-usparc/os ../install/5.0-UltraSPARC/
chorus-usparc/opt/Flite
../install/5.0-UltraSPARC/chorus-usparc/tools $(NEWCONF)

The clean, dist, reconfigure, all and root makefile targets can be present in makefiles.

In the Makefile shown above, the all makefile target is followed by ::, meaning you can have multiple update rules. You must use :: if the make command is to work.

The top level Makefile in build_dir includes a Makefile.bin and a Makefile.src for each source component. You receive these files with your source delivery. This ensures the compatibility of components even if they are built using different development tools.

Makefile.bin

Below is an example of a Makefile.bin file, in this case for the KTS, or microkernel tests, component.

The Makefile.bin file identifies the component, and provides a list of components it requires to work.

Example 3-3 Makefile.bin File for the C_OS

The following example shows a Makefile.bin file for the C_OS, created using mkmerge. This is used to build the root tree.

#****************************************************************
#
# Component = os
#
# Synopsis  =   
#
# Copyright 1999,2001  Sun Microsystems, Inc. All rights reserved. 
#
#****************************************************************
#
# #ident  "@(#)Makefile.bin 1.16     01/10/03 SMI"
#
#****************************************************************

COMPONENT += OS
ROOT      += $(OS_DIR)/root $(BUILD_DIR)/obj/prebuild/os/root
PREBUILD  += $(OS_DIR)/prebuild

OS.all:: NUCLEUS.all

OS_XML = os.xml sys_rule.xml sys_action.xml cinit.xml 
cinit_action.xml hrCtrl.xml hrCtrl_action.xml
OS_SYSADM = sysadm.ini


xml:: DEVTOOLS.all $(OS_DIR)/exports.lst
        @sh $(DEVTOOLS_DIR)/cpxml $(BUILD_DIR)/conf/mkconfig 
        $(OS_DIR)/conf/mkconfig $(OS_XML)
        @sh $(DEVTOOLS_DIR)/cpxml $(BUILD_DIR)/conf $(OS_DIR)/conf 
        $(OS_SYSADM)
        @sh $(DEVTOOLS_DIR)/cpxml $(OS_DIR) $(OS) Makefile.bin

root:: $(BUILD_DIR)/root/etc/resolv.conf

$(BUILD_DIR)/root/etc/resolv.conf:
        @mkdir -p $(BUILD_DIR)/root/tmp
        @chmod ugo+rwx $(BUILD_DIR)/root/tmp
        @mkdir -p $(BUILD_DIR)/root/dev
        @mkdir -p $(BUILD_DIR)/root/image
        @mkdir -p $(BUILD_DIR)/root/etc
        @mkdir -p $(BUILD_DIR)/root/proc
        @mkdir -p $(BUILD_DIR)/root/var/run
        @mkdir -p $(BUILD_DIR)/root/var/log
        @mkdir -p $(BUILD_DIR)/root/var/db
        @chmod ugo+rwx $(BUILD_DIR)/root/var/run
        @chmod ugo+rwx $(BUILD_DIR)/root/var/log
        @touch $(BUILD_DIR)/root/var/log/messages
        @chmod ugo+rw $(BUILD_DIR)/root/var/log/messages
        @[ -f /etc/resolv.conf ] && cp /etc/resolv.conf $@ || touch $@

XML2 += mkconfig/os.xml

Example 3-4 Makefile.bin file for the EXAMPLES component

The following example shows a Makefile.bin file for the EXAMPLES component.

#****************************************************************
#
# Component = examples
#
# Synopsis  =   
#
# Copyright 1999 Sun Microsystems, Inc. All rights reserved. 
#
#****************************************************************
#
# #ident  "@(#)Makefile.bin 1.4     01/10/03 SMI"
#
#****************************************************************

COMPONENT += EXAMPLES
ROOT      += $(EXAMPLES_DIR)/root

EXAMPLES.all::

Makefile.src

The Makefile.src file is more complex than the Makefile.bin file, as it describes how the component is compiled using the mkmk tool.

The Makefile.src file for the KTS component is shown below, as an example. The KTS Makefile.src file provides following information:

• It identifies the component

• It identifies the dependency of KTS.all on the NUCLEUS component and on the DONE file. The DONE file is explained further in "DONE".

• It provides information regarding compilation

Example 3-5 Makefile.src File for Flite

The following example shows a Makefile.src for Flite, created using mkmerge.

#****************************************************************
#
# Component = flite
#
# Synopsis  =   
#
# Copyright 1999,2001  Sun Microsystems, Inc. All rights reserved. 
#
#****************************************************************
#
# #ident  "@(#)Makefile.src 1.9     01/10/03 SMI"
#
#****************************************************************

all:: FLITE.all

FLITE.all:: $(OS_DIR)/exports.lst
FLITE.all:: $(FLITE_DIR)/DONE

$(FLITE_DIR)/exports.lst:
        rm -rf $(FLITE_DIR)
        $(DEVTOOLS_DIR)/host/bin/mkmerge -s $(FLITE) -t $(FLITE_DIR)

$(FLITE_DIR)/Makefile: $(FLITE_DIR)/exports.lst
        rm -f $(FLITE_DIR)/Makefile
        cd $(FLITE_DIR); $(DEVTOOLS_DIR)/host/bin/mkmk -t $(NUCLEUS_DIR)

$(FLITE_DIR)/DONE: $(FLITE_DIR)/Makefile
        sh $(DEVTOOLS_DIR)/resync FLITE -f $(FLITE) -s $(FLITE_DIR)
        cd $(FLITE_DIR); $(make)
        touch $(FLITE_DIR)/DONE

FLITE_DIST = $(BUILD_DIR)/dist-FLITE
FLITECP = lib
FLITE.dist: FLITE.all
        rm -rf $(FLITE_DIST)
        mkdir -p $(FLITE_DIST)
        cp $(FLITE)/Makefile.bin $(FLITE_DIST)
        cd $(FLITE_DIR); cp -pr $(FLITECP) $(FLITE_DIST)

##
$(OS_DIR)/DONE: $(FLITE_DIR)/DONE

Example 3-6 Makefile.src for the drivers

The following example shows a Makefile.src for the drivers, created with Imake.

#****************************************************************
#
# Component = drivers
#
# Synopsis  =   
#
# Copyright 1998,2001  Sun Microsystems, Inc. All rights reserved. 
# 
#
#****************************************************************
#
# #ident  "@(#)Makefile.src 1.3     01/10/03 SMI"
#
#****************************************************************

MYDRV_SRC = $(MYDRV)/src

all:: MYDRV.all 

MYDRV.all:: NUCLEUS.all
MYDRV.all:: $(MYDRV_DIR)/DONE

$(MYDRV_DIR)/DONE : $(MYDRV_DIR)/Makefile
        cd $(MYDRV_DIR); $(make)
        touch $(MYDRV_DIR)/DONE

$(MYDRV_DIR)/Makefile: $(MYDRV_SRC)/Imakefile
        sh $(DEVTOOLS_DIR)/ChorusOSMkMf $(BUILD_DIR) -s $(MYDRV_SRC) 
        -b $(MYDRV_DIR) -d $(MYDRV_DIR)
        cd $(MYDRV_DIR); $(make) Makefiles

The all Makefile Target and Component Dependency

Each component implements the component.all rule, which is defined in the component's Makefile.src file. This rule tells you what other components this component is dependent upon. The component.all rule in the Makefile.src implements the rule, building the component in its own build directory. If this first component depends on a second component, the dependency rule is expressed in the Makefile.src file of the first component, as shown below:

component1.all :: component2.all

If the dependency is valid only for the build process, the dependency rule is expressed in the Makefile.src file.

DONE

When a component is compiled correctly, its Makefile.src file creates a file called DONE in the build--COMPONENT directory. The DONE file prevents make from entering a component's build directory when there is nothing else to compile. If you run the make command, and the Makefile.src file has already created the DONE file, nothing will happen. These DONE files must be removed if a component has been modified, and the dependent components need to be re-linked.

For example, to remove the DONE file for the NUCLEUS component:

host% rm -f build-NUCLEUS/DONE

Run make now and it will enter the NUCLEUS component. Run the make command a second time and you will get no output, as the DONE file is now present.

conf

The conf directory contains ECML files which describe the current ChorusOS configuration.

The ChorusOS.xml file is the top-level configuration file. It contains references to all other configuration files in the conf directory. When building the ChorusOS operating system from the source code, XML configuration files are copied from the various component source files into the conf directory.

obj

The obj directory contains all necessary configurable actors. For example, the PMM component is compiled in build_dir/build-NUCLEUS. Its object files are copied into build_dir/build-NUCLEUS/obj and then linked in the build_dir/obj directory.

image

The image directory is used during the creation of a system image. The information contained within this directory includes temporary files, log files, symbol tables, and relocated binary files.

ChorusOS Build Options

This section demonstrates the use of some optional build features.

Rebuilding a Component

You can delete any of the directories in build_dir during the generation process. If the directory is necessary, the make command will rebuild it. For example, you can remove the boot component and then run make, which will regenerate the component, if necessary.

host% rm -rf build-BSP/ 
host% make build

Rebuilding the conf directory

To return to a previous configuration, remove the conf directory, or some files from the conf directory. This returns the system to the default configuration or to the configuration you updated in the source configuration files. Even if you have not altered the configuration you can rebuild the conf files as follows:

host% rm -rf conf/
host% make xml

Binary Distribution Builds

Binary distributions are prebuilt components that speed the compilation process. To build a binary distribution of the EXAMPLES component, make the EXAMPLES.dist makefile target.

host% make EXAMPLES.dist

The EXAMPLES.dist makefile target creates an independent distribution of examples as a subdirectory, dist-EXAMPLES, of the build directory. This examples directory can be displaced and handled as a single entity, and used as directory of binaries with the -b option of the configure(1CC) build tool.

Updating the Source Configuration

The reconfigure makefile target adds components to an existing configuration. For example, you add the EXAMPLES component to an existing system in build_dir, as follows:

host% make  reconfigure NEWCONF='-s source_dir/opt/examples'
host% make

Build the Target NFS Root

The root makefile target lets you copy files from components into the build_dir/root directory.

For example, as the EXAMPLES component contains binary files that the target machine must see, use the make root command to copy the binary files of the EXAMPLES component into the build_dir/root directory as follows:

host% make root 

The build_dir/root directory now contains the binary files of the EXAMPLES component. You can run this component on a target machine where build_dir/root can be NFS mounted.

Using Binary Files Instead of Source Files

Taking the EXAMPLES component as an example, to use the EXAMPLES component's binary files, you must remove the current configuration of that component. There is no specific command to achieve this. Follow these four steps:

1. Edit the reconfigure rule at the end of the top-level Makefile by removing the following line in the source file:

   -s source_dir/opt/examples

2. Remove the component's build directory and run make reconfigure:

   host% rm -rf build-EXAMPLES/ 
   host% make reconfigure
   

3. Add the application's binary files:

   host% make reconfigure NEWCONF='-b dist-EXAMPLES' 
   

4. Run the make command

   host% make 
   

Verbose Mode Builds

To make all component builds in a build directory generate more messages, define a null macro, SILENT=, in the Paths file.

host% grep -i SILENT Paths
host% echo 'SILENT=' >> Paths
host% grep -i SILENT Paths
SILENT=
hosthost% make 

Once you have defined the null macro, SILENT=, builds generate status messages for every action taken.

Debug Mode Builds

To enable debugging for a component, you must build it with the FREMOTEDEB macro set to ON. When this macro is set in the paths file, it enables debugging information to be generated for all components.

host% grep -i FREMOTEDEB Paths
host% echo 'FREMOTEDEB=ON' >> Paths
host% grep -i FREMOTEDEB Paths
FREMOTEDEB=ON
host% make make-target
host% make

Components built with FREMOTEDEB=ON include debugging information and are therefore larger than components with FREMOTEDEB=OFF.

Forced Rebuilds

To force an unchanged component to be rebuilt, remove the DONE file created during the previous build. For example, to force re-compilation of all components previously built in the build directory:

host% cd build_dir
host% find build_dir -name DONE -exec rm -f {} \;
host% make 

ChorusOS Build Tools

The following table provides a quick reference for the tools used when managing ChorusOS system builds.

Further descriptions of most tools described in the table are available in the ChorusOS man pages. Precompiled binary ChorusOS operating system tools are located in the tools/host/bin subdirectory of the installation directory.