How to include this repo in a core?

[matthijskooijman]

The README says:

In the future, core apis will be updated independently from the core, so all the compatible cores will seamlessly adopt new features. This requires support from all the IDEs, so in the meantime we suggest to release the core by copying a snapshot of this api folder.

The most elegant and effective solution is to develop the core with api symlinked and produce the distributable archive by telling tar to follow symlinks. Example command:

I'm not so sure I like the idea of adapting the tooling to automatically combine (target-specific) core files and generic api files (from this repository). It seems nice to automatically update all of your cores to a new API version, and that works with changes to e.g. String or (to some degree) Streaam, but will that not break when other fnctions/APIs are added? If the function (e.g. like digitalWrite()) is added in ArduinoCore-API, it will be declared (and ARDUINO_API_VERSION is bumped to indicate the new API is available), but the implementation is target-specific and must be provided by the target core (hence this will lead to linker errors).

To me, it seems better to let each core explicitly update to new API versions, which gives the core a chance to test against the new API version, add new APIs or otherwise make changes, etc. The current recommended approach of a symlink is not particularly good in this regard, since the symlink is not tracked in git, so it needs external documentation to know what API version was used for a particular core version, making it harder to go back to older versions.

Tracking the API version used more explicitly seems better to me, and an obvious mechanism for this is to use submodules. These are a bit like symlinks, but then refer to external git repositories and are versioned (i.e. refer to a specific commit id). Updating a submodule to a newer version is commited as normal in the parent repository.

One caveat for submodules is that, I think, you can only add the repository as a whole, not just a subdirectory (so in this case, cores/arduino/api could be a submodule, but then you would get cores/arduino/api/api with the actual files). Fixing this could be done by putting the files in the root of this repository, though having some structure in this repository might also be useful.

[facchinm]

I agree that the submodule approach could be winning but we have to convince @cmaglie first 😄
Ideally, once we release a new release of the APIs, it would be added to the package_index json as a "core dependency" so multiple versions can coexists at the same time, and every core will decide which one it's targeting by declaring it as a dependency (this was the meaning of "seamlessly adopt new features" 🙂 )

[sandeepmistry]

Ideally, once we release a new release of the APIs, it would be added to the package_index json as a "core dependency" so multiple versions can coexists at the same time, and every core will decide which one it's targeting by declaring it as a dependency (this was the meaning of "seamlessly adopt new features" 🙂 )

This would be super! I prefer it 100x over the submodule.

[cmaglie]

The readme suggests to symlink, but everyone can use any other solution they like, including submodules.

About our repos, I personally don't like submodules, but if it's only me then let's do it... :-)

My alternatives proposal is to make a copy of the api folder from the ArduinoCore-API repo and commit it normally.
This implies a duplication yes, tecnically is very similar to submodules once you do checkout them. Of course you lose the version tracking gived by submodules, but you also avoid all the complications.

[facchinm]

With the actual structure we can't use the submodules method (unless we find acceptable to have a nasty api/api subfolder 🙂

[matthijskooijman]

Frankly, I also think submodules are a pain to work with sometimes, but they do have a lot of good things too. But I'm not intent on using submodules, anything that will work is fine :-)

Ideally, once we release a new release of the APIs, it would be added to the package_index json as a "core dependency" so multiple versions can coexists at the same time, and every core will decide which one it's targeting by declaring it as a dependency (this was the meaning of "seamlessly adopt new features" slightly_smiling_face )

Ah, that would seem like a good approach. It's explicitly versioned, without duplication of code.

My alternatives proposal is to make a copy of the api folder from the ArduinoCore-API repo and commit it normally. This implies a duplication yes, tecnically is very similar to submodules once you do checkout them. Of course you lose the version tracking gived by submodules, but you also avoid all the complications.

This seems like a fine solution, especially if we aim for automating this as suggested by @facchinm above later. If we end up copying, we do not need to be careful with documentation version numbers or git hashes somehow (commit messages or in the files) and resist the temptation of making local changes.

[jaenrig-ifx]

Hi guys,

First of all, thanks to @cmaglie to start the coreAPI subproject. In the XMC-for-Arduino project I was starting to feel the need for an unified API to ensure interoperability.
While an official decision in made on how to add, we might try to add it as a submodule. For now, I guess that is the best way to control the API version in a strict way, and update later on (and check how much has been broken :) ).

Libraries then will need to specify in the library.properties the API dependency and compatible versions as well. Or what would be the approach there?

Thanks!

[oclyke]

For the time being I am proceeding with the submodule approach in the Apollo3 core (with an api/api directory). Could be convinced to use another method if it was convenient.

[matthijskooijman]

Any new thoughts on this? I just tried running the samd core from git, which now just fails to compile due to missing ArduinoCore-api, also with nothing in the README indicating what to do, and nothing indicating which version of the API repository is being targeted.

If nothing else is implemented, maybe consider submodules after all?

[aentinger]

I've just checked:

• ArduinoCore-megaavr contains a note how to set up the link to the API
• same for ArduinoCore-mbed

(One could argue that it would be nice for both instructions to share the same "visual" format).

How about adding this information also to this repositories README?

CC @facchinm What's your take? I could easily prepare an PR.

[facchinm]

@aentinger probably we should add the info on both this and samd repos; if you could prepare the PRs it would be great 😉