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 pathlib import Path 

12import click 

13from apio.utils import cmd_util 

14from apio.managers.scons_manager import SConsManager 

15from apio.commands import options 

16from apio.common.proto.apio_scons_pb2 import Verbosity 

17from apio.apio_context import ( 

18 ApioContext, 

19 PackagesPolicy, 

20 ProjectPolicy, 

21 RemoteConfigPolicy, 

22) 

23 

24# ------------ apio build 

25 

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

27APIO_BUILD_HELP = """ 

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

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

30 

31Examples:[code] 

32 apio build # Typical usage 

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

34 apio build -v # Verbose info (all) 

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

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

37 

38NOTES: 

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

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

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

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

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

44""" 

45 

46 

47@click.command( 

48 name="build", 

49 cls=cmd_util.ApioCommand, 

50 short_help="Synthesize the bitstream.", 

51 help=APIO_BUILD_HELP, 

52) 

53@click.pass_context 

54@options.env_option_gen() 

55@options.project_dir_option 

56@options.verbose_option 

57@options.verbose_synth_option 

58@options.verbose_pnr_option 

59def cli( 

60 _: click.Context, 

61 *, 

62 # Options 

63 env: str | None, 

64 project_dir: Path | None, 

65 verbose: bool, 

66 verbose_synth: bool, 

67 verbose_pnr: bool, 

68): 

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

70 to synthesize the source files into a bitstream file. 

71 """ 

72 

73 # -- Create the apio context. 

74 apio_ctx = ApioContext( 

75 project_policy=ProjectPolicy.PROJECT_REQUIRED, 

76 remote_config_policy=RemoteConfigPolicy.CACHED_OK, 

77 packages_policy=PackagesPolicy.ENSURE_PACKAGES, 

78 project_dir_arg=project_dir, 

79 env_arg=env, 

80 ) 

81 

82 # -- Create the scons manager. 

83 scons = SConsManager(apio_ctx) 

84 

85 # -- Build the project with the given parameters 

86 exit_code = scons.build( 

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

88 ) 

89 

90 # -- Done! 

91 sys.exit(exit_code)