Scala Native Documentation Release 0.1 Denys Shabalin Mar 14, 2017 Contents 1 Community 3 2 Documentation 5 2.1 User’s Guide...............................................5 2.2 Libraries................................................. 12 2.3 Contributor’s Guide........................................... 21 2.4 FAQ.................................................... 37 i ii Scala Native Documentation, Release 0.1 Scala Native is an optimizing ahead-of-time compiler and lightweight managed runtime designed specifically for Scala. It features: • Low-level primitives. type Vec = CStruct3[Double, Double, Double] val vec = stackalloc[Vec] // allocate c struct on stack !vec._1 = 10.0 // initialize fields !vec._2 = 20.0 !vec._3 = 30.0 length(vec) // pass by reference Pointers, structs, you name it. Low-level primitives let you hand-tune your application to make it work exactly as you want it to. You’re in control. • Seamless interop with native code. @extern object stdlib { def malloc(size: CSize): Ptr[Byte] = extern } val ptr = stdlib.malloc(32) Calling C code has never been easier. With the help of extern objects you can seamlessly call native code without any runtime overhead. • Instant startup time. > time hello-native hello, native! real 0m0.005s user 0m0.002s sys 0m0.002s Scala Native is compiled ahead-of-time via LLVM. This means that there is no sluggish warm-up phase that’s common for just-in-time compilers. Your code is immediately fast and ready for action. Contents 1 Scala Native Documentation, Release 0.1 2 Contents CHAPTER 1 Community • Want to follow project updates? Follow us on twitter. • Want to chat? Join our Gitter chat channel. • Have a question? Ask it on Stack Overflow with tag scala-native. • Found a bug or want to propose a new feature? Open an issue on Github. 3 Scala Native Documentation, Release 0.1 4 Chapter 1. Community CHAPTER 2 Documentation This documentation is divided into different parts. It’s recommended to go through the User’s Guide to get familiar with Scala Native. Libraries will walk you through all the known libraries that are currently available. Contributor’s Guide contains valuable information for people who want to eithercontribute to the project or learn more about the internals and the development process behind the project. User’s Guide Environment setup This is what you will be doing, in a nutshell: • installation of SBT • installation of LLVM and Clang • installation of Boehm GC Installing SBT Please refer to this link for instructions for your OS. Installing LLVM, Clang and Boehm GC Boehm GC and LLVM (that includes Clang) are Scala Native’s only external dependencies. Here are install instruc- tions for a number of operating systems Scala Native has been used with: Ubuntu: $ sudo apt-get install clang libgc-dev libunwind-dev macOS: 5 Scala Native Documentation, Release 0.1 $ brew install llvm bdw-gc FreeBSD: $ pkg install llvm38 boehm-gc libunwind nix/nixOS: $ wget https://raw.githubusercontent.com/scala-native/scala-native/master/bin/scala- ,!native.nix $ nix-shell scala-native.nix -A clangEnv Continue to Building projects with SBT. Building projects with SBT If you have reached this section you probably have a system that is now able to compile and run Scala Native programs. Minimal sbt project Start within a new folder, and create a file project/plugins.sbt as follows: addSbtPlugin("org.scala-native"%"sbt-scala-native"%"0.1.0") Create a file project/build.properties to define the sbt version as follows: sbt.version= 0.13.13 define a new build.sbt: enablePlugins(ScalaNativePlugin) scalaVersion :="2.11.8" and now you can write your first application in ./src/main/scala/HelloWorld.scala: package example object Main { def main(args: Array[String]): Unit= println("Hello, world!") } now simply run sbt run to get everything compiled and have the expected output! Sbt settings Name Type Description nativeClang File Path to clang command nativeClangPP File Path to clang++ command nativeCompileOptions Seq[String] Extra options passed to clang verbatim nativeMode String Either "debug" or "release" (1) See Compilation modes for details. 6 Chapter 2. Documentation Scala Native Documentation, Release 0.1 Sbt tasks Name Description compile Compile Scala code to NIR nativeLink Link NIR and generate native binary run Compile, link and run the generated binary package Similar to standard package with addition of NIR publish Similar to standard publish with addition of NIR (1) See Publishing for details. Compilation modes Scala Native supports two distinct linking modes: 1. debug. Default mode. Optimized for shortest compilation time. Runs fewer optimizations and is much more suited for iterative development workflow. Similar to clang’s -O0. 2. release. Optimized for best runtime performance at expense of longer compilation time. Similar to clang’s -O2 with addition of link-time optimisation over the whole application code. Publishing Scala Native supports sbt’s standard workflow for the package distribution: 1. Compile your code. 2. Generate a jar with all of the classfiles and NIR files. 3. Publish the jar to sonatype, bintray or any other 3rd party hosting service. Once the jar has been published, it can be resolved through sbt’s standard package resolution system. Cross compilation between JS, JVM and Native We created sbt-crossproject to be a drop-in replacement of Scala.js’ crossProject. Please refer to its documentation in the README. Continue to Language semantics. Language semantics In general, the semantics of the Scala Native language are the same as Scala on the JVM. However, a few differences exist, which we mention here. Interop extensions Annotations and types defined scala.scalanative.native may modify semantics of the language for sake of interoperability with C libraries, read more about those in Native code interoperability section. 2.1. User’s Guide 7 Scala Native Documentation, Release 0.1 Multithreading Scala Native doesn’t yet provide libraries for parallel multi-threaded programming and assumes single-threaded exe- cution by default. It’s possible to use C libraries to get access to multi-threading and synchronization primitives but this is not officially supported at the moment. Undefined behavior A number of error conditions which are well-defined on JVM are undefined behavior: 1. Dereferencing null. 2. Division by zero. 3. Stack overflows. Those typically crash application with a segfault on the supported architectures. Continue to Native code interoperability. Native code interoperability Scala Native provides an interop layer that makes it easy to interact with foreign native code. This includes C and other languages that can expose APIs via C ABI (e.g. C++, D, Rust etc.) All of the interop APIs discussed here are defined in scala.scalanative.native package. For brevity, we’re going to refer to that namespace as just native. Extern objects Extern objects are simple wrapper objects that demarcate scopes where methods are treated as their native C ABI- friendly counterparts. They are roughly analogous to header files with top-level function declarations in C. For example to call C’s malloc one might declare it as following: @native.extern object libc { def malloc(size: native.CSize): native.Ptr[Byte] = native.extern } native.extern on the right hand side of the method definition signifies that the body of the method is defined elsewhere in a native library that is available on the library path (see Linking with native libraries.) Signature of the extern function must match the signature of the original C function (see Finding the right signature.) Finding the right signature To find a correct signature for a given C function one must provide an equivalent Scala type for each of the arguments: 8 Chapter 2. Documentation Scala Native Documentation, Release 0.1 C Type Scala Type void Unit bool native.CBool char, signed char native.CChar unsigned char native.CUnsignedChar (1) short native.CShort unsigned short native.CUnsignedShort (1) int native.CInt unsigned int native.CUnsignedInt (1) long native.CLong unsigned long native.CUnsignedLong (1) long long native.CLongLong unsigned long long native.CUnsignedLongLong (1) size_t native.CSize wchar_t native.CWideChar char16_t native.CChar16 char32_t native.CChar32 float native.CFloat double native.CDouble void* native.Ptr[Byte] (2) int* native.Ptr[native.CInt] (2) char* native.CString (2) (3) int (*)(int) native.CFunctionPtr1[native.CInt, native.CInt] (2) (4) struct { int x, y; }* native.Ptr[native.CStruct2[native.CInt, native.CInt]] (2) (5) struct { int x, y; } Not supported 1. See Unsigned integer types. 2. See Pointer types. 3. See Byte strings. 4. See ‘Function pointers‘_. 5. See Memory layout types. Linking with native libraries In C/C++ one has to typically pass an additional -l mylib flag to dynamically link with a library. In Scala Native one can annotate libraries to link with using @native.link annotation: @native.link("mylib") @native.extern object mylib { ... } Whenever any of the members of mylib object are reachable, the Scala Native linker will automatically link with the corresponding native library. Variadic functions One can declare variadic functions like printf using native.CVararg auxiliary type: 2.1. User’s Guide 9 Scala Native Documentation, Release 0.1 @native.extern object stdio { def printf(format: native.CString, args: native.CVararg*): native.CInt = native.extern } Pointer types Scala Native provides a built-in equivalent of C’s pointers via native.Ptr[T] data type. Under the hood pointers are implemented using unmanaged machine pointers. Operations on pointers are closely related to their C counterparts and are compiled into equivalent machine code: Operation C syntax Scala Syntax Load value *ptr !ptr Store value *ptr = value !ptr = value Pointer to index ptr + i, &ptr[i] ptr + i Load at index ptr[i] ptr(i) Store at index ptr[i] = value ptr(i) = value Pointer to field &ptr->name ptr._N Load a field ptr->name !ptr._N Store a field ptr->name = value !ptr._N = value Where N is the index of the field name in the struct.