wasixcc is a clang wrapper designed to simplify compilation for the WASIX platform. It provides a convenient interface to configure and invoke the LLVM toolchain with appropriate flags for the WASIX platform.

• Easy configuration of WASIX compilation parameters
• Automatic sysroot management
• Support for both C and C++ compilation
• Flexible flag management for compiler and linker
• Integration with wasm-opt for optimization
• Support for various module types
  • Static, dynamic, shared libraries
  • Exception handling, asyncify

curl -fsSL https://wasix.cc | sh

The installer will install wasixcc and its dependencies to ~/.wasixcc

To use wasixcc in your GitHub Action use the following snippet

- name: Install wasixcc
  uses: wasix-org/wasixcc@main

This will setup wasixcc and all dependencies in less than 10 seconds.

Basic usage:

wasixcc [OPTIONS] -- [PASS-THROUGH OPTIONS]

Run wasixcc --help for comprehensive usage instructions.

Configuration can be set via command line (-s flag) or environment variables (WASIXCC_ prefix):

All configuration options can be set via environment variables by prefixing them with WASIXCC_:

export WASIXCC_SYSROOT=/custom/sysroot
export WASIXCC_COMPILER_FLAGS="-O2"
wasixcc program.c -o program.wasm

This is useful when wasixcc is integrated into build systems where you don't control the CLI invocation directly, such as when running through CMake.

1. Compile a simple C program:

   wasixcc hello.c -o hello.wasm

2. Compile a simple C++ program:

   wasix++ hello.cpp -o program.wasm

3. Compile with custom sysroot:

   wasixcc -sSYSROOT=/path/to/sysroot program.c -o program.wasm

4. Compile with custom optimization flags:

   wasixcc -sCOMPILER_FLAGS="-O3" -sWASM_OPT_FLAGS="-O3" app.c -o app.wasm

wasixcc supports 3 primary build configurations. The configurations are mainly differentiated based on where they can run and what language features they support, and how setjmp/longjmp is handled.

• The default configuration; this configuration can run anywhere, but relies on asyncify for setjmp/longjmp support. asyncify has considerable performance implications, and should be avoided where possible. Support for C++ exceptions in this configuration has not been tested, and it is likely to be broken.

• The EH configuration uses the WASM Exception Handling Proposal to support setjmp/longjmp. This configuration can only run on EH-enabled WASM runtimes, including Wasmer's LLVM backend and browsers. However, it is considerably faster than the default configuration due to avoiding asyncify. C++ exceptions are also fully supported in this mode.

  To enable this mode, run wasixcc with -sWASM_EXCEPTIIONS=yes.

• The EH+PIC configuration uses the EH proposal similarly to the EH configuration, but also enables Position-Independent Code. In the WASM world, PIC is only useful for dynamic linking scenarios, so you should avoid this configuration unless you require support for dlopen/dlsym.

  To enable this mode, run wasixcc with -sWASM_EXCEPTIONS=yes -sPIC=yes.

If you need support for dynamic linking, you need to use the EH+PIC configuration for the main module and all side modules. The usual clang flags work here; just passing -shared will give you a DL side module, a.k.a. a dynamically-linked library.

However, there is one caveat: native binaries generally link against libc dynamically at runtime, with libc being provided by the OS. Since there is no concept of an OS in wasm, the approach is slightly different; the main module is expected to embed all libc/libc++ symbols and make them available to side modules.

To enable this behavior in wasixcc, you may need to explicitly set the module kind to dynamic-main by passing -sMODULE_KIND=dynamic-main.

wasixcc can be integrated into different build systems to adapt existing software to the WASIX platform.

To use wasixcc with Autotools, simply replace the default LLVM tools with the wasixcc equivalent.

wasixcc runs wasm-opt to generate working output modules by default, but this can break compilation tests, so it is recommended to disable wasm-opt during configuration:

# Set up wasixcc's settings
export WASIXCC_XXX=YYY

# Replace default tools with wasixcc equivalents
export \
  CC=wasixcc \
  CXX=wasix++ \
  LD=wasixld \
  AR=wasixar \
  NM=wasixnm \
  RANLIB=wasixranlib

# Disable wasm-opt during configuration...
WASIXCC_RUN_WASM_OPT=no \
  ./configure ...

# ... but make sure to enable it again during the build, as skipping
# wasm-opt produces broken binaries in all configurations.
make ...

To use wasixcc with CMake, you can use the toolchain file in this repository:

# First, set up wasixcc settings for the build. This is important
# because the build settings influence the sysroot location.
export WASIXCC_XXX=YYY

# wasix-toolchain.cmake references this variable
export WASIX_SYSROOT=$(wasixcc --print-sysroot)

# Disable wasm-opt during configuration...
WASIXCC_RUN_WASM_OPT=no \
  cmake ... -DCMAKE_TOOLCHAIN_FILE=wasix-toolchain.cmake

# ... but make sure to enable it again during the build
cmake --build ...

Contributions are welcome! Please feel free to open a PR if there's something you feel can be improved.