open62541/doc/building.rst

.. _building:

Building the Library
====================

Building the Single-File Release
--------------------------------

Using the GCC compiler, the following calls build the library on Linux.

.. code-block:: bash

   gcc -std=c99 -fPIC -c open62541.c
   gcc -shared open62541.o -o libopen62541.so

Building with CMake on Ubuntu or Debian
---------------------------------------

.. code-block:: bash

   sudo apt-get install git build-essential gcc pkg-config cmake python

   # enable additional features
   sudo apt-get install liburcu-dev # for multithreading
   sudo apt-get install check # for unit tests
   sudo apt-get install sphinx # for documentation generation

   cd open62541
   mkdir build
   cd build
   cmake ..
   make

   # select additional features
   ccmake ..
   make

Building with CMake on Windows
------------------------------

Here we explain the build process for Visual Studio (2013 or newer). To build
with MinGW, just replace the compiler selection in the call to CMake.

- Download and install

  - Python 2.7.x (Python 3.x should work, too): https://python.org/downloads
  - CMake: http://www.cmake.org/cmake/resources/software.html
  - Microsoft Visual Studio 2015 Community Edition: https://www.visualstudio.com/products/visual-studio-community-vs

- Download the open62541 sources (using git or as a zipfile from github)
- Open a command shell (cmd) and run

.. code-block:: bat

   cd <path-to>\open62541
   mkdir build
   cd build
   <path-to>\cmake.exe .. -G "Visual Studio 14 2015"
   :: You can use use cmake-gui for a graphical user-interface to select single features

- Then open :file:`build\open62541.sln` in Visual Studio 2015 and build as usual

Building on OS X
----------------

- Download and install

  - Xcode: https://itunes.apple.com/us/app/xcode/id497799835?ls=1&mt=12
  - Homebrew: http://brew.sh/
  - Pip (a package manager for python, may be preinstalled): ``sudo easy_install pip``

- Run the following in a shell

.. code-block:: bash

   brew install cmake
   brew install libxml2
   brew install check # for unit tests
   brew install userspace-rcu # for multi-threading support
   brew install graphviz doxygen # for documentation generation
   pip install sphinx # for documentation generation

Follow Ubuntu instructions without the ``apt-get`` commands as these are taken care of by the above packages.

Build Options
-------------


Build Type and Logging
~~~~~~~~~~~~~~~~

**CMAKE_BUILD_TYPE**
  - ``RelWithDebInfo`` -O2 optimization with debug symbols
  - ``Release`` -O2 optimization without debug symbols
  - ``Debug`` -O0 optimization with debug symbols
  - ``MinSizeRel`` -Os optimization without debug symbols

**UA_LOGLEVEL**
   The level of logging events that are reported

     - 600: Fatal and all below
     - 500: Error and all below
     - 400: Error and all below
     - 300: Info and all below
     - 200: Debug and all below
     - 100: Trace and all below

Further options that are not inherited from the CMake configuration are defined
in :file:`ua_config.h`. Usually there is no need to adjust them.

UA_BUILD_* group
~~~~~~~~~~~~~~~~

By default only the shared object libopen62541.so or the library open62541.dll
and open62541.dll.a resp. open62541.lib are build. Additional artifacts can be
specified by the following options:

**UA_BUILD_DOCUMENTATION**
  Generate Make targets for documentation

   * HTML documentation: ``make doc``
   * Latex Files: ``latex``
   * PDF documentation: ``make pdf``

**UA_BUILD_EXAMPLES**
   Compile example servers and clients from :file:`examples/{xyz}.c`. A static and a dynamic binary is linked, respectively.

**UA_BUILD_UNIT_TESTS**
   Compile unit tests with Check framework. The tests can be executed with ``make test``

**UA_BUILD_EXAMPLES_NODESET_COMPILER**
   Generate an OPC UA information model from a nodeset XML (experimental)

**UA_BUILD_SELFIGNED_CERTIFICATE**
   Generate a self-signed certificate for the server (openSSL required)

UA_ENABLE_* group
~~~~~~~~~~~~~~~~~

This group contains build options related to the supported OPC UA features.

**UA_ENABLE_SUBSCRIPTIONS**
   Enable subscriptions
**UA_ENABLE_METHODCALLS**
   Enable the Method service set
**UA_ENABLE_NODEMANAGEMENT**
   Enable dynamic addition and removal of nodes at runtime
**UA_ENABLE_AMALGAMATION**
   Compile a single-file release files :file:`open62541.c` and :file:`open62541.h`
**UA_ENABLE_MULTITHREADING**
   Enable multi-threading support
**UA_ENABLE_COVERAGE**
   Measure the coverage of unit tests



Some options are marked as advanced. The advanced options need to be toggled to
be visible in the cmake GUIs.

**UA_ENABLE_TYPENAMES**
   Add the type and member names to the UA_DataType structure
**UA_ENABLE_GENERATE_NAMESPACE0**
   Generate and load UA XML Namespace 0 definition
   ``UA_GENERATE_NAMESPACE0_FILE`` is used to specify the file for NS0 generation from namespace0 folder. Default value is ``Opc.Ua.NodeSet2.xml``
**UA_ENABLE_EMBEDDED_LIBC**
   Use a custom implementation of some libc functions that might be missing on embedded targets (e.g. string handling).
**UA_ENABLE_EXTERNAL_NAMESPACES**
  Enable namespace handling by an external component (experimental)
**UA_ENABLE_NONSTANDARD_STATELESS**
   Enable stateless extension
**UA_ENABLE_NONSTANDARD_UDP**
   Enable udp extension