1===================================== 2Nanopb: Migration from older versions 3===================================== 4 5.. include :: menu.rst 6 7This document details all the breaking changes that have been made to nanopb 8since its initial release. For each change, the rationale and required 9modifications of user applications are explained. Also any error indications 10are included, in order to make it easier to find this document. 11 12.. contents :: 13 14Nanopb-0.3.5 (2016-02-13) 15========================= 16 17Add support for platforms without uint8_t 18----------------------------------------- 19**Rationale:** Some platforms cannot access 8-bit sized values directly, and 20do not define *uint8_t*. Nanopb previously didn't support these platforms. 21 22**Changes:** References to *uint8_t* were replaced with several alternatives, 23one of them being a new *pb_byte_t* typedef. This in turn uses *uint_least8_t* 24which 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 28added manually, example can be found in *extra/pb_syshdr.h*. 29 30**Error indications:** Compiler error: "unknown type name 'uint_least8_t'". 31 32Nanopb-0.3.2 (2015-01-24) 33========================= 34 35Add 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 41supported inside oneof and generator gives an error. 42 43**Required actions:** The generator option *no_unions* can be used to restore old 44behaviour and to allow callbacks to be used. To use unions, one change is 45needed: use *which_xxxx* field to detect which field is present, instead 46of *has_xxxx*. Compare the value against *MyStruct_myfield_tag*. 47 48**Error indications:** Generator error: "Callback fields inside of oneof are 49not supported". Compiler error: "Message" has no member named "has_xxxx". 50 51Nanopb-0.3.0 (2014-08-26) 52========================= 53 54Separate field iterator logic to pb_common.c 55-------------------------------------------- 56**Rationale:** Originally, the field iteration logic was simple enough to be 57duplicated in *pb_decode.c* and *pb_encode.c*. New field types have made the 58logic more complex, which required the creation of a new file to contain the 59common functionality. 60 61**Changes:** There is a new file, *pb_common.c*, which must be included in 62builds. 63 64**Required actions:** Add *pb_common.c* to build rules. This file is always 65required. Either *pb_decode.c* or *pb_encode.c* can still be left out if some 66functionality is not needed. 67 68**Error indications:** Linker error: undefined reference to 69*pb_field_iter_begin*, *pb_field_iter_next* or similar. 70 71Change data type of field counts to pb_size_t 72--------------------------------------------- 73**Rationale:** Often nanopb is used with small arrays, such as 255 items or 74less. Using a full *size_t* field to store the array count wastes memory if 75there 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. 79The 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 87changes in the same version already require regenerating the files and have 88better indications of errors, so this is only an issue for development 89versions. 90 91Renamed some macros and identifiers 92----------------------------------- 93**Rationale:** Some names in nanopb core were badly chosen and conflicted with 94ISO C99 reserved names or lacked a prefix. While they haven't caused trouble 95so far, it is reasonable to switch to non-conflicting names as these are rarely 96used 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 120identifiers 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 124Nanopb-0.2.9 (2014-08-09) 125========================= 126 127Change semantics of generator -e option 128--------------------------------------- 129**Rationale:** Some compilers do not accept filenames with two dots (like 130in default extension .pb.c). The *-e* option to the generator allowed changing 131the extension, but not skipping the extra dot. 132 133**Changes:** The *-e* option in generator will no longer add the prepending 134dot. The default value has been adjusted accordingly to *.pb.c* to keep the 135default behaviour the same as before. 136 137**Required actions:** Only if using the generator -e option. Add dot before 138the parameter value on the command line. 139 140**Error indications:** File not found when trying to compile generated files. 141 142Nanopb-0.2.7 (2014-04-07) 143========================= 144 145Changed pointer-type bytes field datatype 146----------------------------------------- 147**Rationale:** In the initial pointer encoding support since nanopb-0.2.5, 148the bytes type used a separate *pb_bytes_ptr_t* type to represent *bytes* 149fields. This made it easy to encode data from a separate, user-allocated 150buffer. However, it made the internal logic more complex and was inconsistent 151with the other types. 152 153**Changes:** Dynamically allocated bytes fields now have the *pb_bytes_array_t* 154type, just like statically allocated ones. 155 156**Required actions:** Only if using pointer-type fields with the bytes datatype. 157Change any access to *msg->field.size* to *msg->field->size*. Change any 158allocation to reserve space of amount *PB_BYTES_ARRAY_T_ALLOCSIZE(n)*. If the 159data pointer was begin assigned from external source, implement the field using 160a callback function instead. 161 162**Error indications:** Compiler error: unknown type name *pb_bytes_ptr_t*. 163 164Nanopb-0.2.4 (2013-11-07) 165========================= 166 167Remove the NANOPB_INTERNALS compilation option 168---------------------------------------------- 169**Rationale:** Having the option in the headers required the functions to 170be non-static, even if the option is not used. This caused errors on some 171static analysis tools. 172 173**Changes:** The *#ifdef* and associated functions were removed from the 174header. 175 176**Required actions:** Only if the *NANOPB_INTERNALS* option was previously 177used. 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 182Nanopb-0.2.1 (2013-04-14) 183========================= 184 185Callback function signature 186--------------------------- 187**Rationale:** Previously the auxilary data to field callbacks was passed 188as *void\**. This allowed passing of any data, but made it unnecessarily 189complex 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 194defining *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 201pointer type, when initializing *funcs.encode* or *funcs.decode*. 202 203Nanopb-0.2.0 (2013-03-02) 204========================= 205 206Reformatted generated .pb.c file using macros 207--------------------------------------------- 208**Rationale:** Previously the generator made a list of C *pb_field_t* 209initializers in the .pb.c file. This led to a need to regenerate all .pb.c 210files after even small changes to the *pb_field_t* definition. 211 212**Changes:** Macros were added to pb.h which allow for cleaner definition 213of the .pb.c contents. By changing the macro definitions, changes to the 214field structure are possible without breaking compatibility with old .pb.c 215files. 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 222Changed pb_type_t definitions 223----------------------------- 224**Rationale:** The *pb_type_t* was previously an enumeration type. This 225caused warnings on some compilers when using bitwise operations to set flags 226inside the values. 227 228**Changes:** The *pb_type_t* was changed to *typedef uint8_t*. The values 229were changed to *#define*. Some value names were changed for consistency. 230 231**Required actions:** Only if you directly access the `pb_field_t` contents 232in 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* 238undeclared. 239 240Nanopb-0.1.6 (2012-09-02) 241========================= 242 243Refactored 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 250the 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 256Nanopb-0.1.3 (2012-06-12) 257========================= 258 259Refactored field encoder interface 260---------------------------------- 261**Rationale:** The old *pb_enc_\** functions were designed mostly for the 262internal use by the core. Because they are internally accessed through 263function pointers, their signatures had to be common. This led to a confusing 264interface for external users. 265 266**Changes:** New functions with names *pb_encode_\** were added. These have 267easier to use interfaces. The old functions are now only thin wrappers for 268the new interface. 269 270**Required actions:** By defining NANOPB_INTERNALS, you can still keep using 271the 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 277