ChorusOS 5.0 Source Delivery Guide

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.

Table 3-4 Top Level Build Directory Layout


File or directory	Description
`build-BSP/`	Build directory for the boot code
`build-DRV/`	Build directory for drivers
`build-NUCLEUS/`	Build directory for the microkernel
`build-OS/`	Build directory for the POSIX system
`chorus.obp`	Executable system image file (`.obp` image files run on UltraSPARC^TM family targets -- other file extensions exist for other targets)
`conf/`	Contains configuration files, expressed in the Embedded Component Markup Language, for building system images and associated executables; also contains standard system profile files and a standard `sysadm.ini` system image initialization file
`Ident`	Uniquely identifies the components that put together the contents of the build directory
`image/`	Contains files used during the creation of a system image, including temporary files, logs, symbol tables and relocated binaries
`Makefile`	Top level rules for generating build targets; includes `Makefile`s for each of the components used to generate build targets
`obj/`	Contains configurable actors and `make` rules used to build system images and associated executables
`Paths`	Defines installation-dependent paths to components used to build system images and associated executables
`root/`	Contains a complete file system for use on the target running the system image built in the same build directory; typically, `root` on the host is mounted at the root (`/`) on the target after the system is booted

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.

Build Directory Layout

Build Directories

Paths

Example 3-1 A Paths File

Makefile

Example 3-2 A Makefile

Makefile.bin

Example 3-3 Makefile.bin File for the C_OS

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