Coverage for apio/commands/apio.py: 100%

1# This file is part of the Apio project 

2# (C) 2016-present FPGAwars 

3# Project authors: 

4# * Jesús Arroyo (Jesus89) (2016-2019) 

5# * Juan Gonzalez (obijuan) (2019-2024) 

6# * The Apio Team (2024-present) 

7# License: GPLv2 

8 

9"""Apio top level click command.""" 

10 

11 

12import click 

13from click.exceptions import NoArgsIsHelpError 

14from apio.utils.cmd_util import ApioSubgroup, ApioGroup 

15from apio.utils import util 

16 

17# -- Import sub commands. 

18from apio.commands import ( 

19 apio_api, 

20 apio_boards, 

21 apio_build, 

22 apio_clean, 

23 apio_create, 

24 apio_devices, 

25 apio_docs, 

26 apio_drivers, 

27 apio_examples, 

28 apio_format, 

29 apio_fpgas, 

30 apio_graph, 

31 apio_info, 

32 apio_lint, 

33 apio_packages, 

34 apio_preferences, 

35 apio_raw, 

36 apio_report, 

37 apio_sim, 

38 apio_test, 

39 apio_upload, 

40) 

41 

42 

43# -- The subcommands of this command, grouped by category. 

44SUBGROUPS = [ 

45 ApioSubgroup( 

46 "Build commands", 

47 [ 

48 apio_build.cli, 

49 apio_upload.cli, 

50 apio_clean.cli, 

51 ], 

52 ), 

53 ApioSubgroup( 

54 "Verification commands", 

55 [ 

56 apio_lint.cli, 

57 apio_format.cli, 

58 apio_sim.cli, 

59 apio_test.cli, 

60 apio_report.cli, 

61 apio_graph.cli, 

62 ], 

63 ), 

64 ApioSubgroup( 

65 "Setup commands", 

66 [ 

67 apio_create.cli, 

68 apio_preferences.cli, 

69 apio_packages.cli, 

70 apio_drivers.cli, 

71 apio_devices.cli, 

72 ], 

73 ), 

74 ApioSubgroup( 

75 "Utility commands", 

76 [ 

77 apio_boards.cli, 

78 apio_fpgas.cli, 

79 apio_examples.cli, 

80 apio_docs.cli, 

81 apio_info.cli, 

82 apio_raw.cli, 

83 apio_api.cli, 

84 ], 

85 ), 

86] 

87 

88 

89def context_settings(): 

90 """Return a common Click command settings that adds 

91 the alias -h to --help. This applies also to all the sub 

92 commands such as apio build. 

93 """ 

94 

95 # -- This causes no args help commands such as 'apio' to return 

96 # -- error code 0 instead of 2. 

97 # -- Per https://tinyurl.com/click-help-no-args-error 

98 NoArgsIsHelpError.exit_code = 0 

99 

100 # Per https://click.palletsprojects.com/en/8.1.x/documentation/ 

101 # #help-parameter-customization 

102 return {"help_option_names": ["-h", "--help"]} 

103 

104 

105# --------------------------- 

106# -- Top click command node. 

107# --------------------------- 

108 

109# -- Text in the rich-text format of the python rich library. 

110APIO_HELP = """ 

111[b]WORK WITH FPGAs WITH EASE.[/b] 

112 

113Apio is an easy to use and open-source command-line suite designed to \ 

114streamline FPGA programming. It supports a wide range of tasks, including \ 

115linting, building, simulation, unit testing, and programming FPGA boards. 

116 

117An Apio project consists of a directory containing a configuration file \ 

118named 'apio.ini', along with FPGA source files, testbenches, and pin \ 

119definition files. 

120 

121Apio commands are intuitive and perform their intended functionalities right \ 

122out of the box. For example, the command apio upload automatically compiles \ 

123the design in the current directory and uploads it to the FPGA board. 

124 

125For detailed information about any Apio command, append the -h flag to view \ 

126its help text. For example: 

127 

128[code]apio build -h 

129apio drivers ftdi install -h[/code] 

130 

131To check the apio version type: 

132[code] 

133apio --version[/code] 

134 

135For the full Apio CLI documentation visit https://fpgawars.github.io/apio/docs 

136""" 

137 

138 

139@click.group( 

140 name="apio", 

141 cls=ApioGroup, 

142 subgroups=SUBGROUPS, 

143 help=APIO_HELP, 

144 short_help="Work with FPGAs with ease", 

145 context_settings=context_settings(), 

146) 

147# NOTE: Without this explicit version value, click has difficulty 

148# determining the version when running under pyinstaller. 

149@click.version_option( 

150 # -- Param 'version' (str). We use the custom message below instead. 

151 util.get_apio_version_str(), 

152 # -- Param '*param_decls. The version option names. 

153 "-v", 

154 "--version", 

155 # -- Param 'message', the final string to display for apio --version. 

156 message=util.get_apio_version_message(), 

157) 

158def apio_top_cli(): 

159 """The top level command group of apio commands""" 

160 

161 # pass