Examples in library prevent build?


So, I must be doing something wrong here.
I am attempting to port an existing Arduino library to the Particle ecosystem, but the included examples makes the build not succeed.

For a minimal test case, I am doing:

mkdir mytestlib
cd mytestlib
particle library create
? Enter a name for your library: mytestlib
? Enter a version for your library: 0.0.1
? Who is the author of your library: me
   create library.properties
   create README.md
   create LICENSE
   create src/mytestlib.cpp
   create src/mytestlib.h
   create examples/usage/usage.ino

Then when I try to build the minimal example with:

particle compile photon

I get the error:

/workspace/examples/usage/usage.cpp:3:23: fatal error: mytestlib.h: No such file or directory
// Example usage for mytestlib library by me.

The automatically generated skeleton example does the include line with quotes:

#include "mytestlib.h"

But I was under the impression that the correct form should be:

#include <mytestlib.h>

Unfortunately, that also fails with the same error.

However, this does succeed:

particle compile photon examples/usage

I am not sure if this is the expected behavior or not. This seems to imply that I would have to move the example out of the library file structure to verify that the library builds correctly, then move them back to upload & publish. Help?


Yes this is the expected behaviour, as you can’t by default build a library as such.
And you can’t build the example as it hasn’t got a project.properties file that would tell the build farm to import that library.
Hence this particle compile <platform> examples/<sample> notation was introduced to allow library creators to test the examples before uploading.

And exactly this is what rids you of the need to move the examples in or out of the library to test your lib.


Is there a library-only build command for particle-cli, which will ignore the examples?
Actually, I now realize that I can put a particle.ignore in place and name the examples/usage/usage.ino (and other examples), which will accomplish the same thing.

So, similarly, what is the right approach to developing both the library port and the example locally (still using the build server, though)? The library has a fairly high complexity and a lot of build options via #defines, so using the WebIDE isn’t going to cut it, and I am using VSCode locally.

Is going through the cycle of upload & publish & adding the contributed library back down to a separate example project going to be the only way to do this?


I’d do the building via CLI with excactly the command you’ve been using particle compile photon example/usage
This will build the example for the current - not yet uploaded - local version of your library.

You don’t want to compile a library as it has no ability to render a runnable firmware. You always need to use the library in a project.
Selfcontained buildable “libraries” would be called “projects” and they’d feature a project.properties file instead of a library.properties file.

I have no experience with VSCode, but I used to use Eclipse with a dedicated build command that just called CLI before I just went back to command line direct.
I also do use a local toolchain for my own projects, but for creating or porting libraries I prefer building in the cloud as this is the way most users will do it and my local toolchain and repo might not always be fully compatible with that due to local tweaking :wink:


K … I am still a little lost. I thought that I read somewhere that the particle-cli has now been extended to support compile for library. Not to produce a flashable binary, but to verify that all the parts of the library compile correctly.
Isn’t that what is being talked about here? Compile library examples

Does this mean that I should set up the example as it’s own “project” with the library as a subdir within that project, and develop on that? From what I understand from here, that is a possible configuration: Documentation for libraries 2.0

I am only using VSCode because it is a good editor, and it had two huge features that are seemingly absent from Atom: 1) C language parsing for go-to-definition and go-to-declaration, and 2) it can be set up to run the compile task & parse the error output into the “problems” pane. I should probably make a post about that setup separately, for anyone else who wants to use it.

As for offline build with offline toolchain, yes that would be great, but I was having a devil of a time getting that to work on another project which I posted about separately.


No and no.
That first thread exactly talks (amongst some meanwhile solved issues) about using particle compile <platform> examples/<sample> and that’s the way to test the library whether it will build correctly or not.
If all the examples can be built and run correctly you have the proof that the library itself is correct - at least as far as the examples do actually use the library as they should :wink:
There would be no use in just building the library but not testing if it did actually do what it’s supposed to. That only can be done with an executable binary.

And the other thread talks about how a library should be used in an independten project once the library is properly uploaded and published.

So since we already do have a working test command for the library, I can’t see the issue :confused:


OK, that is more clear to me now: develop the library by building it via the example in place.

Although I did just try it in the “inverted” project structure way and it totally worked, with no dependency listed in project.properties, but the source & library.properties in lib/mytestlib/

Thanks for walking me through that. I was being so pedantic about that because I thought I was using the build system incorrectly and getting a link error becasue of it. But now I have it exactly the way it should be, I think I am actually stuck with a really bad link error:

/usr/local/gcc-arm-embedded/bin/../lib/gcc/arm-none-eabi/4.8.4/../../../../arm-none-eabi/bin/ld: BFD (GNU 
Tools for ARM Embedded Processors) internal error, aborting at /home/build/work/GCC-4-
8-build/src/binutils/bfd/merge.c line 877 in _bfd_merged_section_offset
/usr/local/gcc-arm-embedded/bin/../lib/gcc/arm-none-eabi/4.8.4/../../../../arm-none-eabi/bin/ld: Please report 
this bug.

this must be due to some issue within the library, symbol collision for a configuration for micro/platform/libc that isn’t set up correctly to match Particle … but, damn, talk about an opaque problem.


For anyone else landing on such an error, the _bfd_merged_section_offset one:
this appears to be a bug or limitation in the version of ARM gcc used by the compile server.
I can locally build the library (and firmware) with gcc 4.8.4 and I will get the same error, but if I use 5.4.1, the error is resolved.