Install the binary components of the ChorusOS 4.0 product before you work with the source delivery. You will use the same method to build the source files. Your installation must include the TOOLS and the EXAMPLES components.
Before you read this Chapter, read
ChorusOS 4.0 Installation Guide for Solaris Hosts, to understand how to install ChorusOS binary files on a SolarisTM operating environment.
ChorusOS 4.0 Installation Guide for Windows NT Hosts, to understand how to install ChorusOS binary files on a Windows NT host.
The relevant family documentation from the ChorusOS 4.0 Target Family Documentation Collection
In this Chapter, the following steps are described.
Install source components.
Create a work directory.
Choose the components to be included in your system image and configure them. The configure command creates a Paths file and a Makefile in your work directory.
Use the make command to compile the system image. In your work directory, the make command creates conf, obj and image directories and a build directory for each component included in the system image.
The files and directories that you have created during the above steps are discussed in this Chapter.
Ask your system administrator to supply you with ChorusOS binary and source files. Once you have read the instructions in the ChorusOS 4.0 installation guides, install the source files and the AnswerBook documentation.
Depending on your target family, you will use different source code products. Each product has different installation directories. See ChorusOS 4.0 Target Family Documentation Collection for further details. The default PATH for a source package is:
/opt/SUNWconn/SEW/4.0/chorus-<family>/srcwhere each family is a group of processors, such as PowerPC. This will be your source directory, referred to in this document as <src_dir>.
For your convenience, create an environment variable to shorten your source PATH.
You receive source packages in read-only mode. The fact that the source files are kept in the source directory, 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 targets.
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 that you received.
Table 2-1 gives the profile and board dependent components (such as BSP, boot and family specific driver code) to be used with the configure command. The PATHs are given relative to <src_dir>.
Table 2-1 List of board dependent componentsPaths | Component |
PowerPC Board | |
nucleus/ppc60x/ppc60x | profile |
nucleus/bsp/powerpc/genesis2 | bsp |
nucleus/bsp/powerpc | driver family |
MCP750 board | |
nucleus/ppc60x/ppc60x | profile |
nucleus/bsp/powerpc/mcp750 | bsp |
nucleus/bsp/powerpc | driver family |
SBC8260 board | |
nucleus/mpc8260/mpc8260 | profile |
nucleus/bsp/powerpc/sbc8260 | bsp |
nucleus/bsp/powerpc | driver family |
MPC860 board | |
nucleus/mpc860/mpc860 | profile |
nucleus/bsp/powerpc/mpc8xxADS | bsp |
nucleus/bsp/powerpc | driver family |
CP1500 board | |
nucleus/usparc/usparc | profile |
nucleus/bsp/usparc/cp1500 | bsp |
nucleus/bsp/usparc | driver family |
i386AT board | |
nucleus/x86/x86 | profile |
nucleus/bsp/x86/i386at | bsp |
nucleus/bsp/x86 | driver family |
All examples given in this document are for the PowerPC family and the genesis2 board. For further information on the family and board that you are using, refer to the ChorusOS 4.0 Target Family Documentation Collection.
Table 2-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.
Table 2-2 Source components in a ChorusOS 4.0 delivery and the associated files.Component | Directory | Description |
NUCLEUS |
<src_dir>/nucleus |
generic kernel code + family profiles |
DRV |
<src_dir>/nucleus/bsp/drv |
generic kernel drivers |
DRV_F |
<src_dir>/nucleus/bsp/<family> |
family specific drivers |
BSP | <src_dir>/nucleus/bsp/<family>/<target> | board specific boot code (BSP) |
OS |
<src_dir>/os |
Operating System (network, POSIX) |
IOM |
<src_dir>/iom |
I/O Manager, (drivers, file systems, IP protocol stacks) |
This section describes the operations necessary to generate a standard system image of the ChorusOS operating system. Standard system generation builds a non-customized version of the operating system.
During the build you use two commands:
The configure command: See the configure(1CC) man page for more information.
The make command: See the make(1S) man page for more information.
You will use three parameters with the configure command:
Use the -f option to choose the predefined profile for the PowerPC, ppc60x family (Table 2-1), such as;
-f <src_dir>/nucleus/sys/ppc60x/ppc60xIt selects the NUCLEUS source component which contains a definition of variables for the build.
Use the -s option to select the ChorusOS source components to be included in the build of your system image (Table 2-2), such as;
-s <src_dir>/nucleus/bsp/powerpc/genesis2 \ <src_dir>/nucleus/bsp/powerpc \ <src_dir>/nucleus/bsp/drvThe components included determine the identity of the image. In this case, you have included the BSP, DRV and DRV_F components.
Use the -b option to include 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, Makefile and Paths in <work_dir>. These files are discussed later in this Chapter.
A system image is created from components which you have configured using the configure command. Even though you type a single command, make, the system image is created over four steps, to produce the binary files corresponding to the source components.
Selection of the System Image: Choose which of the configured components you will include in your sytem. By changing the components included, you alter the resultant system. The system images are defined in:
The Makefile.bin file of the NUCLEUS component:
<src_dir>/nucleus/sys/Makefile.bin
<work_dir>/conf/mkimage/mkimage.xmlThe conf directory is discussed in the next section of this Chapter. 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:
make <system image_name>
Building all configured components in your work directory:
make build
The make command automatically performs the next three steps as shown here.
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 may 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. For the chorus system image, the make build output includes:
sh <work_dir>/build-NUCLEUS/mkbuild chorus
Rebuilding the Configurable Components: If the configuration of the system has been changed since the last time the make command was run, using the ews GUI tool or the configurator command, then some actors may need to be relinked. The make command checks if any configurable actors need to be relinked.
Running obj/act/pmm/Makefile <bin_dir>/tools/host/bin/configurator -c /<work_dir>/conf/ChorusOS.xml -action configure Running obj/dbg/Makefile Running obj/kern/Makefile Running obj/os/admin/sys/Makefile Running obj/os/am/sys/Makefile Running obj/os/cinit/ftpd/Makefile Running obj/os/cinit/hrCtrl/Makefile Running obj/os/cinit/rshd/Makefile Running obj/os/cinit/teld/Makefile Running obj/os/iom/sys/Makefile
Building of the System Image: Once the necessary actors have been relinked, the make command calls mkimage. This produces the system image.
Start mkimage Brief log file: /<work_dir>/image/RAM/chorus/log.brief Verbose log file: /<work_dir>/image/RAM/chorus/log.verbose Layout file: /<work_dir>/image/RAM/chorus/layout.xml Image file: /<work-dir>/chorus.RAM Finish mkimage
Once you have built your system image, the work directory contains a build directory for each source component you have included in the build.
Here are two examples of how a system image is created using the steps outlined above. It is presumed that you have already installed the binary and source components for your chosen family, as outlined at the beginning of this Chapter.
Example 1 illustrates standard system generation. The image which you create includes the generic kernel code, PowerPC drivers targeted for the genesis 2 board, generic kernel drivers, and the OS and the IOM components. This is termed a chorus system image.
Create a work directory:
host% mkdir work_dir
Change to the work directory:
host% cd work_dir
Use the configure command with a build profile and a selection of components:
host% configure -f <src_dir>/nucleus/sys/ppc60x/ppc60x \ -s <src_dir>/nucleus/bsp/powerpc/genesis2 \ <src_dir>/nucleus/bsp/powerpc \ <src_dir>/nucleus/bsp/drv \ <src_dir>/os \ <src_dir>/iom
Create a bootable system image named chorus:
host% make chorus
You could also type make build, and get the same result, as this system image is already defined in the Makefile.bin file of the NUCLEUS component.
The system image you create in this Example is the kernonly system and contains the generic kernel code, PowerPC drivers, and kernel generic driver component targeted for the genesis 2 board. You create this image in the first steps of porting a system to a new board. See ChorusOS 4.0 Porting Guide for more details.
Create and change to a work directory as in Example 1.
Use the configure command:
host% configure -f <src_dir>/nucleus/sys/ppc60x/ppc60x \ -s <src_dir>/nucleus/bsp/powerpc/genesis2\ <src_dir>/nucleus/bsp/powerpc \ <src_dir>/nucleus/bsp/drv
Create a bootable system image named kernonly, using the make command:
host% make kernonly
The configure command creates two files, Makefile and Paths. The make command creates a directory for each component included in the system image, as well as a conf, obj and image directory. These files and directories are discussed in this section.
Table 2-3 lists the files and directories generated in your work directory by the configure and make commands.
Table 2-3 Files and Directories generated by the configure and make commandsFiles/Directories | Description |
Makefile | top level Makefile |
Paths | paths to the source or binary components |
conf/ | system configuration files |
obj/ | object files used by configurable actors |
image/ | image generation files |
build-NUCLEUS/ | build directory for nucleus |
build-DRV/ | build directory for generic drivers |
build-BSP/ | build directory for the board specific boot code |
build-DRV_F/ | build directory for the family specific drivers |
build-OS/ | build directory for the POSIX system |
build-IOM/ | build directory for the I/O manager |
The make command creates a build directory, in your work directory, for each component included in the system image created. In Table 2-3, there is a build directory for the NUCLEUS (build-NUCLEUS), generic drivers (build-DRV), board specific code (build-BSP), family specific drivers (DRV_F), operating system (build-OS) and I/O manager (build-IOM). Each build directory contains the binary code for the corresponding component.
The Paths file is created in your work directory by the configure command. For each source component, the Paths file defines two subdirectories, one located in <src_dir> and one in <work_dir>. For example, for the BSP component there is a BSP directory, which is the component source directory, and BSP_DIR, which is the directory where the component will be generated. For binary components, only one directory, that is the BSP_DIR directory, is defined.
... BSP= <src_dir>/nucleus/bsp/powerpc/genesis2 BSP_DIR= <work_dir>/build-BSP ...
The ChorusOS production environment will not modify any file outside of your work directory. This means that regardless of where the source directories of the BSP component are, they will be compiled in the build-BSP subdirectory of your work directory.
The Makefile produced by the configure command includes all the Makefiles for each component. View the Makefile.
all::DEVTOOLS.all PROFILE = -f <src_dir>/nucleus/sys/ppc60x/ppc60x include Paths include <src_dir>/nucleus/bsp/drv/src/Makefile.bin include <src_dir>/nucleus/bsp/drv/src/Makefile.src include <src_dir>/nucleus/bsp/powerpc/Makefile.bin include <src_dir>nucleus/bsp/powerpc/Makefile.src include <src_dir>/nucleus/bsp/powerpc/genesis2/Makefile.bin include <src_dir>/nucleus/bsp/powerpc/genesis2/Makefile.src include <src_dir>/os/Makefile.bin include <src_dir>/os/Makefile.src include <src_dir>/iom/Makefile.bin include <src_dir>/iom/Makefile.src include <bin_dir>/tools/Makefile.bin include <bin_dir>/tools/Makefile.CDS.bin include <src_dir>/nucleus/sys/common/Makefile.bin include <src_dir>/nucleus/sys/common/Makefile.src include <bin_dir>/tools/Makefile.CHSERVER.bin include <bin_dir>/tools/Makefile.CHTOOLS.bin COMPONENTS = DRV DRV_F BSP OS IOM DEVTOOLS NUCLEUS CDS CHSERVER CHTOOLS CLEAN = $(DRV_DIR) $(DRV_F_DIR) $(BSP_DIR) $(OS_DIR) $(IOM_DIR) $(NUCLEUS_DIR) clean:; rm -rf $(CLEAN) dist: DRV.dist DRV_F.dist BSP.dist OS.dist IOM.dist NUCLEUS.dist reconfigure: ; cd /<work_dir>; \ sh <bin_dir>/tools/host/bin/configure \ -f /<src_dir>/nucleus/ppc60x/ppc60x \ -s /<src_dir>/nucleus/bsp/drv /<src_dir>/nucleus/bsp/powerpc \ /<src_dir>/nucleus/bsp/powerpc/genesis2 /<src_dir>/os /<src_dir>/iom $(NEWCONF)
The clean, dist, reconfigure, all and root make targets may be present in Makefiles. They are discussed at the end of this Chapter in relation to the generation of the ChorusOS system image.
In the Makefile shown above, the all target is followed by :: which means you can have multiple update rules. You must use :: if the make command is to work. Note, also, the clean, dist and reconfigure targets in the Makefile shown here.
The top level Makefile of the work directory 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.
View the IOM Makefile.bin file for the IOM component, found in the <src_dir>/iom directory.
The output states that the component is the IOM component and gives a list of the components that must be present in the operating system if the IOM component is to work. In this case the OS and NUCLEUS components must be present.
The Makefile.src file is more complex than the Makefile.bin file, as it describes how the IOM component is compiled. The IOM component is compiled using the mkmk tool.
View the contents of the Makefile.src file for the IOM component, found in the <src_dir>/iom directory.
You are given the information:
This is an IOM component.
The IOM.all target is dependent on the DRV, NUCLEUS and OS components and on the DONE file.
The conf directory contains files which describe the ChorusOS current configuration. These files are expressed in XML. The details of XML files are provided in Chapter 7, XML Syntax.
ChorusOS.xml is the top level configuration file. It contains references to all other configuration files located in the conf directory, as explained in ChorusOS 4.0 Introduction. When building the ChorusOS operating system from the source code, XML configuration files are copied from the various component source files to the conf directory.
The obj directory contains all necessary configurable actors. For instance, the IOM component is compiled in the build-IOM directory. Its object files are copied to the build-IOM/obj directory and then linked in the obj directory.
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.
If you have created your system image and do not need to manipulate your source delivery further, you will not need to continue reading this document.
This section provides further information on directories and files already discussed in this Chapter.
You can delete any of the directories that were created in your work directory during the generation process. If the directory is necessary, the make command will rebuild it. For example, you can remove the BSP component, which in the examples above provides support for the PowerPC board. Then use the make command, which will regenerate the component, if it is necessary.
host% rm -rf build-BSP/ host% make build
When a component is compiled correctly, its Makefile.src file creates a file called DONE, in the build directory. The DONE file exists to prevent 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 relinked.
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 has again been created.
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 that 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
This section details Makefile make targets discussed in the Makefile section above.
The clean target removes all the build directories from the work directory.
The dist target produces a binary version of each component. Each component can implement a <component>.dist rule in the component's Makefile.src.
The reconfigure target adds parameters, using the NEWCONF macro, to the original configure command.
The all target is the first target in the Makefile and so when the make command is run without an argument make all is run.
The root target copies files from components into the root directory.
Each component implements the <component>.all rule, which is defined in the component's Makefile.bin 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
<component1>.all :: <component2>.allis expressed in the Makefile.bin file of the first component.
If the dependency is valid only for the build process, the dependency rule is expressed in the Makefile.src file.
Verify that you have installed the EXAMPLES component. This source component, which contains a number of small applications, is built on top of the os and nucleus levels (See Table 1-1 for further details of component hierarchy).
The reconfigure target adds components to the initial configuration. Add the EXAMPLES component to your initial work directory, and build it as follows:
host% make reconfigure NEWCONF='-s <src_dir>/opt/examples' host% make
The root target lets you copy files from components into the root directory.
As the EXAMPLES component contains binary files that the target must see, use the make root command to copy the binary files of the EXAMPLES component into the root directory as follows:
host% make root
The root directory now contains the binary files of the EXAMPLES component. You can run this component on a target system where this root directory can be NFS mounted.
To build a binary distribution of the EXAMPLES component, run the following command:
host% make EXAMPLES.dist
This command creates a new directory in your work directory, called dist-EXAMPLES, containing the binary files of the EXAMPLES component.
You can move the component's binary files to any directory as follows:
host% mv dist-EXAMPLES ../Use these binary files instead of the source files by using the binary option of the configure command.
To use the EXAMPLES component's binary files, you must remove the current configuration of the component. There is no specific command to achieve this. Follow these four steps:
Edit the reconfigure rule at the end of the top-level Makefile by removing the following line in the source file
-s <src_dir>/opt/examples
Remove the component's build directory and run make reconfigure as shown here:
host% rm -rf build-EXAMPLES/ host% make reconfigure
Add the application's binary files:
host% make reconfigure NEWCONF='-b dist-EXAMPLES'
Run the make command and notice the output as make rebuilds files in the conf directory.
Usually, compilations of an mkmk or imake component are not verbose. If you want to get the whole trace of the build, just add 'SILENT=' to the Paths file:
host% echo 'SILENT=' >> Paths
To test this modification, compile the EXAMPLES component by configuring the source files:
host% make reconfigure NEWCONF='-s /<src_dir>/opt/examples/'
The previous command has produced another Paths files, so if you add "SILENT=" again and run the make command, you will see a more verbose output.
host% echo 'SILENT=' >> Paths host% make
As the application binary files are already configured, the configure command will skip the binary files and choose to use the source files.
To debug a component, you may need to recompile it with special compilation options. To achieve this for the EXAMPLES component: