Chapter 4 Building Makefiles and Configuring the System Image

This chapter describes the tools used to define what a ChorusOS system image contains. It also demonstrates how to include an application in a ChorusOS system image causing the application to execute when the system boots. After implementing the examples in this chapter, you will have a basic understanding of how to include an application in a ChorusOS system image using the tools provided.

Building Makefiles with ChorusOSMkMf

ChorusOSMkMf is a host utility that enables the creation of a Makefile from an Imakefile for an application. ChorusOSMkMf uses imake to generate the Makefile from a project template, a set of cpp macros, and the application's Imakefile. In most cases, an Imakefile contains three things:

• A list of source files

• Macros that specify the global compilation rules

• Macros that specify how to build the target

The following procedure shows how ChorusOSMkMf is used in the development life cycle. The application in this procedure is composed of a single C source file, for example, myprog.c in the directory myprog.

Using ChorusOSMkMf

Writing an Imakefile is straightforward.

1. Set the SRCS variable to the list of source files.

   In this example there is only one:

   SRCS = myprog.c

2. Specify how to build the executable.

   The macro required depends on the type of binary you want. To build a user-mode binary (for example myprog_u), use the UserActorTarget() macro, as illustrated in the following example. The first argument is the name of the executable. The second argument lists the object files. The third argument enables you to specify which libraries your program depends on. In the following example there is no library, therefore, there is an empty argument (you could also pass a NullParameter).

   UserActorTarget(myprog_u,myprog.o,)

   To build a supervisor-mode binary (for example, myprog_s.r), use the SupActorTarget() macro as follows. The arguments are the same as for UserActorTarget().

   SupActorTarget(myprog_s.r,myprog.o,)

3. Use the Depend() macro to generate the Makefile dependencies.

   Depend($(SRCS))

   The complete Imakefile is as follows:

   SRCS = myprog.c
   UserActorTarget(myprog_u,myprog.o,)
   SupActorTarget(myprog_s.r,myprog.o,)
   Depend($(SRCS))

4. Generate the Makefile with the ChorusOSMkMf() tool.

   In the myprog directory, type:

   % ChorusOSMkMf <build_dir>

   Where build_dir is the directory where the ChorusOS system was built and from which the application will run.

5. Generate the make dependencies.

   To do this, type:

   % make depend

6. Compile and link the program.

   To do this type:

   % make

   The program is now ready to be executed.

ChorusOS Configuration Files

The ChorusOS operating system configuration is defined in a number of XML based configuration files. There are several levels of configuration files, all of which are located in the conf directory. These configuration files are used to build the system image.

For more information on the configuration files refer to "Configuring and Tuning" in the ChorusOS 5.0 System Administrator's Guide.

The ChorusOS System Image

The ChorusOS operating system is started from a bootable file called the system image which is loaded in memory either by a hardware or primary boot, depending on the hardware. This bootable file contains the image of the system to be run on the target machine.

The system image contains a configured version of the ChorusOS operating system, and possibly some user-defined applications (actors).

Depending on its configuration options, the ChorusOS operating system is made up of a microkernel and a collection of actors. The actors contribute to the implementation of some ChorusOS operating system features and are known as ChorusOS operating system actors.

Configuration options relating to system image components deal mainly with the inclusion of system and application actors within system images.

For more information on target configuration, refer to "Configuring and Tuning" in the ChorusOS 5.0 System Administrator's Guide.

ChorusOS Configuration Tools

The ChorusOS configuration tools enable you to configure the ChorusOS operating system. The tools also enable configuration of system components (OS) and actors that may be part of the ChorusOS operating system image.

There are two methods of viewing and modifying the characteristics of a system image:

• Ews - graphical interface

• Configurator - command-line interface

The examples in this chapter use Ews to add applications to the system image. For more information on the configuration tools, see "Configuration Tools" in the ChorusOS 5.0 System Administrator's Guide.

Using Ews

