Skip to content
Lucet, the Sandboxing WebAssembly Compiler.
Branch: master
Clone or download
pchickey and acfoltzer Merge pch/return_to_clifwasm into master, closing #44
Squashed commit of the following:

commit 8d80e78
Author: Pat Hickey <phickey@fastly.com>
Date:   Tue Apr 23 17:58:37 2019 -0700

    rustfmt

commit 6b0c8f5
Author: Pat Hickey <phickey@fastly.com>
Date:   Tue Apr 23 17:11:07 2019 -0700

    lucetc: comments in sparsedata

commit ef5234d
Author: Pat Hickey <phickey@fastly.com>
Date:   Tue Apr 23 17:06:54 2019 -0700

    lucetc: s/POINTER_SIZE/NATIVE_POINTER_SIZE/g

    and also add a helpful assertions in translate_memory_ funcs

commit c96c708
Author: Pat Hickey <phickey@fastly.com>
Date:   Tue Apr 23 17:06:34 2019 -0700

    lucetc: doc comment

commit cf30872
Merge: 49b6f44 8f0b1ce
Author: Pat Hickey <phickey@fastly.com>
Date:   Tue Apr 23 15:28:08 2019 -0700

    Merge remote-tracking branch 'origin/master' into pch/return_to_clifwasm

commit 49b6f44
Author: Pat Hickey <phickey@fastly.com>
Date:   Mon Apr 22 17:22:17 2019 -0700

    c_api: fixup

commit 9d6aec1
Author: Pat Hickey <phickey@fastly.com>
Date:   Mon Apr 22 17:09:54 2019 -0700

    lucetc: table putelem is a fn not a closure

commit 054e516
Author: Pat Hickey <phickey@fastly.com>
Date:   Mon Apr 22 17:06:28 2019 -0700

    lucetc: clean up sparsedata creation

commit 264f801
Author: Pat Hickey <phickey@fastly.com>
Date:   Mon Apr 22 16:59:00 2019 -0700

    lucet-runtime: move signal-safe fault detail determination into signal handler

commit e8d4d56
Author: Pat Hickey <phickey@fastly.com>
Date:   Mon Apr 22 16:49:21 2019 -0700

    makefile: convenience target to watch and run interesting tests

    if you just run `cargo watch --exec test` itll run spectest which will
    fail, a known issue

commit a00b706
Author: Pat Hickey <phickey@fastly.com>
Date:   Mon Apr 22 16:33:44 2019 -0700

    lucet-runtime: distinct error for when no linear memory exists

commit 6276741
Author: Pat Hickey <phickey@fastly.com>
Date:   Mon Apr 22 16:25:23 2019 -0700

    pin goblin to 0.0.21

commit 15cef40
Merge: eb29ad7 899b191
Author: Pat Hickey <pat@moreproductive.org>
Date:   Mon Apr 22 14:47:35 2019 -0700

    Merge branch 'master' into pch/return_to_clifwasm

commit eb29ad7
Author: Pat Hickey <phickey@fastly.com>
Date:   Fri Apr 19 14:34:27 2019 -0700

    gitignore core.*

commit 74161bf
Author: Pat Hickey <phickey@fastly.com>
Date:   Fri Apr 19 13:44:01 2019 -0700

    dlmodule: delete unused elem_size

commit 077686c
Author: Pat Hickey <phickey@fastly.com>
Date:   Fri Apr 19 13:41:50 2019 -0700

    lucet-runtime: fail bail in expand heap if no heap exists

commit 80ce206
Author: Pat Hickey <phickey@fastly.com>
Date:   Fri Apr 19 13:40:36 2019 -0700

    lucet-runtime: delete README.rst from package assets

commit a894bfd
Author: Pat Hickey <phickey@fastly.com>
Date:   Tue Apr 16 15:19:19 2019 -0700

    lucet-runtime: representation of table len changed to elements

    change required by cranelift-wasm

commit 8776cae
Author: Pat Hickey <phickey@fastly.com>
Date:   Tue Apr 16 15:19:00 2019 -0700

    lucetc: expose table symbols

    required by ModuleInternal::table_elements()

commit 10c66a7
Author: Pat Hickey <phickey@fastly.com>
Date:   Tue Apr 16 14:49:23 2019 -0700

    lucetc: fix rebase onto new options model

