From 3e355784a77b2ff094f798174a399b12664debd0 Mon Sep 17 00:00:00 2001 From: Tobias Johansson Date: Mon, 7 Mar 2016 19:17:51 +0100 Subject: Format README as markdown --- README.md | 134 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 134 insertions(+) create mode 100644 README.md (limited to 'README.md') diff --git a/README.md b/README.md new file mode 100644 index 0000000..c900182 --- /dev/null +++ b/README.md @@ -0,0 +1,134 @@ +Join the chat at https://gitter.im/cvogt/cbt + +Welcome to Chris' Build Tool (CBT) for Scala +============================================ + +Fun, fast, intuitive, composable and statically checked builds written in Scala. + +Currently CBT has been tested in OSX only. Adding support for Unix and Windows +should not be hard. Please contribute back if you mange :). + +CBT supports the basic needs for Scala builds right now. +Composing, compiling, running, testing, packaging, publishing. +Tasks outside of these, such as building manuals will require +easy custom code. If you integrate something, consider +doing it as traits that you make available as a library that +other builds can depend on and mix in. + +Slides from CBT talk from NEScala 2016: +https://github.com/cvogt/talks/raw/master/2016-03-04_NEScala-2016_A-Vision-For-Scala-Builds.pdf +(video coming soon...) + +Getting started +--------------- + +### Dependencies +You currently need javac, nailgun, gpg and realpath or gcc installed. + +### Installing +CBT bootstraps from source. To install, just clone the repository. + +### Using +To use, just call the `cbt` bash script. You will see CBT first +building up itself, then trying to start your build. + +The easiest CBT build requires no script. It compiles source files from the +current directory and from `src/` into the target folder. Try calling `cbt compile`. +If you have a class called Main with a main method, try `cbt run`. +Put a source file with a Main class into `test/` in order for +`cbt test` to run it. It will see your main code. + +If you need more than this, like dependencies, create a scala file in `build/` +that describes your build. Here is an example + +```scala +// build/build.scala +import cbt._ +class Build(context: cbt.Context) extends PackageBuild(context){ + override def version = "0.6.1-SNAPSHOT" + override def groupId = "org.cvogt" + override def artifactId = "play-json-extensions" + override def dependencies = super.dependencies ++ Vector( + "com.typesafe.play" %% "play-json" % "2.4.4" + ) + override def compile = { + println("Compiling...") + super.compile + } + def foo = "Hello World" +} +``` + +Now you can call methods of this class through cbt. Try `cbt foo`. +You can see how your build is configured via overrides. + +call `cbt` to see a full list of available commands for this build. + +Look into the class `DefaultBuild` in CBT's source code to see their +details. The source code is really simple. Don't shy away from +looking, even as a beginner. No crazy stuff, I promise ;). You +can find the relevant code in CBT's `stage2/DefaultBuild.scala` + +I order to keep executing the same command triggered by file changes use `cbt loop `. + +You can find example builds in CBT's own `test/` folder. +Not all of them have a build file, in which case CBT uses the default +`cbt.DefaultBuild`. + +A folder `build/` can have its own folder `build/` inside in order +to add source or maven dependencies to your build. Eventually +you'll be able to also choose the CBT and Scala versions for +target builds. Make sure you extend cbt.BuilBuild instead of +cbt.Build, in order to automatically trigger building of the +target build. + +cbt is fast. It uses Nailgun to keep the JVM hot. It uses the Java +WatchService (respectively a fast OSX port of it) for instant triggering +re-compilation on file changes. Use `cbt loop compile`. + +CBT concepts +------------ + +There two essential primitives available in build scripts for composing +modular projects: + + 1. Dynamically compiling and loading Build scripts in other + directories and calling methods (aka tasks) on them to compile, + get the classpath, ask for version numbers, etc. + + This allows to do a lot of things just like that: + Multi-project builds, source dependencies, builds of builds and + allowing tests simply as dependent projects of the main project, etc. + + 2. Maven dependencies + + I wrote my own 50 LOC Maven resolver. It's super quick and I have + yet see it not to being able to handle something. I know cases + exist, but seem rare. + alexarchambault's Coursier can be used as a more complete drop-in. + +Build scripts also have access to a small unsurprising library for +- triggering dependencies to build / download and get the classpath +- compiling Java / Scala code using zinc with given class paths +- running code +- packaging jars +- signing / publishing to sonatype/maven + +Missing features in comparison with SBT +--------------------------------------- + +Not implemented yet, but rather easily possible without API changes or +major refactors is concurrently building / downloading dependencies and +running tests. Right now it is sequential. + +CBT allows tasks to lazily depend on other tasks. +SBT currently does not, because it uses an Applicative, not a Monad, so +task dependencies are eager. + +Another edge case that may need a solution is dynamically overwriting +tasks. SBT allows that. Classes and traits are static. The only use +cases I know are debugging, cross builds and the sbt release plugin. A +solution could be code generating traits at build-time and mixing them +in ad-hoc. It's a build-tool after all. Build-time code-generation and +class loading is not rocket science. But there may be simpler solutions +for the cases at hand. And they are edge cases anyways. -- cgit v1.2.3