building.rst 8.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246
  1. .. _building:
  2. Building open62541
  3. ==================
  4. Building the Examples
  5. ---------------------
  6. Using the GCC compiler, the following calls build the examples on Linux.
  7. .. code-block:: bash
  8. cp /path-to/open62541.* . # copy single-file distribution to the local directory
  9. cp /path-to/examples/server_variable.c . # copy the example server
  10. gcc -std=c99 -DUA_ARCHITECTURE_POSIX open62541.c server_variable.c -o server
  11. Building the Library
  12. --------------------
  13. Building with CMake on Ubuntu or Debian
  14. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  15. .. code-block:: bash
  16. sudo apt-get install git build-essential gcc pkg-config cmake python python-six
  17. # enable additional features
  18. sudo apt-get install cmake-curses-gui # for the ccmake graphical interface
  19. sudo apt-get install libmbedtls-dev # for encryption support
  20. sudo apt-get install check # for unit tests
  21. sudo apt-get install python-sphinx graphviz # for documentation generation
  22. sudo apt-get install python-sphinx-rtd-theme # documentation style
  23. cd open62541
  24. mkdir build
  25. cd build
  26. cmake ..
  27. make
  28. # select additional features
  29. ccmake ..
  30. make
  31. # build documentation
  32. make doc # html documentation
  33. make doc_pdf # pdf documentation (requires LaTeX)
  34. Building with CMake on Windows
  35. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  36. Here we explain the build process for Visual Studio (2013 or newer). To build
  37. with MinGW, just replace the compiler selection in the call to CMake.
  38. - Download and install
  39. - Python 2.7.x (Python 3.x works as well): https://python.org/downloads
  40. - Install python-six with the pip package manager (``pip install six``)
  41. - CMake: http://www.cmake.org/cmake/resources/software.html
  42. - Microsoft Visual Studio: https://www.visualstudio.com/products/visual-studio-community-vs
  43. - Download the open62541 sources (using git or as a zipfile from github)
  44. - Open a command shell (cmd) and run
  45. .. code-block:: bat
  46. cd <path-to>\open62541
  47. mkdir build
  48. cd build
  49. <path-to>\cmake.exe .. -G "Visual Studio 14 2015"
  50. :: You can use use cmake-gui for a graphical user-interface to select features
  51. - Then open :file:`build\open62541.sln` in Visual Studio 2015 and build as usual
  52. Building on OS X
  53. ^^^^^^^^^^^^^^^^
  54. - Download and install
  55. - Xcode: https://itunes.apple.com/us/app/xcode/id497799835?ls=1&mt=12
  56. - Homebrew: http://brew.sh/
  57. - Pip (a package manager for python, may be preinstalled): ``sudo easy_install pip``
  58. - Run the following in a shell
  59. .. code-block:: bash
  60. brew install cmake
  61. pip install six # python 2/3 compatibility workarounds
  62. pip install sphinx # for documentation generation
  63. pip install sphinx_rtd_theme # documentation style
  64. brew install graphviz # for graphics in the documentation
  65. brew install check # for unit tests
  66. brew install userspace-rcu # for multi-threading support
  67. Follow Ubuntu instructions without the ``apt-get`` commands as these are taken care of by the above packages.
  68. Building on OpenBSD
  69. ^^^^^^^^^^^^^^^^^^^
  70. The procedure below works on OpenBSD 5.8 with gcc version 4.8.4, cmake version 3.2.3 and Python version 2.7.10.
  71. - Install a recent gcc, python and cmake:
  72. .. code-block:: bash
  73. pkg_add gcc python cmake
  74. - Tell the system to actually use the recent gcc (it gets installed as egcc on OpenBSD):
  75. .. code-block:: bash
  76. export CC=egcc CXX=eg++
  77. - Now procede as described for Ubuntu/Debian:
  78. .. code-block:: bash
  79. cd open62541
  80. mkdir build
  81. cd build
  82. cmake ..
  83. make
  84. Build Options
  85. -------------
  86. The open62541 project uses CMake to manage the build options, for code
  87. generation and to generate build projects for the different systems and IDEs.
  88. The tools *ccmake* or *cmake-gui* can be used to graphically set the build
  89. options.
  90. Most options can be changed manually in :file:`ua_config.h` (:file:`open62541.h`
  91. for the single-file release) after the code generation. But usually there is no
  92. need to adjust them.
  93. Build Type and Logging
  94. ^^^^^^^^^^^^^^^^^^^^^^
  95. **CMAKE_BUILD_TYPE**
  96. - ``RelWithDebInfo`` -O2 optimization with debug symbols
  97. - ``Release`` -O2 optimization without debug symbols
  98. - ``Debug`` -O0 optimization with debug symbols
  99. - ``MinSizeRel`` -Os optimization without debug symbols
  100. **UA_LOGLEVEL**
  101. The SDK logs events of the level defined in ``UA_LOGLEVEL`` and above only.
  102. The logging event levels are as follows:
  103. - 600: Fatal
  104. - 500: Error
  105. - 400: Warning
  106. - 300: Info
  107. - 200: Debug
  108. - 100: Trace
  109. UA_BUILD_* group
  110. ^^^^^^^^^^^^^^^^
  111. By default only the shared object libopen62541.so or the library open62541.dll
  112. and open62541.dll.a resp. open62541.lib are build. Additional artifacts can be
  113. specified by the following options:
  114. **UA_BUILD_EXAMPLES**
  115. Compile example servers and clients from :file:`examples/{xyz}.c`. A static and a dynamic binary is linked, respectively.
  116. **UA_BUILD_UNIT_TESTS**
  117. Compile unit tests with Check framework. The tests can be executed with ``make test``
  118. **UA_BUILD_EXAMPLES_NODESET_COMPILER**
  119. Generate an OPC UA information model from a nodeset XML (experimental)
  120. **UA_BUILD_SELFSIGNED_CERTIFICATE**
  121. Generate a self-signed certificate for the server (openSSL required)
  122. UA_ENABLE_* group
  123. ^^^^^^^^^^^^^^^^^
  124. This group contains build options related to the supported OPC UA features.
  125. **UA_ENABLE_SUBSCRIPTIONS**
  126. Enable subscriptions
  127. **UA_ENABLE_SUBSCRIPTIONS_EVENTS**
  128. Enable the use of events for subscriptions
  129. **UA_ENABLE_METHODCALLS**
  130. Enable the Method service set
  131. **UA_ENABLE_NODEMANAGEMENT**
  132. Enable dynamic addition and removal of nodes at runtime
  133. **UA_ENABLE_AMALGAMATION**
  134. Compile a single-file release into the files :file:`open62541.c` and :file:`open62541.h`
  135. **UA_ENABLE_MULTITHREADING**
  136. Enable multi-threading support
  137. **UA_ENABLE_IMMUTABLE_NODES**
  138. Nodes in the information model are not edited but copied and replaced. The replacement is done with atomic operations so that the information model is always consistent and can be accessed from an interrupt or parallel thread (depends on the node storage plugin implementation). This feature is a prerequisite for ``UA_ENABLE_MULTITHREADING``.
  139. **UA_ENABLE_COVERAGE**
  140. Measure the coverage of unit tests
  141. Some options are marked as advanced. The advanced options need to be toggled to
  142. be visible in the cmake GUIs.
  143. **UA_ENABLE_TYPENAMES**
  144. Add the type and member names to the UA_DataType structure. Enabled by default.
  145. **UA_ENABLE_STATUSCODE_DESCRIPTIONS**
  146. Compile the human-readable name of the StatusCodes into the binary. Enabled by default.
  147. **UA_ENABLE_GENERATE_NAMESPACE0**
  148. Generate and load UA XML Namespace 0 definition
  149. ``UA_GENERATE_NAMESPACE0_FILE`` is used to specify the file for NS0 generation from namespace0 folder. Default value is ``Opc.Ua.NodeSet2.xml``
  150. **UA_ENABLE_NONSTANDARD_UDP**
  151. Enable udp extension
  152. UA_DEBUG_* group
  153. ^^^^^^^^^^^^^^^^
  154. This group contains build options mainly useful for development of the library itself.
  155. **UA_DEBUG**
  156. Enable assertions and additional definitions not intended for production builds
  157. **UA_DEBUG_DUMP_PKGS**
  158. Dump every package received by the server as hexdump format
  159. Building a shared library
  160. ^^^^^^^^^^^^^^^^^^^^^^^^^
  161. open62541 is small enough that most users will want to statically link the
  162. library into their programs. If a shared library (.dll, .so) is required, this
  163. can be enabled in CMake with the ``BUILD_SHARED_LIBS`` option. Note that this
  164. option modifies the :file:`ua_config.h` file that is also included in
  165. :file:`open62541.h` for the single-file distribution.
  166. Minimizing the binary size
  167. ^^^^^^^^^^^^^^^^^^^^^^^^^^
  168. The size of the generated binary can be reduced considerably by adjusting the
  169. build configuration. First, in CMake, the build type can be set to
  170. ``CMAKE_BUILD_TYPE=MinSizeRel``. This sets the compiler flags to minimize the
  171. binary size. The build type also strips out debug information. Second, the
  172. binary size can be reduced by removing features via the build-flags described
  173. above.
  174. Especially, logging takes up a lot of space in the binary and might not be
  175. needed in embedded scenarios. Setting ``UA_LOGLEVEL`` to a value above 600
  176. (=FATAL) disables all logging. In addition, the feature-flags
  177. ``UA_ENABLE_TYPENAMES`` and ``UA_ENABLE_STATUSCODE_DESCRIPTIONS`` add static
  178. information to the binary that is only used for human-readable logging and
  179. debugging.