Skip to content

guide-install.md

Latest commit

 

History

History
298 lines (211 loc) · 9.23 KB

guide-install.md

File metadata and controls

298 lines (211 loc) · 9.23 KB

Installation Guide

Table of Contents

Pepc Packages

Some Linux distributions provide pepc as an installable package. However, these packages are out of date, do not use them.

Running From Source

You can run pepc directly from the source code without installation. Clone the repository, change to the cloned directory, and run pepc from there.

git clone https://github.com/intel/pepc.git
cd pepc
./pepc --help

This method is not recommended for regular use. For regular use, a proper installation is recommended: it configures shell tab completions and man pages, so commands like man pepc-cstates work out of the box.

Installation Script

The tools/install-pepc script is the simplest way to install pepc. It takes care of everything: installing OS dependencies, creating the Python virtual environment, configuring shell tab completions, man pages, and adding a sudo alias if needed.

Clone the repository to get the installation script:

git clone https://github.com/intel/pepc.git
cd pepc

Install the latest release from GitHub

Run tools/install-pepc without arguments. It fetches and installs the latest pepc release directly from GitHub. The local clone is only used to run the script.

sudo -v && ./tools/install-pepc

Install from a local clone

Use --src-path to install from the local clone instead.

sudo -v && ./tools/install-pepc --src-path .

Note: the script runs most steps as the current user, but it requires sudo for installing OS dependencies. The sudo -v pre-authorizes sudo credentials so the script can install dependencies without prompting for a password.

What the script does

The script performs the steps described below in the Manual Installation section. Here is a high-level overview:

  • Install OS dependencies using the system package manager (dnf or apt).
  • Create a Python virtual environment in ~/.pmtools and install pepc and its Python dependencies there.
  • Create ~/.pmtools/.pepc-rc.sh with all the necessary pepc configuration and add a line to ~/.bashrc to source it. The configuration includes the following:
    • Add ~/.pmtools/bin to PATH.
    • Configure tab completions.
    • Configure manual pages.
    • Create a sudo alias for pepc.

tools/install-pepc has additional options to tune the installation (e.g., the installation path), install pepc on a remote host over SSH, and control sudo alias creation and style. See guide-main.md for a discussion of sudo usage with pepc. Run ./tools/install-pepc --help to see all available options.

Standalone Executable

The tools/make-standalone script creates a standalone pepc zipapp: a single self-contained executable file that bundles pepc and all its Python dependencies. No installation, virtual environment, or PATH changes are required to run it.

This is useful when you want to copy pepc to a machine without setting up a Python virtual environment, or when you want a portable snapshot of a specific pepc version.

Like when running from source, the standalone executable does not have tab completions or man pages configured. It is best suited for short-term or one-off use. For regular use, a proper installation is recommended.

Clone the repository and run tools/make-standalone to create the executable.

git clone https://github.com/intel/pepc.git
cd pepc
./tools/make-standalone

This produces a pepc-standalone file in the current directory. Copy it to the target machine and run it directly.

./pepc-standalone --help

tools/make-standalone accepts the same --src-path option as tools/install-pepc, so you can build a standalone from a local clone or a specific Git URL. Run ./tools/make-standalone --help for all options.

Manual Installation

The following sections describe how to install pepc manually, without using the tools/install-pepc script. This is useful if you want full control over the installation, use a custom environment, or prefer a different package manager.

Pepc Package Dependencies

pepc requires a few OS packages. Most are typically pre-installed, but verify they are present on your system.

Tools used by pepc at runtime:

  • cat, id, uname from the coreutils package.
  • dmesg from the util-linux package, to read kernel messages for improved error reporting.
  • modprobe from the kmod package, to load kernel modules such as msr.

Tools needed for installation:

  • pip3 and python3 -m venv: required for pip-based installation (see Installation Using pip). On Ubuntu/Debian, python3 -m venv requires the python3-venv package; the installer will install it automatically if missing.
  • uv: an alternative to pip3 + python3 -m venv (see Using uv). Install one or the other.
  • rsync: used to copy sources to a temporary directory during installation from a local path.

The commands below install the pip3-based tools. If you prefer uv, install it instead and skip python3-pip.

Fedora / RHEL / CentOS

sudo dnf install -y util-linux kmod python3-pip rsync

Ubuntu

sudo apt install -y util-linux kmod python3-pip python3-venv rsync

Installation Using pip

This method installs pepc into a Python virtual environment in your home directory. The installation does not require superuser privileges.

Install pepc and all its Python dependencies into a directory of your choice. The example below uses ~/.pmtools.

python3 -m venv ~/.pmtools
~/.pmtools/bin/pip3 install git+https://github.com/intel/pepc.git@release

Ensure that ~/.pmtools/bin is in your PATH. Add the following line to your ~/.bashrc to make it persistent.

export PATH="$PATH:$HOME/.pmtools/bin"

Using uv

uv is a modern Python project and package manager. Install it using your distribution's package manager. For example, on Fedora:

sudo dnf install uv

Install pepc by running:

uv tool install git+https://github.com/intel/pepc.git@release

uv installs tools to $HOME/.local/bin. Add the following line to your ~/.bashrc to ensure pepc is found.

export PATH="$PATH:$HOME/.local/bin"

Sudo Configuration

Many pepc operations require superuser privileges. When pepc is installed in a Python virtual environment, running it with sudo requires extra configuration: sudo resets PATH and environment variables, which breaks virtual environment activation.

See the Superuser Privileges section in the main guide for a full background and discussion. Two ~/.bashrc snippets are provided below for quick reference.

Option 1: refresh

The alias pre-authorizes sudo credentials before invoking pepc. Requires passwordless sudo or prompts once per session.

alias pepc='sudo -v && pepc'

Option 2: wrap

The alias passes the virtual environment variables to sudo explicitly.

VENV="$HOME/.pmtools"
VENV_BIN="$VENV/bin"
alias pepc="sudo PATH=$PATH VIRTUAL_ENV=$VENV $VENV_BIN/pepc"

Tab completions

pepc supports tab completions. Add one of the following lines to ~/.bashrc, depending on how pepc was installed.

# For pip installation (adjust path if you used a different location):
eval "$($HOME/.pmtools/bin/register-python-argcomplete pepc)"

# For uv installation:
eval "$($HOME/.local/bin/register-python-argcomplete pepc)"

Man pages

pepc provides man pages for each subcommand (e.g., man pepc-cstates). When installed via pip or uv, the man pages land in Python's site-packages directory, which man does not search by default. Add the following line to ~/.bashrc to make them available.

export MANPATH="$MANPATH:$(pepc --print-man-path)"

Verify with:

man pepc-cstates

Example of .bashrc

The example below is for a pip-based installation into ~/.pmtools, using the refresh sudo approach. Adjust paths and the sudo alias as needed for your setup.

# === pepc settings ===
VENV="$HOME/.pmtools"
VENV_BIN="$VENV/bin"

# Ensure the virtual environment's bin directory is in the PATH.
export PATH="$PATH:$VENV_BIN"

# Sudo alias: pre-authorizes sudo credentials before invoking pepc.
alias pepc='sudo -v && pepc'

# Enable tab completion for pepc.
eval "$($VENV_BIN/register-python-argcomplete pepc)"

# Enable man pages.
export MANPATH="$MANPATH:$($VENV_BIN/pepc --print-man-path)"
# === end of pepc settings ===