diff options
Diffstat (limited to 'documentation')
-rw-r--r-- | documentation/conf.py | 4 | ||||
-rw-r--r-- | documentation/user_guide/commands.rst | 22 | ||||
-rw-r--r-- | documentation/user_guide/quickstart.rst | 96 | ||||
-rw-r--r-- | documentation/user_guide/runtimes.rst | 34 |
4 files changed, 154 insertions, 2 deletions
diff --git a/documentation/conf.py b/documentation/conf.py index 5c57195..51bda80 100644 --- a/documentation/conf.py +++ b/documentation/conf.py @@ -38,6 +38,7 @@ extensions = [ 'sphinx.ext.autosectionlabel', 'sphinx_rtd_theme', 'sphinx_copybutton', + 'sphinx.ext.todo', ] # Add any paths that contain templates here, relative to this directory. @@ -83,6 +84,9 @@ html_theme_options = { # -- Extension configuration ------------------------------------------------- +# Display todos by setting to True +todo_include_todos = True + # -- Options for autosectionlabel -------------------------------------------- # Prefix each section label with the name of the document it is in diff --git a/documentation/user_guide/commands.rst b/documentation/user_guide/commands.rst index a2db52e..2600007 100644 --- a/documentation/user_guide/commands.rst +++ b/documentation/user_guide/commands.rst @@ -6,3 +6,25 @@ ######## Commands ######## + +For documentation on the commands that shrinkwrap supports, add ``--help`` to +the command line. + +For top-level help: + +.. code-block:: shell + + shrinkwrap --help + +For help on a specific command: + +.. code-block:: shell + + shrinkwrap inspect --help + shrinkwrap build --help + shrinkwrap run --help + shrinkwrap process --help + +.. todo:: + + Automate importing the help pages into this documentation. diff --git a/documentation/user_guide/quickstart.rst b/documentation/user_guide/quickstart.rst index 64df583..073f4e8 100644 --- a/documentation/user_guide/quickstart.rst +++ b/documentation/user_guide/quickstart.rst @@ -7,7 +7,11 @@ Install Shrinkwrap ****************** Packages don't yet exist, so currently the only way to install Shrinkwrap is to -install its dependencies and clone the git repository: +install its dependencies and clone the git repository. + +Shrinkwrap requires at least Python 3.7 (for ordered dicts). If using a version +older than 3.9, you will also need to install the ``graphlib-backport`` pip +package. .. code-block:: shell @@ -189,7 +193,7 @@ provide a value when running the config. </p> Now build the ``ns-preload.yaml`` config. This is the simplest config that -allows booking a kernel on FVP. (optionally add ``--verbose`` to see all the +allows booting a kernel on FVP. (optionally add ``--verbose`` to see all the output from the component build systems). .. code-block:: shell @@ -360,3 +364,91 @@ forwards stdin to the ``tfa+linux`` uart terminal: </details> </p> + +************************************ +Use Case: Override Component Version +************************************ + +You can change many, many configuration options by overlaying a config on top of +an existing config. Here we modify the revision of the TF-A component from the +``master`` branch (the default defined in tfa-base.yaml), to the ``v2.7.0`` tag. +You could also specify the revision as a SHA or override the remote repo URL, +etc. + +We will use the ``ns-edk2-dt.yaml`` config to spice things up a bit. This loads +EDK2 on top of TF-A then EDK2 pulls the kernel, dtb and command line from the +host system using semihosting. + +.. warning:: + + If you have previously built this config, shrinkwrap will skip syncing the git + repos since they will already exist and it doesn't want to trample any user + changes. So you will need to force shrinkwrap to re-sync. One approach is to + delete the following directories: + + - ``<SHRINKWRAP_BUILD>/source/ns-edk2-dt`` + - ``<SHRINKWRAP_BUILD>/build/ns-edk2-dt`` + +Create a file called ``my-overlay.yaml``: + +.. code-block:: yaml + + build: + tfa: + repo: + revision: v2.7.0 + +Optionally, you can view the final, merged config as follows: + +.. code-block:: shell + + shrinkwrap --runtime=docker process --action=merge --overlay=my-overlay.yaml ns-edk2-dt.yaml + +Now do a build, passing in the overlay: + +.. code-block:: shell + + shrinkwrap --runtime=docker build --overlay=my-overlay.yaml ns-edk2-dt.yaml + +Finally, boot the config. Here, were are providing a custom kernel command line. +But you could omit this and a sensible default would be used. Note that because +EDK2 outputs ncurses-like output, this config starts the appropriate terminal in +telnet mode and provides the command that you need to enter in a separate +window. Follow the instructions, then in EDK2, navigate to Boot Manager -> UEFI +Shell. This will cause the kernel to boot: + +.. code-block:: shell + + shrinkwrap --runtime=docker run --rtvar=KERNEL=path/to/Image --rtvar=ROOTFS=path/to/rootfs.img --rtvar="CMDLINE=console=ttyAMA0 earlycon=pl011,0x1c090000 root=/dev/vda ip=dhcp" ns-edk2-dt.yaml + +*********************************** +Use Case: Reuse Existing Local Repo +*********************************** + +By default, shrinkwrap will sync the git repos for all required components to a +private location the first time you build a given config. However, sometimes you +want shrinkwrap to reuse a repo that already exists on your local system. In +this case, Shrinkwrap will build this source into its own private build tree, +leaving the source tree unmodified. + +.. warning:: + + Components support building in a tree separate from the source to differing + degrees. For example, TF-A will always build fiptool in the source tree, + although it will build all the FW components in the correct build tree. So + depending on the component you are sharing source for, you may see some build + artifacts appear. + +Create a file called ``my-overlay.yaml``: + +.. code-block:: yaml + + build: + tfa: + sourcedir: /path/to/my/tfa/git/repo + +Now do a build, passing in the overlay: + +.. code-block:: shell + + shrinkwrap --runtime=docker build --overlay=my-overlay.yaml ns-edk2-dt.yaml diff --git a/documentation/user_guide/runtimes.rst b/documentation/user_guide/runtimes.rst index fb994f2..f5f4793 100644 --- a/documentation/user_guide/runtimes.rst +++ b/documentation/user_guide/runtimes.rst @@ -7,6 +7,40 @@ Run-Times ######### +Shrinkwrap uses a "runtime" to execute all of its shell commands and allows the +user to choose which runtime to use. Both the design and implementation of this +is borrowed from `Tuxmake <https://tuxmake.org>`_. + +Shrinkwrap supports the following set of runtimes: + +============ ==== +runtime description +============ ==== +null (default). Shell commands are executed natively on the user's system. The user is responsible for ensuring the the required toolchain, environment variables and any other dependencies are set up. +docker Shell commands are executed in a docker container. By default, the official shrinkwrap image will be pulled and used, which contains all dependencies already setup. +docker-local Like docker, but will only look for the container image on the local system. Will not attempt to pull over the network. +podman Like docker, but runs the container using podman. +podman-local Like docker-local, but runs the container using podman. +============ ==== + +.. warning:: + + ``podman`` and ``podman-local`` are not well-tested, and are probably broken. + +The desired runtime can be specified using the ``--runtime`` option, which is a +top-level argument (must come before the command): + +.. code-block:: shell + + shrinkwrap --runtime=<name> ... + +If using a container runtime (anything other than null), a custom image can +optionally be specified. If omitted, the official shrinkwrap image is used: + +.. code-block:: shell + + shrinkwrap --runtime=<name> --image=<name> ... + *********************************** Log into Arm Artifactory Repository *********************************** |