OSE - Makeit User Guide

Graham Dumpleton
Dumpleton Software Consulting Pty Limited
PO BOX 3150
Parramatta, 2124
N.S.W, Australia
email: grahamd@nms.otc.com.au

Table of Contents

Basic Concepts
OSE - Makeit User GuideBasic Concepts

Basic Concepts

1 Introduction

In this chapter you will learn more about the structure of makeit and how to configure makeit. Finally, how to run makeit and the major command line options which makeit accepts are described.

2 Naming of Files

Makeit is controlled through a description file called a makefile. The makefile is not optional, as it is from the makefile that you will include a set of predefined makefiles, supplied with makeit.

When makeit searches for a makefile, it will try the following names, in order:

The preferred name for the makefile is either `makeit.mk' or `Makeit.mk'. The name `Makeit.mk' is recommended, because it appears prominently near the beginning of a directory listing.

3 Makefile Structure

Makefiles for makeit can be generated using the program mksrc. To create a makefile with the name `Makeit.mk', run the command:

  mksrc Makeit.mk
The standard structure of a makefile for use with makeit, and that which is created by mksrc, is given below.

  # Initialisation.

MODULES := c cc ose

include makeit/init.mk

# Definitions.

SUBDIRS :=

PROGRAMS :=
EXCLUDE :=
NONLIBSRC :=

CPPFLAGS :=
CFLAGS :=
C++FLAGS :=
LDFLAGS :=
LDLIBS :=

include makeit/modules.mk

# Dependencies/Rules.
The standard makefile is divided into three sections. The sections are separated by the inclusion of two special top level makefiles from the directory of predefined makefiles. These two files are the only files which need to be included from the directory of predefined makefiles.

The two lines from the makefile which include these files are,

  include makeit/init.mk
and

  include makeit/modules.mk
The first of the included makefiles, `init.mk', is where makeit is initialised. Any definitions which affect the initialisation of makeit should appear in the makefile before `init.mk' is included. The section before this point in the makefile is referred to as the initialisation section of the makefile.

The section of the makefile between the inclusion of `init.mk' and `modules.mk' is the definitions section. Any definitions not directly related to initialisation of makeit should be included here. The `modules.mk' include line results in the remainder of the makefiles necessary for makeit to run, to be included.

The section of the makefile following the inclusion of `modules.mk' is referred to as the dependencies and rules section. If you ever need to add special dependency information, or wish to add your own rules to the makefile, they should be included in this final section.

4 How Makeit Works

Makeit primarily operates by looking at the extensions used on files contained within the directory it is run. From the extension of a file, it is able to deduce what to do with that file. For example, if a file has a `.cc' extension it knows that the file is C++ code and thus should be compiled using the C++ compiler.

Unfortunately, not all files of a particular type will always be dealt with in a specific way. For programming language files, you will want some files to be compiled and the object file generated placed into a library, and some files to be compiled into programs. As makeit cannot automatically distinguish between these two categories of files, it is necessary for you to provide additional information to makeit as to what to do. This generally consists of you identifying which files need to be dealt with in a special way. For example, in the case of programming language files, you will need to tell makeit which are to be compiled into programs. This is done by listing the names of the programs which would be generated. From the names of the programs, makeit is able to match up which files are special, by applying the extension appropriate for that type of language file to the program name.

5 Configuring Makeit

As detailed above, in certain circumstances it is necessary for you to denote that certain files in a directory are special. Such information and other information which makeit requires is provided through assignment to variables within the makefile. The names of these variables are generally specific to the feature of makeit which you are using and will be described where appropriate in the remainder of this manual. In addition to these variables, there are a small number of special variables which apply to the initialisation of makeit. These variables must be defined in the initialisation section of the makefile. Descriptions of a number of these variables are described in the following sections.

For a complete description of variables in general and how to define them you should consult the manual for GNU make.

5.1 Version of OSE

When you run makeit, the version of OSE which will be used will correspond to the version of the makeit program you ran. If you need to ensure that a particular version of OSE is used, the variable OSE_VERSION can be set. For example:

  OSE_VERSION := 3.3
If you define OSE_VERSION, the definition must be placed into the initialisation section of the makefile.

5.2 Modules Included

Only the makefiles containing the basic set of rules are included by makeit by default. Additional features are only accessible, if the makefile corresponding to the module implementing the feature is included by makeit. To have makeit include specific modules, you must list the names of the modules in the MODULES variable. For example:

  MODULES := c cc ose
The definition of the MODULES variable must appear in the initialisation section of the makefile. The following table lists the names of the modules supplied with the standard version of makeit.

