Coverage for apio/commands/apio_create.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"""Implementation of 'apio create' command""" 

10 

11from pathlib import Path 

12import click 

13from apio.common.apio_console import fatal_error 

14from apio.utils import util, cmd_util 

15from apio.commands import options 

16from apio.apio_context import ( 

17 ApioContext, 

18 PackagesPolicy, 

19 ProjectPolicy, 

20 RemoteConfigPolicy, 

21) 

22from apio.managers.project import ( 

23 DEFAULT_TOP_MODULE, 

24 create_project_file, 

25) 

26 

27 

28board_option = click.option( 

29 "board", # Var name. 

30 "-b", 

31 "--board", 

32 type=str, 

33 required=True, 

34 metavar="BOARD", 

35 help="Set the board.", 

36 cls=cmd_util.ApioOption, 

37) 

38 

39# -------------- apio create 

40 

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

42APIO_CREATE_HELP = """ 

43The command 'apio create' creates a new 'apio.ini' project file and is \ 

44typically used when setting up a new Apio project. 

45 

46Examples:[code] 

47 apio create --board alhambra-ii 

48 apio create --board alhambra-ii --top-module MyModule[/code] 

49 

50[b][NOTE][/b] This command only creates a new 'apio.ini' file, rather than a \ 

51complete and buildable project. To create complete projects, refer to the \ 

52'apio examples' command. 

53""" 

54 

55 

56@click.command( 

57 name="create", 

58 cls=cmd_util.ApioCommand, 

59 short_help="Create an apio.ini project file.", 

60 help=APIO_CREATE_HELP, 

61) 

62@click.pass_context 

63@board_option 

64@options.top_module_option_gen(short_help="Set the top level module name.") 

65@options.project_dir_option 

66def cli( 

67 _: click.Context, 

68 *, 

69 # Options 

70 board: str, 

71 top_module: str, 

72 project_dir: Path | None, 

73): 

74 """Create a project file.""" 

75 

76 # Board is annotated above as required so must exist. 

77 assert board is not None 

78 

79 if not top_module: 

80 top_module = DEFAULT_TOP_MODULE 

81 

82 # -- Create the apio context. 

83 apio_ctx = ApioContext( 

84 project_policy=ProjectPolicy.NO_PROJECT, 

85 remote_config_policy=RemoteConfigPolicy.CACHED_OK, 

86 packages_policy=PackagesPolicy.ENSURE_PACKAGES, 

87 ) 

88 assert apio_ctx.definitions is not None 

89 

90 # -- Make sure the board exist. 

91 if board not in apio_ctx.definitions.boards: 

92 fatal_error(f"Unknown board id '{board}'.") 

93 

94 # -- Determine the new project directory. Create if needed. 

95 project_dir_new: Path = util.user_directory_or_cwd( 

96 project_dir, description="Project", create_if_missing=True 

97 ) 

98 

99 # Create the apio.ini file. It exists with an error status if any error. 

100 create_project_file( 

101 project_dir_new, 

102 board, 

103 top_module, 

104 )