From 292b50cd643dab84fe699f656f6cf4c0497dca4f Mon Sep 17 00:00:00 2001 From: Keiichi Watanabe Date: Fri, 28 Jan 2022 21:16:30 +0900 Subject: [PATCH] docs: Cosmetic changes for code blocks * Remove leading `$`s so that readers can copy and pastes commands more easily. * Use `sh` instead of `bash` because `bash` is for scripts rather than command line interfaces. These rules are ones used in mdBook's instruction. https://github.com/rust-lang/mdBook/tree/master/guide/src/guide BUG=none TEST=mdbook build Change-Id: I3b35fa2c7b20ef10e3da78a47f41a1603744daf0 Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/platform/crosvm/+/3423292 Reviewed-by: Dennis Kempin Tested-by: kokoro Commit-Queue: Keiichi Watanabe Auto-Submit: Keiichi Watanabe --- CONTRIBUTING.md | 10 ++--- docs/book/src/building_crosvm/linux.md | 44 +++++++++---------- .../book/src/running_crosvm/advanced_usage.md | 30 ++++++------- 3 files changed, 42 insertions(+), 42 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3e2107ac85..a74467bece 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -93,13 +93,13 @@ If you are not interested in other Chromium OS components, you can simply clone crosvm only. Before you make a commit locally, please set up [Gerrit's Change-Id hook] on your system. -```bash -$ git clone https://chromium.googlesource.com/chromiumos/platform/crosvm +```sh +git clone https://chromium.googlesource.com/chromiumos/platform/crosvm # Modify code and make a git commit with a commit message following this rule: # https://chromium.googlesource.com/chromiumos/docs/+/HEAD/contributing.md#Commit-messages -$ git commit +git commit # Push your commit to Chromium Gerrit (https://chromium-review.googlesource.com/). -$ git push origin HEAD:refs/for/main +git push origin HEAD:refs/for/main ``` ### Code review @@ -150,7 +150,7 @@ through the CQ and watched by the crosvm-uprev rotation. To render the book locally, you need to install mdbook and [mdbook-mermaid], which should be installed when you run `./tools/install-deps`script. -```bash +```sh cd crosvm/docs/book/ mdbook build ``` diff --git a/docs/book/src/building_crosvm/linux.md b/docs/book/src/building_crosvm/linux.md index 7d70ab4567..47070a6454 100644 --- a/docs/book/src/building_crosvm/linux.md +++ b/docs/book/src/building_crosvm/linux.md @@ -4,7 +4,7 @@ Obtain the source code via git clone. -``` +```sh git clone https://chromium.googlesource.com/chromiumos/platform/crosvm ``` @@ -27,8 +27,8 @@ git config push.recurseSubmodules no Crosvm development best works on Debian derivatives. First install rust via https://rustup.rs/. Then for the rest, we provide a script to install the necessary packages on Debian: -``` -$ ./tools/install-deps +```sh +./tools/install-deps ``` For other systems, please see below for instructions on @@ -42,9 +42,9 @@ installation of foreign architecture packages. On Debian this is as easy as: ```sh -$ sudo dpkg --add-architecture arm64 -$ sudo dpkg --add-architecture armhf -$ sudo apt update +sudo dpkg --add-architecture arm64 +sudo dpkg --add-architecture armhf +sudo apt update ``` On ubuntu this is a little harder and needs some @@ -57,8 +57,8 @@ For other systems (**including gLinux**), please see below for instructions on With that enabled, the following scripts will install the needed packages: ```sh -$ ./tools/install-aarch64-deps -$ ./tools/install-armhf-deps +./tools/install-aarch64-deps +./tools/install-armhf-deps ``` ### Using the development container @@ -67,7 +67,7 @@ We provide a Debian container with the required packages installed. With [Docker installed](https://docs.docker.com/get-docker/), it can be started with: ```sh -$ ./tools/dev_container +./tools/dev_container ``` The container image is big and may take a while to download when first used. Once started, you can @@ -76,7 +76,7 @@ follow all instructions in this document within the container shell. Instead of using the interactive shell, commands to execute can be provided directly: ```sh -$ ./tools/dev_container cargo build +./tools/dev_container cargo build ``` Note: The container and build artifacts are preserved between calls to `./tools/dev_container`. If @@ -101,8 +101,8 @@ If you are working on aarch64 specific code, you can use the `set_test_target` t cargo to build for aarch64 and run tests on a VM: ```sh -$ ./tools/set_test_target vm:aarch64 && source .envrc -$ cd mycrate && cargo test +./tools/set_test_target vm:aarch64 && source .envrc +cd mycrate && cargo test ``` The script will start a VM for testing and write environment variables for cargo to `.envrc`. With @@ -116,28 +116,28 @@ Crosvm cannot use `cargo test --workspace` because of various restrictions of ca own test runner: ```sh -$ ./tools/run_tests +./tools/run_tests ``` Which will run all tests locally. Since we have some architecture-dependent code, we also have the option of running tests within an aarch64 VM: ```sh -$ ./tools/run_tests --target=vm:aarch64 +./tools/run_tests --target=vm:aarch64 ``` When working on a machine that does not support cross-compilation (e.g. gLinux), you can use the dev container to build and run the tests. ```sh -$ ./tools/dev_container ./tools/run_tests --target=vm:aarch64 +./tools/dev_container ./tools/run_tests --target=vm:aarch64 ``` It is also possible to run tests on a remote machine via ssh. The target architecture is automatically detected: ```sh -$ ./tools/run_tests --target=ssh:hostname +./tools/run_tests --target=ssh:hostname ``` However, it is your responsibility to make sure the required libraries for crosvm are installed and @@ -148,8 +148,8 @@ the VM has installed. To verify changes before submitting, use the `presubmit` script: -``` -$ ./tools/presubmit +```sh +./tools/presubmit ``` This will run clippy, formatters and runs all tests. The presubmits will use the dev container to @@ -157,14 +157,14 @@ build for other platforms if your host is not set up to do so. To run checks faster, they can be run in parallel in multiple tmux panes: -``` -$ ./tools/presubmit --tmux +```sh +./tools/presubmit --tmux ``` The `--quick` variant will skip some slower checks, like building for other platforms altogether: -``` -$ ./tools/presubmit --quick +```sh +./tools/presubmit --quick ``` ## Known issues diff --git a/docs/book/src/running_crosvm/advanced_usage.md b/docs/book/src/running_crosvm/advanced_usage.md index df13760128..660a708f96 100644 --- a/docs/book/src/running_crosvm/advanced_usage.md +++ b/docs/book/src/running_crosvm/advanced_usage.md @@ -6,8 +6,8 @@ To see the usage information for your version of crosvm, run `crosvm` or `crosvm To run a very basic VM with just a kernel and default devices: -```bash -$ crosvm run "${KERNEL_PATH}" +```sh +crosvm run "${KERNEL_PATH}" ``` The uncompressed kernel image, also known as vmlinux, can be found in your kernel build directory in @@ -19,8 +19,8 @@ the case of x86 at `arch/x86/boot/compressed/vmlinux`. In most cases, you will want to give the VM a virtual block device to use as a root file system: -```bash -$ crosvm run -r "${ROOT_IMAGE}" "${KERNEL_PATH}" +```sh +crosvm run -r "${ROOT_IMAGE}" "${KERNEL_PATH}" ``` The root image must be a path to a disk image formatted in a way that the kernel can read. Typically @@ -32,7 +32,7 @@ To run crosvm with a writable rootfs: > **WARNING:** Writable disks are at risk of corruption by a malicious or malfunctioning guest OS. -```bash +```sh crosvm run --rwdisk "${ROOT_IMAGE}" -p "root=/dev/vda" vmlinux ``` @@ -44,7 +44,7 @@ crosvm run --rwdisk "${ROOT_IMAGE}" -p "root=/dev/vda" vmlinux Linux kernel 5.4+ is required for using virtiofs. This is convenient for testing. The file system must be named "mtd\*" or "ubi\*". -```bash +```sh crosvm run --shared-dir "/:mtdfake:type=fs:cache=always" \ -p "rootfstype=virtiofs root=mtdfake" vmlinux ``` @@ -54,7 +54,7 @@ crosvm run --shared-dir "/:mtdfake:type=fs:cache=always" \ The most convenient way to provide a network device to a guest is to setup a persistent TAP interface on the host. This section will explain how to do this for basic IPv4 connectivity. -```bash +```sh sudo ip tuntap add mode tap user $USER vnet_hdr crosvm_tap sudo ip addr add 192.168.10.1/24 dev crosvm_tap sudo ip link set crosvm_tap up @@ -65,7 +65,7 @@ configure the host to use the IP address `192.168.10.1`, and bring the interface The next step is to make sure that traffic from/to this interface is properly routed: -```bash +```sh sudo sysctl net.ipv4.ip_forward=1 # Network interface used to connect to the internet. HOST_DEV=$(ip route get 8.8.8.8 | awk -- '{printf $5}') @@ -76,7 +76,7 @@ sudo iptables -A FORWARD -i crosvm_tap -o "${HOST_DEV}" -j ACCEPT The interface is now configured and can be used by crosvm: -```bash +```sh crosvm run \ ... --tap-name crosvm_tap \ @@ -86,7 +86,7 @@ crosvm run \ Provided the guest kernel had support for `VIRTIO_NET`, the network device should be visible and configurable from the guest: -```bash +```sh # Replace with the actual network interface name of the guest # (use "ip addr" to list the interfaces) GUEST_DEV=enp0s5 @@ -112,10 +112,10 @@ running. To tell crosvm to stop and exit, for example: > **NOTE:** If the socket path given is for a directory, a socket name underneath that path will be > generated based on crosvm's PID. -```bash -$ crosvm run -s /run/crosvm.sock ${USUAL_CROSVM_ARGS} +```sh +crosvm run -s /run/crosvm.sock ${USUAL_CROSVM_ARGS} -$ crosvm stop /run/crosvm.sock +crosvm stop /run/crosvm.sock ``` > **WARNING:** The guest OS will not be notified or gracefully shutdown. @@ -147,13 +147,13 @@ You can enable the feature by `--gdb` flag: ```sh # Use uncompressed vmlinux -$ crosvm run --gdb ${USUAL_CROSVM_ARGS} vmlinux +crosvm run --gdb ${USUAL_CROSVM_ARGS} vmlinux ``` Then, you can start GDB in another shell. ```sh -$ gdb vmlinux +gdb vmlinux (gdb) target remote : (gdb) hbreak start_kernel (gdb) c