RoadNarrows Make System

Introduction

The rnmake system provides a fast and simple make system for RoadNarrows LLC packages. Each package has a required, but flexible, directory hierarchical structure.

The rnmake system supports both native and cross-compliled target architectures.

The rnmake system is built around GNU make plus some simple shell (sh/bash) utilities and the doxygen documentation tools.

At RoadNarrows, a typical workstation builds for multiple targets. So rnmake evolved to support multiple-target, cross-compilations. All supported compiler tool chains are GNU gcc based. The target platform must be near Posix compliant.

All rnmake core files reside under /installpath/rnmake where /installpath is the installed directory path root of the rnmake/.

Quick Start

Change your current working directory to the top package directory.

The default target architecture is defined by the environment variable RNMAKE_ARCH_DFT if defined. Else the i386 32-bit Linux Posix is the default.

To make the package for the default target architecture:

$ make deps
$ make
$ make install

To clean or to clobber the pre-installed distribution:

$ make clean
$ make distclean 

To make for a specific target architecture, add arch=arch to the command line. For example, to build and install for Arm PXA XScale Linux target:

$ make arch=armpxa install 

Package Definition

A package is a set of functionally related components such as libraries, header files, applications, configuration files, and documentation.

Product Definition

A product is a collection of one or more packages. Because a package has a focused use, a package may be used across multiple products developed by RoadNarrows, RoadNarrows Robotics, and RoadNarrows Intelligent Systems.

Core Make Files

• The core make file rnmake/Rules.mk is included in all package make files. It defines the set of rules to make a package.
• The rnmake/Arch/ subdirectory contains the make macro definitions to build for a given target platform architecture. It includes tool-chain locations, install locations, and build flags.
• The rnmake/doxy/ subdirectory defines the doxygen directives and styles for a package.
• The rnmake/utils subdirectory contains simple shell utility scripts.

Package Make Files

• Under each package's top directory topdir there exists the subdirectory make/ where:
  The Pkg.mk file defines the package specific make definitions.
  The doxy.conf file defines the configuration for the doxygen document generation.
• For each source [sub]directory under topdir there exists a Makefile defining how to make that level of the package.

Doxygen

