Skip to content

Building from Source

Follow these instructions to either build SWS project from the source or the HTML documentation.

Building project from source

If you want to build SWS from the source, all you need is a Rust 2021 Edition installed.

So make sure to install Rust 1.74.0 or newer (or nightly) along with the toolchain(s) of your preference.

Then clone the repository and use Cargo to build the project from the source.

git clone https://github.com/static-web-server/static-web-server.git
cd static-web-server
cargo build --release

Finally, the release binary should be available at target/release/static-web-server or under your toolchain directory chosen.

Don't use the project's Makefile

Please don't use the project's Makefile since it's only intended for development and some on-demand tasks.

Cargo features

When building from the source, all features are enabled by default. However, you can disable just the ones you don't need from the lists below.

Feature Description
Default
default Activates the default features by omission.
all Activates all available features including the experimental feature. This is the default feature used when building SWS binaries.
experimental Activates all SWS experimental features. Make sure to also provide the required RUSTFLAGS if the feature requires so.
HTTP2/TLS
http2 Activates the HTTP2 and TLS feature.
Compression
compression Activates auto-compression and compression static with all supported algorithms.
compression-brotli Activates auto-compression/compression static with only the brotli algorithm.
compression-deflate Activates auto-compression/compression static with only the deflate algorithm.
compression-gzip Activates auto-compression/compression static with only the gzip algorithm.
compression-zstd Activates auto-compression/compression static with only the zstd algorithm.
Directory Listing
directory-listing Activates the directory listing feature.
Basic Authorization
basic-auth Activates the Basic HTTP Authorization Schema feature.
Fallback Page
fallback-page Activates the Fallback Page feature.

Disable all default features

For example, if you want to run or build SWS without the default features like compression, http2, etc then just try:

# run
cargo run --no-default-features -- -h

# or build
cargo build --release --no-default-features

# or including all features (example)
RUSTFLAGS="--cfg tokio_unstable" \
    cargo build -vv --release --features all 

Cross-compiling

If you want to cross-compile SWS then consider using Zig as linker for easier cross compiling.

Let's say, you want to cross-compile SWS from macOS to Linux. Then follow these steps.

  1. Add the necessary toolchain, for example just type: rustup target add x86_64-unknown-linux-gnu or rustup target add x86_64-unknown-linux-musl if a statically-linked binary is wanted.
  2. Install the latest Zig version via brew install zig
  3. Install cargo-zigbuild via cargo install cargo-zigbuild
  4. Finally, build SWS as follows:
    # dynamically-linked binary
    cargo zigbuild --verbose --release --target=x86_64-unknown-linux-gnu
    # or statically-linked binary
    cargo zigbuild --verbose --release --target=x86_64-unknown-linux-musl
    

Built binaries can be found under the corresponding toolchain directory inside target/.

Testing

# run tests for default features
cargo test
# or run tests for all features including experimental ones
RUSTFLAGS="--cfg tokio_unstable" cargo test --features all
# or run specific tests
cargo test --test rewrites

Building documentation from source

All HTML documentation is located in the docs/ project's directory and is built using Material for MkDocs.

It's only necessary to have Docker installed.

Building documentation

By default the docs will be built in the /tmp/docs directory, to do so follow these steps.

git clone https://github.com/static-web-server/static-web-server.git
cd static-web-server
mkdir /tmp/docs
docker run -it --rm \
    -v $PWD/docs:/docs \
    -v /tmp/docs:/tmp/docs squidfunk/mkdocs-material build

Output the docs in a different directory

If you want to output the docs in a different directory then append the --site-dir=/new/dir/path/ argument to the "squidfunk/mkdocs-material" build command and make sure to provide the new directory path.

Development server

If you want to improve the documentation then run the built-in development server via docs/docker-compose.yml.

git clone https://github.com/static-web-server/static-web-server.git
cd static-web-server
docker-compose -f docs/docker-compose.yml up

Now the server will be available at localhost:8000