diff options
Diffstat (limited to 'ml/dlib/docs/docs/compile.xml')
| -rw-r--r-- | ml/dlib/docs/docs/compile.xml | 227 |
1 files changed, 227 insertions, 0 deletions
diff --git a/ml/dlib/docs/docs/compile.xml b/ml/dlib/docs/docs/compile.xml new file mode 100644 index 000000000..bb21b3fa9 --- /dev/null +++ b/ml/dlib/docs/docs/compile.xml @@ -0,0 +1,227 @@ +<?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++11 compiler installed on your system. There are free C++11 compilers +for most operating systems. For example, Visual Studio 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 14 2015 Win64" -T host=x64 ..</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. Note also the <tt>-T host=x64</tt> + option, which tells Visual Studio to let the compiler use more than 2GB of RAM. That is important if you don't want the compiler to + crash from running out of RAM in some situations. +</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 dlib/all/source.cpp 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 <dlib/queue.h></tt>. This will ensure that everything + builds correctly. + </p> + <p> + Note also that if you want to work with jpeg/png/gif files using dlib then you will + need to link your program with libjpeg, libpng, and/or libgif. You also need to tell dlib + about this by defining the DLIB_JPEG_SUPPORT, DLIB_PNG_SUPPORT, and DLIB_GIF_SUPPORT preprocessor directives. + How you "link to libjpeg/libpng/libgif" varies from platform to platform. On UNIX machines you + usually just add a -ljpeg, -lpng, or -lgif switch to your compiler (after installing the libraries). + On windows it's less well defined. So dlib comes with a copy of libjpeg and libpng in the dlib/external + folder so 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++ -std=c++11 -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++ -std=c++11 -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. + </p> + + <h3>Compiling on Windows Using Visual Studio 2015 or Newer</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 + libjpeg, libpng, and zlib 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 <time-in-milliseconds></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> |