Coverage for apio / commands / apio.py: 100%
13 statements
« prev ^ index » next coverage.py v7.13.3, created at 2026-02-08 02:47 +0000
1"""Apio top level click command."""
3# -*- coding: utf-8 -*-
4# -- This file is part of the Apio project
5# -- (C) 2016-2019 FPGAwars
6# -- Author Jesús Arroyo
7# -- License GPLv2
10import click
11from click.exceptions import NoArgsIsHelpError
12from apio.utils.cmd_util import ApioSubgroup, ApioGroup
13from apio.utils import util
15# -- Import sub commands.
16from apio.commands import (
17 apio_api,
18 apio_boards,
19 apio_build,
20 apio_clean,
21 apio_create,
22 apio_devices,
23 apio_docs,
24 apio_drivers,
25 apio_examples,
26 apio_format,
27 apio_fpgas,
28 apio_graph,
29 apio_info,
30 apio_lint,
31 apio_packages,
32 apio_preferences,
33 apio_raw,
34 apio_report,
35 apio_sim,
36 apio_test,
37 apio_upload,
38)
41# -- The subcommands of this command, grouped by category.
42SUBGROUPS = [
43 ApioSubgroup(
44 "Build commands",
45 [
46 apio_build.cli,
47 apio_upload.cli,
48 apio_clean.cli,
49 ],
50 ),
51 ApioSubgroup(
52 "Verification commands",
53 [
54 apio_lint.cli,
55 apio_format.cli,
56 apio_sim.cli,
57 apio_test.cli,
58 apio_report.cli,
59 apio_graph.cli,
60 ],
61 ),
62 ApioSubgroup(
63 "Setup commands",
64 [
65 apio_create.cli,
66 apio_preferences.cli,
67 apio_packages.cli,
68 apio_drivers.cli,
69 apio_devices.cli,
70 ],
71 ),
72 ApioSubgroup(
73 "Utility commands",
74 [
75 apio_boards.cli,
76 apio_fpgas.cli,
77 apio_examples.cli,
78 apio_docs.cli,
79 apio_info.cli,
80 apio_raw.cli,
81 apio_api.cli,
82 ],
83 ),
84]
87def context_settings():
88 """Return a common Click command settings that adds
89 the alias -h to --help. This applies also to all the sub
90 commands such as apio build.
91 """
93 # -- This causes no args help commands such as 'apio' to return
94 # -- error code 0 instead of 2.
95 # -- Per https://tinyurl.com/click-help-no-args-error
96 NoArgsIsHelpError.exit_code = 0
98 # Per https://click.palletsprojects.com/en/8.1.x/documentation/
99 # #help-parameter-customization
100 return {"help_option_names": ["-h", "--help"]}
103# ---------------------------
104# -- Top click command node.
105# ---------------------------
107# -- Text in the rich-text format of the python rich library.
108APIO_HELP = """
109[b]WORK WITH FPGAs WITH EASE.[/b]
111Apio is an easy to use and open-source command-line suite designed to \
112streamline FPGA programming. It supports a wide range of tasks, including \
113linting, building, simulation, unit testing, and programming FPGA boards.
115An Apio project consists of a directory containing a configuration file \
116named 'apio.ini', along with FPGA source files, testbenches, and pin \
117definition files.
119Apio commands are intuitive and perform their intended functionalities right \
120out of the box. For example, the command apio upload automatically compiles \
121the design in the current directory and uploads it to the FPGA board.
123For detailed information about any Apio command, append the -h flag to view \
124its help text. For example:
126[code]apio build -h
127apio drivers ftdi install -h[/code]
129To check the apio version type:
130[code]
131apio --version[/code]
133For the full Apio CLI documentation visit https://fpgawars.github.io/apio/docs
134"""
137@click.group(
138 name="apio",
139 cls=ApioGroup,
140 subgroups=SUBGROUPS,
141 help=APIO_HELP,
142 short_help="Work with FPGAs with ease",
143 context_settings=context_settings(),
144)
145# NOTE: Without this explicit version value, click has difficulty
146# determining the version when running under pyinstaller.
147@click.version_option(
148 # -- Param 'version' (str). We use the custom message below instead.
149 util.get_apio_version_str(),
150 # -- Param '*param_decls. The version option names.
151 "-v",
152 "--version",
153 # -- Param 'message', the final string to display for apio --version.
154 message=util.get_apio_version_message(),
155)
156def apio_top_cli():
157 """The top level command group of apio commands"""
159 # pass