From 677a9d01ec73507f42eb7276807fe1ccd31701fd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mark=20H=C3=A4mmerling?= Date: Wed, 26 Nov 2025 22:46:21 +0100 Subject: [PATCH 01/18] Add GitHub action to test CLI app install on macOS --- .github/workflows/test-macos-kivar.yml | 53 ++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 .github/workflows/test-macos-kivar.yml diff --git a/.github/workflows/test-macos-kivar.yml b/.github/workflows/test-macos-kivar.yml new file mode 100644 index 0000000..7e6953e --- /dev/null +++ b/.github/workflows/test-macos-kivar.yml @@ -0,0 +1,53 @@ +name: Test KiVar on macOS + +on: + workflow_dispatch: + +jobs: + test: + runs-on: macos-latest + timeout-minutes: 360 + + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Install KiCad + run: | + brew update + brew install --cask kicad + + - name: Detect KiCad Python + id: kicad + run: | + app="/Applications/KiCad/KiCad.app" + py="$app/Contents/Frameworks/Python.framework/Versions/Current/bin/python3" + site="$app/Contents/Frameworks/python/site-packages" + echo "PY=$py" >> $GITHUB_OUTPUT + echo "SITE=$site" >> $GITHUB_OUTPUT + + - name: Upgrade pip + run: | + "${{ steps.kicad.outputs.PY }}" -m pip install --upgrade pip + + - name: Install KiVar + run: | + "${{ steps.kicad.outputs.PY }}" -m pip install kivar + + - name: Test pcbnew import + run: | + "${{ steps.kicad.outputs.PY }}" - <<'PY' +import sys +sys.path.insert(0, "${{ steps.kicad.outputs.SITE }}") +import pcbnew +print("pcbnew OK") +PY + + - name: Test KiVar + run: | + "${{ steps.kicad.outputs.PY }}" - <<'PY' +import sys +sys.path.insert(0, "${{ steps.kicad.outputs.SITE }}") +from kivar.__main__ import main +main(["--version"]) +PY From 1820fabe7ec1ece92bc3448a1989c5238bdfed7b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mark=20H=C3=A4mmerling?= Date: Wed, 26 Nov 2025 22:50:05 +0100 Subject: [PATCH 02/18] Change indentation for heredoc parts --- .github/workflows/test-macos-kivar.yml | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/.github/workflows/test-macos-kivar.yml b/.github/workflows/test-macos-kivar.yml index 7e6953e..35cb2ec 100644 --- a/.github/workflows/test-macos-kivar.yml +++ b/.github/workflows/test-macos-kivar.yml @@ -36,18 +36,18 @@ jobs: - name: Test pcbnew import run: | - "${{ steps.kicad.outputs.PY }}" - <<'PY' -import sys -sys.path.insert(0, "${{ steps.kicad.outputs.SITE }}") -import pcbnew -print("pcbnew OK") -PY + "${{ steps.kicad.outputs.PY }}" - << 'PY' + import sys + sys.path.insert(0, "${{ steps.kicad.outputs.SITE }}") + import pcbnew + print("pcbnew OK") + PY - name: Test KiVar run: | - "${{ steps.kicad.outputs.PY }}" - <<'PY' -import sys -sys.path.insert(0, "${{ steps.kicad.outputs.SITE }}") -from kivar.__main__ import main -main(["--version"]) -PY + "${{ steps.kicad.outputs.PY }}" - << 'PY' + import sys + sys.path.insert(0, "${{ steps.kicad.outputs.SITE }}") + from kivar.__main__ import main + main(["--version"]) + PY From 7f9322feb314809ed604cf9cdc98fbbc33145498 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mark=20H=C3=A4mmerling?= Date: Wed, 26 Nov 2025 23:05:15 +0100 Subject: [PATCH 03/18] Add push trigger --- .github/workflows/test-macos-kivar.yml | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/.github/workflows/test-macos-kivar.yml b/.github/workflows/test-macos-kivar.yml index 35cb2ec..2804213 100644 --- a/.github/workflows/test-macos-kivar.yml +++ b/.github/workflows/test-macos-kivar.yml @@ -2,6 +2,12 @@ name: Test KiVar on macOS on: workflow_dispatch: + push: + branches: + - doc-fix-cli-install-guide + pull_request: + branches: + - main jobs: test: From 73cd8a9cfa9bdf3b0c0c8a2e737d83d6624509c5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mark=20H=C3=A4mmerling?= Date: Wed, 26 Nov 2025 23:18:56 +0100 Subject: [PATCH 04/18] Action: Try again --- .github/workflows/test-macos-kivar.yml | 29 ++++++++++++++------------ 1 file changed, 16 insertions(+), 13 deletions(-) diff --git a/.github/workflows/test-macos-kivar.yml b/.github/workflows/test-macos-kivar.yml index 2804213..ac397e1 100644 --- a/.github/workflows/test-macos-kivar.yml +++ b/.github/workflows/test-macos-kivar.yml @@ -28,9 +28,7 @@ jobs: run: | app="/Applications/KiCad/KiCad.app" py="$app/Contents/Frameworks/Python.framework/Versions/Current/bin/python3" - site="$app/Contents/Frameworks/python/site-packages" echo "PY=$py" >> $GITHUB_OUTPUT - echo "SITE=$site" >> $GITHUB_OUTPUT - name: Upgrade pip run: | @@ -40,20 +38,25 @@ jobs: run: | "${{ steps.kicad.outputs.PY }}" -m pip install kivar - - name: Test pcbnew import + - name: Show pcbnew version run: | "${{ steps.kicad.outputs.PY }}" - << 'PY' - import sys - sys.path.insert(0, "${{ steps.kicad.outputs.SITE }}") import pcbnew - print("pcbnew OK") + version = None + if hasattr(pcbnew, 'GetBuildVersion'): + version = pcbnew.GetBuildVersion() + elif hasattr(pcbnew, '__version__'): + version = pcbnew.__version__ + else: + version = 'unknown-version' + print("pcbnew version:", version) PY - - name: Test KiVar + - name: Test KiVar via KiCad Python run: | - "${{ steps.kicad.outputs.PY }}" - << 'PY' - import sys - sys.path.insert(0, "${{ steps.kicad.outputs.SITE }}") - from kivar.__main__ import main - main(["--version"]) - PY + "${{ steps.kicad.outputs.PY }}" -m kivar --version + + - name: Test KiVar executable directly + run: | + KICAD_BIN_DIR=$(dirname "${{ steps.kicad.outputs.PY }}") + "${KICAD_BIN_DIR}/kivar" --version From 826781dff813974409572fc75ce0d72b9e5d51e8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mark=20H=C3=A4mmerling?= Date: Wed, 26 Nov 2025 23:25:05 +0100 Subject: [PATCH 05/18] Action: List KiCad dir content for debugging location of Python modules --- .github/workflows/test-macos-kivar.yml | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/.github/workflows/test-macos-kivar.yml b/.github/workflows/test-macos-kivar.yml index ac397e1..59355a0 100644 --- a/.github/workflows/test-macos-kivar.yml +++ b/.github/workflows/test-macos-kivar.yml @@ -52,9 +52,11 @@ jobs: print("pcbnew version:", version) PY - - name: Test KiVar via KiCad Python + - name: List KiCad app directory tree run: | - "${{ steps.kicad.outputs.PY }}" -m kivar --version + KICAD_APP="/Applications/KiCad/KiCad.app" + echo "Listing all files under $KICAD_APP" + ls -lR "$KICAD_APP" - name: Test KiVar executable directly run: | From e5ff524e7e7819da17a4cd1546e1b21d0c8cb2c1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mark=20H=C3=A4mmerling?= Date: Thu, 27 Nov 2025 00:00:41 +0100 Subject: [PATCH 06/18] Add test with demo project --- .github/workflows/test-macos-kivar.yml | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/.github/workflows/test-macos-kivar.yml b/.github/workflows/test-macos-kivar.yml index 59355a0..baaec08 100644 --- a/.github/workflows/test-macos-kivar.yml +++ b/.github/workflows/test-macos-kivar.yml @@ -52,13 +52,12 @@ jobs: print("pcbnew version:", version) PY - - name: List KiCad app directory tree + - name: Test KiVar executable run: | - KICAD_APP="/Applications/KiCad/KiCad.app" - echo "Listing all files under $KICAD_APP" - ls -lR "$KICAD_APP" + KICAD_BIN_DIR=$(dirname "${{ steps.kicad.outputs.PY }}") + "${KICAD_BIN_DIR}/kivar" --version - - name: Test KiVar executable directly + - name: Test KiVar with demo project run: | KICAD_BIN_DIR=$(dirname "${{ steps.kicad.outputs.PY }}") - "${KICAD_BIN_DIR}/kivar" --version + "${KICAD_BIN_DIR}/kivar" list demo/kivar-demo.kicad_pcb From 0085803dc20f0c0e942fe906224daa17b2ddd890 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mark=20H=C3=A4mmerling?= Date: Thu, 27 Nov 2025 00:15:35 +0100 Subject: [PATCH 07/18] Test alternate call syntax --- .github/workflows/test-macos-kivar.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.github/workflows/test-macos-kivar.yml b/.github/workflows/test-macos-kivar.yml index baaec08..8e5c65a 100644 --- a/.github/workflows/test-macos-kivar.yml +++ b/.github/workflows/test-macos-kivar.yml @@ -61,3 +61,7 @@ jobs: run: | KICAD_BIN_DIR=$(dirname "${{ steps.kicad.outputs.PY }}") "${KICAD_BIN_DIR}/kivar" list demo/kivar-demo.kicad_pcb + + - name: Test KiVar with demo project, alternative syntax + run: | + "$(dirname "${{ steps.kicad.outputs.PY }}")/kivar" list demo/kivar-demo.kicad_pcb From 450ddb2e0414ca2f473affc568faac24554180a5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mark=20H=C3=A4mmerling?= Date: Thu, 27 Nov 2025 14:51:02 +0100 Subject: [PATCH 08/18] Try installation with --user option, see where it gets installed --- .github/workflows/test-macos-kivar.yml | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/.github/workflows/test-macos-kivar.yml b/.github/workflows/test-macos-kivar.yml index 8e5c65a..78dc605 100644 --- a/.github/workflows/test-macos-kivar.yml +++ b/.github/workflows/test-macos-kivar.yml @@ -34,9 +34,15 @@ jobs: run: | "${{ steps.kicad.outputs.PY }}" -m pip install --upgrade pip - - name: Install KiVar + - name: Install KiVar with user option run: | - "${{ steps.kicad.outputs.PY }}" -m pip install kivar + "${{ steps.kicad.outputs.PY }}" -m pip install --user kivar + + - name: List KiCad app directory tree + run: | + KICAD_APP="/Applications/KiCad/KiCad.app" + echo "Listing all files under $KICAD_APP" + ls -lR "$KICAD_APP" - name: Show pcbnew version run: | From 157dd5d858649ea2456908207e6c7cfd6ee408d4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mark=20H=C3=A4mmerling?= Date: Thu, 27 Nov 2025 17:03:53 +0100 Subject: [PATCH 09/18] Try again for user installation, add debugging --- .github/workflows/test-macos-kivar.yml | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/.github/workflows/test-macos-kivar.yml b/.github/workflows/test-macos-kivar.yml index 78dc605..61fca26 100644 --- a/.github/workflows/test-macos-kivar.yml +++ b/.github/workflows/test-macos-kivar.yml @@ -30,6 +30,10 @@ jobs: py="$app/Contents/Frameworks/Python.framework/Versions/Current/bin/python3" echo "PY=$py" >> $GITHUB_OUTPUT + - name: Detect KiCad Python version + run: | + "${{ steps.kicad.outputs.PY }}" --version + - name: Upgrade pip run: | "${{ steps.kicad.outputs.PY }}" -m pip install --upgrade pip @@ -44,6 +48,12 @@ jobs: echo "Listing all files under $KICAD_APP" ls -lR "$KICAD_APP" + - name: List Python user modules tree + run: | + DIRNAME="/Users/runner/Library/Python/3.9/bin" + echo "Listing all files under $DIRNAME" + ls -lR "$DIRNAME" + - name: Show pcbnew version run: | "${{ steps.kicad.outputs.PY }}" - << 'PY' @@ -60,14 +70,12 @@ jobs: - name: Test KiVar executable run: | - KICAD_BIN_DIR=$(dirname "${{ steps.kicad.outputs.PY }}") - "${KICAD_BIN_DIR}/kivar" --version + "/Users/runner/Library/Python/3.9/bin/kivar" --version - name: Test KiVar with demo project run: | - KICAD_BIN_DIR=$(dirname "${{ steps.kicad.outputs.PY }}") - "${KICAD_BIN_DIR}/kivar" list demo/kivar-demo.kicad_pcb + "/Users/runner/Library/Python/3.9/bin/kivar" list -s demo/kivar-demo.kicad_pcb - - name: Test KiVar with demo project, alternative syntax + - name: Test KiVar with demo project, using tilde path run: | - "$(dirname "${{ steps.kicad.outputs.PY }}")/kivar" list demo/kivar-demo.kicad_pcb + "~/Library/Python/3.9/bin/kivar" list -s demo/kivar-demo.kicad_pcb From 519e5d9136cad9a0dd27bb4da64c068117c2af9e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mark=20H=C3=A4mmerling?= Date: Thu, 27 Nov 2025 18:15:51 +0100 Subject: [PATCH 10/18] Further testing --- .github/workflows/test-macos-kivar.yml | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/.github/workflows/test-macos-kivar.yml b/.github/workflows/test-macos-kivar.yml index 61fca26..632ee71 100644 --- a/.github/workflows/test-macos-kivar.yml +++ b/.github/workflows/test-macos-kivar.yml @@ -54,6 +54,13 @@ jobs: echo "Listing all files under $DIRNAME" ls -lR "$DIRNAME" + - name: List Python base and site + run: | + echo "user-base" + "${{ steps.kicad.outputs.PY }}" -m site --user-base + echo "user-site" + "${{ steps.kicad.outputs.PY }}" -m site --user-site + - name: Show pcbnew version run: | "${{ steps.kicad.outputs.PY }}" - << 'PY' @@ -78,4 +85,4 @@ jobs: - name: Test KiVar with demo project, using tilde path run: | - "~/Library/Python/3.9/bin/kivar" list -s demo/kivar-demo.kicad_pcb + "$HOME/Library/Python/3.9/bin/kivar" list -s demo/kivar-demo.kicad_pcb From 485223446ab134d3517647a139a89563f5bd29c5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mark=20H=C3=A4mmerling?= Date: Fri, 28 Nov 2025 08:11:00 +0100 Subject: [PATCH 11/18] Try symlinking into PATH location --- .github/workflows/test-macos-kivar.yml | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/.github/workflows/test-macos-kivar.yml b/.github/workflows/test-macos-kivar.yml index 632ee71..00f0728 100644 --- a/.github/workflows/test-macos-kivar.yml +++ b/.github/workflows/test-macos-kivar.yml @@ -61,6 +61,10 @@ jobs: echo "user-site" "${{ steps.kicad.outputs.PY }}" -m site --user-site + - name: Show PATH + run: | + echo "Current PATH: $PATH" + - name: Show pcbnew version run: | "${{ steps.kicad.outputs.PY }}" - << 'PY' @@ -83,6 +87,14 @@ jobs: run: | "/Users/runner/Library/Python/3.9/bin/kivar" list -s demo/kivar-demo.kicad_pcb - - name: Test KiVar with demo project, using tilde path + - name: Test KiVar with demo project, using home path run: | "$HOME/Library/Python/3.9/bin/kivar" list -s demo/kivar-demo.kicad_pcb + + - name: Create a symlink to KiVar inside home + run: | + ln -s "$HOME/Library/Python/3.9/bin/kivar" "$HOME/.local/bin/kivar" + + - name: Run KiVar using symlink + run: | + kivar list -s demo/kivar-demo.kicad_pcb From 086832a7bdf3f3e1278cb9c3f0d0d164d5a36b9c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mark=20H=C3=A4mmerling?= Date: Fri, 28 Nov 2025 08:16:01 +0100 Subject: [PATCH 12/18] Add bin dir --- .github/workflows/test-macos-kivar.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.github/workflows/test-macos-kivar.yml b/.github/workflows/test-macos-kivar.yml index 00f0728..1648ce9 100644 --- a/.github/workflows/test-macos-kivar.yml +++ b/.github/workflows/test-macos-kivar.yml @@ -91,6 +91,10 @@ jobs: run: | "$HOME/Library/Python/3.9/bin/kivar" list -s demo/kivar-demo.kicad_pcb + - name: Create local bin dir, if not yet there + run: | + mkdir -p "$HOME/.local/bin" + - name: Create a symlink to KiVar inside home run: | ln -s "$HOME/Library/Python/3.9/bin/kivar" "$HOME/.local/bin/kivar" From 8fb3424f114a007be3b845ffb52aeb2e51b247c7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mark=20H=C3=A4mmerling?= Date: Fri, 28 Nov 2025 21:10:10 +0100 Subject: [PATCH 13/18] Improve and update CLI app installation instructions, per OS --- README.md | 81 +++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 67 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 3ca9244..2b478c8 100755 --- a/README.md +++ b/README.md @@ -130,7 +130,7 @@ KiVar currently (still) uses the SWIG-based Python bindings of pcbnew (KiCad PCB ### KiVar Plugin -The recommended plugin installation method is to use KiCad's integrated **Plugin and Content Manager**. KiVar is included in the **official PCM repository**, allowing a smooth and safe installation and update experience. For manual installation users can also choose to download the plugin archive package. +The recommended plugin installation method is to use KiCad's integrated **Plugin and Content Manager**. KiVar is included in the **official PCM repository**, allowing a smooth and safe installation and update experience. Required steps: @@ -141,34 +141,87 @@ Required steps: ### KiVar Command Line Application -> [!IMPORTANT] -> The KiVar CLI application requires access to the KiCad **pcbnew** Python module. -> On _Linux_ systems, KiCad provides this module system-wide, so all Python applications with access to system packages can use it (see installation note below). -> On _Windows_ and _macOS_, KiCad provides its own Python distribution. In the following installation instructions, users must therefore replace `python` by the appropriate KiCad Python executable, for example `C:\Program Files\KiCad\9.0\bin\python.exe` on Windows. +To install the latest KiVar CLI app directly from the official **KiVar PyPI repository**, follow the instructions below depending on your operating system. + +#### Installation on Linux + +For conveniently installing the KiVar CLI app inside a dedicated Virtual Environment, it is recommended to use `pipx`. Install it, if required, depending on your type of Linux distribution. With `pipx` in place, open a shell and run: + +``` +pipx install --system-site-packages kivar +``` + +This will install the KiVar CLI app in a location available in your search path. The name of the executable is `kivar`. + +To check that the installation was successful and that the correct `pcbnew` module version is used, run: + +``` +kivar --version +``` + +#### Installation on Windows + +On _Windows_ systems, KiCad ships with a Python distribution included. It is important to **use the KiCad-provided Python interpreter** for installing the KiVar CLI app. + +To install the `kivar` executable, open a `cmd.exe` shell and run: + +``` +"%ProgramFiles%\KiCad\9.0\bin\python.exe" -m pip install --user kivar +``` + +> [!NOTE] +> The above command assumes that KiCad version 9.0 is used. Please adapt the version part (`9.0`) of the command, if required. + +If you don't happen to have the app installation directory already listed in your `PATH` variable, then `pip` will print a warning including the actual installation directory: + +``` +WARNING: The script kivar.exe is installed in '...' which is not on PATH. +``` -#### Installation From PyPI Repository +This message includes the location of the directory in which the `kivar` executable is installed. -To install (or upgrade to) the latest KiVar CLI app directly from the official KiVar PyPI repository, open a shell (see note above) and run: +You will need to call `kivar` from this exact location. If desired, you can add the installation directory to your `PATH` variable (as suggested by `pip`), or use any other preferred method of making the executable callable from any working directory. + +To check that the installation was successful and that the correct `pcbnew` module version is used, run: ``` -python -m pip install --upgrade kivar +"%USERPROFILE%\Documents\KiCad\9.0\3rdparty\Python311\Scripts\kivar" --version ``` > [!NOTE] -> On newer _Linux_ Python installations, users might consider adding the `--break-system-packages` option for the app to be able to access KiCad's system-wide installed `pcbnew` module. +> The path used in the above command may differ on your system. If in doubt, use the directory printed in the `pip` installation warning. If no such warning appeared, you might be able to simply use `kivar --version` (without path specifier). + +#### Installation on macOS + +On _macOS_ systems, KiCad ships with a Python distribution included. It is important to **use the KiCad-provided Python interpreter** for installing the KiVar CLI app. + +To install the `kivar` executable, open a shell and run: -#### Installation Using a Release Archive +``` +"/Applications/KiCad/KiCad.app/Contents/Frameworks/Python.framework/Versions/Current/bin/python3" -m pip install --user kivar +``` + +If you don't happen to have the app installation directory already listed in your `PATH` variable, then `pip` will print a warning including the actual installation directory: -The KiVar CLI app can also be installed using a downloaded or locally created Python Package. +``` +WARNING: The script kivar is installed in '...' which is not on PATH. +``` -Use the following command (replace `${VERSION}` by the actual package version): +To be able to call `kivar` from _any_ working directory without using the executable's full path, run the following commands to create a symlink in your `~/.local/bin` directory (which should be part of `PATH`). The actual Python version part (`3.9` here) may vary, depending on the KiCad-included Python version. ``` -python -m pip install kivar-${VERSION}.tar.gz +mkdir -p "$HOME/.local/bin" +ln -s "$HOME/Library/Python/3.9/bin/kivar" "$HOME/.local/bin/kivar" ``` > [!NOTE] -> Same note about the `--break-system-packages` option applies (see above). +> The path used in the above command may differ on your system. If in doubt, use the directory printed in the `pip` installation warning. + +To check that the installation was successful and that the correct `pcbnew` module version is used, run: + +``` +kivar --version +``` ## Usage From e8a5c5bc95ca884d1bab60cbf0a2af5031707995 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mark=20H=C3=A4mmerling?= Date: Sun, 30 Nov 2025 23:15:35 +0100 Subject: [PATCH 14/18] Small doc changes --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 2b478c8..864b8d5 100755 --- a/README.md +++ b/README.md @@ -161,7 +161,7 @@ kivar --version #### Installation on Windows -On _Windows_ systems, KiCad ships with a Python distribution included. It is important to **use the KiCad-provided Python interpreter** for installing the KiVar CLI app. +On Windows systems, KiCad ships with its own Python distribution included. It is important to **use the KiCad-provided Python interpreter** for installing the KiVar CLI app. To install the `kivar` executable, open a `cmd.exe` shell and run: @@ -193,7 +193,7 @@ To check that the installation was successful and that the correct `pcbnew` modu #### Installation on macOS -On _macOS_ systems, KiCad ships with a Python distribution included. It is important to **use the KiCad-provided Python interpreter** for installing the KiVar CLI app. +On macOS systems, KiCad ships with its own Python distribution included. It is important to **use the KiCad-provided Python interpreter** for installing the KiVar CLI app. To install the `kivar` executable, open a shell and run: From 47c5bd14908b14aeee80c30c9c74c85290300ebe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mark=20H=C3=A4mmerling?= Date: Sun, 30 Nov 2025 23:18:08 +0100 Subject: [PATCH 15/18] Add .exe suffix for Windows --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 864b8d5..3b97d10 100755 --- a/README.md +++ b/README.md @@ -163,7 +163,7 @@ kivar --version On Windows systems, KiCad ships with its own Python distribution included. It is important to **use the KiCad-provided Python interpreter** for installing the KiVar CLI app. -To install the `kivar` executable, open a `cmd.exe` shell and run: +To install the `kivar.exe` executable, open a `cmd.exe` shell and run: ``` "%ProgramFiles%\KiCad\9.0\bin\python.exe" -m pip install --user kivar @@ -178,9 +178,9 @@ If you don't happen to have the app installation directory already listed in you WARNING: The script kivar.exe is installed in '...' which is not on PATH. ``` -This message includes the location of the directory in which the `kivar` executable is installed. +This message includes the location of the directory in which the `kivar.exe` executable is installed. -You will need to call `kivar` from this exact location. If desired, you can add the installation directory to your `PATH` variable (as suggested by `pip`), or use any other preferred method of making the executable callable from any working directory. +You will need to run `kivar` from this exact location. If desired, you can add the installation directory to your `PATH` variable (as suggested by `pip`), or use any other preferred method of making the executable callable from any working directory. To check that the installation was successful and that the correct `pcbnew` module version is used, run: From eeb2bab4ae40b35c95d79c757f7952467adf7f6d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mark=20H=C3=A4mmerling?= Date: Sun, 30 Nov 2025 23:42:11 +0100 Subject: [PATCH 16/18] Small refinements in the doc, emphasize tips for starters --- README.md | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 3b97d10..012f679 100755 --- a/README.md +++ b/README.md @@ -225,6 +225,9 @@ kivar --version ## Usage +> [!TIP] +> This manual may seem very formal and complicated, especially to new users. To get a first impression how KiVar works, it is highly recommended to watch the live presentation ["**Managing PCB Assembly Variants with KiVar**"](https://youtu.be/SpXH380KWUA) and have a look at some **[usage examples](#usage-examples)** as well as the **[demo project](demo/)** (from which the some examples are taken). + > [!IMPORTANT] > This manual refers to the **0.5.x** series of KiVar. If you are still using an older version, please consider [updating](#installation) KiVar and [migrating](#migrate) your variation rules. @@ -241,14 +244,7 @@ The following sections describe the process of configuring your schematic or boa While it is recommended to define variation rules in the schematic (i.e. in symbol fields) and propagate them to the board, it is also possible to define those rules directly in the board (i.e. in footprint fields) and propagate them back to the schematic. Either way, in order for KiVar to utilize the variation rules, they must be present in the footprint fields, as KiVar uses the _pcbnew_ API wrapper and can therefore only operate on the board (not schematic) data, which must then be [propagated back to the schematic](#updating-the-schematic). > [!TIP] -> Before diving into the more or less formal specification of KiVar variation rules, you might want to have a look at some [usage examples](#usage-examples) or the [demo project](demo/) (from which the examples are taken) for a start. These will give you a first impression of how KiVar rules work. - -> [!TIP] -> If you are already experienced with writing variation rules for older KiVar versions (especially 0.1.x), it is highly recommended to read the [KiVar Migration Guide](#migrate), which covers the most important changes introduced with newer KiVar releases. - -> [!TIP] -> The keywords used in component fields for identifying variation rules and aspect identifiers (`Var` and `Aspect` by default) can be customized. -> See [Overriding KiVar Record Keywords](#overriding-kivar-record-keywords) for details on how to use project text variables to change these keywords. +> If you are already experienced with writing variation rules for **older KiVar versions**, it is highly recommended to read the **[KiVar Migration Guide](#migrate)**, which covers the most important changes introduced with newer KiVar releases. #### Definition of Terms @@ -1493,6 +1489,6 @@ The author of KiVar would like to thank the following people in particular: **Honza Hladík** for his motivating very first feedback, feature inspiration and issue reports. -**Seth Hillbrand** for responding to my first release announcement by inviting me to give a talk at KiCon Europe 2024. +**Seth Hillbrand** for inviting me to give a talk at KiCon Europe 2024, in response to my first [release announcement](https://forum.kicad.info/t/introducing-kivar-pcb-assembly-variants-for-kicad/51467). -**Leonard Bargenda** for recurring pre-release testing sessions on macOS. +**Leonard Bargenda** for our v0.5.0 pre-release macOS testing sessions. From 074037372545d11e06a59e63312832af9ae703a3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mark=20H=C3=A4mmerling?= Date: Sun, 30 Nov 2025 23:44:17 +0100 Subject: [PATCH 17/18] Doc fixes --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 012f679..23fe48f 100755 --- a/README.md +++ b/README.md @@ -226,7 +226,7 @@ kivar --version ## Usage > [!TIP] -> This manual may seem very formal and complicated, especially to new users. To get a first impression how KiVar works, it is highly recommended to watch the live presentation ["**Managing PCB Assembly Variants with KiVar**"](https://youtu.be/SpXH380KWUA) and have a look at some **[usage examples](#usage-examples)** as well as the **[demo project](demo/)** (from which the some examples are taken). +> This manual may seem very formal and complicated, especially to new users. To get a first impression how KiVar works, it is highly recommended to watch the live presentation ["**Managing PCB Assembly Variants with KiVar**"](https://youtu.be/SpXH380KWUA) and have a look at the **[usage examples](#usage-examples)** as well as the **[demo project](demo/)** (from which the examples are taken). > [!IMPORTANT] > This manual refers to the **0.5.x** series of KiVar. If you are still using an older version, please consider [updating](#installation) KiVar and [migrating](#migrate) your variation rules. From a69cb986fb5614f2be1b467d4924d83790148250 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mark=20H=C3=A4mmerling?= Date: Sun, 30 Nov 2025 23:48:24 +0100 Subject: [PATCH 18/18] Remove macOS CLI app installation test workflow --- .github/workflows/test-macos-kivar.yml | 104 ------------------------- 1 file changed, 104 deletions(-) delete mode 100644 .github/workflows/test-macos-kivar.yml diff --git a/.github/workflows/test-macos-kivar.yml b/.github/workflows/test-macos-kivar.yml deleted file mode 100644 index 1648ce9..0000000 --- a/.github/workflows/test-macos-kivar.yml +++ /dev/null @@ -1,104 +0,0 @@ -name: Test KiVar on macOS - -on: - workflow_dispatch: - push: - branches: - - doc-fix-cli-install-guide - pull_request: - branches: - - main - -jobs: - test: - runs-on: macos-latest - timeout-minutes: 360 - - steps: - - name: Checkout - uses: actions/checkout@v4 - - - name: Install KiCad - run: | - brew update - brew install --cask kicad - - - name: Detect KiCad Python - id: kicad - run: | - app="/Applications/KiCad/KiCad.app" - py="$app/Contents/Frameworks/Python.framework/Versions/Current/bin/python3" - echo "PY=$py" >> $GITHUB_OUTPUT - - - name: Detect KiCad Python version - run: | - "${{ steps.kicad.outputs.PY }}" --version - - - name: Upgrade pip - run: | - "${{ steps.kicad.outputs.PY }}" -m pip install --upgrade pip - - - name: Install KiVar with user option - run: | - "${{ steps.kicad.outputs.PY }}" -m pip install --user kivar - - - name: List KiCad app directory tree - run: | - KICAD_APP="/Applications/KiCad/KiCad.app" - echo "Listing all files under $KICAD_APP" - ls -lR "$KICAD_APP" - - - name: List Python user modules tree - run: | - DIRNAME="/Users/runner/Library/Python/3.9/bin" - echo "Listing all files under $DIRNAME" - ls -lR "$DIRNAME" - - - name: List Python base and site - run: | - echo "user-base" - "${{ steps.kicad.outputs.PY }}" -m site --user-base - echo "user-site" - "${{ steps.kicad.outputs.PY }}" -m site --user-site - - - name: Show PATH - run: | - echo "Current PATH: $PATH" - - - name: Show pcbnew version - run: | - "${{ steps.kicad.outputs.PY }}" - << 'PY' - import pcbnew - version = None - if hasattr(pcbnew, 'GetBuildVersion'): - version = pcbnew.GetBuildVersion() - elif hasattr(pcbnew, '__version__'): - version = pcbnew.__version__ - else: - version = 'unknown-version' - print("pcbnew version:", version) - PY - - - name: Test KiVar executable - run: | - "/Users/runner/Library/Python/3.9/bin/kivar" --version - - - name: Test KiVar with demo project - run: | - "/Users/runner/Library/Python/3.9/bin/kivar" list -s demo/kivar-demo.kicad_pcb - - - name: Test KiVar with demo project, using home path - run: | - "$HOME/Library/Python/3.9/bin/kivar" list -s demo/kivar-demo.kicad_pcb - - - name: Create local bin dir, if not yet there - run: | - mkdir -p "$HOME/.local/bin" - - - name: Create a symlink to KiVar inside home - run: | - ln -s "$HOME/Library/Python/3.9/bin/kivar" "$HOME/.local/bin/kivar" - - - name: Run KiVar using symlink - run: | - kivar list -s demo/kivar-demo.kicad_pcb