vsg-bridge-ls/doc/installation.md

2.9 KiB

Installation

vsg-bridge-ls starts vsg by name, so both executables must be available in the environment used by the editor. Formatting additionally requires the companion fork's --stdout and --no-failure options; upstream VSG alone is not sufficient for that workflow.

Preferred: prebuilt VSG package with uv

The prebuilt package avoids a local source checkout and build:

uv venv .venv
uv pip install --python .venv/bin/python \
  --index https://proxy.dandaedre.com/gitea/api/packages/MadGobblins/pypi/simple/ \
  vsg

Activate the environment before launching the editor:

. .venv/bin/activate

Install VSG from master with uv

uv venv .venv
uv pip install --python .venv/bin/python \
  "git+https://proxy.dandaedre.com/gitea/MadGobblins/vhdl-style-guide.git@master"

Install VSG with pip

Both package sources also work with standard pip. For the prebuilt package:

python3 -m venv .venv
. .venv/bin/activate
python -m pip install \
  --index-url https://proxy.dandaedre.com/gitea/api/packages/MadGobblins/pypi/simple/ \
  --extra-index-url https://pypi.org/simple \
  vsg

The extra PyPI index supplies dependencies that are not stored in Gitea. To install the current master branch instead:

python3 -m venv .venv
. .venv/bin/activate
python -m pip install \
  "git+https://proxy.dandaedre.com/gitea/MadGobblins/vhdl-style-guide.git@master"

Preferred: install the prebuilt bridge with cargo-binstall

Releases contain prebuilt archives for three supported targets. With cargo-binstall available, it selects the archive for the current system and installs the latest release candidate:

cargo binstall --git \
  https://proxy.dandaedre.com/gitea/MadGobblins/vsg-bridge-ls.git \
  vsg-bridge-ls

Alternative: build the bridge from source

Without cargo-binstall, install the released branch directly from Gitea:

cargo install --locked \
  --git https://proxy.dandaedre.com/gitea/MadGobblins/vsg-bridge-ls.git

For development, clone this repository and use cargo build. Cargo normally places installed binaries in ~/.cargo/bin; that directory must also be in the editor's PATH.

The bridge supports Rust 1.85.1 and newer. --locked uses the dependency versions tested by CI and is required to preserve that compatibility guarantee.

PATH and virtual environments

Activating .venv before launching the editor is the simplest setup because the child language server inherits the editor's PATH. If the editor is launched by a desktop session, configure that editor to include the absolute paths to .venv/bin and ~/.cargo/bin instead.

Check the same environment the editor will inherit:

command -v vsg
command -v vsg-bridge-ls

Python 3.8 is the fork's minimum supported version. The complete test suite and packaged stdin/stdout workflow are validated on Python 3.8.20.