From 9e375309a4bf3e1a093c3655a28d7530aa0d1c0b Mon Sep 17 00:00:00 2001 From: Nigel Tao Date: Tue, 19 Nov 2019 21:38:09 +1100 Subject: [PATCH] Add doc/wuffs-the-library.md --- doc/wuffs-the-library.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 doc/wuffs-the-library.md diff --git a/doc/wuffs-the-library.md b/doc/wuffs-the-library.md new file mode 100644 index 00000000..67d98c8b --- /dev/null +++ b/doc/wuffs-the-library.md @@ -0,0 +1,32 @@ +# Wuffs the Library + +The Wuffs project is both a programming language and a standard library written +in that programming language (and then e.g. transpiled to C). For more details +on the former, see the [Wuffs the Language](/doc/wuffs-the-language.md) +document. As for Wuffs the Library (also known as "std"): + +- Source code is in [`/std`](/std). +- API documentation is in [`/doc/std`](/doc/std). +- Example programs are in [`/example`](/example). A simple way to get started + is to run the `build-example.sh` script in the top level directory. +- Unit tests are in [`/test`](/test). +- Fuzz tests are in [`/fuzz`](/fuzz). + +It is perfectly feasible to use Wuffs the Library as a C library, without +depending on Wuffs the Language tools (such as its compiler). Although the +standard library's source code is in Wuffs the Language, the transpiled form is +also checked into the repository. Using the standard library's C form would be +like using any other third party C library. It's just not hand written C. + +To do so, you need to download only one file, from the +[`/release/c`](/release/c) directory. Wuffs the Library' C form ships as a +[single file C +library](https://github.com/nothings/stb/blob/master/docs/stb_howto.txt), +targeting the C99 standard. That file acts as either a traditional `.c` or `.h` +file depending on the presence or absence of a `WUFFS_IMPLEMENTATION` macro +definition. + +Most of the example programs treat it as a `.c` file. The +[`/example/library`](/example/library) program treats it as a `.h` file, and +requires a separate step (e.g. running `wuffs genlib` beforehand) to build the +library implementation (e.g. a `libwuffs.a` or `libwuffs.so` file).