Repository files navigation

It is"ridiculouslyfast".

Per itsbenchmarks and other linked-to blog posts:

• It can decode bzip21.3x faster than/usr/bin/bzcat(C).
• It can decode deflate up to1.4x faster than zlib-the-library (C).
• It can decode GIF2x-6x faster than "giflib" (C), "image/gif" (Go) and"gif" (Rust).
• It can decode PNG1.2x-2.7x faster than "libpng" (C), "image/png" (Go) and"png"(Rust).

Wuffs' goal is to produce software libraries that are as safe as Go or Rust,roughly speaking, but as fast as C, and that can be used anywhere C librariesare used. This includes very large C/C++ projects, such as popular web browsersand operating systems (using that term to include desktop and mobile userinterfaces, not just the kernel).

Wuffs the Library isavailable astranspiled C code. Other C/C++ projects canuse that library withoutrequiring theWuffs the Language toolchain.Those projects can use Wuffs the Library like using any other third party Clibrary. It's just not hand-written C.

However, unlike hand-written C, Wuffs the Language is safe with respect tobuffer overflows, integer arithmetic overflows and null pointer dereferences. Akey difference between Wuffs and other memory-safe languages is thatall suchchecks are done at compile time, not at run time. If it compiles, it is safe,with respect to those three bug classes.

The trade-off in aiming for both safety and speed is that Wuffs programs takelonger for a programmer to write, as they have toexplicitly annotate theirprograms with proofs of safety. A statement likex += 1 unsurprisinglymeans to increment the variablex by1. However, in Wuffs, such a statementis a compile time error unless the compiler can also prove thatx is not themaximal value ofx's type (e.g.x is not255 ifx is abase.u8), asthe increment would otherwise overflow. Similarly, an integer arithmeticexpression likex / y is a compile time error unless the compiler can alsoprove thaty is not zero.

Wuffs is not a general purpose programming language.It is for writinglibraries, not programs. Wuffs code ishermeticand can only compute (e.g. convert "compressed bytes" to "decompressed bytes").It cannot make any syscalls (e.g. it has no ambient authority to read yourfiles), implying that it cannot allocate or free memory (and is thereforetrivially safe against things like memory leaks, use-after-frees anddouble-frees).

It producesSans I/O style libraries (but Clibraries, not Python), meaning that they are agnostic to'functioncolors'.They can be combined with synchronous or asynchronous I/O, as the librarycaller (not library implementation) is responsible for the actual I/O.

The idea isn't to write your whole program in Wuffs,only the parts that areboth performance-conscious and security-conscious. For example, whiletechnically possible, it is unlikely that a Wuffs compiler would be worthwriting entirely in Wuffs.

The/std/lzw/decode_lzw.wuffs file is a goodexample. TheWuffs the Language document has moreinformation on how it differs from other languages in the C family.

For example, making this one-line edit to the LZW codec leads to a compile timeerror.wuffs gen fails to generate the C code, i.e. fails to compile(transpile) the Wuffs code to C code:

