Building examples for a library within the same sbt project

[Iain McGinniss]

I am currently porting a library from OCaml to Scala, and as part of this effort I want to be able to provide a set of code examples of how to use the library. I would obviously like to ensure that examples do in fact compile, and can be packaged in a way that makes them easy to run. There would seem to be two ways to do this:

1. Package up the examples in a separate sbt project, which depends on the library project.

2. Introduce some new "examples" phase which compiles source in src/examples against the main source after compile and test have succeeded, and produces a separate JAR for these compiled sources. In particular, I do not want the compiled examples to be included in the main library artifact.

I'm probably going to do option 1 for expediency, but I was wondering if anyone knows how to configure SBT to do the latter, or if an SBT plugin exists for this purpose?

Thanks,

Iain McGinniss

[Tony Sloane]

Hi Iain,

We use a form of option 2 in the Kiama project (http://kiama.googlecode.com). Our view is that the extended examples are part of our test suite. Thus, they are in the main Kiama project and we have the project configured so that the example files are seen to be tests by sbt.

You can find the full sbt configuration on the Kiama google code site, but the most relevant details follow. Note that we don't use the default Maven-style directory layout. All of our sources are under "src" and the tests are located in the directory hierarchy with the code that they test.

scalaSource <<= baseDirectory { _ / "src" }

unmanagedSources in Test <<= scalaSource map { s => {

    val egs = s / "org" / "kiama" / "example" ** "*.scala"

    ((s ** "*Tests.scala") +++ egs).get

}}

unmanagedSources in Compile <<= (scalaSource, unmanagedSources in Test) map { (s, tests) =>

    ((s ** "*.scala") --- tests).get

}

The effect of this configuration is that a .scala file is regarded as a test source if it is in the src/org/kiama/example directory or if it is elsewhere and its filename ends with Tests.scala. All other .scala files are part of the library proper.

Thus the main Kiama jar just includes the library stuff and the test jar includes all tests, including the examples. We don't need any new processing phases since the normal sbt test commands will do the trick. E.g., test runs all of the tests including those in the examples. test:package makes the test jar. Similarly, normal sbt publishing will publish the test jar alongside the library jar.

Overall, this setup seems to work pretty well for us and I think is simpler to deal with than having a separate project for the examples.

cheers,

Tony

[nafg]

You may want to see how Slick (github.com/slick/slick) uses Sphinx for this. Also check out dexy.

[Iain McGinniss]

Hi Tony,

Thanks for the info. I have been viewing the examples as a form of integration tests I guess, though I had not necessarily wanted to use a testing framework to write them. However I suppose as long as it is clear from these tests how the library is intended to be used, then it does not matter was wrapping infrastructure is required.

I also see that there is a way to add an "integration tests" phase that is quite well documented on the xsbt wiki:

https://github.com/harrah/xsbt/wiki/Testing

This seems like a reasonable compromise for me, as it will keep the examples / integration tests separate from the functional tests.

Cheers,

Iain

P.S: Excellent work on kiama by the way, I am using it for my thesis implementation work just now.

[Tony Sloane]

Hi Iain,

No problem. The integration test route seems like a reasonable one too.

Glad you like Kiama. One day if you have time, please drop me a line and tell me what you're using it for. We're also interested to hear about pain points if you have any.

cheers,

Tony

--
You received this message because you are subscribed to the Google Groups "simple-build-tool" group.
To view this discussion on the web visit https://groups.google.com/d/msg/simple-build-tool/-/NB-B7U5KjlQJ.
To post to this group, send email to simple-b...@googlegroups.com.
To unsubscribe from this group, send email to simple-build-t...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/simple-build-tool?hl=en.