Document how to use locally-built versions of programs

[xobs]

Description

The current openlane flow assumes the use of Docker where the entirety of the dependencies are located within the image. However, sometimes it is necessary to build local versions of the tools, such as when debugging segfaults within programs or when testing fixes.

Rather than waiting several weeks for fixes to perccolate through build pipelines, it would be nice to be able to test new versions of builds immediately.

There is mention of a "Containerless / Local" option at https://openlane.readthedocs.io/en/latest/getting_started/installation/installation_local.html, but there is a note that the containerless flow is deprecated and "no longer supported". It's not clear how to tell the openlane scripts to use a local install rather than invoking docker, and it's not clear whether the containerless approach will be supported in the future.

Proposal

No response

[xobs]

cc @proppy @mithro

[donn]

Just ./flow.tcl -ignore_mismatches without make mount or similar. Make sure the tools (OpenROAD, Magic, KLayout) are in PATH.

We stopped actively supporting it because frankly, it was a lot of maintenance work and hacking and like four people total used it.

[proppy]

@donn would you be open to us documenting the usage conda versions packaged in https://anaconda.org/LiteX-Hub/openlane/files?

[donn]

@proppy More than open.

[d-m-bailey]

@xobs Building a new docker container with updated programs is (or at least was) relatively straight-forward.
from your openlane installation directory

% export OPENLANE_IMAGE_NAME=<new_image_name>
% vi dependencies/tool_metadata.yml
 update the repos or commit ids for the programs you're updating
% cd docker
% make build-<program_name>
% make merge

Where <new_image_name> is something like 2023-04-04_12-00-00 or magic-8.3.378.
<program_name> is the name of the program you're updating. eg. build-magic or build-netgen, etc.
You can have multiple make build-<program_name> commands if you're updating multiple programs.

[xobs]

Thanks, @d-m-bailey -- the missing link was https://openlane.readthedocs.io/en/latest/for_developers/docker.html which I didn't previously see. If I'm on a system where I have Docker, I'll give that a try, since it seems to be the officially-sanctioned method of updating packages.

@donn -- I prefer to avoid using Docker for two reasons:

1. It's unreliable on Windows, and tends to stop working entirely (e.g. Endless "Docker desktop stopping"  docker/for-win#12576)
2. On macOs arm64, it runs under emulation, and the conda packages from @proppy have initial support for arm64

It's very nice to know that this method will continue to be usable, even if the documentation marks it as unsupported.

[donn]

On macOs arm64, it runs under emulation, and the conda packages from @proppy have initial support for arm64

I'm afraid I'm not entirely sure what you're referring to here: we generate Docker images for both amd64 and aarch64.

[xobs]

My mistake -- I was under the misconception that Docker ran images under qemu on arm64 and/or relied on Rosetta to perform emulation. It's nice to know that's not the case!