Package: pip-hdl
pip-hdlMost modern programming languages provide package managers to facilitate code reuse, dependency tracking, installation, etc. However, there is no such a standart thing for HDL languages such as SystemVerilog. There are some projects that try to solve this like well-knownFuseSoccreating such system from scratch. But what if we try to solve this another way by reusing existing package manager?pip-hdlenables package managing for HDL (e.g. SystemVerilog) VIP or IP cores using Pythonpip.pipis simple and friendly, it allows to create quite lightweight packages, which are easy to publish toPyPior your local index, and install.How to installpip-hdlThe simplest ways is just use pip as for any other Python package:python-mpipinstallpip-hdlTo facilitate package managing process consider installingpoetryas well:python-mpipinstallpoetryAll the examples and the guide below use it. However, packaging and publishing can be done inother waysfor sure.How to create a packageRunpip-hdl newand follow the interactive instructions. Referexamplesto get an idea how a result looks like - only several files with 5-10 lines of code are required.Flow in a nutshell:Create a filelist (.ffile) for your HDL component. It should contain all needed information to compile in EDA: include directories, defines and sources.Put your component into Python package (basically directory with__init__.py). And add some meta information to your package.Build and publish!Check out the guide section below to get more details.How to use a packageRunpip install <name>to get a package and then putpip-hdl inspect <name> <attr>calls into your scripts to get all the required information for compilation (paths, environment variables, etc.).Check out the guide section below to get more details.GuideCreate HDL componentWhat HDL code can be packed? Actually, any piece of code which can be described as a single compilation unit via filelist.Use of filelists aka.ffiles is a common way in EDA world to describe compilation attributes for a single component. As the name suggests,.fis list of source files to be compiled. Usually, it also consists of include directories and possibly defines. All the things above are described almost equal in the most EDA tools, so filelists are pretty universal.To make your HDL componentpipandpip-hdlcompatible simple requirements have to followed:All sources and filelists have to be placed within Python package directory to be packed (directory with__init__.py). This directory would be theroot directoryfor your sources.There should befilelist.fin the sources root. This is an "entry point" discoverable bypip-hdlto help you compile and simulate your component later.All directories and sources mentioned within filelist have to use environment variable${<PACKAGENAME>_SOURCES_ROOT}. In other words all paths are absolute and based on a path to your sources root.If your component depends on another one, thendo notmention any sources or filelists of that component in yourfilelist.f. Instead, you need to correctly fill metadata of a package and usepip-hdlintrospection possibilities to get all required fileslists in the correct order for your component and dependencies.Add package metadataTo be successfully packed any Python package has to carry some portion of metadata. There are several ways to do it, but in general it ends up in fillingpyproject.toml filenearby a package.
This file usually includes: package name and version, author name, list of dependencies, and some metadata for packaging backend. Check outone of such files in examples.Alsopip-hdladds a bit above to ease HDL components management. This additional metadata is stored inside the package, and can be added by these two lines within__init__.py:frompip_hdlimportPackageMetaInfometainfo=PackageMetaInfo("package_name")Note, thatpip-hdlalways expects that your package hasmetainfovariable of typePackageMetaInfoinside.Pack and publish packagePython package management system a bit messed up, asPython environmentand other things, therefore you have a lot of options. Check outthis tutorialto get an idea how package could be published.pip-hdlis implicitly expectspoetryuse and publishing process in this system is pretty straightforward:poetrybuild
poetrypublishYou can also check outCI publish.yml scriptof this repository to get an idea howpip-hdlis published viapoetryitself.Install packageYour package and its dependencies can be installed from an index:python -m pip install <package_name>Or from a.whl filepython -m pip install <distribution_name>.whlOr as a part of packages listed inrequirements.txtpython -m pip install -r requirements.txtGet package metadatapip-hdlallows to get package attributes printed viainspectcommand. Output can be used within your Makefile, bash or other script.$pip-hdlinspect-h
usage:pip-hdlinspect[-h]OBJATTR

avaliableattributesforinspection:filelist-showabsolutepathtofilelistsources_root-showabsolutepathtosourcesrootsources_var-showenvironmentvariabletosetupsourcesroot(inNAME=VALformat)all_filelists-showallfilelistsinthedependency-resolvedorderall_filelists_as_args-showallfilelistsasabove,butformatthemasEDAarguments(with-f)all_sources_roots-showabsolutepathstoallsourcesdirectoriesall_sources_vars-showallenvironmentvariablesforallsourcesdependency_graph-dumpdependencygraphasinimage(graphvizrequired)positionalarguments:OBJobjectforinspection:nameofpip-hdl-poweredpackageorrequirements.txtwithsuchpackagesATTRattributetoinspect(listofavailableattributesisabove)Options are quite self-descriptive, but you can also referan example Makefile.Alternative way of getting the same metadata is to use Python:importfizzbuzz_agentprint(fizzbuzz_agent.metadata.filelist)