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

1# -*- coding: utf-8 -*- 

2# -- This file is part of the Apio project 

3# -- (C) 2016-2024 FPGAwars 

4# -- Authors 

5# -- * Jesús Arroyo (2016-2019) 

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

7# -- License GPLv2 

8"""Implementation of 'apio create' command""" 

9 

10from pathlib import Path 

11import click 

12from apio.common.apio_console import fatal_error 

13from apio.utils import util, cmd_util 

14from apio.commands import options 

15from apio.apio_context import ( 

16 ApioContext, 

17 PackagesPolicy, 

18 ProjectPolicy, 

19 RemoteConfigPolicy, 

20) 

21from apio.managers.project import ( 

22 DEFAULT_TOP_MODULE, 

23 create_project_file, 

24) 

25 

26 

27board_option = click.option( 

28 "board", # Var name. 

29 "-b", 

30 "--board", 

31 type=str, 

32 required=True, 

33 metavar="BOARD", 

34 help="Set the board.", 

35 cls=cmd_util.ApioOption, 

36) 

37 

38# -------------- apio create 

39 

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

41APIO_CREATE_HELP = """ 

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

43typically used when setting up a new Apio project. 

44 

45Examples:[code] 

46 apio create --board alhambra-ii 

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

48 

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

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

51'apio examples' command. 

52""" 

53 

54 

55@click.command( 

56 name="create", 

57 cls=cmd_util.ApioCommand, 

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

59 help=APIO_CREATE_HELP, 

60) 

61@click.pass_context 

62@board_option 

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

64@options.project_dir_option 

65def cli( 

66 _: click.Context, 

67 *, 

68 # Options 

69 board: str, 

70 top_module: str, 

71 project_dir: Path | None, 

72): 

73 """Create a project file.""" 

74 

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

76 assert board is not None 

77 

78 if not top_module: 

79 top_module = DEFAULT_TOP_MODULE 

80 

81 # -- Create the apio context. 

82 apio_ctx = ApioContext( 

83 project_policy=ProjectPolicy.NO_PROJECT, 

84 remote_config_policy=RemoteConfigPolicy.CACHED_OK, 

85 packages_policy=PackagesPolicy.ENSURE_PACKAGES, 

86 ) 

87 assert apio_ctx.definitions is not None 

88 

89 # -- Make sure the board exist. 

90 if board not in apio_ctx.definitions.boards: 

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

92 

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

94 project_dir_new: Path = util.user_directory_or_cwd( 

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

96 ) 

97 

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

99 create_project_file( 

100 project_dir_new, 

101 board, 

102 top_module, 

103 )