Quick Start Guide¶
Document built: Oct 13, 2023
Java 8 or newer
LLVM/Clang 15 or newer
Project Structure Overview¶
Most projects in ScalaNative cross-build against Scala
3, and these projects have a suffix like
3 to differentiate the Scala version.
In the following we will use suffix
3, but remember that you can build and test for different versions using different suffixes.
Build / Manual Testing on Sandbox¶
sandbox3/run to compile, link and run the main method of the sandbox project defined in
It’s convenient to run the
sandbox project to verify the build works as expected.
Common Test Commands
tests3/test- run the unit tests for libraries on native build
tests3/testOnly org.scalanative.testsuite.javalib.util.RandomTest- run only the test of interest
tests3/testOnly *.RandomTest- run only the test of interest using wildcard
testsExt3/test- run the unit tests on native build, this module contains tests that requires dummy javalib implementation defined in
nirJVM3/test- run the unit tests for NIR
toolsJVM3/test- run the unit tests of the tools: ScalaNative backend
sbtScalaNative/scripted- run all scripted tests of the sbt plugin (this takes a while).
sbtScalaNative/scripted <test directory to run>- run specific scripted tests of the sbt plugin. e.g.
Scripted tests are used when you need to interact with the file system, networking, or the build system that cannot be done with a unit test.
set ThisBuild / scriptedBufferLog := falsedisables buffer log in scripted test and get more verbose output
Other Test Commands
test-all- run all tests, ideally after
Some additional tips
If you modify the
nscplugin, you will need to
cleanthe project that you want to rebuild with its new version (typically
tests/clean). For a full rebuild, use the global
If you modify the sbt plugin or any of its transitive dependencies (
test-runner), you will need to
reloadfor your changes to take effect with most test commands (except with the
For a completely clean build, from scratch, run
./scripts/scalafmt- format all Scala codes
./scripts/clangfmt- format all C/C++ codes
publish-local-dev x.y.z publishes the ScalaNative artifact and sbt plugin for specified scala version locally.
You will see, the log message like the following, which means you have successfully published locally for the version
[info] published tools_native0.5.0-SNAPSHOT_3 to ...
[info] published ivy to ...tools_native0.5.0-SNAPSHOT_3/0.5.0-SNAPSHOT/ivys/ivy.xml
Then you’ll be able to use locally published version in other projects.
addSbtPlugin("org.scala-native" % "sbt-scala-native" % "0.5.0-SNAPSHOT")
scalaVersion := "3.3.1" # set to locally published version
Locally build docs¶
First time building the docs. This command will setup & build the docs.
$ bash scripts/makedocs setup
If setup is already done. This command will only build the docs assuming setup is already done.
$ bash scripts/makedocs
docs/_build/htmldirectory and open
index.htmlfile in your browser.
Configure Native Build¶
To configure the native build in this project, you can edit
project/MyScalaNativePlugin.scala instead of
MyScalaNativePlugin is a custom sbt plugin that extends
ScalaNativePlugin and overrides some of its settings for this project.