Coverage for apio/utils/env_options.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"""Functions for reading the APIO env options. This are system env 

10variables that are used to modify the default behavior of APIO. 

11""" 

12 

13import os 

14from apio.common.apio_console import fatal_error 

15 

16# -- Env variable to override the apio home dir ~/.apio. If specified, 

17# -- it contains the profile.json file and if APIO_PACKAGES is not 

18# -- specified, the 'packages' directory with the individual packages. 

19# -- This env variable is used in testing to have an isolated home for each 

20# -- test. 

21APIO_HOME = "APIO_HOME" 

22 

23# -- Env variable to override the apio packages dir <apio_home>/packages. 

24# -- it contains the apio packages loaded from github. If specified, the 

25# -- path must contain the strings 'apio' and 'packages' (case insensitive, 

26# -- order doesn't matter) and must not contain '..' for safety. This env 

27# -- variable used in testing to share cached downloaded packages across 

28# -- tests runs. 

29APIO_PACKAGES = "APIO_PACKAGES" 

30 

31# -- Env variable to override the platform id that is determined automatically 

32# -- from the system properties. If specified, the value should match one 

33# -- of the platforms specified in resources/platforms.json. 

34APIO_PLATFORM = "APIO_PLATFORM" 

35 

36# -- Env variable to enable printing of debug info, valid values are from 

37# -- 1 to 10 with 1 for minimal debug info and 10 for maximum. 

38# -- 

39# -- Do not access it directly, use debug_util.is_debug(n) instead. 

40APIO_DEBUG = "APIO_DEBUG" 

41 

42# -- An env variable that if defined, contains an override url of the remote 

43# -- config file defined in apio/resources/config.jsonc. During automated 

44# -- tests, it is overridden to point to the local copy of the remote config 

45# -- file. 

46# 

47# Examples: 

48# file:///projects/apio-dev/repo/remote-config 

49# https://github.com/zapta/apio_dev/raw/main/remote-config 

50# 

51APIO_REMOTE_CONFIG_URL = "APIO_REMOTE_CONFIG_URL" 

52 

53# -- Env variable to override the dir from which apio reads the boards.jsonc, 

54# -- fpgas.jsonc, and programmers.jsonc definition files. By default they are 

55# -- read from <packages dir>/definitions. For testing only, it's used to 

56# -- test changes to the apio-definitions repo without installing them. 

57# -- The examples are still read from the installed definitions package. 

58# 

59# Example: 

60# /projects/apio-definitions-dev/repo/definitions 

61# 

62APIO_DEFINITIONS = "APIO_DEFINITIONS" 

63 

64 

65# -- List of all supported env options. 

66_SUPPORTED_APIO_VARS = [ 

67 APIO_HOME, 

68 APIO_PACKAGES, 

69 APIO_PLATFORM, 

70 APIO_REMOTE_CONFIG_URL, 

71 APIO_DEFINITIONS, 

72 APIO_DEBUG, 

73] 

74 

75 

76def get(var_name: str, default: str | None = None): 

77 """Return the given APIO config env value or default if not found. 

78 var_name must be in _SUPPORTED_APIO_VARS. The returned 

79 value is not cached such that mutating the var in this program will 

80 affect the result of this function. 

81 """ 

82 

83 # -- Sanity check. To make sure we are aware of all the vars used. 

84 assert ( 

85 var_name in _SUPPORTED_APIO_VARS 

86 ), f"Unknown apio env var '{var_name}'" 

87 

88 # -- Get the value, None if not defined. 

89 var_value = os.getenv(var_name) 

90 

91 if var_value is None: 

92 # -- Var is undefined. Use default 

93 var_value = default 

94 else: 

95 # -- Var is defined. For windows benefit, remove optional quotes. 

96 if var_value.startswith('"') or var_value.endswith('"'): 

97 if ( 

98 len(var_value) < 2 

99 or not var_value.startswith('"') 

100 or not var_value.endswith('"') 

101 ): 

102 fatal_error( 

103 f"Env var {var_name} has unbalanced double quotes: " 

104 f"[{var_value}]" 

105 ) 

106 # -- Remove first and last chars. 

107 var_value = var_value[1:-1] 

108 

109 return var_value 

110 

111 

112def is_defined(var_name) -> bool: 

113 """Returns true if the env var is currently defined, regardless to its 

114 value, or False otherwise. var_name must be in _SUPPORTED_APIO_VARS. The 

115 returned value is not cached such that mutating the var in this program may 

116 affect the result of this function.""" 

117 # -- Sanity check. To make sure we are aware of all the vars used. 

118 assert ( 

119 var_name in _SUPPORTED_APIO_VARS 

120 ), f"Unknown apio env var '{var_name}'" 

121 

122 # -- Get the value, None if not defined. 

123 var_value = os.getenv(var_name) 

124 return var_value is not None 

125 

126 

127def get_defined() -> list[str]: 

128 """Return the list of apio env options vars in _SUPPORTED_APIO_VARS 

129 that are currently defined. The returned value is not cached such that 

130 mutating the var in this program may affect the result.""" 

131 result = [] 

132 for var in _SUPPORTED_APIO_VARS: 

133 if is_defined(var): 

134 result.append(var) 

135 return result 

136 

137 

138def get_all() -> list[str]: 

139 """Return the list of all of apio supported env vars.""" 

140 return _SUPPORTED_APIO_VARS.copy()