ChorusOS 4.0 Introduction

Developing ChorusOS Applications

This section explains how to build a component to be included in a ChorusOS operating system. The component could be an application, a device driver, or a BSP. To build a ChorusOS component, you use the make and imake tools. All development tools are provided in the tools directory of your delivery.

`make` Environment

The make environment is defined by a file containing variable definitions and rules. Rules for compiling C, C++, and assembly language are provided. The rules are specific to the compiler you use, and the name of the file indicates the compiler. For example, if you are using the gcc compiler, the make environment file is called tgt-make/gcc-devsys.mk. The file contains the variables and rules required for building the component. The following variables are defined:

CFLAGS and CXXFLAGS specify the compilation options for C and C++ files, respectively. The compilation options are shown in Table 4-1.
Table 4-1 Compilation Options

Option Possible Settings Default Setting

WARN WARN_ON, WARN_OFF WARN_ON

DEBUG DEBUG_ON, DEBUG_OFF DEBUG_OFF

PROF PROF_ON, PROF_OFF PROF_OFF

OPT OPT_ON, OPT_OFF OPT_ON
INCLUDES and DEPENDS specify include and depend values. These variables can be overloaded at the application level. They are grouped into the CPPFLAGS flag, which is used in compilation and to compute dependencies. Both INCLUDES and DEPENDS can be initialized at the application level.
LD_UCRT0, LD_SCRT0, LD_LCRT0, LD_CRTI, LD_CRTN, and LD_CRTXT are used to manage different types of crt object files.
LD_U_ACTOR and LD_S_ACTOR specify link information for user and supervisor actors.
CLX_U_LIBS, CLX_S_LIBS, EBD_U_LIBS, EBD_S_LIBS, and CXX_LIBS are provided to manage libraries.

Option	Possible Settings	Default Setting
`WARN`	`WARN_ON`, `WARN_OFF`	`WARN_ON`
`DEBUG`	`DEBUG_ON`, `DEBUG_OFF`	`DEBUG_OFF`
`PROF`	`PROF_ON`, `PROF_OFF`	`PROF_OFF`
`OPT`	`OPT_ON`, `OPT_OFF`	`OPT_ON`

The make environment includes the following commands: cc, ld, as, and mkactors.

`imake` Environment

The ChorusOS imake environment extends the make environment by providing template rules for common ChorusOS build operations through generic names. When using those predefined imake rules, you do not need to know which libraries, crt files, or entry points you should use to build an application, as they are automatically selected for you.

Instead of creating Makefiles you must create Imakefiles, as imake will generate Makefiles from them.

The imake environment is defined by four files containing sets of variables and rules, located in the tools/imake directory. The rules are independent of the compiler you use.

Imake.tmpl contains definitions of variables.
Imake.rules contains build rules. See "imake Build Rules".
Package.rules contains the rules used to build a binary distribution.

`imake` Variable Definitions

The file Imake.tmpl contains the following definitions:

FAMILY, indicating the target family (x86, usparc, ppc60x, mpc860, mpc8260).
COMPILER, indicating the compiler to be used (gcc, for example).
REL_DIR, indicating the path of the current directory. This variable is automatically set in subdirectories by imake.
HOSTOS, indicating the host operating system (solaris, win32).
DEVTOOLS_DIR, indicating the path of the ChorusOS tools.

`imake` Build Rules

The file Imake.rules contains macros known as Imake build rules. Their name and function are described in Table 4-2.

Table 4-2 Imake build rules


