add developer documentation

close #134

Author: MikaelSlevinsky

docs/make.jl

@@ -36,6 +36,7 @@ makedocs(
             authors = "Richard Mikael Slevinsky",
             pages = Any[
                     "Home" => "index.md",
+                    "Development" => "dev.md",
                     "Examples" => [
                         "generated/automaticdifferentiation.md",
                         "generated/chebyshev.md",

docs/src/dev.md

@@ -0,0 +1,61 @@
+# Development Documentation
+
+The core of `FastTransforms.jl` is developed in parallel with the [C library](https://github.com/MikaelSlevinsky/FastTransforms) of the same name. Julia and C interoperability is enhanced by the [BinaryBuilder](https://github.com/JuliaPackaging/BinaryBuilder.jl) infrastructure, which provides the user a safe and seamless experience using a package in a different language.
+
+## Why two packages?
+
+Orthogonal polynomial transforms are performance-sensitive imperative tasks. Yet, many of Julia's rich and evolving language features are simply unnecessary for defining these computational routines. Moreover, rapid language changes in Julia (as compared to C) have been more than a perturbation to this repository in the past.
+
+The C library generates assembly for vectorized operations such as single instruction multiple data (SIMD) that is more efficient than that generated by a compiler without human intervention. It also uses OpenMP to introduce shared memory parallelism for large tasks. Finally, calling into precompiled binaries reduces the Julia package's pre-compilation, improving the user experience. Some of these capabilities also exist in Julia, but with C there is just more control over performance.
+
+C libraries are easier to call from any other language, partly explaining why the Python package manager Spack [already supports the C library](https://spack.readthedocs.io/en/latest/package_list.html#fasttransforms) through third-party efforts.
+
+## The developer's right to build from source
+
+Precompiled binaries are important for users, but development in C may be greatly accelerated by coupling it with a dynamic language such as Julia. For this reason, the repository preserves the developer's right to build the C library from source by setting an environment variable to trigger the build script:
+
+```julia
+julia> ENV["FT_BUILD_FROM_SOURCE"] = "true"
+"true"
+
+(@v1.5) pkg> build FastTransforms
+   Building FFTW ──────────→ `~/.julia/packages/FFTW/ayqyZ/deps/build.log`
+   Building TimeZones ─────→ `~/.julia/packages/TimeZones/K98G0/deps/build.log`
+   Building FastTransforms → `~/.julia/dev/FastTransforms/deps/build.log`
+
+julia> using FastTransforms
+[ Info: Precompiling FastTransforms [057dd010-8810-581a-b7be-e3fc3b93f78c]
+
+```
+
+This lets the developer experiment with new features through `ccall`ing into bleeding edge source code. Customizing the build script further allows the developer to track a different branch or even a fork.
+
+## From release to release to release
+
+To get from a C library release to a Julia package release, the developer needs to update Yggdrasil's [build_tarballs.jl](https://github.com/JuliaPackaging/Yggdrasil/blob/master/F/FastTransforms/build_tarballs.jl) script for the new version and its 256-bit SHA. On macOS, the SHA can be found by:
+
+```julia
+julia> run(`curl https://codeload.github.com/MikaelSlevinsky/FastTransforms/tar.gz/v0.5.0 --output FastTransforms-0.5.0.tar.gz`)
+  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
+                                 Dload  Upload   Total   Spent    Left  Speed
+100  156k    0  156k    0     0   351k      0 --:--:-- --:--:-- --:--:--  350k
+Process(`curl https://codeload.github.com/MikaelSlevinsky/FastTransforms/tar.gz/v0.5.0 --output FastTransforms-0.5.0.tar.gz`, ProcessExited(0))
+
+julia> run(`shasum -a 256 FastTransforms-0.5.0.tar.gz`)
+9556d0037bd5348a33f15ad6100e32053b6e22cab16a97c504f30d6c52fd0efd  FastTransforms-0.5.0.tar.gz
+Process(`shasum -a 256 FastTransforms-0.5.0.tar.gz`, ProcessExited(0))
+
+julia> run(`rm -f FastTransforms-0.5.0.tar.gz`)
+Process(`rm -f FastTransforms-0.5.0.tar.gz`, ProcessExited(0))
+```
+
+Then we wait for the friendly folks at [JuliaPackaging](https://github.com/JuliaPackaging) to merge the pull request to Yggdrasil, triggering a new release of the [FastTransforms_jll.jl](https://github.com/JuliaBinaryWrappers/FastTransforms_jll.jl) meta package that stores all precompiled binaries. With this release, we update the FastTransforms.jl [Project.toml](https://github.com/JuliaApproximation/FastTransforms.jl/blob/master/Project.toml) to point to the latest release and register the new version.
+
+Since development of Yggdrasil is quite rapid, a fork may easily become stale. Git permits the developer to forcibly make a master branch on a fork even with upstream master:
+
+```
+git fetch upstream
+git checkout master
+git reset --hard upstream/master
+git push origin master --force
+```