------------------------------------------------------------------
Module Name  Feature Supported                                      
------------------------------------------------------------------
c            C code                                                 
cc           C++ code - `.cc' extension                             
c-cc         C++ code - `.c' extension                              
cpp          C++ code - `.cpp' extension                            
cxx          C++ code - `.cxx' extension                            
C            C++ code - `.C' extension                              
sh           shell scripts                                          
lex          lexical analyser generator                             
yacc         parser generator                                       
rpcgen       remote procedure call generator                        
combine      library combination and template closure of libraries  
check        test environment                                       
repository   cfront template repositories                           
install      program/library installation                           
ose          OSE C++ class libraries                                
ocenter      ObjectCenter GUI support                               
tcl          TCL/TK libraries                                       
x11          X Windows libraries                                    
------------------------------------------------------------------

5.3 Compilation Variant

When using makeit, you will always be working within a particular compilation variant. Makeit provides a choice of four compilation variants. These are `dbg', `opt', `prf' and `std'.

A particular compilation variant is selected by defining the VARIANT variable to one of the names listed above. If you define the VARIANT variable, the definition must occur in the initialisation section of the makefile. For example:

  VARIANT := opt
If you do not define the VARIANT variable, the default variant, `dbg', will be used by makeit. Normally, you would not define the VARIANT variable in a makefile. Instead, you would always work in the `dbg' variant. When it is necessary to compile in a different compilation variant, VARIANT can be defined on the command line when makeit is run:

---------------------------------------------------------------------------------
Variant  Description                                                               
---------------------------------------------------------------------------------
dbg      The `dbg' variant is the default compilation variant and is used during   
         the the implementation phase of development. If this variant is selec     
         ted, flags will be provided to compilers to cause inclusion of support    
         for debugging tools.                                                      
opt      The `opt' variant should be used when necessary to compile an appli       
         cation for release. When the `opt' variant is selected, flags will be     
         supplied to compilers to enable optimisation. In addition, the prepro     
         cessor symbol NDEBUG will be defined.                                     
prf      The `prf' variant is used when you want to improve the performance        
         of an application through the use of execution profilers. The profiler    
         for which support is included is gprof. If gprof is not supported for     
         a compiler then support for prof will be included.                        
std      The `std' variant is equivalent to a standard compilation, ie., with no   
         special flags provided to compilers.                                      
---------------------------------------------------------------------------------

6 Running Makeit

When you run makeit, in most cases you will want to tell makeit what to build. In addition you may wish to provide options to makeit to change how it operates. How to tell makeit what to build and the major options which makeit accepts are detailed in the following sections.

6.1 Targets

When you run makeit you must tell it what it is that you want built. What you tell it to build is referred to as the target. If you want everything that is in a directory built, you should use the target `all'. Running makeit without any target is equivalent to giving makeit the target `all'.

In addition to the `all' target, makeit accepts a number of other high level targets which do not relate directly to an end product of the build. A summary of the actions performed by makeit for these high level targets, including the target `all', is given below.

------------------------------------------------------------------------------------
Target    Description                                                                 
------------------------------------------------------------------------------------
all       Compiles library code files and creates a library. Program code files       
          are compiled and linked with the library to produce executable pro          
          grams.  Any auxiliary files required by the programs or library will        
          also be updated.                                                            
lib       Compiles library code files and creates a library.                          
programs  Compiles program code files and links them with the library to pro          
          duce executable programs.                                                   
depend    Updates dependency information for files.                                   
install   Compiles the library and any programs. The library and programs are         
          then copied into an area where they should reside in order to be used       
          by others. Any auxiliary files required by the programs or library will     
          also be copied to their appropriate destinations. This target is only       
          available through the `install' module.                                     
clean     Deletes all files from the current directory that are normally created by   
          building the library and programs.                                          
check     Runs tests (if any). This requires the user to provide appropriate test     
          harnesses and log files recording what the expected outputs of the tests    
          are. This target is only available through the `check' module.              
------------------------------------------------------------------------------------
When using special features of makeit it is possible to also have makeit build specific targets, which are realised as an end product. For example, you would be able to get makeit to build a specific program executable. Details of such targets will be described later in this manual.

6.2 Options

Command line options which apply to GNU make, also apply to makeit. A summary of the major options are given below.

--------------------------------------------------------------------------------
Option             Description                                                    
--------------------------------------------------------------------------------
-C DIR             Change to directory `DIR' before reading the makefiles.        
--directory DIR    If multiple `-C' options are specified, each is interpreted    
                   relative to the previous one:  `-C / -C etc' is equi           
                   valent to `-C /etc'.                                           
-d                 rint debugging information in addition to normal proces        
--debug            sing. The debugging information says which files are           
                   being considered for remaking, which file-times are            
                   being compared with what results, which files actually         
                   need to be remade, which implicit rules are considered         
                   and which are applied - everything interesting about           
                   how makeit decides what to do.                                 
-f FILE            Read the file named `FILE' as a makefile.                      
--file FILE                                                                       
--makefile FILE                                                                   
-h                 Remind you of the options that makeit understands,             
--help             and then exit.                                                 
-n                 Print the commands that would be executed, but do not          
--just-print       execute them.                                                  
--dry-run                                                                         
--recon                                                                           
-p                 Print the data base (rules and variable values) that results   
--print-data-base  from reading the makefiles; then execute as usual, or as       
                   otherwise specified.                                           
--------------------------------------------------------------------------------