RASCSI/INSTALL.md

Installing PiSCSI

The recommended way to install PiSCSI is via the binary deb packages. Find the latest release on the GitHub releases page and download the piscsi_*.deb file for your Raspberry Pi architecture.

If you want the Web interface, download the piscsi-web_*.deb file as well. If your Raspberry Pi has an OLED screen, download the piscsi-oled_*.deb file, and if you have a PiSCSI Control Board, download the piscsi-ctrlboard_*.deb file.

Runtime dependencies

Use apt to install the packages and their dependencies, for example the mandatory runtime dependencies for the piscsi daemon:

sudo apt update
sudo apt install libprotobuf-dev libspdlog-dev libpcap-dev

The piscsi daemon requires the following packages to be installed on the system:

• libprotobuf-dev for the protobuf runtime library
• libspdlog-dev for the spdlog runtime library
• libpcap-dev for the pcap runtime library

Note that the -dev packages are not strictly required at runtime, but they are the easiest way to install the libraries on Debian-based systems, since they are named consistently regardless of the Raspberry Pi architecture. The -dev packages are also required to build PiSCSI from source.

In addition, these optional packages enables additional functionality:

• dhcp-helper for proxy ARP support
• parprouted for proxy ARP support
• rsyslog for logging

The piscsi-web package has the following optional runtime dependencies:

• genisoimage for creating ISO images
• unar for extracting compressed archives
• dosfstools for creating FAT filesystems
• hfdisk for creating HFS partition tables
• hfsutils for creating HFS filesystems
• groff for displaying man pages
• man2html for converting man pages to HTML
• disktype for identifying disk image types

The piscsi-oled and piscsi-ctrlboard packages have the following optional runtime dependency:

• i2c-tools for configuring and testing I2C devices

Installing the packages

Use dpkg to install the downloaded packages. For example, if you downloaded the piscsi_*.deb and piscsi-web_*.deb files to your home directory:

sudo dpkg -i ~/piscsi_*.deb ~/piscsi-web_*.deb

In most cases, dpkg will report missing dependencies. Use apt to install them.

Build from source

This guide builds the C++ PiSCSI daemon and command-line tools from a source checkout. Note that building the C++ code directly on Raspberry Pi hardware can be very slow. Cross-compiling on a more powerful host is recommended.

Building from source is most useful for development, testing, or trying an unreleased change. PiSCSI is developed and tested primarily on recent Raspberry Pi OS releases.

The C++ code and tests can be built on most Unix-like systems, but the GPIO hardware interface is only available on a Raspberry Pi with a PiSCSI hat.

Build prerequisites

On Raspberry Pi OS, install the PiSCSI C++ build dependencies with:

sudo apt update
sudo apt install --yes \
  build-essential ca-certificates git protobuf-compiler rsyslog \
  clang libgmock-dev libpcap-dev libprotobuf-dev libspdlog-dev

libgmock-dev supplies the unit-test dependency. You may omit it when you do not intend to build or run tests.

For the Meson build system, also install Meson and Ninja:

sudo apt install --yes meson ninja-build

Clone the repository:

git clone https://github.com/PiSCSI/piscsi.git
cd piscsi

The web interface and the optional OLED/control-board programs are built with Go. Start with the web interface README; the OLED and control-board directories each have their own README as well.

Build with Meson

Meson is configured from the repository root. A separate build directory keeps generated files out of the checkout.

meson setup build
meson compile -C build

The default target set builds piscsi, scsictl, scsimon, scsiloop, scsidump, and the unit tests. scsiloop requires Linux on Raspberry Pi GPIO hardware.

To select targets explicitly, pass a Meson array option:

meson setup build -Dtarget=piscsi,scsictl
meson compile -C build

Run unit tests when the Google Test/Mock packages are installed:

meson test -C build

Install the Meson-built binaries and installed data with:

sudo meson install -C build

By default this installs executable and manual-page files under /usr/local, along with the other data declared by the Meson project. Use --prefix to change the installation root. You may need to manually adjust the systemd unit files to match the prefix.

Build with Make

The legacy Makefile is run from cpp/. It compiles C++ sources there and writes binaries to cpp/bin/.

cd cpp
make -j"$(nproc)" all

For a development build with debug symbols and no optimization:

make -j"$(nproc)" DEBUG=1 all

Run the C++ unit tests:

make -j"$(nproc)" test

The Makefile accepts CROSS_COMPILE, for example CROSS_COMPILE=arm-linux-gnueabihf-, and DEFAULT_IMAGE_FOLDER to change the compiled default image directory.

Install the Make-built development files with:

sudo make install

After a Makefile installation, reload logging and enable/start the service as needed:

sudo systemctl restart rsyslog
sudo systemctl enable --now piscsi
sudo systemctl status piscsi

The daemon log is written to /var/log/piscsi.log when the supplied rsyslog configuration is active.

Cleaning and rebuilding

For a clean Makefile build:

cd cpp
make clean

For Meson, remove the build directory and configure it again:

rm -rf build
meson setup build

The two build systems can be used in parallel, but they do not share build artifacts.

For system setup and SCSI hardware guidance, see the PiSCSI Setup Instructions.