uicache/theos/documentation/makefiles.docbook

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY project "<literal>Theos</literal>">
]>
<chapter>
  <title>Makefiles</title>

  <section id="intro">
    <title>Introduction</title>

    <para>&project; is a set of Makefiles designed to take away the complexity
    of building and organizing iPhoneOS projects without the use of Xcode (or
    even Mac OS X.)</para>
  </section>

  <section id="structure">
    <title>Structure of a Makefile</title>

    <para>Here is an example makefile for a project using &project;</para>

    <programlisting># System variables such as MODULES and TARGET.

include theos/makefiles/common.mk

# Instance-related variables such as xxx_FILES.

TOOL_NAME = Simple
Simple_FILES = simple.mm

include $(THEOS_MAKE_PATH)/tool.mk

# Custom rules</programlisting>
  </section>

  <section id="project-types">
    <title>Project Types</title>

    <para>Projects are divided into different types, briefly described below.
    To create a project of a given type, simply include its makefile. For
    example, to create a command-line tool:</para>

    <programlisting>include theos/makefiles/tool.mk</programlisting>

    <para>From one Makefile, you can build multiple types of project (just
    include both project type makefiles). An example:</para>

    <programlisting>include theos/makefiles/common.mk

TWEAK_NAME = Simple
Simple_FILES = Tweak.mm

TOOL_NAME = simpleutility
simpleutility_FILES = su.c

include $(THEOS_MAKE_PATH)/tweak.mk
include $(THEOS_MAKE_PATH)/tool.mk</programlisting>

    <para>You can also build multiple instances of a single project type from
    one Makefile.</para>

    <programlisting>include theos/makefiles/common.mk

TWEAK_NAME = Simple Complex
Simple_FILES = Tweak.mm
Complex_FILES = 1.mm 2.mm 3.mm 4.mm

