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

10 

11import sys 

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.stubs.apio_scons_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""" 

46 

47 

48@click.command( 

49 name="build", 

50 cls=cmd_util.ApioCommand, 

51 short_help="Synthesize the bitstream.", 

52 help=APIO_BUILD_HELP, 

53) 

54@click.pass_context 

55@options.env_option_gen() 

56@options.project_dir_option 

57@options.verbose_option 

58@options.verbose_synth_option 

59@options.verbose_pnr_option 

60def cli( 

61 _: click.Context, 

62 *, 

63 # Options 

64 env: str | None, 

65 project_dir: Path | None, 

66 verbose: bool, 

67 verbose_synth: bool, 

68 verbose_pnr: bool, 

69): 

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

71 to synthesize the source files into a bitstream file. 

72 """ 

73 

74 # -- Create the apio context. 

75 apio_ctx = ApioContext( 

76 project_policy=ProjectPolicy.PROJECT_REQUIRED, 

77 remote_config_policy=RemoteConfigPolicy.CACHED_OK, 

78 packages_policy=PackagesPolicy.ENSURE_PACKAGES, 

79 project_dir_arg=project_dir, 

80 env_arg=env, 

81 ) 

82 

83 # -- Create the scons manager. 

84 scons = SConsManager(apio_ctx) 

85 

86 # -- Build the project with the given parameters 

87 exit_code = scons.build( 

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

89 ) 

90 

91 # -- Done! 

92 sys.exit(exit_code)