Skip to content

Dev Environment Setup

Jump to bottom
Rahul Butani edited this page Jul 7, 2022 · 22 revisions

Note: We offer binary releases for the TUI and for the TM4C on their respective GitHub repos.

You only need to follow these steps if you wish to make changes to these repos.

Basic Setup

First, install a Rust toolchain:

This should be all you need to do to be able to build ut-utp/core and ut-utp/tui.

Recommended Extras:

Once you have a working Rust installation you can install these with cargo install ... (i.e. cargo install cargo-expand).

Using nix?

If you're using nix on macOS or Linux, simply run nix develop (or use nix-direnv). All our repos have nix flakes with shells with all the dependencies you need provided for you.

To set up nix (for use with VSCode):

  • install Nix
    • be sure to pick the "multi-user installation"
  • enable Flakes
    • add experimental-features = nix-command flakes to ~/.config/nix/nix.conf
      • i.e. run mkdir -p ~/.config/nix/; echo "experimental-features = nix-command flakes" >> ~/.config/nix/nix.conf
  • install direnv:
  • install nix-direnv
    • run nix-env -f '<nixpkgs>' -iA nix-direnv
    • and add source $HOME/.nix-profile/share/nix-direnv/direnvrc to $HOME/.direnvrc
      • i.e. run echo 'source $HOME/.nix-profile/share/nix-direnv/direnvrc' >> ~/.direnvrc
  • restart your terminal to load nix
    • depending on your setup you may need to run log out and log in again for all processes (like VSCode) to see things in your Nix profile
    • if you're not sure how applications pick up environment variables on your system, logging out and logging in again is the best option
  • install VSCode
  • install the VSCode direnv extension

Then, for any UTP repo, open the .code-workspace file (for example, [.vscode/tm4c.code-workspace](https://github.com/ut-utp/tui/blob/main/.vscode/workspace.code-workspace) for the utp/tm4c` repo) in VSCode and follow the prompts to install the recommended extensions.

direnv should prompt you to "allow" the .envrc in the repo and once you do it will prompt you to reload your extensions. Once you do so you should have a fully functional development environment for the repo.

TODO: core, assembler

IDE Setup

Rust has broad support amongst the popular text editors and IDEs.

If you don't already have a favorite, we recommend using VSCode with rust-analyzer. All our repos have VSCode workspaces that include lists of helpful extensions and other useful repo-specific tooling.

TODO: core, assembler

Embedded Development Setup

If you wish to debug embedded programs, you'll need to install some extra tools.

We strongly recommend using nix + VSCode if you are on macOS or Linux; it will handle managing all of these tools for you.

In general this requires some common packages as well as board specific tools (i.e. the TI ICDI drivers for the TM4C).

The common packages are:

  • openocd
    • Windows: available here
      • note: you may need to grab 7-zip to extract this file
      • add the bin directory to your PATH (this guide may be helpful)
    • macOS: outside of using nix, brew is probably the best way to install openocd on macOS
      • first install brew if you haven't already
      • then, this is the package; running brew install open-ocd will install it
    • Linux: installation will vary with your distribution
      • your distribution's package manager likely has openocd (i.e. apt install openocd)
      • if not, the OpenOCD website has some suggestions
  • gdb
    • Windows: unofficial binaries are available here
      • be sure to add the extracted gdb folder to your PATH
      • alternatively, the source is available here if you'd rather build it yourself
    • macOS: once again, brew is likely your best option
    • Linux: check your distro's package manager first (i.e. apt install gdb-multiarch)
      • Note: our repos are configured to expect gdb-multiarch to be present in $PATH, if your repo only offers a gdb binary with ARM support you'll need to use update-alternatives or a symlink to expose gdb-multiarch
  • (optional) the LLVM binutils:
    • VSCode's Cortex Debug extension uses this; feel free to skip installing this if you're not using that extension
    • Windows:
    • macOS: brew install llvm
    • Linux: varies per distro (i.e. apt install llvm-13-tools)
      • be sure to use update-alternatives or your distro's equivalent to get llvm-objdump and llvm-nm aliases (if, for example, you package exposes versioned binary names like llvm-13-nm).
      • see this page for alternate ways to get and install a release

Recommended, but not required:

For the TM4C

For the TM4C specifically, you'll also need:

udev rule

You may also want to configure a udev rule (Linux only). This will allow you to interact with the board (i.e. screen, the UTP TUI) without needing to run as root.

To install:

  • on NixOS:
    • add this: 
      services.udev.extraRules = ''
  # We can only alias, not rename, so: we change the permissions of `ttyACM0` too.  
  KERNEL=="ttyACM0", MODE:="0666"
  # TI Stellaris Launchpad
  SUBSYSTEM=="usb", ATTR{idVendor}=="1cbe", ATTR{idProduct}=="00fd", GROUP:="plugdev", MODE:="0666", SYMLINK+="tm4c"
'';
      to your configuration.nix
    • run sudo nixos-rebuild switch
  • on other Linux distros:
    • put the above (or a different udev rule like this one) in /etc/udev/rules.d
    • i.e. run something like: 
      echo 'KERNEL=="ttyACM0", MODE:="0666"' | sudo tee /etc/udev/rules.d/99-tiva-launchpad.rules
echo 'SUBSYSTEM=="usb", ATTR{idVendor}=="1cbe", ATTR{idProduct}=="00fd", GROUP:="plugdev", MODE:="0666", SYMLINK+="tm4c"' | sudo tee -a /etc/udev/rules.d/99-tiva-launchpad.rules

Finally:

  • run: 
    sudo udevadm control --reload
sudo udevadm trigger
    so that the new udev rule will take effect
  • with your board plugged in, run: 
    ls -l /dev/tm4c
    to verify that you now have permission to access your board

lm4flash

If you're just looking to flash binaries onto your TM4C you can use lm4flash instead of OpenOCD.

TODO: link to the nixpkg once it's up

For Windows:

For macOS:

For Linux:

Rust WASM Development Setup

Need: node, wasm-pack, ...

Recommend:

TODO

Developer Environment Setup:

Misc:

Clone this wiki locally