How To Create a Project Using the Makefile Engine

Haiku helps developers with the build process of their projects by providing the so called makefile-engine. It's made of two files, that reside in /boot/system/develop/etc directory and are named 'Makefile' and 'makefile-engine'.
Together, these two files provide you with a simple ready-to-be used build engine for your projects.

This How-To describes the makefile-engine v2.6 and the Makefile template v2.6. 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 the user's convenience.

Contents

Getting Started

To start a project, just copy Makefile from /boot/system/develop/etc directory, into your project directory. Write a few files that you want to add to your project. Add either relative or full paths to them into the SRCS variable definition in the Makefile and run make. Example files for a "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 the Makefile-Engine
DEVEL_DIRECTORY := \
	$(shell findpaths -r "makefile_engine" B_FIND_PATH_DEVELOP_DIRECTORY)
include $(DEVEL_DIRECTORY)/etc/makefile-engine

After creating both these files in same directory, just go there in Terminal, using the 'cd' command and run 'make'. This will create a new directory, named in the format: 'objects.x86-cc2-release' (the name depends on current compiler, that may be either "cc2" or "cc4", 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:

Please also note, that if you're building your own Makefile, that will use this engine, last lines must contain:

DEVEL_DIRECTORY := \
	$(shell findpaths -r "makefile_engine" B_FIND_PATH_DEVELOP_DIRECTORY)
include $(DEVEL_DIRECTORY)/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.

  1. 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>

  2. Add following two libraries into your LIBS variable: locale localestub

  3. Add every language, that you want to support, into LOCALES variable, e.g. 'LOCALES = en de fr' for English, German and French locale support.

  4. Add the resource definition script (also specified in the RDEF variable) containing the following entries to project:

    resource app_signature "application/x-vnd.<author>-<project_name>";
resource app_name_catalog_entry "<author>-<project_name>:System name:Terminal";

  5. Run 'make' to build the binary file.

  6. Run 'make catkeys' to get the locales/en.catkeys file.

  7. Copy this file to locales/<language_code>.catkeys and translate it, as needed.

  8. When you've prepared all needed .catkeys files, run 'make catalogs' to create catalog files from them.

  9. Run either 'make catalogsinstall' or 'make bindcatalogs' to make the catalogs available for the application. For more information about differences between these two commands, please see the next section.

Here is an 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 the Makefile-Engine
DEVEL_DIRECTORY := \
	$(shell findpaths -r "makefile_engine" B_FIND_PATH_DEVELOP_DIRECTORY)
include $(DEVEL_DIRECTORY)/etc/makefile-engine

Target Reference

This is supposed to be the list of all non-file related targets.

This How-To was originally created on November 28, 2011 by Peter Poláčik Copyright © 2017 Haiku Inc.