Coverage for apio / commands / apio_build.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 build' command""" 

9 

10import sys 

11from typing import Optional 

12from pathlib import Path 

13import click 

14from apio.utils import cmd_util 

15from apio.managers.scons_manager import SConsManager 

16from apio.commands import options 

17from apio.common.proto.apio_pb2 import Verbosity 

18from apio.apio_context import ( 

19 ApioContext, 

20 PackagesPolicy, 

21 ProjectPolicy, 

22 RemoteConfigPolicy, 

23) 

24 

25# ------------ apio build 

26 

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

28APIO_BUILD_HELP = """ 

29The command 'apio build' processes the project’s synthesis source files and \ 

30generates a bitstream file, which can then be uploaded to your FPGA. 

31 

32Examples:[code] 

33 apio build # Typical usage 

34 apio build -e debug # Set the apio.ini env. 

35 apio build -v # Verbose info (all) 

36 apio build --verbose-synth # Verbose synthesis info 

37 apio build --verbose-pnr # Verbose place and route info[/code] 

38 

39NOTES: 

40* The files are sorted in a deterministic lexicographic order. 

41* The top module in apio.ini using the 'top-module' option. 

42* The build command ignores testbench files (*_tb.v, and *_tb.sv). 

43* It is unnecessary to run 'apio build' before 'apio upload'. 

44* To force a rebuild from scratch use the command 'apio clean' first. 

45* The '--gui' option launches a Yosys's experimental diagnostics tool. 

46""" 

47 

48gui_option = click.option( 

49 "nextpnr_gui", # Var name. 

50 "-g", 

51 "--gui", 

52 is_flag=True, 

53 help="Launch experimental nextpnr GUI.", 

54 cls=cmd_util.ApioOption, 

55) 

56 

57 

58@click.command( 

59 name="build", 

60 cls=cmd_util.ApioCommand, 

61 short_help="Synthesize the bitstream.", 

62 help=APIO_BUILD_HELP, 

63) 

64@click.pass_context 

65@options.env_option_gen() 

66@options.project_dir_option 

67@options.verbose_option 

68@options.verbose_synth_option 

69@options.verbose_pnr_option 

70@gui_option 

71def cli( 

72 _: click.Context, 

73 *, 

74 # Options 

75 env: Optional[str], 

76 project_dir: Optional[Path], 

77 verbose: bool, 

78 verbose_synth: bool, 

79 verbose_pnr: bool, 

80 nextpnr_gui: bool, 

81): 

82 """Implements the apio build command. It invokes the toolchain 

83 to synthesize the source files into a bitstream file. 

84 """ 

85 

86 # pylint: disable=too-many-arguments 

87 

88 # -- Create the apio context. 

89 apio_ctx = ApioContext( 

90 project_policy=ProjectPolicy.PROJECT_REQUIRED, 

91 remote_config_policy=RemoteConfigPolicy.CACHED_OK, 

92 packages_policy=PackagesPolicy.ENSURE_PACKAGES, 

93 project_dir_arg=project_dir, 

94 env_arg=env, 

95 ) 

96 

97 # -- Create the scons manager. 

98 scons = SConsManager(apio_ctx) 

99 

100 # -- Build the project with the given parameters 

101 exit_code = scons.build( 

102 nextpnr_gui, 

103 Verbosity(all=verbose, synth=verbose_synth, pnr=verbose_pnr), 

104 ) 

105 

106 # -- Done! 

107 sys.exit(exit_code)