Publish a library

Beta Libs 2.0 Beta
1

It’s now possible to publish libraries using the CLI. Those libraries must be in the library 2.0 format

To create a new library, do particle library init in an empty directory and follow the prompts.

To publish a new version of an existing library, migrate it to 2.0 format with particle library migrate

Since the new library format is compatible with Arduino, you should be able to clone an Arduino library, make minor modifications for platform differences and publish it as a Particle library.

Update the source files for the library in src/ and the examples in examples/.

To try the library in your own project before publishing it, copy-paste or symbolic link the entire library directory inside the lib/ directory of your project like so:

+- lib
| +- MyLibrary
|   +- src
|   | +- MyLibrary.h
|   | +- MyLibrary.cpp
|   +- library.properties
+- src
| +- my_project_test.cpp
+- project.properties <-- mandatory for extended project, even if blank

Compile your project with the library copy like any other project:
particle compile photon .

When the library works, you can contribute a private version of the library that only you can use.
particle library contribute
particle library upload

At this point you can add your new library to one of your projects with
particle library add my_library

When you tested the private version, go ahead and publish the library to be used by others.
particle library publish my_library

Note 1: nobody else can use a library you contributed until you publish it.
Note 2: you won’t see the new version of the library in Build until we deploy a new version with libs 2.0 support.

Go ahead and give this a whirl and let me know if something is weird.

5 Likes
2

@jvanier will we wipe away all the libraries after our beta? Or rather, how will we be able to see all the new libraries that we ported?

I would love to try out and port all libraries under my care earlier :slight_smile:

1 Like
3

Good question. I don’t plan on deleting any newly published library but of course if something goes wrong during publish let me know and I’ll remove the version.

You will be able to see the libraries you ported by using library search and use them using library add.

4

Original post updated for private libraries.

5

Faced an issue with: Library is not valid. LICENSE is missing

I think it’s better not enforce a license for compatibility reasons

6

Good point!

What are the implications of publishing without a license? What does it mean for library users?

If it’s grey and undefined/uncertain, then I feel enforcing a license is the right way forward. Although most of the libraries we have migrated don’t have a license, so if we fix it for new libraries, then we should also fix it for migrated libraries.

7

The “fix” is more like the ease of maintaining with upstream. If we introduce license, all libraries need a maintainer to constantly manage and tweak such non code differences before porting is possible.

8

@jvanier, I just tried to contribute/publish my first 2.0 lib, but got this

Library is not valid. main source is missing
main header is missing

That’s particularly surprising since the respective “ol’ school” library migrated via

particle library migrate

without issue, but the subsequent

particle library contribute

failed (when executed from the same direcory as the previous migrate command).
What have I done wrong?

BTW, once I will be able to contribute, how could I instruct CLI to build one of the embedded examples?

C:\Users\Andy\Dropbox\DokumenteAndy\Particle\ParticleSoftSerial
|   library.properties
|   LICENSE
|   project.properties
|   readme.md
|
+---examples
|   \---PSS_SimpleTest
|           PSS_SimpleTest.ino
|
\---src
    |   ParticleSoftSerial.cpp
    |   ParticleSoftSerial.h
    |
    \---ParticleSoftSerial
            ParticleSoftSerial.h

Using CLI 1.18.0-libraries.16

9

I guess this is an issue with the case of the library. The “real name” of the library is still ParticleSoftSerial but people can add the library with particlesoftserial. @mdma, we need to add a test to make sure the validate command works for mixed case library names.

10

The problem is not that people might try to pull the lib with the “wrong” case, but I can’t even push the lib with the “correct”/“real” case.
Does CLI check for a wrong main file name?
The path and the library.properties file have got the correct spelling, why would CLI change that on upload?

11

I am trying to migrate the ntpTime library to v 2.0. When I try to upload from the Particle Dev, I get:
“Library is not valid. main source is missing main header is missing”

The library is in the directory ntp-time, there is a subdirectory named src with ntp-time.h and ntp-time.c and the library.properties is:

name=ntp-time
version=0.0.2
license=MIT
author=Douglas Johnson
sentence=Keeps the Particle Time synced to NTP.
url=https://github.com/classtech/ntptime
repository=https://github.com/classtech/ntptime.git

