Add Apicula for Gowin FPGA Devices

[racerxdl]

This adds hdlc/apicula and hdlc/pkg:apicula for using in Gowin FPGA Devices.

Based on discussion in #4

This shouldn't affect any other package.

[umarcor]

Looks good with a couple of minor fixes (see below). However, updating the docs is pending. See https://hdl.github.io/containers/#_step_by_step_checklist. It's ok if you don't want to update the graph. Apicula is not listed in the To Do. So, you just need to:

• Add apicula to hdl/awesome. It's a markdown file with a yaml frontmatter. Minimal fields are project name, a description and an URL to a repo/site.
• Update dopc/tools.yml, including the ref to the awesome page, and the images the tool is included in.
• Add shield/badge to section CI.

Let us know if you need help with any of them 😃

[umarcor]

I just had a look at https://github.com/hdl/containers/pull/11/checks?check_run_id=1711703969#step:6:53 (the log of dockerTestPkg apicula), and it seems empty. You might need to use the following:

curl -fsSL https://codeload.github.com/YosysHQ/apicula/tar.gz/master | tar xzf - --strip-components=1
python3 setup.py build
python3 setup.py install --prefix=/usr/local --root=/tmp/apicula --optimize=1 --skip-build

[racerxdl]

Well its not that easy to compile the apicula by hand, it needs the gowin sdk and extract all the stuff. The PIP package is already pre-compiled. https://github.com/YosysHQ/apicula/blob/master/Dockerfile

The test is empty for now, it doesn't do anything. The image works correctly since it's what I'm using locally. I will make the fixes :D

[umarcor]

Well its not that easy to compile the apicula by hand, it needs the gowin sdk and extract all the stuff. The PIP package is already pre-compiled. https://github.com/YosysHQ/apicula/blob/master/Dockerfile

It is not necessary to compile it by hand, specially if that requires gowin's sdk (which might not be free). The point is to do whatever it needs to be done, so that all the artifacts/assets are available in $DESTDIR/user/local/, where DESTDIR=/opt/apicula or DESTDIR=/tmp/apicula. The motivation is to then copy the content of that directory to multiple containers, without installing pip in each of them.

Therefore, if you want to download the pre-compiled PIP package, and rearrange the artifacts, that's an acceptable solution. Building from sources would be ideal, but not an stopper.

/cc @pepijndevos, we are trying to install apicula to a directory, which is then to be copied into different environments with Python but not pip. For reference, Symbiyosys supports make DESTDIR=/opt/symbiyosys install. Can you provide us any guideline about how to achieve it with apicula?

The test is empty for now, it doesn't do anything. The image works correctly since it's what I'm using locally. I will make the fixes :D

I meant the dockerTestPkg, not the dockerTest. That is hdlc/pkg:apicula is empty, but hdlc/apicula works because you installed it explicitly with pip. In other words, in the current state, hdlc/pkg:apicula is useless (and unused). We need to be useful, because other PRs (#10) will need it.

[pepijndevos]

Uh, if you don't want pip you can just get the source tarball and use the setup.py I suppose?

Or you can just copy the source tarball somewhere and just run it from there. You just need to make sure to run with python -m apycula.gowin_pack to set the path as expected. You could generate your own wrapper scripts if you really want to avoid installing it as a python package. The only thing to watch out for is that if you do a naive python apycula/gowin_pack.py it wont be able to find all the stuff, see YosysHQ/apicula#25

[racerxdl]

I think I found a nice way, python let's change the "root" of its work by setting a virtualenv. Adding that makes all thing it install go that folder instead of another one. That should work :D

[racerxdl]

Hey @pepijndevos! My worry is that the picke files are not at the repository just in the pip package, so the gowin_pack / gowin_unpack wouldn't work I think.

[pepijndevos]

I mean the pypi source tarball https://pypi.org/project/Apycula/#files

[racerxdl]

Ahh @pepijndevos , I will try the pypi package directly. This should work :D

[racerxdl]

Hey @umarcor I think I got it now

[umarcor]

This RUN command should not be done here, but in the build stage. Therefore, python3-setuptools should not be required in the final image.

[racerxdl]

Well there is no way to install apycula without that. It is needed for that image otherwise the gowin_pack and gowin_unpack will not be usable. These commands are aliases to python functions that is created by setup tools.

[umarcor]

Well, that is undesirable, because it requires a non standard procedure for this tool, which we need to replicate in all the images where apicula is to be used. I would strongly recommend having the build procedure fixed/enhanced upstream, so that it's installable similarly to Symbiyosys.

Anyway, let's move forward. Please, do the following modifications:

• python3 is already installed in hdlc/build:base (see base.dockerfile). There is no need to install it here. Furthermore, please install python3-setuptools in https://github.com/hdl/containers/blob/main/base.dockerfile#L26. Then, remove apt-get calls from here.
• Instead of using COPY, use the experimental mount:
  • Add this comment at the top of the dockerfile: https://github.com/ghdl/ghdl-cosim/blob/master/docker/vunit-cocotb.dockerfile#L1.
  • Modify the RUN call similarly to https://github.com/ghdl/ghdl-cosim/blob/master/docker/vunit-cocotb.dockerfile#L34.
• Modify test/apicula.pkg.sh, for taking into account that no content will be located in /apicula/usr/local, only in /apicula.

[pepijndevos]

You can actually run the scripts with python -m apycula.gowin_pack without installation, the trick is just that the module path has to be set correctly else the databases can't be found. The installation step just adds a platform-specific binary file, but in this case you could include your own wrapper script if desired.

[umarcor]

WRT to CI errors, rebasing and force pushing should get rid of them. Those were fixed in main yesterday.

[racerxdl]

I wish github actions could use other images built in the same pipeline, so apicula would work. Maybe I should add python3-setuptools in another PR?

[umarcor]

I rebased and updated. There seems to be some issue with CI evaluating conditions incorrectly when I push to a PR. Anyway, I'll merge it. The solution is not ideal for now, but it will allow users to pull and use */apicula, while the wrappers for making it independent from pip, setuptools and wheel are contributed.

Thanks!