docs/migration.rst

   1 =====================================
   2 Nanopb: Migration from older versions
   3 =====================================
   4
   5 .. include :: menu.rst
   6
   7 This document details all the breaking changes that have been made to nanopb
   8 since its initial release. For each change, the rationale and required
   9 modifications of user applications are explained. Also any error indications
  10 are included, in order to make it easier to find this document.
  11
  12 .. contents ::
  13
  14 Nanopb-0.3.2 (2015-01-24)
  15 =========================
  16
  17 Add support for OneOfs
  18 ----------------------
  19 **Rationale:** Previously nanopb did not support the *oneof* construct in
  20 *.proto* files. Those fields were generated as regular *optional* fields.
  21
  22 **Changes:** OneOfs are now generated as C unions. Callback fields are not
  23 supported inside oneof and generator gives an error.
  24
  25 **Required actions:** The generator option *no_unions* can be used to restore old
  26 behaviour and to allow callbacks to be used. To use unions, one change is
  27 needed: use *which_xxxx* field to detect which field is present, instead
  28 of *has_xxxx*. Compare the value against *MyStruct_myfield_tag*.
  29
  30 **Error indications:** Generator error: "Callback fields inside of oneof are
  31 not supported". Compiler error: "Message" has no member named "has_xxxx".
  32
  33 Nanopb-0.3.0 (2014-08-26)
  34 =========================
  35
  36 Separate field iterator logic to pb_common.c
  37 --------------------------------------------
  38 **Rationale:** Originally, the field iteration logic was simple enough to be
  39 duplicated in *pb_decode.c* and *pb_encode.c*. New field types have made the
  40 logic more complex, which required the creation of a new file to contain the
  41 common functionality.
  42
  43 **Changes:** There is a new file, *pb_common.c*, which must be included in
  44 builds.
  45
  46 **Required actions:** Add *pb_common.c* to build rules. This file is always
  47 required. Either *pb_decode.c* or *pb_encode.c* can still be left out if some
  48 functionality is not needed.
  49
  50 **Error indications:** Linker error: undefined reference to
  51 *pb_field_iter_begin*, *pb_field_iter_next* or similar.
  52
  53 Change data type of field counts to pb_size_t
  54 ---------------------------------------------
  55 **Rationale:** Often nanopb is used with small arrays, such as 255 items or
  56 less. Using a full *size_t* field to store the array count wastes memory if
  57 there are many arrays. There already exists parameters *PB_FIELD_16BIT* and
  58 *PB_FIELD_32BIT* which tell nanopb what is the maximum size of arrays in use.
  59
  60 **Changes:** Generator will now use *pb_size_t* for the array *_count* fields.
  61 The size of the type will be controlled by the *PB_FIELD_16BIT* and
  62 *PB_FIELD_32BIT* compilation time options.
  63
  64 **Required actions:** Regenerate all *.pb.h* files. In some cases casts to the
  65 *pb_size_t* type may need to be added in the user code when accessing the
  66 *_count* fields.
  67
  68 **Error indications:** Incorrect data at runtime, crashes. But note that other
  69 changes in the same version already require regenerating the files and have
  70 better indications of errors, so this is only an issue for development
  71 versions.
  72
  73 Renamed some macros and identifiers
  74 -----------------------------------
  75 **Rationale:** Some names in nanopb core were badly chosen and conflicted with
  76 ISO C99 reserved names or lacked a prefix. While they haven't caused trouble
  77 so far, it is reasonable to switch to non-conflicting names as these are rarely
  78 used from user code.
  79
  80 **Changes:** The following identifier names have changed:
  81
  82   * Macros:
  83
  84     * STATIC_ASSERT(x) -> PB_STATIC_ASSERT(x)
  85     * UNUSED(x) -> PB_UNUSED(x)
  86
  87   * Include guards:
  88
  89     * _PB_filename_ -> PB_filename_INCLUDED
  90
  91   * Structure forward declaration tags:
  92
  93     * _pb_field_t -> pb_field_s
  94     * _pb_bytes_array_t -> pb_bytes_array_s
  95     * _pb_callback_t -> pb_callback_s
  96     * _pb_extension_type_t -> pb_extension_type_s
  97     * _pb_extension_t -> pb_extension_s
  98     * _pb_istream_t -> pb_istream_s
  99     * _pb_ostream_t -> pb_ostream_s
 100
 101 **Required actions:** Regenerate all *.pb.c* files. If you use any of the above
 102 identifiers in your application code, perform search-replace to the new name.
 103
 104 **Error indications:** Compiler errors on lines with the macro/type names.
 105
 106 Nanopb-0.2.9 (2014-08-09)
 107 =========================
 108
 109 Change semantics of generator -e option
 110 ---------------------------------------
 111 **Rationale:** Some compilers do not accept filenames with two dots (like
 112 in default extension .pb.c). The *-e* option to the generator allowed changing
 113 the extension, but not skipping the extra dot.
 114
 115 **Changes:** The *-e* option in generator will no longer add the prepending
 116 dot. The default value has been adjusted accordingly to *.pb.c* to keep the
 117 default behaviour the same as before.
 118
 119 **Required actions:** Only if using the generator -e option. Add dot before
 120 the parameter value on the command line.
 121
 122 **Error indications:** File not found when trying to compile generated files.
 123
 124 Nanopb-0.2.7 (2014-04-07)
 125 =========================
 126
 127 Changed pointer-type bytes field datatype
 128 -----------------------------------------
 129 **Rationale:** In the initial pointer encoding support since nanopb-0.2.5,
 130 the bytes type used a separate *pb_bytes_ptr_t* type to represent *bytes*
 131 fields. This made it easy to encode data from a separate, user-allocated
 132 buffer. However, it made the internal logic more complex and was inconsistent
 133 with the other types.
 134
 135 **Changes:** Dynamically allocated bytes fields now have the *pb_bytes_array_t*
 136 type, just like statically allocated ones.
 137
 138 **Required actions:** Only if using pointer-type fields with the bytes datatype.
 139 Change any access to *msg->field.size* to *msg->field->size*. Change any
 140 allocation to reserve space of amount *PB_BYTES_ARRAY_T_ALLOCSIZE(n)*. If the
 141 data pointer was begin assigned from external source, implement the field using
 142 a callback function instead.
 143
 144 **Error indications:** Compiler error: unknown type name *pb_bytes_ptr_t*.
 145
 146 Nanopb-0.2.4 (2013-11-07)
 147 =========================
 148
 149 Remove the NANOPB_INTERNALS compilation option
 150 ----------------------------------------------
 151 **Rationale:** Having the option in the headers required the functions to
 152 be non-static, even if the option is not used. This caused errors on some
 153 static analysis tools.
 154
 155 **Changes:** The *#ifdef* and associated functions were removed from the
 156 header.
 157
 158 **Required actions:** Only if the *NANOPB_INTERNALS* option was previously
 159 used. Actions are as listed under nanopb-0.1.3 and nanopb-0.1.6.
 160
 161 **Error indications:** Compiler warning: implicit declaration of function
 162 *pb_dec_string*, *pb_enc_string*, or similar.
 163
 164 Nanopb-0.2.1 (2013-04-14)
 165 =========================
 166
 167 Callback function signature
 168 ---------------------------
 169 **Rationale:** Previously the auxilary data to field callbacks was passed
 170 as *void\**. This allowed passing of any data, but made it unnecessarily
 171 complex to return a pointer from callback.
 172
 173 **Changes:** The callback function parameter was changed to *void\*\**.
 174
 175 **Required actions:** You can continue using the old callback style by
 176 defining *PB_OLD_CALLBACK_STYLE*. Recommended action is to:
 177
 178   * Change the callback signatures to contain *void\*\** for decoders and
 179     *void \* const \** for encoders.
 180   * Change the callback function body to use *\*arg* instead of *arg*.
 181
 182 **Error indications:** Compiler warning: assignment from incompatible
 183 pointer type, when initializing *funcs.encode* or *funcs.decode*.
 184
 185 Nanopb-0.2.0 (2013-03-02)
 186 =========================
 187
 188 Reformatted generated .pb.c file using macros
 189 ---------------------------------------------
 190 **Rationale:** Previously the generator made a list of C *pb_field_t*
 191 initializers in the .pb.c file. This led to a need to regenerate all .pb.c
 192 files after even small changes to the *pb_field_t* definition.
 193
 194 **Changes:** Macros were added to pb.h which allow for cleaner definition
 195 of the .pb.c contents. By changing the macro definitions, changes to the
 196 field structure are possible without breaking compatibility with old .pb.c
 197 files.
 198
 199 **Required actions:** Regenerate all .pb.c files from the .proto sources.
 200
 201 **Error indications:** Compiler warning: implicit declaration of function
 202 *pb_delta_end*.
 203
 204 Changed pb_type_t definitions
 205 -----------------------------
 206 **Rationale:** The *pb_type_t* was previously an enumeration type. This
 207 caused warnings on some compilers when using bitwise operations to set flags
 208 inside the values.
 209
 210 **Changes:** The *pb_type_t* was changed to *typedef uint8_t*. The values
 211 were changed to *#define*. Some value names were changed for consistency.
 212
 213 **Required actions:** Only if you directly access the `pb_field_t` contents
 214 in your own code, something which is not usually done. Needed changes:
 215
 216   * Change *PB_HTYPE_ARRAY* to *PB_HTYPE_REPEATED*.
 217   * Change *PB_HTYPE_CALLBACK* to *PB_ATYPE()* and *PB_ATYPE_CALLBACK*.
 218
 219 **Error indications:** Compiler error: *PB_HTYPE_ARRAY* or *PB_HTYPE_CALLBACK*
 220 undeclared.
 221
 222 Nanopb-0.1.6 (2012-09-02)
 223 =========================
 224
 225 Refactored field decoder interface
 226 ----------------------------------
 227 **Rationale:** Similarly to field encoders in nanopb-0.1.3.
 228
 229 **Changes:** New functions with names *pb_decode_\** were added.
 230
 231 **Required actions:** By defining NANOPB_INTERNALS, you can still keep using
 232 the old functions. Recommended action is to replace any calls with the newer
 233 *pb_decode_\** equivalents.
 234
 235 **Error indications:** Compiler warning: implicit declaration of function
 236 *pb_dec_string*, *pb_dec_varint*, *pb_dec_submessage* or similar.
 237
 238 Nanopb-0.1.3 (2012-06-12)
 239 =========================
 240
 241 Refactored field encoder interface
 242 ----------------------------------
 243 **Rationale:** The old *pb_enc_\** functions were designed mostly for the
 244 internal use by the core. Because they are internally accessed through
 245 function pointers, their signatures had to be common. This led to a confusing
 246 interface for external users.
 247
 248 **Changes:** New functions with names *pb_encode_\** were added. These have
 249 easier to use interfaces. The old functions are now only thin wrappers for
 250 the new interface.
 251
 252 **Required actions:** By defining NANOPB_INTERNALS, you can still keep using
 253 the old functions. Recommended action is to replace any calls with the newer
 254 *pb_encode_\** equivalents.
 255
 256 **Error indications:** Compiler warning: implicit declaration of function
 257 *pb_enc_string*, *pb_enc_varint, *pb_enc_submessage* or similar.
 258