Suggestions would be very welcome.

Thanks,
Doug

12

Right now the validation expects the library to contain one main .h and one main .cpp. Does your library still compile if you rename the .c to .cpp? If not we’ll need to change the validation logic, perhaps to make this a warning but not an error.

13

Is this your legacy repo?

I've seen another user report a similar issue with his upload

In both cases I can't see the actual problem either.

The repo already has a .cpp file in place, so I'd suppose there's another reason.

14

Yes, https://github.com/ClassTech/NtpTime is it.
Thanks,
Doug

15

I just tried again and got the same error. Any suggestions would be appreciated. I’m trying to get the library updated in time to get the Electron.
Thanks,
Doug

16

You can always use CLI (1.19.2 or later) to upload and publish, if you are pressed for time.

17

Arrrrrg. I just tried installing CLI on Windows 10 and got the following error:

Upgrade finished. Your new npm version is 4.2.0. Have a nice day!
PS C:\WINDOWS\system32> particle setup
particle: Installing plugins (retrying)…
! Error reading plugin: particle-cli
! exit status 1
! module.js:327
! throw err;
! ^
!
! Error: Cannot find module ‘particle-cli/package.json’
! at Function.Module._resolveFilename (module.js:325:15)
! at Function.Module._load (module.js:276:25)
! at Module.require (module.js:353:17)
! at require (internal/module.js:12:17)
! at [eval]:3:15
! at Object.exports.runInThisContext (vm.js:54:17)
! at Object. ([eval]-wrapper:6:22)
! at Module._compile (module.js:397:26)
! at node.js:611:27
! at nextTickCallbackWith0Args (node.js:452:9)

I’ve tried uninstalling the old CLI, updating npm, and running as administrator. Suggestions welcome.

– Doug

18

Try the CLI installer (after you uninstalled CLI again)
https://binaries.particle.io/cli/installer/windows/ParticleCLISetup.exe

1 Like
19

I was able to install the CLI on my Mac. I carefully went through the instructions to create a library:

Dougs-MacBook-Pro:NtpTime djohnson$ particle library create
? Enter a name for your library: NtpTime
? Enter a version for your library: 0.0.4
? Who is the author of your library: ClassTech
create library.properties
create README.md
create LICENSE
create src/NtpTime.cpp
create src/NtpTime.h
create examples/usage/usage.ino

I copied NtpTime.cpp, NtpTime.h to src/ and usage.ino to examples/usage from my draft library to the newly created one. I edited the library.properties, LICENSE, and README.md.

Then, following the directions, I did:

Dougs-MacBook-Pro:NtpTime djohnson$ particle library upload
Uploading library NtpTime> Library NtpTime was successfully uploaded.
Add it to your project with particle library add NtpTime

Dougs-MacBook-Pro:NtpTime djohnson$ particle library publish
This library could not be published. Try another library or try this one again later.

It has given me this unhelpful message multiple times.

The library structure is:

Dougs-MacBook-Pro:NtpTime djohnson$ ls -lR
total 24
-rw-r–r--@ 1 djohnson staff 1297 Feb 13 14:00 LICENSE
-rw-r–r-- 1 djohnson staff 2461 Feb 13 14:19 README.md
drwxr-xr-x 4 djohnson staff 136 Feb 13 15:25 examples
-rw-r–r-- 1 djohnson staff 839 Feb 13 14:59 library.properties
drwxr-xr-x 4 djohnson staff 136 Feb 13 13:57 src

./examples:
total 0
drwxr-xr-x 3 djohnson staff 102 Feb 13 15:25 usage

./examples/usage:
total 8
-rwx------ 1 djohnson staff 554 Feb 13 14:49 usage.ino

./src:
total 24
-rwx------ 1 djohnson staff 6164 Feb 13 13:55 NtpTime.cpp
-rwx------ 1 djohnson staff 1698 Jan 13 14:40 NtpTime.h

Sigh. I’ve got to be doing something wrong. What?

Thanks,
Doug

20

Yup, that's an issue that should be fixed in next release.
Currently you need to cd .. out of the library folder and do particle library publish <libPath> (<libPath> should be equal to <libName>).