ChorusOS 5.0 Application Developer's Guide

Using `make` and `imake`

To build a ChorusOS component, use the make and imake tools. All development tools are provided in the install_dir/5.0/chorus-family/tools directory of your ChorusOS installation.

The `make` Environment

The make environment is defined by a file containing variable definitions and rules. This file provides the rules for compiling C, C++, and assembly language. The rules are specific to your compiler - the name of the file indicates the compiler used. For example, when using the gcc compiler, the make environment file is named tgt-make/gcc-devsys.mk. This 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 6-1.

Table 6-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 DEFINES specify include and depend values. These variables can be replaced by different variables (overloaded) at the application level. The variables are contained in the CPPFLAGS flag, which is used in compilation and in computing dependencies. Both INCLUDES and DEFINES can be initialized at the application level.

LD_UCRT0, LD_SCRT0, LD_DCRTO, LD_PSCRT0, LD_PUCRT0, LD_CRTI, and LD_CRTN are used to manage different types of crt object files. A crt object file (crto) contains the entry point of the application (_start or _main).

Table 6-2 crt Object Files


`LD_UCRT0`	Specifies the entry point for an embedded user actor
`LD_SCRT0`	Specifies the entry point for an embedded supervisor actor
`LD_DCRT0`	Specifies the entry point for drivers
`LD_PSCRT0`	Specifies the entry point for a supervisor actor or process
`LD_PUCRT0`	Specifies the entry point for a user actor or process
`LD_CRTI`	Contains the `crti.o` file. This file is always the first object file of a link list and should contain the beginning of the `.init` and `.fini` sections
`LD_CRTN`	Contains the `.fini` section

LD_U_ACTOR and LD_S_ACTOR specify link information for user and supervisor actors.

EBD_U_LIBS, EBD_S_LIBS, CLX_U_LIBS, CLX_S_LIBS, EBD_CXX_LIBS, and CLX_LIBS are provided to manage the libraries for embedded actors, actors and processes.

Table 6-3 Library Variables


`EBD_U_LIBS`	Manages the C library for embedded user actors
`EBD_S_LIBS`	Manages the C library for embedded supervisor actors
`CLX_U_LIBS`	Manages the C library for user actors and processes
`CLX_S_LIBS`	Manages the C library for supervisor actors and processes
`EBD_CXX_LIBS`	Manages the C++ library for embedded actors
`CLX_LIBS`	Manages the C++ library for actors and processes

The make environment includes the following commands:

cc
ld
as
mkctors

The `imake` Environment

The ChorusOS imake environment enhances the make environment by providing template rules for common ChorusOS build operations using generic names. When using the predefined imake rules, it is not necessary to know which libraries, crt files, or entry points should be used to build an application, because they are selected automatically.

Instead of creating Makefiles you create Imakefiles, and imake generates Makefiles from them.

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

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

`imake` Variable Definitions

The Imake.tmpl file contains the following definitions:

FAMILY, indicates the target family (x86, usparc, ppc60x, mpc860).
COMPILER, identifies the compiler to be used (for example, gcc).
REL_DIR, specifies the path of the current directory. This variable is automatically set in subdirectories by imake.
HOST, indicates the host operating system (SOLARIS).
DEVTOOLS_DIR, indicates the path of the ChorusOS development tools.

`imake` Build Rules

The Imake.rules file contains macros known as Imake build rules. A list of Imake build rules and their functions is displayed in Table 6-4.

Table 6-4 imake Build Rules


Macro name	Function
`MakeDir(dir)`	Creates a 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 or process.
`SupActorTarget(prog, objs, libs)`	Creates a supervisor C actor or process.
`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 or process named `prog`, and passes `options`, `crt0` and `libs` to the linker.
`CXXUserActorTarget(prog, objs, libs)`	Creates a user C++ actor or process.
`CXXSupActorTarget(prog, objs, libs)`	Creates a supervisor C++ actor or process.
`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 process.
`DynamicSupTarget(prog, objs, libs, dynamicLibs, dlDeps, options)`	Creates a dynamic supervisor C process.
`DynamicCXXUserTarget(prog, objs, libs, dynamicLibs, dlDeps, options)`	Creates a dynamic user C++ process.
`DynamicCXXSupTarget(prog, objs, libs, dynamicLibs, dlDeps, options)`	Creates a dynamic supervisor C++ process.
`DynamicLibraryTarget(dlib, objs, staticLibs, dynamicLibs, dlDeps, options)`	Creates a dynamic library.
`SharedUserTarget(prog, shobjs, staticLibs, sharedLibs, slDeps, options)`	Creates a shared user C process.
`SharedSupTarget(prog, objs, staticLibs, sharedLibs, slDeps, options)`	Creates a shared supervisor C process.
`SharedCXXUserTarget(prog, objs, staticLibs, sharedLibs, slDeps, options)`	Creates a shared user C++ process.
`SharedCXXSupTarget(prog, objs, staticLibs, sharedLibs, slDeps, options)`	Creates a shared supervisor C++ process.
`SharedLibraryTarget(shlib, shobjs, sharedLibs, staticLibs, slDeps, options)`	Creates a shared library.

The rules for building actors and processes use the following common arguments:

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

The rules used to build dynamic or shared libraries for actors and processes are described in more detail in "Building a Dynamic Process".

`imake` Packaging Rules

The Package.rules file contains macros known as Imake packaging rules which are used for building a binary distribution. Their names and functions are listed in Table 6-5.

Table 6-5 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.

`imake` Examples

The following examples demonstrate how to create an Imakefile using single and multiple source files.

Using `imake`

The application in this example is composed of a single C source file, myprog.c, in the directory myprog. Writing an Imakefile is fairly straightforward.

Set the SRCS variable to the list of source files.

In this case there is only one source file:
```
SRCS = myprog.c
```

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 in the following file extract. The first argument is the name of the executable and the second lists the object files. The third argument enables you to specify which libraries your program requires. In this example there is no library, therefore the argument is empty (you could also pass a NullParameter).
```
UserActorTarget(myprog_u,myprog.o,) 
```
In the following example, we will build a user-mode binary. If you want to build a supervisor-mode binary (for example, myprog_s.r), use the SupActorTarget() macro as shown. The arguments are the same as for UserActorTarget().
```
SupActorTarget(myprog_s.r,myprog.o,)  
```

Use the Depend() macro to generate the Makefile dependencies.
```
Depend($(SRCS))
```
The Imakefile is now complete and looks as follows:
```
SRCS = myprog.c
UserActorTarget(myprog_u,myprog.o,)
Depend($(SRCS))
```

Generate the Makefile with the ChorusOSMkMf tool.

See the ChorusOSMkMf(1CC) man page for details of how to do this. In the myprog directory, type:
% ChorusOSMkMf build_dir
Where build_dir is the directory where you have built the ChorusOS system image on which your application will run.

Generate the make dependencies

To do this type:
% make depend

Compile and link the program

To do this type:
% make
The compiled program is now in your myprog directory and ready to be executed.

Using `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 make Makefiles, make depend, and then make.

% make Makefiles   
% make depend   
% make

The compiled program is now ready to be executed.

Note -

Examples of Imakefiles which can be modified and used to build your own applications are provided in install_dir/chorus_family/src/opt/examples.

Using make and imake

The make Environment

The imake Environment

imake Variable Definitions

imake Build Rules

imake Packaging Rules

imake Examples

Using imake

Using imake with Multiple Source Files