commit eb3b9bf
Author: Pat Hickey <phickey@fastly.com>
Date:   Tue Apr 16 12:36:16 2019 -0700

    fixup

commit e774136
Author: Adam Foltzer <acfoltzer@fastly.com>
Date:   Tue Apr 16 12:11:26 2019 -0700

    lucet-runtime-tests: disable building a test executable

    it only provides macros used elsewhere

commit 8893945
Author: Pat Hickey <phickey@fastly.com>
Date:   Tue Apr 16 11:39:27 2019 -0700

    lucetc: wasi-sdk test fixes

commit c115a2c
Author: Pat Hickey <phickey@fastly.com>
Date:   Tue Apr 16 11:39:09 2019 -0700

    lucet-runtime: test fixes

commit 66b698c
Author: Pat Hickey <phickey@fastly.com>
Date:   Tue Apr 16 10:50:29 2019 -0700

    rustfmt

commit eace7ff
Author: Pat Hickey <phickey@fastly.com>
Date:   Thu Apr 11 18:10:06 2019 -0700

    lucetc: undeclared table 0 is accepted, begrudgingly

    the spec tests say we must

commit 651bdd1
Author: Pat Hickey <phickey@fastly.com>
Date:   Thu Apr 11 17:50:33 2019 -0700

    lucet-spectest: delete unnecessary instance wrapper, don't reset after err

commit db4078b
Author: Pat Hickey <phickey@fastly.com>
Date:   Thu Apr 11 17:49:51 2019 -0700

    lucet-runtime: permit running instance that had non-fatal fault

    there's no reason not to do this, and the spec tests actually require it

commit 6d6b78a
Author: Pat Hickey <phickey@fastly.com>
Date:   Thu Apr 11 17:31:44 2019 -0700

    fixup bf0a2ca

commit 0bbfd6a
Author: Pat Hickey <phickey@fastly.com>
Date:   Thu Apr 11 17:02:13 2019 -0700

    lucetc/runtime - refactor trap codes

    we had a fatal error in one of the spec tests because i made a big mess
    of the trap codes. this hopefully corrects the error:

    * the unreachable instruction was getting encoded as an "unknown"
      trapcode. this was because all of the code having to do with the
      representation of trapcodes was a hot mess, which is on me.
    * we get rid of trapcodes being a pair (struct) of code and the other 16
      bits that were in the "user" code. now we reject all user codes.
      we have no use for them.
    * if a trapcode is unknown, in rust its a None. in the C API
      we still have a variant for unknown

commit 04153b9
Author: Pat Hickey <phickey@fastly.com>
Date:   Thu Apr 11 16:57:22 2019 -0700

    lucet-analyze: support printing out the trap table

commit 0baff6a
Author: Pat Hickey <phickey@fastly.com>
Date:   Thu Apr 11 16:55:29 2019 -0700

    lucet-spectest: add some comments, disable names test because too noisy

commit 4049eb3
Author: Pat Hickey <phickey@fastly.com>
Date:   Thu Apr 11 16:55:09 2019 -0700

    lucet-spectest: print the command running

    so that if they segfault we have a clue

commit 1ebfc65
Author: Pat Hickey <phickey@fastly.com>
Date:   Thu Apr 11 15:01:35 2019 -0700

    lucetc: bound check table correctly by loading bound from symbol

commit ab1ff7c
Author: Pat Hickey <phickey@fastly.com>
Date:   Thu Apr 11 14:45:18 2019 -0700

    lucet-runtime: check multiplication for overflow

    the memory_trap.wast spectest caught this

commit 8f564df
Author: Adam Foltzer <acfoltzer@fastly.com>
Date:   Thu Apr 11 14:17:26 2019 -0700

    lucet-runtime: add a test to cover missed case

    previous commit fixes a bug where alloc reset fails if the heap
    never grew. this tests that case

commit ba1ac0b
Author: Pat Hickey <phickey@fastly.com>
Date:   Thu Apr 11 14:13:22 2019 -0700

    lucet-runtime: correct implementation of heap reset

    the lucet-spectest address.wast test triggered this bug by calling
    reset on an instance that did not grow the heap. all of the runtime
    tests that tested reset behavior previously grew the heap, so that the
    mprotect was always triggered.

