From 4135f1fd20076c2632f838a164a96cf1c2914343 Mon Sep 17 00:00:00 2001 From: Humdinger Date: Mon, 13 Mar 2017 19:33:40 +0100 Subject: [PATCH] Update makefile-engine doc to v2.6 Grammar, formatting, updated paths etc. --- docs/develop/makefile-engine.html | 206 ++++++++++++++++-------------- 1 file changed, 108 insertions(+), 98 deletions(-) diff --git a/docs/develop/makefile-engine.html b/docs/develop/makefile-engine.html index 9f95a34386..731c7491cd 100644 --- a/docs/develop/makefile-engine.html +++ b/docs/develop/makefile-engine.html @@ -1,20 +1,22 @@ - How To Create a Project Using Makefile Engine + How To Create a Project Using the Makefile Engine -

How To Create a Project Using Makefile Engine

+

How To Create a Project Using the 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 +

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 user's convenience.

+with Haiku. We made both, the Makefile and Jamfile engines completely +target-compatible for the user's convenience.

Contents

@@ -28,10 +30,10 @@ target-compatible for user's convenience.

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:

+

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:

@@ -44,25 +46,29 @@ int main(void) } -

makefile:

+

Makefile:

NAME = hello
 TYPE = APP
 SRCS = hello.cpp
-include $(BUILDHOME)/etc/makefile-engine
+
+## Include the Makefile-Engine
+DEVEL_DIRECTORY := \
+	$(shell findpaths -r "makefile_engine" B_FIND_PATH_DEVELOP_DIRECTORY)
+include $(DEVEL_DIRECTORY)/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 +

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 +

In Makefile, there are many variables to configure builder helpers for your needs. Let's take a look at them:

-
  • APP_MIME_SIG specifies application's mime signature for +
  • APP_MIME_SIG specifies the 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 +provided to the 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.
    • +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 +paths and paths relative to the location of the Makefile. All objects, +regardless of the location of their sources will be created in the +common object directory. Please note, that this means, that the Makefile won't work correctly, if two source files with the same name -(e.g. source.c and source.cpp) are included from different +(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: +separately by resource editors. Both RDEFS and RSRCS can be +defined in the same Makefile.
    • +
  • LIBS specifies additional libraries, that the binary file should be +linked against. There are two acceptable forms of library specifications:
  • 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. +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 the 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 +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 +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.
    • @@ -126,9 +131,9 @@ 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.
    • +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: @@ -151,15 +156,17 @@ that this will disable all optimization.
    • 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". +~/config/non-packaged/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:

    +

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

    -
    include $(BUILDHOME)/etc/makefile-engine
+
    DEVEL_DIRECTORY := \
+	$(shell findpaths -r "makefile_engine" B_FIND_PATH_DEVELOP_DIRECTORY)
+include $(DEVEL_DIRECTORY)/etc/makefile-engine
 
    
 
 
    Using Localization
    
@@ -181,46 +188,50 @@ int main(void)
 }
    -

    This file uses header file Catalog.h, that belongs to locale library. So to +

    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.

    +settings in your Makefile.

      -
    1. Adjust a value to your project's APP_MIME_SIG variable. +

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

      3. -
    3. Add following two libraries into your LIBS variable: locale localestub
      4. -
    4. Add every language, that you want to support, into LOCALES variable, -e.g. 'LOCALES = en de fr' for English, German and French locale -support.
      5. -

    5. Add the Resource Definition script (also please specify it in RDEF -variable) containing the following entries into project:

      +format: x.vnd-<author>-<project_name>

      6. +

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

      7. +

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

      8. +

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

      -

      resource app_signature "application/x-vnd.-";

      - -

      resource appnamecatalog_entry "-:System name:Terminal";

      9. -

    9. Run 'make' to build binary file.

      10. -
    10. Run either: 'make catkeys' to get locales/en.catkeys file.
      11. -
    11. Copy this file to locales/<language_code>.catkeys and translate it, -as needed.
      12. -
    12. When you prepared all needed .catkeys files, run 'make catalogs' to create -catalogs files from them.
      13. -
    13. 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.
      14. +
      resource app_signature "application/x-vnd.<author>-<project_name>";
+resource appnamecatalog_entry "<author>-<project_name>:System name:Terminal";
      +

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

      15. +

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

      16. +

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

      17. +

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

      18. +

    18. 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 also example makefile for the localized_hello.cpp above:

    +

    Here is an example Makefile for the localized_hello.cpp above:

    -

    makefile:

    +

    Makefile:

    NAME = hello
 TYPE = APP
-APP_MIME_SIG = x.vnd-example-hello
+APP_MIME_SIG = x-vnd.example-hello
 SRCS = localized_hello.cpp
 LIBS = locale localestub
 LOCALES = en de fr
-include $(BUILDHOME)/etc/makefile-engine
+
+## Include the Makefile-Engine
+DEVEL_DIRECTORY := \
+	$(shell findpaths -r "makefile_engine" B_FIND_PATH_DEVELOP_DIRECTORY)
+include $(DEVEL_DIRECTORY)/etc/makefile-engine

    Target Reference

    @@ -228,33 +239,32 @@ include $(BUILDHOME)/etc/makefile-engine

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

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