examples: split in two categories?

[emmanuelsearch]

The number of examples is growing, and some (e.g. the automated border router + ethos) are orders of magnitude much more elaborate than others (hello world).

However, while more elaborate examples may not be the best didactic-wise or tutorial-like, they offer fundamental functionality, that are somewhere between "tools" and "applications".

So the question is how to deal with those, and where they belong.

[jnohlgard]

I think we should use the applications repository for these kinds of complex use-cases.

[Kijewski]

@kaspar030, could Murdock build applications in https://github.com/RIOT-OS/applications for a branch? I.e. move all "big" examples into there without losing certainty that a patch does not break anything.

[kaspar030]

I think we should use the applications repository for these kinds of complex use-cases.

I think a basic border router it not a complex use case, but the base for many users' experiments. The same goes for minimal 6lowpan/RPL/CoAP or MQTT base applications.
IMHO RIOT should ship those, together with the necessary host tools (like linux ethos).

I would like to see a nice "getting started" experience, as in,

1. check out code
2. flash a border router
3. flash a node
4. launch network setup script
5. open firefox, toggle node's LED via copper.

Having this basic functionality spread over multiple repositories doesn't make things easier.

• if there's no user, where does ethos go, or uhcpd?
• how do we keep the repositories in sync?

[kaspar030]

@kaspar030, could Murdock build applications in https://github.com/RIOT-OS/applications for a branch? I.e. move all "big" examples into there without losing certainty that a patch does not break anything.

Of course it could. The devil lies in the detail.

I administer the CI for one of my clients. In theory, it is a very simple OpenWrt build. In practise, OpenWrt is spread over multiple repositories: core code, package feed repositories and repositories for the packages' sources. From a CI / configuration management perspective, that is a nightmare, unless repository heads are clearly pinned.

For a seperate "applications" repository that would mean it would have to be build against a pinned version of RIOT master, with all the manual updating that implies.
IMHO RIOT is still too volatile for that.

[OlegHahm]

Having this basic functionality spread over multiple repositories doesn't make things easier.

I don't see how this makes a difference, if e.g. RIOT-OS/RIOT would be a submodule of RIOT-OS/applications.

[OlegHahm]

For a seperate "applications" repository that would mean it would have to be build against a pinned version of RIOT master, with all the manual updating that implies.
IMHO RIOT is still too volatile for that.

We have a three monthly release cycle. Pinning the applications against the latest release should be enough.

[kaspar030]

Having this basic functionality spread over multiple repositories doesn't make things easier.

I don't see how this makes a difference, if e.g. RIOT-OS/RIOT would be a submodule of RIOT-OS/applications.

It would at least require a "development branch" for the applications repository, which is based on RIOT master.

Something like the border router and the way it gets configured is tied to RIOT's core, not an application that can be developed against RIOT's stable API.

[OlegHahm]

It would at least require a "development branch" for the applications repository, which is based on RIOT master.

We have this release branches anyway. Do we need anything else?

Something like the border router and the way it gets configured is tied to RIOT's core, not an application that can be developed against RIOT's stable API.

Yes and no. The 6LBR is a feature of GNRC and belongs to RIOT's core. The application that we're discussing is basically a scripted configuration preset.

[kaspar030]

It would at least require a "development branch" for the
applications repository, which is based on RIOT master.

We have this release branches anyway. Do we need anything else?
Yes, the same for RIOT-OS/applications.

Yes and no. The 6LBR is a feature of GNRC and belongs to RIOT's core.
The application that we're discussing is basically a scripted
configuration preset.

No, a scripted configuration preset would be pre-setting fixed
addresses. This is integration of a protocol to configure addresses
automatically, like SLAAC.

Why are you so opposed to see auto configuration as integral part of a
border router? Manually having to configure IP addresses just sucks.

[OlegHahm]

Yes, the same for RIOT-OS/applications.

I don't understand. Why?

No, a scripted configuration preset would be pre-setting fixed addresses. This is integration of a protocol to configure addresses automatically, like SLAAC.

Yes, and this is nice.

Why are you so opposed to see auto configuration as integral part of a
border router? Manually having to configure IP addresses just sucks.

I'm not opposed at all (although I'm not allergic to manual configuration as other people).

[kaspar030]

Yes, the same for RIOT-OS/applications.

I don't understand. Why?
Let's assume RIOT-OS/applications has RIOT-OS/RIOT as a submodule, which
implies a pinned version. Let's say that version os the last RIOT release.

Now I want to introduce, e.g., a new auto configuration scheme for the
border router. That change involves adding a new protocol, a new
host-tool and changes to the border router application.

So I open a PR for the core changes in RIOT-OS/RIOT, and a PR to
RIOT-OS/application.

In RIOT, master is a development branch, so as soon as the changes are
accepted, we can merge.

