This is where the code for the Ammonite project lives; Both:
- Ammonite-REPL, the improved Scala REPL
- Ammonite-Ops, the Scala file-system library
- Ammonite-Shell, the Bash-replacement system shell
If you want to learn more about Ammonite or how to use it, check out the links above, or ask on the Gitter Channel. The remainder of this document is developer-docs for people who want to work on the Ammonite source code itself.
The layout of the repository is roughly:
ops/
is Ammonite-Opsrepl/
is Ammonite-REPLshell/
is Ammonite-Shellterminal/
is the JLine re-implementation used by Ammonite-REPL to provide syntax highlighting and multiline editingreadme/
is the source code for the Documentation, written in Scalatex.modules/
is a synthetic project used for publishing, purely intended to exclude the readme
Although most features should be unit tested, it's still useful to fire up a REPL from the current codebase to see things work (or not). There are a variety of shells you can spin up for testing different things:
sbt ~terminal/test:run
is useful for manual testing the terminal interaction; it basically contains a minimal echo-anything terminal, with multiline input based on the count of open- and closed-parentheses. This lets you test all terminal interactions without all the complexity of the Scala compiler, classloaders, etc. that comes inrepl/
sbt ~repl/test:run
brings up the Ammonite-REPL using the source code in the repository, and automatically restarts it on-exit if you have made a change to the code. Useful for manual testing both ofrepl/
as well asops/
, since you can justimport ammonite.ops._
and start using them. Note that this does not bring in filesystem utilities like thewd
variable,cd!
command.sbt ~shell/test:run
brings up a fully-loaded shell with all filesystem utilities included:wd
,cd!
, autocomplete for filesystem paths, and more. This usesreadme/resources/example-predef.scala
instead of your default predef, for easier experimentation and development.sbt ~integration/test:run
runs the trivial main method in theintegration
subproject, letting you manually test running Ammonite programmatically, whether throughrun
ordebug
sbt ~integration/test:console
brings up a console in theintegration
subproject, loading Ammonite-REPL as a test console, as described in the readme. Similar tointegration/test:run
but useful for verifying the different classloader/execution environment we get by starting Ammonite inside the Scala REPL doesn't break things
While working on a arbitrary xyz
subproject, sbt ~xyz/test
runs tests after every change. repl/test
can be a bit slow because of the amount of code it compiles, so you may want to specify the test manually via repl/test-only -- ammonite.repl.TestObject.path.to.test
.
ops/test
tests the filesystem operations, without any REPL presentrepl/test
tests the Ammonite-REPL, without filesystem-shell integration.terminal/test
tests the readline re-implementation: keyboard navigation, shortcuts, editing, without any filesystem/scala-repl logicshell/test
tests the integration between the standaloneops/
andrepl/
projects: features likecd!
/wd
, path-completion, ops-related pretty-printing and toolsintegration/test
kicks off the integration tests, which bundlerepl/
andshell/
into their respective jars and invoke them as subprocesses. Somewhat slow, but exercises all the command-line-parsing stuff that the other unit tests do not exercise, and makes sure that everything works when run from.jar
s instead of loose class-files
sbt repl/assembly ++2.10.5 repl/assembly
to bundle the REPL as a standalone distributionsbt +modules/publishLocal
or+sbt modules/publishSigned
is used for publishing.sbt ~readme/run
builds the documentation inside its target folder, which you can view by openingreadme/target/scalatex/index.html
in your browser.git checkout gh-pages && cp -r readme/target/scalatex/* . && git commit -am . && git push
will deploy the generated documentation to Github Pages
I've started tagging open issues in the issue tracker to try and keep things neat. This is what the various tags mean:
Each issue should only have one of these:
bug
: this behavior clearly wrong, and needs to be fixedenhancement
: something relatively speccable, that can be worked on, finished, and will make Ammonite betterwishlist
: could be totally awesome, but we're uncertain if it is worth doing at all, what it would look like, or if it will ever reach a "finished" state.
And possibly:
help wanted
: I don't have context, hardware, or for some other reason am unlikely to ever do this. But I know people out there care, so one of you should step up and fix it.
- All code PRs should come with: a meaningful description, inline-comments for important things, unit tests (positive and negative), and a green build in CI
- Try to keep lines below 80 characters width, with a hard limit of 100 characters.
- PRs for features should generally come with something added to the Documentation, so people can discover that it exists
- Be prepared to discuss/argue-for your changes if you want them merged! You will probably need to refactor so your changes fit into the larger codebase
- If your code is hard to unit test, and you don't want to unit test it, that's ok. But be prepared to argue why that's the case!
- It's entirely possible your changes won't be merged, or will get ripped out later. This is also the case for my changes, as the Author!
- Even a rejected/reverted PR is valuable! It helps explore the solution space, and know what works and what doesn't. For every line in the repo, at least three lines were tried, committed, and reverted/refactored, and more than 10 were tried without committing.
- Feel free to send Proof-Of-Concept PRs that you don't intend to get merged.