The graphical configuration tool, Ews, requires Sun Java JDK 1.2 (JAVA 2) or higher to be installed, and the location of the Java virtual machine to be set in your path. For a complete description of Ews, refer to "Configuration Tools" in the ChorusOS 5.0 System Administrator's Guide.

To start Ews and open an existing configuration file, type:

$ews -c <path>/ChorusOS.xml

The optional config-file specifies the path of the ChorusOS operating system configuration file conf/ChorusOS.xml to open when starting.

To start ews without opening a file, simply type:

$ ews

Adding an Application to the System Image

An application may be loaded either at system boot time or dynamically.

Adding a Boot Actor With Ews

The ChorusOS configuration tools enable configuration of the system image with user provided actors (which may be user or supervisor actors). After the system has initialized, it starts the actors automatically and creates a main thread for each of them. These actors are often referred to as boot actors.

There are two stages in adding a boot actor to the system image:

1. Specify the characteristics of the new actor.

   Open the Applications folder in the ChorusOS System Image Configuration folder. A newly-created System Image Configuration folder contains two templates for defining actors, one for user actors (user_actor), and one for supervisor actors (supervisor_actor). To create your actor definition, either modify or duplicate one of these templates, or choose New Actor from the context menu of the Applications folder:

   

   A new actor called my_actor is created. Click on the handle icon to the left of the actor, or double-click on my_actor itself, to reveal a list of fields or children:

   

   Invalid elements are indicated by an exclamation mark (!) on top of the icon. The new actor is invalid because its field values are empty. Double-click on the path field to open the Properties Inspector window within the Multiple Document Interface (MDI):

   

   Enter the absolute pathname of the actor by double-clicking in the Value field of the Current Value property. For example:

   

   Now, double-click on the bank property to open up its Properties Inspector window, then double-click in the Value field of the Reference property. An ellipsis (...) is displayed in the right of the field:

   

   Click on the ellipsis to open the reference selecting window, Select a reference window:

   

   Click on the required reference, sys_bank, then click Ok.

   Now, double-click on the binary property and perform the same actions as those performed when setting the bank property.

2. Add the actor to the list of application files present in the system image.

   The application_files list in the ChorusOS System Image Configuration folder contains references to the actors that will be present in the ChorusOS operating system image. If an actor is defined but not referenced in this list, it will not be added to the image. Add your actor to this list by choosing New element from its context menu:

   

   An empty element is displayed:

   

   Update the new element by opening it in the Properties Inspector and changing the Value field of the Reference property. Scroll down and select your newly defined actor (my_actor in this example), from the opened Select a reference window:

   

   Click Ok to complete the operation.

Applications that are device drives can be added using the same method.

After a configuration has been edited it must be saved. To do this, select the ChorusOS configuration item from the navigation tree (the root element of a configuration), and use its context menu. It is also possible to save the configuration using the Save option in the File menu on the main menu bar, or the Save button on the toolbar.

A modified configuration that is displayed in red indicates the file has been changed.

The new actor has now been added and you are ready to rebuild the system image.

Rebuilding the System Image

To rebuild the system image, select the ChorusOS configuration item in the navigation tree, and use the build item from the context menu (or corresponding toolbar button). If the configuration file has not been saved since it was last modified, the tool will prompt you to save it because the configuration cannot be built unless the file has been saved. If the configuration is invalid, it is not possible to build the corresponding ChorusOS operating system image.

During the build of the system image, messages generated by the make tools are displayed in the output window.

To interrupt the build use the stop button on the toolbar. In this case, the system image is not built.

Adding a Non-Boot Application

Not all applications included in the system image need to start at boot time.

The ChorusOS operating system is able to load binary files dynamically from a host system acting as an NFS server, from a local disk, or from the system image (/image/sys_bank). This host-target environment enables you to load supervisor and user actors using a basic remote shell mechanism.

To execute an application called hello on the target host moon, launch the application as follows:

% rsh moon hello