doc/getting-started.md

# Getting Started

If you just want to **decode an image**:

- [example/toy-aux-image](/example/toy-aux-image/toy-aux-image.cc) demonstrates
  the high-level `wuffs_aux::DecodeImage` C++ function (for decoding still
  images, not animated images) and links to more documentation.
- [example/convert-to-nia](/example/convert-to-nia/convert-to-nia.c)
  demonstrates the low-level C API, which is more complicated but (1) handles
  animation, (2) handles asynchronous I/O, (3) handles metadata and (4) does no
  dynamic memory allocation, so it can run under a `SECCOMP_MODE_STRICT`
  sandbox. Wuffs is already a memory-safe language, but this provides defense
  in depth and can make the security audit trivial.
- [script/print-image-metadata.cc](/script/print-image-metadata.cc)
  demonstrates extracting image metadata like ICC color profiles (in raw form).

In all of these cases, you don't need to first configure or build any Wuffs
code. You can just run a C/C++ compiler, like this (for an unoptimized build):
`g++ example/toy-aux-image/toy-aux-image.cc -o my-toy-aux-image`

If you want a fast (optimized) build, pass `-O3` or equivalent to your C/C++
compiler, or from the Wuffs root directory, run this:
`./build-example.sh example/toy-aux-image`

---

If you're looking to **use the Wuffs standard library** generally, e.g. you
want to safely decode some gzip'ed data in your C program, see the [Wuffs the
Library](/doc/wuffs-the-library.md) document and the [other examples](/example)
instead of this document.

If you're looking to **write your own Wuffs code** outside of its standard
library, e.g. you want to safely decode your own custom file format, see the
[Wuffs the Language](/doc/wuffs-the-language.md) document and the
[/hello-wuffs-c](/hello-wuffs-c) example instead of this document.

If you're looking to **modify the Wuffs language**, it's probably best to ask
the [mailing list](https://groups.google.com/forum/#!forum/wuffs).

If you're looking to **modify the Wuffs standard library**, keep reading.

---

First, install the Go toolchain in order to build the Wuffs tools. To run the
test suite, you might also have to install C compilers like clang and gcc, as
well as C libraries (and their .h files) like libjpeg and libpng, as some tests
compare that Wuffs produces exactly the same output as these other libraries.

Run `git clone https://github.com/google/wuffs.git` to get the latest Wuffs
code, `cd` into its directory and run `go install -v ./cmd/wuffs*` to install
the Wuffs tools. The Wuffs tools that you'll most often use are `wuffsfmt`
(analogous to `clang-format`, `gofmt` or `rustfmt`) and `wuffs` (roughly
analogous to `make`, `go` or `cargo`).

You should now be able to run `wuffs test`. If you only have the `gcc` C
compiler installed, but not `clang`, then you can run `wuffs
test -ccompilers=gcc` instead. If all goes well, you should see some output
containing the word "PASS" multiple times.

Remember to re-run `go install etc` whenever you've modified the Wuffs *tools'*
source code (i.e. `*.go` files) or after a manually issued `git pull`. If
you're only modifying the Wuffs *standard library's* source code (i.e.
`*.wuffs` files), re-running `go install etc` is unnecessary.

If you're modifying just one particular codec in the standard library, such as
the `std/png/*.wuffs` files, then you can exclude unrelated tests by running
`wuffs test std/png`.


## Poking Around

Feel free to edit the `std/lzw/decode_lzw.wuffs` file, which implements the GIF
LZW decoder. After editing, run `wuffs gen std/gif` or `wuffs test std/gif` to
re-generate the C edition of the Wuffs standard library's GIF codec, and
optionally run its tests.

Try deleting an assert statement and re-running `wuffs gen`. The result should
be syntactically valid, but a compile error, as some bounds checks can no
longer be proven.

Find the `var bits : base.u32` line, which declares the bits variable,
implicitly initialized to zero. Try adding `bits -= 1` on a new line of code
after all of the `var` lines. Again, `wuffs gen` should fail, as the
computation can underflow.

Similarly, changing the `4095` in `var prev_code : base.u32[..= 4095]` either
higher or lower should fail.

Try adding `assert false` at various places, which should obviously fail, but
should also cause `wuffs gen` to print what facts the compiler knows at that
point. This can be useful when debugging why Wuffs can't prove something you
think it should be able to.


## Running the Tests

If you've changed any of the tools (i.e. changed any `.go` code), re-run `go
install -v github.com/google/wuffs/cmd/...` and `go test
github.com/google/wuffs/lang/...`.

If you've changed any of the libraries (i.e. changed any `.wuffs` code), run
`wuffs test` or, ideally, `wuffs test -mimic` to also check that Wuffs' output
mimics (i.e. exactly matches) other libraries' output, such as giflib for GIF,
libpng for PNG, etc.

If your library change is an optimization, run `wuffs bench` or `wuffs bench
-mimic` both before and after your change to quantify the improvement. The
mimic benchmark numbers shouldn't change if you're only changing `.wuffs` code,
but seeing zero change in those numbers is a coherence check on any unrelated
system variance, such as software updates or virus checkers running in the
background.