Reorganize the documentation

Author: jonas

.scalafmt.conf

@@ -3,6 +3,8 @@ docstrings = JavaDoc
 assumeStandardLibraryStripMargin = true
 project.excludeFilters = [
   tests/samples
+  "docs/src/test/scala/org/example/.*[.]scala"
+  "sbt-scala-native-bindgen/.*/expected/.*[.]scala"
 ]
 project.git = true
 runner.dialect = Scala211

CONTRIBUTING.md

@@ -30,6 +30,12 @@ cd tests
 sbt ~test
 ```
 
+To run the same tests as is run by Travis CI use the `test.sh` script, which will both build the executable and run `sbt verify`:
+
+```sh
+./scripts/test.sh
+```
+
 ## Coding Guidelines
 
 Code should be formatted with `./scripts/scalafmt` and `./scripts/clangfmt`.

build.sbt

@@ -1,6 +1,8 @@
 import scala.sys.process._
+import org.scalanative.bindgen.sbt.ScalaNativeBindgenPlugin
 
-addCommandAlias("verify", "; ^test:compile ; ^test ; ^scripted ; docs/makeSite")
+addCommandAlias("verify",
+                "; tests/test ; docs/test ; ^scripted ; docs/makeSite")
 
 val Versions = new {
   val scala210 = "2.10.6"
@@ -88,6 +90,7 @@ lazy val tests = project("tests")
     ),
     libraryDependencies += "org.scalatest" %% "scalatest" % "3.0.5" % Test
   )
+  .aggregate(samples)
 
 lazy val samples = project("samples")
   .in(file("tests/samples"))
@@ -98,47 +101,7 @@ lazy val samples = project("samples")
     libraryDependencies += "com.lihaoyi" %%% "utest" % "0.6.3" % "test",
     testFrameworks += new TestFramework("utest.runner.Framework"),
     nativeLinkStubs := true,
-    Test / nativeLinkingOptions += {
-      Seq("-L", (Test / target).value.getAbsoluteFile / "bindgen").mkString
-    },
-    Test / compile := {
-      val log            = streams.value.log
-      val cwd            = (Test / target).value / "bindgen"
-      val compileOptions = (Test / nativeCompileOptions).value
-      val cpaths         = (baseDirectory.value.getAbsoluteFile * "*.c").get
-      val clangPath      = nativeClang.value.toPath.toAbsolutePath.toString
-
-      cwd.mkdirs()
-
-      def abs(path: File): String =
-        path.getAbsolutePath
-
-      def run(command: Seq[String]): Int = {
-        log.info("Running " + command.mkString(" "))
-        Process(command, cwd) ! log
-      }
-
-      val opaths = cpaths.map { cpath =>
-        val opath = abs(cwd / s"${cpath.getName}.o")
-        val command = Seq(clangPath) ++ compileOptions ++ Seq("-c",
-                                                              abs(cpath),
-                                                              "-o",
-                                                              opath)
-
-        if (run(command) != 0) {
-          sys.error(s"Failed to compile $cpath")
-        }
-        opath
-      }
-
-      val archivePath = cwd / "libbindgentests.a"
-      val archive     = Seq("ar", "cr", abs(archivePath)) ++ opaths
-      if (run(archive) != 0) {
-        sys.error(s"Failed to create archive $archivePath")
-      }
-
-      (Test / compile).value
-    }
+    compileTask("bindgentests", baseDirectory)
   )
 
 lazy val tools = project("tools")
@@ -166,16 +129,33 @@ lazy val sbtPlugin = project("sbt-scala-native-bindgen", ScriptedPlugin)
 
 lazy val docs = project("docs")
   .enablePlugins(GhpagesPlugin, ParadoxSitePlugin, ParadoxMaterialThemePlugin)
+  .enablePlugins(ScalaNativePlugin, ScalaNativeBindgenPlugin)
   .settings(
     publish / skip := true,
+    scalaVersion := Versions.scala211,
+    // FIXME: Remove when a version has been released with Test scope settings.
+    ScalaNativeBindgenPlugin.nativeBindgenScopedSettings(Test),
+    Test / nativeBindings += {
+      NativeBinding((Test / resourceDirectory).value / "vector.h")
+        .name("vector")
+        .link("vector")
+        .packageName("org.example")
+    },
+    Test / nativeBindgen / target := (Test / scalaSource).value / "org/example",
+    nativeLinkStubs := true,
+    compileTask("vector", Test / resourceDirectory),
+    libraryDependencies += "org.scalatest" %%% "scalatest" % "3.2.0-SNAP10" % Test,
     Paradox / paradoxProperties ++= Map(
       "github.base_url" -> scmInfo.value.get.browseUrl.toString
     ),
     ParadoxMaterialThemePlugin.paradoxMaterialThemeSettings(Paradox),
     Paradox / paradoxMaterialTheme := {
+      val licenseUrl = scmInfo.value.get.browseUrl.toString + "blob/master/LICENSE.txt"
       (Paradox / paradoxMaterialTheme).value
         .withRepository(scmInfo.value.get.browseUrl.toURI)
         .withColor("indigo", "indigo")
+        .withCopyright(
+          s"Copyright © Liudmila Kornilova, distributed under the <a href='$licenseUrl'>Scala license</a>.")
     }
   )
 
@@ -209,3 +189,47 @@ def project(name: String, plugged: AutoPlugin*) = {
 
 lazy val setReleaseVersions: String => State => State =
   v => _.put(ReleaseKeys.versions, (v, v))
+
+def compileTask(libname: String, srcDirTask: SettingKey[File]) = Def.settings(
+  Test / nativeLinkingOptions += {
+    Seq("-L", (Test / target).value.getAbsoluteFile / "bindgen").mkString
+  },
+  Test / compile := {
+    val log            = streams.value.log
+    val cwd            = (Test / target).value / "bindgen"
+    val compileOptions = (Test / nativeCompileOptions).value
+    val cpaths         = (srcDirTask.value.getAbsoluteFile * "*.c").get
+    val clangPath      = nativeClang.value.toPath.toAbsolutePath.toString
+
+    cwd.mkdirs()
+
+    def abs(path: File): String =
+      path.getAbsolutePath
+
+    def run(command: Seq[String]): Int = {
+      log.info("Running " + command.mkString(" "))
+      Process(command, cwd) ! log
+    }
+
+    val opaths = cpaths.map { cpath =>
+      val opath = abs(cwd / s"${cpath.getName}.o")
+      val command = Seq(clangPath) ++ compileOptions ++ Seq("-c",
+                                                            abs(cpath),
+                                                            "-o",
+                                                            opath)
+
+      if (run(command) != 0) {
+        sys.error(s"Failed to compile $cpath")
+      }
+      opath
+    }
+
+    val archivePath = cwd / s"lib$libname.a"
+    val archive     = Seq("ar", "cr", abs(archivePath)) ++ opaths
+    if (run(archive) != 0) {
+      sys.error(s"Failed to create archive $archivePath")
+    }
+
+    (Test / compile).value
+  }
+)

docs/src/paradox/cli.md

@@ -0,0 +1,55 @@
+# Generating Bindings with the CLI
+
+Statically linked executables are provided with each release for Linux and macOS. Head over to the [releases page] to download the latest version for your platform.
+
+ [releases page]: https://github.com/kornilova-l/scala-native-bindgen/releases
+
+@@@ note
+
+In the following we assume you have renamed the downloaded `scala-native-bindgen-$PLATFORM` file to `scala-native-bindgen`.
+
+@@@
+
+## Command Line Usage
+
+When generating bindings with the CLI, you need to specify the header file and provide the name of the created bindings using the `--name` option:
+
+```sh
+scala-native-bindgen --name fnmatch /usr/include/fnmatch.h --
+```
+
+When running the CLI it will also yield warnings along with the translation. To keep only the bindings please redirect the output to a file like this:
+
+```sh
+scala-native-bindgen --name fnmatch /usr/include/fnmatch.h -- > fnmatch.scala
+```
+
+By default it is assumed that you want to link with a library based on the name option.
+In case the name of the library to link with is different from the binding name provide the library name using `--link`:
+
+```sh
+scala-native-bindgen --name zlib --link z /usr/include/zlib.h --
+```
+
+If the binding does not require any linking, pass `--no-link`:
+
+```sh
+scala-native-bindgen --name fnmatch --no-link /usr/include/fnmatch.h --
+```
+
+For libraries that require linking you m
+
+## Options
+
+The generated bindings can be configured using the different options and it is also possible to pass arguments directly to the Clang compiler using the `--extra-arg*` options.
+
+| Option               | Description
+|----------------------|---------------------------------------------------------------------------------|
+| `--link`             | Library to link with, e.g. `--link` uv for libuv.
+| `--no-link`          | Library does not require linking.
+| `--name`             | Scala object name that contains bindings. Default value set to library name.
+| `--package`          | Package name of generated Scala file.
+| `--exclude-prefix`   | Functions and unused typedefs will be removed if their names have given prefix.
+| `--binding-config`   | Path to a config file that contains the information about bindings that should be reused. See @ref:[Integrating Bindings](integrating-bindings.md) for more information.
+| `--extra-arg`        | Additional argument to append to the compiler command line.
+| `--extra-arg-before` | Additional argument to prepend to the compiler command line.

docs/src/paradox/command-line-usage/index.md

@@ -1,4 +1,4 @@
-# Building with `CMake`
+# Building the executable with `CMake`
 
 Building `scala-native-bindgen` requires the following tools and libraries:
 
@@ -40,16 +40,6 @@ equivalent, e.g. to compile with debug symbols the following are the same:
 ```sh
 cmake -DCMAKE_CXX_FLAGS=-g ..
 CXXFLAGS=-g cmake ..
