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