Skip to main content

Installation

This guide covers different ways to install CodeQL Wrapper.

Prerequisites​

  • Python 3.9 or higher
  • Poetry (for development installation)
  • Git (for repository analysis)

Install from PyPI​

The easiest way to install CodeQL Wrapper is from PyPI:

pip install codeql-wrapper

Verify Installation​

After installation, verify that CodeQL Wrapper is working:

codeql-wrapper --version

Install from Source​

For development or to get the latest features:

1. Clone the Repository​

git clone https://github.com/tweag/codeql-wrapper.git
cd codeql-wrapper

2. Install Poetry​

If you don't have Poetry installed:

curl -sSL https://install.python-poetry.org | python3 -

3. Install Dependencies​

poetry install

4. Run CodeQL Wrapper​

poetry run codeql-wrapper --help

Development Setup​

For contributing to the project:

1. Install Development Dependencies​

poetry install --with dev

2. Run Tests​

poetry run pytest
# Run tests with coverage
poetry run pytest --cov=src/codeql_wrapper --cov-report=term-missing

3. Run Quality Checks​

# Format code
poetry run black src/ tests/

# Type checking
poetry run mypy src/

# Linting
poetry run flake8 src/

# All checks
poetry run pytest && poetry run black src/ && poetry run mypy src/ && poetry run flake8 src/

4. Building and Publishing​

# Build the package
poetry build

# Publish to PyPI (requires authentication)
poetry config pypi-token.pypi <your-token>
poetry publish

# Or publish to test PyPI first
poetry config repositories.testpypi https://test.pypi.org/legacy/
poetry publish -r testpypi

# Or run the release workflow on Github

Docker Installation​

Note: Docker installation is not supported on ARM-based Macs (Apple Silicon) since CodeQL CLI does not work properly through Docker on macOS ARM.

CodeQL Wrapper can also be run in a Docker container:

FROM python:3.11-slim

WORKDIR /app

COPY pyproject.toml poetry.lock ./
RUN pip install poetry && poetry install --no-dev

COPY . .

ENTRYPOINT ["poetry", "run", "codeql-wrapper"]

Build and run:

docker build -t codeql-wrapper .
docker run --rm -v /path/to/repo:/workspace codeql-wrapper analyze /workspace

Troubleshooting​

Common Issues​

Python Version Error​

Make sure you have Python 3.9 or higher:

python --version

Poetry Not Found​

Make sure Poetry is in your PATH after installation:

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

Permission Errors​

On some systems, you might need to use pip3 instead of pip:

pip3 install codeql-wrapper

Getting Help​

If you encounter issues:

  1. Check the Issues page
  2. Create a new issue with details about your problem
  3. Include your Python version, operating system, and error messages