root: add BUILD.md

This commit is contained in:
Nigel Tao committed 2023-06-01 13:20:47 +10:00
1 parent da95945d65
commit 805e37915f
5 files changed
+127 -3

No files matched your search

+115
View File
@@ -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
```
+7 -2
View File
@@ -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.
+2
View File
@@ -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."
+1 -1
View File
@@ -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."
+2
View File
@@ -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.