RoadNarrows heavily uses doxygen (see http://www.stack.nl/~dimitri/doxygen) to document the source code. The rnmake system has built-in targets to support the generation of doxygen HTML documenation.

Make Target Rules

make [arch=arch] help	List available key make targets.
make [arch=arch] deps	Make dependencies.
make [arch=arch] [all]	Compile libraries and applications.
make [arch=arch] documents	Make documentation.
make [arch=arch] install	Install distribution. (libraries, applications, and documentation are automatically made as required).
make [arch=arch] tarballs	Make binary, source, and documenation compressed tar files (tarballs).
make [arch=arch] clean	Clean object files.
make [arch=arch] distclean	Clean plus remove distribution and local files, and dependencies.
make [arch=arch] clobber	Same as distclean.
make [arch=arch] file.o	Make an individual object file.
make [arch=arch] file.ii	Make an individual post c preprocessor file.

Architectures

The currently supported architectures are:

i386	Linux with any Intel (backwards) compatible 32-bit architectures.
x86_64	Linux with any AMD 64-bit architectures.
armpxa	Cross-compiled Familiar Linux XScale Arm PXA architectures.
armang	Cross-compiled Angstrom Linux XScale Arm PXA architectures.
cygwin	Cross-compiled for Windows systems with install cygwin (see http://www.cygwin.com).
cygwin-nat	Natively compiled on Windows systems with install cygwin (see http://www.cygwin.com).
osx	Apple Mac OS-X natively compiled systems. Tested on users' personal machines, but has not officially RoadNarrows tested and verified.

New architectures are added as needed. One near-term addition will be the Gumstix Verdex and Overo platform running Linux 2.6.

Tool Chains

No compiler tool chains are included. This is the responsibility of the developer or organization.

Verified Tool-Chains and Targets

The rnmake system and resultant compiled packages have been verified using the following tool chains and cross-compiled targets:

make	GNU make 3.8+. make 3.81 Fedora Core 5/6 on 32-bit and 64-bit machines. make 3.81 Ubuntu 8.1/9.4 on 32-bit and 64-bit machines. make 3.8+ Windows cygwin on 32-bit machines.
gcc	GNU gcc 4.3+ compiler, link loader, pre-processor, archiver, utilities, target system headers and libraries. gcc 4.1.2 Fedora Core 5/6 on 32-bit and 64-bit machines. gcc 4.3.2+ for Ubuntu 8.1/9.4 on 32-bit and 64-bit machines. gcc 4.3+ Windows cygwin on 32-bit machines.
arm-linux-gcc	GNU gcc 4.1 cross-compiler, link loader, pre-processor, archiver, utilities, target system headers and libraries. gcc 4.1.0 Linux 2.4 XScale Arm PXA. Tested on the K-Team KoreBot single board computer.
i686-pc-cygwin-gcc	GNU gcc 4.3+ cross-compiler, link loader, pre-processor, archiver, utilities, target system headers and libraries. gcc 4.3 for Fedora Core 5 & 6 on 32-bit and 64-bit machines.
doxygen	Doxygen 1.5.8 for Fedora Core 5/6, Ubuntu 8.1/9.4, and Windows cygwin platforms
shell	System standard sh or bash shell.

Tweaks

There are many tweaks a developer can do to rnmake to alter its behavior by simply editing the appropriate make file macros. Some common tweaks are:

• Export the environment variable RNMAKE_ARCH_DFT to defined the default make architecture.

  # Example
  $ export RNMAKE_ARCH_DFT=x86_64
  $
  $ make         # make [sub]package for x86_64 architecture

• A developer can easily add a new host architecture by adding their new rnmake architecture make file Arch.newarch.mk to rnmake/Arch/ directory. The best way to start is to copy an existing Arch.arch.mk file and make the appropriate changes.
• For Arch.arch.mk (see files for full set of tweaks):

  prefix	Defines where to install the package.
  CROSS_COMPILE	Tool chain command prefix string

• Top Makefile

  prefix_root

  Root directory to install all target architectures. If prefix is defined, prefix_root is ignored. Default: topdir/xinstall/

File Manifest

List of directories, files, and naming conventions.

Nomenclature

rnmake	Directory path to the top directory of the rnmake package. Example: /prj/rnmake
pkgroot	Directory path to package top directory. Example: /prj/pkg/librnr
topdir	Directory path to product's top directory. May be same as pkgroot for single packages.
prefix	Install root directory. Example: topdir/xinstall/arch/ Default: /prj/xinstall/arch/
arch	Target host platform architecture.
pkg	Package fully qualified name.
prod	Product fully qualified name.
path	A directory path.

Core Make System

rnmake/	The rnmake top directory containing core make files including Rules.mk.
rnmake/Arch/	The subdirectory holding the architecture make files.
rnmake/doxy/	The doxygen package files.
rnmake/utils/	Various rnmake utility scripts.

General Package Structure

pkgroot/docs/	Package doxygen main and support documentation.
pkgroot/examples/	Package example programs.
pkgroot/include/	Package top include directory.
pkgroot/make/	Package wide make and configuration files.
pkgroot/path/	Package subcomponent directory. For examploe: a subdirectory holding source files for a library.

General Product Structure

topdir/make/	Product wide make and configuration files.
topdir/pkg_n/	Package n root directory.

Make Intermediates

pkgroot/path/.deps/	Source dependencies for package directory.
pkgroot/path/.deps/deps.arch/	Source dependencies for arch architecure.
pkgroot/path/obj/	Object files for packaage directory.
pkgroot/path/obj/obj.arch/	Object files for arch architecure.
pkgroot/loc/	Top directory containing local-only generated libraries and applications. Local files are not installed.
topdir/dist/	Distribution generated files top directory. Distribution files are installed to prefix.
topdir/dist/dist.arch/	Distribution generated files for arch architecture.
topdir/dist/dist.arch/bin/	Executables.
topdir/dist/dist.arch/lib/	Libraries.
topdir/dist/dist.arch>/etc/	System configuration.
topdir/dist/dist.arch/share/	Package configuration and documenation including doxygen generated HTML.
topdir/dist/dist.arch/src/	A clean copy of source files for tarring, etc.
topdir/dist/dist.arch/tmp/	Directory holding temporaries.

Install

Install directories. Any of the following parameters can be overriden as necessary in an including Makefile or on the command line. Note that these parameters are the same as the traditional configuration naming convention.

prefix/	Installed files root directory.
exec_prefix	Installed executables root directory default: prefix
bindir	Installed executables directory default: exec_prefix/bin
sbindir	Installed system executables directory default: exec_prefix/sbin
libexecdir	Installed executable libraries directory default: exec_prefix/libexec
sysconfdir	Installed system configuration files directory default: prefix/etc
localstatedir	Installed local state directory default: prefix/var
libdir	Installed libraries directory default: exec_prefix/lib
includedir	Installed API headers directory default: prefix/include
sharedir	Installed shared data directory default: prefix/share
infodir	Installed information directory default: prefix/info
docdir	Installed documentation directory default: prefix/share/doc
mandir	Installed manpages directory default: prefix/man

Tarballs

topdir/dist/pkg-doc.tar.gz	Package source documentation tarball file.
topdir/dist/pkg-src.tar.gz	Package source tarball file.
topdir/dist/pkg-arch.tar.gz	Package binary compiled source tarball file for arch architecture (only if stand-alone package).
topdir/dist/prod-arch.tar.gz	Product binary compiled source tarball file for arch architecture .