Merge branch 'main' into implements-options

Author: rodrigomelo9

.github/workflows/docs.yml

@@ -4,6 +4,7 @@ on:
   push:
     paths:
       - 'docs/**'
+      - 'pyfpga/project.py'
     branches:
       - main
       - dev

.github/workflows/lint.yml

@@ -2,6 +2,10 @@ name: 'lint'
 
 on:
   push:
+    paths:
+      - 'examples/**'
+      - 'pyfpga/**'
+      - 'tests/**'
 
 jobs:
   lint:
@@ -11,5 +15,5 @@ jobs:
       uses: actions/checkout@v4
     - name: Install dependencies
       run: pip install pycodestyle pylint
-    - name: Run linters
+    - name: Run linting
       run: make lint

.github/workflows/pypi.yaml

@@ -0,0 +1,30 @@
+name: Publish Package to PyPI
+
+on:
+  push:
+    tags:
+      - '*.*.*'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.12'
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install setuptools wheel twine
+    - name: Build package
+      run: |
+        python setup.py sdist bdist_wheel
+    - name: Upload package to PyPI
+      run: |
+        twine upload dist/*
+      env:
+        TWINE_USERNAME: __token__
+        TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}

.github/workflows/test.yml

@@ -2,26 +2,36 @@ name: 'test'
 
 on:
   push:
+    paths:
+      - 'examples/projects/**'
+      - 'pyfpga/**'
+      - 'tests/**'
 
 jobs:
   test:
     strategy:
       matrix:
-        os: ['ubuntu']
+        os: ['ubuntu', 'windows']
         pyver: ['3.8', '3.9', '3.10', '3.11', '3.12']
+        exclude:
+          - os: 'windows'
+            pyver: '3.8'
+          - os: 'windows'
+            pyver: '3.9'
+          - os: 'windows'
+            pyver: '3.10'
+          - os: 'windows'
+            pyver: '3.11'
     runs-on: ${{ matrix.os }}-latest
     name: ${{ matrix.os }} | ${{ matrix.pyver }}
     steps:
     - name: Checkout repository
       uses: actions/checkout@v4
-      with:
-        submodules: true
-        fetch-depth: 0
     - name: Set up Python ${{ matrix.pyver }}
       uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.pyver }}
     - name: Install dependencies
       run: pip install . && pip install pytest
     - name: Run tests
-      run: source tests/mocks/source-me.sh && make test
+      run: make test

CHANGELOG.md

@@ -619,56 +619,3 @@ Program, unless a warranty or assumption of liability accompanies a
 copy of the Program in return for a fee.
 
                      END OF TERMS AND CONDITIONS
-
-            How to Apply These Terms to Your New Programs
-
-  If you develop a new program, and you want it to be of the greatest
-possible use to the public, the best way to achieve this is to make it
-free software which everyone can redistribute and change under these terms.
-
-  To do so, attach the following notices to the program.  It is safest
-to attach them to the start of each source file to most effectively
-state the exclusion of warranty; and each file should have at least
-the "copyright" line and a pointer to where the full notice is found.
-
-    PyFPGA
-    Copyright (C) 2019  Rodrigo Alejandro Melo
-
-    This program is free software: you can redistribute it and/or modify
-    it under the terms of the GNU General Public License as published by
-    the Free Software Foundation, either version 3 of the License, or
-    (at your option) any later version.
-
-    This program is distributed in the hope that it will be useful,
-    but WITHOUT ANY WARRANTY; without even the implied warranty of
-    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-    GNU General Public License for more details.
-
-    You should have received a copy of the GNU General Public License
-    along with this program.  If not, see <http://www.gnu.org/licenses/>.
-
-Also add information on how to contact you by electronic and paper mail.
-
-  If the program does terminal interaction, make it output a short
-notice like this when it starts in an interactive mode:
-
-    PyFPGA  Copyright (C) 2019  Rodrigo Alejandro Melo
-    This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
-    This is free software, and you are welcome to redistribute it
-    under certain conditions; type `show c' for details.
-
-The hypothetical commands `show w' and `show c' should show the appropriate
-parts of the General Public License.  Of course, your program's commands
-might be different; for a GUI interface, you would use an "about box".
-
-  You should also get your employer (if you work as a programmer) or school,
-if any, to sign a "copyright disclaimer" for the program, if necessary.
-For more information on this, and how to apply and follow the GNU GPL, see
-<http://www.gnu.org/licenses/>.
-
-  The GNU General Public License does not permit incorporating your program
-into proprietary programs.  If your program is a subroutine library, you
-may consider it more useful to permit linking proprietary applications with
-the library.  If this is what you want to do, use the GNU Lesser General
-Public License instead of this License.  But first, please read
-<http://www.gnu.org/philosophy/why-not-lgpl.html>.

LICENSE

@@ -2,6 +2,13 @@
 
 .PHONY: docs
 
+ifeq ($(OS),Windows_NT)
+  PATH_SEP := ;
+else
+  PATH_SEP := :
+endif
+export PATH := $(CURDIR)/tests/mocks$(PATH_SEP)$(PATH)
+
 all: docs lint test
 
 docs:
@@ -13,7 +20,8 @@ lint:
 	git diff --check --cached
 
 test:
-	pytest
+	pytest -vv
+	cd tests && bash regress.sh
 
 clean:
 	py3clean .

Makefile

@@ -49,29 +49,37 @@ For a comprehensive list of supported tools, features and limitations, please re
 
 ## Installation
 
-PyFPGA requires Python>=3.8.
+> **NOTE:** PyFPGA requires Python >= 3.8.
 
-At the moment, it's only available as a git repository hosted on GitHub. It can be installed with pip:
+PyFPGA can be installed in several ways:
+
+1. From PyPi using pip:
+
+```
+pip install pyfpga
+```
+
+2. From the GitHub repository:
 
 ```
 pip install 'git+https://github.com/PyFPGA/pyfpga#egg=pyfpga'
 ```
 
-Alternatively, you can get a copy of the repository either through git clone or downloading a tarball/zipfile, and then:
+3. Clone/download the repository and install it manually:
 
 ```
 git clone https://github.com/PyFPGA/pyfpga.git
 cd pyfpga
 pip install -e .
 ```
 
-> With `-e` (`--editable`) your application is installed into site-packages via a kind of symlink.
-> That allows pulling changes through git or changing the branch, avoiding the need to reinstall the package.
+> **NOTE:** with `-e` (`--editable`), the application is installed into site-packages via a symlink, which allows you to pull changes through git or switch branches without reinstalling the package.
 
 ## Similar projects
 
 * [edalize](https://github.com/olofk/edalize): an abstraction library for interfacing EDA tools.
-* [Hdlmake](https://ohwr.org/project/hdl-make): tool for generating multi-purpose makefiles for FPGA projects.
+* Firmware Framework ([FWK](https://gitlab.desy.de/fpgafw/fwk)): set of scripts and functions/procedures that combine all the input files needed to produce build.
 * HDL On Git ([Hog](https://gitlab.com/hog-cern/Hog)): a set of Tcl/Shell scripts plus a suitable methodology to handle HDL designs in a GitLab repository.
+* [Hdlmake](https://ohwr.org/project/hdl-make): tool for generating multi-purpose makefiles for FPGA projects.
 * IPbus Builder ([IPBB](https://github.com/ipbus/ipbb)): a tool for streamlining the synthesis, implementation and simulation of modular firmware projects over multiple platforms.
 * [tsfpga](https://github.com/tsfpga/tsfpga): a flexible and scalable development platform for modern FPGA projects.

README.md

@@ -18,12 +18,13 @@ Add support for the new tool
    pyfpga/factory.py # UPDATE
    pyfpga/helpers/prj2bit.py # UPDATE
 
-Add tests and a tool mock-up
+Add tests and tools mock-ups
 ----------------------------
 
 .. code-block:: bash
 
    tests/test_tools.py # UPDATE
+   tests/regress.sh # UPDATE
    tests/support.py # UPDATE if exceptions are needed
    tests/mocks/<NEWCOMMAND>
 
@@ -36,7 +37,6 @@ Add examples
    examples/sources/cons/<NEWBOARD>/clk.<EXT>
    examples/sources/cons/<NEWBOARD>/led.<EXT>
    examples/projects/<NEWTOOL>.py
-   examples/projects/regress.sh # UPDATE
    examples/helpers/<NEWTOOL>.sh
    examples/hooks/<NEWTOOL>.py # OPTIONAL
 
@@ -61,9 +61,7 @@ Verify the functionality
 
 .. code-block:: bash
 
-   cd examples/projects/
-   bash regress.sh <NEWTOOL>
-   cd ../../tests/
+   cd tests
    python3 support.py --tool <NEWTOOL>
 
 Updated the documentation