deprecate UA_StatusCode_explanation; document build options

doc/building.rst

@@ -120,6 +120,15 @@ The procedure below works on OpenBSD 5.8 with gcc version 4.8.4, cmake version 3
 Build Options
 -------------
 
+The open62541 project uses CMake to manage the build options, for code
+generation and to generate build projects for the different systems and IDEs.
+The tools *ccmake* or *cmake-gui* can be used to graphically set the build
+options.
+
+Most options can be changed manually in :file:`ua_config.h` (:file:`open62541.h`
+for the single-file release) after the code generation. But usually there is no
+need to adjust them.
+
 Build Type and Logging
 ^^^^^^^^^^^^^^^^^^^^^^
 
@@ -130,17 +139,15 @@ Build Type and Logging
   - ``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
+   The SDK logs events of the level defined in ``UA_LOGLEVEL`` and above only.
+   The logging event levels are as follows:
 
-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.
+     - 600: Fatal
+     - 500: Error
+     - 400: Warning
+     - 300: Info
+     - 200: Debug
+     - 100: Trace
 
 UA_BUILD_* group
 ^^^^^^^^^^^^^^^^
@@ -173,7 +180,7 @@ This group contains build options related to the supported OPC UA features.
 **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`
+   Compile a single-file release into the files :file:`open62541.c` and :file:`open62541.h`
 **UA_ENABLE_MULTITHREADING**
    Enable multi-threading support
 **UA_ENABLE_COVERAGE**
@@ -183,7 +190,9 @@ 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
+   Add the type and member names to the UA_DataType structure. Enabled by default.
+**UA_ENABLE_STATUSCODE_DESCRIPTIONS**
+   Compile the human-readable name of the StatusCodes into the binary. Enabled by default.
 **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``
@@ -197,5 +206,26 @@ be visible in the cmake GUIs.
 Building a shared library
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
-open62541 is small enough that most users will want to statically link the library into their programs. If a shared library (.dll, .so) is required, this can be enabled in CMake with the `BUILD_SHARED_LIBS` option.
-Note that this option modifies the :file:`ua_config.h` file that is also included in :file:`open62541.h` for the single-file distribution.
+open62541 is small enough that most users will want to statically link the
+library into their programs. If a shared library (.dll, .so) is required, this
+can be enabled in CMake with the ``BUILD_SHARED_LIBS`` option. Note that this
+option modifies the :file:`ua_config.h` file that is also included in
+:file:`open62541.h` for the single-file distribution.
+
+
+Minimizing the binary size
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The size of the generated binary can be reduced considerably by adjusting the
+build configuration. First, in CMake, the build type can be set to
+``CMAKE_BUILD_TYPE=MinSizeRel``. This sets the compiler flags to minimize the
+binary size. The build type also strips out debug information. Second, the
+binary size can be reduced by removing features via the build-flags described
+above.
+
+Especially, logging takes up a lot of space in the binary and might not be
+needed in embedded scenarios. Setting ``UA_LOGLEVEL`` to a value above 600
+(=FATAL) disables all logging. In addition, the feature-flags
+``UA_ENABLE_TYPENAMES`` and ``UA_ENABLE_STATUSCODE_DESCRIPTIONS`` add static
+information to the binary that is only used for human-readable logging and
+debugging.

include/ua_types.h

@@ -127,26 +127,13 @@ typedef double UA_Double;
  * specific code. */
 typedef uint32_t UA_StatusCode;
 
-typedef struct {
-    UA_StatusCode code;      /* The numeric value of the StatusCode */
-    const char* name;        /* The symbolic name */
-    const char* explanation; /* Short message explaining the StatusCode */
-} UA_StatusCodeDescription;
-
-/* Returns the description of the StatusCode. Never returns NULL, but a generic
- * description for invalid StatusCodes instead. */
-UA_EXPORT const UA_StatusCodeDescription *
-UA_StatusCode_description(UA_StatusCode code);
-
-static UA_INLINE const char *
-UA_StatusCode_name(UA_StatusCode code) {
-    return UA_StatusCode_description(code)->name;
-}
-
-static UA_INLINE const char *
-UA_StatusCode_explanation(UA_StatusCode code) {
-    return UA_StatusCode_description(code)->explanation;
-}
+/* Returns the human-readable name of the StatusCode. If no matching StatusCode
+ * is found, a default string for "Unknown" is returned. This feature might be
+ * disabled to create a smaller binary with the
+ * UA_ENABLE_STATUSCODE_DESCRIPTIONS build-flag. Then the function returns an
+ * empty string for every StatusCode. */
+UA_EXPORT const char *
+UA_StatusCode_name(UA_StatusCode code);
 
 /**
  * String
@@ -895,6 +882,31 @@ UA_Guid UA_EXPORT UA_Guid_random(void);     /* no cryptographic entropy */
  * .. toctree::
  *
  *    types_generated */
+
+/**
+ * Deprecated Data Types API
+ * -------------------------
+ * The following definitions are deprecated and will be removed in future
+ * releases of open62541. */
+
+typedef struct {
+    UA_StatusCode code;      /* The numeric value of the StatusCode */
+    const char* name;        /* The symbolic name */
+    const char* explanation; /* Short message explaining the StatusCode */
+} UA_StatusCodeDescription;
+
+UA_EXPORT extern const UA_StatusCodeDescription statusCodeExplanation_default;
+
+UA_DEPRECATED static UA_INLINE const UA_StatusCodeDescription *
+UA_StatusCode_description(UA_StatusCode code) {
+    return &statusCodeExplanation_default;
+}
+
+UA_DEPRECATED static UA_INLINE const char *
+UA_StatusCode_explanation(UA_StatusCode code) {
+    return statusCodeExplanation_default.name;
+}
+
 #ifdef __cplusplus
 } // extern "C"
 #endif

tests/check_utils.c

@@ -139,28 +139,20 @@ START_TEST(StatusCode_msg) {
     return;
 #endif
         // first element in table
-    ck_assert_str_eq(UA_StatusCode_explanation(UA_STATUSCODE_GOOD), "Success / No error");
     ck_assert_str_eq(UA_StatusCode_name(UA_STATUSCODE_GOOD), "Good");
 
         // just some randomly picked status codes
-    ck_assert_str_eq(UA_StatusCode_explanation(UA_STATUSCODE_BADNOCOMMUNICATION),
-                     "Communication with the data source is defined");
     ck_assert_str_eq(UA_StatusCode_name(UA_STATUSCODE_BADNOCOMMUNICATION),
                      "BadNoCommunication");
 
-    ck_assert_str_eq(UA_StatusCode_explanation(UA_STATUSCODE_GOODNODATA),
-                     "No data exists for the requested time range or event filter.");
     ck_assert_str_eq(UA_StatusCode_name(UA_STATUSCODE_GOODNODATA), "GoodNoData");
 
         // last element in table
-    ck_assert_str_eq(UA_StatusCode_explanation(UA_STATUSCODE_BADMAXCONNECTIONSREACHED),
-                     "The operation could not be finished because all available connections are in use.");
     ck_assert_str_eq(UA_StatusCode_name(UA_STATUSCODE_BADMAXCONNECTIONSREACHED),
                      "BadMaxConnectionsReached");
 
         // an invalid status code
-    ck_assert_str_eq(UA_StatusCode_explanation(0x80123456), "Unknown StatusCode");
-    ck_assert_str_eq(UA_StatusCode_name(0x80123456), "Unknown");
+    ck_assert_str_eq(UA_StatusCode_name(0x80123456), "Unknown StatusCode");
 }
 END_TEST
 

tools/generate_statuscode_descriptions.py

@@ -39,31 +39,38 @@ for row in rows:
     count += 1
 
 printc('''
+
+/* Definition for the deprecated StatusCode description API */
+const UA_StatusCodeDescription statusCodeExplanation_default = {0xffffffff, "", ""};
+
+typedef struct {
+    UA_StatusCode code;
+    const char *name;
+} UA_StatusCodeName;
+
 #ifndef UA_ENABLE_STATUSCODE_DESCRIPTIONS
-static const size_t statusCodeDescriptionsSize = 1;
-static const UA_StatusCodeDescription statusCodeDescriptions[1] = {
-{0xffffffff, \"StatusCode descriptions not available\", \"open62541 was compiled without support for statuscode descriptions\"}
-};
+static const char * emptyStatusCodeName = "";
+const char * UA_StatusCode_name(UA_StatusCode code) {
+    return emptyStatusCodeName;
+}
 #else
 static const size_t statusCodeDescriptionsSize = %s;
-static const UA_StatusCodeDescription statusCodeDescriptions[%i] =
-{''' % (count, count))
+static const UA_StatusCodeName statusCodeDescriptions[%i] = {''' % (count, count))
 
-printc(" {UA_STATUSCODE_GOOD, \"Good\", \"Success / No error\"},")
+printc("    {UA_STATUSCODE_GOOD, \"Good\"},")
 for row in rows:
-    printc(" {UA_STATUSCODE_%s, \"%s\", \"%s\"}," % (row[0].upper(), row[0], row[2]))
-printc(" {0xffffffff, \"Unknown\", \"Unknown StatusCode\"},")
-printc('''\n};
-#endif''')
+    printc("    {UA_STATUSCODE_%s, \"%s\",}," % (row[0].upper(), row[0]))
+printc('''    {0xffffffff, "Unknown StatusCode"}
+};
 
-printc('''
-const UA_StatusCodeDescription * UA_StatusCode_description(UA_StatusCode code) {
+const char * UA_StatusCode_name(UA_StatusCode code) {
     for(size_t i = 0; i < statusCodeDescriptionsSize; ++i) {
         if(statusCodeDescriptions[i].code == code)
-            return &statusCodeDescriptions[i];
+            return statusCodeDescriptions[i].name;
     }
-    return &statusCodeDescriptions[statusCodeDescriptionsSize-1];
+    return statusCodeDescriptions[statusCodeDescriptionsSize-1].name;
 }
-''')
+
+#endif''')
 
 fc.close()