Installation

Relevant source files

The following files were used as context for generating this wiki page:

• setup.py
• readme.md
• regif/regif.py
• regif/init.py
• LICENSE

The regif utility is a Python-based tool designed to automatically generate register interface RTL code from an Excel template. As a Python script, it can be installed and run on any platform with a compatible Python environment.

This document outlines the prerequisites and different methods for installing and using the regif tool. It covers installation via the Python Package Index (PyPI) as well as direct script execution. Both methods rely on the same set of dependencies and core script logic.

Sources: readme.md:16, setup.py:11

Prerequisites

Before installing or running regif, ensure your system meets the following requirements.

Python Version

The tool requires a Python version of 3.3 or higher.

Sources: setup.py:25

Dependencies

regif depends on two external Python libraries to handle Excel file reading and DOCX file generation. These dependencies are automatically handled when installing with pip, but must be installed manually for direct script execution.

Package	Version	Description
xlrd	>=1.1.0	Used to read the input .xls register map.
python_docx	>=1.11.3	Used to generate the register manual .docx file.

Sources: setup.py:27-30

Runtime Dependency Check

The main script includes a function checklib() that verifies the presence of the required libraries at runtime. If a dependency is not found, it prints an error message indicating which library is missing and how to install it, then terminates the program.

This diagram illustrates the dependency check flow.

Installation Methods

There are two primary ways to use regif: by installing it as a package from PyPI or by running the script directly.

Using pip (Recommended)

The recommended method is to install regif using pip. This will download the package from PyPI, handle all dependencies automatically, and make the regif command available in your system's path.

pip install regif

This process is defined by the setup.py script, which specifies the package name, version, and dependencies.

The diagram below shows the pip install process.

Direct Script Execution

Alternatively, you can clone the repository and run the regif.py script directly using a Python interpreter. This method does not require package installation, but you must manually install the dependencies first.

1. Install dependencies:

   pip install xlrd>=1.1.0 python-docx>=1.11.3
   

2. Run the script:

   python regif.py mymodule.xls
   

If dependencies are missing, the checklib() function within the script will catch the ImportError and provide instructions.

Sources: readme.md:34, regif/regif.py:19-30

Basic Usage Flow

After installation, the typical workflow involves initializing a template, defining registers, and then generating the output files. The command-line interface is managed using Python's argparse library.

This sequence diagram illustrates the user workflow.

Package Details

The regif package is configured in setup.py. The use of find_packages() discovers the regif directory as a package due to the presence of the regif/__init__.py file.

Metadata	Value	Source File
name	regif	setup.py:11
version	1.3.3	setup.py:12
description	register interface verilog code generator...	setup.py:13
author	jijing.guo	setup.py:14
url	`https://github.com/jijingg/regif%60	setup.py:16
license	GPLv3	setup.py:19
python_requires	>=3.3	setup.py:25

The project is licensed under the GNU General Public License v3, as specified in the setup.py classifiers and the LICENSE file.

Sources: setup.py:11-25, regif/init.py, LICENSE