247 lines
8.4 KiB
Markdown
247 lines
8.4 KiB
Markdown
<!--
|
|
Copyright 2022, Proofcraft Pty Ltd
|
|
Copyright 2020, Data61, CSIRO (ABN 41 687 119 230)
|
|
|
|
SPDX-License-Identifier: CC-BY-SA-4.0
|
|
-->
|
|
|
|
<!-- This file is also included on https://docs.sel4.systems/projects/buildsystem/host-dependencies.html -->
|
|
|
|
# Proof and Isabelle Dependencies
|
|
|
|
## Proof Dependencies
|
|
|
|
### Linux Packages - Debian
|
|
|
|
On **Buster** or **Bullseye**, to run all proofs against the
|
|
**ARMv7-A** architecture you will need to install the following packages:
|
|
|
|
```bash
|
|
sudo apt-get install \
|
|
python3 python3-pip python3-dev \
|
|
gcc-arm-none-eabi build-essential libxml2-utils ccache \
|
|
ncurses-dev librsvg2-bin device-tree-compiler cmake \
|
|
ninja-build curl zlib1g-dev texlive-fonts-recommended \
|
|
texlive-latex-extra texlive-metapost texlive-bibtex-extra \
|
|
rsync
|
|
```
|
|
|
|
There is no package for the MLton compiler on Buster or Bullseye, so you will
|
|
need to install it from the [MLton website](http://www.mlton.org).
|
|
|
|
The Haskell Stack package is unavailable on Bullseye and out-of-date on Buster,
|
|
so you will need to install it from the [Haskell Stack
|
|
website](https://docs.haskellstack.org/en/stable/).
|
|
|
|
Continue with the [python setup step](#python) below.
|
|
|
|
### Linux Packages - Ubuntu
|
|
|
|
These instructions are intended for Ubuntu LTS versions 20.04, and 22.04.
|
|
|
|
To run all proofs against the **ARMv7-A** architecture you will need to install
|
|
the following packages:
|
|
|
|
```bash
|
|
sudo apt-get install \
|
|
python3 python3-pip python3-dev \
|
|
gcc-arm-none-eabi build-essential libxml2-utils ccache \
|
|
ncurses-dev librsvg2-bin device-tree-compiler cmake \
|
|
ninja-build curl zlib1g-dev texlive-fonts-recommended \
|
|
texlive-latex-extra texlive-metapost texlive-bibtex-extra \
|
|
mlton-compiler haskell-stack repo
|
|
```
|
|
|
|
Continue with the [python setup step](#python) below.
|
|
|
|
### macOS packages
|
|
|
|
The proofs work well on Intel and Apple Silicon Macs.
|
|
|
|
These instructions use Homebrew, which can be installed from [their website][homebrewwebsite].
|
|
To install the main dependencies and cross compilers, use the following steps:
|
|
|
|
```sh
|
|
brew install git libxml2 ncurses librsvg dtc cmake ninja texlive rsync python ccache \
|
|
zstd haskell-stack mlton arm-none-eabi-gcc repo
|
|
|
|
brew install --cask gcc-arm-embedded
|
|
|
|
brew tap messense/macos-cross-toolchains
|
|
brew install x86_64-unknown-linux-gnu aarch64-unknown-linux-gnu
|
|
|
|
brew tap riscv/riscv
|
|
brew install riscv-tools
|
|
```
|
|
|
|
The instructions in the sections below apply for both Linux and macOS.
|
|
|
|
[homebrewwebsite]: https://brew.sh
|
|
|
|
### Python
|
|
|
|
The build system for the seL4 kernel requires several python packages:
|
|
|
|
```bash
|
|
pip3 install --user --upgrade pip
|
|
pip3 install --user sel4-deps
|
|
```
|
|
|
|
### Haskell Stack
|
|
|
|
After installing [haskell-stack](https://docs.haskellstack.org/en/stable/)
|
|
(already included in the packages above on Mac and Ubuntu), make sure you've
|
|
adjusted your `PATH` to include `$HOME/.local/bin`, that you're running an
|
|
up-to-date version, and that you have installed cabal:
|
|
|
|
```bash
|
|
stack upgrade --binary-only
|
|
which stack # should be $HOME/.local/bin/stack
|
|
stack install cabal-install
|
|
```
|
|
|
|
## Checking out the repository collection
|
|
|
|
The seL4 repositories use the [Google `repo` tool][repo] for configuration
|
|
control and managing sets of repositories. For verification, this means in
|
|
particular managing the correct combinations of the proofs, the kernel sources,
|
|
and the Isabelle/HOL theorem prover.
|
|
|
|
The [verification-manifest] repository records which versions of these are known
|
|
to work well together.
|
|
|
|
To check out a consistent set of repositories, run the following steps:
|
|
|
|
```sh
|
|
mkdir verification
|
|
cd verification
|
|
repo init -u https://git@github.com/seL4/verification-manifest.git
|
|
repo sync
|
|
```
|
|
|
|
If you are developing proofs, intending to contribute, and have `ssh` set up
|
|
for GitHub, use
|
|
|
|
```sh
|
|
repo init -m devel.xml -u ssh://git@github.com/seL4/verification-manifest.git
|
|
```
|
|
|
|
instead for the `init` line. The `-m devel.xml` gives you the `master` branch of
|
|
the `l4v` repository instead of the last known-good version. To set up `git` for
|
|
`ssh` make sure to use the `ssh://` protocol explicitly as above instead of just
|
|
`git@github.com`, because the short form seems to confuse `repo`.
|
|
|
|
If you are looking to use the proofs for a specific release version of seL4, use
|
|
the `-m` option to select the corresponding manifest file in the
|
|
[verification-manifest] repository.
|
|
|
|
[repo]: https://gerrit.googlesource.com/git-repo/+/HEAD/README.md
|
|
[verification-manifest]: https://github.com/seL4/verification-manifest
|
|
|
|
## Isabelle Setup
|
|
|
|
After the repository is set up using `repo` with the [verification-manifest]
|
|
repository, you should have following directory structure, where `l4v` is the
|
|
repository you are currently looking at:
|
|
|
|
```bash
|
|
verification/
|
|
HOL4/
|
|
graph-refine/
|
|
isabelle/
|
|
l4v/
|
|
seL4/
|
|
```
|
|
|
|
To set up Isabelle for use in `l4v/`, assuming you have no previous
|
|
installation of Isabelle, run the following commands in the directory
|
|
`verification/l4v/`:
|
|
|
|
```bash
|
|
mkdir -p ~/.isabelle/etc
|
|
cp -i misc/etc/settings ~/.isabelle/etc/settings
|
|
./isabelle/bin/isabelle components -a
|
|
./isabelle/bin/isabelle jedit -bf
|
|
./isabelle/bin/isabelle build -bv HOL
|
|
```
|
|
|
|
These commands perform the following steps:
|
|
|
|
* create an Isabelle user settings directory.
|
|
* install L4.verified Isabelle settings.
|
|
These settings initialise the Isabelle installation to use the standard
|
|
Isabelle `contrib` tools from the Munich Isabelle repository and set up
|
|
paths such that multiple Isabelle repository installations can be used
|
|
side by side without interfering with each other.
|
|
* download `contrib` components from the Isabelle repository. This includes
|
|
Scala, a Java JDK, PolyML, and multiple external provers. You should
|
|
download these, even if you have these tools previously installed
|
|
elsewhere to make sure you have the right versions. Depending on your
|
|
internet connection, this may take some time.
|
|
* compile and build the Isabelle PIDE jEdit interface.
|
|
* build basic Isabelle images to ensure that
|
|
the installation works. This may take a few minutes.
|
|
|
|
Alternatively, it is possible to use the official Isabelle2022 release
|
|
bundle for your platform from the [Isabelle website][isabelle]. In this case, the
|
|
installation steps above can be skipped, and you would replace the directory
|
|
`verification/isabelle/` with a symbolic link to the Isabelle home directory
|
|
of the release version. Note that this is not recommended for development,
|
|
since Google repo will overwrite this link when you synchronise repositories
|
|
and Isabelle upgrades will have to be performed manually as development
|
|
progresses.
|
|
|
|
You are now set up to process proofs, for instance by following the instructions
|
|
at the bottom of the main [README page][running-proofs].
|
|
|
|
The sections below contain a few tools and tips for proof development on seL4.
|
|
|
|
[running-proofs]: https://github.com/seL4/l4v/blob/master/README.md#running-the-proofs
|
|
|
|
## PIDE Tools
|
|
|
|
The following tools and tips can make writing proofs easier and more efficient
|
|
when using the Isabelle PIDE jEdit interface.
|
|
|
|
### WhiteSpace plugin
|
|
|
|
The WhiteSpace plugin can highlight normally invisible whitespace characters
|
|
such as tabs and spaces, and can remove trailing whitespace on save. To
|
|
install and configure the WhiteSpace plug-in for jEdit, follow
|
|
the instructions below.
|
|
|
|
1. Go to Plugins -> Plugin manager -> Install.
|
|
2. Search for `WhiteSpace` and install the plugin.
|
|
3. Go to Plugins -> Plugin Options -> WhiteSpace -> On save actions.
|
|
4. Check "Remove trailing whitespace" and click Apply.
|
|
|
|
### Key bindings for Navigator
|
|
|
|
The Isabelle PIDE provides "Back" and "Forward" actions that allow you to
|
|
easily navigate to previous positions in your edit history. Follow the steps
|
|
below to bind a key to the "Back" function. We recommend ``[ctrl]+[`]``.
|
|
|
|
1. Go to Utilities -> Global Options -> jEdit -> Shortcuts.
|
|
2. Select Action Set -> Plugin: Navigator.
|
|
3. Set a shortcut for `Back`.
|
|
|
|
### Go-to-error macro
|
|
|
|
Run the following commands in the directory `verification/l4v/`:
|
|
|
|
```sh
|
|
mkdir -p ~/.isabelle/jedit/macros
|
|
cp misc/jedit/macros/goto-error.bsh ~/.isabelle/jedit/macros/.
|
|
```
|
|
|
|
You can add keybindings for this macro in the usual way, by going to
|
|
`Utilities -> Global Options -> jEdit -> Shortcuts`.
|
|
|
|
Additionally, our fork of Isabelle/jEdit has an updated indenter which is more
|
|
proof-context aware than the 'original' indenter. Pressing `ctrl+i` while some
|
|
`apply`-script text is selected should auto-indent the script while respecting
|
|
subgoal depth and maintaining the relative indentation of multi-line `apply`
|
|
statements.
|
|
|
|
[isabelle]: http://isabelle.in.tum.de
|