Skip to content

Latest commit

 

History

History
357 lines (231 loc) · 11.3 KB

building.md

File metadata and controls

357 lines (231 loc) · 11.3 KB
Raw

Slint Build Guide

This page explains how to build and test Slint.

Prerequisites

Installing Rust

Install Rust by following the Rust Getting Started Guide. If you already have Rust installed, make sure that it's at least version 1.77 or newer. You can check which version you have installed by running rustc --version.

Once this is done, you should have the rustc compiler and the cargo build system installed in your path.

Dependencies

  • FFMPEG

  • Skia (only few available binaries):

Platform Binaries
Windows x86_64-pc-windows-msvc
Linux Ubuntu 16+
CentOS 7, 8		 x86_64-unknown-linux-gnu
macOS x86_64-apple-darwin
Android aarch64-linux-android
x86_64-linux-android
iOS aarch64-apple-ios
x86_64-apple-ios
WebAssembly wasm32-unknown-emscripten
  • Use Skia capable toolchain rustup default stable-x86_64-pc-windows-msvc

Linux

For Linux a few additional packages beyond the usual build essentials are needed for development and running apps:

  • xcb (libxcb-shape0-dev libxcb-xfixes0-dev on debian based distributions)
  • xkbcommon (libxkbcommon-dev on debian based distributions)
  • fontconfig library (libfontconfig-dev on debian based distributions)
  • (optional) Qt will be used when qmake is found in PATH
  • FFMPEG library clang libavcodec-dev libavformat-dev libavutil-dev libavfilter-dev libavdevice-dev libasound2-dev pkg-config
  • openssl (libssl-dev on debian based distributions)

xcb and xcbcommon aren't needed if you are only using backend-winit-wayland without backend-winit-x11.

macOS

  • Make sure the "Xcode Command Line Tools" are installed: xcode-select --install
  • (optional) Qt will be used when qmake is found in PATH
  • FFMPEG brew install pkg-config ffmpeg

Windows

  • See System Link

  • Make sure the MSVC Build Tools are installed: winget install Microsoft.VisualStudio.2022.BuildTools

  • (optional) make sure Qt is installed and qmake is in the Path

  • FFMPEG

    • Option 1:

      • install vcpkg
      • vcpkg install ffmpeg --triplet x64-windows
      • Make sure VCPKG_ROOT is set to where vcpkg is installed
      • Make sure %VCPKG_ROOT%\installed\x64-windows\bin is in your path

    • Option 2:

C++ API (optional)

To use Slint from C++, the following extra dependencies are needed:

  • cmake (3.21 or newer)
  • Ninja (Optional, or remove the -GNinja when invoking cmake)
  • A C++ compiler that supports C++20 (e.g., MSVC 2022 17.3 on Windows, or GCC 10)

Node.js API (optional)

To use Slint from Node.js, the following extra dependencies are needed.

  • Node.js (including npm) At this time you will need to use the version 16.
  • Python

Symlinks in the repository (Windows)

The Slint repository makes use of symbolic links to avoid duplication. On Windows, this require to set a git config before cloning, and have Windows switched in developer mode or do the git clone as Administrator

git clone -c core.symlinks=true https://github.com/slint-ui/slint

More info: https://github.com/git-for-windows/git/wiki/Symbolic-Links

Building and Testing

Most of the project is written in Rust, and compiling and running the test can done with cargo.

cargo build
cargo test

Important: Note that cargo test does not work without first calling cargo build because the the required dynamic library won't be found.

Building workspace

To build all examples install the entire workplace to executables (excluding UEFI-demo - different target)

cargo build --workspace --exclude uefi-demo --release

C++ Tests

The C++ tests are contained in the test-driver-cpp crate. It requires the Slint C++ library to be built, which isn't done by default. Build it explicitly before running the tests:

cargo build --lib -p slint-cpp
cargo test -p test-driver-cpp

Node.js Tests

The Node.js tests are contained in the test-driver-nodejs crate. The node integration will be run automatically when running the tests:

cargo build -p test-driver-nodejs

More Info About Tests

For more details about the tests and how they are implemented, see testing.md.

C++ API Build

The Slint C++ API is implemented as a normal cmake build:

mkdir cppbuild && cd cppbuild
cmake -GNinja ..
cmake --build .

The build will call cargo to build the Rust libraries, and build the examples. To install the libraries and everything you need, use:

cmake --install .

