docs: recommend installation via uv for most users

CONTRIBUTING.md

@@ -8,50 +8,84 @@ Join the [Halmos Telegram Group][chat] for any inquiries or further discussions.
 
 ## Development Setup
 
-If you want to submit a pull request, fork the repository:
+Clone or fork the repository:
 
 ```sh
+# if you want to submit a pull request, fork the repository:
 gh repo fork a16z/halmos
-```
-
-Or, if you just want to develop locally, clone it:
 
-```sh
+# Or, if you just want to develop locally, clone it:
 git clone [email protected]:a16z/halmos.git
+
+# navigate to the project directory
+cd halmos
 ```
 
-Create and activate a virtual environment:
+**Recommended**: set up the development environment using [uv](https://docs.astral.sh/uv/):
 
 ```sh
-python3.12 -m venv .venv && source .venv/bin/activate
+# install uv
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# this does a lot of things:
+# - install a suitable python version if one is not found
+# - create a virtual environment in `.venv`
+# - install the main dependencies
+# - install the development dependencies
+# - generates a `uv.lock` file
+uv sync --extra dev
+
+# install and run the pre-commit hooks
+uv run pre-commit install
+uv run pre-commit run --all-files
+
+# make changes to halmos, then run it with:
+uv run halmos
+
+# run the tests with:
+uv run pytest
+
+# add a dependency to the project:
+uv add <dependency>
+
+# remove a dependency from the project:
+uv remove <dependency>
+
+# update a dependency to the latest version:
+uv lock --upgrade-package <dependency>
+
+# to manually update the environment and activate it:
+uv sync
+source .venv/bin/activate
 ```
 
-Install the dependencies:
+Alternatively, you can manage the python version and the virtual environment manually using `pip` (not recommended for most users):
 
 ```sh
-# install halmos and its runtime dependencies
+# create and activate a virtual environment with a suitable python version
+python3.12 -m venv .venv && source .venv/bin/activate
+
+# install halmos and its runtime dependencies in editable mode
 python -m pip install -e .
 
 # install the dev dependencies
 python -m pip install -r requirements-dev.txt
-```
-
-Install and run the git hook scripts (this is optional but will make sure that your PR will follow the style convention):
 
-```sh
+# install and run the pre-commit hooks
 pre-commit install
 pre-commit run --all-files
 ```
 
+
 ## Coding Style
 
-We recommend enabling the [black] formatter in your editor, but you can run it manually if needed:
+We recommend enabling the [ruff] formatter in your editor, but you can run it manually if needed:
 
 ```sh
-python -m black src/
+python -m ruff check src/
 ```
 
-[black]: <https://black.readthedocs.io/en/stable/>
+[ruff]: <https://docs.astral.sh/ruff/>
 
 ## GitHub Codespace
 

README.md

@@ -23,39 +23,58 @@ Join the [Halmos Telegram Group][chat] for any inquiries or further discussions.
 
 ## Installation
 
+### ⭐ Using `uv` (recommended for most users)
+
 ```sh
-pip install halmos
+# install uv if you don't have it already
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# install the latest version of halmos for the current user and add it to PATH
+uv tool install halmos
+
+# or, install the development version from the repository
+# uv tool install git+https://github.com/a16z/halmos
+
+# after installing, you can update halmos to the latest version with:
+uv tool upgrade halmos
 ```
 
-Or, if you want to try out the nightly build version:
+### Using `docker`
+
+You can download a pre-built Docker image that contains python, halmos, its dependencies, foundry, solvers, etc.:
 
 ```sh
-pip install git+https://github.com/a16z/halmos
+docker pull ghcr.io/a16z/halmos:latest
 ```
 
-Alternatively, you can download the Docker image that contains halmos and its dependencies:
+### Using `pip` (for advanced users)
+
+Note: this is not recommended because of the extra work required to manage the python version and the virtual environment. But if you know what you are doing, and need the extra control, you can do it like this:
 
 ```sh
-docker pull .:/workspace ghcr.io/a16z/halmos:0.1.14
-```
+# make sure you have a suitable python version installed, e.g.:
+python3.12 --version
 
-And finally, if you want to install halmos into an isolated virtual environment (so you don't have to deal with dependency issues), you can install it with [uv](https://docs.astral.sh/uv/getting-started/installation/):
+# create and activate a virtual environment with an explicit python version
+python3.12 -m venv .venv && source .venv/bin/activate
 
-```
-curl -LsSf https://astral.sh/uv/install.sh | sh # install UV (see docs for other install methods)
-uv tool install halmos
+# install the latest version of halmos
+pip install halmos
+
+# or, install the development version from the repository
+pip install git+https://github.com/a16z/halmos
 ```
 
 ## Usage
 
-```
+```sh
 cd /path/to/src
 halmos
 ```
 
 For more details:
 
-```
+```sh
 halmos --help
 ```
 
@@ -65,14 +84,14 @@ Alternatively, you can run the latest halmos Docker image available at [ghcr.io/
 cd /path/to/src
 
 # mount '.' under /workspace in the container
-docker run -v .:/workspace ghcr.io/a16z/halmos:0.1.14
+docker run -v .:/workspace ghcr.io/a16z/halmos:latest
 ```
 
-## Examples
+## Getting Started
 
 Refer to the [getting started guide](docs/getting-started.md) and the [examples](examples/README.md) directory.
 
-## Contributing
+## Contributing / Developing
 
 Refer to the [contributing guidelines](CONTRIBUTING.md), and explore the list of issues labeled ["good first issue" or "help wanted."][issues]
 

docs/getting-started.md

@@ -8,34 +8,11 @@ Symbolic tests looks similar to fuzz tests, but there are certain differences th
 
 ## 0. Install Halmos
 
-Halmos is available as a [Python package][Halmos Package], and can be installed using `pip`:
-```
-pip install halmos
-```
-
-[Halmos Package]: <https://pypi.org/project/halmos/>
-
-**Tips:**
-
-- If you want to try out the nightly build version, you can install it from the Github repository:
-  ```
-  pip install git+https://github.com/a16z/halmos
-  ```
+If you haven't installed Halmos yet, please refer to the [installation guide](../README.md#installation) or quickly install it with:
 
-- If you're not familiar with managing Python packages, we recommend using `venv`. Create a virtual environment and install Halmos within it:
-  ```
-  python3 -m venv <venv-dir>
-  source <venv-dir>/bin/activate
-  pip install halmos
-  ```
-  You can activate or deactivate the virtual environment before or after using Halmos:
-  ```
-  # to activate:
-  source <venv-dir>/bin/activate
-
-  # to deactivate:
-  deactivate
-  ```
+```sh
+uv tool install halmos
+```
 
 ## 1. Write setUp()
 

pyproject.toml

@@ -35,8 +35,13 @@ halmos = "halmos.__main__:main"
 [project.urls]
 "Homepage" = "https://github.com/a16z/halmos"
 
-[tool.black]
-target-version = ["py311", "py312"]
+# development dependencies, can be installed with
+#   uv sync --extra dev
+# or
+#   pip install -e ".[dev]"
+# (see CONTRIBUTING.md for more details)
+[project.optional-dependencies]
+dev = ["ruff", "pre-commit", "pytest"]
 
 [tool.pytest.ini_options]
 # TODO: re-add test_traces.py when we have a better way to support it in CI