Skip to content

NAME Getting Started Guide

Jump to bottom
Luke Wells edited this page Dec 8, 2023 · 8 revisions

This guide will explain how to install and run the NAME extension on your machine to start running MIPS code with NAME.

There are 2 major ways to use NAME

  • Using the NAME vscode extension
  • Running the NAME assembler and Emulator in a terminal

This guide will Focus on setting up NAME using the VSCode extension

How to set up the VSCode extension

Eventually, we plan on submitting the NAME extension to the VSCode extension store so that user's can easily install it with a 1-click install. As our project is still in development, it is currently necessary to build the extension from source. This guide will explain how to do that.

Prerequisites

  • VSCode
    • Follow the instructions here or download through your preferred package manager
  • Node-JS
    • Our recommended method for installing NodeJS is through a package manager.
    • Official instructions are provided here
    • If you prefer an installer, or use a Mac, you can follow the instructions here
  • Rust
    • Follow the instructions here
    • NOTE: You must restart VSCode and any active terminals in order for the installation to take effect.
    • Try to type "cargo" in a terminal, if you get a help page with a list of commands, Rust has been installed correctly
  • Optional: A GNU Mips Assembler
    • This is helpful for creation of ELF files during development.
    • It is not strictly necessary to run MIPS programs
    • NOTE: More info is needed here

After installing all of these prerequisites, restart VSCode and any active terminals

Cloning the Repository

  • There are many ways to clone a repository, if you have no experience with Git it is recommended for you to use Github Desktop
    • This section of the guide will focus on using GitHub Desktop, though command line git will also work if you are more comfortable with that.

Setting up the extension

1. Open up name-ext in VSCode

  • Navigate to where you have cloned NAME onto your system
  • Open up the name-ext directory into a new VSCode window
  • If you do not have a terminal open within VSCode
    • At the top of your VSCode window, click on the Terminal button in the navigation bar
    • image

2. Install the NPM packages

  • Open the terminal in your name-ext vscode window and type in npm install

3. Start the extension development window

  • Navigate to name-ext > src > extension.ts in your VSCode editor
    • It should look like this
      • image
    • In the terminal, type in 'npm run watch' to compile the extension and watch for changes
      • You should see this message appear in your terminal

        [watch] build finished, watching for changes...

      • If you don't get the above response, and instead get a bunch of errors, you are likely in the wrong directory
        • Refer to the first bullet point of step 3 above
    • Click into the extension.ts window and press f5
      • This will open the "Extension Development Host" window
      • The extension will be active within only this window

4. Open a mips file in the extension development window

  • If you are just testing the extension, there are sample mips files available under mips-as/.artifacts

5. IMPORTANT: Specify the path of the NAME directory on your machine

  • This is done in the name-ext settings in the extension development host window
  • This is the directory of the project you cloned from GitHub
  • It should contain, name-as, name-emu, name-ext, and name-fmt
  • image

6. Start the Emulator

  • Press ctrl + shift + p to open the command pallet
  • Type in, 'Start Emulator' and press enter to start the emulator
  • You should see something similar to the message below in your terminal when it is done

    Running `target/debug/name 63321 ....

  • Common errors
    • Your path is not set correctly, refer to step 5

7. Finally, debug your asm file!

  • In the extension development host window, click into your .asm file and press f5
  • The registers pane should appear on the left, and you now have the ability to step through your mips program and run it

How to use NAME through the command line

If you want to run the NAME assembler and emulator independently, follow this part of the guide

How to run the NAME assembler

  • Navigate to the name-as directory
  • Compile name-as using `cargo build --release'
  • Run with cargo run <configFileIn.toml> <assemblyFileIn.asm> <objectFileNameOut.o> -l
    • This program requires 3 inputs, shown in brackets <> above
      • An abbreviated list of these arguments is provided when you run cargo run with no arguments
      • In the place of <configFile.toml>, place the path to a config file for the assembler
        • A default config file exists at name-as/configs/default.toml
      • In the place of <assemblyFile.asm>, place the path of the MIPS assembly file you want to assemble
      • In the place of <objectFileNameOut.o>, place the path and name to the object file you with to output
    • The "-l" argument is optional and tells the assembler to produce a line-info file when run
      • Note that this line-info file is REQUIRED by name-emu, so if you are using the assembler with the intention of passing the assembled file to the name emulator, you will want to use this option

Clone this wiki locally