Adding KVStore Examples for Global API

[offirko]

Description

KVStore Examples for Global API
(https://github.com/ARMmbed/mbed-os-example-kvstore)

Pull request type

[ ] Fix
[ ] Refactor
[ ] Target update
[ ] Functionality change
[X] Docs update
[ ] Test update
[ ] Breaking change

[offirko]

@cmonr , @0xc0170 , @AnotherButler , @dannybenor - I'd appreciate your review - thanks.

[dannybenor]

@MarceloSalazar @ashok-rao @adbridge Please review

[0xc0170]

Repositories should follow what we have in this repo.

• have a license file (LICENSE)
• add section to readme about contributions & license (see https://github.com/ARMmbed/mbed-os#license-and-contributions)

[dannybenor]

@0xc0170 we will do.
BTW, I did not find any example that follows both instructions. https://github.com/ARMmbed/mbed-os-example-blinky is not following any of them.

[offirko]

@0xc0170 - added license and contribution information and files

[0xc0170]

BTW, I did not find any example that follows both instructions. https://github.com/ARMmbed/mbed-os-example-blinky is not following any of them.

Correct, the intention is the new repositories should follow it (we check them manually at the moment). We might do a cleanup of current repo in the next feature release (and having automatic check for license + contributing).

It is partially covered here : https://github.com/ARMmbed/mbed-os-5-docs/blob/development/docs/reference/contributing/guidelines/guidelines.md#contributing-guidelines . I'll send an update to the docs to state it explicitly there.

Update: I've sent PR to add it to the docs: ARMmbed/mbed-os-5-docs#848

[MarceloSalazar]

@offirko @dannybenor Can you help me to understand the differences between the examples?

I assume mbed-os-example-kvstore is the one that would be used by most developers, whether mbed-os-example-kvstore-class-api is using low-level APIs? is this correct?
Do we really need the latter as an example?
Also it feels there is lots of repetition

[dannybenor]

@MarceloSalazar The examples are for customers and your are their representative.
We will be more than happy to remove the class API example. Just say the word :)

[offirko]

@MarceloSalazar - it kinda reminds fopen/fwrite/fread -vs-open/write/read .. both are used

[cmonr]

@dannybenor I'm alright with adding another example, but would you/your team be willing to compact these two examples into a single repo? Something like what NFC does with theirs?

Reference: https://github.com/ARMmbed/mbed-os-example-nfc

Similar to @MarceloSalazar's thoughts, it seems like the two are closely related.

[dannybenor]

They were in a single repo. @MarceloSalazar asked for the separation to support online compiler...

[cmonr]

They were in a single repo. @MarceloSalazar asked for the separation to support online compiler...

OH. Well then.

[cmonr]

So here's an idea. No one is saying that we don't want the examples.
For the time being, I'm going to start CI, and if we remove one of the examples, then so be it. This should at least let us progress this PR.

Might need other @ARMmbed/mbed-os-maintainers and @MarceloSalazar to chime in. Didn't know the part about wanting the split for the online compiler, although that sounds odd.

[MarceloSalazar]

Thanks for splitting the examples. This greatly helps with the review of the docs and application when using both Mbed CLI and Online Compiler. Otherwise, we'd need to do a number of hacks (git clone, delete folders, ets), which is not great for users. We should just use mbed import ...

My main request right now is to clarify the name of the mbed-os-example-kvstore-class-api example to make it a bit more clear what's intended for - this will let us proceed to merge this PR asap. Any ideas?
Later on you can add a bit more context to the docs.

[dannybenor]

@MarceloSalazar The name reflects exactly what the example is. It is clear that kvstore is the key that you will look for in the documentation if you don't know what it is. I believe people looks for examples like this when they want to use some Mbed OS functionality. Kvstore is the name of this functionality. Recommend to leave the name as is.

[0xc0170]

This will soon complete the CI (expecting green).

Please finalize reviews soon

My addition - also not sure about class-api example - shouldn't this be in docs rather (we provide code snippets in the doxygen docs for class, also docs pages have own documentation where this code can live) ? or will be linked there as own example?

[MarceloSalazar]

My addition - also not sure about class-api example - shouldn't this be in docs rather (we provide code snippets in the doxygen docs for class, also docs pages have own documentation where this code can live) ? or will be linked there as own example?

I like the idea of code snippets in the docs for this class-api example, as it's a reference for a different kind of users but probably not the example that most people will be using as starting point.

[0xc0170]

Looks like exporters will fail

compiling main.cpp...
linking...
.\.link_script.sct(47): error: L6236E: No section matches selector - no section to be FIRST/LAST.
.\.link_script.sct(51): error: L6236E: No section matches selector - no section to be FIRST/LAST.
Not enough information to list image symbols.
Not enough information to list load addresses in the image map.

There's assembling startup_LPC54114_cm4.S... so why is this failing is weird (blinky example is this one).

I am going to fetch this locally, have seen this failure yesterday somewhere. This indicates there's missing startup file. not related to this PR

cc @OPpuolitaival

[mbed-ci]

Test run: SUCCESS

Summary: 4 of 4 test jobs passed
Build number : 1
Build artifacts
Build logs

[0xc0170]

@bulislaw Please review above comments about class-api example

[bulislaw]

I agree, I don't like idea of proliferating examples as that introduces maintenance burden. One should be enough and we can extend the docs (not necessarily for 5.11 if there's no time)

[dannybenor]

OK. I understand now that I know nothing about the goal of the examples. Will be good to get an explanation at some point why we do not want an example for 3 new classes, with customer facing API added in 5.11.
@offirko please remove the link to the class example

[offirko]

https://user-images.githubusercontent.com/36957743/49081132-78089780-f24e-11e8-81d2-0648998bbd09.png

removing..

[0xc0170]

Starting CI now

[0xc0170]

I believe @MarceloSalazar this as approved, so started CI to get this through asap

[mbed-ci]

Test run: SUCCESS

Summary: 4 of 4 test jobs passed
Build number : 2
Build artifacts
Build logs

[cmonr]

Restarting export CI job.

[0xc0170]

Restarted exporters job after jenkins was restarted