From e5780e602eea748ee8b2213263593eab5c5af228 Mon Sep 17 00:00:00 2001 From: Alexandre Archambault Date: Fri, 27 Nov 2015 01:21:07 +0100 Subject: [PATCH] Rework README --- README.md | 146 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 137 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index b9bb21260..381a7001d 100644 --- a/README.md +++ b/README.md @@ -8,21 +8,149 @@ A pure Scala substitute for [Aether](http://www.eclipse.org/aether/) [![Build status (Windows)](https://ci.appveyor.com/api/projects/status/trtum5b7washfbj9?svg=true)](https://ci.appveyor.com/project/alexarchambault/coursier) [![Join the chat at https://gitter.im/alexarchambault/coursier](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/alexarchambault/coursier?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) -See [Scala JS demo](https://alexarchambault.github.io/coursier/index.html#demo) and [usage](https://github.com/alexarchambault/coursier/blob/master/USAGE.md). +*coursier* is a dependency resolver / fetcher *à la* Maven / Ivy, entirely +rewritten from scratch in Scala. It aims at being fast and easy to embed +in other contexts. Its very core (`core` module) aims at being +extremely pure, and should be approached with a mathsy / algebraic mindset. -Both a JVM library and a Scala JS one. +The `files` module handles caching of the metadata and artifacts themselves, +and is less so pure than the `core` module, in the sense that it happily +does IO as a side-effect (although it naturally favors immutability for all +that's kept in memory). -Work in progress: -* full list of dependencies / version conflict resolution working, mildly to well tested, -* downloading/caching of JARs in its early stages. - -Handles fancy Maven features like +It handles fancy Maven features like * [POM inheritance](http://books.sonatype.com/mvnref-book/reference/pom-relationships-sect-project-relationships.html#pom-relationships-sect-project-inheritance), * [dependency management](http://books.sonatype.com/mvnex-book/reference/optimizing-sect-dependencies.html), * [import scope](https://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html#Importing_Dependencies), -* [properties](http://books.sonatype.com/mvnref-book/reference/resource-filtering-sect-properties.html). +* [properties](http://books.sonatype.com/mvnref-book/reference/resource-filtering-sect-properties.html), +* etc., +It happily resolves dependencies involving modules from the Hadoop ecosystem (Spark, Flink, etc.), that +make a heavy use of these. -Restricted to Maven resolution and repositories for now. Support for Ivy seems at reach. +It can be used either from the command-line, via its API, or from the browser. + +## Command-line + +Download and run it with +``` +$ curl -L -o coursier https://git.io/vBkT9; chmod +x coursier; ./coursier --help +``` + +The first time it is run, it will download the artifacts required to launch +coursier. You'll be fine the next times :-). + +``` +$ ./coursier --help +``` +lists the available coursier commands. The most notable ones are `launch`, +`fetch`, and `classpath`. Type +``` +$ ./coursier command --help +``` +to get a description of the various options the command `command` (replace with one +of the above command) accepts. + +### launch + +The `launch` command fetches a set of Maven coordinates it is given, along +with their transitive dependencies, then launches the "main `main` class" from +it if it can find one (typically from the manifest of the first coordinates). +The main class to launch can also be manually specified with the `-M` option. + +For example, it can launch: + +* [Ammonite](https://github.com/lihaoyi/Ammonite) (enhanced Scala REPL), +``` +$ ./coursier launch com.lihaoyi:ammonite-repl_2.11.7:0.5.0 +``` + +* the REPLs of various JVM languages like +** Frege, +``` +$ ./coursier launch -r central -r https://oss.sonatype.org/content/groups/public org.frege-lang:frege-repl-core:1.3 -M frege.repl.FregeRepl +``` +** clojure, +``` +$ ./coursier launch org.clojure:clojure:1.7.0 -M clojure.main +``` +** jruby, +``` +$ wget https://raw.githubusercontent.com/jruby/jruby/master/bin/jirb && \ + ./coursier launch org.jruby:jruby:9.0.4.0 -M org.jruby.Main -- -- jirb +``` +** jython, +``` +$ ./coursier launch org.python:jython-standalone:2.7.0 -M org.python.util.jython +``` +** Groovy, +``` +$ ./coursier launch org.codehaus.groovy:groovy-groovysh:2.4.5 -M org.codehaus.groovy.tools.shell.Main commons-cli:commons-cli:1.3.1 +``` +etc. + +* various programs, like Proguard, or its utility, Retrace, +``` +$ ./coursier launch net.sf.proguard:proguard-base:5.2.1 -M proguard.ProGuard +$ ./coursier launch net.sf.proguard:proguard-retrace:5.2.1 -M proguard.retrace.ReTrace +``` + +### fetch + +The `fetch` command simply fetches a set of dependencies, along with their +transitive dependencies, then prints the local paths of all their artefacts. + +Example +``` +$ ./coursier fetch org.apache.spark:spark-sql_2.11:1.5.2 +... +``` + +### classpath + +The `classpath` command transitively fetches a set of dependencies like +`fetch` does, then prints a classpath that can be handed over directly +to `java`, like +``` +$ java -cp "$(./coursier classpath com.lihaoyi:ammonite-repl_2.11.7:0.5.0 | tail -n1)" ammonite.repl.Repl +Loading... +Welcome to the Ammonite Repl 0.5.0 +(Scala 2.11.7 Java 1.8.0_60) +@ +``` + +## API + +This @larsrh [gist](ammonite.repl.Repl) illustrates how the API of coursier can be used to get transitives dependencies +and fetch the corresponding artefacts + +More explanations to come :-) + +## Scala JS demo + +*coursier* is also compiled to Scala JS, and can be tested in the browser via its +[demo](http://alexarchambault.github.io/coursier/#demo). + +# To do / missing + +- Snapshots metadata / artifacts, once in cache, are not automatically +updated for now. [#41](https://github.com/alexarchambault/coursier/issues/41) +- File locking could be better (none for metadata, no re-attempt if file locked elsewhere for artifacts) [#71](https://github.com/alexarchambault/coursier/issues/71) +- Handle "configurations" like Ivy does, instead of just the standard +(hard-coded) Maven "scopes" [#8](https://github.com/alexarchambault/coursier/issues/8) +- SBT plugin [#52](https://github.com/alexarchambault/coursier/issues/52), +requires Ivy-like configurations [#8](https://github.com/alexarchambault/coursier/issues/8) + +# Contributors + +- Your name here :-) + +# Projects using coursier + +- @larsrh's [libisabelle](https://github.com/larsrh/libisabelle) fetches +some of its requirements via coursier, +- [jupyter-scala](https://github.com/alexarchambault/jupyter-scala) should soon allow +to add dependencies in its sessions with coursier (initial motivation for writing coursier), +- Your project here :-) Released under the Apache license, v2.