include $(THEOS_MAKE_PATH)/tweak.mk</programlisting>

    <section>
      <title>Aggregate (<filename>aggregate.mk</filename>)</title>

      <para>An Aggregate project is a project that consists of several
      subprojects. Each subproject can be any valid type (including another
      Aggregate).</para>

      <variablelist>
        <varlistentry>
          <term><varname>SUBPROJECTS</varname></term>

          <listitem>
            <para><varname>The SUBPROJECTS</varname> variable defines the
            directory names that contain the subprojects this Aggregate
            project should build.</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>

    <section>
      <title><systemitem class="library">UIKit</systemitem> Applications
      (<filename>application.mk</filename>)</title>

      <para>An <literal>application</literal> is an Objective-C program that includes a GUI
      component, and by default links against <systemitem
      class="library">UIKit</systemitem>.</para>
    </section>

    <section>
      <title>Command Line Tools (<filename>tool.mk</filename>)</title>

      <para>A <literal>tool</literal> is a program that does not have a GUI component, and differs from an <literal>application</literal> wherein it does
      not link against <systemitem class="library">UIKit</systemitem>. This
      project type is intended for command-line tools, daemons, etc.</para>
    </section>

    <section>
      <title>MobileSubstrate Tweaks (<filename>tweak.mk</filename>)</title>

      <para>A <literal>tweak</literal> is a dynamic library that links against <systemitem
      class="library">MobileSubstrate</systemitem> for the purposes of adding
      and replacing functions and methods at runtime.</para>

      <para>Tweaks in &project; are often written with the help of the Logos
      preprocessor.</para>

      <note>
        <para>A <literal>tweak</literal> does not, by default, link against <systemitem
        class="library">UIKit</systemitem>. If you want to link against
        <systemitem class="library">UIKit</systemitem>, add it to
        <varname>xxx_FRAMEWORKS</varname>.</para>
      </note>
    </section>

    <section>
      <title>Bundles (<filename>bundle.mk</filename>)</title>

      <para>A <literal>bundle</literal> is a dynamic library meant to be loaded into another
      application at runtime, using the <classname>NSBundle</classname> class.</para>
    </section>

    <section>
      <title>Frameworks (<filename>framework.mk</filename>)</title>

      <!--para>A framework is a dynamic library bundle, containing resources, meant to be linked by another
      application or dynamic library.</para-->
    </section>

    <section>
      <title>Dynamic Libraries (<filename>library.mk</filename>)</title>
    </section>
  </section>

  <section>
    <title>Variables</title>

    <section>
      <title>System Constants</title>

      <para>These constants are listed for use in toplevel Makefiles.</para>

      <variablelist>
        <varlistentry>
          <term><varname>THEOS</varname></term>
          <term><varname>THEOS_MAKE_PATH</varname></term>
          <term><varname>THEOS_BIN_PATH</varname></term>
          <term><varname>THEOS_LIBRARY_PATH</varname></term>
          <term><varname>THEOS_INCLUDE_PATH</varname></term>
          <term><varname>THEOS_MODULE_PATH</varname></term>

          <listitem>
            <para>Used for locating other &project; resources, such as binaries, scripts, modules and other makefiles.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><varname>THEOS_PLATFORM_NAME</varname></term>
          <term><varname>THEOS_TARGET_NAME</varname></term>

          <listitem>
            <para>The build platform and the platform being targeted, normalized.</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>

    <section>
      <title>System Variables</title>

      <para>These variables are listed for use in toplevel Makefiles, but if
      you really want to change them, you can.</para>

      <variablelist>
        <varlistentry>
          <term><varname>THEOS_BUILD_DIR</varname></term>

          <listitem>
            <para>Build directory (objects are placed in
            <filename><varname>THEOS_BUILD_DIR</varname>/<varname>THEOS_OBJ_DIR_NAME</varname></filename>).
            Defaults to the current directory.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><varname>THEOS_OBJ_DIR_NAME</varname></term>

          <listitem>
            <para>Output file directory name. Defaults to
            <filename>.theos/obj</filename>.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><varname>THEOS_STAGING_DIR</varname></term>

          <listitem>
            <para>Package staging directory. Defaults to
            <filename><varname>THEOS_PROJECT_DIR</varname>/_</filename>.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><varname>Blah</varname></term>

          <listitem>
            <para>Description</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>

    <section>
      <title>Local Variables</title>

      <para>These variables are not tied to any particular project instance,
      and can be set either in the toplevel Makefile or in the
      environment.</para>

      <variablelist>
        <varlistentry>
          <term><varname>ADDITIONAL_CFLAGS</varname></term>

          <term><varname>ADDITIONAL_CCFLAGS</varname></term>

          <term><varname>ADDITIONAL_OBJCFLAGS</varname></term>

          <term><varname>ADDITIONAL_OBJCCFLAGS</varname></term>

          <term><varname>ADDITIONAL_LDFLAGS</varname></term>

          <listitem>
            <para>The <varname>ADDITIONAL_FLAGS</varname> variables control
            additional compilation flags for an entire project. These
            variables are not passed into subdirectories or subprojects, but
            can be made to do so with <command>export</command>, as in
            <command>export
            <varname>ADDITIONAL_CFLAGS</varname></command>.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><varname>CFLAGS</varname></term>

          <term><varname>CCFLAGS</varname></term>

          <term><varname>OBJCFLAGS</varname></term>

          <term><varname>OBJCCFLAGS</varname></term>

          <term><varname>LDFLAGS</varname></term>

          <listitem>
            <para>The unqualified <varname>FLAGS</varname> variables can be
            used for additional compilation flags stored in the environment or
            given on the commandline, as in <command>make
            <varname>CFLAGS</varname>=-funroll-loops</command>.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><varname>OPTFLAG</varname></term>

          <listitem>
            <para>The <varname>OPTFLAG</varname> variable controls
            optimization. Its default value is <literal>-O2</literal>.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><varname>DEBUG</varname></term>

          <listitem>
            <para>The <varname>DEBUG</varname> variable controls compilation
            of debug symbols and stripping. When set to <literal>1</literal>,
            <literal>-ggdb -DDEBUG</literal> is added to the compilation
            flags, stripping is disabled, and optimization flags are stripped
            from <varname>OPTFLAG</varname>. Additionally,
            <literal>+debug</literal> is appended to the package build
            identifier.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><varname>Blah</varname></term>

          <listitem>
            <para>Description</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><varname>Blah</varname></term>

          <listitem>
            <para>Description</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><varname>Blah</varname></term>

          <listitem>
            <para>Description</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><varname>Blah</varname></term>

          <listitem>
            <para>Description</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>

    <section>
      <title>Project Variables</title>

      <para>The various project type makefiles all support a common set of
      variables, described below. In this list, <literal>xxx</literal> is
      assumed to be the project instance name.</para>

      <variablelist>
        <varlistentry>
          <term><varname>xxx_FILES</varname></term>

          <listitem>
            <para>The <varname>FILES</varname> variables contain
            space-delimited lists of the source files comprising the project.
	    Including files with the <filename>.m</filename> or <filename>.mm</filename> extensions causes the Objective-C runtime and
            Foundation framework to be linked with your project.</para>
            <para>The older type-specific <varname>FILES</varname> variables are deprecated in favour of <varname>xxx_FILES</varname>.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><varname>xxx_OBJ_FILES</varname></term>

          <listitem>
            <para>The <varname>OBJ_FILES</varname> variable contains a
            space-delimited list of precompiled object files
	    (<filename>.o</filename> or library/framework binaries) to be linked with the project.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><varname>xxx_FRAMEWORKS</varname></term>

          <term><varname>xxx_PRIVATE_FRAMEWORKS</varname></term>

          <listitem>
            <para>The <varname>FRAMEWORKS</varname> variables contain
            space-delimited lists of frameworks to link with the project, if
            Objective-C source files are used. Including
            <varname>PRIVATE_FRAMEWORKS</varname> causes the private Framework
            directory to be included in the Framework search path.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><varname>xxx_CFLAGS</varname></term>

          <term><varname>xxx_CCFLAGS</varname></term>

          <term><varname>xxx_OBJCFLAGS</varname></term>

          <term><varname>xxx_OBJCCFLAGS</varname></term>

          <listitem>
            <para>The <varname>FLAGS</varname> variables contain flags passed
            to the compiler for a given filetype.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><varname>xxx_LDFLAGS</varname></term>

          <listitem>
            <para>The <varname>LDFLAGS</varname> variable contains flags
            passed to the linker for a project.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><varname>Blah</varname></term>

          <listitem>
            <para>Description</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </section>
  </section>
</chapter>