commit 8ed45b4
Author: Pat Hickey <phickey@fastly.com>
Date:   Wed Apr 10 16:02:31 2019 -0700

    lucet-spectest: catch unsupported cases of unexpected failures

    wtf was i doing when i wrote this the first time around. this code is
    horrific

commit cb36f45
Author: Pat Hickey <phickey@fastly.com>
Date:   Wed Apr 10 15:34:00 2019 -0700

    lucetc: simplify error kinds

    theres no need for strings in them, we already have strings in the error
    messages themselves

commit 5353e41
Author: Pat Hickey <phickey@fastly.com>
Date:   Wed Apr 10 14:57:46 2019 -0700

    lucet-spectest: port to new lucetc

commit 346506f
Author: Pat Hickey <phickey@fastly.com>
Date:   Wed Apr 10 14:26:19 2019 -0700

    lucetc: add check to sparsedata construction to ensure in initial heap

commit 969c542
Author: Pat Hickey <phickey@fastly.com>
Date:   Wed Apr 10 13:22:35 2019 -0700

    delete pwasm-validation submodule

commit b54127b
Author: Pat Hickey <phickey@fastly.com>
Date:   Wed Apr 10 13:19:54 2019 -0700

    lucetc: use wasmparser to validate before cranelift-wasm parses

    and delete dependency on pwasm-validation

commit b211fd3
Author: Pat Hickey <phickey@fastly.com>
Date:   Wed Apr 10 11:43:37 2019 -0700

    lucetc: map cranelift-wasm translation errors to the correct error kinds

commit fda3d9e
Author: Pat Hickey <phickey@fastly.com>
Date:   Wed Apr 10 11:30:53 2019 -0700

    lucetc: uncomment remaining wasm module_data tests

commit 363748f
Author: Pat Hickey <phickey@fastly.com>
Date:   Wed Apr 10 11:27:34 2019 -0700

    lucetc: fix up globals wasm tests

commit cecb4f8
Author: Pat Hickey <phickey@fastly.com>
Date:   Wed Apr 10 10:55:57 2019 -0700

    lucetc: fix heap & table indexing, distinguish func error types

commit 9361d1f
Author: Pat Hickey <phickey@fastly.com>
Date:   Tue Apr 9 17:20:39 2019 -0700

    lucetc: test suites compile again

commit 6a41de6
Author: Pat Hickey <phickey@fastly.com>
Date:   Tue Apr 9 17:20:36 2019 -0700

    fixup

