From 0c296d5070a882b073eb2cfcfd97d4cfc3ecf098 Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Sat, 3 Oct 2026 22:11:46 +0200 Subject: [PATCH] Document VSG fork installation updates --- README.md | 36 ++++++++++++++++++++++++++++++++---- 1 file changed, 32 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index aa1d612..6f96178 100644 --- a/README.md +++ b/README.md @@ -26,11 +26,14 @@ explicit formatting and fix actions can. See the ## 1. Install the VSG fork -The preferred installation uses `uv pip` and the prebuilt package: +The modified VSG packages are published in the +[MadGobblins Python package index](https://proxy.dandaedre.com/gitea/api/packages/MadGobblins/pypi/simple/vsg/). +The preferred installation uses `uv pip` and its prebuilt wheel: ```sh uv venv .venv uv pip install --python .venv/bin/python \ + --upgrade \ --index https://proxy.dandaedre.com/gitea/api/packages/MadGobblins/pypi/simple/ \ vsg ``` @@ -41,11 +44,20 @@ Without `uv`, use standard `pip`: python3 -m venv .venv . .venv/bin/activate python -m pip install \ + --upgrade \ --index-url https://proxy.dandaedre.com/gitea/api/packages/MadGobblins/pypi/simple/ \ --extra-index-url https://pypi.org/simple \ vsg ``` +This is a narrow integration fork, so upstream remains the owner of VSG release +numbers. Packages built between upstream tags instead use an automatic PEP 440 +post version such as `3.35.0.post186+git.b7dc18c1`; this lets `--upgrade` select +newer fork commits. If an installation still remains on an equal or newer +version—for example after rewritten development history—add `--reinstall` to +the `uv` command or `--force-reinstall` to the `pip` command. As a final +fallback, uninstall `vsg` and install it again manually. + ## 2. Install the bridge The preferred method uses @@ -130,9 +142,24 @@ Less common options are collected under [Advanced usage](#advanced-usage). ## Advanced usage -This section covers [configuration generation](#generate-a-project-configuration), -[multiple language servers](#multiple-language-servers), -[experimental fixes](#experimental-fixes), and [debug mode](#debug-mode). +This section covers [installing VSG from source](#install-vsg-from-source), +[configuration generation](#generate-a-project-configuration), [multiple +language servers](#multiple-language-servers), [experimental +fixes](#experimental-fixes), and [debug mode](#debug-mode). + +### Install VSG from source + +To install the current fork directly from Git instead of the package index: + +```sh +uv venv .venv +uv pip install --python .venv/bin/python --upgrade \ + "vsg @ git+https://proxy.dandaedre.com/gitea/MadGobblins/vhdl-style-guide.git@master" +``` + +This requires Git and builds VSG locally. Replace `master` with a commit hash +for a reproducible installation. Add `--reinstall` when reinstalling the same +commit after a local packaging or environment problem. ### Generate a project configuration @@ -221,6 +248,7 @@ process environment variables. See the [debug-mode reference](doc/debug-mode.md) ## More documentation - [Installation alternatives and PATH troubleshooting](doc/installation.md) +- [Install VSG from source](#install-vsg-from-source) - [Generate a project configuration](#generate-a-project-configuration) - [Use multiple language servers](#multiple-language-servers) - [Layered bridge configuration reference](doc/configuration.md)