133 lines
5.5 KiB
Markdown
133 lines
5.5 KiB
Markdown
# Bootstrapping the development environment
|
|
|
|
This project includes convenience scripts to create a Python virtual environment, install the package, and (optionally) create OS shortcuts.
|
|
|
|
Files:
|
|
- `scripts/bootstrap.ps1` — PowerShell script for Windows (creates venv, installs, optional Desktop/Start Menu shortcuts)
|
|
- `scripts/bootstrap.sh` — POSIX shell script (Linux/macOS) (creates venv, installs, optional desktop launcher)
|
|
|
|
Quick examples
|
|
|
|
Windows (PowerShell):
|
|
|
|
```powershell
|
|
# Create a .venv, install in editable mode and add a Desktop shortcut
|
|
powershell -ExecutionPolicy Bypass -File .\scripts\bootstrap.ps1 -Editable -CreateDesktopShortcut
|
|
|
|
# Use a specific python.exe and force overwrite
|
|
powershell -ExecutionPolicy Bypass -File .\scripts\bootstrap.ps1 -Python "C:\\Python39\\python.exe" -Force
|
|
```
|
|
|
|
Linux/macOS (bash):
|
|
|
|
```bash
|
|
# Create a .venv and install the project in editable mode
|
|
./scripts/bootstrap.sh --editable
|
|
|
|
# Create a desktop entry (GNU/Linux)
|
|
./scripts/bootstrap.sh --editable --desktop
|
|
```
|
|
|
|
Notes
|
|
|
|
- On Windows you may need to run PowerShell with an appropriate ExecutionPolicy (example shows using `-ExecutionPolicy Bypass`).
|
|
- The scripts default to a venv directory named `.venv` in the repository root. Use `-VenvPath` (PowerShell) or `--venv` (bash) to choose a different directory.
|
|
- The scripts will also install Playwright browser binaries by default (Chromium only) after installing Python dependencies. Use `--no-playwright` (bash) or `-NoPlaywright` (PowerShell) to opt out, or `--playwright-browsers <list>` / `-PlaywrightBrowsers <list>` to request specific engines (comma-separated, or use `all` to install all engines).
|
|
- The scripts are intended to make day-to-day developer setup easy; tweak flags for your desired install mode (editable vs normal) and shortcut preferences.
|
|
|
|
## Deno — installed by bootstrap
|
|
|
|
The bootstrap scripts will automatically install Deno if it is not already present on the system. They use the official installers and attempt to add Deno's bin directory to the PATH for the current session. If the installer completes but `deno` is not available in your shell, restart your shell or add `$HOME/.deno/bin` (Windows: `%USERPROFILE%\\.deno\\bin`) to your PATH.
|
|
|
|
Opinionated behavior
|
|
|
|
Running `python ./scripts/setup.py` is intentionally opinionated: it will create a local virtual environment at `./.venv` (repo root), install Python dependencies and the project into that venv, install Playwright browsers, install Deno, and write small launcher scripts in the project root:
|
|
|
|
- `mm` (POSIX shell)
|
|
- `mm.ps1` (PowerShell)
|
|
- `mm.bat` (Windows CMD)
|
|
|
|
These launchers prefer the local `./.venv` Python and console scripts so you can run the project with `./mm` or `mm.ps1` directly from the repo root.
|
|
|
|
Additionally, the setup helpers install a global `mm` launcher into your user bin so you can run `mm` from any shell session:
|
|
|
|
- POSIX: `~/.local/bin/mm` (created if missing; the script attempts to add `~/.local/bin` to `PATH` by updating `~/.profile` / shell RCs if required)
|
|
- Windows: `%USERPROFILE%\bin\mm.cmd` and `%USERPROFILE%\bin\mm.ps1` (created if missing; the script attempts to add the folder to your **User** PATH)
|
|
|
|
The scripts back up any existing `mm` shims before replacing them and will print actionable messages when a shell restart is required.
|
|
|
|
Debugging the global `mm` launcher
|
|
|
|
- POSIX: set MM_DEBUG=1 and run `mm` to print runtime diagnostics (resolved REPO, VENV, and Python import checks):
|
|
|
|
```bash
|
|
MM_DEBUG=1 mm
|
|
```
|
|
|
|
- PowerShell: set and export `$env:MM_DEBUG='1'` then run `mm.ps1` or the installed `mm` shim:
|
|
|
|
```powershell
|
|
$env:MM_DEBUG = '1'
|
|
mm
|
|
```
|
|
|
|
- CMD: `set MM_DEBUG=1` then run `mm`.
|
|
|
|
These diagnostics help identify whether the global launcher is selecting the correct repository and virtual environment; please include the output when reporting launcher failures.
|
|
|
|
PowerShell (Windows):
|
|
```powershell
|
|
irm https://deno.land/install.ps1 | iex
|
|
```
|
|
|
|
Linux/macOS:
|
|
```bash
|
|
curl -fsSL https://deno.land/install.sh | sh
|
|
```
|
|
|
|
Pinning a Deno version
|
|
|
|
You can pin a Deno release by setting the `DENO_VERSION` environment variable before running the bootstrap script. Examples:
|
|
|
|
PowerShell (Windows):
|
|
```powershell
|
|
$env:DENO_VERSION = 'v1.34.3'; .\scripts\bootstrap.ps1
|
|
```
|
|
|
|
POSIX (Linux/macOS):
|
|
```bash
|
|
DENO_VERSION=v1.34.3 ./scripts/bootstrap.sh
|
|
```
|
|
|
|
If you'd like, I can also:
|
|
- Add a short README section in `readme.md` referencing this doc, or
|
|
- Add a small icon and polish Linux desktop entries with an icon path.
|
|
|
|
## Troubleshooting: urllib3 / urllib3-future conflicts ⚠️
|
|
|
|
On some environments a third-party package (for example `urllib3-future`) may
|
|
install a site-packages hook that interferes with the real `urllib3` package.
|
|
When this happens you might see errors like:
|
|
|
|
Error importing cmdlet 'get_tag': No module named 'urllib3.exceptions'
|
|
|
|
The bootstrap scripts now run a verification step after installing dependencies
|
|
and will stop if a broken `urllib3` is detected to avoid leaving you with a
|
|
partially broken venv.
|
|
|
|
Recommended fix (activate the venv first or use the venv python explicitly):
|
|
|
|
PowerShell / Windows (from repo root):
|
|
|
|
.venv\Scripts\python.exe -m pip uninstall urllib3-future -y
|
|
.venv\Scripts\python.exe -m pip install --upgrade --force-reinstall urllib3
|
|
.venv\Scripts\python.exe -m pip install niquests -U
|
|
|
|
POSIX (Linux/macOS):
|
|
|
|
.venv/bin/python -m pip uninstall urllib3-future -y
|
|
.venv/bin/python -m pip install --upgrade --force-reinstall urllib3
|
|
.venv/bin/python -m pip install niquests -U
|
|
|
|
If problems persist, re-run the bootstrap script after applying the fixes.
|