[haiku-commits] haiku: hrev43451 - docs/develop
- From: zharik@xxxxxx
- To: haiku-commits@xxxxxxxxxxxxx
- Date: Sat, 10 Dec 2011 08:39:31 +0100 (CET)
hrev43451 adds 1 changeset to branch 'master'
old head: 802ac6355d9d2300ad64f798e6431d7b87de5656
new head: 8f03c411b002727e1dc7d4532eb0c1d3c4d8a44c
----------------------------------------------------------------------------
8f03c41: A makefile/Jamfile engines How To added
* This document was written during GCI 2011
by Peter Poláčik and is explaining how to use
makefile and Jamfile engines to start and
setup new development projects for Haiku.
Signed-off-by: Siarzhuk Zharski <zharik@xxxxxx>
[ Peter Polacik <polacik.p@xxxxxxxxx> ]
----------------------------------------------------------------------------
Revision: hrev43451
Commit: 8f03c411b002727e1dc7d4532eb0c1d3c4d8a44c
URL: http://cgit.haiku-os.org/haiku/commit/?id=8f03c41
Author: Peter Polacik <polacik.p@xxxxxxxxx>
Date: Sat Dec 10 07:31:18 2011 UTC
Committer: Siarzhuk Zharski <zharik@xxxxxx>
Commit-Date: Sat Dec 10 07:31:18 2011 UTC
----------------------------------------------------------------------------
1 files changed, 254 insertions(+), 0 deletions(-)
docs/develop/makefile-engine.html | 254 +++++++++++++++++++++++++++++++++
----------------------------------------------------------------------------
diff --git a/docs/develop/makefile-engine.html
b/docs/develop/makefile-engine.html
new file mode 100644
index 0000000..0df205e
--- /dev/null
+++ b/docs/develop/makefile-engine.html
@@ -0,0 +1,254 @@
+<h1>How To Create a Project Using Makefile Engine</h1>
+
+<p>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.</p>
+
+<h2>Contents</h2>
+<p>
+<ul>
+ <li><a href="#getting_started">Getting Started</a></li>
+ <li><a href="#config">Configuring a Project</a></li>
+ <li><a href="#localization">Using Localization</a></li>
+ <li><a href="#targets">Target Reference</a></li>
+</ul>
+</p>
+
+<div id="getting_started"><h2>Getting Started</h2></div>
+
+<p>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:</p>
+
+<p><em>hello.cpp</em>:</p>
+
+<pre><code>#include <stdio.h>
+
+int main(void)
+{
+ printf("Hello world!\n");
+ return 0;
+}
+</code></pre>
+
+<p><em>makefile</em>:</p>
+
+<pre><code>NAME = hello
+TYPE = APP
+SRCS = hello.cpp
+include $(BUILDHOME)/etc/makefile-engine
+</code></pre>
+
+<p>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.</p>
+
+<div id="config"><h2>Configuring a Project</h2></div>
+
+<p>In makefile, there are many variables, to configure builder helpers for your
+needs. Let's take a look at them:</p>
+
+<ul>
+<li><strong>NAME</strong> specifies the name of the project and the output
binary filename</li>
+<li><strong>TYPE</strong> specifies the type of binary, can be one of the
following:
+<ul>
+<li><strong>APP</strong> - Application</li>
+<li><strong>SHARED</strong> - Shared library or add-on</li>
+<li><strong>STATIC</strong> - Static library archive</li>
+<li><strong>DRIVER</strong> - Kernel Driver</li>
+</ul></li>
+<li><strong>APP_MIME_SIG</strong> 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.</li>
+<li><strong>SRCS</strong> 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.</li>
+<li><strong>RDEFS</strong> specifies the resource definition files to be used.
You may
+specify both, relative and full paths to the files.</li>
+<li><strong>RSRCS</strong> specifies the binary file compiled from
<em>RDEF</em>, or created
+separately by Resource Editors, both <em>RDEFS</em> and <em>RSRCS</em> can be
+defined in the same makefile.</li>
+<li><strong>LIBS</strong> specifies additional libraries, that binary file
should be
+linked against. There are two acceptable forms of library
+specifications:
+<ul>
+<li>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</li>
+<li>for version-independent linking of standard C++ libraries, please
+add $(STDCPPLIBS instead of raw "stdc++[.r4] [supc++]" library names</li>
+<li>for localization support add following libraries: locale localestub</li>
+<li>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</li>
+</ul></li>
+<li><strong>LIBPATHS</strong> 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.</li>
+<li><strong>SYSTEM_INCLUDE_PATHS</strong> specifies additional paths to look
for system
+headers. These use the form: #include <header>. Source file
+directories are <em>NOT</em> automatically included here.</li>
+<li><strong>LOCAL_INCLUDE_PATHS</strong> specifies additional paths to look
for local
+headers. There use the form: #include "header". Source file
+directories are automatically included.</li>
+<li><strong>OPTIMIZE</strong> specifies the level of optimization desired, can
be one of
+following: <em>NONE</em>, <em>SOME</em>, <em>FULL</em>.</li>
+<li><strong>LOCALES</strong> 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.</li>
+<li><strong>DEFINES</strong> 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 <em>DEFINES</em> to "DEBUG=1" will
+cause the compiler option "-DDEBUG=1" to be used. However, setting
+<em>DEFINES</em> to "DEBUG" would pass "-DDEBUG" option.</li>
+<li><strong>WARNINGS</strong> 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:
+<ul>
+<li>NONE - supress all warnings</li>
+<li>ALL - enable all warnings</li>
+</ul></li>
+<li><strong>SYMBOLS</strong> specifies, whether image symbols should be
created, so the
+stack crawls in the debugger are meaningful. Setting it to <em>TRUE</em>
+enables the creation of symbols.</li>
+<li><strong>DEBUGGER</strong> specifies debugging settings. If set to
<em>TRUE</em>, it allows
+the application to be run from a source-level debugger. Please note,
+that this will disable all optimization.</li>
+<li><strong>COMPILER_FLAGS</strong> specifies additional compiler flags for
all files.</li>
+<li><strong>LINKER_FLAGS</strong> specifies additional linker flags.</li>
+<li><strong>APP_VERSION</strong> specifies the version of the particular item
(e.g. -app
+3 4 0 d 0 -short 340 -long "340 "<code>echo -n -e '\302\251'</code>).
+"1999 GNU GPL"). This may also be specified in a resource.</li>
+<li><strong>DRIVER_PATH</strong> works only for <em>TYPE</em> ==
<em>DRIVER</em>. It specifies desired
+location of driver in the /dev hierarchy. It's user by the
+driverinstall rule. E.g. <em>DRIVER_PATH</em> = 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".</li>
+<li><strong>INSTALL_DIR</strong> specifies the installation directory of
application.</li>
+</ul>
+
+<p>Please also note, that if you're building your own makefile, that will use
this
+engine, last line must contain:</p>
+
+<pre><code>include $(BUILDHOME)/etc/makefile-engine
+</code></pre>
+
+<div id="localization"><h2>Using Localization</h2></div>
+
+<p>Localization in Haiku programs is achieved simply, as following example
shows.</p>
+
+<p><em>localized_hello.cpp</em>:</p>
+
+<pre><code>#include <stdio.h>
+#include <Catalog.h>
+
+#undef B_TRANSLATE_CONTEXT
+#ifdef B_TRANSLATE_CONTEXT "hello"
+
+int main(void)
+{
+ printf(B_TRANSLATE("Hello, world!\n"));
+ return 0;
+}
+</code></pre>
+
+<p>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.</p>
+
+<ol>
+<li>Adjust a value to your project's <strong>APP_MIME_SIG</strong> variable.
+Application's mime signature should also be set in the following
+format: x.vnd-<author>-<project_name></li>
+<li>Add following two libraries into your <strong>LIBS</strong> variable:
locale localestub</li>
+<li>Add every language, that you want to support, into
<strong>LOCALES</strong> variable,
+e.g. 'LOCALES = en de fr' for English, German and French locale
+support.</li>
+<li><p>Add the Resource Definition script (also please specify it in
<em>RDEF</em>
+variable) containing the following entries into project:</p>
+
+<p>resource app_signature "application/x-vnd.<author>-<project_name>";</p>
+
+<p>resource app<em>name</em>catalog_entry "<author>-<project_name>:System
name:Terminal";</p></li>
+<li><p>Run 'make' to build binary file.</p></li>
+<li>Run either: 'make catkeys' to get locales/en.catkeys file.</li>
+<li>Copy this file to locales/<language_code>.catkeys and translate it,
+as needed.</li>
+<li>When you prepared all needed .catkeys files, run 'make catalogs' to create
+catalogs files from them.</li>
+<li>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.</li>
+</ol>
+
+<p>Here is also example makefile for the localized_hello.cpp above:</p>
+
+<p><em>makefile</em>:</p>
+
+<pre><code>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
+</code></pre>
+
+<div id="targets"><h2>Target Reference</h2></div>
+
+<p>This is supposed to be the list of all non-file related targets.</p>
+
+<ul>
+<li><strong>default</strong> is the same as running make without arguments, it
builds output
+file</li>
+<li><strong>catkeys</strong> creates locales/en.catkeys file, containing all
strings from
+sources, ready to be localized.</li>
+<li><strong>catalogs</strong> compiles all .catkeys files into corresponding
.catalog files</li>
+<li><strong>clean</strong> cleans project directory of building leftovers,
removes
+everything in the objects folder.</li>
+<li><strong>rmapp</strong> removes only the executable application file from
objects folder</li>
+<li><strong>driverinstall</strong> installs driver into system.</li>
+<li><strong>install</strong> installs program into directory, specified by
<em>INSTALL_DIR</em>
+variable.</li>
+<li><strong>catalogsinstall</strong> 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.</li>
+<li><strong>bindcatalogs</strong> 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).</li>
+</ul>
+
+<table border="0" width="100%">
+<tr>
+<td align="left">This How To was created on November 28, 2011 by Peter
+Poláčik</td>
+<td align="right">Copyright © 2011 Haiku Inc.</td>
+</tr>
+</table>
Other related posts: