building.rst 9.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297
  1. .. _building:
  2. Building open62541
  3. ==================
  4. open62541 uses CMake to build the library and binaries. The library version is automatically
  5. detected using ``git describe``. This command returns a valid version string based on the current tag.
  6. If you did not directly clone the sources, but use the tar or zip package from a release, you need
  7. to manually specify the version. In that case use e.g. ``cmake -DOPEN62541_VERSION=v1.0.3``.
  8. Building the Examples
  9. ---------------------
  10. Using the GCC compiler, the following calls build the examples on Linux.
  11. .. code-block:: bash
  12. cp /path-to/open62541.* . # copy single-file distribution to the local directory
  13. cp /path-to/examples/tutorial_server_variable.c . # copy the example server
  14. gcc -std=c99 -DUA_ARCHITECTURE_POSIX open62541.c tutorial_server_variable.c -o server
  15. Building the Library
  16. --------------------
  17. Building with CMake on Ubuntu or Debian
  18. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  19. .. code-block:: bash
  20. sudo apt-get install git build-essential gcc pkg-config cmake python
  21. # enable additional features
  22. sudo apt-get install cmake-curses-gui # for the ccmake graphical interface
  23. sudo apt-get install libmbedtls-dev # for encryption support
  24. sudo apt-get install check libsubunit-dev # for unit tests
  25. sudo apt-get install python-sphinx graphviz # for documentation generation
  26. sudo apt-get install python-sphinx-rtd-theme # documentation style
  27. cd open62541
  28. mkdir build
  29. cd build
  30. cmake ..
  31. make
  32. # select additional features
  33. ccmake ..
  34. make
  35. # build documentation
  36. make doc # html documentation
  37. make doc_pdf # pdf documentation (requires LaTeX)
  38. Building with CMake on Windows
  39. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  40. Here we explain the build process for Visual Studio (2013 or newer). To build
  41. with MinGW, just replace the compiler selection in the call to CMake.
  42. - Download and install
  43. - Python 2.7.x (Python 3.x works as well): https://python.org/downloads
  44. - CMake: http://www.cmake.org/cmake/resources/software.html
  45. - Microsoft Visual Studio: https://www.visualstudio.com/products/visual-studio-community-vs
  46. - Download the open62541 sources (using git or as a zipfile from github)
  47. - Open a command shell (cmd) and run
  48. .. code-block:: bat
  49. cd <path-to>\open62541
  50. mkdir build
  51. cd build
  52. <path-to>\cmake.exe .. -G "Visual Studio 14 2015"
  53. :: You can use use cmake-gui for a graphical user-interface to select features
  54. - Then open :file:`build\open62541.sln` in Visual Studio 2015 and build as usual
  55. Building on OS X
  56. ^^^^^^^^^^^^^^^^
  57. - Download and install
  58. - Xcode: https://itunes.apple.com/us/app/xcode/id497799835?ls=1&mt=12
  59. - Homebrew: http://brew.sh/
  60. - Pip (a package manager for python, may be preinstalled): ``sudo easy_install pip``
  61. - Run the following in a shell
  62. .. code-block:: bash
  63. brew install cmake
  64. pip install sphinx # for documentation generation
  65. pip install sphinx_rtd_theme # documentation style
  66. brew install graphviz # for graphics in the documentation
  67. brew install check # for unit tests
  68. Follow Ubuntu instructions without the ``apt-get`` commands as these are taken care of by the above packages.
  69. Building on OpenBSD
  70. ^^^^^^^^^^^^^^^^^^^
  71. 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.
  72. - Install a recent gcc, python and cmake:
  73. .. code-block:: bash
  74. pkg_add gcc python cmake
  75. - Tell the system to actually use the recent gcc (it gets installed as egcc on OpenBSD):
  76. .. code-block:: bash
  77. export CC=egcc CXX=eg++
  78. - Now procede as described for Ubuntu/Debian:
  79. .. code-block:: bash
  80. cd open62541
  81. mkdir build
  82. cd build
  83. cmake ..
  84. make
  85. .. _build_options:
  86. Build Options
  87. -------------
  88. The open62541 project uses CMake to manage the build options, for code
  89. generation and to generate build projects for the different systems and IDEs.
  90. The tools *ccmake* or *cmake-gui* can be used to graphically set the build
  91. options.
  92. Most options can be changed manually in :file:`ua_config.h` (:file:`open62541.h`
  93. for the single-file release) after the code generation. But usually there is no
  94. need to adjust them.
  95. Main Build Options
  96. ^^^^^^^^^^^^^^^^^^
  97. **CMAKE_BUILD_TYPE**
  98. - ``RelWithDebInfo`` -O2 optimization with debug symbols
  99. - ``Release`` -O2 optimization without debug symbols
  100. - ``Debug`` -O0 optimization with debug symbols
  101. - ``MinSizeRel`` -Os optimization without debug symbols
  102. **UA_LOGLEVEL**
  103. The SDK logs events of the level defined in ``UA_LOGLEVEL`` and above only.
  104. The logging event levels are as follows:
  105. - 600: Fatal
  106. - 500: Error
  107. - 400: Warning
  108. - 300: Info
  109. - 200: Debug
  110. - 100: Trace
  111. Select build artefacts
  112. ^^^^^^^^^^^^^^^^^^^^^^
  113. By default only the main library shared object libopen62541.so (open62541.dll)
  114. or static linking archive open62541.a (open62541.lib) is built. Additional
  115. artifacts can be specified by the following options:
  116. **UA_BUILD_EXAMPLES**
  117. Compile example servers and clients from :file:`examples/*.c`.
  118. **UA_BUILD_UNIT_TESTS**
  119. Compile unit tests. The tests can be executed with ``make test``
  120. **UA_BUILD_SELFSIGNED_CERTIFICATE**
  121. Generate a self-signed certificate for the server (openSSL required)
  122. Detailed SDK Features
  123. ^^^^^^^^^^^^^^^^^^^^^
  124. **UA_ENABLE_SUBSCRIPTIONS**
  125. Enable subscriptions
  126. **UA_ENABLE_SUBSCRIPTIONS_EVENTS (EXPERIMENTAL)**
  127. Enable the use of events for subscriptions. This is a new feature and currently marked as EXPERIMENTAL.
  128. **UA_ENABLE_METHODCALLS**
  129. Enable the Method service set
  130. **UA_ENABLE_NODEMANAGEMENT**
  131. Enable dynamic addition and removal of nodes at runtime
  132. **UA_ENABLE_AMALGAMATION**
  133. Compile a single-file release into the files :file:`open62541.c` and :file:`open62541.h`. Not receommended for installation.
  134. **UA_ENABLE_MULTITHREADING (EXPERIMENTAL)**
  135. Enable multi-threading support. Work is distributed to a number of worker threads.
  136. This is a new feature and currently marked as EXPERIMENTAL.
  137. **UA_ENABLE_IMMUTABLE_NODES**
  138. Nodes in the information model are not edited but copied and replaced. The
  139. replacement is done with atomic operations so that the information model is
  140. always consistent and can be accessed from an interrupt or parallel thread
  141. (depends on the node storage plugin implementation). This feature is a
  142. prerequisite for ``UA_ENABLE_MULTITHREADING``.
  143. **UA_ENABLE_COVERAGE**
  144. Measure the coverage of unit tests
  145. **UA_ENABLE_DISCOVERY**
  146. Enable Discovery Service (LDS)
  147. **UA_ENABLE_DISCOVERY_MULTICAST**
  148. Enable Discovery Service with multicast support (LDS-ME)
  149. **UA_ENABLE_DISCOVERY_SEMAPHORE**
  150. Enable Discovery Semaphore support
  151. **UA_NAMESPACE_ZERO**
  152. Namespace zero contains the standard-defined nodes. The full namespace zero
  153. may not be required for all applications. The selectable options are as follows:
  154. - ``MINIMAL``: A barebones namespace zero that is compatible with most
  155. clients. But this namespace 0 is so small that it does not pass the CTT
  156. (Conformance Testing Tools of the OPC Foundation).
  157. - ``REDUCED``: Small namespace zero that passes the CTT.
  158. - ``FULL``: Full namespace zero generated from the official XML definitions.
  159. The advanced build option ``UA_FILE_NS0`` can be used to override the XML
  160. file used for namespace zero generation.
  161. Some options are marked as advanced. The advanced options need to be toggled to
  162. be visible in the cmake GUIs.
  163. **UA_ENABLE_TYPENAMES**
  164. Add the type and member names to the UA_DataType structure. Enabled by default.
  165. **UA_ENABLE_STATUSCODE_DESCRIPTIONS**
  166. Compile the human-readable name of the StatusCodes into the binary. Enabled by default.
  167. **UA_ENABLE_FULL_NS0**
  168. Use the full NS0 instead of a minimal Namespace 0 nodeset
  169. ``UA_FILE_NS0`` is used to specify the file for NS0 generation from namespace0 folder. Default value is ``Opc.Ua.NodeSet2.xml``
  170. Debug Build Options
  171. ^^^^^^^^^^^^^^^^^^^
  172. This group contains build options mainly useful for development of the library itself.
  173. **UA_DEBUG**
  174. Enable assertions and additional definitions not intended for production builds
  175. **UA_DEBUG_DUMP_PKGS**
  176. Dump every package received by the server as hexdump format
  177. Building a shared library
  178. ^^^^^^^^^^^^^^^^^^^^^^^^^
  179. open62541 is small enough that most users will want to statically link the
  180. library into their programs. If a shared library (.dll, .so) is required, this
  181. can be enabled in CMake with the ``BUILD_SHARED_LIBS`` option. Note that this
  182. option modifies the :file:`ua_config.h` file that is also included in
  183. :file:`open62541.h` for the single-file distribution.
  184. Minimizing the binary size
  185. ^^^^^^^^^^^^^^^^^^^^^^^^^^
  186. The size of the generated binary can be reduced considerably by adjusting the
  187. build configuration. With open2541, it is possible to configure minimal servers
  188. that require less than 100kB of RAM and ROM.
  189. The following options influence the ROM requirements:
  190. First, in CMake, the build type can be set to ``CMAKE_BUILD_TYPE=MinSizeRel``.
  191. This sets the compiler flags to minimize the binary size. The build type also
  192. strips out debug information. Second, the binary size can be reduced by removing
  193. features via the build-flags described above.
  194. Second, setting ``UA_NAMESPACE_ZERO`` to ``MINIMAL`` reduces the size of the
  195. builtin information model. Setting this option can reduce the binary size by
  196. half in some cases.
  197. Third, some features might not be needed and can be disabled to reduce the
  198. binary footprint. Examples for this are Subscriptions or encrypted
  199. communication.
  200. Last, logging messages take up a lot of space in the binary and might not be
  201. needed in embedded scenarios. Setting ``UA_LOGLEVEL`` to a value above 600
  202. (``FATAL``) disables all logging. In addition, the feature-flags
  203. ``UA_ENABLE_TYPENAMES`` and ``UA_ENABLE_STATUSCODE_DESCRIPTIONS`` add static
  204. information to the binary that is only used for human-readable logging and
  205. debugging.
  206. The RAM requirements of a server are mostly due to the following settings:
  207. - The size of the information model
  208. - The number of connected clients
  209. - The configured maximum message size that is preallocated
  210. .. include:: building_arch.rst