Skip to content

Developers

Jump to bottom
Pete Pupalaikis edited this page Mar 14, 2024 · 38 revisions

This page contains the instructions for developers that want to modify and contribute to the SignalIntegrity project.

The topics covered here are:

Developer Installation

In order to develop SignalIntegrity, you will need to use git. Once you have git installed, create a directory somewhere on your machine, like SignalIntegrity. Then, from within that directory, type the following:

git init
git remote add origin https://github.com/Nubis-Communications/SignalIntegrity.git
git pull origin InNextRelease
pip install -e .

This initializes an empty git repository, defines the remote location as the GitHub website, pulls the current state of the branch InNextRelease to your repository and installs SignalIntegrity in a development mode with the source for the installation pointing to your current directory. See getting pip if you don't already have it installed.

All development is performed on feature branches that are pulled into the InNextRelease branch as they are completed. This is a continuous branch from master, the branch on which releases are made.

Code Development and Releases

Currently there are two main branches of the git repository used.

  • InNextRelease - where all derived branches for code development should be made from.
  • master - where the released code is.

For the time being, only the originator of SignalIntegrity retains the ability to check in on the master branch. Anyone can check in on any other branches. Periodically, during development, developers should merge the branch InNextRelease onto their branch to keep up to date with any currently approved changes - meaning they are not released, but they are intended to be released at some point in time. Better yet would be to rebase their branches to the InNextRelease branch. When any development branches are complete enough, the InNextRelease branch should be merged onto the development branch, any problems resolved, and then the development branch should be merged onto InNextRelease. A release occurs by merging the InNextRelease branch onto the master branch.

Coding Standards

SignalIntegrity doesn't really adhere strictly to any particular coding standards. There are, however, a few things to make sure of. One is that unit tests are generated for any new code and that code coverage is checked. Because this code is developed in conjunction with a text book, there are listings that appear in the book and this causes the need for certain special things done during the existing unit tests. You will find that some tests write listings that are included in the book. The code that writes these listings strip off the comments (as these can be read in the accompanying code documentation), and removes certain esoteric code that is deemed to not be of interest in the textbook. In other words, the textbook is concentrating on the algorithms themselves and as such don't need to list certain exception checking and handling, results caching and other things that would detract from the understanding of the algorithm. The control over the listings is performed through the use of comment lines containing the word pragma . Comment lines containing this will look for other tokens that control how the pragma is executed during code listing generation:

  • exclude - tells the generator to begin excluding lines.
  • include - tells the generator to begin including lines again.
  • silent - tells the generator to be silent when excluding lines. Silent exclusion means the lines simply disappear from the listing. Otherwise, excluded lines are replaced with an ellipses (...) to indicate that something is not being shown.
  • outdent - sometimes code is excluded that would normally cause the subsequent code to be indented, and removing the code would cause the indentation to be incorrect. For example, the removal of an if statement. outdent tells the generator to outdent the subsequent code.
  • indent - after a section that is usually indented, but has been outdented in the listing, indent tells the generator to begin indenting again. All of this detail really only pertains to the accompanying book, but while code is being modified, it is good to keep these areas properly up to date. Since the code listings are written in unit tests, the regression tests will fail whenever code that generates a listing is modified, but prior to relearning the test, the proper listing format should be checked. Also, code listings that appear in the book must meet certain criteria that is also tested by the unit tests, these are:
  • number of lines (cannot exceed a hard-coded constant number currently set to 67)
  • line length (cannot exceed a hard-coded constant number currently set to 88 characters) Any listing generated that exceeds these numbers and fails the test simply cannot be included in the book until fixed. Fixing can be made by reduction of line lengths, usually by breaking lines, and reduction of code length either through the use of pragmas, or by breaking up the method. Class listings are made often with multiple methods listed, and sometimes these class listings can be broken into multiple listings showing the multiple methods.

SignalIntegrityApp Help System Development

