Merge pull request #52 from mitchmindtree/wgpu

Update guide for recent trasition from vulkano to wgpu
nannou-org · Mar 3, 2020 · e6a6e34 · e6a6e34
2 parents a702ba4 + 3f8ae9e
commit e6a6e34
Show file tree

Hide file tree

Showing 7 changed files with 190 additions and 189 deletions.
diff --git a/src/SUMMARY.md b/src/SUMMARY.md
@@ -9,7 +9,7 @@
     - [Editor Setup](./getting_started/editor_setup.md)
     - [Running Examples](./getting_started/running_examples.md)
     - [Create A Project](./getting_started/create_a_project.md)
-    - [Upgrading to a New Release](./getting_started/upgrading.md)
+    - [Updating Nannou and Rust](./getting_started/updating.md)
 - [Tutorials](./tutorials.md)
     - [Basics - Anatomy of a Nannou App](./tutorials/basics/anatomy-of-a-nannou-app.md)
     - [Basics - Drawing 2D Shapes](./tutorials/basics/drawing-2d-shapes.md)

diff --git a/src/getting_started/create_a_project.md b/src/getting_started/create_a_project.md
@@ -61,7 +61,7 @@ create a new project with just a few small steps:
    fn update(_app: &App, _model: &mut Model, _update: Update) {
    }
 
