Coverage for apio/commands/options.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"""Common apio command options""" 

10 

11from pathlib import Path 

12import click 

13from apio.utils import cmd_util 

14 

15 

16# The design is based on the idea here https://stackoverflow.com/a/77732441. 

17# It contains shared command line options in two forms, dynamic option 

18# which can be customized for specific use cases and fixed static options 

19# with fixed attributes. Options that are too specific to a single command 

20# not not listed here and defined instead in the command itself. 

21# Both type of options are listed in an alphabetical order. 

22 

23 

24# ---------------------------------- 

25# -- Customizable option generators 

26# ---------------------------------- 

27 

28 

29def env_option_gen(*, short_help: str = "Set the apio.ini env."): 

30 """Generate an --env option with given help text.""" 

31 

32 return click.option( 

33 "env", # Var name. 

34 "-e", 

35 "--env", 

36 type=str, 

37 default=None, 

38 metavar="name", 

39 help=short_help, 

40 cls=cmd_util.ApioOption, 

41 ) 

42 

43 

44def force_option_gen(*, short_help: str): 

45 """Generate a --force option with given help text.""" 

46 

47 return click.option( 

48 "force", # Var name 

49 "-f", 

50 "--force", 

51 is_flag=True, 

52 help=short_help, 

53 cls=cmd_util.ApioOption, 

54 ) 

55 

56 

57def list_option_gen(*, short_help: str): 

58 """Generate a --list option with given help text.""" 

59 

60 return click.option( 

61 "list_", # Var name. Deconflicting from python builtin 'list'. 

62 "-l", 

63 "--list", 

64 is_flag=True, 

65 help=short_help, 

66 cls=cmd_util.ApioOption, 

67 ) 

68 

69 

70def top_module_option_gen( 

71 *, 

72 short_help: str = "Set the top level module name.", 

73): 

74 """Generate a --top-module option with given help text.""" 

75 

76 return click.option( 

77 "top_module", # Var name. 

78 "-t", 

79 "--top-module", 

80 type=str, 

81 metavar="name", 

82 # deprecated=deprecated, 

83 help=short_help, 

84 cls=cmd_util.ApioOption, 

85 ) 

86 

87 

88def dst_option_gen(*, short_help: str): 

89 """Generate a --dst option with given help text.""" 

90 

91 dst_option = click.option( 

92 "dst", # Var name. 

93 "-d", 

94 "--dst", 

95 type=Path, 

96 metavar="path", 

97 help=short_help, 

98 cls=cmd_util.ApioOption, 

99 ) 

100 

101 return dst_option 

102 

103 

104# --------------------------- 

105# -- Static options 

106# --------------------------- 

107 

108docs_format_option = click.option( 

109 "docs", # Var name. 

110 "-d", 

111 "--docs", 

112 is_flag=True, 

113 help="Format for Apio Docs.", 

114 cls=cmd_util.ApioOption, 

115) 

116 

117project_dir_option = click.option( 

118 "project_dir", # Var name. 

119 "-p", 

120 "--project-dir", 

121 type=Path, 

122 metavar="path", 

123 help="Set the root directory for the project.", 

124 cls=cmd_util.ApioOption, 

125) 

126 

127 

128verbose_option = click.option( 

129 "verbose", # Var name. 

130 "-v", 

131 "--verbose", 

132 is_flag=True, 

133 help="Show detailed output.", 

134 cls=cmd_util.ApioOption, 

135) 

136 

137 

138verbose_pnr_option = click.option( 

139 "verbose_pnr", # Var name. 

140 "--verbose-pnr", 

141 is_flag=True, 

142 help="Show detailed pnr stage output.", 

143 cls=cmd_util.ApioOption, 

144) 

145 

146 

147verbose_synth_option = click.option( 

148 "verbose_synth", # Var name. 

149 "--verbose-synth", 

150 is_flag=True, 

151 help="Show detailed synth stage output.", 

152 cls=cmd_util.ApioOption, 

153)