-```
-
-## Testing
-
-The tests assume that the above instructions for building `scala-native-bindgen` from source
-has been followed.
-
-```sh
-cd tests
-sbt test
 ```
 
  [CMake]: https://cmake.org/

docs/src/paradox/obtaining-bindgen/cmake.md renamed to docs/src/paradox/contrib/cmake.md

@@ -1,4 +1,4 @@
-# Building with `docker-compose`
+# Building the executable with `docker-compose`
 
 You can use [docker-compose] to build and test the program:
 
@@ -11,4 +11,5 @@ docker-compose run --rm ubuntu-18.04-llvm-6.0 ./script/test.sh
 docker-compose run --rm ubuntu-18.04-llvm-6.0 \
     bindgen/target/scala-native-bindgen --name union tests/samples/Union.h --
 ```
+
  [docker-compose]: https://docs.docker.com/compose/

docs/src/paradox/obtaining-bindgen/docker-compose.md renamed to docs/src/paradox/contrib/docker-compose.md

@@ -0,0 +1 @@
+../../../../CONTRIBUTING.md

docs/src/paradox/contrib/guidelines.md

@@ -0,0 +1,15 @@
+# Contributor's Guide
+
+Contributions to the project is very welcome. This section provides more
+information about how to build and contribute to the project.
+
+@@ toc
+
+@@@ index
+
+* [guidelines](guidelines.md)
+* [cmake](cmake.md)
+* [docker-compose](docker-compose.md)
+* [releasing](releasing.md)
+
+@@@