-   fn view(_app: &App, _model: &Model, frame: &Frame){
+   fn view(_app: &App, _model: &Model, frame: Frame){
        frame.clear(PURPLE);
    }
    ```

diff --git a/src/getting_started/platform-specific_setup.md b/src/getting_started/platform-specific_setup.md
@@ -5,177 +5,164 @@ installing Rust and building nannou projects.
 
 Depending on what OS you are running, you might require an extra step or two.
 
-- **All Platforms**
+By the way, if you notice some steps are missing from this section of the guide,
+feel free to open an issue or PR at [the nannou guide
+repo](https://github.com/nannou-org/guide)!
 
-  For now, nannou requires that you have both `python` and `cmake` installed.
-  These are required by a tool called `shaderc`, a part of nannou's graphics
-  stack. The role of this tool is to compile GLSL shaders to SPIR-V so that we
-  may run them using the system's Vulkan implementation. There are a few
-  attempts at pure-rust alternatives to this tool in the works and we hope to
-  switch to one of these in the near future to avoid the need for these extra
-  dependencies.
+## macOS
 
-- **macOS**: Ensure that you have xcode-tools installed:
+Ensure that you have xcode-tools installed:
 
+```bash
+xcode-select --install
+```
+
+This should provide all the developer tools needed for building nannou.
+
+## Windows
+
+Rust requires the C++ build tools for Visual Studio. The Rust book has this to
+say:
+
+> On Windows, go to
+> [https://www.rust-lang.org/tools/install](https://www.rust-lang.org/tools/install)
+> and follow the instructions for installing Rust. At some point in the
+> installation, you’ll receive a message explaining that you’ll also need the
+> C++ build tools for Visual Studio 2013 or later. The easiest way to acquire
+> the build tools is to install [Build Tools for Visual Studio
+> 2019](https://www.visualstudio.com/downloads/#build-tools-for-visual-studio-2019).
+> The tools are in the Other Tools and Frameworks section.
+
+## Linux
+
+Ensure you have the following system packages installed:
+
+- **Basic dev packages**
+
+  First make sure the basic dev packages are installed.
+  - `curl` will be required by `rustup` the rust toolchain manager.
+  - `build-essential` will be required by `rustc` the rust compiler for linking.
+  - `pkg-config` is used by some build scripts to source information about
+    certain libraries.
+  - `alsa` dev packages are required for `nannou_audio`.
+
+  For Debian/Ubuntu users:
   ```bash
-  xcode-select --install
+  sudo apt-get install curl build-essential python cmake pkg-config
   ```
 
-  In case it throws an error `couldn't find required command: "cmake"`, you can install `cmake` by brew:
+- **alsa dev package**
+
+  For Fedora users:
   ```bash
-    brew install cmake
+  sudo dnf install alsa-lib-devel
   ```
 
-  In order to add support for [Vulkan](https://www.khronos.org/vulkan/) (the
-  graphics backend used by nannou) to macOS, nannou will prompt you and attempt
-  to automatically download and install the [MoltenVK
-  SDK](https://github.com/KhronosGroup/MoltenVK). MoltenVK is a driver-level
-  implementation of the Vulkan graphics and compute API, that runs on Apple's
-  Metal graphics and compute framework on both iOS and macOS. If you wish to
-  update your MoltenVK SDK version, simply remove the currently installed SDK
-  (this should be at `~/.vulkan_sdk`) and nannou will prompt you about
-  downloading and installing the next version the next time you attempt to build
-  a nannou project.
+  For Debian/Ubuntu users:
+  ```bash
+  sudo apt-get install libasound2-dev
+  ```
 
-- **Windows**: Install the `ninja` tool.
+  For Arch users:
+  ```bash
+  sudo pacman -S alsa-lib
+  ```
+
+- **curl lib dev package**
 
-  This tool is another required by the `shaderc` tool as mentioned under the
-  "All Platforms" section above.
+  Nannou depends on the `curl-sys` crate. Some Linux distributions use
+  LibreSSL instead of OpenSSL (such as AlpineLinux, Voidlinux, possibly
+  [others](https://en.wikipedia.org/wiki/LibreSSL#Adoption) if manually
+  installed).
 
-  1. Download the latest release of ninja from the [ninja releases
-     page](https://github.com/ninja-build/ninja/releases).
-  2. Place the `ninja.exe` file somewhere you are happy for it to stay.
-  3. Add the directory containing `ninja.exe` to your `Path` environment
-     variable if it is not already included.
-  4. Donwload [cmake](https://cmake.org/download/)
-  5. Download and install [Python](https://www.python.org/downloads/windows/)
+- **xcb**
 
-- **Linux**: ensure you have the following system packages installed:
+  The XCB library provides inter-operability with Xlib.
 
-  - **Basic dev packages**
+  For Debian/Ubuntu users:
+  ```bash
+  sudo apt install libxcb-shape0-dev libxcb-xfixes0-dev
+  ```
 
-    First make sure our basic dev packages are installed. `curl` will be
-    required by `rustup` the rust toolchain manager. `build-essential` will be
-    required by `rustc` the rust compiler for linking. `cmake` and `python` are
-    necessary for nannou's `shaderc` dependency to build, as mentioned in the
-    "All Platforms" section above. `pkg-config`will be used to retrieve 
-    information about `alsa` during the building process.
+  You might also need `python3` for the `xcb` crate's build script.
 
-    For Debian/Ubuntu users:
-    ```bash
-    sudo apt-get install curl build-essential python cmake pkg-config
-    ```
+- **vulkan**
 
-  - **alsa dev package**
+  Installing Vulkan support on Linux is generally quite easy using your
+  distro's package manager. That said, there may be different driver
+  options to consider depending on your graphics card and tolerance for
+  proprietary software. The following are rough guidelines on how to get
+  going quickly, however if you are at all concerned with finding the
+  approach that suits you best we recommend searching for vulkan driver
+  installation for your graphics card on your distro.
 
-    For Fedora users:
-    ```bash
-    sudo dnf install alsa-lib-devel
-    ```
+  For Fedora with AMD graphic cards:
+  ```bash
+  sudo dnf install vulkan vulkan-info
+  ```
+
+  For Fedora with NVIDIA graphic cards:
+  Add the proprietary drivers
+  ```bash
+  sudo dnf install https://download1.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm https://download1.rpmfusion.org/nonfree/fedora/rpmfusion-nonfree-release-$(rpm -E %fedora).noarch.rpm
+  ```
+  and run
+  ```bash
+  sudo dnf install xorg-x11-drv-nvidia akmod-nvidia vulkan-tools
+  ```
 
-    For Debian/Ubuntu users:
-    ```bash
-    sudo apt-get install libasound2-dev
-    ```
+  For Debian with AMD or Intel graphic cards:
+  ```bash
+  sudo apt-get install libvulkan1 mesa-vulkan-drivers vulkan-utils
+  ```
 
-    For Arch users:
-    ```bash
-    sudo pacman -S alsa-lib
-    ```
+  For Debian with NVIDIA graphic cards:
+  ```bash
+  sudo apt-get install vulkan-utils
+  ```
 
-  - **curl lib dev package**
+  For Ubuntu users with AMD or Intel graphic cards:
+  Add a PPA for the latest drivers
+  ```bash
+  sudo add-apt-repository ppa:oibaf/graphics-drivers
+  sudo apt-get update
+  sudo apt-get upgrade
+  ```
+  and run
+  ```bash
+  sudo apt-get install libvulkan1 mesa-vulkan-drivers vulkan-utils
+  ```
 
-    Nannou depends on the `curl-sys` crate. Some Linux distributions use
-    LibreSSL instead of OpenSSL (such as AlpineLinux, Voidlinux, possibly
-    [others](https://en.wikipedia.org/wiki/LibreSSL#Adoption) if manually
-    installed).
+  For Ubuntu users with NVIDIA graphic cards:
+  Add a PPA for the latest drivers
+  ```bash
+  sudo add-apt-repository ppa:graphics-drivers/ppa
+  sudo apt-get update
+  sudo apt-get upgrade
+  ```
+  and run
+  ```bash
+  sudo apt-get install nvidia-graphics-drivers-396 nvidia-settings vulkan vulkan-utils
+  ```
 
-  - **xcb**
+  For Arch with AMD graphic cards:
+  ```bash
+  sudo pacman -S vulkan-radeon lib32-vulkan-radeon
+  ```
 
-    The XCB library provides inter-operability with Xlib. 
-
-    For Debian/Ubuntu users:
-    ```bash
-    sudo apt install libxcb-shape0-dev libxcb-xfixes0-dev
-    ```
-
-  - **vulkan**
-
-    Installing Vulkan support on Linux is generally quite easy using your
-    distro's package manager. That said, there may be different driver
-    options to consider depending on your graphics card and tolerance for
-    proprietary software. The following are rough guidelines on how to get
-    going quickly, however if you are at all concerned with finding the
-    approach that suits you best we recommend searching for vulkan driver
-    installation for your graphics card on your distro.
-
-    For Fedora with AMD graphic cards:
-    ```bash
-    sudo dnf install vulkan vulkan-info
-    ```
-
-    For Fedora with NVIDIA graphic cards:
-    Add the proprietary drivers
-    ```bash
-    sudo dnf install https://download1.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm https://download1.rpmfusion.org/nonfree/fedora/rpmfusion-nonfree-release-$(rpm -E %fedora).noarch.rpm
-    ```
-    and run
-    ```bash
-    sudo dnf install xorg-x11-drv-nvidia akmod-nvidia vulkan-tools
-    ```
-
-    For Debian with AMD or Intel graphic cards:
-    ```bash
-    sudo apt-get install libvulkan1 mesa-vulkan-drivers vulkan-utils
-    ```
-
-    For Debian with NVIDIA graphic cards:
-    ```bash
-    sudo apt-get install vulkan-utils
-    ```
-
-    For Ubuntu users with AMD or Intel graphic cards:
-    Add a PPA for the latest drivers
-    ```bash
-    sudo add-apt-repository ppa:oibaf/graphics-drivers
-    sudo apt-get update
-    sudo apt-get upgrade
-    ```
-    and run
-    ```bash
-    sudo apt-get install libvulkan1 mesa-vulkan-drivers vulkan-utils
-    ```
-
-    For Ubuntu users with NVIDIA graphic cards:
-    Add a PPA for the latest drivers
-    ```bash
-    sudo add-apt-repository ppa:graphics-drivers/ppa
-    sudo apt-get update
-    sudo apt-get upgrade
-    ```
-    and run
-    ```bash
-    sudo apt-get install nvidia-graphics-drivers-396 nvidia-settings vulkan vulkan-utils
-    ```
-
-    For Arch with AMD graphic cards:
-    ```bash
-    sudo pacman -S vulkan-radeon lib32-vulkan-radeon
-    ```
-    
-    For Arch with Intel graphics card:
-    ```bash
-    sudo pacman -S vulkan-intel
-    ```
-
-    For Arch with NVIDIA graphic cards:
-    ```bash
-    sudo pacman -S nvidia lib32-nvidia-utils
-    ```
-
-    For Gentoo run:
-    ```bash
-    sudo emerge --ask --verbose dev-util/vulkan-tools dev-util/vulkan-headers
-    ```
+  For Arch with Intel graphics card:
+  ```bash
+  sudo pacman -S vulkan-intel
+  ```
+
+  For Arch with NVIDIA graphic cards:
+  ```bash
+  sudo pacman -S nvidia lib32-nvidia-utils
+  ```
+
+  For Gentoo run:
+  ```bash
+  sudo emerge --ask --verbose dev-util/vulkan-tools dev-util/vulkan-headers
+  ```
 
 OK, we should now be ready to install Rust!
diff --git a/src/getting_started/updating.md b/src/getting_started/updating.md
@@ -0,0 +1,25 @@
+# Updating nannou
+
+You can update to a new version of nannou by editing your `Cargo.toml` file to
+use the new crate. For version 0.12 add the line
+
+```toml
+nannou = "0.12"
+```
+
+Then within the nannou directory run the following to update all dependencies:
+
+```bash
+cargo update
+```
+
+## Updating Rust.
+
+From time to time, a nannou update might require features from a newer version
+of rustc. For example, nannou 0.12 is known to require at least rustc 1.35.0. In
+these cases, you can update your rust toolchain to the latest version by running
+the following:
+
+```bash
+rustup update
+```
diff --git a/src/getting_started/upgrading.md b/src/getting_started/upgrading.md