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