Hi, all.
This is qrqiuren.
I was selected as a member of GSoC of MyHDL in May and the coding starts in this June. I will post my blog contents here weekly for my GSoC project from now on. Please post your suggestions
The link to my blog: http://qren.logdown.com/posts/2017/05/07/myhdl-gsoc-setup-dev-env
The first step to get involved in the development MyHDL is to set up the environment. In this blog post, I will introduce the development environment.
Before reading these files, I assume you should have a basic knowledge of Python, Git, and MyHDL.
Step 0: Prerequisites
The software prerequisites of developing MyHDL is quite simple: Python and Git. If you want to do cosimulation, you may need a VHDL/Verilog simulator supported by MyHDL.
There are bunches of tutorials on the Internet that teach you how to install Python and Git. You can search them for detailed instructions of installation. Here is just a reminder.
Also, a GitHub account is required.
Python
For MyHDL development, the version of Python should be at least 2.6 for 2.x versions and at least 3.4 for Python 3.x. Personally, I prefer Python 3.x, but it doesn’t matter which version you use for developing. For compatibility purpose, the code should treat 2.x and 3.x equally.
On Linux distributions, you can install from either package repositories or source code.
For example, you may execute the following command on Ubuntu to install from software repo:
sudo apt install python3
On Windows, you can download directly from the official website of Python. Or you can also download Python distributions such as Anaconda since it contains more tools especially for science and Engineering.
Git
On Linux distributions, you can install git from software repository. For example, in Ubuntu, you may execute the following command:
sudo apt install git
For Windows and Mac users, GitHub Desktop is recommended.
You may find the book Pro Git useful when you using git command line.
My blog posts will mainly introduce operations in command line. If you prefer GitHub Desktop, you may find the user interface very friendly and very easy to do equivalent work as in command line. But the git command line is more extensive.
Register and configure GitHub account
Please follow the related documents in GitHub Help.
Also, it is nice to configure git by following the related section of Pro Git. Especially, configuring text editor using in git is recommended.
Step 1: Fork the repo
The main repository of MyHDL is on GitHub.
In MyHDL repository page, click “Fork” button, which is located on the upper right corner of the page. Then, the page will jump to your own repository forked before.
Forking a repo on GitHub is like to create your own copy of the project. You may make changes on your own repo and make pull requests to contribute back to the original project.
Step 2: Clone the repo to your own computer
Now, you are in your own repo.
Click “Clone or download” button, and the URL will pop up. Copy this URL to the clipboard.
In the working directory of your local computer, execute the following command: (Please change “qrqiuren” to your own user name)
git clone https://github.com/qrqiuren/myhdl.git
Then, you will see a subfolder called myhdl is created. It is your git repository.
Execute the following command to change the current directory to myhdl subfolder.
cd myhdl
Add the upstream as a remote would be easier to keep up with upstream in later development.
git remote add upstream https://github.com/myhdl/myhdl.git
git fetch upstream
Step 3: Setup MyHDL in developer mode
You may need setuptools to setup in developer mode. In Ubuntu, install setuptools by
sudo apt install python-setuptools
Execute the following command to setup MyHDL in developer mode
sudo python setup.py develop
If you have read the README file, you may find that I have replaced install into develop in the command. That is because if I use develop, and changed the code in myhdl directory, the changes will immediately affect other Python programs that import myhdl. This is very useful when you change the code frequently.
Installation of cosimulation modules
Please refer to GSoC #2: Configuration of Cosimulation.
Run unit tests
cd myhdl/test/core
py.test
It will start running unit tests. If there is any problems, maybe the installation or the code is not correct.
Step 4: Contribute
In order not to mix with other code, you should work on a new branch instead of master. For example, if you want to add a branch to implement MEP-111 specified in the website of MyHDL, you should switch to this branch by using
git branch mep-111
git checkout mep-111
And then, you can make the commits while remaining the main branch unaffected.
Now, it is time to review the code and contribute to it.
After you make some changes in the code, you may have to commit it. Execute the following command to see what you have done since last commit
git status
Now, you can add the changed files to the buffer to prepare for the next commit. For example, if you changed some code in myhdl/_intbv.py, you may execute
git add myhdl/_intbv.py
After you added all the files, you can commit to the git database by using
git commit
Then, a text editor (as configured before) will be opened for you to edit the commit message. You should briefly write what you have done in this commit, preferrably in one sentence. Please note that usually commits in git should be as “atomic” as possible, which means one commit does only one thing and cannot be separated anymore.
Finally, if you want to push the local git database to GitHub, you should execute the following:
git push origin mep-111
Writing unit tests
It is required to write corresponding unit tests if you modified the code. You may put your unit tests to the corresponding subfolder in myhdl/test/.
Please refer to Writing Tests for a guide to write unit tests for MyHDL.
Step 5: Make a pull request
A pull request (PR) is a way to request contributing the code from your repo to the original repo.
Before making a PR
Here is a simple checklist before making a PR:
- Have you committed all the code that consist this PR?
- Have you written unit tests for it?
Make a pull request
Go to the GitHub page of the forked repository.
Click “New pull request” button, and then submit the information about this pull request. Then, the PR will be created.
For more information of making a pull request, please refer to GitHub help.