The help system for SignalIntegrityApp is written in LyX in the file Help.lyx. The file is converted into a sort of website under the directory PySIHelp.html.LyXconv using a program called elyxer project. I have only ever been successful in setting this up on a linux machine, and when set up properly, the help system is built using the file convert.sh. Linkage between the help system and SignalIntegrityApp is very important, especially in the area of control help. If you examine SignalIntegrityApp, you will find that the UI is put together using a class called Doers. Doers do something when executed and maintain the help system linkage (through labels placed throughout the help system) and the code that the doer executes, the pull-down menu system and ribbon bar icons. This was mostly done to avoid all of the coordination required with activating and deactivating things (a doer can be deactivated and it's ribbon bar icon goes gray along with the pull-down menu item. But the important thing here is to maintain the connection between the help system links in each doer and the labels in the help system. Someday a test should be made for this, but for now, one simply needs to be careful.

Release Checklist

To make a release, a subset zip file of the software is created:

  1. Make sure the branch master is up to date with what is intended to be released - make sure it's up to date on the remote system.
  2. Edit SignalIntegrity.__about__ and bump the version to the next intended number - check it in and push to remote.
  3. Edit 'setup.py' and make sure that all needed packages are included, and set the version numbers to the current package version numbers currently on the release machine.
  4. Edit the doxygen files and bump their version to the next intended number - check it in and push to remote.
  5. (at this point, you might want run doxygen and push the documentation to the gh-pages branch)
  6. Make a copy of the SignalIntegrity directory
  7. Rename it to SignalIntegrity-X.Y.Z
  8. Delete *.pyc
  9. Delete _pycache_ directories
  10. Delete *cached*.p
  11. Delete .* (all hidden files) - especially .git
  12. Unlink any linked Doc and Help directories
  13. Delete the SignalIntegrity.egg-info directory
  14. Delete the files LinkDoc.sh, LinkHelp.sh, UnlinkDoc.sh, and UnlinkHelp.sh
  15. Delete everything in Doc except for the README.md file
  16. Delete the Test directory
  17. Delete the SignalIntegrity/App/Help directory
  18. Delete the SignalIntegrity/App/Examples/PowerIntegrity directory
  19. Compress the SignalIntegrity-X.Y.Z directory to a zip file - the zip should be named SignalIntegrity-X.Y.Z and if opened, the first directory in the tree should be SignalIntegrity-X.Y.Z.
  20. On GitHub, start a new release
    1. tag it with the new version number.
    2. enter the release notes.
    3. drag the zip file in.
    4. at the end, add the line See [Installation](https://github.com/Nubis-Communications/SignalIntegrity/wiki/Installation) for installation instructions.

Then, to release to the Python Packaging Index (PyPI):

In the unzipped directory for the new version:

python setup.py bdist_wheel --universal
twine upload dist/*

You can test it first, by uploading to the test repository:

twine upload --repository-url https://test.pypi.org/legacy/ dist/*

Installation Details

These are some notes about how installations work.

sudo -H pip install . on Linux

  • All of the non-package data files go in usr/local/SignalIntegrity. Like the icon files - no python files seem to be copied here.
  • A bash script goes in usr/local/bin:

#!/usr/bin/python

# -*- coding: utf-8 -*-
import re
import sys

from SignalIntegrity.App.SignalIntegrityApp import main

if __name__ == '__main__':
sys.argv[0] = re.sub(r'(-script\.pyw?|\.exe)?$', '', sys.argv[0])
sys.exit(main())

  • A file is created in 'usr/local/lib/python2.7/dist-packages/SignalIntegrity-x.y.z.dist-info' containing information about the package
  • The python data files (all of the python files, icons, license files, etc.) are copied to '/usr/local/lib/python2.7/dist-packages/SignalIntegrity'

sudo -H python setup.py install

  • creates write-protected 'build', 'dist' and 'SignalIntegrity.egg-info' in working directory.
  • the build directory contains an empty 'bdist.linux-i686' directory and a directory called 'lib.linux-i686-2.7' containing all of the data files including python source.
  • the 'dist' directory contains a file called 'SignalIntegrity-x.y.z-py2.7.egg' which contains a directory called 'EGG-INFO' and the rest is all of the data files including the python source.
  • the 'SignalIntegrity.egg-info' file contains what seems to be the identical contents in the aforementioned 'EGG-INFO' directory in the egg file in the 'dist' directory.
  • In 'usr/local/bin' is a bash file called 'SignalIntegrity':

#!/usr/bin/python
# EASY-INSTALL-ENTRY-SCRIPT: 'SignalIntegrity==1.0.4','console_scripts','SignalIntegrity'
__requires__ = 'SignalIntegrity==1.0.4'
import re
import sys
from pkg_resources import load_entry_point

if __name__ == '__main__':
sys.argv[0] = re.sub(r'(-script\.pyw?|\.exe)?$', '', sys.argv[0])
sys.exit(
' load_entry_point('SignalIntegrity==1.0.4', 'console_scripts', 'SignalIntegrity')() ' ' )

  • In '/usr/local/python2.7/dist-packages' is the entire aforementioned egg file 'SignalIntegrity-x.y.z-py2.7.egg'

Once installed, it seems that the 'build','dist', and 'SignalIntegrity-x.y.x-py2.7.egg' can be removed from the working directory - it's just left there.

By the way, 'pip uninstall SignalIntegrity' removes only the egg file from '/usr/local/python2.7/dist-packages' and leaves the bash script in 'usr/local/bin'.

sudo -H pip install -e .

  • A file called 'SignalIntegrity.egg-info' is created in the work directory. It contains only egg information.
  • A bash script goes in usr/local/bin:

#!/usr/bin/python
# EASY-INSTALL-ENTRY-SCRIPT: 'SignalIntegrity','console_scripts','SignalIntegrity'
__requires__ = 'SignalIntegrity'
import re
import sys
from pkg_resources import load_entry_point

if __name__ == '__main__':
sys.argv[0] = re.sub(r'(-script\.pyw?|\.exe)?$', '', sys.argv[0])
sys.exit(
load_entry_point('SignalIntegrity', 'console_scripts', 'SignalIntegrity')()
)

  • A file is created in 'usr/local/lib/python2.7/dist-packages/SignalIntegrity.egg-link' is created which is a text file containing the path to the SignalIntegrity work directory.
  • In this case, it seems that the 'SignalIntegrity.egg-info' file left in the work directory must stay there.
  • 'pip uninstall SignalIntegrity' removes only the file 'usr/local/lib/python2.7/dist-packages/SignalIntegrity.egg-link'. It does not remove the 'SignalIntegrity.egg-info' in the working directory, nor the bash file in usr/local/bin.

sudo -H python setup.py develop

This seems to do exactly the same thing as sudo -H pip install -e .

SignalIntegrity is brought to you by:

Clone this wiki locally