diff --git a/Docker/Dockerfile.dev b/Docker/Dockerfile.dev index f26228531..07b017f9c 100644 --- a/Docker/Dockerfile.dev +++ b/Docker/Dockerfile.dev @@ -132,7 +132,8 @@ RUN install -D -m 0755 /home/${USERNAME}/lind-wasm/scripts/bin/lind_compile /usr # Replace copied helper scripts with symlinks so local edits are reflected. RUN rm -f /usr/local/bin/lind_compile /usr/local/bin/lind_run \ && ln -sf /home/${USERNAME}/lind-wasm/scripts/bin/lind_compile /usr/local/bin/lind_compile \ - && ln -sf /home/${USERNAME}/lind-wasm/scripts/bin/lind_run /usr/local/bin/lind_run + && ln -sf /home/${USERNAME}/lind-wasm/scripts/bin/lind_run /usr/local/bin/lind_run \ + && ln -sf /home/${USERNAME}/lind-wasm/scripts/bin/lind_checkenv /usr/local/bin/lind_checkenv USER ${USERNAME} CMD ["/bin/bash"] diff --git a/Makefile b/Makefile index 4666f440d..9bd0ab8c5 100644 --- a/Makefile +++ b/Makefile @@ -235,6 +235,13 @@ md_generation: @echo "Wrote $(OUT)/e2e_comment.md" +# Verify the host has everything needed to build and run lind-wasm. +# Use `make checkenv BUILD_ONLY=1` on a fresh checkout to skip the checks for +# artifacts that `make build` has not produced yet. +.PHONY: checkenv +checkenv: + ./scripts/bin/lind_checkenv $(if $(BUILD_ONLY),--build) + .PHONY: lint lint: cargo fmt --check --all --manifest-path src/wasmtime/Cargo.toml diff --git a/README.md b/README.md index 70977a85e..f29a45b96 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,23 @@ Check out the [Getting started](https://lind-project.github.io/lind-wasm/getting guide for a Hello World! example and [our docs](https://lind-project.github.io/lind-wasm/) to learn more about Lind! +**Supported platforms:** `lind-wasm` targets **linux/amd64**. A native build +requires x86-64 Linux (tested on Ubuntu 22.04) and roughly 20 GB of free disk +space. + +| Host | How to run | +| --- | --- | +| x86-64 Linux | native build, or the development image | +| Windows | Ubuntu 22.04 under WSL2, covered in the [Native Linux setup](https://lind-project.github.io/lind-wasm/contribute/running-on-native-linux/) guide; or Docker Desktop with `--platform=linux/amd64` | +| macOS (Intel or Apple Silicon) | the development image with `--platform=linux/amd64`; on Apple Silicon this runs under emulation and is slower | + +On Windows and macOS, clone into a case-sensitive filesystem — the WSL2 ext4 +filesystem rather than `/mnt/c`, for example. The glibc sources contain +case-colliding filenames (see +[#1246](https://github.com/Lind-Project/lind-wasm/issues/1246)). + +Run `make checkenv` to verify a machine. + ## Repository Structure and Components diff --git a/docs/contribute/debug-programs.md b/docs/contribute/debug-programs.md index ed5f32c29..b6425a44a 100644 --- a/docs/contribute/debug-programs.md +++ b/docs/contribute/debug-programs.md @@ -2,35 +2,52 @@ ## Debugging with GDB -To debug a WebAssembly module using GDB, ensure that your module is compiled with debugging information (e.g., using the -g flag during compilation). Additionally, Wasmtime itself must be compiled in debug mode (i.e., without the --release flag) to enable effective debugging of both the runtime and the module. This allows GDB to access symbol information from both your program and Wasmtime. +To debug a WebAssembly module using GDB, ensure that your module is compiled with debugging information (e.g., using the -g flag during compilation). Additionally, the runtime itself must be built in debug mode, with `make lind-debug`, to enable effective debugging of both the runtime and the module. This allows GDB to access symbol information from both your program and the runtime. > **Note:** Current limitations in GDB support for WebAssembly include lack of instruction-level inspection. Commands like `layout split` and `si` (step instruction) may break the terminal. It’s recommended to use `layout src` for source-level debugging. +> **Note:** GDB debugs the Rust runtime, not the C code running inside the WebAssembly module. + --- -### Running GDB with Wasmtime +### Running GDB with the runtime + +Build the debug runtime, then start GDB against it. Which invocation you need +depends on how the program was compiled. -Use the following command to start GDB with Wasmtime: +For a **dynamic build** — what `lind_compile` produces by default: ```sh -gdb --args ../wasmtime/target/debug/wasmtime run -D debug-info -O opt-level=0 malloc-test.wasm +make lind-debug +sudo gdb --args ./build/lind-boot --preload env=/lib/libc.cwasm --preload env=/lib/libm.cwasm malloc-test.cwasm +``` + +For a **static build** (`lind_compile -s`), the preloads are not needed: + +```sh +make lind-debug +sudo gdb --args ./build/lind-boot malloc-test.cwasm ``` **Explanation of arguments:** - `gdb --args`: Passes arguments to the program through GDB. -- `../wasmtime/target/debug/wasmtime run`: Runs your WebAssembly module using the Wasmtime binary. -- `-D debug-info`: Enables Wasmtime’s debug information support. -- `-O opt-level=0`: Disables optimizations for easier debugging. +- `sudo`: The runtime `chroot`s into `lindfs`, which requires root. `scripts/bin/lind_run` normally does this for you. +- `./build/lind-boot`: The runtime binary. `make lind-debug` installs the debug build here, at the same path as the release build. +- `--preload env=/lib/libc.cwasm --preload env=/lib/libm.cwasm`: The shared *lind-glibc* and libm a dynamic build resolves its imports against. `lind_run` passes these for you; running `lind-boot` directly under GDB means passing them yourself. +- `malloc-test.cwasm`: Your program, as a path *inside* `lindfs` (see [Getting Started](../getting-started.md#what-just-happened)). + +Run `./build/lind-boot --help` for the full set of runtime options. --- ### Example Debugging Session 1. **Start GDB** - Launch GDB with Wasmtime and your WebAssembly module: + Launch GDB with the runtime and your WebAssembly module (dynamic build shown, + see [above](#running-gdb-with-the-runtime) for the static variant): ```sh - gdb --args ../wasmtime/target/debug/wasmtime run -D debug-info -O opt-level=0 malloc-test.wasm + sudo gdb --args ./build/lind-boot --preload env=/lib/libc.cwasm --preload env=/lib/libm.cwasm malloc-test.cwasm ``` 2. **Set Breakpoints** diff --git a/docs/contribute/dev-container.md b/docs/contribute/dev-container.md index 6cc7dd617..a80a5dc0e 100644 --- a/docs/contribute/dev-container.md +++ b/docs/contribute/dev-container.md @@ -1,6 +1,16 @@ +# Development setup + To access an environment with the source code and tooling, there is a development image available as well. (Note: If you intend to use perf, you will need to install the appropriate `linux-tools-xxx` for your kernel) +> **Note:** Despite the page name, this is a plain Docker image — there is no +> `.devcontainer/` in the repository, so VS Code's "Reopen in Container" will not +> pick it up automatically. + +The published image is prebuilt: it already contains a compiled runtime, sysroot +and `lindfs`, so you can run a program without building anything. See +[Getting Started](../getting-started.md) for the quickest path. + ``` docker pull --platform=linux/amd64 securesystemslab/lind-wasm-dev # this might take a while ... docker run --platform=linux/amd64 -it --privileged --ipc=host --init --cap-add=SYS_PTRACE securesystemslab/lind-wasm-dev /bin/bash diff --git a/docs/contribute/e2e-testing.md b/docs/contribute/e2e-testing.md index 9e82d082d..1d2d6a9e7 100644 --- a/docs/contribute/e2e-testing.md +++ b/docs/contribute/e2e-testing.md @@ -75,9 +75,10 @@ Runs `scripts/build/make_glibc_and_sysroot.sh` to: -### make wasmtime +### make lind-boot -- Builds the embedded Wasmtime with Cargo (release) from `src/wasmtime/`. +- Builds the runtime with Cargo (release) from `src/lind-boot/`, which embeds the + customized Wasmtime, and installs it as `build/lind-boot`. ### make test @@ -132,7 +133,7 @@ High level: `docker buildx create --use --name lind-builder || docker buildx use lind-builder` #### Build with cache import/export -`docker buildx build --platform=linux/amd64 -f Docker/Dockerfile.e2e --cache-from type=local,src=~/.cache/docker-buildx --cache-to type=type=local,dest=.~/.cache/docker-buildx,mode=max .` +`docker buildx build --platform=linux/amd64 -f Docker/Dockerfile.e2e --cache-from type=local,src=~/.cache/docker-buildx --cache-to type=local,dest=~/.cache/docker-buildx,mode=max .` > CI typically uses type=gha; locally a local cache is simple and reliable. diff --git a/docs/contribute/running-on-native-linux.md b/docs/contribute/running-on-native-linux.md index 7464f9f4d..1bfeaefb9 100644 --- a/docs/contribute/running-on-native-linux.md +++ b/docs/contribute/running-on-native-linux.md @@ -120,19 +120,15 @@ The dependencies require a significant amount of storage so 15-20gb of free spac source "$HOME/.cargo/env" ``` - Install the pinned nightly toolchain and `rust-src` component: + The repository pins its toolchain in + [`rust-toolchain.toml`](https://github.com/Lind-Project/lind-wasm/blob/main/rust-toolchain.toml), + and `rustup` installs and selects that channel automatically the first time you + build inside the repository. Do not pin a different nightly by hand: + `rust-toolchain.toml` wins at build time, so a toolchain you select manually — + and any components you add to it — is silently ignored. - ```bash - rustup toolchain install nightly-2026-02-11 \ - --profile minimal \ - --component rust-src - ``` - - Verify the installation: - - ```bash - rustc +nightly-2026-02-11 --version - ``` + The `rust-src` component still has to be added explicitly. Because that must + happen against the pinned channel, it is done after cloning, in step 8. 4. __Install WABT 1.0.38__ @@ -243,16 +239,36 @@ The dependencies require a significant amount of storage so 15-20gb of free spac 8. __Build Lind-Wasm__ - From the repository root, build the development runtime, Lind filesystem, - custom glibc, and sysroot: + From the repository root, add `rust-src` to the pinned toolchain. Running this + inside the repository is what makes `rustup` resolve `rust-toolchain.toml`: ```bash cd ~/lind-wasm - make lind-debug + rustup component add rust-src + rustup show active-toolchain + ``` + + Check that the machine has everything else it needs. Every `FAIL` comes with + the command that fixes it: + + ```bash + make checkenv BUILD_ONLY=1 + ``` + + Then build the runtime, Lind filesystem, custom glibc, and sysroot: + + ```bash + make build ``` + Use `make build` rather than the individual targets: `make lind-boot sysroot` + skips the `lindfs` target, and `make sysroot` on its own fails on a clean + checkout because building the shared libc needs `lind-boot` to exist already. + For a debug runtime use `make lind-debug` instead — but do not mix the two, or + you will get `unknown import: debug::lind_debug_num` at run time. + See the project [`Makefile`](https://github.com/Lind-Project/lind-wasm/blob/main/Makefile) for the individual build - targets. + targets and build knobs. 9. __Install the Lind helper commands__ @@ -301,9 +317,12 @@ The dependencies require a significant amount of storage so 15-20gb of free spac 10. __Create the Lind filesystem compatibility link__ - The current runtime expects `lindfs` at - `/home/lind/lind-wasm/lindfs`. When the WSL username is not `lind`, - create a compatibility symbolic link: + The runtime `chroot`s into a path that is compiled in as a constant — + `LINDFS_ROOT` in `src/sysdefs/src/constants/lind_platform_const.rs`, currently + `/home/lind/lind-wasm/lindfs`. It is not read from the environment, so a + checkout anywhere else panics at startup with `The configured lindfs does not + exist`. Unless your home directory is literally `/home/lind`, create a + compatibility symbolic link: ```bash sudo mkdir -p /home/lind @@ -333,7 +352,7 @@ The dependencies require a significant amount of storage so 15-20gb of free spac ```bash cd ~/lind-wasm - lind_compile -s hello.c + lind_compile hello.c ``` Run the compiled program using its path inside `lindfs`: @@ -348,6 +367,18 @@ The dependencies require a significant amount of storage so 15-20gb of free spac Hello, World! ``` + Two things to expect the first time: + + - `lind_run` prompts for a password. It re-executes itself under `sudo -E` + because the runtime needs root to `chroot`. + - The path is `/hello.cwasm`, not `./hello.cwasm`. `lind_compile` copies its + output into `lindfs/`, and the runtime `chroot`s there, so paths are relative + to `lindfs` rather than to your shell's working directory. + + `lind_compile` builds dynamically by default, resolving *lind-glibc* from + `lindfs/lib/libc.cwasm` at run time. Pass `-s` for a statically linked binary, + which does not need the shared libc to be present. + 12. __Run the full test suite__ From the repository root, run the full test suite. It can take a while, so diff --git a/docs/contribute/testing.md b/docs/contribute/testing.md index c9500588d..7275fe2cf 100644 --- a/docs/contribute/testing.md +++ b/docs/contribute/testing.md @@ -31,18 +31,16 @@ docker build --platform=linux/amd64 -f Docker/Dockerfile.e2e -t dev --target bas docker run --platform=linux/amd64 -v $(PWD):/lind -w /lind -it dev /bin/bash ``` -5. Build toolchain (glibc and wasmtime) +5. Build the toolchain (runtime, glibc sysroot and `lindfs`) ``` # this may take a while ... -make lind-boot sysroot +make build ``` 6. Run the test suite ``` ./scripts/test/harnesses/wasmtestreport.py -./scripts/test/harnesses/wasmtestreport.py ``` Run `scripts/test/harnesses/wasmtestreport.py --help` to list available usage options. -Run `scripts/test/harnesses/wasmtestreport.py --help` to list available usage options. ## Directory Structure diff --git a/docs/contribute/toolchain.md b/docs/contribute/toolchain.md index 1f80ba674..079950887 100644 --- a/docs/contribute/toolchain.md +++ b/docs/contribute/toolchain.md @@ -50,10 +50,11 @@ options. along with headers and a pre-built C runtime into a sysroot directory structure as required by *Clang*. -4. __Build custom wasmtime__ (see [`make wasmtime`](https://github.com/Lind-Project/lind-wasm/blob/main/Makefile)) +4. __Build the runtime__ (see [`make lind-boot`](https://github.com/Lind-Project/lind-wasm/blob/main/Makefile)) - Builds `src/wasmtime` workspace. Custom dependencies `fdtables`, `RawPOSIX` - and `sysdefs` are included in the build automatically. + Builds the `src/lind-boot` workspace into `build/lind-boot`. The customized + `wasmtime` and the `fdtables`, `RawPOSIX`, `threei` and `sysdefs` crates are + included in the build automatically. A customized `wasm-opt` binary is included in the *lind-wasm* repo under diff --git a/docs/getting-started.md b/docs/getting-started.md index 64758a49f..8dd385415 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,28 +1,152 @@ # Getting Started -1. Make sure to read the [Basics](index.md) first. -2. If you want to start contributing, check out the [Contributor Instructions](contribute/index.md). -3. Continue reading to run a *__Hello World__* program in the Lind Sandbox. +By the end of this page you will have compiled a C program to WebAssembly against +*lind-glibc* and run it inside a Lind cage. -## Hello World! +If you want the concepts first — cages, grates, 3i, RawPOSIX — read the +[Basics](index.md). If you are here to contribute, also see the +[Contributor Instructions](contribute/index.md). -**1. Set up the environment** +There are two ways to get a working Lind: -Run the following commands in your terminal to download and shell into an environment -that comes with the Lind Sandbox. *You'll need [Docker installed](https://docs.docker.com/engine/install/).* +- **[Option A: the prebuilt development image](#option-a-prebuilt-development-image)** — + Docker, no build step. Start here. +- **[Option B: build from source](#option-b-build-from-source)** — build the image + yourself, or install natively on Linux. +## Prerequisites + +**Platform.** Lind-Wasm targets **linux/amd64 only**. This is why every `docker` +command below passes `--platform=linux/amd64`. On an arm64 host — an Apple +Silicon Mac, for example — the image still runs under emulation, but noticeably +more slowly. A *native* (non-Docker) install requires x86-64 Linux. + +**Disk.** Budget **~20 GB free**. The toolchain is large: clang+LLVM and the +Wasmtime build account for most of it. + +**Privileges.** Running a program needs root. `lind_run` re-executes itself under +`sudo` because the runtime `chroot`s into the Lind filesystem, so expect a +password prompt the first time. + +**Reference environment.** The setup is tested on Ubuntu 22.04, x86-64, 16 GB RAM. + +To check a machine against all of the above at once: + +```bash +make checkenv ``` + +Each prerequisite is reported as `OK` or `FAIL`, and every `FAIL` comes with the +command that fixes it. On a fresh checkout that has not been built yet, use +`make checkenv BUILD_ONLY=1` to skip the checks for build outputs. + +## Option A: prebuilt development image + +This is the fastest path and the one to use if you are evaluating Lind. + +```bash docker pull --platform=linux/amd64 securesystemslab/lind-wasm-dev # this might take a while ... -docker run --platform=linux/amd64 -it --privileged --ipc=host --init --cap-add=SYS_PTRACE securesystemslab/lind-wasm-dev /bin/bash -cd lind-wasm +docker run --platform=linux/amd64 -it --privileged --ipc=host --init \ + --cap-add=SYS_PTRACE securesystemslab/lind-wasm-dev /bin/bash +``` + +The shell starts in `/home/lind/lind-wasm`, the prebuilt checkout. + +What those flags are for: + +| Flag | Why | +| --- | --- | +| `--platform=linux/amd64` | see [Prerequisites](#prerequisites) | +| `--privileged` | the runtime `chroot`s into `lindfs` and runs as root | +| `--ipc=host` | shared-memory system calls | +| `--init` | reaps the processes that `fork`/`exec` tests leave behind | +| `--cap-add=SYS_PTRACE` | attaching `gdb`, `strace` or `perf` | + +!!! note "There is no build step" + + Run exactly as above and there is nothing to build. The image ships a + runtime, sysroot and `lindfs` that were built into `/home/lind/lind-wasm` + when the image was built (see `RUN make lind-debug` in + [`Docker/Dockerfile.dev`](https://github.com/Lind-Project/lind-wasm/blob/main/Docker/Dockerfile.dev)). + That is the directory the shell starts in. Skip straight to + [Run your first program](#run-your-first-program). + + You only need to rebuild after changing the source — see + [Option B](#option-b-build-from-source). + +!!! warning "A bind-mounted checkout has no build outputs" + + The prebuilt outputs live *inside the image*, at `/home/lind/lind-wasm`. + Mounting your own checkout over a different path gives you a tree that has + never been built: + + ```bash + # Your host checkout at /lind — no build/lind-boot, no sysroot, no lindfs + docker run --platform=linux/amd64 -v "$PWD:/lind" -w /lind -it \ + securesystemslab/lind-wasm-dev /bin/bash + ``` + + `make test` and `lind_run` then fail with `lind-boot` missing + ([#1355](https://github.com/Lind-Project/lind-wasm/issues/1355)). Either + run `make build` once inside the mounted tree, or drop `-v`/`-w` and use + the image's own checkout. + +## Option B: build from source + +### B1. Build the development image yourself + +Useful for building a specific branch. See +[Development setup](contribute/dev-container.md) for the `docker build` +invocation and its build args. + +### B2. Install natively on Linux + +Lind-Wasm builds and runs directly on Ubuntu 22.04, both native and under WSL2. +The [Native Linux setup](contribute/running-on-native-linux.md) guide covers the +dependencies, pinned toolchain versions and environment variables. + +### Building + +Either way, one command builds everything: + +```bash +make build ``` -This is a development environment with tooling and source code available. Additional instructions can be found [here](contribute/dev-container.md). +That builds the runtime (`lind-boot`, Wasmtime, RawPOSIX, 3i), the *lind-glibc* +sysroot, and the `lindfs` skeleton the runtime `chroot`s into. + +!!! warning "Use `make build`, not the individual targets" + + `make lind-boot sysroot` looks equivalent but skips the `lindfs` target, so + `lindfs/etc`, `dev/null`, the locale data and the timezone database are never + created, and programs fail in confusing ways. `make sysroot` on its own fails + outright on a clean checkout, because building the shared libc needs + `lind-boot` to already exist. `make all` is an alias for `make build`. + + For a debug runtime, use `make lind-debug` instead — but do not mix the two, + see [Troubleshooting](#troubleshooting). Other targets and build knobs + (`FDTABLES_IMPL`, `NO_LOGGING`, `WITH_FPCAST`) are documented in the + [`Makefile`](https://github.com/Lind-Project/lind-wasm/blob/main/Makefile). + +!!! danger "The checkout must live at `/home/lind/lind-wasm`" + + The path the runtime `chroot`s into is currently compiled in as a constant + (`LINDFS_ROOT` in `src/sysdefs/src/constants/lind_platform_const.rs`), so a + checkout anywhere else panics at startup with + `The configured lindfs does not exist`. If yours is elsewhere, symlink it: + + ```bash + sudo mkdir -p /home/lind + sudo ln -sfnT "$PWD" /home/lind/lind-wasm + ``` + + `make checkenv` checks this for you. This is a known limitation, not a design + goal; making the path configurable is tracked upstream. -**2. Write a program** +## Run your first program -In the same terminal, use e.g. `vi` to write a `hello.c` program to be executed -in the Lind sandbox. You can also just paste the snippet below. +Write a C program: ```bash cat << EOF > hello.c @@ -35,40 +159,75 @@ int main() { EOF ``` -**3. Compile the Lind-Wasm runtime** - -The Lind-Wasm runtime must be compiled before running the program. Use this path for a first build: +Compile and run it: ```bash -make lind-boot sysroot +lind-clang hello.c +lind-wasm hello.cwasm ``` -This builds the runtime (`lind-boot`, Wasmtime, RawPOSIX, 3i, etc.) and the lind-glibc sysroot. +```text +Hello, World! +``` -For a full build, including both lind-glibc and Rust code, use `make all`. More build targets are documented in `lind-wasm/Makefile`. +`lind-clang` and `lind-wasm` are the names the development image installs. Outside +the container, call the scripts directly — `scripts/bin/lind_compile` and +`scripts/bin/lind_run` — or symlink them onto your `PATH` as the +[Native Linux setup](contribute/running-on-native-linux.md) guide describes. -**4. Compile and run** +### What just happened -Inside the development container, `lind-clang` is an alias for `scripts/lind_compile`, and `lind-wasm` is an alias for `scripts/lind_run`. If you are running outside the container, use the scripts directly or add the aliases to your shell. +1. `lind_compile` compiled `hello.c` into a WebAssembly binary linked against + *lind-glibc*, optimized it with Lind's custom `wasm-opt`, and ahead-of-time + compiled the result to `hello.cwasm`. The output was copied into the Lind + filesystem root, `lindfs/`. +2. `lind_run` executed it on the *Lind-Wasm* runtime, with system calls mediated + by *3i* and serviced by the *RawPOSIX* microvisor. -```bash -lind-clang hello.c -lind-wasm hello.cwasm -``` +Two details worth knowing early: + +- **Paths are relative to `lindfs`, not your shell.** The runtime `chroot`s into + `lindfs` and changes directory to `/`, so `hello.cwasm` and `/hello.cwasm` both + refer to `lindfs/hello.cwasm`. Your host working directory is invisible to the + program. +- **`lind_compile` builds dynamically by default**, producing a position-independent + executable that resolves *lind-glibc* from `lindfs/lib/libc.cwasm` at run time. + Pass `-s` for a traditional statically linked binary instead. Both run the same + way; the static build does not need the shared libc to be present. + +## Troubleshooting + +**`The configured lindfs does not exist: /home/lind/lind-wasm/lindfs`** — +your checkout is not at the compiled-in path. Create the symlink shown in +[Option B](#option-b-build-from-source). + +**`lind-clang: command not found`** — those names exist only inside the +development image. Use `scripts/bin/lind_compile` and `scripts/bin/lind_run`, or +add the symlinks. + +**An unexpected password prompt when running a program** — expected. `lind_run` +re-executes itself under `sudo -E` because the runtime needs root to `chroot`. -*Here is what happens under the hood:* +**`WARNING: The requested image's platform (linux/amd64) does not match the +detected host platform`** — you are on an arm64 host. Add +`--platform=linux/amd64`; the image runs under emulation, more slowly. -1. `lind-clang`(aka `scripts/bin/lind_compile`) compiles `hello.c` into a WebAssembly (WASM) -binary that is linked against *lind-glibc*, and put into lind file system root(`lind-wasm/lindfs`). -1. `lind-wasm`(aka `scripts/bin/lind_run`) runs the compiled wasm using *Lind-Wasm* runtime -and the *RawPOSIX* microvisor. +**`unknown import: debug::lind_debug_num`** — a debug-built sysroot is being used +with a release runtime, or the reverse. Rebuild consistently: `make build` for +release, `make lind-debug` for debug — not one after the other. ---- +**`[LIND DEBUG NUM]` / `[LIND DEBUG STR]` lines before your output** — not errors. +The published development image is built with `make lind-debug`, which enables +debug logging. -To compile a Rust crate into a *lind-glibc* linked WASM binary, follow this guide: [Compiling Rust Code with `lind-glibc`](./contribute/compile-with-rust.md) +If none of these match, please +[open an issue](https://github.com/Lind-Project/lind-wasm/issues) — including the +output of `make checkenv` makes it much easier to help. -## What's next! +## What's next -The Lind documentation is currently under heavy construction. Please [submit an -issue](https://github.com/Lind-Project/lind-wasm/issues), if something doesn't seem right or is missing. -More detailed usage guides will follow soon! +- Compile a Rust crate against *lind-glibc*: + [Compiling Rust programs](contribute/compile-with-rust.md) +- Run the test suite: [Testing](contribute/testing.md) +- Understand the pieces: [Internal Documentation](internal/index.md) +- Contribute a change: [Contributor Instructions](contribute/index.md) diff --git a/mkdocs.yml b/mkdocs.yml index 08e2f02a8..d8b85196c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -14,6 +14,11 @@ plugins: nav: - Home: index.md - Getting Started: getting-started.md + # Installation pages sit next to Getting Started rather than under Contributing: + # they are how a user installs Lind, not how they contribute to it. The files + # stay under docs/contribute/ so their published URLs do not change. + - Development setup: contribute/dev-container.md + - Native Linux setup: contribute/running-on-native-linux.md - Internal Documentation: - internal/index.md - libc: internal/libc.md @@ -30,8 +35,6 @@ nav: - C++ support: internal/libcpp.md - Contributing: - contribute/index.md - - Development setup: contribute/dev-container.md - - Native Linux setup: contribute/running-on-native-linux.md - Rust style guide: contribute/styleguide.md - Lind toolchain: contribute/toolchain.md - Compiling Rust programs: contribute/compile-with-rust.md diff --git a/scripts/bin/lind_checkenv b/scripts/bin/lind_checkenv new file mode 100755 index 000000000..99bc42719 --- /dev/null +++ b/scripts/bin/lind_checkenv @@ -0,0 +1,301 @@ +#!/usr/bin/env bash +set -Eeuo pipefail + +# Check that this machine can build and run lind-wasm. +# +# Reports one line per prerequisite and exits non-zero if any check FAILs, so it +# can gate a build. WARN entries do not affect the exit status. +# +# Usage: +# lind_checkenv # check everything +# lind_checkenv --build # only what is needed to *build* (skip built artifacts) +# +# No assumption about current working directory. + +usage() { + cat >&2 <&2; usage; exit 2 ;; + esac +done + +# --- repo root discovery (env var -> script dir -> git), matching lind_run --- +if [[ -n "${LIND_WASM_ROOT:-}" && -d "${LIND_WASM_ROOT}" ]]; then + REPO_ROOT="${LIND_WASM_ROOT}" +else + SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)" + if [[ -f "${SCRIPT_DIR}/../../Makefile" ]]; then + REPO_ROOT="$(cd -- "${SCRIPT_DIR}/../.." && pwd)" + elif command -v git >/dev/null 2>&1; then + REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || true)" + else + REPO_ROOT="" + fi +fi + +if [[ -z "${REPO_ROOT}" || ! -d "${REPO_ROOT}" ]]; then + echo "error: cannot locate lind-wasm repo root; export LIND_WASM_ROOT=/path/to/lind-wasm" >&2 + exit 2 +fi + +# --- reporting --- +FAILURES=0 +WARNINGS=0 + +# Colors only when stdout is a terminal, so piping to a file stays readable. +if [[ -t 1 ]]; then + C_OK=$'\033[32m'; C_FAIL=$'\033[31m'; C_WARN=$'\033[33m'; C_OFF=$'\033[0m' +else + C_OK=""; C_FAIL=""; C_WARN=""; C_OFF="" +fi + +# ok