diff options
Diffstat (limited to 'apidocs/Install.txt')
| -rw-r--r-- | apidocs/Install.txt | 158 |
1 files changed, 158 insertions, 0 deletions
diff --git a/apidocs/Install.txt b/apidocs/Install.txt new file mode 100644 index 00000000..30b4de99 --- /dev/null +++ b/apidocs/Install.txt @@ -0,0 +1,158 @@ +Libical uses the CMake buildsystem. + +Please see the comments at the top of CMakeLists.txt for +the available configuration options you can pass to cmake. + +The installation directory defaults to /usr/local on UNIX +and c:/Program Files on Windows. You can change this by +passing -DCMAKE_INSTALL_PREFIX=/install/path to cmake. + +To build a debug version pass -DCMAKE_BUILD_TYPE=Debug to cmake. + +To build libical you will need: + - a C99-compliant C compiler (let us know if the build fails with your C compiler) + - a C11-compliant C compiler for libical-glib + - a C++11 compliant compiler for C++ bindings + - CMake version 3.11.0 or higher + - Perl + - libicu (not required but strongly recommended) + +Building on Unix with gcc or clang: +% mkdir build +% cd build +% cmake .. +% make +% make install + +Building on Windows with MicroSoft Visual Studio: +From a command prompt for the version of MSVC you want to use +% mkdir build +% cd build +% cmake -G "NMake Makefiles" .. +% nmake +% nmake install + +NOTE: Some MSVC 32bit compilers (like MSVC2005) use a 64bit version of time_t. +In these cases you must pass -DUSE_32BIT_TIME_T=true to cmake to make sure +the 32bit version of time_t is used instead. + +Building on Windows with mingw: +Make sure you have the path to the MinGW programs in %PATH% first, for example: +% set "PATH=c:\MinGW\mingw64\bin;%PATH%" +% mkdir build +% cd build +% cmake -G "MinGW Makefiles" .. +% mingw32-make +% mingw32-make install + +Building on Windows under Cygwin: +% mkdir build +% cd build +% cmake .. +% make +% make install + +Building on MSYS with mingw: +% mkdir build +% cd build +% cmake -G "MSYS Makefiles" .. +% nmake +% nmake install + +To run the test suite, from inside the build directory +run 'make test' (or 'nmake test' or 'mingw32-make test') + +To run the test suite in verbose mode, pass ARGS="-V" to the make command +For example: nmake test ARGS="-V" + +By default, the buildsystem creates shared(dynamic) and static versions +of the libraries, but that behavior can be modified at CMake time: + - To build the static libraries only, pass -DSTATIC_ONLY=True to CMake. + - To build the shared libraries only, pass -DSHARED_ONLY=True to CMake. + +== Building with Different Compilers == +For example, say you want to use Clang to build on Linux. +Then you can set the C and C++ compilers at CMake time, like so: +% CC=clang CXX=clang++ cmake .. + +== Building for OSX (Mac) == +Homebrew: + A couple of necessary dependencies do not have their headers + and development libraries linked into /usr/local/{include,lib} due + to possible contamination with the operating system versions of the + same name. This is known to be the case with libffi and libxml2 + Fix is to export PKG_CONFIG_PATH so CMake can find them, as in: + export PKG_CONFIG_PATH=/usr/local/opt/libffi/lib/pkgconfig:\ + /usr/local/opt/libxml2/lib/pkgconfig + + Also, if building the gtkdocs you'll need to say where the xml + catalog files can be found so the gtk entities are located, like so: + export XML_CATALOG_FILES=/usr/local/etc/xml/catalog + +== Optional Dependencies == +* libicu "International Components for Unicode" development libraries. + Highly recommended for RSCALE support. + libicu can be found at http://www.icu-project.org + + If CMake doesn't locate your libicu installation try setting the + ICU_ROOT or ICU_BASE environment variables to the top folder where + libicu is installed and run cmake again. + +* Berkeley DB storage. + Optional for the Berkeley Database storage support. + The development toolkit can be found at https://www.oracle.com/database/berkeley-db + + ** This code path has not been fully tested. + ** Don't be surprised if there are bugs. + ** Do NOT use for production code. + +* GObject Introspection. To generate GObject introspection "typelib" + files pass the -DGOBJECT_INTROSPECTION=True option to CMake. You'll + need to have the GObject Introspection development package v0.6.7 or higher + installed beforehand. + +You can also force CMake to ignore any of the optional dependencies +by passing the option -DCMAKE_DISABLE_FIND_PACKAGE_<PACKAGE>=True. +For instance: +# tell cmake to ignore ICU + % cmake -DCMAKE_DISABLE_FIND_PACKAGE_ICU=True + +== Language Bindings == +This C library can be built with bindings for these other languages: +* C++. If a C++ compiler is found the buildsystem will create and install the C++ bindings API. + Turn this off by passing -DWITH_CXX_BINDINGS=False option to CMake. + Don't mix ABI from C and C++ compilers. + +* There are Java, Perl, PHP and Python bindings but they are old and haven't + been tested in a very long time. Volunteers wanted. + +== Tweaking the Library Behavior == +Use these CMake options to adjust the library behavior as follows: + * ICAL_ERRORS_ARE_FATAL=[true|false] + Set to make icalerror_* calls abort instead of internally signaling an error. + Default=false + + * ICAL_ALLOW_EMPTY_PROPERTIES=[true|false] + Set to prevent empty properties from being replaced with X-LIC-ERROR properties. + Default=false + + * USE_BUILTIN_TZDATA=[true|false] + Set to build using our own (instead of the system's) timezone data. + Default=false (use the system timezone data on non-Windows systems) + ALWAYS true on Windows systems + +== Tweaking the Installation Directories == +By default, the installation layout is according to the GNU standard installation directories. +https://www.gnu.org/prep/standards/html_node/Directory-Variables.html + +You can override various installation folders by passing the following variables to CMake: + CMAKE_INSTALL_LIBDIR = The fullpath where you want the put the installed libraries + CMAKE_INSTALL_INCLUDEDIR = The fullpath where you want to put the installed include files + CMAKE_INSTALL_DATAROOTDIR = The fullpath where to want to put the shared files + +for example: cmake -DCMAKE_INSTALL_PREFIX=/opt -DCMAKE_INSTALL_LIBDIR=/opt/lib32 .. + +== Build the documentation == +Run 'make docs' to build the API documentation and reference. +Disable the docs make target by running CMake with -DICAL_BUILD_DOCS=False option. +Disable the libical-glib developer documentation by running CMake with -DENABLE_GTK_DOC=False. |