Installation¶
The tools to install depend on how the models will be used. Steps 1 and 2 are required for every use, and they are sufficient to build and run the C++ models. Each later step is optional and independent of the others. A step can be skipped until the tool it installs is needed.
| Goal | Steps |
|---|---|
| Build and run the C++ models, and run the validation suite | 1, 2 |
| Also build and run the Sitar timing models | 1, 2, 3 |
| Write new SPARC programs in assembly or C, and run them | 1, 2, 4 |
| Examine a running model with gdb | 1, 2, 5 |
| Modify the models and rebuild them | 1, 2, and 3 for the Sitar models |
| Edit and rebuild this documentation | 1, 2, 6 |
These steps assume Linux on an x86_64 machine, and use the package names of Debian and Ubuntu. Other distributions provide the same tools through their own package managers.
1. Check the basic tools¶
The models need git, a C++ compiler with C++11 support (g++), and
Python 3. The following commands check that each of them is installed:
A missing tool can be installed with the following command:
The models also use libquadmath for quad-precision floating point.
Most Linux distributions include it with g++, so it rarely needs a
separate installation.
2. Get the code¶
The following commands clone the repository and enter its folder:
Each command block in these pages begins with a cd into the folder
where it runs. These folders are written relative to $SPARC_HOME,
which is the repository's folder. The following command sets this
variable, and must be run from inside the repository's folder:
A variable set in this way lasts only for the current terminal. The
following command adds it to ~/.bashrc, so that every new terminal
has it:
The C++ models need nothing more. This documentation is also part of
the repository, and can be read offline by opening
docs/generated_site/index.html in a browser.
3. (Optional) Install Sitar¶
This step is needed only for the Sitar timing models. These models describe the same core as the C++ models, with cycle-level timing added. They are built with the Sitar simulation framework.
Sitar's installation
instructions
describe how to install it and put the sitar command on the PATH.
After the installation, the following command should run from any
folder:
The models need a copy of Sitar from November 2026 or later, which
records the phase in which a run is stopped (see When the run
stops). An older copy is
brought up to date with git pull in its folder, followed by
./install.py to rebuild its translator.
4. (Optional) Install the SPARC cross-toolchain¶
This step is needed only to compile new programs. The simulator runs a
program from its memory image, which is a .hex file. The programs in
this repository come with their memory images, so they run without this
step.
A cross-toolchain is a compiler, assembler and linker that run on the
host machine but produce code for SPARC. The repository includes a
prebuilt toolchain. The following commands unpack it and add it to the
PATH:
The first command unpacks the toolchain into compiler/toolchain/. It
needs the unzip tool, which is installed with sudo apt install unzip.
The second command adds the toolchain to the PATH for the current
terminal only. The following commands check that the toolchain runs:
The following command adds the second command to ~/.bashrc, so that
every new terminal has the toolchain on its PATH:
If the toolchain doesn't run
The bundled toolchain is built for 32-bit x86 (i386). On a 64-bit Debian or Ubuntu machine, it needs the 32-bit C library, which the following commands install:
The toolchain cannot run on a machine that is not x86, such as an Apple Silicon Mac. On such a machine, a Linux x86_64 virtual machine can be used instead. Another option is to build a new toolchain with Buildroot, as described in Cross Compiler.
5. (Optional) Install gdb¶
This step is needed only to examine a running model with
gdb, the GNU debugger.
With gdb, a model can be stopped at a chosen instruction, and its
registers and memory can be examined. The models are ordinary programs
on the host machine, so the host's own gdb is sufficient. The
following commands install it and check its version:
6. (Optional) Install MkDocs¶
This step is needed only to edit this documentation and rebuild the
site. Reading the documentation needs nothing more than a browser, by
opening docs/generated_site/index.html.
The site is built with MkDocs. The following
commands install MkDocs and the packages it uses into a Python virtual
environment in docs/. They need to be run only once:
The pages are the Markdown files in docs/source/. After they are
edited, the following commands rebuild the site, with the virtual
environment active:
The site is written to docs/generated_site/. The command mkdocs
serve can be used instead of mkdocs build to preview edits in a
browser as they are made. It prints the address to open.
Next¶
The next page, Getting Started, builds the C++ model, runs a first program on it, and continues from there.