diff --git a/std/lzw/decode_lzw.wuffs b/std/lzw/decode_lzw.wuffsindex f878c5e..f10dcee 100644--- a/std/lzw/decode_lzw.wuffs+++ b/std/lzw/decode_lzw.wuffs@@ -98,7 +98,7 @@ pub func lzw_decoder.decode?(dst ptr buf1, src ptr buf1, src_final bool)() {                        in.dst.write?(x:s)                        if use_save_code {-                               this.suffixes[save_code] = c as u8+                               this.suffixes[save_code] = (c + 1) as u8                                this.prefixes[save_code] = prev_code as u16                        }

$ wuffs gen std/gifcheck: expression "(c + 1) as u8" bounds [1 ..= 256] is not within bounds [0 ..= 255] at/home/n/go/src/github.com/google/wuffs/std/lzw/decode_lzw.wuffs:101. Facts:    n_bits < 8    c < 256    this.stack[s] == (c as u8)    use_save_code

In comparison, this two-line edit will compile (but the "does it decode GIFcorrectly" tests then fail):

diff --git a/std/lzw/decode_lzw.wuffs b/std/lzw/decode_lzw.wuffsindex f878c5e..b43443d 100644--- a/std/lzw/decode_lzw.wuffs+++ b/std/lzw/decode_lzw.wuffs@@ -97,8 +97,8 @@ pub func lzw_decoder.decode?(dst ptr buf1, src ptr buf1, src_final bool)() {                        // type checking, bounds checking and code generation for it).                        in.dst.write?(x:s)-                       if use_save_code {-                               this.suffixes[save_code] = c as u8+                       if use_save_code and (c < 200) {+                               this.suffixes[save_code] = (c + 1) as u8                                this.prefixes[save_code] = prev_code as u16                        }

$ wuffs gen std/gifgen wrote:      /home/n/go/src/github.com/google/wuffs/gen/c/gif.cgen unchanged:  /home/n/go/src/github.com/google/wuffs/gen/h/gif.h$ wuffs test std/gifgen unchanged:  /home/n/go/src/github.com/google/wuffs/gen/c/gif.cgen unchanged:  /home/n/go/src/github.com/google/wuffs/gen/h/gif.htest:           /home/n/go/src/github.com/google/wuffs/test/c/gifgif/basic.c     clang   PASS (8 tests run)gif/basic.c     gcc     PASS (8 tests run)gif/gif.c       clang   FAIL test_lzw_decode: bufs1_equal: wi: got 19311, want 19200.contents differ at byte 3 (in hex: 0x000003):  000000: dcdc dc00 00d9 f5f9 f6df dc5f 393a 3a3a  ..........._9:::  000010: 3a3b 618e c8e4 e4e4 e5e4 e600 00e4 bbbb  :;a.............  000020: eded 8f91 9191 9090 9090 9190 9192 9192  ................  000030: 9191 9292 9191 9293 93f0 f0f0 f1f1 f2f2  ................excerpts of got (above) versus want (below):  000000: dcdc dcdc dcd9 f5f9 f6df dc5f 393a 3a3a  ..........._9:::  000010: 3a3a 618e c8e4 e4e4 e5e4 e6e4 e4e4 bbbb  ::a.............  000020: eded 8f91 9191 9090 9090 9090 9191 9191  ................  000030: 9191 9191 9191 9193 93f0 f0f0 f1f1 f2f2  ................gif/gif.c       gcc     FAIL test_lzw_decode: bufs1_equal: wi: got 19311, want 19200.contents differ at byte 3 (in hex: 0x000003):  000000: dcdc dc00 00d9 f5f9 f6df dc5f 393a 3a3a  ..........._9:::  000010: 3a3b 618e c8e4 e4e4 e5e4 e600 00e4 bbbb  :;a.............  000020: eded 8f91 9191 9090 9090 9190 9192 9192  ................  000030: 9191 9292 9191 9293 93f0 f0f0 f1f1 f2f2  ................excerpts of got (above) versus want (below):  000000: dcdc dcdc dcd9 f5f9 f6df dc5f 393a 3a3a  ..........._9:::  000010: 3a3a 618e c8e4 e4e4 e5e4 e6e4 e4e4 bbbb  ::a.............  000020: eded 8f91 9191 9090 9090 9090 9191 9191  ................  000030: 9191 9191 9191 9193 93f0 f0f0 f1f1 f2f2  ................wuffs-test-c: some tests failedwuffs test: some tests failed

• lang holds the Go libraries that implement Wuffs the Language: tokenizer,AST, parser, renderer, etc. The Wuffs tools are written in Go, but asmentioned above, Wuffs transpiles to C code, and Go is not necessarilyinvolved if all you want is to use the C edition of Wuffs.
• lib holds other Go libraries, not specific to Wuffs the Language per se.
• internal holds internal implementation details, as per Go'sinternalpackages convention.
• cmd holds Wuffs the Language' command line tools, also written in Go.
• std holds Wuffs the Library's code.
• release holds the releases (e.g. in their C form) of Wuffs the Library.
• test holds the regular tests for Wuffs the Library.
• fuzz holds the fuzz tests for Wuffs the Library.
• script holds miscellaneous utility programs.
• doc holds documentation.
• example holds example programs for Wuffs the Library.
• hello-wuffs-c holds an example program for Wuffs the Language.

See theBUILD instructions.

• Getting Started.Start here if you want toplay but aren't sure how (andBUILD doesn't help).
• Background.
• Benchmarks.
• Binary Size.
• Changelog.
• Glossary.
• Related Work.
• Roadmap.
• Wuffs the Language overview.
• Wuffs the Library overview and see alsoAPIcategories.

TheNote directory also contains various short articles.

• dev0x13/pywuffs holds Python bindingsfor Wuffs the Library.
• Bindings for Go, Rust and other languages are tracked asissue#38.

Version 0.3 (April 2023) is the latest stable version. Stable means thatits API won't change any further, but being a "version 0.x" means that:

• It will not have long term support.
• Newer versions make no promises about compatibility.

The compiler undoubtedly has bugs. Assertion checking needs more rigor,especially around side effects and aliasing, and being sufficiently wellspecified to allow alternative implementations. Lots of detail needs work, butthe broad brushstrokes are there.

Nonetheless, Wuffs' GIF decoder has shipped in the Google Chrome web browsersince June2021(milestone M93). See also the"ridiculouslyfast" tweet alreadymentioned above.

The mailing list is athttps://groups.google.com/forum/#!forum/wuffs.

TheCONTRIBUTING.md file contains instructions on how tofile the Contributor License Agreement before sending any pull requests (PRs).Of course, if you're new to the project, it's usually best to discuss anyproposals and reach consensus before sending your first PR.

Source code isauto-formatted.

This software is distributed under the terms of both the MIT license and theApache License (Version 2.0).

See LICENSE for details.

This is not an official Google product, it is just code that happens to beowned by Google.

Tony is an arse-kicking wombat who loves playingfull-forward and hates bufferoverflows.

Updated on November 2023.