Installation for contributors
While we recommend regular users to install Exegol using pipx
for simplicity and isolation (see First install), contributors and developers should install from sources. Here's why and how.
Requirements
Before starting, ensure you have all the requirements from the First install guide (git, python3, docker).
Why install from sources?
When contributing to Exegol, installing from sources provides several advantages:
- Direct code access: you can modify the code directly and test your changes immediately
- Branch switching: easily switch between release and development branches
- Auto-update feature: the wrapper knows how to self-update when installed from sources
- Development tools: access to development dependencies and testing frameworks
- Version control: direct integration with Git for contributing changes
Installation steps
1. Fork Exegol
- Go to github.com/ThePorgs/Exegol
- Click the "Fork" button in the top-right corner
- Select your GitHub account as the destination
- Wait for the fork to complete
This creates your own copy of the repository where you can make changes without affecting the original project.
2. Clone your fork
Clone your fork of the Exegol repository:
# Replace YOUR_USERNAME with your GitHub username
git clone "https://github.com/YOUR_USERNAME/Exegol" && cd Exegol
# Add the upstream repository to easily keep your fork in sync
git remote add upstream "https://github.com/ThePorgs/Exegol"
3. Virtual environment
For development, we recommend using a virtual environment to isolate dependencies:
# Create a virtual environment
python3 -m venv .venv
# Activate it
source .venv/bin/activate
Then, install both the runtime and development dependencies:
# Install runtime dependencies
pip3 install -r requirements.txt
Deactivate the virtual environment when done:
deactivate
4. Finalize setup
You can now run Exegol with the following command:
# On Linux
sudo /path/to/Exegol/venv/bin/python3 /path/to/Exegol/exegol.py
# On macOS, Windows
/path/to/Exegol/venv/bin/python3 /path/to/Exegol/exegol.py
To make this version of Exegol accessible system-wide, you can create an alias or symbolic link, and name it exegol-dev
so that it can coexist with the production/official version:
# Create a symbolic link, from the Exegol directory
sudo ln -s "$(pwd)/exegol.py" "/usr/local/bin/exegol-dev"
For security reasons on Linux, we recommend running Exegol with sudo
rather than adding your user to the docker group. You can create an alias for convenience:
# For bash
echo "alias exegol-dev='sudo -E $(which exegol-dev)'" >> ~/.bash_aliases
source ~/.bashrc
Once this is done, you can have both the pipx installation (for regular use) and the source installation (for development) at the same time. Here's how to manage them:
# Regular install
exegol version
# Source install
exegol-dev version
Development workflow
Branch management
Create a new branch for each feature or fix. This branch will be used for your local development and will be pushed to your fork when you stage, commit, and push your changes:
git checkout -b type/description
Branch naming conventions (preferred, not mandatory):
feat/
- new features (e.g.,feat/add-toolxyz
)fix/
- bug fixes (e.g.,fix/toolxyz-install
)docs/
- documentation updates (e.g.,docs/update-install-guide
)refactor/
- code refactoring (e.g.,refactor/install-scripts
)perf/
- performance improvements (e.g.,perf/clean-up-artefactxyz
)
Keeping your fork updated
To keep your development branch in sync with upstream changes:
# Fetch latest changes from upstream
git fetch upstream
# Make sure you're on your development branch
git checkout feat/your-feature-name
# Merge upstream dev branch into your development branch
git merge upstream/dev
# If there are conflicts, resolve them and then
git add .
git commit -m "Merge upstream dev"
Commit signing
We strongly recommend signing your commits when contributing to Exegol. While it's a strict requirement for internal contributors, we prefer signed commits from external contributors as well. See our Signing Commits guide for detailed instructions.
Submitting changes
Push your changes to your fork:
bashgit push origin feat/your-feature-name
Create a Pull Request from your fork's branch to the upstream repository's
dev
branchWait for review and address any feedback
Once approved, your changes will be merged into the development branch