In application, we don't have that development branch, so if the PR is
incompatible with the pinned RIOT release version, the PR has to wait.
Then, as soon as the next RIOT release is tagged, the PR can be merged.
That means that on release day (always after the release), the border
router application might have become incompatible with the now current
RIOT release. At the same time, the PR might have become stale.

The only way out is having a development branch for the applications.

For things written with the high-level API, these conflicts are
hopefully less often. For something tied to the core, they will pop up
regularly.

The application that we're discussing is basically a scripted
configuration preset.

No, a scripted configuration preset would be pre-setting fixed
addresses. This is integration of a protocol to configure addresses
automatically, like SLAAC.

Yes, and this is nice.

???

Why are you so opposed to see auto configuration as integral part of a
border router? Manually having to configure IP addresses just sucks.

I'm not opposed at all (although I'm not allergic to manual
configuration as other people).

You keep insisting that the concept is something that goes beyond core
functionality and should reside oustide of RIOT's main repository.

[OlegHahm]

Will have to think about this application repository problem, but I'm still convinced we can find a solution that doesn't force us to mix applications and the OS.

The application that we're discussing is basically a scripted configuration preset.
No, a scripted configuration preset would be pre-setting fixed
addresses. This is integration of a protocol to configure addresses
automatically, like SLAAC.

Yes, and this is nice.
???

I think it is a nice feature and one nice way to configure the border router, but other options are possible.

Why are you so opposed to see auto configuration as integral part of a
border router? Manually having to configure IP addresses just sucks.

I'm not opposed at all (although I'm not allergic to manual configuration as other people).
You keep insisting that the concept is something that goes beyond core functionality and should reside oustide of RIOT's main repository.

Yes.

[OlegHahm]

To be clear. I think the updated border router PR is good to be merged. My main point about the discussion here is that we should not mix the OS with applications or configurations that are tailored for one specific use case.

I agree that RIOT and IOT cannot exactly be mapped to Linux and the traditional Internet, but I'm still convinced that we should ship RIOT without KDE. ;)

[aabadie]

So the question is how to deal with those, and where they belong.

Sounds related to my question on the devel mailing list some days ago.
After reading the discussion, I get the point @kaspar030 about maintaining the compatibility between separate repositories for applications and for RIOT.
I have some experience in developing Qt applications and one the strengths of this SDK is the huge number of examples. All features of Qt have one or more examples making things easy to start with Qt.
Maybe RIOT could get some idea from how they organize examples, using one directory per theme (base, serial, network, etc) and a set of documented examples in each of them.
The advantage is that the examples keep their compatibility with the RIOT code base.

[OlegHahm]

I sense that we need a discussion about the overall purpose of RIOT and the RIOT repository. How about discussing this at the next developer meeting on PlaceCam?

[PeterKietzmann]

I put it on the agenda.

[OlegHahm]

thanks

[LudwigKnuepfer]

any outcome?

[OlegHahm]

Have you checked the minutes from the meeting?

[LudwigKnuepfer]

No, they are not linked here. In any case it would have been the right thing to document the outcome here if there was an outcome.

[OlegHahm]

Feel free.

[LudwigKnuepfer]

Seems to have been cast to void.

PeterKietzmann commented on Mar 21, 2016
I put it on the agenda.

->

https://github.com/RIOT-OS/RIOT/wiki/Meetings

->

https://yourpart.eu/p/riot-2016-03-23-virtual-meeting

-overall purpose of the RIOT repository (#5105)

• Postponed to next meeting

->

https://yourpart.eu/p/riot-2016-05-17-virtual-meeting

->

not mentioned (same as for all later linked meeting minutes [Virtual Meeting on October 19, 2016, Virtual Meeting on October 5, 2016, Virtual Meeting on June 15, 2016] as of the time of this writing)

[miri64]

After looking into the doxygen documentation for #6367 I noticed that there actually is a way to include *.c files via the @example command. So I was thinking that maybe moving the show-case examples to doc/examples instead and incorporating them into the show-cased module's doxygen documentation might be a good idea. More complex 'tool examples' could be kept in examples (or have that directory renamed to tools/)

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. If you want me to ignore this issue, please mark it with the "State: don't stale" label. Thank you for your contributions.

[emmanuelsearch]

Some examples have grown even more complex since we last talked about this (e.g. the firmware update example in #11818 ). However, do we qualify this as a problem, in which case we might revisiting this issue?
(else I would close now.)

[aabadie]

I think we should keep it open but change the title to 'examples: split in categories' (remove two and ?).
Then the questions would be more:

• what categories do we want ?
• how can this be handled nicely by the build system ?

[aabadie]

(the question is also valid for tests btw)

[miri64]

See also #5105 for reference.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. If you want me to ignore this issue, please mark it with the "State: don't stale" label. Thank you for your contributions.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. If you want me to ignore this issue, please mark it with the "State: don't stale" label. Thank you for your contributions.