docs/src/paradox/contrib/index.md

@@ -0,0 +1,21 @@
+# Release Workflow
+
+First build the `scala-native-bindgen` executable for both macOS and
+Linux:
+
+```sh
+scripts/prepare-release.sh
+```
+
+You should now have `scala-native-bindgen-linux` and
+`scala-native-bindgen-darwin` if you ran the script on a macOS machine.
+
+Then release version `x.y.z` by running:
+
+```sh
+sbt -Dproject.version=x.y.z release
+```
+
+Finally, upload the `scala-native-bindgen-linux` and
+`scala-native-bindgen-darwin` executables to the release page at:
+<https://github.com/kornilova-l/scala-native-bindgen/releases/tag/vx.y.z>

docs/src/paradox/contrib/releasing.md

@@ -1,21 +1,37 @@
 # Scala Native Bindgen
 
-@@@ index
-
-* [Obtaining Bindgen](obtaining-bindgen/index.md)
-* [Command Line Usage](command-line-usage/index.md)
-* [Integrating Bindings](integrating-bindings/index.md)
-* [Limitations](limitations/index.md)
-* [Using Generated Bindings](using-generated-bindings/README.md)
+Scala Native Bindgen is a binding generator for Scala Native that uses [Clang] to
+parse C header files and generates Scala binding definitions.
 
-@@@
+## Features
 
-This tool generates Scala Native bindings from C headers.
-It's built upon clang and [LibTooling] and thus respects the conventions of clang-tools.
+* possibility to reuse types from existing bindings.
+* type casts that make recursive structs be valid Scala Native structs.
+* implicit classes for structs and unions that make fields access easier.
+* implicit classes that add setters and getters to structs with more than 22 fields (such structs in Scala
+  Native are represented as arrays of bytes).
+* literal defines embedding `#define MY_CONSTANT 42` → `val MY_CONSTANT: native.CInt = 42`.
+* read-only bindings for extern variables (such variables cannot be updated due to Scala Native limitation).
+* declarations filtering by prefix.
 
 ## License
 
 This project is distributed under the Scala license.
 @github[See LICENSE.txt for details](/LICENSE.txt)
 
- [LibTooling]: https://clang.llvm.org/docs/LibTooling.html
+ [Clang]: https://clang.llvm.org/
+
+## Table of Contents
+
+@@ toc
+
+@@@ index
+
+* [sbt](sbt.md)
+* [cli](cli.md)
+* [Using Generated Bindings](using-generated-bindings.md)
+* [Integrating Bindings](integrating-bindings.md)
+* [Limitations](limitations.md)
+* [Contributor's Guide](contrib/index.md)
+
+@@@