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