diff --git a/README.md b/README.md index 2a2d01d9..33925e95 100644 --- a/README.md +++ b/README.md @@ -4,51 +4,71 @@ [![Build Status][build-image]][build-url] [![License][license-image]][license-url] -![][linux-logo] -  -![][macosx-logo] -  -![][windows-logo] -  -![][ubuntu-logo] -  -![][raspbian-logo] - -Open source **ecosystem for open FPGA boards** +![][linux-logo]   ![][macosx-logo]   ![][windows-logo]   ![][ubuntu-logo]   ![][raspbian-logo] + + +**TL;DR, Apio is an extremly easy to install and use open-source toolbox for programming FPGA boards.** ## What is Apio? -Apio is a **multiplatform** toolbox with **static** pre-built packages to verify, synthesize, simulate and upload your verilog designs into the supported **FPGA boards** +* Apio is an **extremly easy to use** toolbox for FPGA programming. +* Apio is **easy to install**, no more dealing with 'toolcahins', licenses, scripts, and makefiles. +* Apio runs on a wide range of platforms, **Linux, Windows, Mac, and more**. +* Apio is **open source and free to use**. +* Apio supports **all aspects of FPGA developement cycles**, including building, simulation, testing, and uploading a design. +* **Apio commands are very simple,** for example, ``apio build`` to build, ``apio test`` to test end ``apio upload`` to upload. +* Apio can be used with **any text editor** and also **playes well with Visual Studio Code and github**. +* Apio supports out of the **more than 80 boards** and **custom boards can be easily added**. +* Apio provides out of the box tens of simple **project examples ready to build and upload**. +* Apio currently supports the ``ICE40`` and ``ECP5`` FPGA architecture with ``GOWIN`` architecture in the works. -## What?????? +## The Apio phylosophy -Apio makes **extremely easy** the process of working with **FPGAs**. Go from **scratch** to having a **blinky LED** in your FPGA board in minutes! This is because it is based only on **Free/Libre Open Source Software** (FLOSS). Just install it and use it as you want +Apio makes **extremely easy** the process of working with **FPGAs**. Go from **scratch** to having a **blinky LED** in your FPGA board in minutes! This is because it is was designed for ease of use and uses only **Free/Libre Open Source Software** (FLOSS). Just install it and use it as you want. -In this animation you can see the whole process of testing the Blinky led circuit: Just type one command and the circuit will be synthesized, and uploaded into the FPGA +In this animation you can see the whole process of testing the Blinky led circuit: Just type the command ``apio upload`` and the circuit will be synthesized, and uploaded into the FPGA ![](https://github.com/FPGAwars/Apio-wiki/raw/main/wiki/Quick-start/apio-alhambra-II-01.gif) -Think of Apio as a small **FPGA distribution**, which **collects** and **packages** **FLOSS toolchains for FPGAs**. You can install packages in **Linux**, **Mac** and **Windows** for synthesizing hardware, verifying and simulating from verilog files -The goal is making it **very easy** to start with FPGAs As the user **gh02t** said in this post on [Hacker-news](https://news.ycombinator.com/item?id=17912510): > Apio is a command line tool that automates installing the toolchain for your FPGA and running it. It just simplifies things, you don't have to use it if you'd rather call the individual tools for synthesis, P&R, simulation etc. It'd be reasonable to think of it as akin to a very smart Makefile combined with an automatic package manager, specialized to FPGAs (it's based on PlatformIO). It's nice when you're still kind of getting oriented, because you don't need to know how to set up and invoke the different tools... just call `apio build` or `apio simulate` -## Apio and higher level tools +## Sample Apio Commands -Apio has a **command line interface** (CLI). It is the **building block** for other **higher level tools**, like [Icestudio](https://icestudio.io/), [Apio-IDE](https://github.com/FPGAwars/apio-ide) or working with FPGAs from IDEs such as [Visual Studio Code](https://code.visualstudio.com/) +Below are typical apio commands that are used during the project developement cycle. The commands +are simple and intuitive. +``` +# Create a project +apio examples -f alhambra-ii/ledon # Fetch the files of an example + +# Build +apio build # Build the project +apio upload # Upload the design to the FPGA board + +# Verification +apio lint # Inspect the source code for issues. +apio test # Run the testbench +apio sim ledon_tb.v # Simulate the testbench and open a graphical viewer. +``` + +## Apio and higher level tools + +While many use Apio as a stand alone text based CLI toolbox, it can also be used with higher level graphical tools such as [Icestudio](https://icestudio.io/): -### A circuit in Icestdio ![](https://github.com/FPGAwars/Apio-wiki/raw/main/wiki/Introduction/icestudio-example.png) -### A verilog circuit in VSCode +## Apio in the media + +[Shawn Hymel's](https://shawnhymel.com/) excellent series on FPGA programming is based on **Apio** and the the Icestick board + +[![Introduction to FPGA YouTube Series](https://raw.githubusercontent.com/ShawnHymel/introduction-to-fpga/main/images/Intro%20to%20FPGA%20Part%201_Thumbnail.png)](https://www.youtube.com/watch?v=lLg1AgA2Xoo&list=PLEBQazB0HUyT1WmMONxRZn9NmQ_9CIKhb) -![](https://github.com/FPGAwars/Apio-wiki/raw/main/wiki/Introduction/vscode-example.png) ## Documentation @@ -71,12 +91,18 @@ Find all the information on this [WIKI PAGE](https://github.com/FPGAwars/apio/wi ## Credits +* Apio is uses the [YosysHQ](https://www.yosyshq.com) open source toolchain. + * APIO was inspired by [PlatformIO](https://github.com/platformio/platformio). * [FPGAwars](http://fpgawars.github.io/) community has developed this project in a voluntary and altruistic way since 11/2016. + +* Apio is implemented in Python and using the packages [Click](https://pypi.org/project/click/), and [Scons](https://pypi.org/project/SCons/). + * [BQ](https://www.bq.com) sponsored this project from 02/2016 to 11/2016. Thanks. + ## License Licensed under [GPL 2.0](http://opensource.org/licenses/GPL-2.0) and [Creative Commons Attribution-ShareAlike 4.0 International License](http://creativecommons.org/licenses/by-sa/4.0/). @@ -87,6 +113,8 @@ Licensed under [GPL 2.0](http://opensource.org/licenses/GPL-2.0) and [Creative C +[apio-logo]: https://github.com/FPGAwars/Apio-wiki/raw/main/wiki/Logos/Apio-github.png + [pypi-image]: https://img.shields.io/pypi/v/apio [pypi-url]: https://pypi.org/project/apio/ @@ -96,11 +124,11 @@ Licensed under [GPL 2.0](http://opensource.org/licenses/GPL-2.0) and [Creative C [license-image]: http://img.shields.io/:license-gpl-blue.svg [license-url]: (http://opensource.org/licenses/GPL-2.0) -[apio-logo]: https://github.com/FPGAwars/Apio-wiki/raw/main/wiki/Logos/Apio-github.png -[linux-logo]: https://github.com/FPGAwars/Apio-wiki/blob/main/wiki/Logos/linux.png -[macosx-logo]: https://github.com/FPGAwars/Apio-wiki/blob/main/wiki/Logos/macosx.png -[windows-logo]: https://github.com/FPGAwars/Apio-wiki/blob/main/wiki/Logos/windows.png -[ubuntu-logo]: https://github.com/FPGAwars/Apio-wiki/blob/main/wiki/Logos/ubuntu.png -[raspbian-logo]: https://github.com/FPGAwars/Apio-wiki/blob/main/wiki/Logos/raspbian.png + +[linux-logo]: https://raw.githubusercontent.com/FPGAwars/Apio-wiki/refs/heads/main/wiki/Logos/linux.png +[macosx-logo]: https://raw.githubusercontent.com/FPGAwars/Apio-wiki/refs/heads/main/wiki/Logos/macosx.png +[windows-logo]: https://raw.githubusercontent.com/FPGAwars/Apio-wiki/refs/heads/main/wiki/Logos/windows.png +[ubuntu-logo]: https://raw.githubusercontent.com/FPGAwars/Apio-wiki/refs/heads/main/wiki/Logos/ubuntu.png +[raspbian-logo]: https://raw.githubusercontent.com/FPGAwars/Apio-wiki/refs/heads/main/wiki/Logos/raspbian.png [wiki]: https://github.com/FPGAwars/apio/wiki diff --git a/apio/cmd_util.py b/apio/cmd_util.py index 0b083be2..70ee4495 100644 --- a/apio/cmd_util.py +++ b/apio/cmd_util.py @@ -12,6 +12,7 @@ import sys from typing import Mapping, List, Tuple, Any, Dict, Union import click +from apio import util # This text marker is inserted into the help text to indicates @@ -139,9 +140,9 @@ def check_at_most_one_param( canonical_aliases = _params_ids_to_aliases( cmd_ctx, specified_param_ids ) - aliases_str = ", ".join(canonical_aliases) + aliases_str = util.list_plurality(canonical_aliases, "and") fatal_usage_error( - cmd_ctx, f"[{aliases_str}] cannot be combined together." + cmd_ctx, f"{aliases_str} cannot be combined together." ) @@ -165,15 +166,17 @@ def check_exactly_one_param( if len(specified_param_ids) < 1: # -- User specified Less flags than required. canonical_aliases = _params_ids_to_aliases(cmd_ctx, param_ids) - aliases_str = ", ".join(canonical_aliases) - fatal_usage_error(cmd_ctx, f"Specify one of [{aliases_str}].") + aliases_str = util.list_plurality(canonical_aliases, "or") + fatal_usage_error(cmd_ctx, f"specify one of {aliases_str}.") else: # -- User specified more flags than allowed. canonical_aliases = _params_ids_to_aliases( cmd_ctx, specified_param_ids ) - aliases_str = ", ".join(canonical_aliases) - fatal_usage_error(cmd_ctx, f"Specify only one of [{aliases_str}].") + aliases_str = util.list_plurality(canonical_aliases, "and") + fatal_usage_error( + cmd_ctx, f"{aliases_str} cannot be combined together." + ) def check_at_least_one_param( @@ -193,9 +196,9 @@ def check_at_least_one_param( # If more 2 or more print an error and exit. if len(specified_param_ids) < 1: canonical_aliases = _params_ids_to_aliases(cmd_ctx, param_ids) - aliases_str = ", ".join(canonical_aliases) + aliases_str = util.list_plurality(canonical_aliases, "or") fatal_usage_error( - cmd_ctx, f"At list one of [{aliases_str}] must be specified." + cmd_ctx, f"at list one of {aliases_str} must be specified." ) diff --git a/apio/commands/examples.py b/apio/commands/examples.py index 38303ac2..54b7a5e5 100644 --- a/apio/commands/examples.py +++ b/apio/commands/examples.py @@ -53,7 +53,7 @@ apio examples --list # List all examples apio examples -l | grep -i icezum # Filter examples. apio examples -f icezum/leds # Fetch example files - apio examples -s icezum/leds # Fetch example directory + apio examples -d icezum/leds # Fetch example directory apio examples -d icezum # Fetch all board examples """ diff --git a/apio/commands/system.py b/apio/commands/system.py index ab0dbbf0..8506d904 100644 --- a/apio/commands/system.py +++ b/apio/commands/system.py @@ -147,6 +147,10 @@ def cli( click.secho("Apio version ", nl=False) click.secho(importlib.metadata.version("apio"), fg="cyan") + # -- Apio version. + click.secho("Python version ", nl=False) + click.secho(util.get_python_version(), fg="cyan") + # -- Print platform id. click.secho("Platform id ", nl=False) click.secho(apio_ctx.platform_id, fg="cyan") diff --git a/apio/managers/examples.py b/apio/managers/examples.py index 8a177668..00ee20f7 100644 --- a/apio/managers/examples.py +++ b/apio/managers/examples.py @@ -15,21 +15,6 @@ from apio import pkg_util from apio.apio_context import ApioContext -# -- Error messages -EXAMPLE_NOT_FOUND_MSG = """ -Warning: this example does not exist -Use `apio examples -l` to list all the available examples""" - -USAGE_EXAMPLE = """ -To fetch example files: - apio examples -f - -Example of use: - apio examples -f icesum/leds - -Type 'apio examples -h' for more details. -""" - @dataclass class ExampleInfo: @@ -138,7 +123,6 @@ def list_examples(self) -> None: # -- For a terminal, emit additional summary. if output_config.terminal_mode(): click.secho(f"Total: {len(examples)}") - click.secho(USAGE_EXAMPLE, fg="green") return 0 @@ -166,7 +150,7 @@ def copy_example_dir(self, example: str, project_dir: Path, sayno: bool): # -- If the source example path is not a folder... it is an error if not src_example_path.is_dir(): - click.secho(EXAMPLE_NOT_FOUND_MSG, fg="yellow") + click.secho(f"Error: example [{example}] not found.", fg="red") return 1 # -- The destination path is a folder...It means that the @@ -221,9 +205,9 @@ def copy_example_files(self, example: str, project_dir: Path, sayno: bool): # -- Build the source example path (where the example was installed) src_example_path = self.examples_dir / example - # -- If the source example path is not a folder... it is an error + # -- If the source example path is not a folder. it is an error if not src_example_path.is_dir(): - click.secho(EXAMPLE_NOT_FOUND_MSG, fg="yellow") + click.secho(f"Error: example [{example}] not found.", fg="red") return 1 # -- Copy the example files!! diff --git a/apio/util.py b/apio/util.py index 779fe7f8..1a31f177 100644 --- a/apio/util.py +++ b/apio/util.py @@ -15,7 +15,7 @@ import shutil from enum import Enum from dataclasses import dataclass -from typing import Optional, Any, Tuple +from typing import Optional, Any, Tuple, List import subprocess from threading import Thread from pathlib import Path @@ -488,3 +488,20 @@ def plurality(obj: Any, singular: str, plural: str = None) -> str: if plural is None: plural = singular + "s" return f"{n} {plural}" + + +def list_plurality(str_list: List[str], conjunction: str) -> str: + """Format a list as a human friendly string.""" + # -- This is a programming error. Not a user error. + assert str_list, "list_plurarlity expect len() >= 1." + + # -- Handle the case of a single item. + if len(str_list) == 1: + return str_list[0] + + # -- Handle the case of 2 items. + if len(str_list) == 2: + return f"{str_list[0]} {conjunction} {str_list[1]}" + + # -- Handle the case of three or more items. + return ", ".join(str_list[:-1]) + f", {conjunction} {str_list[-1]}" diff --git a/test/commands/test_drivers.py b/test/commands/test_drivers.py index fb348429..62b3db12 100644 --- a/test/commands/test_drivers.py +++ b/test/commands/test_drivers.py @@ -17,8 +17,8 @@ def test_drivers(apio_runner: ApioRunner): result = sb.invoke_apio_cmd(apio_drivers) assert result.exit_code == 1 assert ( - "Error: Specify one of [--ftdi-install, --ftdi-uninstall, " - "--serial-install, --serial-uninstall]" in result.output + "specify one of --ftdi-install, --ftdi-uninstall, " + "--serial-install, or --serial-uninstall" in result.output ) # -- Execute "apio --ftdi-install, --serial-install" @@ -27,6 +27,6 @@ def test_drivers(apio_runner: ApioRunner): ) assert result.exit_code == 1, result.output assert ( - "Error: Specify only one of [--ftdi-install, --serial-install]" + "Error: --ftdi-install and --serial-install cannot be combined" in result.output ) diff --git a/test/commands/test_examples.py b/test/commands/test_examples.py index fac0b536..617c01a9 100644 --- a/test/commands/test_examples.py +++ b/test/commands/test_examples.py @@ -17,7 +17,7 @@ def test_examples(apio_runner: ApioRunner): result = sb.invoke_apio_cmd(apio_examples) assert result.exit_code == 1, result.output assert ( - "Error: Specify one of [--list, --fetch-dir, --fetch-files]" + "specify one of --list, --fetch-dir, or --fetch-files" in result.output ) diff --git a/test/commands/test_packages.py b/test/commands/test_packages.py index 1862336b..acc55546 100644 --- a/test/commands/test_packages.py +++ b/test/commands/test_packages.py @@ -17,7 +17,7 @@ def test_packages(apio_runner: ApioRunner): result = sb.invoke_apio_cmd(apio_packages) assert result.exit_code == 1, result.output assert ( - "Error: Specify one of [--list, --install, --uninstall, --fix]" + "specify one of --list, --install, --uninstall, or --fix" in result.output ) diff --git a/test/commands/test_system.py b/test/commands/test_system.py index 751a8b4c..b6330ab9 100644 --- a/test/commands/test_system.py +++ b/test/commands/test_system.py @@ -17,9 +17,8 @@ def test_system(apio_runner: ApioRunner): result = sb.invoke_apio_cmd(apio_system) assert result.exit_code == 1, result.output assert ( - "Specify one of " - "[--lsftdi, --lsusb, --lsserial, --info, --platforms]" - in result.output + "specify one of --lsftdi, --lsusb, --lsserial, --info, " + "or --platforms" in result.output ) # -- Execute "apio system --lsftdi" diff --git a/test/test_cmd_util.py b/test/test_cmd_util.py index 714e2b42..b567448b 100644 --- a/test/test_cmd_util.py +++ b/test/test_cmd_util.py @@ -57,4 +57,4 @@ def test_check_at_most_one_param(capsys): check_at_most_one_param(cmd_ctx, ["_opt1", "_opt2", "_opt3"]) captured = capsys.readouterr() assert e.value.code == 1 - assert "[--opt1, --opt2] cannot be combined together" in captured.out + assert "--opt1 and --opt2 cannot be combined together" in captured.out diff --git a/test/test_util.py b/test/test_util.py index 26e994f6..e2e0f738 100644 --- a/test/test_util.py +++ b/test/test_util.py @@ -2,12 +2,34 @@ Tests of scons_util.py """ -from apio.util import plurality +import pytest +from apio.util import plurality, list_plurality # pylint: disable=fixme # TODO: Add more tests. def test_pluraliry(): - """Tests the plurality function.""" + """Tests the plurality() function.""" + # -- Test for ints 1, 2, 3 + assert plurality(1, "file") == "1 file" + assert plurality(2, "file") == "2 files" assert plurality(3, "file") == "3 files" + + # -- Test for lengths 1, 2, 3. + assert plurality(["aa"], "file") == "1 file" + assert plurality(["aa", "bb"], "file") == "2 files" + assert plurality(["aa", "bb", "cc"], "file") == "3 files" + + +def test_list_pluraliry(): + """Tests the list_plurality() function.""" + + # -- Test for lengths 1, 2, and 3. + assert list_plurality(["aa"], "or") == "aa" + assert list_plurality(["aa", "bb"], "and") == "aa and bb" + assert list_plurality(["aa", "bb", "cc"], "or") == "aa, bb, or cc" + + # -- An empty list should trhow an assert exception. + with pytest.raises(AssertionError): + list_plurality([], "or")