git.maemo.org Git - hildon/blob - doc/building.sgml

   1 <refentry id="hildon-building">
   2 <refmeta>
   3 <refentrytitle>Compiling the Hildon libraries</refentrytitle>
   4 <manvolnum>3</manvolnum>
   5 <refmiscinfo>Hildon Library</refmiscinfo>
   6 </refmeta>
   7
   8 <refnamediv>
   9 <refname>Compiling the Hildon Libraries</refname>
  10 <refpurpose>
  11 How to compile Hildon itself
  12 </refpurpose>
  13 </refnamediv>
  14   <refsect1 id="overview">
  15     <title>Building Hildon on UNIX-like systems</title>
  16     <para>
  17       This chapter covers building and installing Hildon on UNIX and
  18       UNIX-like systems such as GNU/Linux.
  19     </para>
  20     <para>
  21       On UNIX-like systems Hildon uses the standard GNU build system,
  22       using <application>autoconf</application> for package
  23       configuration and resolving portability issues,
  24       <application>automake</application> for building makefiles that
  25       comply with the GNU Coding Standards, and
  26       <application>libtool</application> for building shared libraries
  27       on multiple platforms.
  28     </para>
  29     <para>
  30       The first thing to do before start building Hildon widgets is to
  31       uncompress the source tarball packages. For example:
  32     </para>
  33     <programlisting>
  34       $ tar xvzf hildon-widgets-2.2.0.tar.gz
  35       $ tar xvjf hildon-widgets-2.2.0.tar.bz2
  36     </programlisting>
  37     <para>
  38       In the toplevel of the directory that is created, there will be
  39       a shell script called <filename>configure</filename> which
  40       you then run to take the template makefiles called
  41       <filename>Makefile.in</filename> in the package and create
  42       makefiles customized for your operating system. The <filename>configure</filename>
  43       script can be passed various command line arguments to determine how
  44       the package is built and installed. The most commonly useful
  45       argument is the <systemitem>--prefix</systemitem> argument which
  46       determines where the package is installed. To install a package
  47       in <filename>/opt/hildon</filename> you would run configure as:
  48     </para>
  49     <programlisting>
  50       $ ./configure --prefix=/opt/hildon
  51     </programlisting>
  52     <para>
  53       A full list of options can be found by running
  54       <filename>configure</filename> with the
  55       <systemitem>--help</systemitem> argument. In general, the defaults are
  56       right and should be trusted. After you've run
  57       <filename>configure</filename>, you then run the
  58       <command>make</command> and <command>make install</command> commands
  59       to build the package and install it, respectively.
  60     </para>
  61     <programlisting>
  62       $ make
  63       $ make install
  64     </programlisting>
  65     <para>
  66       If you don't have permission to write to the directory you are
  67       installing in, you may have to change to root temporarily before
  68       running <literal>make install</literal>. Also, if you are
  69       installing in a system directory, on some systems you will need
  70       to run <command>ldconfig</command> after <literal>make
  71       install</literal> so that the newly installed libraries will be
  72       found.
  73     </para>
  74     <para>
  75       Several environment variables are useful to pass to set before
  76       running configure. <envar>CPPFLAGS</envar> contains options to
  77       pass to the C compiler, and is used to tell the compiler where
  78       to look for include files. The <envar>LDFLAGS</envar> variable
  79       is used in a similar fashion for the linker. Finally, the
  80       <envar>PKG_CONFIG_PATH</envar> environment variable contains
  81       a search path that <command>pkg-config</command> (see below)
  82       uses when looking for for file describing how to compile
  83       programs using different libraries. If you were installing Hildon
  84       and its dependencies into <filename>/opt/hildon</filename>, you
  85       might want to set these variables as:
  86     </para>
  87     <programlisting>
  88       $ CPPFLAGS="-I/opt/hildon/include"
  89       $ LDFLAGS="-L/opt/hildon/lib"
  90       $ PKG_CONFIG_PATH="/opt/hildon/lib/pkgconfig"
  91       $ export CPPFLAGS LDFLAGS PKG_CONFIG_PATH
  92     </programlisting>
  93     <para>
  94       You may also need to set the <envar>LD_LIBRARY_PATH</envar>
  95       environment variable so the systems dynamic linker can find
  96       the newly installed libraries, and the <envar>PATH</envar>
  97       environment program so that utility binaries installed by
  98       the various libraries will be found.
  99     </para>
 100     <programlisting>
 101       $ LD_LIBRARY_PATH="/opt/hildon/lib"
 102       $ PATH="/opt/hildon/bin:$PATH"
 103       $ export LD_LIBRARY_PATH PATH
 104     </programlisting>
 105   </refsect1>
 106   <refsect1 id="dependencies">
 107     <title>Dependencies</title>
 108     <para>
 109       Before you can compile the Hildon widget toolkit, you need to have
 110       various other tools and libraries installed on your
 111       system. The two tools needed during the build process (apart from
 112       the tools mentioned above such as <application>autoconf</application>)
 113       are <command>pkg-config</command> and GNU make.
 114     </para>
 115     <itemizedlist>
 116       <listitem>
 117         <para>
 118           <ulink
 119           url="http://pkg-config.freedesktop.org">pkg-config</ulink>
 120           is a tool for tracking the compilation flags needed for
 121           libraries that are used by the Hildon libraries. For each
 122           library, a small <literal>.pc</literal> text file is installed
 123           in a standard location that contains the compilation flags
 124           needed for that library along with version number information.
 125         </para>
 126       </listitem>
 127       <listitem>
 128         <para>
 129           The Hildon makefiles will mostly work with different versions
 130           of <command>make</command>, however, there tends to be
 131           a few incompatibilities, so the Hildon team recommends
 132           installing <ulink url="http://www.gnu.org/software/make">GNU
 133           make</ulink> if you don't already have it on your system
 134           and using it.
 135         </para>
 136       </listitem>
 137       <listitem>
 138         <para>
 139           GTK+
 140         </para>
 141       </listitem>
 142       <listitem>
 143         <para>
 144           Canberra
 145         </para>
 146       </listitem>
 147     </itemizedlist>
 148   </refsect1>
 149   <refsect1 id="extra-configuration-options">
 150     <title>Extra Configuration Options</title>
 151     <para>
 152       In addition to the normal options, the
 153       <command>configure</command> script for the Hildon library
 154       supports a number of additional arguments.
 155       <cmdsynopsis>
 156         <command>configure</command>
 157         <group>
 158           <arg>--disable-gtk-doc</arg>
 159           <arg>--enable-gtk-doc</arg>
 160         </group>
 161         <group>
 162           <arg>--enable-deprecated=[no|yes]</arg>
 163         </group>
 164         <group>
 165           <arg>--with-examples=[no|yes]</arg>
 166         </group>
 167         <group>
 168           <arg>--with-html-dir=PATH</arg>
 169         </group>
 170         <group>
 171           <arg>--with-maemo-gtk=[no|yes]</arg>
 172         </group>
 173         <group>
 174           <arg>--with-asserts=[no|yes]</arg>
 175         </group>
 176       </cmdsynopsis>
 177     </para>
 178     <formalpara>
 179       <title><systemitem>--disable-gtk-doc</systemitem> and
 180         <systemitem>--enable-gtk-doc</systemitem></title>
 181
 182       <para>
 183         The <application>gtk-doc</application> package is
 184         used to generate the reference documentation included
 185         with Hildon. By default, support for <application>gtk-doc</application>
 186         is disabled because it requires several extra dependencies
 187         to be installed. If you have
 188         <application>gtk-doc</application> installed and
 189         are modifying Hildon, you may want to enable
 190         <application>gtk-doc</application> support by passing
 191         in <systemitem>--enable-gtk-doc</systemitem>. If not
 192         enabled, pre-generated HTML files distributed with Hildon
 193         will be installed.
 194       </para>
 195     </formalpara>
 196
 197     <formalpara>
 198       <title><systemitem>--enable-deprecated</systemitem></title>
 199
 200       <para>
 201         This option allows you to specify whether deprecated widgets included in the
 202         package will be built or not.
 203       </para>
 204     </formalpara>
 205
 206     <formalpara>
 207       <title><systemitem>--with-examples</systemitem></title>
 208
 209       <para>
 210         This option allows you to specify whether examples included in the
 211         package will be built or not.
 212       </para>
 213     </formalpara>
 214
 215     <formalpara>
 216       <title><systemitem>--with-html-dir</systemitem></title>
 217
 218       <para>
 219         This option allows you to specify the directory to install the
 220         generated documentation.
 221       </para>
 222     </formalpara>
 223
 224     <formalpara>
 225       <title><systemitem>--with-maemo-gtk</systemitem></title>
 226
 227       <para>
 228         Use Maemo GTK+ API (enabled by default).
 229       </para>
 230     </formalpara>
 231
 232     <formalpara>
 233       <title><systemitem>--with-asserts</systemitem></title>
 234
 235       <para>
 236         Build with the assertion checks
 237       </para>
 238     </formalpara>
 239
 240   </refsect1>
 241
 242 </refentry>
 243
 244 <!-- Local Variables: -->
 245 <!-- sgml-parent-document: ("hildon-docs.sgml" "chapter" "refentry")  -->
 246 <!-- End: -->