commit 8f5df13
Author: Pat Hickey <phickey@fastly.com>
Date:   Thu Apr 4 14:58:49 2019 -0700

    lucetc: port wasi-sdk tests to new interface

    they fail at codegen :(

commit 3db73b4
Author: Pat Hickey <phickey@fastly.com>
Date:   Thu Apr 4 14:27:35 2019 -0700

    lucetc: switch to linear memory spec, as part of the decls

commit b8e2f25
Author: Pat Hickey <phickey@fastly.com>
Date:   Thu Apr 4 14:27:25 2019 -0700

    lucet-module-data: forgot an export

commit 23f27a1
Author: Pat Hickey <phickey@fastly.com>
Date:   Thu Apr 4 11:39:35 2019 -0700

    lucet-runtime: switch to LinearMemorySpec

commit 30a6457
Author: Pat Hickey <phickey@fastly.com>
Date:   Wed Apr 3 15:45:45 2019 -0700

    lucet-module-data: linear memory spec is optional

    if no memory is declared for the module, there should be neither a
    heap spec nor a way to initialize memory, otherwise there should be
    both.

commit 0b4b836
Author: Pat Hickey <phickey@fastly.com>
Date:   Mon Apr 1 16:27:04 2019 -0700

    lucetc: get rid of implicit Error -> LucetcError promotion

commit b0f84cb
Author: Pat Hickey <phickey@fastly.com>
Date:   Mon Apr 1 16:19:48 2019 -0700

    lucetc: table errors dont need additional context

commit 8ca748a
Author: Pat Hickey <phickey@fastly.com>
Date:   Mon Apr 1 16:18:40 2019 -0700

    lucetc: replace "Other" error kind with real info

commit f283d5c
Author: Pat Hickey <phickey@fastly.com>
Date:   Mon Apr 1 16:02:15 2019 -0700

    lucetc: backport reserved size fixes

commit 7303975
Author: Pat Hickey <phickey@fastly.com>
Date:   Mon Apr 1 15:38:22 2019 -0700

    lucetc: move new stuff to root. rustfmt.

commit 103e70a
Author: Pat Hickey <phickey@fastly.com>
Date:   Mon Apr 1 15:34:06 2019 -0700

    lucetc: clean out the old junk

commit 90f6a70
Author: Pat Hickey <phickey@fastly.com>
Date:   Mon Apr 1 15:29:45 2019 -0700

    lucetc: move remaining compiler and program definitions into new

commit 67219e7
Author: Pat Hickey <phickey@fastly.com>
Date:   Mon Apr 1 15:19:17 2019 -0700

    move stack probe to new structure

commit 87e9893
Author: Pat Hickey <phickey@fastly.com>
Date:   Mon Apr 1 15:16:02 2019 -0700

    lucetc: move pointer consts to their own place

commit 57da276
Author: Pat Hickey <phickey@fastly.com>
Date:   Mon Apr 1 11:39:42 2019 -0700

    lucetc: output moved to new::

commit 9899f42
Author: Pat Hickey <phickey@fastly.com>
Date:   Thu Mar 28 16:51:05 2019 -0700

    lucetc: move compiler to own module

commit 3420724
Author: Pat Hickey <phickey@fastly.com>
Date:   Wed Mar 27 14:40:52 2019 -0700

    lucetc: fix declaration of table to get element pointer size right

commit 699a37e
Author: Pat Hickey <phickey@fastly.com>
Date:   Wed Mar 27 12:46:53 2019 -0700

    lucetc: empty heap spec and data init if no memory defined

commit 26f15a7
Author: Pat Hickey <phickey@fastly.com>
Date:   Wed Mar 27 12:36:02 2019 -0700

    lucetc: emit start func

commit acb2181
Author: Pat Hickey <phickey@fastly.com>
Date:   Wed Mar 27 12:20:03 2019 -0700

    lucetc: various serious bugfixes

    * werent setting func names or signatures before creating them! wow
    * don't create table if none declared
    * fix conventions for Name methods

commit 498cd10
Author: Pat Hickey <phickey@fastly.com>
Date:   Tue Mar 26 17:10:36 2019 -0700

    rustfmt

commit 6baeaeb
Author: Pat Hickey <phickey@fastly.com>
Date:   Tue Mar 26 17:10:08 2019 -0700

    lucetc: add vmctx to signatures and direct calls

commit 337152e
Author: Pat Hickey <phickey@fastly.com>
Date:   Tue Mar 26 16:35:37 2019 -0700

    lucetc: finish output of module data and tables

commit 8c0531f
Author: Pat Hickey <phickey@fastly.com>
Date:   Mon Mar 25 18:05:31 2019 -0700

    lucetc: port sparse data to clifwasm

commit 39eacc9
Author: Pat Hickey <phickey@fastly.com>
Date:   Mon Mar 25 16:45:04 2019 -0700

    lucetc: thread through memory specs, implement icalls

commit 24a99e5
Author: Pat Hickey <phickey@fastly.com>
Date:   Fri Mar 22 18:37:57 2019 -0700

    lucetc: implement more of cranelift_wasm FuncEnvironment

commit 3ffd648
Author: Pat Hickey <phickey@fastly.com>
Date:   Thu Mar 21 17:52:49 2019 -0700

    lucetc: new style for tracking runtime functions

commit 6d126b8
Author: Pat Hickey <phickey@fastly.com>
Date:   Thu Mar 21 14:44:27 2019 -0700

    lucetc: declarations in clifmodule for funcs, table data

commit 5514f8b
Author: Pat Hickey <phickey@fastly.com>
Date:   Wed Mar 20 14:38:25 2019 -0700

    lucetc: make a place for ModuleInfo to turn into ClifModule declarations

commit 85ca9bb
Author: Pat Hickey <phickey@fastly.com>
Date:   Tue Mar 19 12:20:53 2019 -0700

    lucetc: eliminate tests that execute code in mock vm

    the lucet-runtime-tests provide good coverage of all of these concerns

commit 9e5fd82
Author: Pat Hickey <phickey@fastly.com>
Date:   Mon Mar 18 19:17:22 2019 -0700

    rustfmt

commit 2af6f37
Author: Pat Hickey <phickey@fastly.com>
Date:   Mon Mar 18 17:49:25 2019 -0700

    lucetc: scaffold out FuncEnvironment and compiler loop

commit f2a1274
Author: Pat Hickey <phickey@fastly.com>
Date:   Mon Mar 18 16:21:22 2019 -0700

    lucetc: implement ModuleEnvironment

commit 8f7356f
Author: Pat Hickey <phickey@fastly.com>
Date:   Mon Mar 18 11:45:13 2019 -0700

    lucetc: delete runtime-c globals serializer

commit b756b0a
Author: Pat Hickey <phickey@fastly.com>
Date:   Mon Mar 18 11:44:10 2019 -0700

    lucetc: delete runtime-c linear memory serializers

commit ee8adba
Author: Pat Hickey <phickey@fastly.com>
Date:   Mon Mar 18 11:42:00 2019 -0700

    lucetc: delete runtime-c memory spec serializer

commit 372fc52
Author: Pat Hickey <phickey@fastly.com>
Date:   Mon Mar 18 11:22:58 2019 -0700

    depend on cranelift-wasm
Latest commit d03aaad Apr 24, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.cargo Replace -W,-export-dynamic with -rdynamic Apr 11, 2019
assemblyscript The WASI bindings are now in the AssemblyScript standard library Apr 1, 2019
assets Don't consider assets/*.png files as text Apr 11, 2019
benchmarks For some reason, nix forgot to define unistd::sync() on macOS Apr 18, 2019
cranelift @ 894cecc bump cranelift, faerie, and expand readme Mar 15, 2019
faerie @ ebe9edf bump cranelift, faerie, and expand readme Mar 15, 2019
helpers Bail out if helpers/install.sh is run on a non-Linux system Apr 20, 2019
lucet-analyze Merge pch/return_to_clifwasm into master, closing #44 Apr 24, 2019
lucet-builtins Merge pch/return_to_clifwasm into master, closing #44 Apr 24, 2019
lucet-idl
lucet-module-data
lucet-runtime Merge pch/return_to_clifwasm into master, closing #44 Apr 24, 2019
lucet-spectest Merge pch/return_to_clifwasm into master, closing #44 Apr 24, 2019
lucet-wasi-fuzz Merge branch 'master' into acf/more-fuzz Apr 22, 2019
lucet-wasi-sdk Add sysroot to the linker flags Apr 20, 2019
lucet-wasi lucet-wasi tests: temporary fix for getrusage prototype Apr 23, 2019
lucetc Merge pch/return_to_clifwasm into master, closing #44 Apr 24, 2019
sightglass @ 4999f90 Update sightglass again Apr 16, 2019
.clang-format add clang-format and gitignore Jan 25, 2019
.dockerignore
.editorconfig add Makefile exception to .editorconfig Apr 10, 2019
.gitattributes gitattributes: wasm is also binary Apr 17, 2019
.gitignore Merge branch 'master' into acf/more-fuzz Apr 22, 2019
.gitmodules Merge pch/return_to_clifwasm into master, closing #44 Apr 24, 2019
.travis.yml Simplify Travis builds Apr 11, 2019
CODE_OF_CONDUCT.md add contributor covenant 1.4 Jan 31, 2019
Cargo.lock Merge pch/return_to_clifwasm into master, closing #44 Apr 24, 2019
Cargo.toml
Dockerfile dockerfile: upgrade to wasi-sdk 4.0 Apr 23, 2019
LICENSE add Apache-2.0 WITH LLVM-exception license throughout Jan 28, 2019
Makefile Merge pch/return_to_clifwasm into master, closing #44 Apr 24, 2019
README.md
SECURITY.md Move security.md and supporting files Mar 27, 2019
config.inc Support bash in devenv scripts Mar 28, 2019
devenv_build_container.sh Build a "lucet" layer on top of "lucet-dev" Apr 4, 2019
devenv_run.sh Old versions of Docker didn't support regexes in filters Apr 11, 2019
devenv_setenv.sh Support bash in devenv scripts Mar 28, 2019
devenv_start.sh Old versions of Docker didn't support regexes in filters Apr 11, 2019
devenv_stop.sh Support bash in devenv scripts Mar 28, 2019
platform.info [lucet-wasi-fuzz] creduce driver and test predicate improvements Apr 4, 2019
rust-toolchain

README.md

Lucet   Build Status

Lucet is a native WebAssembly compiler and runtime. It is designed to safely execute untrusted WebAssembly programs inside your application.

Check out our announcement post on the Fastly blog.

Lucet uses, and is developed in collaboration with, Mozilla's Cranelift code generator.

Lucet powers Fastly's Terrarium platform.


Status

Lucet supports running WebAssembly programs written in C (via clang), Rust, and AssemblyScript. It does not yet support the entire WebAssembly spec, but full support is coming in the near future.

Lucet's runtime currently only supports x86-64 based Linux systems, with experimental support for macOS.

Contents

lucetc

lucetc is the Lucet Compiler.

The Rust crate lucetc provides an executable lucetc. It compiles WebAssembly modules (.wasm or .wat files) into native code (.o or .so files).

lucet-runtime

lucet-runtime is the runtime for WebAssembly modules compiled through lucetc. It is a Rust crate that provides the functionality to load modules from shared object files, instantiate them, and call exported WebAssembly functions. lucet-runtime manages the resources used by each WebAssembly instance (linear memory & globals), and the exception mechanisms that detect and recover from illegal operations.

The bulk of the library is defined in the child crate lucet-runtime-internals. The public API is exposed in lucet-runtime. Test suites are defined in the child crate lucet-runtime-tests. Many of these tests invoke lucetc and the wasi-sdk tools.

lucet-runtime is usable as a Rust crate or as a C library. The C language interface is found at lucet-runtime/include/lucet.h.

lucet-wasi

lucet-wasi is a crate providing runtime support for the WebAssembly System Interface (WASI). It can be used as a library to support WASI in another application, or as an executable, lucet-wasi, to execute WASI programs compiled through lucetc.

See "Your first Lucet application" for an example that builds a C program and executes it with lucet-wasi.

For details on WASI's implementation, see lucet-wasi/README.md.

lucet-wasi-sdk

wasi-sdk is a Cranelift project that packages a build of the Clang toolchain, the WASI reference sysroot, and a libc based on WASI syscalls. lucet-wasi-sdk is a Rust crate that provides wrappers around these tools for building C programs into Lucet modules. We use this crate to build test cases in lucet-runtime-tests and lucet-wasi.

lucet-module-data

lucet-module-data is a crate with data structure definitions and serialization functions that we emit into shared objects with lucetc, and read with lucet-runtime.

lucet-analyze

lucet-analyze is a Rust executable for inspecting the contents of a shared object generated by lucetc.

lucet-idl

lucet-idl is a Rust executable that implements code generation via an Interface Description Language (IDL). The generated code provides zero-copy accessor and constructor functions for datatypes that have the same representation in both the WebAssembly guest program and the host program.

Functionality is incomplete at the time of writing, and not yet integrated with other parts of the project. Rust code generator, definition of import and export function interfaces, and opaque type definitions are planned for the near future.

lucet-spectest

lucet-spectest is a Rust crate that uses lucetc and lucet-runtime, as well as the (external) wabt crate, to run the official WebAssembly spec test suite, which is provided as a submodule in this directory. Lucet is not yet fully spec compliant, and the implementation of lucet-spectest has not been maintained very well during recent codebase evolutions. We expect to fix this up and reach spec compliance in the near future.

lucet-builtins

lucet-builtins is a C library that provides optimized native versions of libc primitives. lucetc can substitute the implementations defined in this library for the WebAssembly implementations.

lucet-builtins/wasmonkey is the Rust crate that lucetc uses to transform function definitions in a WebAssembly module into uses of an import function.

Vendor libraries

Lucet is tightly coupled to several upstream dependencies, and Lucet development often requires making changes to these dependencies which are submitted upstream once fully baked. To reduce friction in this development cycle, we use git submodules to vendor these modules into the Lucet source tree.

Cranelift

We keep the primary Cranelift project repository as a submodule at /cranelift.

Cranelift provides the native code generator used by lucetc, and a ton of supporting infrastructure.

Cranelift was previously known as Cretonne. Project developers hang out in the #cranelift channel on irc.mozilla.org:6697.

Faerie

faerie is a Rust crate for producing ELF files. Faerie is used by Cranelift (through the module system's cranelift-faerie backend) and also directly by lucetc, for places where the cranelift-module API can't do everything we need.

Tests

Most of the crates in this repository have some form of unit tests. In addition, lucet-runtime/lucet-runtime-tests defines a number of integration tests for the runtime, and lucet-wasi has a number of integration tests using WASI C programs.

Benchmarks

We created the sightglass benchmarking tool to measure the runtime of C code compiled through a standard native toolchain against the Lucet toolchain. It is provided as a submodule at /sightglass.

Sightglass ships with a set of microbenchmarks called shootout. The scripts to build the shootout tests with native and various versions of the Lucet toolchain are in /benchmarks/shootout.

Furthermore, there is a suite of benchmarks of various Lucet runtime functions, such as instance creation and teardown, in /benchmarks/lucet-benchmarks.

Development Environment

Operating System

Lucet is developed and tested on Linux and macOS. We expect it to work on any POSIX system which supports shared libraries.

Dependencies

Lucet requires:

  • Stable Rust, and rustfmt. We typically track the latest stable release.
  • wasi-sdk, providing a Clang toolchain with wasm-ld, the WASI reference sysroot, and a libc based on WASI syscalls.
  • GNU Make, CMake, & various standard Unix utilities for the build system.

Getting started

The easiest way to get started with the Lucet toolchain is by using the provided Docker-based development environment.

This repository includes a Dockerfile to build a complete environment for compiling and running WebAssembly code with Lucet, but you shouldn't have to use Docker commands directly. A set of shell scripts with the devenv_ prefix are used to manage the container.

Setting up the environment

  1. The Lucet repository uses git submodules. Make sure they are checked out by running git submodule init && git submodule update.

  2. Install and run the docker service. We do not support podman at this time. On MacOS, Docker for Mac is an option.

  3. Once Docker is running, in a terminal, and at the root of the cloned repository, run: source devenv_setenv.sh. (This command requires the current shell to be zsh, ksh or bash). After a couple minutes, the Docker image is built and a new container is run.

  4. Check that new commands are now available:

lucetc --help

You're now all set!

Your first Lucet application

The devenv_setenv.sh shell script ensures the Lucet executables are available in your shell. Under the hood, these commands are executed in the Docker container. The container has limited visibility into the host's filesystem - it can only see files under the lucet repository.

Create a new work directory in the lucet directory:

mkdir -p src/hello

cd src/hello

Save the following C source code as hello.c:

#include <stdio.h>

int main(void)
{
    puts("Hello world");
    return 0;
}

Time to compile to WebAssembly! The development environment includes a version of the Clang toolchain that is built to generate WebAssembly by default. The related commands are accessible from your current shell, and are prefixed by wasm32-unknown-wasi-.

For example, to create a WebAssembly module hello.wasm from hello.c:

wasm32-unknown-wasi-clang -Ofast -o hello.wasm hello.c

The next step is to use Lucet to build native x86_64 code from that WebAssembly file:

lucetc-wasi -o hello.so hello.wasm

lucetc is the WebAssembly to native code compiler. The lucetc-wasi command runs the same compiler, but automatically configures it to target WASI.

hello.so is created and ready to be run:

lucet-wasi hello.so

Additional shell commands

  • ./devenv_build_container.sh rebuilds the container image. This is never required unless you edit the Dockerfile.
  • ./devenv_run.sh [<command>] [<arg>...] runs a command in the container. If a command is not provided, an interactive shell is spawned. In this container, Lucet tools are installed in /opt/lucet by default. The command source /opt/lucet/bin/devenv_setenv.sh can be used to initialize the environment.
  • ./devenv_start.sh and ./devenv_stop.sh start and stop the container.

Security

The lucet project aims to provide support for secure execution of untrusted code. Security is achieved through a combination of lucet-supplied security controls and user-supplied security controls. See SECURITY.md for more information on the lucet security model.

Reporting Security Issues

The Lucet project team welcomes security reports and is committed to providing prompt attention to security issues. Security issues should be reported privately via Fastly’s security issue reporting process. Remediation of security vulnerabilities is prioritized. The project teams endeavors to coordinate remediation with third-party stakeholders, and is committed to transparency in the disclosure process.

You can’t perform that action at this time.