1. These instructions changed dramatically with the release of PyBERT v6, because PyBERT is now Pip-installable; no more Conda! :)

2. These instructions are for developers only! If you are a user, who does not intend to modify the PyBERT source code, back up and choose Instant Gratification, instead.

3. You may also wish to follow these instructions if you want to test the code in an unreleased development branch to, for instance, provide feedback to the developers.

4. I'm assuming you're working at a Bash, or Sh, prompt. If you're using Csh, please, make the necessary translations to the following commands.

5. The new development infrastructure is exclusively make driven. Enter just make without arguments, to see all available targets with descriptions.

If you wish to install PyBERT in a way that allows you to see immediate feedback to any changes you make to the PyBERT source code, follow these steps:

CAUTION: Do NOT skip step #1! It provides protection to your pre-existing, system Python installation. By doing your PyBERT development work inside a new virtual Python environment intended only for that purpose, you will prevent damage to your system Python environment.

NOTE: Your new virtual environment will be set up to use whichever version of Python you run when you create it.

1. Create and activate a custom virtual environment for PyBERT development:

   • python3 -m venv ~/.venv/pybert-dev (If that fails, try just "python".)
   • source ~/.venv/pybert-dev/bin/activate (Windows users: source ~\.venv\pybert-dev\Scripts\activate)

   NOTE: At this point, you should see (pybert-dev) in your prompt.

2. Install PyBERT and its dependencies into the new environment:

   • pip install PipBERT (Note the package name: Pip BERT!)

3. Fork/clone the PyBERT GitHub repository to your machine.

   1. From the main PyBERT repository, make your own fork of PyBERT by clicking where shown:

      

   2. From your new fork of PyBERT, clone, or download, to your working machine, by clicking where shown:

      

      and entering the following command:

      git clone <PASTE>

   Note: If you don't wish to create your own fork of the PyBERT project, you may just clone mine. However, note that you won't be able to push any changes you make to the Python source code back up to GitHub!

4. Move into the newly created PyBERT/ directory and install PyBERT in "development" mode:

   pip install -e .

5. Install the necessary development infrastructure tools, via:

   pip install -r requirements-dev.txt

6. If you wish to develop on something other than the main branch then check it out:

   git checkout <branch>

7. Test your new development mode installation of PyBERT, by executing the following command:

   python -m pybert

   You should see the usual PyBERT GUI application appear on your screen.

8. Enter the command: make, without any arguments, to see a list of targets available to you.

You are now ready to begin changing the PyBERT source code and testing those changes. Of course, you must quit and restart PyBERT, after making a source code change, in order to see its effects.

If you also wish to install PyIBIS-AMI in development mode, enter the following commands from the same command prompt and from within the PyBERT/ directory:

1. git submodule update --init PyAMI/
2. pip install -e ./PyAMI/
3. python -c "import pyibisami as dut; print(dut.__file__)"

In response to the last command, you should see something like:

<path to PyBERT project>/PyAMI/pyibisami/__init__.py

This section is intended to capture the procedure I've been using to do a major new release of PyBERT. The general idea here is to provide some "bread crumbs" for those wishing to begin participating in major releases of the PyBERT package.

Q: What defines a "major" release?

A: A major release occurs when a significant improvement has been made to either: the architecture of the PyBERT simulator, or the implementation of that architecture. For instance, this document is being first written as part of a release that adds a Viterbi decoder to the native PyBERT Rx model. Such an addition represents a fundamental improvement to the assumed underlying architecture of the receiver being modeled. A major release might also be justified if the implementation of the Viterbi decoder were improved so as to afford, say, an order of magnitude improvement in the simulation performance of this new block.

Note: All steps in PyBERT development/release are now driven by make. If you find yourself at some point using tox directly then you are probably doing something the "old way" and I encourage you to find and use the equivalent make command, instead.

Note: You can quickly get a synopsis of all available make commands, by simply entering the command: make, without arguments.

The iterative loop I've been using, to drive the repo. to a state of acceptability for a major release consists of the following 3 sub-procedures:

In order to type check the code, run the command:

• make type-check.

A successful run looks like this:

(pybert-dev)
davibana@5CD3141WXZ MINGW64 ~/prj/PyBERT (master)
$ make type-check
python -I -m tox run -e type-check
type-check: commands[0]> python -m mypy type_stubs/ src/
Success: no issues found in 51 source files
  type-check: OK (3.09=setup[0.17]+cmd[2.92] seconds)
  congratulations :) (3.73 seconds)

In order to lint the code, run the commands:

• make lint.
• make flake8.

Successful runs look like this:

(pybert-dev)
davibana@5CD3141WXZ MINGW64 ~/prj/PyBERT (master)
$ make lint
python -I -m tox run -e lint
lint: commands[0]> python -m pylint --disable=E0401 src/
************* Module pybert.gui.plot
src\pybert\gui\plot.py:549:5: W0511: ToDo: Make extrapolated portion of curve dashed. (fixme)
************* Module pybert.models.bert
src\pybert\models\bert.py:226:13: W0511: FIXME: The new import_channel() implementation breaks this. (fixme)
src\pybert\models\bert.py:233:36: W0511: ToDo: This needs interpolation first. (fixme)
src\pybert\models\bert.py:544:24: W0511: ToDo: Make this an accurate assessment of the random vertical noise. (fixme)
************* Module pybert.utility.jitter
src\pybert\utility\jitter.py:320:5: W0511: ToDo: Report this in the status bar. (fixme)

------------------------------------------------------------------
Your code has been rated at 9.99/10 (previous run: 9.98/10, +0.01)

  lint: OK (5.83=setup[0.16]+cmd[5.67] seconds)
  congratulations :) (6.42 seconds)

Note that the only warnings reported have to do with ToDos and FixMes.

(pybert-dev)
davibana@5CD3141WXZ MINGW64 ~/prj/PyBERT (master)
$ make flake8
python -I -m tox run -e flake8
flake8: commands[0]> python -m flake8 --ignore=E501,E272,E241,E222,E221,F401,F403,W291 src/
  flake8: OK (4.36=setup[0.16]+cmd[4.20] seconds)
  congratulations :) (4.94 seconds)

In order to functionally test the code, run the command:

• make test.

The complete output from a successful run is too long to include here. A successful run will include in its output several lines of the following form:

py311-win: OK (79.42=setup[4.08]+cmd[75.34] seconds)

And you should see one such line for each version of Python installed on your machine in the supported range, which is currently: >=3.10, <3.13.

Note: For a major release, please make sure to run functional testing as the last step before building. Please, do not assume that any changes made to satisfy either type checking or linting were innocuous enough that a final functional test isn't necessary; IT IS!