ls / pamflet

on Github with contributions from

publishing

The best of two worlds

ls assumes two things about your library

* 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
 "organization":"org.yourdomain",
 # name of your library
 "name":"my-awesome-library",
 # version of your library
 "version":"1.0",
 # quaint description of what it provides
 "description":"Hot stuff comin' through",
 # a uri for more info & resources
 "site":"http://yourdomain.org/awesome-library-overview",
 # keywords to help others to find your library
 "tags": ["awesome", "opossum"],
 # a uri for version-specific api docs
 "docs":"http://yourdomain.org/awesome-library-docs",
 # licenses if you care for them
 "licenses": [{
   "name": "MIT",
   "url":"https://yourdomain.org/awesome-library/LICENSE"
  }],
 # where can your library be downloaded from
 "resolvers": ["http://repo.yourdomain.org/"],
 # what does your library depend on
 "dependencies": [{
   "organization":"org.otherdomain",
   "name": "my-awesome-dependency",
   "version": "0.1.0"
  }],
 # scala cross-binary dialects
 "scalas": [
   "2.8.0","2.8.1","2.8.2",
   "2.9.0","2.9.0-1","2.9.1"
  ],
 # is this an sbt plugin?
 "sbt": false
}

To perform an lsync for a given project, simply perform the following HTTP POST

curl -X POST http://ls.implicit.ly/api/1/libraries \
  -d 'user=your-gh-user&repo=your-gh-repo&version=version-to-sync'
This will tell ls to extract any files in the github.com/your-gh-user/your-gh-repo repository for files matching src/main/ls/version-to-sync.json 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

$ lsinit

With the 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

seq(lsSettings:_*)

(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.

sbt> ls-write-version

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

sbt> lsync

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-install and ls-try do not currently support installing plugins. This will probably change soon.

Thumbing through

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 ls -n

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 unfiltered@0.5.1

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.

For convenience, ls provides a task for launching a library's docs in your browser

sbt> ls-docs unfiltered@0.5.2

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.

Checking the fit

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 unfiltered@0.5.1

You or I

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 library@0.5.0 user/repo

By default, try and 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.

Issues

ls makes a handful of assumptions about your libraries and build environments. It's quite possible some of these assumptions are flawed. If you find one, let me know.