Macro name	Function
`MakeDir(dir)`	Creates the directory named `dir`.
`LibraryTarget(lib, objs)`	Adds the objects indicated by `objs` into the library `lib`.
`Depend(srcs)`	Computes the dependencies of `srcs` and adds them to the dependency list in the `Makefile` (using `makedepend`).
`ActorTarget(prog, objs, options, crt0, libs)`	Uses `objs` to create a C actor called `prog`, and passes `options`, `crt0` and `libs` to the linker.
`UserActorTarget(prog, objs, libs)`	Creates a user C actor.
`SupActorTarget(prog, objs, libs)`	Creates a supervisor C actor.
`EmbeddedUserActorTarget(prog, objs, libs)`	Creates an embedded user C actor.
`EmbeddedSupActorTarget(prog, objs, libs)`	Creates an embedded supervisor C actor.
`BuiltinDriver(prog, objs, libs)`	Creates a ChorusOS operating system driver.
`BspProgtarget(prog, entry, objs, libs)`	Creates a BSP program.
`CXXActorTarget(prog, objs, options, crt0, libs)`	Uses `objs` to create a C++ actor called `prog`, and passes `options`, `crt0` and `libs` to the linker.
`CXXUserActorTarget(prog, objs, libs)`	Creates a user C++ actor.
`CXXSupActorTarget(prog, objs, libs)`	Creates a supervisor C++ actor.
`CXXEmbeddedUserActorTarget(prog, objs, libs)`	Creates an embedded user C++ actor.
`CXXEmbeddedSupActorTarget(prog, objs, libs)`	Creates an embedded supervisor C++ actor.
`DynamicUserTarget(prog, objs, libs, dynamicLibs, dlDeps, options)`	Creates a dynamic user C actor.
`DynamicSupTarget(prog, objs, libs, dynamicLibs, dlDeps, options)`	Creates a dynamic user C actor.
`DynamicCXXUserTarget(prog, objs, libs, dynamicLibs, dlDeps, options)`	Creates a dynamic user C actor.
`DynamicCXXSupTarget(prog, objs, libs, dynamicLibs, dlDeps, options)`	Creates a dynamic user C actor.
`DynamicLibraryTarget(dlib, objs, staticLibs, dynamicLibs, dlDeps, options)`	Creates a dynamic library.

Rules used to build actors use the following common arguments:

obj is the list of binary objects included in the actor.
prog is the name of the actor.
libs is the list of additional libraries used to build the actor. The actor is linked by default with the library to provide either the basic or extended environment.

The rules used to build dynamic actors are described in more detail in "Building a Dynamic Program".

`imake` Packaging Rules

The file Package.rules contains macros known as Imake packaging rules for building a binary distribution. Their name and function are described in Table 4-3.

Table 4-3 Imake packaging rules


Macro name	Function
`DistLibrary(lib, dir)`	Creates the directory `dir` and copies the library `lib` into it.
`DistActor(actor, dir)`	Creates the directory `dir` and copies the actor `actor` into it.
`DistFile(file, dir)`	Creates the directory `dir` and copies the file `file` into it.
`DistRenFile(file, nFile, dir)`	Creates the directory `dir`, copies `file` into it, changing the name of `file` to `nFile`.
`DistProgram(program, dir)`	Creates the directory `dir` and copies `program` into it.

Examples

Simple `imake` Example

The application in this example is composed of a single C source file, for example myprog.c in the directory myprog. Writing an Imakefile is quite straightforward. First, you must set the SRCS variable to the list of source files (in this case only one).

SRCS = myprog.c

Then, you must specify how to build the executable. The macro you use depends on the type of binary you want. If you want to build a user-mode binary (for example myprog_u), use the UserActorTarget() macro, as illustrated below. The first argument is the name of the executable. The second argument lists the object files. The third argument allows you to specify which libraries your program depends on. In this example there is no library, hence the empty argument (you could also pass NullParameter).

UserActorTarget(myprog_u,myprog.o,)

If you want to build a supervisor-mode binary (for example, myprog_s.r), use the SupActorTarget() as shown below. The arguments are the same as for UserActorTarget().

SupActorTarget(myprog_s.r,myprog.o,)

Finally, use the Depend() macro to generate the Makefile dependencies.

Depend($(SRCS))

The Imakefile is complete. It looks like this:

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

Next, generate the Makefile with the ChorusOSMkMf tool (see the ChorusOSMkMf(1CC) manpage for details). In the myprog directory, type:

% ChorusOSMkMf build_dir

Where build_dir is the directory where you have built a ChorusOS system image on which your application will run.

Next, generate the make dependencies by typing the following command:

% make depend

Finally, compile and link the program by typing:

% make

The program is now ready to be executed, and can be run on your target by following the steps in "Running the "Hello World" Example".

`imake` with Multiple Source Files

If an application used source files located in several subdirectories, you need to create a root Imakefile in the root directory, containing only the following:

#define IHaveSubdirs
SUBDIRS = subdir1 subdir2 ...

where subdir1, subdir2, ... are the subdirectories containing the source files (or other intermediate root Imakefile files). Next, create an Imakefile in each subdirectory containing source files. To generate the first Makefile, go to the root directory and type:

% ChorusOSMkMf build_dir

Next, populate the tree with Makefile files, generate dependencies and finally compile the programs by typing the make Makefiles, make depend, and then make commands.

% make Makefiles   
% make depend   
% make

The program is now ready to be executed.

Note -

Examples of Imakefiles which you can modify and use to build your own applications are provided in /opt/SUNWconn/SEW/4.0/chorus-<target>/src/opt/examples.

Developing ChorusOS Applications

make Environment

imake Environment

imake Variable Definitions

imake Build Rules

imake Packaging Rules