<?xml version="1.0" encoding="ISO-8859-1"?>
<?xml-stylesheet type="text/xsl" href="stylesheet.xsl"?>

<doc>
    <title>How to compile</title>





    <!-- ************************************************************************* -->

    <body>
        
        <h2>Compiling C++ Example Programs on Any Operating System Using CMake</h2>
        The best way to compile a program that uses dlib is to use <a href="http://www.cmake.org">CMake</a>.  For
        example, the following commands will compile the example programs on any operating
        system:
<code_box>
cd examples
mkdir build
cd build
cmake ..
cmake --build . --config Release
</code_box>
Note that you also need to have a C++ compiler installed on your system.  There are free C++ compilers
for most operating systems.  For example, Visual Studio Express is free on Windows and GCC is free and
works well on Mac OS X and Linux systems.  If you have multiple compilers/IDEs installed then you can
tell CMake which one you want it to use via the -G option.
<p>
   The <a href="examples/CMakeLists.txt.html">examples/CMakeLists.txt</a> file tells CMake how to build
   the examples.  You can create your own projects by starting with this file and editing it however you like.
   You can also perform additional configuration of a cmake project using the cmake-gui or ccmake tool.  For example,
   if you are using dlib's face detector then you should turn on either SSE4 or AVX instructions since this
   makes it run much faster (also see <a href="faq.html#Whyisdlibslow">this FAQ</a>). 
</p>
<p>
   Finally, note that when using Visual Studio, CMake will by default generate a 32bit executable.  
   This means the programs you compile will only be able to use 2GB of RAM.  To avoid this, you need
   to tell CMake to generate a 64bit executable.  You do this by using a command like 
   <code_box>cmake -G "Visual Studio 10 2010 Win64" ..</code_box> instead of <code_box>cmake ..</code_box>  
   You can see the list of valid arguments to <tt>-G</tt> by running <tt>cmake</tt> with no options. 
</p>
            

<br/>
        <h2>Compiling Dlib's Python Interface</h2>
        <p>
           Go to the base folder of the dlib repository and run <tt>python setup.py install</tt>.  That
           should compile and install the dlib python API on your system. 
        </p>
        <p>
           Alternatively, if you want to add more python bindings to dlib's
           python interface then you probably want to avoid the setup.py file
           and work directly using CMake.  In particular, dlib's python API is
           built by the CMake project in the tools/python folder.  You build
           this project using the usual CMake commands and when compiled it
           outputs the dlib shared library that defines the python API for dlib.
        </p>
<br/>


        <h2>Compiling C++ Examples Without CMake</h2>

        <p>
           In most cases, to use this library all you have to do is extract it somewhere, make
           sure the folder <i>containing</i> the dlib folder is in your include path, and
           finally add <a href="dlib/all/source.cpp.html">dlib/all/source.cpp</a> to your
           project.  It is worth noting that most of dlib is "header-only" which means that, in
           many cases, you don't actually have to build dlib/all/source.cpp into your
           application.  So if you don't get linker errors when you exclude dlib/all/source.cpp
           from your project then you don't need it.
        </p>
        <p>
            An example makefile that uses this library can be found here: <a
            href="dlib/test/makefile">dlib/test/makefile</a>.  It is the makefile used to build
            the regression test suite for this library.  
        </p>
        <p>
           Again, note that you should <b><i>not</i></b> add the dlib folder itself to your compiler's include path.  
           Doing so will cause the
           build to fail because of name collisions (e.g. dlib/string.h with string.h from the standard library).  
           Instead you should add the folder that contains the dlib folder to your include search path and then use 
           include statements of the form <tt>#include &lt;dlib/queue.h&gt;</tt>.  This will ensure that everything 
           builds correctly.
        </p>
        <p>
           Note also that if you want to work with jpeg/png files using dlib then you will
           need to link your program with libjpeg and/or libpng.  You also need to tell dlib 
           about this by defining the DLIB_JPEG_SUPPORT and DLIB_PNG_SUPPORT preprocessor directives.
           How you "link to libjpeg/libpng" varies from platform to platform.  On UNIX machines you
           usually just add a -ljpeg or -lpng switch to your compiler (after installing the libraries).
           On windows it's less well defined.  So dlib comes with a copy of these libraries in the dlib/external
           folder so that you can statically compile them into your application if no system wide version 
           is available on your machine.  If all this talk about linking is confusing to you then
           just use CMake.  It will set this all up for you.
        </p>
        <p>
           Dlib is also capable of using any optimized BLAS or LAPACK libraries that are
           installed on your system.  Linking to these libraries will make many things run
           faster.  To do this you define the DLIB_USE_BLAS and/or DLIB_USE_LAPACK preprocessor
           directives and then link your program with whatever BLAS or LAPACK libraries you
           have.  If you use CMake it will set this up automatically.
        </p>




        <h3>Compiling on Linux From Command Line</h3>
        From within the examples folder, you can compile nearly all of the examples with a single command like so:
<code_box>
g++ -O3 -I.. ../dlib/all/source.cpp -lpthread -lX11 example_program_name.cpp
</code_box>
        Note that not all examples require this much work.  For example, the svm_ex.cpp example
        can be compiled with just:
<code_box>
g++ -O3 -I.. svm_ex.cpp
</code_box>

