building.rst 9.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291
  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/tutorial_server_variable.c . # copy the example server
  10. gcc -std=c99 -DUA_ARCHITECTURE_POSIX open62541.c tutorial_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. Follow Ubuntu instructions without the ``apt-get`` commands as these are taken care of by the above packages.
  67. Building on OpenBSD
  68. ^^^^^^^^^^^^^^^^^^^
  69. 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.
  70. - Install a recent gcc, python and cmake:
  71. .. code-block:: bash
  72. pkg_add gcc python cmake
  73. - Tell the system to actually use the recent gcc (it gets installed as egcc on OpenBSD):
  74. .. code-block:: bash
  75. export CC=egcc CXX=eg++
  76. - Now procede as described for Ubuntu/Debian:
  77. .. code-block:: bash
  78. cd open62541
  79. mkdir build
  80. cd build
  81. cmake ..
  82. make
  83. Build Options
  84. -------------
  85. The open62541 project uses CMake to manage the build options, for code
  86. generation and to generate build projects for the different systems and IDEs.
  87. The tools *ccmake* or *cmake-gui* can be used to graphically set the build
  88. options.
  89. Most options can be changed manually in :file:`ua_config.h` (:file:`open62541.h`
  90. for the single-file release) after the code generation. But usually there is no
  91. need to adjust them.
  92. Main Build Options
  93. ^^^^^^^^^^^^^^^^^^
  94. **CMAKE_BUILD_TYPE**
  95. - ``RelWithDebInfo`` -O2 optimization with debug symbols
  96. - ``Release`` -O2 optimization without debug symbols
  97. - ``Debug`` -O0 optimization with debug symbols
  98. - ``MinSizeRel`` -Os optimization without debug symbols
  99. **UA_LOGLEVEL**
  100. The SDK logs events of the level defined in ``UA_LOGLEVEL`` and above only.
  101. The logging event levels are as follows:
  102. - 600: Fatal
  103. - 500: Error
  104. - 400: Warning
  105. - 300: Info
  106. - 200: Debug
  107. - 100: Trace
  108. Select build artefacts
  109. ^^^^^^^^^^^^^^^^^^^^^^
  110. By default only the main library shared object libopen62541.so (open62541.dll)
  111. or static linking archive open62541.a (open62541.lib) is built. Additional
  112. artifacts can be specified by the following options:
  113. **UA_BUILD_EXAMPLES**
  114. Compile example servers and clients from :file:`examples/*.c`.
  115. **UA_BUILD_UNIT_TESTS**
  116. Compile unit tests. The tests can be executed with ``make test``
  117. **UA_BUILD_SELFSIGNED_CERTIFICATE**
  118. Generate a self-signed certificate for the server (openSSL required)
  119. Detailed SDK Features
  120. ^^^^^^^^^^^^^^^^^^^^^
  121. **UA_ENABLE_SUBSCRIPTIONS**
  122. Enable subscriptions
  123. **UA_ENABLE_SUBSCRIPTIONS_EVENTS (EXPERIMENTAL)**
  124. Enable the use of events for subscriptions. This is a new feature and currently marked as EXPERIMENTAL.
  125. **UA_ENABLE_METHODCALLS**
  126. Enable the Method service set
  127. **UA_ENABLE_NODEMANAGEMENT**
  128. Enable dynamic addition and removal of nodes at runtime
  129. **UA_ENABLE_AMALGAMATION**
  130. Compile a single-file release into the files :file:`open62541.c` and :file:`open62541.h`
  131. **UA_ENABLE_MULTITHREADING (EXPERIMENTAL)**
  132. Enable multi-threading support. Work is distributed to a number of worker threads.
  133. This is a new feature and currently marked as EXPERIMENTAL.
  134. **UA_ENABLE_IMMUTABLE_NODES**
  135. Nodes in the information model are not edited but copied and replaced. The
  136. replacement is done with atomic operations so that the information model is
  137. always consistent and can be accessed from an interrupt or parallel thread
  138. (depends on the node storage plugin implementation). This feature is a
  139. prerequisite for ``UA_ENABLE_MULTITHREADING``.
  140. **UA_ENABLE_COVERAGE**
  141. Measure the coverage of unit tests
  142. **UA_ENABLE_DISCOVERY**
  143. Enable Discovery Service (LDS)
  144. **UA_ENABLE_DISCOVERY_MULTICAST**
  145. Enable Discovery Service with multicast support (LDS-ME)
  146. **UA_ENABLE_DISCOVERY_SEMAPHORE**
  147. Enable Discovery Semaphore support
  148. **UA_NAMESPACE_ZERO**
  149. Namespace zero contains the standard-defined nodes. The full namespace zero
  150. may not be required for all applications. The selectable options are as follows:
  151. - ``MINIMAL``: A barebones namespace zero that is compatible with most
  152. clients. But this namespace 0 is so small that it does not pass the CTT
  153. (Conformance Testing Tools of the OPC Foundation).
  154. - ``REDUCED``: Small namespace zero that passes the CTT.
  155. - ``FULL``: Full namespace zero generated from the official XML definitions.
  156. The advanced build option ``UA_FILE_NS0`` can be used to override the XML
  157. file used for namespace zero generation.
  158. Some options are marked as advanced. The advanced options need to be toggled to
  159. be visible in the cmake GUIs.
  160. **UA_ENABLE_TYPENAMES**
  161. Add the type and member names to the UA_DataType structure. Enabled by default.
  162. **UA_ENABLE_STATUSCODE_DESCRIPTIONS**
  163. Compile the human-readable name of the StatusCodes into the binary. Enabled by default.
  164. **UA_ENABLE_FULL_NS0**
  165. Use the full NS0 instead of a minimal Namespace 0 nodeset
  166. ``UA_FILE_NS0`` is used to specify the file for NS0 generation from namespace0 folder. Default value is ``Opc.Ua.NodeSet2.xml``
  167. **UA_ENABLE_NONSTANDARD_UDP**
  168. Enable udp extension
  169. Debug Build Options
  170. ^^^^^^^^^^^^^^^^^^^
  171. This group contains build options mainly useful for development of the library itself.
  172. **UA_DEBUG**
  173. Enable assertions and additional definitions not intended for production builds
  174. **UA_DEBUG_DUMP_PKGS**
  175. Dump every package received by the server as hexdump format
  176. Building a shared library
  177. ^^^^^^^^^^^^^^^^^^^^^^^^^
  178. open62541 is small enough that most users will want to statically link the
  179. library into their programs. If a shared library (.dll, .so) is required, this
  180. can be enabled in CMake with the ``BUILD_SHARED_LIBS`` option. Note that this
  181. option modifies the :file:`ua_config.h` file that is also included in
  182. :file:`open62541.h` for the single-file distribution.
  183. Minimizing the binary size
  184. ^^^^^^^^^^^^^^^^^^^^^^^^^^
  185. The size of the generated binary can be reduced considerably by adjusting the
  186. build configuration. With open2541, it is possible to configure minimal servers
  187. that require less than 100kB of RAM and ROM.
  188. The following options influence the ROM requirements:
  189. First, in CMake, the build type can be set to ``CMAKE_BUILD_TYPE=MinSizeRel``.
  190. This sets the compiler flags to minimize the binary size. The build type also
  191. strips out debug information. Second, the binary size can be reduced by removing
  192. features via the build-flags described above.
  193. Second, setting ``UA_NAMESPACE_ZERO`` to ``MINIMAL`` reduces the size of the
  194. builtin information model. Setting this option can reduce the binary size by
  195. half in some cases.
  196. Third, some features might not be needed and can be disabled to reduce the
  197. binary footprint. Examples for this are Subscriptions or encrypted
  198. communication.
  199. Last, logging messages take up a lot of space in the binary and might not be
  200. needed in embedded scenarios. Setting ``UA_LOGLEVEL`` to a value above 600
  201. (``FATAL``) disables all logging. In addition, the feature-flags
  202. ``UA_ENABLE_TYPENAMES`` and ``UA_ENABLE_STATUSCODE_DESCRIPTIONS`` add static
  203. information to the binary that is only used for human-readable logging and
  204. debugging.
  205. The RAM requirements of a server are mostly due to the following settings:
  206. - The size of the information model
  207. - The number of connected clients
  208. - The configured maximum message size that is preallocated