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-09-xx)
  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 Nanopb-0.2.9 (2014-08-09)
  35 =========================
  36
  37 Change semantics of generator -e option
  38 ---------------------------------------
  39 **Rationale:** Some compilers do not accept filenames with two dots (like
  40 in default extension .pb.c). The *-e* option to the generator allowed changing
  41 the extension, but not skipping the extra dot.
  42
  43 **Changes:** The *-e* option in generator will no longer add the prepending
  44 dot. The default value has been adjusted accordingly to *.pb.c* to keep the
  45 default behaviour the same as before.
  46
  47 **Required actions:** Only if using the generator -e option. Add dot before
  48 the parameter value on the command line.
  49
  50 **Error indications:** File not found when trying to compile generated files.
  51
  52 Nanopb-0.2.7 (2014-04-07)
  53 =========================
  54
  55 Changed pointer-type bytes field datatype
  56 -----------------------------------------
  57 **Rationale:** In the initial pointer encoding support since nanopb-0.2.5,
  58 the bytes type used a separate *pb_bytes_ptr_t* type to represent *bytes*
  59 fields. This made it easy to encode data from a separate, user-allocated
  60 buffer. However, it made the internal logic more complex and was inconsistent
  61 with the other types.
  62
  63 **Changes:** Dynamically allocated bytes fields now have the *pb_bytes_array_t*
  64 type, just like statically allocated ones.
  65
  66 **Required actions:** Only if using pointer-type fields with the bytes datatype.
  67 Change any access to *msg->field.size* to *msg->field->size*. Change any
  68 allocation to reserve space of amount *PB_BYTES_ARRAY_T_ALLOCSIZE(n)*. If the
  69 data pointer was begin assigned from external source, implement the field using
  70 a callback function instead.
  71
  72 **Error indications:** Compiler error: unknown type name *pb_bytes_ptr_t*.
  73
  74 Nanopb-0.2.4 (2013-11-07)
  75 =========================
  76
  77 Remove the NANOPB_INTERNALS compilation option
  78 ----------------------------------------------
  79 **Rationale:** Having the option in the headers required the functions to
  80 be non-static, even if the option is not used. This caused errors on some
  81 static analysis tools.
  82
  83 **Changes:** The *#ifdef* and associated functions were removed from the
  84 header.
  85
  86 **Required actions:** Only if the *NANOPB_INTERNALS* option was previously
  87 used. Actions are as listed under nanopb-0.1.3 and nanopb-0.1.6.
  88
  89 **Error indications:** Compiler warning: implicit declaration of function
  90 *pb_dec_string*, *pb_enc_string*, or similar.
  91
  92 Nanopb-0.2.1 (2013-04-14)
  93 =========================
  94
  95 Callback function signature
  96 ---------------------------
  97 **Rationale:** Previously the auxilary data to field callbacks was passed
  98 as *void\**. This allowed passing of any data, but made it unnecessarily
  99 complex to return a pointer from callback.
 100
 101 **Changes:** The callback function parameter was changed to *void\**.
 102
 103 **Required actions:** You can continue using the old callback style by
 104 defining *PB_OLD_CALLBACK_STYLE*. Recommended action is to:
 105
 106   * Change the callback signatures to contain *void\** for decoders and
 107     *void \* const \** for encoders.
 108   * Change the callback function body to use *\*arg* instead of *arg*.
 109
 110 **Error indications:** Compiler warning: assignment from incompatible
 111 pointer type, when initializing *funcs.encode* or *funcs.decode*.
 112
 113 Nanopb-0.2.0 (2013-03-02)
 114 =========================
 115
 116 Reformatted generated .pb.c file using macros
 117 ---------------------------------------------
 118 **Rationale:** Previously the generator made a list of C *pb_field_t*
 119 initializers in the .pb.c file. This led to a need to regenerate all .pb.c
 120 files after even small changes to the *pb_field_t* definition.
 121
 122 **Changes:** Macros were added to pb.h which allow for cleaner definition
 123 of the .pb.c contents. By changing the macro definitions, changes to the
 124 field structure are possible without breaking compatibility with old .pb.c
 125 files.
 126
 127 **Required actions:** Regenerate all .pb.c files from the .proto sources.
 128
 129 **Error indications:** Compiler warning: implicit declaration of function
 130 *pb_delta_end*.
 131
 132 Changed pb_type_t definitions
 133 -----------------------------
 134 **Rationale:** The *pb_type_t* was previously an enumeration type. This
 135 caused warnings on some compilers when using bitwise operations to set flags
 136 inside the values.
 137
 138 **Changes:** The *pb_type_t* was changed to *typedef uint8_t*. The values
 139 were changed to *#define*. Some value names were changed for consistency.
 140
 141 **Required actions:** Only if you directly access the `pb_field_t` contents
 142 in your own code, something which is not usually done. Needed changes:
 143
 144   * Change *PB_HTYPE_ARRAY* to *PB_HTYPE_REPEATED*.
 145   * Change *PB_HTYPE_CALLBACK* to *PB_ATYPE()* and *PB_ATYPE_CALLBACK*.
 146
 147 **Error indications:** Compiler error: *PB_HTYPE_ARRAY* or *PB_HTYPE_CALLBACK*
 148 undeclared.
 149
 150 Nanopb-0.1.6 (2012-09-02)
 151 =========================
 152
 153 Refactored field decoder interface
 154 ----------------------------------
 155 **Rationale:** Similarly to field encoders in nanopb-0.1.3.
 156
 157 **Changes:** New functions with names *pb_decode_\** were added.
 158
 159 **Required actions:** By defining NANOPB_INTERNALS, you can still keep using
 160 the old functions. Recommended action is to replace any calls with the newer
 161 *pb_decode_\** equivalents.
 162
 163 **Error indications:** Compiler warning: implicit declaration of function
 164 *pb_dec_string*, *pb_dec_varint*, *pb_dec_submessage* or similar.
 165
 166 Nanopb-0.1.3 (2012-06-12)
 167 =========================
 168
 169 Refactored field encoder interface
 170 ----------------------------------
 171 **Rationale:** The old *pb_enc_\** functions were designed mostly for the
 172 internal use by the core. Because they are internally accessed through
 173 function pointers, their signatures had to be common. This led to a confusing
 174 interface for external users.
 175
 176 **Changes:** New functions with names *pb_encode_\** were added. These have
 177 easier to use interfaces. The old functions are now only thin wrappers for
 178 the new interface.
 179
 180 **Required actions:** By defining NANOPB_INTERNALS, you can still keep using
 181 the old functions. Recommended action is to replace any calls with the newer
 182 *pb_encode_\** equivalents.
 183
 184 **Error indications:** Compiler warning: implicit declaration of function
 185 *pb_enc_string*, *pb_enc_varint, *pb_enc_submessage* or similar.
 186