On non-Linux systems like Solaris, you might have to link to other libraries.  For example, I have seen systems
where it was also necessary to supply -lnsl or -lsocket options to g++.  Additionally, the X11 development
library isn't installed on Ubuntu by default.  So if you require it and are using Ubuntu you can install
it by typing:
<code_box>
sudo apt-get install libx11-dev
</code_box>

        <h3>Compiling on Windows Using GCC</h3>
        <p>
            The commands for gcc on windows are the same as above but you may also have to link 
            (via the -l option) to the following libraries: gdi32, comctl32, user32, winmm, ws2_32, or imm32.
            However, it's worth pointing out that Visual Studio Express is free and a much better choice for
            windows development than gcc.
        </p>

        <h3>Compiling on Windows Using Visual Studio</h3>
        <p>
           All you need to do is create an empty console project. Then add dlib/all/source.cpp to it and add the
           folder containing the dlib folder to the #include search path.  Then you can compile any example program 
           by adding it to your project.  
        </p>
        <p>
           Again, note that dlib will only be able to work with jpeg and png files if you link
           in libjpeg and libpng.  In Visual Studio, the easiest way to do this is to add all the
           source files in the dlib/external folder into your project and also define the
           DLIB_PNG_SUPPORT and DLIB_JPEG_SUPPORT preprocessor directives.  If you don't know
           how to configure Visual Studio then you should use CMake as shown above since it will
           take care of everything automatically.
        </p>


         <br/>
        <center><h1>Miscellaneous Preprocessor Directives</h1></center>

         <p>
            In addition to the preprocessor directives mentioned above, there
            are a few more you can supply during the build process to cause the
            library to build in various optional ways.  By default, the library
            will always do something reasonable, but they are listed here in
            the event that you need to use them.
         </p>


         <anchor>ENABLE_ASSERTS</anchor>
        <h3>#define ENABLE_ASSERTS</h3>
        <p>
           Defining this directive causes all the <a href="metaprogramming.html#DLIB_ASSERT">DLIB_ASSERT</a> macros to
           be active.  If you are using Visual Studio or CMake then ENABLE_ASSERTS will be automatically enabled
           for you when you compile in debug mode.  However, if you are using a different build system then you
           might have to manually enable it if you want to turn the asserts on.
        </p>

         <anchor>DLIB_ISO_CPP_ONLY</anchor>
        <h3>#define DLIB_ISO_CPP_ONLY</h3>
        <p>
           This is a #define directive that you can set to cause the library to exclude all non ISO C++ code (The things in the <a href="api.html">API wrappers</a> section and any objects that depend on those wrappers).
           This is useful if you are trying to build on a system that isn't fully supported by the library or if you 
           just decide you don't want any of that stuff compiled into your program for your own reasons.
        </p>
         <anchor>DLIB_NO_GUI_SUPPORT</anchor>
        <h3>#define DLIB_NO_GUI_SUPPORT</h3>
        <p>
           This is just like the DLIB_ISO_CPP_ONLY option except that it excludes only the GUI part of the library.
           An example of when you might want to use this would be if you don't need GUI support and you are building
           on a UNIX platform that doesn't have the X11 headers installed.
        </p>
         <anchor>NO_MAKEFILE</anchor>
        <h3>#define NO_MAKEFILE</h3>
        <p>
           This preprocessor directive causes the dlib headers to pull in all the 
           code that would normally be built in dlib/all/source.cpp.  Thus if you #define NO_MAKEFILE you won't 
           have to add dlib/all/source.cpp to your project.  The <i>only</i> time this is useful is when your 
           project consists of a single translation unit (i.e. a single cpp file).  In this instance NO_MAKEFILE
           allows you to easily build your project on the command line by saying something like <tt>g++ -DNO_MAKEFILE
           project.cpp</tt>.  But again, this is only for single cpp file projects.  If you use NO_MAKEFILE with projects 
           that contain more than one cpp file you will get linker errors about multiply defined symbols.
        </p>
        <p>
           Also note that if you use this macro then the <a href="metaprogramming.html#DLIB_STACK_TRACE">stack trace</a>
           functionality in the library will be disabled.   
        </p>
         <anchor>DLIB_THREAD_POOL_TIMEOUT</anchor>
        <h3>#define DLIB_THREAD_POOL_TIMEOUT &lt;time-in-milliseconds&gt;</h3>
        <p>
           If you use dlib to create your threads then you receive the benefit of the dlib dynamic thread pool (Note that the 
           dlib::<a href="api.html#thread_pool">thread_pool</a> object is something else unrelated to this so don't confuse
           the two).  This pool 
           enables dlib to spawn new threads very rapidly since it draws threads back out of its thread pool when 
           the pool isn't empty. 
        </p>
        <p>
           Thus, when a thread that was created by dlib ends it actually goes back into the dlib thread pool
           and waits DLIB_THREAD_POOL_TIMEOUT milliseconds before totally terminating and releasing its resources back
           to the operating system.  The default timeout used by this library is 30,000 milliseconds (30 seconds).  You
           may however change this to whatever you like by defining DLIB_THREAD_POOL_TIMEOUT to some new value.  
        </p>



    
    </body>



    <!-- ************************************************************************* -->

</doc>
