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 

10import sys 

11from typing import Optional 

12from pathlib import Path 

13import click 

14from apio.common.apio_console import cerror 

15from apio.utils import util, cmd_util 

16from apio.commands import options 

17from apio.apio_context import ( 

18 ApioContext, 

19 PackagesPolicy, 

20 ProjectPolicy, 

21 RemoteConfigPolicy, 

22) 

23from apio.managers.project import ( 

24 DEFAULT_TOP_MODULE, 

25 create_project_file, 

26) 

27 

28 

29board_option = click.option( 

30 "board", # Var name. 

31 "-b", 

32 "--board", 

33 type=str, 

34 required=True, 

35 metavar="BOARD", 

36 help="Set the board.", 

37 cls=cmd_util.ApioOption, 

38) 

39 

40# -------------- apio create 

41 

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

43APIO_CREATE_HELP = """ 

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

45typically used when setting up a new Apio project. 

46 

47Examples:[code] 

48 apio create --board alhambra-ii 

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

50 

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

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

53'apio examples' command. 

54""" 

55 

56 

57@click.command( 

58 name="create", 

59 cls=cmd_util.ApioCommand, 

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

61 help=APIO_CREATE_HELP, 

62) 

63@click.pass_context 

64@board_option 

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

66@options.project_dir_option 

67def cli( 

68 _: click.Context, 

69 # Options 

70 board: str, 

71 top_module: str, 

72 project_dir: Optional[Path], 

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 

89 # -- Make sure the board exist. 

90 if board not in apio_ctx.boards: 

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

92 sys.exit(1) 

93 

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

95 project_dir: 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, 

102 board, 

103 top_module, 

104 )