1.2. Hammer Setup

Hammer depends on Python 3.9+.

The default technology, ASAP7, has some extra requirements. See its README for instructions.

1.2.1. User Setup

You can install Hammer from PyPI:

pip install hammer-vlsi

If you are using ASAP7, you need to install hammer-vlsi with the asap7 extra dependency (gdspy or gdstk). By default, gdspy is installed:

pip install hammer-vlsi[asap7]

If instead, you want to install gdstk:

pip install hammer-vlsi[asap7-gdstk]

After installation, verify that you can run the hammer-vlsi script from the command line.

hammer-vlsi -h

Note: certain tools and technologies will have additional system requirements. For example, LVS with Netgen requires Tcl/Tk 8.6, which is not installed for CentOS7/RHEL7 and below. Refer to each respective tool and technology’s documentation for those requirements.

1.2.1.1. Installing Hammer as a Source Dependency

In some cases, it is useful to install Hammer as a source dependency. For instance, when developing tool or PDK plugins alongside a new feature or API changes in main Hammer, installing hammer as a source dependency will allow you to make changes in main hammer and see them reflected immediately when running code for your tool/PDK plugin.

1.2.1.1.1. 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.1.1.2. From a Generic Python Project

Other repos, such as Chipyard, are not poetry projects, but still depend on Hammer. To use Hammer as a source dependency:

Remove the PyPI hammer-vlsi dependency from the project (e.g. by editing a conda env.yml file and rerunning dependency resolution)
Clone Hammer somewhere on your disk
Activate the virtualenv of the project (e.g. Chipyard)
Run pip install -e . from the root of Hammer within the project’s virtualenv

1.2.2. 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.2.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.2.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.2.3. Type Checking with mypy

There is a small issue with the ruamel.yaml package typechecking which can be hacked around with:

touch .venv/lib/python3.10/site-packages/ruamel/py.typed

Inside your poetry virtualenv, from the root of Hammer, run:

mypy --namespace-packages --warn-unused-ignores -p hammer

Success: no issues found in 146 source files

mypy --namespace-packages --warn-unused-ignores tests

Success: no issues found in 25 source files

1.2.2.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.2.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.2.6. Building Documentation

Within your poetry virutualenv, 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.2.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>