How To Create a Project Using Makefile Engine
Haiku helps developers in build process of their projects by providing so
called Makefile engine. It's made of two files, that reside in
/boot/develop/etc directory and are named 'makefile' and 'makefile-engine'.
Together, these two files provide you with simple ready-to-be used build
engine for your projects. This How To describes makefile-engine v2.5.1 and
makefile template v2.5. Regardless of mentioning the 'makefiles' in this
How To, the same technique can be used for creating Jamfile-driven
projects. Corresponding Jamfile and Jamfile-engine template files are provided
with Haiku. We made both, the makefile and Jamfile engines completely
target-compatible for user's convenience.
Contents
Getting Started
To start a project, just copy makefile from /boot/develop/etc directory, into
your project directory. Write few files, you want to add into project. Add
either relative or full paths to them, into SRCS variable definition in
makefile and run make. Example files for Hello World project:
hello.cpp:
#include <stdio.h>
int main(void)
{
printf("Hello world!\n");
return 0;
}
makefile:
NAME = hello
TYPE = APP
SRCS = hello.cpp
include $(BUILDHOME)/etc/makefile-engine
After adding both these files into same directory, just go there in Terminal,
using 'cd' command and run 'make'. This will create a new directory, named in
similar format: 'objects.x86-gcc2-release' (name depends on current compiler,
that may be either "gcc2" or "gcc4", and defining DEBUG will force using
"debug" instead of "release"), which will contain .o files (one
for each source file), .d files with dependencies, generated automatically by
the engine and a binary file, named 'hello' for the example case above.
Configuring a Project
In makefile, there are many variables, to configure builder helpers for your
needs. Let's take a look at them:
- NAME specifies the name of the project and the output binary filename
- TYPE specifies the type of binary, can be one of the following:
- APP - Application
- SHARED - Shared library or add-on
- STATIC - Static library archive
- DRIVER - Kernel Driver
- APP_MIME_SIG specifies application's mime signature for
localization features. Note that it should correspond to MIME type
provided to BApplication's constructor and the application MIME type
defined in resource file. In case this parameter is not set, the
default value x-vnd.Haiku-$(NAME) will be used.
- SRCS specifies the source files to use. You may specify both, full
paths and paths relative to the position of makefile, all objects,
regardless of the position of their sources will be created in the
common object directory. Please note, that this means, that makefile
won't work correctly, if two source files with the same name
(e.g. source.c and source.cpp) are included from different
directories. Also note, that spaces in folder names do not work well
with the engine.
- RDEFS specifies the resource definition files to be used. You may
specify both, relative and full paths to the files.
- RSRCS specifies the binary file compiled from RDEF, or created
separately by Resource Editors, both RDEFS and RSRCS can be
defined in the same makefile.
- LIBS specifies additional libraries, that binary file should be
linked against. There are two acceptable forms of library
specifications:
- if your library follows the naming pattern of libXXX.so or libXXX.a,
you can simply specify XXX, e.g. for library libbe.so, that would be:
be
- for version-independent linking of standard C++ libraries, please
add $(STDCPPLIBS instead of raw "stdc++[.r4] [supc++]" library names
- for localization support add following libraries: locale localestub
- if your library doesn't follow the standard library naming
scheme, you need to specify the path to the library and its name, e.g.
for library: my_lib.a, the entry would be either: my_lib.a or
path/my_lib.a
- LIBPATHS specifies additional paths to directories following the
standard libXXX.so or libXXX.a naming scheme. You can specify both,
full paths or paths relative to the makefile. The paths included may
not be recursive, so include all paths, where libraries can be found.
Directories where source files are found are automatically included.
- SYSTEM_INCLUDE_PATHS specifies additional paths to look for system
headers. These use the form: #include <header>. Source file
directories are NOT automatically included here.
- LOCAL_INCLUDE_PATHS specifies additional paths to look for local
headers. There use the form: #include "header". Source file
directories are automatically included.
- OPTIMIZE specifies the level of optimization desired, can be one of
following: NONE, SOME, FULL.
- LOCALES specifies language codes, that are going to be supported
by application. The default "en" one must be provided too. For more
information about localization, see the corresponding section of this
how-to.
- DEFINES specifies any preprocessor symbols to be defined. The symbols
will not have their values set automatically, you have to provide
these values (if any). For example, setting DEFINES to "DEBUG=1" will
cause the compiler option "-DDEBUG=1" to be used. However, setting
DEFINES to "DEBUG" would pass "-DDEBUG" option.
- WARNINGS specifies the level of warnings reported by compiler. If this
option is unspecified, the default warnings will be used. It can be
set to one of the following:
- NONE - supress all warnings
- ALL - enable all warnings
- SYMBOLS specifies, whether image symbols should be created, so the
stack crawls in the debugger are meaningful. Setting it to TRUE
enables the creation of symbols.
- DEBUGGER specifies debugging settings. If set to TRUE, it allows
the application to be run from a source-level debugger. Please note,
that this will disable all optimization.
- COMPILER_FLAGS specifies additional compiler flags for all files.
- LINKER_FLAGS specifies additional linker flags.
- APP_VERSION specifies the version of the particular item (e.g. -app
3 4 0 d 0 -short 340 -long "340 "
echo -n -e '\302\251'
).
"1999 GNU GPL"). This may also be specified in a resource.
- DRIVER_PATH works only for TYPE == DRIVER. It specifies desired
location of driver in the /dev hierarchy. It's user by the
driverinstall rule. E.g. DRIVER_PATH = video/usb will instruct
the driverinstall rule to place a symlink to your driver's binary into
~/add-ons/kernel/drivers/dev/video/usb, so that your driver will
appear in /dev/video/usb when loaded. Default is "misc".
- INSTALL_DIR specifies the installation directory of application.
Please also note, that if you're building your own makefile, that will use this
engine, last line must contain:
include $(BUILDHOME)/etc/makefile-engine
Using Localization
Localization in Haiku programs is achieved simply, as following example shows.
localized_hello.cpp:
#include <stdio.h>
#include <Catalog.h>
#undef B_TRANSLATION_CONTEXT
#define B_TRANSLATION_CONTEXT "hello"
int main(void)
{
printf(B_TRANSLATE("Hello, world!\n"));
return 0;
}
This file uses header file Catalog.h, that belongs to locale library. So to
actually be able to use localization in your programs, you have to adjust few
settings in your makefile.
- Adjust a value to your project's APP_MIME_SIG variable.
Application's mime signature should also be set in the following
format: x.vnd-<author>-<project_name>
- Add following two libraries into your LIBS variable: locale localestub
- Add every language, that you want to support, into LOCALES variable,
e.g. 'LOCALES = en de fr' for English, German and French locale
support.
Add the Resource Definition script (also please specify it in RDEF
variable) containing the following entries into project:
resource app_signature "application/x-vnd.-";
resource appnamecatalog_entry "-:System name:Terminal";
Run 'make' to build binary file.
- Run either: 'make catkeys' to get locales/en.catkeys file.
- Copy this file to locales/<language_code>.catkeys and translate it,
as needed.
- When you prepared all needed .catkeys files, run 'make catalogs' to create
catalogs files from them.
- Run either 'make catalogsinstall' or 'make bindcatalogs' to make catalogs
available for application. For more information about differences
between these two commands, please see the next section.
Here is also example makefile for the localized_hello.cpp above:
makefile:
NAME = hello
TYPE = APP
APP_MIME_SIG = x.vnd-example-hello
SRCS = localized_hello.cpp
LIBS = locale localestub
LOCALES = en de fr
include $(BUILDHOME)/etc/makefile-engine
Target Reference
This is supposed to be the list of all non-file related targets.
- default is the same as running make without arguments, it builds output
file
- catkeys creates locales/en.catkeys file, containing all strings from
sources, ready to be localized.
- catalogs compiles all .catkeys files into corresponding .catalog files
- clean cleans project directory of building leftovers, removes
everything in the objects folder.
- rmapp removes only the executable application file from objects folder
- driverinstall installs driver into system.
- install installs program into directory, specified by INSTALL_DIR
variable.
- catalogsinstall installs localization resources catalogs into
/boot/home/config/data/locale/catalogs/<APP_MIME_SIG>
directory for testing purposes. Note that for the distribution of
release version catalogs should be stored in
/boot/common/data/locale/catalogs/<APP_MIME_SIG> instead of
home.
- bindcatalogs binds localization resources catalogs into executable
file's resources (it's alternative way of storing localization
catalogs that doesn't require to distribute separate catalog files).
This How To was created on November 28, 2011 by Peter
Poláčik |
Copyright © 2011 Haiku Inc. |