Local Libraries + Workbench

Hi Folks,

I’ve read about every docs page and community post I can find on local libraries and their structure and how to use them in Workbench but the picture is still unclear to me as to what Workbench is expecting in order to compile local libraries. Usually the answer to others questions is “Create a demo project and copy the structure” but sometimes that’s just not possible when wanting to bring in pre-existing libraries and it appears that my library is already following that structure but I’m still facing an error.

Currently I understand the following must be true:

  • Libraries must be within their own folder in the “libs” or “libraries” folder of a project
  • Libraries must have a libraries.properties file
  • Libraries must have their .h and .cpp files within an “src” folder inside the library folder

I have a library I am trying to port over to use on a Particle Boron from an Arduino project and it’s structured according to the above rules however it’s not able to be found by the compiler.

Creating c:/Users/<username>/Documents/GitHub/icarus_firmware/target/1.5.2/boron/platform_user_ram.ld ...
In file included from c:/Users/<username>/Documents/GitHub/icarus_firmware/libraries/SimpleHDLC/src/SimpleHDLC.cpp:1:0:
c:/Users/<username>/Documents/GitHub/icarus_firmware/libraries/SimpleHDLC/src/SimpleHDLC.h:7:21: fatal error: FastCRC.h: No such file or directory
compilation terminated.

You can find the project and the specific library I am referring to here: https://github.com/outoftolerance/icarus_firmware/tree/master/libraries/FastCRC

I’ve tried a number of different experiments with naming, file locations, etc but can’t seem to get it to compile, any insight as to why the compiler can’t find the file would be much appreciated!

Hmm, I don’t think that’s the way to do it.
If you want to build a library you should use particle library create

I don’t know about the or “libraries” part, I’d stick with “lib” and only that.

BTW, does <username> happen to contain blanks? If so, that may be the issue.

Thanks @ScruffR.

<username> does not contain any spaces or special characters, it’s just lowercase alphabet chars.

One of the experiments I ran was changing from “libraries” to “lib” and “libs” and that didn’t change the issue, it appears to me that Workbench compiles with either option and I’d prefer to use “libraries” because there are other .ino files in the project that I am compiling with Arduino IDE which uses this name.

I did create a library with particle library create to ensure that my properties file and file structure matched, which they do.

Is it required that the .h and .cpp files have the same name?

This library I am porting has FashCRC.h but no FastCRC.cpp file, the cpp files are structured differently. I did try re-naming the files as such but it didn’t compile, maybe I didn’t do it correctly if this is a requirement…

Nope, this is not required. But for clarity it is always good to have at least one header file that matches the library name. Apart from that, your library can consist of many files of various names as long things are consistent (i.e. include statements refer to the correct files) and don’t clash with other file names present in the project.

However, this might be also contributing to the issue.
Usually we advise people to only have one .ino file in a project to prevent confusion - particularly for the Wiring preprocessor.

Unfortunately both my dev machines recently died on me, so I cannot really test stuff for myself till I get a new machine set up.

1 Like

Thanks, the library and my files seem like they should match the correct structure.

I tried removing all other .ino files in the project but have the same error. Is there a way to access the compiler and linker settings/configuration in Workbench?

I’d be really grateful if you could try to compile once you’ve got a working setup again!

Can you pack your entire project in a zip file and PM me a link (e.g. Google Drive) or upload the project to GitHub?

The GitHub link is here: https://github.com/outoftolerance/icarus_firmware/tree/master/

Does anyone else know if the compiler and linker settings are available somewhere to be tweaked?

there are a number of options you can explore - they all come with the standard disclaimer: for advanced users only.

first, you can interact with Workbench’s local compiler by running Particle: Launch Compiler Shell - it prints out basic usage info when you invoke the command.

Workbench sits on top of the Device OS’ build system - (somewhat) documented here:

https://github.com/particle-iot/device-os/blob/v1.5.2/docs/build.md (note: you should reference the docs for the specific version of the Device OS you are targeting)

Device OS’ build system supports extension via a custom ./src/build.mk file - visit:

…then scroll down until you see the section labeled " Including additional header directories" (we’re working on creating direct links to these)

you can basically ignore all directions to install custom toolchain bits as this is what WB does for you the caveat being that you’ll need to run within WB for now.

hope that helps, good luck :+1:

1 Like

Also, for anyone looking to use the build system outside of Workbench I’ve been working on a feature-complete utility for the last month.

Thanks @m_m! I was able to restructure the project using the Extended Project Structure and add a custom build.mk file that explicitly included by libraries directory, it built first go!

The solution looked as follows and is a really neat way to build multiple source files, Arduino and Particle, from a single project that share libraries with one another (in my case this is because I have multiple devices communicating with each other and I want to share things like the message protocol libraries).

  • Project Dir
  • project.properties
  • libraries
    • libraryName
      • library.properties
      • src
        • libraryName.h
        • libraryName.cpp
  • src
    • build.mk
    • first_app
      • first_app.ino
    • other_app
      • other_app.ino

The build.mk file ended up looking like this:

# Standard behavior must be included here
INCLUDE_DIRS += $(SOURCE_PATH)/$(USRSRC)  # add user sources to include path
CPPSRC += $(call target_files,$(USRSRC_SLASH),*.cpp)
CSRC += $(call target_files,$(USRSRC_SLASH),*.c)

APPSOURCES=$(call target_files,$(USRSRC_SLASH),*.cpp)
APPSOURCES+=$(call target_files,$(USRSRC_SLASH),*.c)

# Custom stuff can be added here
INCLUDE_DIRS += $(SOURCE_PATH)/libraries

This can now be seen in my GitHub repo here for anyone looking for a future reference: https://github.com/outoftolerance/icarus_firmware/tree/624dfec59c3a1975fe120b5e97f90049ecb62d5e

Update: You don’t even need the build file, it appears just nesting the *.ino files into a “src” directory solves the problem.

1 Like

@outoftolerance glad you got things sorted out and thanks for sharing your notes :+1: