root: add BUILD.md

Author: nigeltao

BUILD.md

@@ -0,0 +1,115 @@
+# Build Instructions
+
+Answering "how do I build Wuffs" depends on what exactly you mean by "Wuffs":
+
+1. The Wuffs library (e.g. image decoders) in C/C++ form.
+2. Its example programs (e.g. jsonptr).
+3. The Wuffs toolchain (e.g. Wuffs-to-C compiler/proof-checker).
+4. The Wuffs library in Wuffs form (converting it to C/C++ code).
+5. Everything.
+
+
+## Quick Start
+
+The rest of this document assumes that you've already checked out and moved
+into the Wuffs repository's directory, like this:
+
+```
+git clone https://github.com/google/wuffs.git
+cd wuffs
+```
+
+If you just want to kick the metaphorical tyres:
+
+```
+./build-example.sh example/jsonptr
+gen/bin/example-jsonptr test/data/rfc-6901-json-pointer.json
+```
+
+
+## Building the Wuffs Library (in C/C++ Form)
+
+There's no build step, in that there's no "configure and make" step needed
+before moving on to building the example programs.
+
+To elaborate, transpiling (converting Wuffs-the-library from `*.wuffs` form
+into a single `*.c` file) isn't done by whoever *checks out* the Wuffs
+repository. It's done by whoever *checks in* code changes.
+
+Wuffs-the-library is provided as [single file C
+library](https://github.com/nothings/stb/blob/master/docs/stb_howto.txt). The
+example programs just `#include` that file directly.
+
+For your own projects, just copy `release/c/wuffs-$VERSION.c` to your directory
+and add that file to your pre-existing build system, or compile an `*.o` object
+file directly like below. Remember to define the `WUFFS_IMPLEMENTATION` macro
+to compile all of the C code in that single file, not just the "header" part.
+
+```
+# Most developers won't have to do this. It just demonstrates how to produce
+# wuffs-v0.3.o directly from a C/C++ compiler.
+gcc -c -DWUFFS_IMPLEMENTATION -O3 release/c/wuffs-v0.3.c
+```
+
+
+## Building the Example Programs
+
+Just run your favorite C/C++ compiler (e.g. `gcc` or `g++`) on the
+`example/foo/*.{c,cc}` file. Pass `-O3` or equivalent for an optimized build:
+
+```
+gcc -O3 example/bzcat/bzcat.c -o my-bzcat
+./my-bzcat < test/data/romeo.txt.bz2
+```
+
+Some example programs require additional libraries:
+
+```
+g++ example/imageviewer/imageviewer.cc -lxcb -lxcb-image -lxcb-render -lxcb-render-util
+
+g++ example/sdl-imageviewer/sdl-imageviewer.cc -lSDL2 -lSDL2_image
+```
+
+The `build-example.sh` script (an alternative to running your favorite C/C++
+compiler directly) takes care of having to remember those additional libraries.
+
+```
+./build-example.sh example/sdl-imageviewer
+gen/bin/example-sdl-imageviewer test/data/hat.jpeg
+```
+
+Building the fuzzers are similar, using `build-fuzz.sh` instead of
+`build-example.sh`.
+
+
+## Building the Wuffs Toolchain
+
+Most developers won't have to do this. See the sections above instead.
+
+But after editing `lang/check/*.go` files, do this:
+
+```
+go install ./cmd/wuffs*
+```
+
+
+## Building the Wuffs library (from its Wuffs Form)
+
+Most developers won't have to do this. See the sections above instead.
+
+But after editing `std/jpeg/*.wuffs` files, do this:
+
+```
+wuffs gen std/...
+```
+
+
+## Building Everything (All of the Above, Plus Tests, Benchmarks, Etc)
+
+Most developers won't have to do this. See the sections above instead.
+
+But before sending a Pull Request, do this:
+
+```
+./build-all.sh
+```

README.md

@@ -181,10 +181,15 @@ wuffs test: some tests failed
 - `hello-wuffs-c` holds an example program for Wuffs the Language.
 
 
+# Building
+
+See the [BUILD](/BUILD.md) instructions.
+
+
 # Documentation
 
 - [Getting Started](/doc/getting-started.md). **Start here** if you want to
-  play but aren't sure how.
+  play but aren't sure how (and [BUILD](/BUILD.md) doesn't help).
 - [Background](/doc/background.md).
 - [Benchmarks](/doc/benchmarks.md).
 - [Binary Size](/doc/binary-size.md).
@@ -241,4 +246,4 @@ owned by Google.
 
 ---
 
-Updated on January 2023.
+Updated on June 2023.

build-all.sh

@@ -36,6 +36,8 @@
 # cd wuffs
 # gcc ./example/zcat/zcat.c
 # ./a.out < ./test/data/romeo.txt.gz
+#
+# See BUILD.md for more discussion.
 
 if [ ! -e wuffs-root-directory.txt ]; then
   echo "$0 should be run from the Wuffs root directory."

build-example.sh

@@ -15,7 +15,7 @@
 
 # ----------------
 
-# See build-all.sh for commentary.
+# See BUILD.md and build-all.sh for more discussion.
 
 if [ ! -e wuffs-root-directory.txt ]; then
   echo "$0 should be run from the Wuffs root directory."

example/README.md

@@ -24,3 +24,5 @@ examples. To check out and build just one, such as `jsonptr`:
 When re-building, you only need the last of those three lines. To run it:
 
     gen/bin/example-jsonptr test/data/json-things.unformatted.json
+
+See also the top-level [BUILD](/BUILD.md) instructions.