[Docs] More extensive description of different workflows (#1011)

giordano · web-flow · commit 5a88b728fc16 · 2021-02-14T18:45:57.000Z
In particular

* be slightly less enthusiastic and more realistic about the wizard
* encourage users to modify `build_tarballs.jl` for existing recipes instead
  of starting from scratch with the wizard
* move information about how to run the `build_tarballs.jl` script from the FAQ
  to the first page
* briefly mention GitHub Codespaces
* update some doctests

[skip ci]
diff --git a/docs/src/FAQ.md b/docs/src/FAQ.md
@@ -30,26 +30,6 @@ What BinaryBuilder needs is to find the relevant file (shared libraries, or exec
 When the script completes, BinaryBuilder expects to find at least one artifact _built for the expected architecture_ in either `${libdir}` or `${bindir}`.
 Remember also that you should use the standard environment variables like `CC`, `CXX`, `CFLAGS`, `LDFLAGS` as appropriate in order to cross compile.  See the list of variables in the [Tips for Building Packages](build_tips.md) section.
 
-### I love the wizard, but now I want to break free: can I build the tarballs without it?
-
-The `build_tarballs.jl` script can be used as a command line utility, it takes a few options and as argument the list of triplets of the targets.  You can find more information about the syntax of the script in the [Command Line](@ref) section or by running
-```
-julia build_tarballs.jl --help
-```
-Instead of using the wizard, you can adapt for a new library a `build_tarballs.jl` script originally written for another library.  Then, you can build the tarballs with
-```
-julia --color=yes build_tarballs.jl --debug --verbose
-```
-The `--debug` option will drop you into the BinaryBuilder interactive shell if an error occurs.  If the build fails, after finding out the steps needed to fix the build you have to manually update the script in `build_tarballs.jl`.  You should run again the above command to make sure that everything is actually working.
-
-Since `build_tarballs.jl` takes as argument the comma-separated list of targets for which to build the tarballs, you can select only a few of them.  For example, with
-```
-julia --color=yes build_tarballs.jl --debug --verbose aarch64-linux-musl,arm-linux-musleabihf
-```
-you'll run the build script only for the `aarch64-linux-musl` and `arm-linux-musleabihf` targets.
-
-If you decide to use this workflow, however, you will need to manually open pull requests for [Yggdrasil](https://github.com/JuliaPackaging/Yggdrasil/).
-
 ### Can I open a shell in a particular build environment for doing some quick tests?
 
 Yes!  You can use [`BinaryBuilder.runshell(platform)`](@ref BinaryBuilderBase.runshell) to quickly start a shell in the current directory, without having to set up a working `build_tarballs.jl` script.  For example,
@@ -65,7 +45,7 @@ You can always build a JLL package on your machine with the `--deploy` flag to t
 A common use case is that you want to build a JLL package for, say, `Libfoo`, that will be used as dependency to build `Quxlib`, and you want to make sure that building both `Libfoo` and `Quxlib` will work before submitting all the pull requests to [Yggdrasil](https://github.com/JuliaPackaging/Yggdrasil/).  You can prepare the `build_tarballs.jl` script for `Libfoo` and then build and deploy it with
 
 ```
-julia --color=yes build_tarballs.jl --debug --verbose --deploy="MY_USERNAME/Libfoo_jll.jl"
+julia build_tarballs.jl --debug --verbose --deploy="MY_USERNAME/Libfoo_jll.jl"
 ```
 
 replacing `MY_USERNAME` with your GitHub username: this will build the tarballs for all the platforms requested and upload them to a release of the `MY_USERNAME/Libfoo_jll.jl`, where the JLL package will also be created.  As explained above, you can pass argument the list of triplets of the platforms for you which you want to build the tarballs, in case you want to compile only some of them.  In the Julia REPL, you can install this package as any unregistered package with
@@ -89,7 +69,7 @@ Since this package is unregistered, you have to use the full [`PackageSpec`](htt
 You can of course in turn build and deply this package with
 
 ```
-julia --color=yes build_tarballs.jl --debug --verbose --deploy="MY_USERNAME/Quxlib_jll.jl"
+julia build_tarballs.jl --debug --verbose --deploy="MY_USERNAME/Quxlib_jll.jl"
 ```
 
 ### Can I install packages in the build environment?
diff --git a/docs/src/building.md b/docs/src/building.md
@@ -149,7 +149,7 @@ supported_platforms()
 triplet.(supported_platforms())
 ```
 
-The triplet of the platform is used name of the tarball generated.
+The triplet of the platform is used in the name of the tarball generated.
 
 For some packages, (cross-)compilation may not be possible for all those
 platforms, or you have interested in building the package only for a subset of
@@ -191,13 +191,13 @@ You should be aware of two incompatibilities in particular:
   julia> using BinaryBuilder
 
   julia> platforms = [Platform("x86_64", "linux")]
-  1-element Array{Linux,1}:
-   Platform("x86_64", "linux"; libc="glibc")
+  1-element Vector{Platform}:
+   Linux x86_64 {libc=glibc}
 
   julia> expand_cxxstring_abis(platforms)
-  2-element Array{Platform,1}:
-   Linux(:x86_64, libc=:glibc, compiler_abi=CompilerABI(cxxstring_abi=:cxx03))
-   Linux(:x86_64, libc=:glibc, compiler_abi=CompilerABI(cxxstring_abi=:cxx11))
+  2-element Vector{Platform}:
+   Linux x86_64 {cxxstring_abi=cxx03, libc=glibc}
+   Linux x86_64 {cxxstring_abi=cxx11, libc=glibc}
   ```
 
   Example of packages dealing with the C++ `std::string` ABIs are:
@@ -222,14 +222,14 @@ You should be aware of two incompatibilities in particular:
   julia> using BinaryBuilder
 
   julia> platforms = [Platform("x86_64", "linux")]
-  1-element Array{Linux,1}:
-   Platform("x86_64", "linux"; libc="glibc")
+  1-element Vector{Platform}:
+   Linux x86_64 {libc=glibc}
 
   julia> expand_gfortran_versions(platforms)
-  3-element Array{Platform,1}:
-   Linux(:x86_64, libc=:glibc, compiler_abi=CompilerABI(libgfortran_version=v"3.0.0"))
-   Linux(:x86_64, libc=:glibc, compiler_abi=CompilerABI(libgfortran_version=v"4.0.0"))
-   Linux(:x86_64, libc=:glibc, compiler_abi=CompilerABI(libgfortran_version=v"5.0.0"))
+  3-element Vector{Platform}:
+   Linux x86_64 {libc=glibc, libgfortran_version=3.0.0}
+   Linux x86_64 {libc=glibc, libgfortran_version=4.0.0}
+   Linux x86_64 {libc=glibc, libgfortran_version=5.0.0}
   ```
 
   Example of packages expanding the `libgfortran` versions are:
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -10,13 +10,44 @@ Suppose that you have a Julia package `Foo.jl` which wants to use a compiled `li
 
 The first step in the `BinaryBuilder` journey is to create a build recipe, usually named `build_tarballs.jl`.  The Julia community curates a tree of build recipes, [Yggdrasil](https://github.com/JuliaPackaging/Yggdrasil), that already contains many examples of how to write a `build_tarballs.jl` file.  These files contain information such as the name, version and source locations for a particular build, as well as the actual steps (in the form of a `bash` script) and the products that should be generated by the build.
 
-The result of a successful build is an autogenerated JLL package, typically uploaded to the [JuliaBinaryWrappers](https://github.com/JuliaBinaryWrappers/) github organization.  Binaries for each version of every build are uploaded to the GitHub releases page of the relevant JLL package.  Finally, a registration request is opened against the `General` Julia registry, so that packages such as the aforementioned `Foo.jl` can simply `pkg> add libfoo_jll` to download the binary artifacts as well as the autogenerated Julia wrapper code.
+The result of a successful build is an autogenerated JLL package, typically uploaded to the [JuliaBinaryWrappers](https://github.com/JuliaBinaryWrappers/) github organization.  Binaries for each version of every build are uploaded to the GitHub releases page of the relevant JLL package.  Finally, a registration request is opened against the `General` Julia registry, so that packages such as the aforementioned `Foo.jl` can simply `pkg> add libfoo_jll` to download the binary artifacts as well as the autogenerated Julia wrapper code.  See also the [FAQ](FAQ.md), [build tips](build_tips.md), [build troubleshooting](troubleshooting.md) and [tricksy gotchas](tricksy_gotchas.md) for help with common problems.
 
-To generate a `build_tarballs.jl` file (explained in greater detail in [Building Packages](building.md)), one can clone `Yggdrasil`, copy an existing build recipe, modify it, and submit a new PR, or use the `BinaryBuilder` Wizard to do all of that automatically.  See also the [FAQ](FAQ.md), [build tips](build_tips.md), [build troubleshooting](troubleshooting.md) and [tricksy gotchas](tricksy_gotchas.md) for help with common problems.
+### Wizard interface
 
-## Wizard interface
+`BinaryBuilder.jl` supports an interactive method for building the binary dependencies and capturing the commands used to build it into a `build_tarballs.jl` file: the Wizard interface.  To launch it, run
 
-While constructing your own `build_tarballs.jl` is certainly possible, `BinaryBuilder.jl` supports a more interactive method for building the binary dependencies and capturing the commands used to build it into a `build_tarballs.jl` file: the Wizard interface.  To launch it, run `BinaryBuilder.run_wizard()`, and follow the instructions on-screen.
+```julia
+using BinaryBuilder
+state = BinaryBuilder.run_wizard()
+```
+
+and follow the instructions on-screen.  You can watch an [asciinema demo](https://asciinema.org/a/304105) of the use of the wizard.
+
+### Manually create or edit `build_tarballs.jl`
+
+The wizard is a great tool, especially to get started with BinaryBuilder and create your first simple recipes for new packages.  However, it lacks the full control of all options you can use in a `build_tarballs.jl` script.  To generate this file (explained in greater detail in [Building Packages](building.md)), one can clone `Yggdrasil`, copy an existing build recipe, modify it, and submit a new pull request.  Manually editing the `build_tarballs.jl` script is also the recommended way when you want to update an existing recipe, rather then starting from scratch with the wizard.
+
+The `build_tarballs.jl` script can be used as a command line utility, it takes a few options and as argument the list of triplets of the targets.  You can find more information about the syntax of the script in the [Command Line](@ref) section or by running
+```
+julia build_tarballs.jl --help
+```
+You can build the tarballs with
+```
+julia build_tarballs.jl --debug --verbose
+```
+The `--debug` option will drop you into the BinaryBuilder interactive shell if an error occurs.  If the build fails, after finding out the steps needed to fix the build you have to manually update the script in `build_tarballs.jl`.  You should run again the above command to make sure that everything is actually working.
+
+Since `build_tarballs.jl` takes as argument the comma-separated list of [triplets](@ref Platforms) for which to build the tarballs, you can select only a few of them.  For example, with
+```
+julia build_tarballs.jl --debug --verbose aarch64-linux-musl,arm-linux-musleabihf
+```
+you'll run the build script only for the `aarch64-linux-musl` and `arm-linux-musleabihf` target platforms.
+
+If you decide to use this workflow, however, you will need to manually open pull requests for [Yggdrasil](https://github.com/JuliaPackaging/Yggdrasil/).
+
+### GitHub Codespaces
+
+If you already have access to the [GitHub Codespaces](https://github.com/features/codespaces) service, you can use use BinaryBuilder and all the workflows described above in your browser or with Visual Studio Code, on any operating system, including those not natively supported by the package!  Head to [Yggdrasil](https://github.com/JuliaPackaging/Yggdrasil/) and create a new Codespace.
 
 ## How does this all work?
 