You can pass -DCMAKE_INSTALL_PREFIX in the first cmake command in order to choose the installation location.

Node.js API Build

The Slint Node.js API is implemented as npm build. You can build it locally using the following command line:

cd api/node
npm install

To build your own project against the Git version of the Slint Node.js API, add the path to the api/node folder in the dependencies section of your package.json:

    "dependencies": {
        "slint-ui": "/path/to/api/node"
    },

Cross-Compiling

Slint can be cross-compiled to different target architectures and environments. For the Rust build we have had a good experience using cross. For convenience we're including a Cross.toml configuration file for cross in the source tree along with Docker containers that allow targeting a Debian ARMv7 and ARMv8 based Distribution with X11 or Wayland, out of the box. If you want to use the default Cross containers or your own, make sure the dependencies are in the container.

This includes for example the Raspberry Pi OS. Using the following steps you can run the examples on a pi:

cross build --target armv7-unknown-linux-gnueabihf --workspace --exclude slint-node --exclude pyslint --release
scp target/armv7-unknown-linux-gnueabihf/release/printerdemo [email protected]:.

Finally on a shell on the Pi:

DISPLAY=:0 ./printerdemo

Examples

See the examples folder for examples to build, run and test.

Running the Viewer

Slint also includes a viewer tool that can load .slint files dynamically at run-time. It's a cargo-integrated binary and can be run directly on the .slint files, for example:

cargo run --release --bin slint-viewer -- demos/printerdemo/ui/printerdemo.slint

Generating the Documentation

The Slint documentation consists of five parts:

  • The quickstart guide
  • The Rust API documentation
  • The C++ API documentation
  • The Node.js API documentation
  • The DSL documentation

The quickstart guide is part of the DSL documentation.

Quickstart and DSL docs

The quickstart and DSL docs are written in markdown and built with Sphinx, using the myst parser extension.

Prerequisites:

Use the following command line to build the documentation using rustdoc to the target/slintdocs/html folder:

cargo xtask slintdocs --show-warnings

Rust API docs

Run the following command to generate the documentation using rustdoc in the target/doc/ sub-folder:

RUSTDOCFLAGS="--html-in-header=$PWD/docs/resources/slint-docs-preview.html --html-in-header=$PWD/docs/resources/slint-docs-highlight.html" cargo doc --no-deps --features slint/document-features,slint/log

Note: --html-in-header arguments passed to rustdoc via RUSTDOCFLAGS are used to enable syntax highlighting and live-preview for Slint example snippets.

C++ API docs

Prerequisites:

Run the following command to generate the documentation using sphinx/exhale/breathe/doxygen/myst_parser in the target/cppdocs sub-folder:

cargo xtask cppdocs

Node.js API docs

Run the following commands from the /api/node sub-folder to generate the docs using typedoc in the /api/node/docs sub-folder:

npm install
npm run docs

Building search database

We use Typesense for document search.

Infrastructure

  • Typesense Server: The Typesense Server will hold the search index.
  • Accessibility: The Typesense server must be accessible from the search bar in documentation site.
  • Docker: Docker is needed to run the Typesense Docsearch Scraper.
  • Typesense Docsearch Scraper: This tool will be used to index the documentation website.

Pre-requisites

pip3 install jq

Testing Locally

curl http://localhost:8108/health

Testing on Typesense Cloud

Creating search index

A helper script is located under search sub-folder that will (optionally) build the docs (currently only Slint docs), scrape the documents, and upload the search index to Typesense server.

The script accepts the following arguments

-a : API key to authenticate with Typesense Server (default: xyz)

-b : Build Slint docs (for testing locally set this flag ) (default: false)

-c : Location of config file (default: docs/search/scraper-config.json)

-d : Location of index.html of docs (default: target/slintdocs/html)

-i : Name of the search index (default: local)

-p : Port to access Typesense server (default: 8108)

-r : Remote Server when using Typesense Cloud

-u : URL on which the docs will be served (default: http://localhost:8000)

Example when running locally

docs/search/docsearch-scraper.sh -b

Example when running on Typesense Cloud, where $cluster_name is the name of the cluster on Typesense Cloud

docs/search/docsearch-scraper.sh -a API_KEY -b -r TYPESENSE_CLOUD_HOST_NAME

Testing search functionality

Run http server

python3 -m http.server -d target/slintdocs/html

Open browser (http://localhost:8000) and use the search bar to search for content