The best of two worlds
ls assumes two things about your library
- 1) Its source is opensource and hosted on Github
- 2) You build your projects with sbt*
* 2 is not required, but highly recommended.
ls learns about your library through a process called
lsyncing, which synchronizes
ls with build information hosted on Github. Because only privileged parties may commit to these repositories,
ls is not concerned with who is requesting an
lsync—that is, authentication—but with the controlled project metadata on Github.
lsync syncs library versions
So what are you actually publishing? Information.
ls stores semi-structured information about each published version of your library's build in a json encoded file within your repository source tree. It is encouraged to only
lsync build info about released versions.
The following is a description of the format that
ls uses to capture version snapshots of library information.
# a maven/ivy organization identifier
# name of your library
# version of your library
# quaint description of what it provides
"description":"Hot stuff comin' through",
# a uri for more info & resources
# keywords to help others to find your library
"tags": ["awesome", "opossum"],
# a uri for version-specific api docs
# licenses if you care for them
# where can your library be downloaded from
# what does your library depend on
# scala cross-binary dialects
# is this an sbt plugin?
To perform an
lsync for a given project, simply perform the following HTTP
curl -X POST http://ls.implicit.ly/api/1/libraries \
This will tell
to extract any files in the
repository for files matching
and store the library's metadata.
No wants you to hand copy that for every library you write. That's what plugins are for!
Say hello to ls-sbt
To install a convenient
ls client, install the following conscript locally
$ cs softprops/ls
Then in the root of your project run
ls-sbt plugin installed to your project, you can generate version info automatically from its sbt build.
A few customization settings you may want so set are
(LsKeys.tags in LsKeys.lsync) := Seq("futures", "async-awesome")
(externalResolvers in LsKeys.lsync) := Seq(
"my own resolver" at "http://repo.myhost.io")
(description in LsKeys.lsync) :=
"One futures library to rule them all."
You can easily generate the json file mentioned above with the following task.
Add or edit the generated file under
src/main/ls/:version.json to fit your liking before commiting to git and pushing to your Github remote.
When you are ready to sync your library's build info with
ls, do the following
That's it! Feel free to go ahead and start banging out the next awesome version of your library now.
A note on sbt plugins
Authors of sbt plugins may
lsync their library information with
ls for others to find their plugins but
ls-try do not currently support installing plugins. This will probably change soon.
There are lot of scala libraries out there, waiting to make your life easier.
ls aims to make finding Scala libraries as simple as it possibly can be by adding some vocabulary to your sbt shell.
To find a library by name use
sbt> ls -n unfiltered
This command will find any ls-published library named
unfiltered, listing recent versions with descriptions
What if you are looking for a specific version? Just add
@version to your query
sbt> ls -n email@example.com
What if you don't know the name of the library you are looking for? Try searcing by tags and see what pops up.
sbt> ls web netty
Tags help categorize libraries and make them easier for users to find.
ls provides a task for launching a library's docs in your browser
sbt> ls-docs firstname.lastname@example.org
The task above will fetch the docs for unfiltered at version 0.5.2 and open them in a browser. You can also use this command without specifying the library version and
ls will automatically choose the latest version of the library's docs. Library authors are encouraged to bind
(LsKeys.docsUrl in LsKeys.lsync) to the library's generated scala docs. If that is not available
ls-docs will fallback on
(homepage in LsKeys.lsync) and finally the Github repository page for the project if neither of those are available.
Once you find the library you are looking for, you have a few options. You can hand edit a configuration file, paste in the info you had to previous search for or you could do
sbt> ls-try unfiltered
This will temporarily add the latest version of unfiltered to your library dependency chain. Try typing
console-quick to play with the library in the repl. If you don't like it, you can always remove it with the sbt built-in command
session clear or by reloading your project. If a library fits your need, it's just as easy to install it.
sbt> ls-install unfiltered
The same syntax for specifying a specific version applies
sbt> ls-install email@example.com
Because of the open nature of Github, a forked repository easily can coexist with another of the same name under a different user's account. Libraries in
ls are just references to
uris. More specifically a uri for Github repository, a library name, and version.
sbt> ls -n firstname.lastname@example.org user/repo
install will always use the latest version of a library by name using an inferred uri.
It is not recommended to
lsync version information across repos. Doing so may decrease the likelihood of your users finding the right version of the library. In the case a library author has lsync'd across repositories, ls will prompt you for the repo you wish to use.