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