API stability

The stable branch guarantees API stability "forever". The idea is that if you build your ROM against libdragon stable, we will strive to make sure that your ROM will build against newer libdragon versions as well.

Rules to follow

To benefit from API stability in the stable branch, follow these simple rules:

• Include libdragon.h only. libdragon.h brings in the whole libdragon API, so no other libdragon include is necessary. Do not include other header files such as display.h, rsp.h, etc., as these might get renamed, removed, or rearranged in the future.
• Only use public APIs. Libdragon public APIs are those exposed via libdragon.h and documented in the reference manual. Sometimes, header files expose other symbols for internal purposes, that are clearly marked as such with code comments, and specifically hidden from the reference manual. Those symbols are not part of the public API and should not be used as they could go away at any time.
• Use designated initializers for C structures. When initializing a structure defined by libdragon, make sure to use designated initializer to specify the value of one or multiple members of the structure. For instance:

resolution_t res = { .width = 320, .height = 240 };
display_init(res, ...);

// or you can do that inline if you prefer
display_init((resolution_t){.width=320, .height=240}, ...);

This allows libdragon maintainers to add more fields to the structure (as long as 0 is a good, backward compatible default for them), and freely reorder fields in the definition. Using other approaches might create problems in the future. For instance:

// DO NOT DO THIS. All fields not mentioned in your code will be uninitialized causing undefined behavior.
// This will make it impossible to libdragon authors to add more fields to the structure.
resolution_t res;
res.width = 320; 
res.height = 240;
res.interlace = false;
display_init(res, ...);

// DO NOT DO THIS. This would make it impossible to libdragon authors to reorder fields in the structure, which
// is sometimes needed.
resolution_t res = {320, 240, false};
display_init(res, ...);