diff --git a/developer/building/development-workflow.rst b/developer/building/development-workflow.rst index 07c8742ac9..3432d4d3af 100644 --- a/developer/building/development-workflow.rst +++ b/developer/building/development-workflow.rst @@ -17,7 +17,7 @@ The best way to write and contribute code is to create a git repo somewhere (e.g **Example:** -.. code:: console +.. code-block:: console $ cd qubes-builder/artifacts/sources/qubes-manager $ git remote add abel git@GitHub.com:abeluck/qubes-manager.git @@ -38,7 +38,7 @@ Prepare fresh version of kernel sources, with Qubes-specific patches applied In ``qubes-builder/artifacts/sources/linux-kernel``: -.. code:: console +.. code-block:: console $ make prep @@ -46,7 +46,7 @@ In ``qubes-builder/artifacts/sources/linux-kernel``: The resulting tree will be in kernel-/linux-: -.. code:: console +.. code-block:: console $ ls -ltrd kernel*/linux* drwxr-xr-x 23 user user 4096 Nov 5 09:50 kernel-3.4.18/linux-3.4.18 @@ -60,7 +60,7 @@ Go to the kernel tree and update the version In ``qubes-builder/artifacts/sources/linux-kernel``: -.. code:: console +.. code-block:: console $ cd kernel-3.4.18/linux-3.4.18 @@ -72,7 +72,7 @@ Changing the config In ``kernel-3.4.18/linux-3.4.18``: -.. code:: console +.. code-block:: console $ cp ../../config .config $ make oldconfig @@ -81,7 +81,7 @@ In ``kernel-3.4.18/linux-3.4.18``: Now change the configuration. For example, in ``kernel-3.4.18/linux-3.4.18``: -.. code:: console +.. code-block:: console $ make menuconfig @@ -89,7 +89,7 @@ Now change the configuration. For example, in ``kernel-3.4.18/linux-3.4.18``: Copy the modified config back into the kernel tree: -.. code:: console +.. code-block:: console $ cp .config ../../../config @@ -101,7 +101,7 @@ Patching the code TODO: describe the workflow for patching the code, below are some random notes, not working well -.. code:: console +.. code-block:: console $ ln -s ../../patches.xen $ export QUILT_PATCHES=patches.xen @@ -131,7 +131,7 @@ You might want to take a moment here to review (git diff, git status), commit yo To actually build RPMs, in qubes-builder: -.. code:: console +.. code-block:: console $ ./qb -c linux-kernel package fetch prep build @@ -169,7 +169,7 @@ Syncing dom0 files TODO: edit this script to be more generic -.. code:: bash +.. code-block:: bash #!/bin/sh @@ -202,7 +202,7 @@ Apply qvm-tools TODO: make it more generic -.. code:: bash +.. code-block:: bash #!/bin/sh @@ -217,7 +217,7 @@ Copy from dom0 to an appvm ^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. code:: bash +.. code-block:: bash #/bin/sh # @@ -242,7 +242,7 @@ Below example assumes that you use ``builder-RX`` directory in target VM to stor Service file (save in ``/usr/local/etc/qubes-rpc/local.Git`` in target VM): -.. code:: bash +.. code-block:: bash #!/bin/sh @@ -271,7 +271,7 @@ Service file (save in ``/usr/local/etc/qubes-rpc/local.Git`` in target VM): Client script (save in ``~/bin/git-qrexec`` in source VM): -.. code:: bash +.. code-block:: bash #!/bin/sh @@ -285,7 +285,7 @@ You will also need to setup qrexec policy in dom0 (``/etc/qubes-rpc/policy/local Usage: -.. code:: console +.. code-block:: console [user@source core-agent-linux]$ git remote add testbuilder "ext::git-qrexec testbuilder 3 core-agent-linux" [user@source core-agent-linux]$ git push testbuilder master @@ -294,7 +294,7 @@ Usage: You can create ``~/bin/add-remote`` script to ease adding remotes: -.. code:: bash +.. code-block:: bash #!/bin/sh @@ -325,7 +325,7 @@ RPM packages - yum repo In source VM, grab `linux-yum `__ repository (below is assumed you’ve made it in ``~/repo-yum-upload`` directory) and replace ``update_repo.sh`` script with: -.. code:: bash +.. code-block:: bash #!/bin/sh @@ -342,7 +342,7 @@ In source VM, grab `linux-yum `__ re In target VM, setup actual yum repository (also based on `linux-yum `__, this time without modifications). You will also need to setup some gpg key for signing packages (it is possible to force yum to install unsigned packages, but it isn’t possible for ``qubes-dom0-update`` tool). Fill ``~/.rpmmacros`` with key description: -.. code:: text +.. code-block:: text %_gpg_name Test packages signing key @@ -350,7 +350,7 @@ In target VM, setup actual yum repository (also based on `linux-yum ` to avoid repeating this step after reboot, adding the following to the ``/rw/config/qubes-bind-dirs.d/docker.conf`` file in this qube: - .. code:: bash + .. code-block:: bash binds+=( '/var/lib/docker' ) @@ -78,7 +78,7 @@ Configuration To use Qubes OS Builder v2, you need to have a ``builder.yml`` configuration file. You can use one of the sample files from the ``example-configs/`` directory; for a more readable ``builder.yml``, you can also include one of the files from that directory in your ``builder.yml``. An example ``builder.yml`` is: -.. code:: yaml +.. code-block:: yaml # include configuration relevant for the current release include: @@ -109,7 +109,7 @@ To use Qubes OS Builder v2, you need to have a ``builder.yml`` configuration fil If you want use the ``podman`` executor, you have to enable socket activation, with: - .. code:: console + .. code-block:: console # systemctl --user enable --now podman.socket @@ -118,7 +118,7 @@ Using Builder v2 To fetch sources - in this example, for the ``core-admin-client`` package, you can use the following command: -.. code:: console +.. code-block:: console $ ./qb -c core-admin-client package fetch @@ -126,19 +126,19 @@ This will fetch the sources for the listed package and place them in ``artifacts To build a package (from sources in the ``artifacts/sources`` directory), use: -.. code:: console +.. code-block:: console $ ./qb -c core-admin-client package fetch prep build or, if you want to build for a specific target (``host-fc37`` is a ``dom0`` using Fedora 37, ``vm-fc40`` would be a qube using Fedora 40 etc.), use: -.. code:: console +.. code-block:: console $ ./qb -c core-admin-client -d host-fc37 package fetch prep build If you want to fetch the entire Qubes OS source use the following: -.. code:: console +.. code-block:: console $ ./qb package fetch diff --git a/developer/building/qubes-builder.rst b/developer/building/qubes-builder.rst index aaa7f33ac3..d5dc57e9e6 100644 --- a/developer/building/qubes-builder.rst +++ b/developer/building/qubes-builder.rst @@ -55,7 +55,7 @@ In order to use it, you should use an rpm-based distro, like Fedora :), and shou Usually you can install those packages by just issuing: -.. code:: console +.. code-block:: console $ sudo dnf install gnupg git createrepo rpm-build make wget rpmdevtools python3-sh dialog rpm-sign dpkg-dev debootstrap python3-pyyaml devscripts perl-Digest-MD5 perl-Digest-SHA @@ -65,14 +65,14 @@ The build system creates build environments in chroots and so no other packages The build system is configured via builder.conf file. You can use the setup.sh script to create and modify this file. Alternatively, you can copy the provided default builder.conf, and modify it as needed, e.g.: -.. code:: console +.. code-block:: console $ cp example-configs/qubes-os-master.conf builder.conf Edit the builder.conf file and set the following variables: -.. code:: bash +.. code-block:: bash NO_SIGN=1 @@ -81,7 +81,7 @@ One additional useful requirement is that ‘sudo root’ must work without any Additionally, if building with signing enabled (NO_SIGN is not set), you must adjust ``\~/.rpmmacros`` file so that it points to the GPG key used for package signing, e.g.: -.. code:: text +.. code-block:: text %_signature gpg %_gpg_path /home/user/.gnupg @@ -94,14 +94,14 @@ So, to build Qubes you would do: Import the Qubes master key: -.. code:: console +.. code-block:: console $ gpg --recv-keys 0xDDFA1A3E36879494 Verify its fingerprint, set as 'trusted'. This is described :doc:`here `. -.. code:: console +.. code-block:: console $ wget https://keys.qubes-os.org/keys/qubes-developers-keys.asc $ gpg --import qubes-developers-keys.asc @@ -112,42 +112,42 @@ Verify its fingerprint, set as 'trusted'. This is described :doc:`here ` by default verifies signed tags on every downloaded code. Public keys used for that are stored in ``keyrings/git``. By default Qubes developers’ keys are imported automatically, but if you need some additional keys (for example your own), you can add them using: -.. code:: bash +.. code-block:: bash GNUPGHOME=$PWD/keyrings/git gpg --import /path/to/key.asc GNUPGHOME=$PWD/keyrings/git gpg --edit-key ID_OF_JUST_IMPORTED_KEY diff --git a/developer/building/qubes-iso-building.rst b/developer/building/qubes-iso-building.rst index 1c9ec82605..3989886114 100644 --- a/developer/building/qubes-iso-building.rst +++ b/developer/building/qubes-iso-building.rst @@ -15,14 +15,14 @@ Fedora 36 (and 37) has been successfully used to build Qubes R4.1 with the below **Notes:** On modern Fedora system (like Fedora 37) SeLinux is enforced by default and is blocking the build system. You would get error like “can’t create transaction lock on /…/rpm/.rpm.lock (Permission denied)”. You can set SeLinux to permissive mode with -.. code:: console +.. code-block:: console $ sudo setenforce 0 In ``dom0``, install the Fedora 36 (or 37) template if you don’t already have it. -.. code:: console +.. code-block:: console $ sudo qubes-dom0-update qubes-template-fedora-36 @@ -32,7 +32,7 @@ Create a standalone AppVM from the Fedora template. Set private storage to at le Once you’ve built the development AppVM, open a Terminal window to it and install the necessary dependencies (see :doc:`QubesBuilder ` for more info): -.. code:: console +.. code-block:: console $ sudo dnf install git createrepo rpm-build rpm-sign make python3-sh rpmdevtools rpm-sign dialog perl-open python3-pyyaml perl-Digest-MD5 perl-Digest-SHA @@ -40,20 +40,20 @@ Once you’ve built the development AppVM, open a Terminal window to it and inst Get the necessary keys to verify the sources (run these and other commands below as a regular user, not root): -.. code:: console +.. code-block:: console $ wget https://keys.qubes-os.org/keys/qubes-master-signing-key.asc $ gpg --import qubes-master-signing-key.asc $ gpg --edit-key 36879494 $ fpr -.. code:: output +.. code-block:: output # Verify fingerprint! See Note below! # Once verified, set trust to *ultimate* # (Typical sequence is trust, 5, Y, q) -.. code:: console +.. code-block:: console $ wget https://keys.qubes-os.org/keys/qubes-developers-keys.asc $ gpg --import qubes-developers-keys.asc @@ -64,7 +64,7 @@ Get the necessary keys to verify the sources (run these and other commands below Now let’s bootstrap the builder. Unfortunately, the builder cannot verify itself (the classic Chicken and Egg problem), so we need to verify the signature manually: -.. code:: console +.. code-block:: console $ git clone https://github.com/QubesOS/qubes-builder.git $ cd qubes-builder @@ -82,12 +82,12 @@ Build using setup script Let’s configure the builder first (see :ref:`procedure ` at bottom if you would prefer to manually configure): -.. code:: console +.. code-block:: console $ cd ~/qubes-builder $ ./setup -.. code:: output +.. code-block:: output # Select Yes to add Qubes Master Signing Key # Select Yes to add Qubes OS Signing Key @@ -105,11 +105,11 @@ Let’s configure the builder first (see :ref:`procedure `__, etc. It should look something like this: -.. code:: output +.. code-block:: output pub rsa4096 2014-01-16 [SC] [expires: 2026-01-23] Key fingerprint = 916B 8D99 C38E AF5E 8ADC 7A2A 8D66 066A 2EEA CCDA @@ -183,7 +183,7 @@ If you will be building Whonix templates: Next, prepare the Git keyring directory and copy them in: -.. code:: console +.. code-block:: console $ export GNUPGHOME=~/qubes-builder/keyrings/git $ mkdir --parents "$GNUPGHOME" @@ -195,7 +195,7 @@ Next, prepare the Git keyring directory and copy them in: Copy one of the example configurations: -.. code:: console +.. code-block:: console $ cd ~/qubes-builder $ cp example-configs/qubes-os-master.conf builder.conf @@ -206,7 +206,7 @@ Edit ``builder.conf``, referring to ``doc/Configuration.md`` for a description o Continue the build process with: -.. code:: console +.. code-block:: console $ make install-deps $ make get-sources @@ -218,7 +218,7 @@ When building the Whonix templates, you will often need to add/update the ``WHON Finally, if you are making a test build, use: -.. code:: console +.. code-block:: console $ make qubes $ make iso @@ -227,7 +227,7 @@ Finally, if you are making a test build, use: Or for a fully signed build (this requires setting ``SIGN_KEY`` in ``builder.conf``): -.. code:: console +.. code-block:: console $ make qubes $ make sign-all diff --git a/developer/code/code-signing.rst b/developer/code/code-signing.rst index c547534fbc..244f3d503c 100644 --- a/developer/code/code-signing.rst +++ b/developer/code/code-signing.rst @@ -13,7 +13,7 @@ Generating a Key Alex Cabal has written an excellent `guide `__ on creating a PGP keypair. Below, we reproduce just the minimum steps in generating a keypair using GnuPG. Please read Cabal’s full guide for further important details. -.. code:: console +.. code-block:: console $ gpg --gen-key gpg (GnuPG) 2.2.27; Copyright (C) 2021 Free Software Foundation, Inc. @@ -68,14 +68,14 @@ In the example below, we will use ``keyserver.ubuntu.com``. Replace 6E2F4E7AF50A5827 with your key ID, preferably the **long keyID** which is the last 16 hex digits of the long number in the second line of the output above: -.. code:: output +.. code-block:: output pub rsa3072 2021-12-30 [SC] [expires: 2023-12-30] 87975838063F97A968D503266E2F4E7AF50A5827 -.. code:: console +.. code-block:: console $ gpg --send-keys --keyserver hkps://keyserver.ubuntu.com 6E2F4E7AF50A5827 gpg: sending key 6E2F4E7AF50A5827 to hkps://keyserver.ubuntu.com @@ -89,7 +89,7 @@ If you’re submitting a patch via GitHub (or a similar Git server), please sign 1. Set up Git to use your key: - .. code:: console + .. code-block:: console $ git config --global user.signingkey @@ -97,14 +97,14 @@ If you’re submitting a patch via GitHub (or a similar Git server), please sign 2. Set up Git to sign your commits with your key: - .. code:: console + .. code-block:: console $ git config --global commit.gpgsign true Alternatively, manually specify when a commit is to be signed: - .. code:: console + .. code-block:: console $ git commit -S @@ -114,14 +114,14 @@ If you’re submitting a patch via GitHub (or a similar Git server), please sign This is useful for example, if you have a commit back in the git history which you like to sign now without rewriting the history. - .. code:: console + .. code-block:: console $ git tag -s -m "" You can also create an alias to make this easier. Edit your ``~/.gitconfig`` file. In the ``[alias]`` section, add ``stag`` to create signed tags and ``spush`` to create signed tags and push them. - .. code:: ini + .. code-block:: ini [alias] stag = "!bash -c 'id=\"`git rev-parse --verify HEAD`\"; tag_name="signed_tag_for_${id:0:8}"; git tag -s "$tag_name" -m \"Tag for commit $id\"; echo \"$tag_name\"'" @@ -130,7 +130,7 @@ If you’re submitting a patch via GitHub (or a similar Git server), please sign You may also find it convenient to have an alias for verifying the tag on the latest commit: - .. code:: ini + .. code-block:: ini vtag = !git tag -v `git describe` @@ -170,14 +170,14 @@ In this case, you have several options to sign the commit: 1. Amend the commit and replace it with a signed commit. You can use this command to create a new signed commit: - .. code:: console + .. code-block:: console $ git commit --amend -S This also rewrites the commit so you need to push it forcefully: - .. code:: console + .. code-block:: console $ git push -f @@ -185,7 +185,7 @@ In this case, you have several options to sign the commit: 2. Create a signed tag for the unsigned commit. If the commit is back in history and you do not want to change it, you can create a signed tag for this commit and push the signature. You can use the alias from above: - .. code:: console + .. code-block:: console $ git checkout $ git spush diff --git a/developer/code/coding-style.rst b/developer/code/coding-style.rst index 759daceaca..707a3167ac 100644 --- a/developer/code/coding-style.rst +++ b/developer/code/coding-style.rst @@ -55,7 +55,7 @@ General typographic conventions - **Comments should be indented together with the code**, e.g. like this: - .. code:: c + .. code-block:: c for (...) { // The following code finds PGP private key matching the given public key in O(1) @@ -120,7 +120,7 @@ General programming style guidelines - Do **not** use comments for code fragments where it is immediately clear what the code does. E.g. avoid constructs like this: - .. code:: c + .. code-block:: c // Return window id int get_window_id (...) { @@ -132,7 +132,7 @@ General programming style guidelines - Do **not** use comments to disable code fragments. In production code there should really be no commented or disabled code fragments. If you really, really have a good reason to retain some fragment of unused code, use #if or #ifdef to disable it, e.g.: - .. code:: c + .. code-block:: c #if 0 (...) // Some unused code here @@ -141,7 +141,7 @@ General programming style guidelines … and preferably use some descriptive macro instead of just ``0``, e.g.: - .. code:: c + .. code-block:: c #if USE_OLD_WINDOW_TRAVERSING (...) // Some unused code here @@ -214,7 +214,7 @@ Security coding guidelines - Use ``untrusted_`` prefix for all variables that hold values read from untrusted party and which have not yet been verified to be decent, e.g.: - .. code:: c + .. code-block:: c read_struct(untrusted_conf); /* sanitize start */ diff --git a/developer/code/source-code.rst b/developer/code/source-code.rst index 6b8e6c1f59..8832dda32b 100644 --- a/developer/code/source-code.rst +++ b/developer/code/source-code.rst @@ -19,7 +19,7 @@ All of our repositories are available under the `QubesOS GitHub account .git @@ -27,7 +27,7 @@ To clone a repository: e.g.: -.. code:: console +.. code-block:: console $ git clone https://github.com/QubesOS/qubes-core-admin.git core-admin @@ -37,7 +37,7 @@ To build Qubes you do not need to download all these repositories. If you use :d If you really do want to clone **all** of the repositories, you can use these commands: -.. code:: console +.. code-block:: console $ curl "https://api.github.com/orgs/QubesOS/repos?page=1&per_page=100" | grep -e 'clone_url*' | cut -d \" -f 4 | xargs -L1 git clone $ curl "https://api.github.com/orgs/QubesOS/repos?page=2&per_page=100" | grep -e 'clone_url*' | cut -d \" -f 4 | xargs -L1 git clone @@ -46,7 +46,7 @@ If you really do want to clone **all** of the repositories, you can use these co To update (git fetch) **all** of these repositories : -.. code:: console +.. code-block:: console $ find . -mindepth 1 -maxdepth 1 -type d -exec git -C {} fetch --tags --recurse-submodules=on-demand --all \; diff --git a/developer/debugging/automated-tests.rst b/developer/debugging/automated-tests.rst index a08f17292d..09c6da4068 100644 --- a/developer/debugging/automated-tests.rst +++ b/developer/debugging/automated-tests.rst @@ -39,7 +39,7 @@ Our test runner runs mostly the same as the standard one, but it has some nice a You can use ``python3 -m qubes.tests.run -h`` to get usage information: -.. code:: console +.. code-block:: console [user@dom0 ~]$ python3 -m qubes.tests.run -h usage: run.py [-h] [--verbose] [--quiet] [--list] [--failfast] [--no-failfast] @@ -82,7 +82,7 @@ You can use ``python3 -m qubes.tests.run -h`` to get usage information: For instance, to run only the tests for the fedora-21 template, you can use the ``-l`` option, then filter the list: -.. code:: console +.. code-block:: console [user@dom0 ~]$ python3 -m qubes.tests.run -l | grep fedora-21 network/VmNetworking_fedora-21/test_000_simple_networking @@ -109,7 +109,7 @@ For instance, to run only the tests for the fedora-21 template, you can use the Some developers script this part, so you can provide arguments to the script and it handles ``qubesd``. Save the following contents to :file:`~/run-tests`: -.. code:: console +.. code-block:: console #!/bin/sh set -eu @@ -123,13 +123,13 @@ Some developers script this part, so you can provide arguments to the script and And run: -.. code:: console +.. code-block:: console ~/run-tests -L INFO -o /tmp/tests.log You might even almost complete test names and shell expansion: -.. code:: console +.. code-block:: console ~/run-tests qubes.tests.integ.dispvm_perf/TC_00_DispVMPerf_debian-{12,13}-xfce/test_0{0,1,2} @@ -142,7 +142,7 @@ Example test run: Tests are also compatible with nose2 test runner, so you can use this instead: -.. code:: console +.. code-block:: console $ sudo systemctl stop qubesd; sudo -E nose2 -v --plugin nose2.plugins.loader.loadtests qubes.tests; sudo systemctl start qubesd @@ -165,7 +165,7 @@ The below example however will assume that you set up a build environment as des Assuming you cloned the ``qubes-builder`` repository to your home directory inside a fedora VM, you can use the following commands to run the unit tests: -.. code:: console +.. code-block:: console $ cd ~ $ sudo dnf install python3-pip lvm2 python35 python3-virtualenv @@ -214,7 +214,7 @@ Editing ``__init__.py`` You’ll also need to add your test at the bottom of the ``__init__.py`` file, in the method ``def load_tests``, in the for loop with ``modname``. Again, given the hypothetical ``example.py`` test: -.. code:: python +.. code-block:: python for modname in ( 'qubes.tests.basic', @@ -234,7 +234,7 @@ Testing PyQt applications When testing (Py)QT applications, it’s useful to create a separate QApplication object for each test. But QT framework does not allow multiple QApplication objects in the same process at the same time. This means it’s critical to reliably cleanup the previous instance before creating a new one. This turns out to be a non-trivial task, especially if *any* test uses the event loop. Failure to perform proper cleanup in many cases results in SEGV. Below you can find steps for the proper cleanup: -.. code:: python +.. code-block:: python import asyncio import quamash @@ -357,7 +357,7 @@ Notes: Examples: -.. code:: console +.. code-block:: console # Only this PR openQArun diff --git a/developer/debugging/mount-lvm-image.rst b/developer/debugging/mount-lvm-image.rst index dbc19b618e..cf4c5c5769 100644 --- a/developer/debugging/mount-lvm-image.rst +++ b/developer/debugging/mount-lvm-image.rst @@ -7,7 +7,7 @@ You want to read your LVM image (e.g., there is a problem where you can’t star 1: make the image available for qubesdb. From dom0 terminal: -.. code:: console +.. code-block:: console # Example: /dev/qubes_dom0/vm-debian-9-tmp-root [user@dom0]$ dev=$(basename $(readlink /dev/YOUR_LVM_VG/YOUR_LVM_IMAGE)) @@ -16,7 +16,7 @@ You want to read your LVM image (e.g., there is a problem where you can’t star 2: Create a new disposable VM -.. code:: console +.. code-block:: console [user@dom0]$ qvm-run -v --dispvm=YOUR_DVM_TEMPLATE --service qubes.StartApp+xterm & @@ -25,28 +25,28 @@ You want to read your LVM image (e.g., there is a problem where you can’t star From the GUI, or from the command line: -.. code:: console +.. code-block:: console [user@dom0]$ qvm-block attach NEWLY_CREATED_DISPVM dom0:$dev 4: Mount the partition you want to, and do what you want with it -.. code:: console +.. code-block:: console [user@dispXXXX]$ mount /dev/xvdiX /mnt/ 5: Umount and kill the VM -.. code:: console +.. code-block:: console [user@dispXXXX]$ umount /mnt/ 6: Remove the image from qubesdb -.. code:: console +.. code-block:: console [user@dom0]$ qubesdb-rm /qubes-block-devices/$dev/ diff --git a/developer/debugging/safe-remote-ttys.rst b/developer/debugging/safe-remote-ttys.rst index cb53a527b0..e8b395784a 100644 --- a/developer/debugging/safe-remote-ttys.rst +++ b/developer/debugging/safe-remote-ttys.rst @@ -17,7 +17,7 @@ To a different VM As an example of forwarding terminal output to another VM on the same machine: -.. code:: console +.. code-block:: console $ mkfifo /tmp/foo $ qvm-run -p some-vm 'xterm -e "cat 0<&5" 5<&0' /dev/null 2>&1 & @@ -31,7 +31,7 @@ To a different machine In this case over SSH (from a network-connected VM): -.. code:: console +.. code-block:: console $ mkfifo /tmp/foo $ qvm-run -p some-vm \ @@ -55,7 +55,7 @@ Terminal size It is up to you to ensure the sizes of the local and remote terminal are the same, otherwise things may display incorrectly (especially in interactive programs). Depending on your shell, the size of your local (blind) terminal is likely stored in the ``$LINES`` and ``$COLUMNS`` variables. -.. code:: console +.. code-block:: console $ echo $COLUMNS $LINES 80 24 @@ -68,7 +68,7 @@ A note on serial consoles If your machine has a serial console, you may with to use that, but note that a similar split-I/O model should be used to ensure Dom0 integrity. If you use the serial console as normal (via e.g. getty on ttyX, and logging in as normal), then the machine at the end of the serial cable could compromise your machine! Ideally, you would take input from your trusted keyboard, and only send the output over the serial cable via e.g. disabling getty and using: -.. code:: console +.. code-block:: console $ script -f /dev/ttyS0 diff --git a/developer/debugging/test-bench.rst b/developer/debugging/test-bench.rst index 4a64cc20b2..14ce37c240 100644 --- a/developer/debugging/test-bench.rst +++ b/developer/debugging/test-bench.rst @@ -35,7 +35,7 @@ Internet access is intentionally disabled by default in dom0. But to ease the de 4. Save the following script in ``/home/user/bin/dom0_network.sh`` and make it executable. It should enable your network card in dom0. *Be sure to adjust the script’s variables to suit your needs.* - .. code:: bash + .. code-block:: bash #!/bin/sh @@ -78,7 +78,7 @@ Internet access is intentionally disabled by default in dom0. But to ease the de 6. You’ll need to run the above script on every startup. To automate this save the following systemd service ``/etc/systemd/system/dom0-network-direct.service`` - .. code:: systemd + .. code-block:: systemd [Unit] Description=Connect network to dom0 @@ -94,7 +94,7 @@ Internet access is intentionally disabled by default in dom0. But to ease the de 7. Then, enable and start the SSH Server and the script on boot: - .. code:: console + .. code-block:: console $ sudo systemctl enable sshd $ sudo systemctl start sshd @@ -117,7 +117,7 @@ Because of the above reason, some additional configurations need to be done to y The following commands should work for you, but do keep in mind that the provisioning scripts are designed for the `openQA environment `__ and not your specific local testing system. Run the following in ``dom0``: -.. code:: console +.. code-block:: console # For future reference the following commands are an adaptation of # https://github.com/marmarek/openqa-tests-qubesos/blob/master/tests/update.pm @@ -155,7 +155,7 @@ SSH Arrange firewall so you can reach the testbench from your ``qubes-dev`` VM. Generate SSH key in ``qubes-dev``: -.. code:: console +.. code-block:: console $ ssh-keygen -t ecdsa -b 521 @@ -163,7 +163,7 @@ Arrange firewall so you can reach the testbench from your ``qubes-dev`` VM. Gene Add the following section in ``.ssh/config`` in ``qubes-dev``: -.. code:: text +.. code-block:: text Host testbench # substitute username in testbench @@ -187,7 +187,7 @@ This step is optional, but very helpful. Put these scripts somewhere in your ``$ ``qtb-runtests``: -.. code:: bash +.. code-block:: bash #!/bin/sh @@ -196,7 +196,7 @@ This step is optional, but very helpful. Put these scripts somewhere in your ``$ ``qtb-install``: -.. code:: bash +.. code-block:: bash #!/bin/sh @@ -220,7 +220,7 @@ This step is optional, but very helpful. Put these scripts somewhere in your ``$ ``qtb-iterate``: -.. code:: bash +.. code-block:: bash #!/bin/sh @@ -247,7 +247,7 @@ I (woju) have those two git hooks. They ensure tests are passing (or are marked ``core-admin/.git/hooks/pre-commit``: (you may retain also the default hook, here omitted for readability) -.. code:: bash +.. code-block:: bash #!/bin/sh @@ -258,7 +258,7 @@ I (woju) have those two git hooks. They ensure tests are passing (or are marked ``core-admin/.git/hooks/pre-push``: -.. code:: bash +.. code-block:: bash #!/bin/sh diff --git a/developer/debugging/windows-debugging.rst b/developer/debugging/windows-debugging.rst index dd0d047163..8ca9f6d82b 100644 --- a/developer/debugging/windows-debugging.rst +++ b/developer/debugging/windows-debugging.rst @@ -45,7 +45,7 @@ You will need to create a :doc:`custom libvirt config ` for -.. code:: xml+jinja +.. code-block:: xml+jinja {% extends 'libvirt/xen.xml' %} @@ -98,7 +98,7 @@ Host and target preparation - ``kdnet`` should show that the NIC is supported, note the busparams: - .. code:: text + .. code-block:: text Network debugging is supported on the following NICs: busparams=0.6.0, Intel(R) PRO/1000 MT Network Connection, KDNET is running on this NIC. @@ -117,7 +117,7 @@ Host and target preparation - Reboot ``target-vm``, debugging should start: - .. code:: text + .. code-block:: text Waiting to reconnect... Connected to target 10.137.0.19 on port 50000 on local IP 10.137.0.20. diff --git a/developer/general/developing-gui-applications.rst b/developer/general/developing-gui-applications.rst index 007efb2892..58e3dcaae8 100644 --- a/developer/general/developing-gui-applications.rst +++ b/developer/general/developing-gui-applications.rst @@ -13,7 +13,7 @@ Where you would normally provide the Qubes object, use the ``qubesadmin.tests.mo For example, the following code can be used to run the ``qui-domains`` tool using the mock Qubes object (this code would replace the initial part of the main function): -.. code:: python +.. code-block:: python def main(): ''' main function ''' @@ -32,7 +32,7 @@ For example, the following code can be used to run the ``qui-domains`` tool usin To run a mocked program without installing it in a qube, remember to extend PYTHONPATH appropriately, for example: -.. code:: console +.. code-block:: console ~/qubes-sources/manager $ PYTHONPATH=../core-admin-client:. python3 qui/tray/domains.py @@ -49,7 +49,7 @@ The mock Qubes object has a collection of expected Qubes RPC calls and the respo If you need more calls, you can add them to the mock object using the following syntax (the following example adds listing available vm kernels): -.. code:: python +.. code-block:: python mock_app.expected_calls[('dom0', 'admin.pool.volume.List', 'linux-kernel', None)] = \ b'0\x006.1.57-1.fc37\n6.1.43-1.fc37\ncustom_kernel\n' @@ -57,7 +57,7 @@ If you need more calls, you can add them to the mock object using the following If error should be thrown, you need to provide the error code and name, for example: -.. code:: python +.. code-block:: python mock_app.expected_calls[("vmname", "admin.vm.property.Get", "property_name", None)] = \ b'2\x00QubesNoSuchPropertyError\x00\x00No such property\x00' @@ -85,7 +85,7 @@ Extending the mock Qubes object To collect information to modify this script, you can use the wrapper function to wrap and output all qubesd calls used by a program running on a live qubes instance. -.. code:: python +.. code-block:: python qapp = qubesadmin.Qubes() import qubesadmin.tests.mock_app as mock_app @@ -99,7 +99,7 @@ Writing tests The same mock Qubes can also be used to write tests. You can use the wrappers above to check which calls are made when certain actions are performed, and add them to the mock objects in the following way: -.. code:: python +.. code-block:: python # this is an excerpt from tests for Qubes Global Config tool clockvm_combo.set_active_id('test-blue') diff --git a/developer/general/gsoc.rst b/developer/general/gsoc.rst index caef042cfb..a6530ded5f 100644 --- a/developer/general/gsoc.rst +++ b/developer/general/gsoc.rst @@ -49,7 +49,7 @@ A project proposal is what you will be judged upon. Write a clear proposal on wh Below is the application template: -.. code:: markdown +.. code-block:: markdown # Introduction diff --git a/developer/general/how-to-edit-the-rst-documentation.rst b/developer/general/how-to-edit-the-rst-documentation.rst index 5bbe4512d9..cdf5c75c2a 100644 --- a/developer/general/how-to-edit-the-rst-documentation.rst +++ b/developer/general/how-to-edit-the-rst-documentation.rst @@ -159,20 +159,20 @@ Tips & Tricks - Pull upstream changes into your fork regularly. Diverging too far from main can be cumbersome to update at a later stage. - To pull in upstream changes: - .. code:: console + .. code-block:: console $ git remote add upstream https://github.com/QubesOS/qubes-doc.git $ git fetch upstream - Check the log and the current changes, before merging: - .. code:: console + .. code-block:: console $ git log upstream/main - Then merge the changes that you fetched: - .. code:: console + .. code-block:: console $ git merge upstream/main @@ -255,7 +255,7 @@ The first part (before the colon) is the path of the file as with the `:doc: rol **When referencing some kind of code** use the corresponding role, eventually prefixed by the sub-project, as in: -.. code:: rst +.. code-block:: rst See :py:class:`core-admin:qubes.vm.dispvm.DispVM` diff --git a/developer/general/how-to-edit-the-website.rst b/developer/general/how-to-edit-the-website.rst index 37c96862da..1c8f33670e 100644 --- a/developer/general/how-to-edit-the-website.rst +++ b/developer/general/how-to-edit-the-website.rst @@ -75,7 +75,7 @@ Quick intro to Jekyll The main `qubesos.github.io `__ contains the following directories: -.. code:: bash +.. code-block:: bash ├── data # ← YAML files with key‑value pairs used throughout the site │ └── *.yml # e.g. site settings, navigation menus @@ -158,13 +158,13 @@ This can be useful for making sure that your changes render the way you expect, 1. Create a template qube: -.. code:: console +.. code-block:: console $ qvm-clone debian-12-minimal jekyll-tvm 2. Install packages: -.. code:: console +.. code-block:: console $ apt install qubes-core-agent-networking $ apt install ruby-full build-essential zlib1g-dev vim @@ -174,7 +174,7 @@ This can be useful for making sure that your changes render the way you expect, 3. Create a ``jekyll-app-vm`` based on the ``jekyll-tvm`` template, install and configure in ``jekyll-app-vm``: -.. code:: console +.. code-block:: console $ echo '# Install Ruby Gems to ~/gems' >> ~/.bashrc $ echo 'export GEM_HOME="$HOME/gems"' >> ~/.bashrc diff --git a/developer/general/rst-documentation-style-guide.rst b/developer/general/rst-documentation-style-guide.rst index 13edb358e4..140bc3b818 100644 --- a/developer/general/rst-documentation-style-guide.rst +++ b/developer/general/rst-documentation-style-guide.rst @@ -28,10 +28,10 @@ provided by `Docutils `__ and extended by `Sphinx `__ for a list of supported languages). -.. code:: rst +.. code-block:: rst - .. code:: language + .. code-block:: language code @@ -108,15 +108,15 @@ Use ``[...]`` for anything omitted. For inlining small code snippets you can use the `code role `__ as in -.. code:: rst +.. code-block:: rst :code:`:term:`qube`` You can add line numbers to code examples with the ``:linenos:`` parameter. -.. code:: rst +.. code-block:: rst - .. code:: python + .. code-block:: python :linenos: def hello_world(): @@ -125,50 +125,50 @@ You can add line numbers to code examples with the ``:linenos:`` parameter. You can have certain lines with the ``:emphasize-lines:`` parameter. -.. code:: rst +.. code-block:: rst - .. code:: python + .. code-block:: python :emphasize-lines: 1,3,4 For Python use ``python``. -.. code:: rst +.. code-block:: rst - .. code:: python + .. code-block:: python string_var = 'python' For Bash use ``bash``. -.. code:: rst +.. code-block:: rst - .. code:: bash + .. code-block:: bash #!/bin/bash For a terminal session use ``console``. -.. code:: rst +.. code-block:: rst - .. code:: console + .. code-block:: console $ echo "Hello" For text output use ``output``. -.. code:: rst +.. code-block:: rst - .. code:: output + .. code-block:: output some output For text use ``text``. -.. code:: rst +.. code-block:: rst - .. code:: text + .. code-block:: text some text @@ -180,7 +180,7 @@ We adhere to the list tables directive by docutils as described `here `_: -.. code:: rst +.. code-block:: rst .. admonition:: Did you know? @@ -252,7 +252,7 @@ Glossary Most of the `glossaries `__ are present in :file:`/user/reference/glossary.rst`, like: -.. code:: rst +.. code-block:: rst .. glossary:: @@ -275,7 +275,7 @@ and thus enhance the readability and consistency of the documentation. Syntax is as follows: -.. code:: rst +.. code-block:: rst :rolename:`content` @@ -306,7 +306,7 @@ Cross-referencing a page To cross-reference a page, use the `doc role `__ with a path. To get a link to the file called :file:`intro.rst` in the :file:`introduction/` directory, use: - .. code:: rst + .. code-block:: rst :doc:`/introduction/intro` @@ -317,7 +317,7 @@ Cross-referencing a section with a header To cross-reference a section with a header, use the `ref role `__ with a path and the reStructuredText content of the header, separated by a colon: - .. code:: rst + .. code-block:: rst :ref:`introduction/intro:What is Qubes OS?` @@ -325,13 +325,13 @@ Note that with the `ref role ` @@ -411,7 +411,7 @@ To do such a cross-reference, use the usual cross-reference syntax but with the * - reStructuredText markup - output - * - .. code:: rst + * - .. code-block:: rst :doc:`core-admin:index` @@ -425,7 +425,7 @@ Even if it works without it, **always prefix the external cross-references** wit Intersphinx `can list all the available links `__ to another project with the following command: - .. code:: console + .. code-block:: console python3 -m sphinx.ext.intersphinx https://dev.qubes-os.org/projects/core-admin/en/latest/objects.inv @@ -445,7 +445,7 @@ You can create a reference to `any documented python objects ` to shorten the link lab * - reStructuredText markup - output - * - .. code:: rst + * - .. code-block:: rst :py:class:`~core-admin:qubes.vm.dispvm.DispVM` @@ -480,7 +480,7 @@ Do not use a :ref:`custom title ` to shorten the link lab **If a cross-reference points to a missing reference** (i.e.: reference to a removed component), prefix the reference with an exclamation mark (``!``). If the function :py:func:`!old_function` has been removed but is still referenced, to discuss the old implementation use: -.. code:: rst +.. code-block:: rst :py:func:`!old_function` @@ -489,13 +489,13 @@ Hyperlink to other websites syntax Use `embedded links `__ like -.. code:: rst +.. code-block:: rst `website `__ **Do not use reference-style links** like -.. code:: rst +.. code-block:: rst Some text link_ @@ -536,7 +536,7 @@ Although possible, using a level under the paragraph level should be avoided. Here is a simple example of a page with a title and three nested levels of heading: -.. code:: rst +.. code-block:: rst ========== Main Title @@ -561,19 +561,19 @@ Emphasis and Italics - *Italics*: Use single asterisks - .. code:: rst + .. code-block:: rst *italics* - **Bold**: Use double asterisks. - .. code:: rst + .. code-block:: rst **bold** - ``Monospace``: Use backticks. - .. code:: rst + .. code-block:: rst ``monospace`` @@ -620,11 +620,11 @@ Writing command-line examples * - reStructuredText markup - output - * - .. code:: rst + * - .. code-block:: rst Open a terminal in dom0 and run: - .. code:: console + .. code-block:: console [user@dom0] $ cd test [user@dom0 ~/test] $ echo Hello @@ -632,7 +632,7 @@ Writing command-line examples - Open a terminal in dom0 and run: - .. code:: console + .. code-block:: console [user@dom0] $ cd test [user@dom0 ~/test] $ echo Hello @@ -654,46 +654,46 @@ Writing command-line examples - output * - minimal - - .. code:: rst + - .. code-block:: rst - .. code:: console + .. code-block:: console $ cd test - - .. code:: console + - .. code-block:: console $ cd test * - qube name - - .. code:: rst + - .. code-block:: rst - .. code:: console + .. code-block:: console [dom0] $ cd test - - .. code:: console + - .. code-block:: console [dom0] $ cd test * - with path - - .. code:: rst + - .. code-block:: rst - .. code:: console + .. code-block:: console [dom0 /tmp] $ cd test - - .. code:: console + - .. code-block:: console [dom0 /tmp] $ cd test * - full - - .. code:: rst + - .. code-block:: rst - .. code:: console + .. code-block:: console [user@dom0 /tmp] $ cd test - - .. code:: console + - .. code-block:: console [user@dom0 /tmp] $ cd test @@ -701,7 +701,7 @@ Writing command-line examples **Don’t try to add comments inside the code block**. For example, *don’t* do this: - .. code:: console + .. code-block:: console # Navigate to the new directory $ cd test @@ -717,7 +717,7 @@ Variable names in commands **Syntactically distinguish variables in commands**. For example, this is ambiguous: -.. code:: console +.. code-block:: console $ qvm-run --dispvm=disposable-template --service qubes.StartApp+xterm @@ -725,7 +725,7 @@ Variable names in commands It should instead be: -.. code:: console +.. code-block:: console $ qvm-run --dispvm= --service qubes.StartApp+xterm @@ -832,7 +832,7 @@ Cheatsheet: Headings * - Markdown markup - reStructuredText markup - * - .. code:: markdown + * - .. code-block:: markdown [...] # Title @@ -847,7 +847,7 @@ Cheatsheet: Headings #### Paragraph [...] - - .. code:: rst + - .. code-block:: rst ===== Title @@ -872,35 +872,35 @@ Cheatsheet: Hyperlinks and cross-references * - Markdown markup - reStructuredText markup - * - .. code:: markdown + * - .. code-block:: markdown [Link Text](/doc/path/to/some-file) - - .. code:: rst + - .. code-block:: rst :doc:`/path/to/some-file` - * - .. code:: markdown + * - .. code-block:: markdown [Link Text](/doc/path/to/some-file#some-title) - - .. code:: rst + - .. code-block:: rst :ref:`/path/to/some-file:Some title` - * - .. code:: markdown + * - .. code-block:: markdown a [qube](/doc/glossary#qube) - - .. code:: rst + - .. code-block:: rst :term:`qube` - * - .. code:: markdown + * - .. code-block:: markdown [Link Text](http://example.com) - - .. code:: rst + - .. code-block:: rst `Link Text `__ @@ -914,31 +914,31 @@ Cheatsheet: Text Decorations * - Markdown markup - reStructuredText markup - * - .. code:: markdown + * - .. code-block:: markdown *Italic* or _Italic_ - - .. code:: rst + - .. code-block:: rst *Italic* - * - .. code:: markdown + * - .. code-block:: markdown **Bold** or __Bold__ - - .. code:: rst + - .. code-block:: rst **Bold** - * - .. code:: markdown + * - .. code-block:: markdown ~~Strikethrough~~ - - .. code:: rst + - .. code-block:: rst :strike:`Strikethrough` - * - .. code:: markdown + * - .. code-block:: markdown ***Bold and italic*** @@ -960,7 +960,7 @@ Cheatsheet: Lists * - Markdown markup - reStructuredText markup - * - .. code:: markdown + * - .. code-block:: markdown - Item 1 - Item 2 @@ -972,7 +972,7 @@ Cheatsheet: Lists a. Subitem 1 b. Subitem 2 - - .. code:: rst + - .. code-block:: rst - Item 1 - Item 2 @@ -998,14 +998,14 @@ Cheatsheet: Tables * - Markdown markup - reStructuredText markup - * - .. code:: markdown + * - .. code-block:: markdown | Header 1 | Header 2 | |----------|----------| | Cell 1 | Cell 2 | | Cell 3 | Cell 4 | - - .. code:: rst + - .. code-block:: rst .. list-table:: :widths: 10 10 @@ -1032,14 +1032,14 @@ Cheatsheet: Code Blocks * - Markdown markup - reStructuredText markup - * - .. code:: markdown + * - .. code-block:: markdown ```python print("Hello, world!") ``` - - .. code:: rst + - .. code-block:: rst - .. code:: python + .. code-block:: python print("Hello, world!") @@ -1057,14 +1057,14 @@ Alerts and Warnings * - Markdown markup - reStructuredText markup - * - .. code:: markdown + * - .. code-block:: markdown - - .. code:: rst + - .. code-block:: rst .. note:: @@ -1091,7 +1091,7 @@ List of the roles used in documentation * - `:guilabel: `__ - - .. code:: rst + - .. code-block:: rst :guilabel:`&Apply` @@ -1099,7 +1099,7 @@ List of the roles used in documentation * - `:file: `__ - - .. code:: rst + - .. code-block:: rst :file:`~/QubesIncoming/disp{XXXX}` @@ -1107,7 +1107,7 @@ List of the roles used in documentation * - `:program: `__ - - .. code:: rst + - .. code-block:: rst :program:`qvm-copy` @@ -1115,7 +1115,7 @@ List of the roles used in documentation * - `:menuselection: `__ - - .. code:: rst + - .. code-block:: rst :menuselection:`Settings --> &Advanced` @@ -1123,7 +1123,7 @@ List of the roles used in documentation * - `:samp: `__ - - .. code:: rst + - .. code-block:: rst :samp:`disp{XXXX}` @@ -1131,7 +1131,7 @@ List of the roles used in documentation * - `:kbd: `__ - - .. code:: rst + - .. code-block:: rst :kbd:`Ctrl` @@ -1139,7 +1139,7 @@ List of the roles used in documentation * - `:abbr: `__ - - .. code:: rst + - .. code-block:: rst :abbr:`OCR (Optical Character Recognition)` @@ -1147,7 +1147,7 @@ List of the roles used in documentation * - `:code: `__ - - .. code:: rst + - .. code-block:: rst :code:`qvm-ls --help` @@ -1155,7 +1155,7 @@ List of the roles used in documentation * - `:mimetype: `__ - - .. code:: rst + - .. code-block:: rst :mimetype:`application/pdf` diff --git a/developer/general/usability-ux.rst b/developer/general/usability-ux.rst index c3f9515e87..f428d8fb3a 100644 --- a/developer/general/usability-ux.rst +++ b/developer/general/usability-ux.rst @@ -124,7 +124,7 @@ By using the same term throughout an interface, a user can create a mental model It is easy to add words like ``Domain`` before items in a list or menu in an attempt to be descriptive, such as: -.. code:: text +.. code-block:: text Menu - Domain: work @@ -137,7 +137,7 @@ The repeated use of the word ``Domain`` requires a user to read it for each item It is more efficient to group things under headings instead as this allows the eye to easily scan the uniqueness of the items. (As per our previous example:) -.. code:: text +.. code-block:: text Domains - Work diff --git a/developer/general/website-style-guide.rst b/developer/general/website-style-guide.rst index 3e6c923d42..54e969c490 100644 --- a/developer/general/website-style-guide.rst +++ b/developer/general/website-style-guide.rst @@ -39,7 +39,7 @@ Indentation example Here’s an example that follows the indentation rules: -.. code:: html +.. code-block:: html @@ -97,7 +97,7 @@ Image linking To add an image to a page, use the following syntax in the main document. -.. code:: markdown +.. code-block:: markdown [![Image Title](/attachment/doc/image.png)](/attachment/doc/image.png) @@ -143,7 +143,7 @@ Do not use Markdown syntax for styling For example, there is a common temptation to use block quotations (created by beginning lines with the ``>`` character) in order to stylistically distinguish some portion of text from the rest of the document, e.g.: -.. code:: markdown +.. code-block:: markdown > **Note:** This is an important note! @@ -163,7 +163,7 @@ There are two problems with this: Instead, an example of an appropriate way to stylistically distinguish a portion of text is by using :ref:`developer/general/website-style-guide:alerts`. Consider also that extra styling and visual distinction may not even be necessary. In most cases, traditional writing methods are perfectly sufficient, e.g.,: -.. code:: markdown +.. code-block:: markdown **Note:** This is an important note. @@ -177,7 +177,7 @@ Alerts Alerts are sections of HTML used to draw the reader’s attention to important information, such as warnings, and for stylistic purposes. They are typically styled as colored text boxes, usually accompanied by icons. Alerts should generally be used somewhat sparingly, so as not to cause `alert fatigue `__ and since they must be written in HTML instead of Markdown, which makes the source less readable and more difficult to work with for localization and automation purposes. Here are examples of several types of alerts and their recommended icons: -.. code:: html +.. code-block:: html