gmake-manual.tex

%//////////////////////////////////////////////////////////////////////////////
%
% Copyright (c) 2007,2009 Daniel Adler <dadler@uni-goettingen.de>, 
%                         Tassilo Philipp <tphilipp@potion-studios.com>
%
% Permission to use, copy, modify, and distribute this software for any
% purpose with or without fee is hereby granted, provided that the above
% copyright notice and this permission notice appear in all copies.
%
% THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
% WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
% MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
% ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
% WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
% ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
% OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
%
%//////////////////////////////////////////////////////////////////////////////

\documentclass{article}

\newcommand{\var}[1]{{\tt #1}}
\newcommand{\val}[1]{"{\tt #1}"}
\newcommand{\file}[1]{{\tt #1}}

\begin{document}

\title{buildsys/gmake}
\author{Daniel Adler}
\maketitle

\section{Usage}

\subsection{Configuring the project}

Before building a project, one has to configure the project.

\begin{verbatim}
./configure
.\configure.bat
\end{verbatim}

The configure script creates a top-level \file{ConfigVars} that
specifies a list of \var{CONIFG\_*} variables.

Here's a sample \file{ConfigVars} file:

\begin{verbatim}
CONFIG_OS=windows
CONFIG_ARCH=x86
CONFIG_TOOL=gcc
BUILD_ASM=as
INSTALL_DIR=/usr/local
\end{verbatim}

\subsection{Building the project}

Type {\tt gmake} or {\tt make}\footnote{some platforms use a different Make tool which is accessible as
{\tt make} from the command-line. Platforms that need to use {\tt gmake} are: Solaris and all BSD platforms.} on the shell.

\subsection{Phony targets}

\begin{tabular}{ll}
Target  & Description				\\
\hline
\val{default}	& Default rule, depends on build	\\
\val{dirs}	& Traverse sub-directories		\\
\val{build}	& Build project, depends on dirs	\\
\val{install}	& Install project, depends on build and dirs \\
\val{clean}	& Clean project, depends on dirs	\\
\end{tabular}


\subsection{Project directory setup}

Write up a \file{GNUmakefile} file in some project folder. Specify the
relative path to the top-level project directory which contains the \file{buildsys} folder
using the \var{TOP} variable. Your project settings are embedded between
two includes, namely the prolog and the epilog files.

\begin{verbatim}
# Sample GNUmakefile for buildsys/gmake
TOP	= ../..
include $(TOP)/buildsys/gmake/prolog.gmake
# ... project directory settings goes here ...
include $(TOP)/buildsys/gmake/epilog.gmake
\end{verbatim}

\pagebreak
\section{Configuration variables}
  
\subsection{BUILD\_OS}

Specifies the target operating system or embedded run-time platform:

\begin{tabular}{ll}
Value         & Description           \\
\hline
\val{windows} & Microsoft Windows     \\
\val{macosx}  & Mac OS X              \\
\val{iphoneos}& iPhone OS             \\
\val{linux}   & Linux                 \\
\val{sunos}   & SunOS                 \\
\val{freebsd} & FreeBSD		      \\
\val{openbsd} & OpenBSD		      \\
\val{netbsd}  & NetBSD		      \\
\val{psp}     & Playstation Portable  \\
\val{nds}     & Nintendo DS           \\
\end{tabular}

\subsection{BUILD\_ARCH}

Specifies the processor architecture:

\begin{tabular}{ll}
Value        & Description                 \\
\hline
\val{x86}    & X86 32-bit Architecture     \\
\val{x64}    & X86 64-bit Architecture     \\
\val{ppc32}  & PowerPC 32-bit Architecture \\
\val{arm32}  & ARM32 Architecture          \\
\val{mips32} & MIPS 32-bit Architecture    \\
\end{tabular}

\subsection{BUILD\_TOOL}

Specifies the build tool chain:

\begin{tabular}{ll}
Value      & Description             \\
\hline
\val{gcc}  & GNU Compiler Collection \\
\val{msvc} & Microsoft Visual C++ (windows) \\
\val{pspsdk} & Playstation Portable SDK \\
\val{llvm_gcc} & LLVM with GCC Front-end \\
\end{tabular}

\subsection{BUILD\_ASM}

Specifies the assembler tool:

\begin{tabular}{ll}
Value      & Description              \\
\hline
\val{as}   & GNU Assembler            \\
\val{nasm} & NASM Assembler (x86/x64) \\
\val{ml}   & Micrsoft Macro Assembler (x86/x64)\\
\end{tabular}

\subsection{Others}

\begin{tabular}{ll}
Variable name		& Description		\\
\hline
\var{BUILD\_CONFIG}	& Build configuration ("release", "debug") \\
\var{INSTALL\_PREFIX}	& Installation prefix directory \\
\end{tabular}

\section{Predefined variables}

\begin{tabular}{ll}
Variable name		& Description		\\
\hline
\var{GMAKE\_TOP}	& Relative path to folder \file{buildsys/gmake} \\
\var{BUILD\_DIR}	& Build directory (e.g. "out-$<$os$>$-$<$arch$>$-$<$tool$>$-$<$config$>$")\\
\hline
& OS-specific \\
\hline
\var{APP\_SUFFIX} & Application suffix            \\
\var{LIB\_SUFFIX} & Static library suffix         \\
\var{DLL\_SUFFIX} & Dynamic linked library suffix \\
\hline
& Tool-specific \\
\hline
\var{LIB\_PREFIX} & Static library prefix         \\
\var{OBJ\_SUFFIX} & Object file suffix            \\
\end{tabular}

All suffixes should include the "." (dot) .

\section{Project variables}

\begin{tabular}{ll}
Variable name              & Description                       \\
\hline
\var{TOP}		   & Relative path to top directory    \\
\var{DIRS}		   & Sub-project directory names       \\
\var{UNITS}                & List of units to link for target      \\
\hline
& targets \\
\hline
\var{TARGET\_APP}           & Build application name              \\
\var{TARGET\_LIB}           & Build static library name           \\
\var{TARGET\_DLL}           & Build dynamic library name          \\
\var{TARGET\_PDF}	   & Build PDF manual (sources in latex) \\
\hline
& build related \\
\hline
\var{ASFLAGS}              & Assembler flags \\
\var{CPPFLAGS}		   & C Preprocessor flags \\
\var{CFLAGS}		   & C Compiler flags \\
\var{CXXFLAGS}		   & C++ Compiler flags \\
\var{LINK}                 & Application linker: \val{c}, \val{c++} or empty (default linker)\\
\var{LINK\_PATHS}	   & List of library paths \\
\var{LINK\_LIBS}	   & List of library names \\
\var{CXX\_EXCEPTIONS}      & If set to \val{1}, use C++ Exceptions                \\
\var{CXX\_RTTI}       	   & If set to \val{1}, use C++ Run-time Type Information \\
\hline
& installation related \\
\hline
\var{INSTALL\_APP}	   & If set to \val{1}, install executable to bin install-directory \\
\var{INSTALL\_LIB}	   & If set to \val{1}, install library to lib install-directory \\
\var{INSTALL\_HEADERS}    & List of header files to copy to include install-directory \\
\end{tabular}

\pagebreak

\section{Inclusion order}

\begin{enumerate}
\item \file{prolog.gmake}
\begin{itemize}
\item Set \var{GMAKE\_TOP} variable
\item Define \val{default} rule
\item Include \file{ConfigVars}
\item Define build value variables (\var{BUILD\_*\_*} variables)
\item Define \var{BUILD\_DIR} variable and a mkdir rule.
\end{itemize}
\item \file{epilog.gmake}
\begin{itemize}
\item Include \file{os/\$(\var{BUILD\_OS}).gmake}
\item If \var{BUILD\_ASM\_nasm} is defined then include \file{tool/nasm.gmake}
\item Include \file{tool/latex.gmake}
\item Include \file{targets.gmake}
\end{itemize}
\end{enumerate}

The os-specific gmake files will typically include 
\file{tool/\$(\var{BUILD\_TOOL}).gmake} file. 
The tool-specific gmake file will typically include configuration specific files driven by the \var{BUILD\_CONFIG} define.
Other more-specific platforms such as psp and nds might preclude and append additional information
depending on platform and tool quirks.

\section{OS notes}

\begin{description}
\item [windows] gcc and msvc tool-chain support
\item [psp] gcc only
\end{description}

\end{document}