From 7cb7d705d6e65826c03818690e2397aaf6cc5b74 Mon Sep 17 00:00:00 2001 From: Pete Johanson Date: Tue, 9 Jun 2020 16:35:47 -0400 Subject: [PATCH 01/13] Improved dev setup docs. --- docs/docs/dev-setup.md | 112 ++++++++++++++++++++++++++++++++++++++--- 1 file changed, 106 insertions(+), 6 deletions(-) diff --git a/docs/docs/dev-setup.md b/docs/docs/dev-setup.md index 8500365d..286b30c9 100644 --- a/docs/docs/dev-setup.md +++ b/docs/docs/dev-setup.md @@ -4,9 +4,109 @@ title: Basic Setup sidebar_label: Basic Setup --- -1. Install `west` from pip. -1. Install the ARM SDK from Zephyr project. -1. (Optional) Install 32-bit libs for building and testing locally. -1. `west init -l zmk` -1. Build it. -1. Flash it. +## Preprequisites + +A unix-like environment with Python 3 installed. So far this has been tested on Fedora and Debian. Further testing is required for macOS and WSL. + +## Setup + +### West Build Command + +`west` is the [Zephyr meta-tool](https://docs.zephyrproject.org/latest/guides/west/index.html) used to configure and build Zephyr applications. It can be installed by using the `pip` python package manager: + +```bash +pip install --user west +``` + +:::note +If you don't already have it configured, you may need to update your +`PATH` to include the pip install path. See [User Installs](https://pip.pypa.io/en/stable/user_guide/#user-installs) and (Stack Overflow)[https://stackoverflow.com/questions/38112756/how-do-i-access-packages-installed-by-pip-user] for more details. +::: + +### Zephyr ARM SDK + +To build firmwares for the ARM architecture (all supported MCUs/keyboards at this point), you'll need to install the Zephyr ARM SDK to your system: + +``` +export ZSDK_VERSION=0.11.3 +wget -q "https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v${ZSDK_VERSION}/zephyr-toolchain-arm-${ZSDK_VERSION}-setup.run" && \ + sh "zephyr-toolchain-arm-${ZSDK_VERSION}-setup.run" --quiet -- -d /opt/toolchains/zephyr-sdk-${ZSDK_VERSION} && \ + rm "zephyr-toolchain-arm-${ZSDK_VERSION}-setup.run" +``` + +### Source Code + +Next, you'll need to clone the ZMK source repository if you haven't already: + +``` +git clone https://github.com/zmkfirmware/zmk.git +``` + +### Initialize & Update Zephy Workspace + +Since ZMK is build as a Zephyr application, the next step is +to use `west` to initialize and update your workspace. The ZMK +Zephyr application is in the `app/` source directory: + +#### Initialize West + +```bash +west init -l app/ +``` + +#### Update To Fetch Modules + +```bash +west update +``` + +#### Export Zephyr Core + +```bash +west zephyr-export +``` + +## Build + +To build for your particular keyboard, the behaviour varies slightly depending on if you are building for a keyboard with +an onboard MCU, or one that uses a MCU board addon. + +### Keyboard (Shield) + MCU Board + +ZMK treats keyboards that take a MCU addon board as [shields](https://docs.zephyrproject.org/latest/guides/porting/shields.html), and treats the smaller MCU board as the true [board](https://docs.zephyrproject.org/latest/guides/porting/board_porting.html) + +Given the following: + +- MCU Board: Proton-C +- Keyboard PCB: kyria +- Keymap: default + +You can build ZMK with the following: + +```bash +west build -b proton_c -- -DSHIELD=kyria -DKEYMAP=default +``` + +### Keyboard With Onboard MCU + +Keyboards with onboard MCU chips are simply treated as the [board](https://docs.zephyrproject.org/latest/guides/porting/board_porting.html) as far as Zephyr is concerned. + +Given the following: + +- Keyboard: Planck +- Keymap: default + +you can build ZMK with the following: + +```bash +west build -b planck -- -DKEYMAP=default +``` + +## Flashing + +Once built, the previously supplied parameters will be remember, so you can simply run the following to flash your +board, with it in bootloader mode: + +``` +west flash +``` From 4ea641f34a8f097209cefa9d8095ced7dd520897 Mon Sep 17 00:00:00 2001 From: Pete Johanson Date: Tue, 9 Jun 2020 17:00:22 -0400 Subject: [PATCH 02/13] =?UTF-8?q?Typo=20fix,=20add=20=E2=84=A2=20properly.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 4 ++-- docs/docs/dev-setup.md | 14 +++++++------- docs/docs/intro.md | 2 +- 3 files changed, 10 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index f4a05bad..916ed7fd 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,11 @@ -# Zephyr Mechanical Keyboard (ZMK) Firmware +# Zephyr™ Mechanical Keyboard (ZMK) Firmware [![Build](https://github.com/zmkfirmware/zmk/workflows/Build/badge.svg)](https://github.com/zmkfirmware/zmk/actions) [![Netlify Status](https://api.netlify.com/api/v1/badges/942d61a9-87c0-4c23-9b51-f5ed0bce495d/deploy-status)](https://app.netlify.com/sites/zmk/deploys) This project is a complete work in progress, with absolutely nothing functioning yet. The goal is to explore a new MK firmware -with a less restritive license and better BLE support, built on top of the [Zephyr Project](https://www.zephyrproject.org/) +with a less restritive license and better BLE support, built on top of the [Zephyr™ Project](https://www.zephyrproject.org/) Basic WIP website to learn more: https://zmk.netlify.app/ diff --git a/docs/docs/dev-setup.md b/docs/docs/dev-setup.md index 286b30c9..9946438f 100644 --- a/docs/docs/dev-setup.md +++ b/docs/docs/dev-setup.md @@ -12,7 +12,7 @@ A unix-like environment with Python 3 installed. So far this has been tested on ### West Build Command -`west` is the [Zephyr meta-tool](https://docs.zephyrproject.org/latest/guides/west/index.html) used to configure and build Zephyr applications. It can be installed by using the `pip` python package manager: +`west` is the [Zephyr™ meta-tool](https://docs.zephyrproject.org/latest/guides/west/index.html) used to configure and build Zephyr™ applications. It can be installed by using the `pip` python package manager: ```bash pip install --user west @@ -23,9 +23,9 @@ If you don't already have it configured, you may need to update your `PATH` to include the pip install path. See [User Installs](https://pip.pypa.io/en/stable/user_guide/#user-installs) and (Stack Overflow)[https://stackoverflow.com/questions/38112756/how-do-i-access-packages-installed-by-pip-user] for more details. ::: -### Zephyr ARM SDK +### Zephyr™ ARM SDK -To build firmwares for the ARM architecture (all supported MCUs/keyboards at this point), you'll need to install the Zephyr ARM SDK to your system: +To build firmwares for the ARM architecture (all supported MCUs/keyboards at this point), you'll need to install the Zephyr™ ARM SDK to your system: ``` export ZSDK_VERSION=0.11.3 @@ -44,9 +44,9 @@ git clone https://github.com/zmkfirmware/zmk.git ### Initialize & Update Zephy Workspace -Since ZMK is build as a Zephyr application, the next step is +Since ZMK is built as a Zephyr™ application, the next step is to use `west` to initialize and update your workspace. The ZMK -Zephyr application is in the `app/` source directory: +Zephyr™ application is in the `app/` source directory: #### Initialize West @@ -60,7 +60,7 @@ west init -l app/ west update ``` -#### Export Zephyr Core +#### Export Zephyr™ Core ```bash west zephyr-export @@ -89,7 +89,7 @@ west build -b proton_c -- -DSHIELD=kyria -DKEYMAP=default ### Keyboard With Onboard MCU -Keyboards with onboard MCU chips are simply treated as the [board](https://docs.zephyrproject.org/latest/guides/porting/board_porting.html) as far as Zephyr is concerned. +Keyboards with onboard MCU chips are simply treated as the [board](https://docs.zephyrproject.org/latest/guides/porting/board_porting.html) as far as Zephyr™ is concerned. Given the following: diff --git a/docs/docs/intro.md b/docs/docs/intro.md index 82def2fe..f38d293a 100644 --- a/docs/docs/intro.md +++ b/docs/docs/intro.md @@ -5,7 +5,7 @@ sidebar_label: Introduction --- ZMK Firmware is an open source (MIT) keyboard -firmware built on the [Zephyr Project](https://zephyrproject.com/) RTOS. +firmware built on the [Zephyr™ Project](https://zephyrproject.com/) RTOS. The goal is to provider a powerful, featureful keyboard firmware that is free of licensing issues that prevent upstream BLE support as a first-class From a709e956802b872421d373bb98816c1e75ca3805 Mon Sep 17 00:00:00 2001 From: Pete Johanson Date: Tue, 9 Jun 2020 23:15:02 -0400 Subject: [PATCH 03/13] Fill out dev setup even more. --- docs/docs/dev-setup.md | 54 +++++++++++++++++++++++++++++++++++++++--- 1 file changed, 51 insertions(+), 3 deletions(-) diff --git a/docs/docs/dev-setup.md b/docs/docs/dev-setup.md index 9946438f..9ddb6141 100644 --- a/docs/docs/dev-setup.md +++ b/docs/docs/dev-setup.md @@ -6,7 +6,52 @@ sidebar_label: Basic Setup ## Preprequisites -A unix-like environment with Python 3 installed. So far this has been tested on Fedora and Debian. Further testing is required for macOS and WSL. +A unix-like environment with the following base packages installed: + +- Python 3 +- `pip` +- `wget` +- devicetree compiler +- CMake +- `dfu-util` +- Various build essentials, e.g. gcc, automake, autoconf + +### Debian/Ubuntu + +On Debian and Ubuntu, this can be accomplished with: + +```bash +apt-get install -y \ + autoconf \ + automake \ + build-essential \ + ccache \ + device-tree-compiler \ + dfu-util \ + g++ \ + gcc \ + gcc-multilib \ + libtool \ + make \ + cmake \ + ninja-build \ + python3-dev \ + python3-pip \ + python3-setuptools \ + xz-utils +``` + +### Fedora + +TODO + +### macOS + +TODO + +### WSL + +TODO ## Setup @@ -15,7 +60,7 @@ A unix-like environment with Python 3 installed. So far this has been tested on `west` is the [Zephyr™ meta-tool](https://docs.zephyrproject.org/latest/guides/west/index.html) used to configure and build Zephyr™ applications. It can be installed by using the `pip` python package manager: ```bash -pip install --user west +pip3 install --user west ``` :::note @@ -34,6 +79,8 @@ wget -q "https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v${ZSDK_ rm "zephyr-toolchain-arm-${ZSDK_VERSION}-setup.run" ``` +The installation will prompt with several questions about installation location, and creating a default `~/.zephyrrc` for you with various variables. The defaults shouldn normally work as expected. + ### Source Code Next, you'll need to clone the ZMK source repository if you haven't already: @@ -68,7 +115,8 @@ west zephyr-export ## Build -To build for your particular keyboard, the behaviour varies slightly depending on if you are building for a keyboard with +Actually building the ZMK firmware occurs within the `app/` subdirectory +of the ZMK repository. To build for your particular keyboard, the behaviour varies slightly depending on if you are building for a keyboard with an onboard MCU, or one that uses a MCU board addon. ### Keyboard (Shield) + MCU Board From 5cebba16372c265893d1a502396adbdda5d982b2 Mon Sep 17 00:00:00 2001 From: Pete Johanson Date: Wed, 10 Jun 2020 00:05:28 -0400 Subject: [PATCH 04/13] Various docs fixes, including PR feedback. --- docs/docs/dev-setup.md | 40 ++++++++++++++++++++++++++++++++++++---- 1 file changed, 36 insertions(+), 4 deletions(-) diff --git a/docs/docs/dev-setup.md b/docs/docs/dev-setup.md index 9ddb6141..302a75ab 100644 --- a/docs/docs/dev-setup.md +++ b/docs/docs/dev-setup.md @@ -4,10 +4,11 @@ title: Basic Setup sidebar_label: Basic Setup --- -## Preprequisites +## Prerequisites A unix-like environment with the following base packages installed: +- Git - Python 3 - `pip` - `wget` @@ -22,6 +23,8 @@ On Debian and Ubuntu, this can be accomplished with: ```bash apt-get install -y \ + git \ + wget \ autoconf \ automake \ build-essential \ @@ -34,7 +37,6 @@ apt-get install -y \ libtool \ make \ cmake \ - ninja-build \ python3-dev \ python3-pip \ python3-setuptools \ @@ -65,7 +67,7 @@ pip3 install --user west :::note If you don't already have it configured, you may need to update your -`PATH` to include the pip install path. See [User Installs](https://pip.pypa.io/en/stable/user_guide/#user-installs) and (Stack Overflow)[https://stackoverflow.com/questions/38112756/how-do-i-access-packages-installed-by-pip-user] for more details. +`PATH` to include the pip install path. See [User Installs](https://pip.pypa.io/en/stable/user_guide/#user-installs) and [Stack Overflow](https://stackoverflow.com/questions/38112756/how-do-i-access-packages-installed-by-pip-user) for more details. ::: ### Zephyr™ ARM SDK @@ -73,7 +75,7 @@ If you don't already have it configured, you may need to update your To build firmwares for the ARM architecture (all supported MCUs/keyboards at this point), you'll need to install the Zephyr™ ARM SDK to your system: ``` -export ZSDK_VERSION=0.11.3 +export ZSDK_VERSION=0.11.2 wget -q "https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v${ZSDK_VERSION}/zephyr-toolchain-arm-${ZSDK_VERSION}-setup.run" && \ sh "zephyr-toolchain-arm-${ZSDK_VERSION}-setup.run" --quiet -- -d /opt/toolchains/zephyr-sdk-${ZSDK_VERSION} && \ rm "zephyr-toolchain-arm-${ZSDK_VERSION}-setup.run" @@ -113,6 +115,36 @@ west update west zephyr-export ``` +### Environment Variables + +By default, the Zephyr™ SDK will create a file named `~/.zephyrrc` with the correct environment variables to build ZMK. +We suggest two main [options](https://docs.zephyrproject.org/latest/guides/env_vars.html?highlight=zephyrrc) for how to load those settings. + +#### Per Shell + +To load the Zephyr environment properly for just one transient shell, run: + +``` +source zmk/zephyr/zephyr-env.sh +``` + +#### All Shells + +To load the environment variables for your shell every time, +append the existing `~/.zephyrrc` file to your shell's RC file, e.g. + +##### Bash + +``` +cat ~/.zephyrc >> ~/.bashrc +``` + +##### ZSH + +``` +cat ~/.zephyrc >> ~/.zshrc +``` + ## Build Actually building the ZMK firmware occurs within the `app/` subdirectory From 2c63214c7d331f6ace4a3dd9a9ecd1fc20b2ce6a Mon Sep 17 00:00:00 2001 From: Pete Johanson Date: Wed, 10 Jun 2020 00:13:55 -0400 Subject: [PATCH 05/13] A few more missing build steps. --- docs/docs/dev-setup.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/docs/dev-setup.md b/docs/docs/dev-setup.md index 302a75ab..ea6772dd 100644 --- a/docs/docs/dev-setup.md +++ b/docs/docs/dev-setup.md @@ -36,6 +36,7 @@ apt-get install -y \ gcc-multilib \ libtool \ make \ + ninja-build \ cmake \ python3-dev \ python3-pip \ @@ -115,6 +116,12 @@ west update west zephyr-export ``` +#### Install Zephyr Python Dependencies + +```bash +pip3 install --user -r zephyr/scripts/requirements.txt +``` + ### Environment Variables By default, the Zephyr™ SDK will create a file named `~/.zephyrrc` with the correct environment variables to build ZMK. @@ -131,7 +138,7 @@ source zmk/zephyr/zephyr-env.sh #### All Shells To load the environment variables for your shell every time, -append the existing `~/.zephyrrc` file to your shell's RC file, e.g. +append the existing `~/.zephyrrc` file to your shell's RC file and then start a new shell. ##### Bash From 35d07cff172f5667f52255690220959874ca9983 Mon Sep 17 00:00:00 2001 From: Pete Johanson Date: Wed, 10 Jun 2020 10:06:55 -0400 Subject: [PATCH 06/13] Apply suggestions from code review Co-authored-by: Nick Winans --- docs/docs/dev-setup.md | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/docs/docs/dev-setup.md b/docs/docs/dev-setup.md index ea6772dd..2c39d992 100644 --- a/docs/docs/dev-setup.md +++ b/docs/docs/dev-setup.md @@ -22,7 +22,8 @@ A unix-like environment with the following base packages installed: On Debian and Ubuntu, this can be accomplished with: ```bash -apt-get install -y \ +sudo apt update +sudo apt install -y \ git \ wget \ autoconf \ @@ -54,7 +55,13 @@ TODO ### WSL -TODO +Windows Subsystem for Linux can use various Linux distributions. Find a WSL installation on the [Windows Store](https://aka.ms/wslstore). + +After installing your preferred flavor, follow the directions above on [Debian/Ubuntu](#debianubuntu) or [Fedora](#fedora). + +:::note +On WSL2 don't put the project files into `/mnt/c/` as file I/O speeds are extremely slow. Instead, run everything in the Linux system and use `cp` to move files over to `/mnt/c/` as needed. +::: ## Setup @@ -92,11 +99,16 @@ Next, you'll need to clone the ZMK source repository if you haven't already: git clone https://github.com/zmkfirmware/zmk.git ``` -### Initialize & Update Zephy Workspace +### Initialize & Update Zephyr Workspace Since ZMK is built as a Zephyr™ application, the next step is to use `west` to initialize and update your workspace. The ZMK Zephyr™ application is in the `app/` source directory: +### Step into the repository + +```bash +cd zmk +``` #### Initialize West From 9e62cc7069fe5bf8e75128ea6d092160013aa9cb Mon Sep 17 00:00:00 2001 From: Pete Johanson Date: Wed, 10 Jun 2020 10:30:28 -0400 Subject: [PATCH 07/13] Fix a `.zephyrrc` typo. --- docs/docs/dev-setup.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/docs/dev-setup.md b/docs/docs/dev-setup.md index 2c39d992..9939349c 100644 --- a/docs/docs/dev-setup.md +++ b/docs/docs/dev-setup.md @@ -104,6 +104,7 @@ git clone https://github.com/zmkfirmware/zmk.git Since ZMK is built as a Zephyr™ application, the next step is to use `west` to initialize and update your workspace. The ZMK Zephyr™ application is in the `app/` source directory: + ### Step into the repository ```bash @@ -155,13 +156,13 @@ append the existing `~/.zephyrrc` file to your shell's RC file and then start a ##### Bash ``` -cat ~/.zephyrc >> ~/.bashrc +cat ~/.zephyrrc >> ~/.bashrc ``` ##### ZSH ``` -cat ~/.zephyrc >> ~/.zshrc +cat ~/.zephyrrc >> ~/.zshrc ``` ## Build From 2f4bc94b7e4b54ca423fce45e1acc5e25b79bd55 Mon Sep 17 00:00:00 2001 From: Pete Johanson Date: Wed, 10 Jun 2020 10:31:21 -0400 Subject: [PATCH 08/13] Tweaks to sourcing the `zephyr-env.sh` script. --- docs/docs/dev-setup.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs/dev-setup.md b/docs/docs/dev-setup.md index 9939349c..beca83de 100644 --- a/docs/docs/dev-setup.md +++ b/docs/docs/dev-setup.md @@ -142,10 +142,10 @@ We suggest two main [options](https://docs.zephyrproject.org/latest/guides/env_v #### Per Shell -To load the Zephyr environment properly for just one transient shell, run: +To load the Zephyr environment properly for just one transient shell, run the following from your ZMK checkout directory: ``` -source zmk/zephyr/zephyr-env.sh +source zephyr/zephyr-env.sh ``` #### All Shells From 6ef823be3ab475b36c242abb2fe3514869f188a0 Mon Sep 17 00:00:00 2001 From: Pete Johanson Date: Wed, 10 Jun 2020 11:00:03 -0400 Subject: [PATCH 09/13] More doc tweaks for SDK install and build clarity. * Suggest installing SDK to `~/.local` directory. * Clarify about switching to `app/` before build/flash. --- docs/docs/dev-setup.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/docs/docs/dev-setup.md b/docs/docs/dev-setup.md index beca83de..fd6d1d12 100644 --- a/docs/docs/dev-setup.md +++ b/docs/docs/dev-setup.md @@ -85,7 +85,7 @@ To build firmwares for the ARM architecture (all supported MCUs/keyboards at thi ``` export ZSDK_VERSION=0.11.2 wget -q "https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v${ZSDK_VERSION}/zephyr-toolchain-arm-${ZSDK_VERSION}-setup.run" && \ - sh "zephyr-toolchain-arm-${ZSDK_VERSION}-setup.run" --quiet -- -d /opt/toolchains/zephyr-sdk-${ZSDK_VERSION} && \ + sh "zephyr-toolchain-arm-${ZSDK_VERSION}-setup.run" --quiet -- -d ~/.local/zephyr-sdk-${ZSDK_VERSION} && \ rm "zephyr-toolchain-arm-${ZSDK_VERSION}-setup.run" ``` @@ -167,8 +167,13 @@ cat ~/.zephyrrc >> ~/.zshrc ## Build -Actually building the ZMK firmware occurs within the `app/` subdirectory -of the ZMK repository. To build for your particular keyboard, the behaviour varies slightly depending on if you are building for a keyboard with +From here on, building and flashing ZMK should all be done from the `app/` subdirectory of the ZMK checkout: + +```bash +cd app +``` + +To build for your particular keyboard, the behaviour varies slightly depending on if you are building for a keyboard with an onboard MCU, or one that uses a MCU board addon. ### Keyboard (Shield) + MCU Board From 43008494c4c966cc2ced7f7a5d9d1a165b16ef88 Mon Sep 17 00:00:00 2001 From: Pete Johanson Date: Wed, 10 Jun 2020 11:07:20 -0400 Subject: [PATCH 10/13] Header level fix. --- docs/docs/dev-setup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/dev-setup.md b/docs/docs/dev-setup.md index fd6d1d12..f96ffed9 100644 --- a/docs/docs/dev-setup.md +++ b/docs/docs/dev-setup.md @@ -105,7 +105,7 @@ Since ZMK is built as a Zephyr™ application, the next step is to use `west` to initialize and update your workspace. The ZMK Zephyr™ application is in the `app/` source directory: -### Step into the repository +#### Step into the repository ```bash cd zmk From 20545ea4fa34e2b1831d11ef99311c4a2b28fc70 Mon Sep 17 00:00:00 2001 From: Pete Johanson Date: Wed, 10 Jun 2020 11:18:22 -0400 Subject: [PATCH 11/13] Add note about possible missing `west` command. --- docs/docs/dev-setup.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/docs/dev-setup.md b/docs/docs/dev-setup.md index f96ffed9..4fa01a85 100644 --- a/docs/docs/dev-setup.md +++ b/docs/docs/dev-setup.md @@ -117,6 +117,12 @@ cd zmk west init -l app/ ``` +:::note +If you encounter errors like `command not found: west` then your `PATH` environment variable is likely +missing the Python 3 user packages directory. See the [West Build Command](#west-build-command) +section again for links to how to do this +::: + #### Update To Fetch Modules ```bash From 8527102bb9dcff33574de91bcdcf32b2aabddacc Mon Sep 17 00:00:00 2001 From: Pete Johanson Date: Wed, 10 Jun 2020 11:23:42 -0400 Subject: [PATCH 12/13] Add a note about older Ubuntu LTS and CMake. --- docs/docs/dev-setup.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/docs/dev-setup.md b/docs/docs/dev-setup.md index 4fa01a85..b6edc4fc 100644 --- a/docs/docs/dev-setup.md +++ b/docs/docs/dev-setup.md @@ -45,6 +45,11 @@ sudo apt install -y \ xz-utils ``` +:::note +Ubuntu 18.04 LTS release packages a version of CMake that is too old. Please upgrade to Ubuntu 20.04 LTS +or download and install CMake version 3.13.1 or newer manually. +::: + ### Fedora TODO From 8a81dbb5fb7fe1d60b2aebec12c2c87dcda477c1 Mon Sep 17 00:00:00 2001 From: Pete Johanson Date: Wed, 10 Jun 2020 20:58:32 -0400 Subject: [PATCH 13/13] Split apt update and install into two sections. --- docs/docs/dev-setup.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/docs/docs/dev-setup.md b/docs/docs/dev-setup.md index b6edc4fc..5eacd878 100644 --- a/docs/docs/dev-setup.md +++ b/docs/docs/dev-setup.md @@ -19,10 +19,22 @@ A unix-like environment with the following base packages installed: ### Debian/Ubuntu -On Debian and Ubuntu, this can be accomplished with: +On Debian and Ubuntu, we'll use apt to install our base dependencies: + +#### Apt Update + +First, if you haven't updated recently, or if this is a new install from WSL, +you should update to get the latest package information: ```bash sudo apt update +``` + +#### Install Dependencies + +With the latest package information, you can now install the base dependencies: + +```bash sudo apt install -y \ git \ wget \