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