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 *, 

70 # Options 

71 board: str, 

72 top_module: str, 

73 project_dir: Optional[Path], 

74): 

75 """Create a project file.""" 

76 

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

78 assert board is not None 

79 

80 if not top_module: 

81 top_module = DEFAULT_TOP_MODULE 

82 

83 # -- Create the apio context. 

84 apio_ctx = ApioContext( 

85 project_policy=ProjectPolicy.NO_PROJECT, 

86 remote_config_policy=RemoteConfigPolicy.CACHED_OK, 

87 packages_policy=PackagesPolicy.ENSURE_PACKAGES, 

88 ) 

89 

90 # -- Make sure the board exist. 

91 if board not in apio_ctx.boards: 

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

93 sys.exit(1) 

94 

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

96 project_dir: Path = util.user_directory_or_cwd( 

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

98 ) 

99 

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

101 create_project_file( 

102 project_dir, 

103 board, 

104 top_module, 

105 )