1.2. Hammer Setup

Hammer depends on Python 3.9+.

The Hammer setup is different based on its usecase, which are summarized as follows:

User Setup: Use Hammer with no modifications.
Power User Setup: Modify Hammer and see these changes immediately reflected when calling Hammer [recommended].
Developer Setup: Developing major Hammer features, adding dependencies, running Hammer unit tests, etc.

Note that some tools and technologies have extra setup requirements:

1.2.1. User Setup

Install the hammer python package from PyPI.

pip install hammer-vlsi

# if using the ASAP7 PDK you need the gdspy or gdstk dependencies
pip install hammer-vlsi[asap7]        # default: gdspy
pip install hammer-vlsi[asap7-gdstk]  # install gdstk instead

# verify that you can run the `hammer-vlsi` script from the command line
hammer-vlsi -h

1.2.2. Power User Setup

Install Hammer as a source dependency to some target virtual environment, such as conda.

# clone Hammer somewhere on your disk
git clone https://github.com/ucb-bar/hammer.git

# activate your target virtual environment, e.g. Chipyard
#   commands vary for this based on your package/environment manager:
#     conda activate <env name>
#     source <path>/.venv/bin/activate

# install hammer package in editable mode to your environment
cd hammer
pip install -e .  # run this after activating your target environment

1.2.2.1. Installing from Another Poetry Project

Hammer tool (e.g. hammer-cadence-plugins) and PDK plugin repositories are poetry projects (with a pyproject.toml in their root). To depend on Hammer as a source dependency, first clone Hammer somewhere on your disk. Then add this snippet to the tool/PDK plugin repo’s pyproject.toml (and remove any PyPI dependency on Hammer):

[tool.poetry.dependencies]
#hammer-vlsi = "^1.0.0"
hammer-vlsi = {path = "path/to/hammer", extras = ["asap7"], develop = true}

Run poetry update and poetry install. Do not commit the changes to pyproject.toml or poetry.lock without first removing the source dependency. You only need to specify extras if you need the asap7 optional dependency (gdstk).

1.2.3. Developer Setup

Clone Hammer with git

git clone git@github.com:ucb-bar/hammer
cd hammer

Install poetry to manage the development virtualenv and dependencies

curl -sSL https://install.python-poetry.org | python3 -

Create a poetry-managed virtualenv using the dependencies from pyproject.toml

# create the virtualenv inside the project folder (in .venv)
poetry config virtualenvs.in-project true
poetry install

Activate the virtualenv. Within the virtualenv, Hammer is installed and you can access its scripts defined in pyproject.toml (in [tool.poetry.scripts])

poetry shell
hammer-vlsi -h

1.2.3.1. Using PyCharm

This project works out of the box with PyCharm. You should install the Pydantic plugin to enable autocomplete for Pydantic BaseModels.

1.2.3.2. Unit Tests with pytest

Within the poetry virtualenv, from the root of Hammer, run the tests (-v will print out each test name explicitly)

pytest tests/ -v

If you want to skip the single long running-test in test_stackup.py:

pytest tests/ -m "not long" -v

If you want to run only a specific test use -k with a snippet of the test function you want to run:

pytest tests/ -k "lsf" -v

> tests/test_submit_command.py::TestSubmitCommand::test_lsf_submit[lsf] PASSED

By default, pytest will only display what a test prints to stdout if the test fails. To display stdout even for a passing test, use -rA:

pytest tests/test_build_systems.py -k "flat_makefile" -rA -v

> __________________ TestHammerBuildSystems.test_flat_makefile _________________
> ---------------------------- Captured stdout call ----------------------------
> [<global>] Loading hammer-vlsi libraries and reading settings
> [<global>] Loading technology 'nop'
> =========================== short test summary info ==========================
> PASSED tests/test_build_systems.py::TestHammerBuildSystems::test_flat_makefile

1.2.3.3. Type Checking with pyright

Run: poetry run pyright

1.2.3.4. Testing Different Python Versions with tox

Hammer is supposed to work with Python 3.9+, so we run its unit tests on all supported Python versions using tox and pyenv.

Install pyenv

curl https://pyenv.run | bash

Restart your shell and run pyenv init (and follow any of its instructions). Then restart your shell again.

Install Python versions

See the .python-version file at the root of hammer and install those Python versions using pyenv.

pyenv install 3.9.13
pyenv install 3.10.6

Once the Python interpreters are installed, run pyenv versions from the root of hammer.

pyenv versions
  system
* 3.9.13 (set by .../hammer/.python-version)
* 3.10.6 (set by .../hammer/.python-version)

From within your poetry virtualenv, run tox

tox

This will run the pytest unit tests using all the Python versions specified in pyproject.toml under the [tool.tox] key.

You can run tests only on a particular environment with -e

tox -e py39 # only run tests on Python 3.9

You can pass command line arguments to the pytest invocation within a tox virtualenv with --

tox -e py39 -- -k "lsf" -v

1.2.3.5. Adding / Updating Dependencies

To add a new Python (pip) dependency, modify pyproject.toml. If the dependency is only used for development, add it under the key [tool.poetry.dev-dependencies], otherwise add it under the key [tool.poetry.dependencies]. Then run poetry update and poetry install. The updated poetry.lock file should be committed to Hammer.

To update an existing dependency, modify pyproject.toml with the new version constraint. Run poetry update and poetry install and commit poetry.lock.

1.2.3.6. Building Documentation

First, generate the schema.json file from within your poetry virtualenv:

python3 -c "from hammer.tech import TechJSON; print(TechJSON.schema_json(indent=2))" > doc/Technology/schema.json

Then:

cd doc
Modify any documentation files. You can migrate any rst file to Markdown if desired.
Run sphinx-build . build
The generated HTML files are placed in build/
Open them in your browser firefox build/index.html

1.2.3.7. Publishing

Build a sdist and wheel (results are in dist):

poetry build

To publish on TestPyPI:

Create an account on TestPyPi
Note the source repository testpypi in pyproject.toml under the key [tool.poetry.source]
- To add another PyPI repository to poetry: poetry source add <source name> <source url>
Publish: poetry publish --repository testpypi -u <username> -p <password>