diff --git a/tobi/doc/Makefile b/tobi/doc/Makefile new file mode 100644 index 0000000000000000000000000000000000000000..68d1b9fa853df64aba3a27940809bffb9d0da70a --- /dev/null +++ b/tobi/doc/Makefile @@ -0,0 +1,38 @@ +COMPONENT_NAME=Tobi +MD_FILES:=$(wildcard src/*.md) + +# Define a variable that contains a space. +# Needed because we can't write spaces directly in $(subst). +space:=' ' + +.PHONY: all +all: $(patsubst src/%.md,html/%.html,$(MD_FILES)) html/style.css + +# All rules that generate files in the 'html' directory depend on the 'html' directory. +# Those dependencies must be of the form '| html', meaning "ignore the timestamp". +# A normal dependency would not work because of the way directory timestamps change. +html: + mkdir html + +# To generate an html file from a markdown file, we call 'markdown', +# which must be installed (e.g. with 'sudo apt install markdown'). +# +# We also insert some common headers and footers. +# We generate a title from the component name and the filename, +# by replacing underscores with spaces. +# +# We also replace URLs of the form X.md with X.html. +# This allows links in the markdown version to link to the markdown version, +# and links in the HTML version to link to the HTML version. +html/%.html: src/%.md src/header1.html src/header2.html src/footer.html | html + cat src/header1.html > $@ + echo '$(COMPONENT_NAME): $(subst _,$(space),$*)' >> $@ + cat src/header2.html >> $@ + sed 's/\.md)/\.html)/g' src/$*.md | markdown >> $@ + cat src/footer.html >> $@ + +# Copy src/style.css into html/style.css. +# We could instead commit the file directly into html/, +# but being able to 'rm -rf html' is convenient. +html/style.css: src/style.css | html + cp $< $@ diff --git a/tobi/doc/src/footer.html b/tobi/doc/src/footer.html new file mode 100644 index 0000000000000000000000000000000000000000..308b1d01b6ca1e7ab1b1fa896e6a8497bbcd1a37 --- /dev/null +++ b/tobi/doc/src/footer.html @@ -0,0 +1,2 @@ + + diff --git a/tobi/doc/src/get_familiar_with_tobi.md b/tobi/doc/src/get_familiar_with_tobi.md new file mode 100644 index 0000000000000000000000000000000000000000..142f210078a8edf596532e0bceec4199865bcc64 --- /dev/null +++ b/tobi/doc/src/get_familiar_with_tobi.md @@ -0,0 +1,226 @@ +# Tutorial: get familiar with Tobi + +In this Tutorial, we will install Tobi and use it to speed up compilation of `octez-node` +by installing `octez-libs`. + +All instructions from this tutorial must be run from the root of the repository. + +## Install Tobi + +Run: + + make build-deps + eval $(opam env) + dune exec tobi -- install tobi + +The last command outputs: + + Installing: tobi + +Let's check that Tobi was installed correctly. +Run: + + tobi --help + +## Install Tobi with Tobi + +Let's install Tobi again, but with Tobi. +And let's do it in verbose mode, to learn what Tobi is doing under the hood. +Run: + + tobi install tobi -v + +This outputs: + + Installing: tobi.HEAD (explicitly requested) + Found in cache. + -> _opam/lib/tobi/META + -> _opam/lib/tobi/dune-package + -> _opam/bin/tobi + +The first line is familiar: Tobi tells us that it is installing `tobi`. +But this time, it also tells us which version of Tobi it is installing: `HEAD`. +This is a Git reference to the current commit. + +The second line is new: Tobi tells us that it was able to find an already-compiled +version of Tobi in its cache. This means that it didn't have to recompile anything. + +The last three lines are Tobi telling us which files it installed. +Let's take a look at those files. +Run: + + ls -l _opam/lib/tobi/{META,dune-package} _opam/bin/tobi + +This outputs something that looks like this (prefix truncated for brevity): + + _opam/bin/tobi -> tezos/_tobi/cache/tobi/cfedbfc7d427f7d90216d279eee0bf388dc8940b/_build/install/default/bin/tobi + _opam/lib/tobi/dune-package -> tezos/_tobi/cache/tobi/cfedbfc7d427f7d90216d279eee0bf388dc8940b/_build/install/default/lib/tobi/dune-package + _opam/lib/tobi/META -> tezos/_tobi/cache/tobi/cfedbfc7d427f7d90216d279eee0bf388dc8940b/_build/install/default/lib/tobi/META + +meaning that the files Tobi installed in `_opam` are actually symbolic links to `_tobi/cache`. + +## Play with Tobi's cache + +Let's remove Tobi from its own cache and reinstall Tobi. +Run: + + rm -rf _tobi/cache/tobi + tobi install tobi + +Oops! This fails, because now Tobi is no longer installed. Let's install it via Dune instead. +Run: + + dune exec tobi -- install tobi + +This outputs: + + Installing: tobi + +This time it could not find the files in the cache, so it had to recompile. + +## Install an actual component + +Let's install `octez-libs` with Tobi. Run: + + tobi install octez-libs + +This takes a while. It outputs: + + Installing: bls12-381 + Installing: octez-alcotezt + Installing: octez-distributed-internal + Installing: octez-distributed-lwt-internal + Installing: octez-internal-libs + Installing: octez-libs + +Before installing `octez-libs`, Tobi installed the dependencies of `octez-libs`, +the dependencies of those dependencies, etc. + +## Build the L1 node + +Let's build `octez-node` with Tobi. +Run: + + tobi build octez-node + +This also takes a while. It outputs: + + The following components are installed and will not be built: + - bls12-381 + - octez-alcotezt + - octez-distributed-internal + - octez-distributed-lwt-internal + - octez-internal-libs + - octez-libs + +Let's build it again in verbose mode. +Don't worry, it will be faster this time. +Run: + + tobi build octez-node -v + +This outputs: + + The following components are installed and will not be built: + - bls12-381.cfedbfc7d427f7d90216d279eee0bf388dc8940b + - octez-alcotezt.cfedbfc7d427f7d90216d279eee0bf388dc8940b + - octez-distributed-internal.cfedbfc7d427f7d90216d279eee0bf388dc8940b + - octez-distributed-lwt-internal.cfedbfc7d427f7d90216d279eee0bf388dc8940b + - octez-internal-libs.cfedbfc7d427f7d90216d279eee0bf388dc8940b + - octez-libs.cfedbfc7d427f7d90216d279eee0bf388dc8940b + dune build --only-packages 'octez-rust-deps,octez-version,octez-riscv-api,octez-riscv-pvm,octez-proto-libs,octez-protocol-compiler-compat,octez-protocol-compiler,tezos-benchmark,octez-shell-libs,octez-node-config,octez-rpc-process,tezos-protocol-000-Ps9mPmXa,tezos-protocol-021-PsQuebec,tezt-tezos,tezos-dal-node-services,dal_node_migrations,octez-performance-metrics,octez-l2-libs,tezos-dal-node-lib,octez-crawler,octez-injector,octez-protocol-021-PsQuebec-libs,tezos-protocol-022-PsRiotum,octez-protocol-022-PsRiotum-libs,octez-node' '--display=progress' src/bin_node + +The last line is new. It tells us that `tobi build` actually just runs `dune build` +with the `--only-packages` argument. Dune will ignore any other package. +In particular, we don't see `octez-libs` in this list, nor any of its dependencies. +The packages that we installed using Tobi are hidden from Dune when running `tobi build`. + +## Simulate a Git pull and rebuild the L1 node + +After a `git pull`, we get all sorts of changes. +Some of those changes may be in `octez-libs`. +Let's simulate such a situation by adding a value to `data-encoding`. +Run: + + echo 'let dummy_value = 0' >> data-encoding/src/data_encoding.ml + echo 'val dummy_value: int' >> data-encoding/src/data_encoding.mli + +Now let's rebuild `octez-node`. +Run: + + tobi build octez-node + +Despite `data-encoding` being used all over the place +and being very low in the dependency tree, this takes only a few seconds. +This is the time it takes Dune to realize it has nothing to do. + +The reason Dune has nothing to do is that Tobi tells it to ignore `data-encoding/src/` +and to instead use the version of `octez-libs` that Tobi installed in `_opam`. +`tobi build octez-node` will thus not recompile `octez-libs` if `octez-libs` +is installed, whether there are important changes in `octez-libs` or not. + +## Clean up + +Throughout this tutorial, we have installed a few components. +Let's ask Tobi for the list. +Run: + + tobi list -i + +`-i` tells `tobi list` to only list installed components. +This outputs: + + bls12-381 + octez-alcotezt + octez-distributed-internal + octez-distributed-lwt-internal + octez-internal-libs + octez-libs + tobi + +Let's uninstall those components. +Run: + + tobi reset + +This outputs nothing. +Let's check that components were uninstalled successfully. +Run: + + tobi list -i + +Oops! This fails, because Tobi is no longer installed. +Should have seen this one coming. +Let's check what is in `_opam` instead. + + ls _opam/lib/octez-libs/base + +There is no file there, only empty directories. + +Let's finish cleaning up by removing Tobi's cache. +You can skip this step if you intend to use the installed `octez-libs` +and don't want to waste time reinstalling it. +Run: + + rm -rf _tobi + +## Conclusion + +In this tutorial, we discovered the following commands: + +- `tobi install` +- `tobi build` +- `tobi list` +- `tobi reset` + +We used Dune to install Tobi, then Tobi to install Tobi. +We installed `octez-libs` and used this installed `octez-libs` to build `octez-node`. +We also had a look at Tobi's cache and how Tobi installs components in `_opam`. + +You should now be familiar enough with Tobi to: + +- speed up compilation times in some scenarios; +- store multiple versions of a component in Tobi's cache to quickly + switch between them. + +To explore more about Tobi, go back to the [index](index.md). diff --git a/tobi/doc/src/header1.html b/tobi/doc/src/header1.html new file mode 100644 index 0000000000000000000000000000000000000000..44a6cc869036daa1c123f0124d08f5208452b478 --- /dev/null +++ b/tobi/doc/src/header1.html @@ -0,0 +1,6 @@ + + + + + + diff --git a/tobi/doc/src/header2.html b/tobi/doc/src/header2.html new file mode 100644 index 0000000000000000000000000000000000000000..099af6128388173d2c30cfaa66609f16423a135f --- /dev/null +++ b/tobi/doc/src/header2.html @@ -0,0 +1,3 @@ + + + diff --git a/tobi/doc/src/index.md b/tobi/doc/src/index.md new file mode 100644 index 0000000000000000000000000000000000000000..b534c77b00fc60e3553b49cf9fdad168fe528e04 --- /dev/null +++ b/tobi/doc/src/index.md @@ -0,0 +1,9 @@ +# Tobi: documentation + +Tobi is a package manager for internal components. +It allows to work on a component without having to recompile its dependencies +after each `git pull`. + +## Tutorial + +- [Get familiar with Tobi](get_familiar_with_tobi.md) diff --git a/tobi/doc/src/style.css b/tobi/doc/src/style.css new file mode 100644 index 0000000000000000000000000000000000000000..616968c277afd589069c131afb567435e2c42fc9 --- /dev/null +++ b/tobi/doc/src/style.css @@ -0,0 +1,36 @@ +a { text-decoration: none; } +a:link { color: #0000FF; } +a:visited { color: #008000; } +a:hover { color: #FF0000; text-decoration: underline; } + +body { + max-width: 50em; + margin: auto; +} + +h1 { + margin-top: 1em; + margin-bottom: 1em; + text-align: center; +} + +h2 { + border-top: 1px solid black; + background-color: #ffddbb; +} + +code, pre { + background-color: #eeeeee; +} + +code { + padding: 0.2em; + font-size: 1.2em; +} + +pre { + padding: 0.5em; + border: 1px solid #cccccc; + line-height: 180%; + overflow-x: auto; +}