def setup(self, init_logging=True):
"""Initializes logging, loads backends/plugins and parses options.
:param bool init_logging: Whether or not to initialize logging as part of setup.
:returns: A tuple of (options, build_configuration).
"""
global_bootstrap_options = self._options_bootstrapper.get_bootstrap_options().for_global_scope()
if global_bootstrap_options.pants_version != pants_version():
raise BuildConfigurationError(
'Version mismatch: Requested version was {}, our version is {}.'
.format(global_bootstrap_options.pants_version, pants_version())
)
# Get logging setup prior to loading backends so that they can log as needed.
if init_logging:
self._setup_logging(global_bootstrap_options.quiet,
global_bootstrap_options.level,
global_bootstrap_options.logdir)
# Conditionally load backends/plugins and materialize a `BuildConfiguration` object.
if not self._has_build_configuration():
build_configuration = self._load_plugins(self._working_set,
global_bootstrap_options.pythonpath,
global_bootstrap_options.plugins,
global_bootstrap_options.backend_packages)
self._set_build_configuration(build_configuration)
else:
build_configuration = self._get_build_configuration()
# Parse and register options.
options = self._install_options(self._options_bootstrapper, build_configuration)
return options, build_configuration
def create(cls, options_bootstrapper, build_configuration, init_subsystems=True):
global_bootstrap_options = options_bootstrapper.get_bootstrap_options().for_global_scope()
if global_bootstrap_options.pants_version != pants_version():
raise BuildConfigurationError(
'Version mismatch: Requested version was {}, our version is {}.'
.format(global_bootstrap_options.pants_version, pants_version())
)
pants_runtime_python_version = global_bootstrap_options.pants_runtime_python_version
current_python_version = '.'.join(map(str, sys.version_info[0:2]))
if pants_runtime_python_version and pants_runtime_python_version != current_python_version:
raise BuildConfigurationError(
'Running Pants with a different Python interpreter version than requested. '
'You requested {}, but are running with {}.\n\n'
'Note that Pants cannot use the value you give for `--pants-runtime-python-version` to '
'dynamically change the interpreter it uses, as it is too late for it to change once the program '
'is already running. Instead, your setup script (e.g. `./pants`) must configure which Python '
'interpreter and virtualenv to use. For example, the setup script we distribute '
'at https://www.pantsbuild.org/install.html#recommended-installation will read the '
'`pants_runtime_python_version` defined in your pants.ini to determine which Python '
'version to run with.'.format(pants_runtime_python_version, current_python_version)
)
# Parse and register options.
options = cls._construct_options(options_bootstrapper, build_configuration)
GlobalOptionsRegistrar.validate_instance(options.for_global_scope())
if init_subsystems:
Subsystem.set_options(options)
return options
def create(cls, options_bootstrapper, build_configuration, init_subsystems=True):
global_bootstrap_options = options_bootstrapper.get_bootstrap_options().for_global_scope()
if global_bootstrap_options.pants_version != pants_version():
raise BuildConfigurationError(
'Version mismatch: Requested version was {}, our version is {}.'
.format(global_bootstrap_options.pants_version, pants_version())
)
pants_runtime_python_version = global_bootstrap_options.pants_runtime_python_version
current_python_version = '.'.join(map(str, sys.version_info[0:2]))
if pants_runtime_python_version and pants_runtime_python_version != current_python_version:
raise BuildConfigurationError(
'Running Pants with a different Python interpreter version than requested. '
'You requested {}, but are running with {}.\n\n'
'Note that Pants cannot use the value you give for `--pants-runtime-python-version` to '
'dynamically change the interpreter it uses, as it is too late for it to change once the program '
'is already running. Instead, your setup script (e.g. `./pants`) must configure which Python '
'interpreter and virtualenv to use. For example, the setup script we distribute '
'at https://www.pantsbuild.org/install.html#recommended-installation will read the '
'`pants_runtime_python_version` defined in your pants.ini to determine which Python '
'version to run with.'.format(pants_runtime_python_version, current_python_version)
)
# Parse and register options.
options = cls._construct_options(options_bootstrapper, build_configuration)
GlobalOptionsRegistrar.validate_instance(options.for_global_scope())
if init_subsystems:
Subsystem.set_options(options)
return options
def setup(self, init_logging=True):
"""Initializes logging, loads backends/plugins and parses options.
:param bool init_logging: Whether or not to initialize logging as part of setup.
:returns: A tuple of (options, build_configuration).
"""
global_bootstrap_options = self._options_bootstrapper.get_bootstrap_options().for_global_scope()
if global_bootstrap_options.pants_version != pants_version():
raise BuildConfigurationError(
'Version mismatch: Requested version was {}, our version is {}.'
.format(global_bootstrap_options.pants_version, pants_version())
)
# Get logging setup prior to loading backends so that they can log as needed.
if init_logging:
self._setup_logging(global_bootstrap_options.quiet,
global_bootstrap_options.level,
global_bootstrap_options.logdir)
# Conditionally load backends/plugins and materialize a `BuildConfiguration` object.
if not self._has_build_configuration():
missing = (set(global_bootstrap_options.default_backend_packages).difference(
global_bootstrap_options.backend_packages))
deprecated_conditional(
lambda: len(missing) > 0,
'1.3.0',
'default_backend_packages option',
'You are relying on the following backends being listed in the deprecated '
'default_backend_packages option: {}.\n '
'This is probably because you are overwriting the value of the backend_packages option '
'in your pants.ini, instead of appending to it.\n To get rid of this message, consider '
'changing backend_packages: [...] to backend_packages: +[...] in your pants.ini. '
'Once you are happy with the state of your backend_packages option, you can set '
'default_backend_packages to [] to silence this warning.'.format(
', '.join(missing))
)
backends = (global_bootstrap_options.default_backend_packages +
global_bootstrap_options.backend_packages)
build_configuration = self._load_plugins(self._working_set,
global_bootstrap_options.pythonpath,
global_bootstrap_options.plugins,
backends)
self._set_build_configuration(build_configuration)
else:
build_configuration = self._get_build_configuration()
# Parse and register options.
options = self._install_options(self._options_bootstrapper, build_configuration)
return options, build_configuration
def setup(self, init_logging=True):
"""Initializes logging, loads backends/plugins and parses options.
:param bool init_logging: Whether or not to initialize logging as part of setup.
:returns: A tuple of (options, build_configuration).
"""
global_bootstrap_options = self._options_bootstrapper.get_bootstrap_options(
).for_global_scope()
if global_bootstrap_options.pants_version != pants_version():
raise BuildConfigurationError(
'Version mismatch: Requested version was {}, our version is {}.'
.format(global_bootstrap_options.pants_version,
pants_version()))
# Get logging setup prior to loading backends so that they can log as needed.
if init_logging:
self._setup_logging(global_bootstrap_options.quiet,
global_bootstrap_options.level,
global_bootstrap_options.logdir)
# Conditionally load backends/plugins and materialize a `BuildConfiguration` object.
if not self._has_build_configuration():
missing = (set(
global_bootstrap_options.default_backend_packages).difference(
global_bootstrap_options.backend_packages))
deprecated_conditional(
lambda: len(missing) > 0, '1.3.0',
'default_backend_packages option',
'You are relying on the following backends being listed in the deprecated '
'default_backend_packages option: {}.\n '
'This is probably because you are overwriting the value of the backend_packages option '
'in your pants.ini, instead of appending to it.\n To get rid of this message, consider '
'changing backend_packages: [...] to backend_packages: +[...] in your pants.ini. '
'Once you are happy with the state of your backend_packages option, you can set '
'default_backend_packages to [] to silence this warning.'.
format(', '.join(missing)))
backends = (global_bootstrap_options.default_backend_packages +
global_bootstrap_options.backend_packages)
build_configuration = self._load_plugins(
self._working_set, global_bootstrap_options.pythonpath,
global_bootstrap_options.plugins, backends)
self._set_build_configuration(build_configuration)
else:
build_configuration = self._get_build_configuration()
# Parse and register options.
options = self._install_options(self._options_bootstrapper,
build_configuration)
return options, build_configuration
def _setup_options(self, options_bootstrapper, working_set):
# TODO: This inline import is currently necessary to resolve a ~legitimate cycle between
# `GoalRunner`->`EngineInitializer`->`OptionsInitializer`->`GoalRunner`.
from pants.bin.goal_runner import GoalRunner
bootstrap_options = options_bootstrapper.get_bootstrap_options()
global_bootstrap_options = bootstrap_options.for_global_scope()
if global_bootstrap_options.pants_version != pants_version():
raise BuildConfigurationError(
'Version mismatch: Requested version was {}, our version is {}.'.format(
global_bootstrap_options.pants_version, pants_version()
)
)
# Get logging setup prior to loading backends so that they can log as needed.
if self._init_logging:
self._setup_logging(global_bootstrap_options)
# Add any extra paths to python path (e.g., for loading extra source backends).
for path in global_bootstrap_options.pythonpath:
sys.path.append(path)
pkg_resources.fixup_namespace_packages(path)
# Load plugins and backends.
plugins = global_bootstrap_options.plugins
backend_packages = global_bootstrap_options.backend_packages
build_configuration = load_plugins_and_backends(plugins, working_set, backend_packages)
# Now that plugins and backends are loaded, we can gather the known scopes.
known_scope_infos = [GlobalOptionsRegistrar.get_scope_info()]
# Add scopes for all needed subsystems via a union of all known subsystem sets.
subsystems = Subsystem.closure(
GoalRunner.subsystems() | Goal.subsystems() | build_configuration.subsystems()
)
for subsystem in subsystems:
known_scope_infos.append(subsystem.get_scope_info())
# Add scopes for all tasks in all goals.
for goal in Goal.all():
known_scope_infos.extend(filter(None, goal.known_scope_infos()))
# Now that we have the known scopes we can get the full options.
options = options_bootstrapper.get_full_options(known_scope_infos)
self._register_options(subsystems, options)
# Make the options values available to all subsystems.
Subsystem.set_options(options)
return options, build_configuration
def _setup_options(self, options_bootstrapper, working_set):
# TODO: This inline import is currently necessary to resolve a ~legitimate cycle between
# `GoalRunner`->`EngineInitializer`->`OptionsInitializer`->`GoalRunner`.
from pants.bin.goal_runner import GoalRunner
bootstrap_options = options_bootstrapper.get_bootstrap_options()
global_bootstrap_options = bootstrap_options.for_global_scope()
if global_bootstrap_options.pants_version != pants_version():
raise BuildConfigurationError(
'Version mismatch: Requested version was {}, our version is {}.'
.format(global_bootstrap_options.pants_version,
pants_version()))
# Get logging setup prior to loading backends so that they can log as needed.
if self._init_logging:
self._setup_logging(global_bootstrap_options)
# Add any extra paths to python path (e.g., for loading extra source backends).
for path in global_bootstrap_options.pythonpath:
sys.path.append(path)
pkg_resources.fixup_namespace_packages(path)
# Load plugins and backends.
plugins = global_bootstrap_options.plugins
backend_packages = global_bootstrap_options.backend_packages
build_configuration = load_backends_and_plugins(
plugins, working_set, backend_packages)
# Now that plugins and backends are loaded, we can gather the known scopes.
known_scope_infos = [GlobalOptionsRegistrar.get_scope_info()]
# Add scopes for all needed subsystems via a union of all known subsystem sets.
subsystems = Subsystem.closure(GoalRunner.subsystems()
| Goal.subsystems()
| build_configuration.subsystems())
for subsystem in subsystems:
known_scope_infos.append(subsystem.get_scope_info())
# Add scopes for all tasks in all goals.
for goal in Goal.all():
known_scope_infos.extend(filter(None, goal.known_scope_infos()))
# Now that we have the known scopes we can get the full options.
options = options_bootstrapper.get_full_options(known_scope_infos)
self._register_options(subsystems, options)
# Make the options values available to all subsystems.
Subsystem.set_options(options)
return options, build_configuration
def print_help(self) -> Literal[0, 1]:
"""Print help to the console."""
def print_hint() -> None:
print(f"Use `{self.maybe_green(self._bin_name + ' help')}` to get help.")
print(f"Use `{self.maybe_green(self._bin_name + ' help goals')}` to list goals.")
if isinstance(self._help_request, VersionHelp):
print(pants_version())
elif isinstance(self._help_request, AllHelp):
self._print_all_help()
elif isinstance(self._help_request, ThingHelp):
self._print_thing_help()
elif isinstance(self._help_request, UnknownGoalHelp):
# Only print help and suggestions for the first unknown goal.
# It gets confusing to try and show suggestions for multiple cases.
unknown_goal = self._help_request.unknown_goals[0]
print(f"Unknown goal: {self.maybe_red(unknown_goal)}")
did_you_mean = list(
difflib.get_close_matches(
unknown_goal, self._all_help_info.name_to_goal_info.keys()
)
)
if did_you_mean:
print(f"Did you mean: {', '.join(self.maybe_cyan(g) for g in did_you_mean)}?")
print_hint()
return 1
elif isinstance(self._help_request, NoGoalHelp):
print("No goals specified.")
print_hint()
return 1
return 0
def print_help(self) -> Literal[0, 1]:
"""Print help to the console."""
def print_hint() -> None:
print(
f"Use `{self.maybe_green(bin_name() + ' help')}` to get help.")
print(
f"Use `{self.maybe_green(bin_name() + ' help goals')}` to list goals."
)
if isinstance(self._help_request, VersionHelp):
print(pants_version())
return 0
elif isinstance(self._help_request, AllHelp):
self._print_all_help()
return 0
elif isinstance(self._help_request, ThingHelp):
return self._print_thing_help()
elif isinstance(self._help_request, UnknownGoalHelp):
# Only print help and suggestions for the first unknown goal.
# It gets confusing to try and show suggestions for multiple cases.
unknown_goal = self._help_request.unknown_goals[0]
print(f"Unknown goal: {self.maybe_red(unknown_goal)}")
self._print_alternatives(
unknown_goal, self._all_help_info.name_to_goal_info.keys())
print_hint()
return 1
elif isinstance(self._help_request, NoGoalHelp):
print("No goals specified.")
print_hint()
return 1
else:
# Unexpected.
return 1
def create(cls, options_bootstrapper, build_configuration, init_subsystems=True):
global_bootstrap_options = options_bootstrapper.get_bootstrap_options().for_global_scope()
if global_bootstrap_options.pants_version != pants_version():
raise BuildConfigurationError(
'Version mismatch: Requested version was {}, our version is {}.'
.format(global_bootstrap_options.pants_version, pants_version())
)
# Parse and register options.
options = cls._construct_options(options_bootstrapper, build_configuration)
if init_subsystems:
Subsystem.set_options(options)
return options
def assert_pants_requirement(self,
python_requirement_library,
expected_dist='pantsbuild.pants'):
self.assertIsInstance(python_requirement_library,
PythonRequirementLibrary)
expected = PythonRequirement('{key}=={version}'.format(
key=expected_dist, version=pants_version()))
def key(python_requirement):
return (python_requirement.requirement.key,
python_requirement.requirement.specs,
python_requirement.requirement.extras)
self.assertEqual([key(expected)], [
key(pr) for pr in python_requirement_library.payload.requirements
])
req = list(python_requirement_library.payload.requirements)[0]
self.assertIsNotNone(req.requirement.marker)
self.assertTrue(
req.requirement.marker.evaluate(),
'pants_requirement() should always work in the current test environment'
)
self.assertFalse(
req.requirement.marker.evaluate({'python_version': '3.5'}))
self.assertFalse(
req.requirement.marker.evaluate({'python_version': '2.6'}))
self.assertTrue(
req.requirement.marker.evaluate({'python_version': '2.7'}))
def __call__(self, name=None, dist=None):
"""
:param string name: The name to use for the target, defaults to the dist name if specified and
otherwise the parent dir name.
:param string dist: The pants dist to create a requirement for. This must be a
'pantsbuild.pants*' distribution; eg:
'pantsbuild.pants.contrib.python.checks'.
"""
name = name or dist or os.path.basename(self._parse_context.rel_path)
dist = dist or 'pantsbuild.pants'
if not (dist == 'pantsbuild.pants'
or dist.startswith('pantsbuild.pants.')):
target = Address(spec_path=self._parse_context.rel_path,
target_name=name)
raise TargetDefinitionException(
target=target,
msg='The {} target only works for pantsbuild.pants '
'distributions, given {}'.format(self.alias, dist))
# TODO(John Sirois): Modify to constraint to >=3.5,<4 as part of
# https://github.com/pantsbuild/pants/issues/6062
env_marker = "python_version>='2.7' and python_version<'3'"
requirement = PythonRequirement(
requirement="{key}=={version} ; {env_marker}".format(
key=dist, version=pants_version(), env_marker=env_marker))
self._parse_context.create_object('python_requirement_library',
name=name,
requirements=[requirement])
def print_help(self):
"""Print help to the console.
:return: 0 on success, 1 on failure
"""
def print_hint():
print(f'Use `{self.bin_name} goals` to list goals.')
print(f'Use `{self.bin_name} help` to get help.')
if isinstance(self._help_request, VersionHelp):
print(pants_version())
elif isinstance(self._help_request, OptionsHelp):
self._print_options_help()
elif isinstance(self._help_request, GoalsHelp):
self._print_goals_help()
elif isinstance(self._help_request, UnknownGoalHelp):
print('Unknown goals: {}'.format(', '.join(
self._help_request.unknown_goals)))
print_hint()
return 1
elif isinstance(self._help_request, NoGoalHelp):
print('No goals specified.')
print_hint()
return 1
return 0
def __call__(self, name=None):
"""
:param string name: The name to use for the target, defaults to the parent dir name.
"""
name = name or os.path.basename(self._parse_context.rel_path)
requirement = PythonRequirement(requirement="pantsbuild.pants=={}".format(pants_version()))
self._parse_context.create_object(PythonRequirementLibrary, name=name, requirements=[requirement])
def assert_pants_requirement(self,
python_requirement_library,
expected_dist='pantsbuild.pants'):
self.assertIsInstance(python_requirement_library,
PythonRequirementLibrary)
expected = PythonRequirement('{key}=={version}'.format(
key=expected_dist, version=pants_version()))
def key(python_requirement):
return (python_requirement.requirement.key,
python_requirement.requirement.specs,
python_requirement.requirement.extras)
self.assertEqual([key(expected)], [
key(pr) for pr in python_requirement_library.payload.requirements
])
req = list(python_requirement_library.payload.requirements)[0]
self.assertIsNotNone(req.requirement.marker)
def evaluate_version(version):
return req.requirement.marker.evaluate({'python_version': version})
self.assertTrue(evaluate_version('2.7'))
self.assertFalse(
all(
evaluate_version(v)
for v in ('2.6', '3.4', '3.5', '3.6', '3.7')))
def __call__(self, name=None, dist=None):
"""
:param string name: The name to use for the target, defaults to the dist name if specified and
otherwise the parent dir name.
:param string dist: The pants dist to create a requirement for. This must be a
'pantsbuild.pants*' distribution; eg:
'pantsbuild.pants.contrib.python.checks'.
"""
name = name or dist or os.path.basename(self._parse_context.rel_path)
dist = dist or "pantsbuild.pants"
if not (dist == "pantsbuild.pants"
or dist.startswith("pantsbuild.pants.")):
target = Address(spec_path=self._parse_context.rel_path,
target_name=name)
raise TargetDefinitionException(
target=target,
msg="The {} target only works for pantsbuild.pants "
"distributions, given {}".format(self.alias, dist),
)
requirement = PythonRequirement(requirement="{key}=={version}".format(
key=dist, version=pants_version()))
self._parse_context.create_object("python_requirement_library",
name=name,
requirements=[requirement])
def _run(exiter):
# Place the registration of the unhandled exception hook as early as possible in the code.
sys.excepthook = exiter.unhandled_exception_hook
# We want to present warnings to the user, set this up early to ensure all warnings are seen.
# The "default" action displays a warning for a particular file and line number exactly once.
# See https://docs.python.org/2/library/warnings.html#the-warnings-filter for the complete action
# list.
warnings.simplefilter("default")
# The GoalRunner will setup final logging below in `.setup()`, but span the gap until then.
logging.basicConfig()
# This routes the warnings we enabled above through our loggers instead of straight to stderr raw.
logging.captureWarnings(True)
version = pants_version()
if len(sys.argv) == 2 and sys.argv[1] == _VERSION_OPTION:
exiter.do_exit(msg=version, out=sys.stdout)
root_dir = get_buildroot()
if not os.path.exists(root_dir):
exiter.exit_and_fail('PANTS_BUILD_ROOT does not point to a valid path: %s' % root_dir)
goal_runner = GoalRunner(root_dir)
goal_runner.setup()
result = goal_runner.run()
exiter.do_exit(result)
def __call__(self, name=None):
"""
:param string name: The name to use for the target, defaults to the parent dir name.
"""
name = name or os.path.basename(self._parse_context.rel_path)
requirement = PythonRequirement(requirement='pantsbuild.pants=={}'.format(pants_version()))
self._parse_context.create_object(PythonRequirementLibrary, name=name,
requirements=[requirement])
def assert_pants_requirement(self, python_requirement_library):
self.assertIsInstance(python_requirement_library,
PythonRequirementLibrary)
pants_requirement = PythonRequirement('pantsbuild.pants=={}'.format(
pants_version()))
self.assertEqual(
[pants_requirement.requirement],
list(pr.requirement
for pr in python_requirement_library.payload.requirements))
def create(cls, options_bootstrapper, build_configuration, init_subsystems=True):
global_bootstrap_options = options_bootstrapper.get_bootstrap_options().for_global_scope()
if global_bootstrap_options.pants_version != pants_version():
raise BuildConfigurationError(
'Version mismatch: Requested version was {}, our version is {}.'
.format(global_bootstrap_options.pants_version, pants_version())
)
# Parse and register options.
options = cls._construct_options(options_bootstrapper, build_configuration)
GlobalOptionsRegistrar.validate_instance(options.for_global_scope())
if init_subsystems:
Subsystem.set_options(options)
return options
def print_help_if_requested(self):
"""If help was requested, print it and return True.
Otherwise return False.
"""
if self._help_request:
if self._help_request.version:
print(pants_version())
else:
self._print_help()
return True
else:
return False
def print_help_if_requested(self):
"""If help was requested, print it and return True.
Otherwise return False.
"""
if self._help_request:
if self._help_request.version:
print(pants_version())
else:
self._print_help()
return True
else:
return False
def unstable_pants_version(self):
stable_version = pants_version()
unstable_version = b'{}+{}'.format(stable_version, uuid.uuid4().hex)
version_dir = os.path.join(get_buildroot(), 'src/python/pants')
with self.file_renamed(version_dir, 'VERSION', 'VERSION.orig'):
with open(os.path.join(version_dir, 'VERSION'), 'wb') as fp:
fp.write(unstable_version)
pants_run = self.run_pants(['--version'])
self.assert_success(pants_run)
self.assertEqual(unstable_version, pants_run.stdout_data.strip())
yield
def _unstable_pants_version(self):
stable_version = pants_version()
unstable_version = b'{}+{}'.format(stable_version, uuid.uuid4().hex)
version_dir = os.path.join(get_buildroot(), 'src/python/pants')
with self.file_renamed(version_dir, 'VERSION', 'VERSION.orig'):
with open(os.path.join(version_dir, 'VERSION'), 'wb') as fp:
fp.write(unstable_version)
pants_run = self.run_pants(['--version'])
self.assert_success(pants_run)
self.assertEqual(unstable_version, pants_run.stdout_data.strip())
yield
def pants_requirement(parse_context, name=None):
"""Exports a `python_requirement_library` pointing at the active pants' corresponding sdist.
This requirement is useful for custom plugin authors who want to build and test their plugin with
pants itself. Using the resulting target as a dependency of their plugin target ensures the
dependency stays true to the surrounding repo's version of pants.
NB: The requirement generated is for official pants releases on pypi; so may not be appropriate
for use in a repo that tracks `pantsbuild/pants` or otherwise uses custom pants sdists.
:param string name: The name to use for the target, defaults to the parent dir name.
"""
name = name or os.path.basename(parse_context.rel_path)
requirement = PythonRequirement(requirement='pantsbuild.pants=={}'.format(pants_version()))
parse_context.create_object(PythonRequirementLibrary, name=name, requirements=[requirement])
def assert_pants_requirement(self,
python_requirement_library,
expected_dist='pantsbuild.pants'):
self.assertIsInstance(python_requirement_library,
PythonRequirementLibrary)
expected = PythonRequirement('{key}=={version}'.format(
key=expected_dist, version=pants_version()))
def key(python_requirement):
return (python_requirement.requirement.key,
python_requirement.requirement.specs,
python_requirement.requirement.extras)
self.assertEqual([key(expected)], [
key(pr) for pr in python_requirement_library.payload.requirements
])
def print_help(self):
"""Print help to the console."""
def print_hint():
print('Use `pants goals` to list goals.')
print('Use `pants help` to get help.')
if isinstance(self._help_request, VersionHelp):
print(pants_version())
elif isinstance(self._help_request, OptionsHelp):
self._print_options_help()
elif isinstance(self._help_request, UnknownGoalHelp):
print('Unknown goals: {}'.format(', '.join(self._help_request.unknown_goals)))
print_hint()
# TODO: Should probably cause a non-zero exit code.
elif isinstance(self._help_request, NoGoalHelp):
print('No goals specified.')
print_hint()
def _run(exiter):
# Place the registration of the unhandled exception hook as early as possible in the code.
sys.excepthook = exiter.unhandled_exception_hook
logging.basicConfig()
version = pants_version()
if len(sys.argv) == 2 and sys.argv[1] == _VERSION_OPTION:
exiter.do_exit(msg=version, out=sys.stdout)
root_dir = get_buildroot()
if not os.path.exists(root_dir):
exiter.exit_and_fail('PANTS_BUILD_ROOT does not point to a valid path: %s' % root_dir)
goal_runner = GoalRunner(root_dir)
goal_runner.setup()
result = goal_runner.run()
exiter.do_exit(result)
def full_options(self, build_configuration: BuildConfiguration) -> Options:
global_bootstrap_options = self.get_bootstrap_options().for_global_scope()
if global_bootstrap_options.pants_version != pants_version():
raise BuildConfigurationError(
f"Version mismatch: Requested version was {global_bootstrap_options.pants_version}, "
f"our version is {pants_version()}."
)
# Parse and register options.
known_scope_infos = [
subsystem.get_scope_info() for subsystem in build_configuration.all_subsystems
]
options = self.full_options_for_scopes(
known_scope_infos, allow_unknown_options=build_configuration.allow_unknown_options
)
GlobalOptions.validate_instance(options.for_global_scope())
return options
def pants_setup_py(name, description, additional_classifiers=None, **kwargs):
"""Creates the setup_py for a pants artifact.
:param str name: The name of the package.
:param str description: A brief description of what the package provides.
:param list additional_classifiers: Any additional trove classifiers that apply to the package,
see: https://pypi.python.org/pypi?%3Aaction=list_classifiers
:param kwargs: Any additional keyword arguments to be passed to `setuptools.setup
<https://pythonhosted.org/setuptools/setuptools.html>`_.
:returns: A setup_py suitable for building and publishing pants components.
"""
if not name.startswith("pantsbuild.pants"):
raise ValueError(
"Pants distribution package names must start with 'pantsbuild.pants', " "given {}".format(name)
)
standard_classifiers = [
"Intended Audience :: Developers",
"License :: OSI Approved :: Apache Software License",
# We know for a fact these OSs work but, for example, know Windows
# does not work yet. Take the conservative approach and only list OSs
# we know pants works with for now.
"Operating System :: MacOS :: MacOS X",
"Operating System :: POSIX :: Linux",
"Programming Language :: Python",
"Topic :: Software Development :: Build Tools",
]
classifiers = OrderedSet(standard_classifiers + (additional_classifiers or []))
def _read_contents(path):
with open(os.path.join(get_buildroot(), path), "rb") as fp:
return fp.read()
return PythonArtifact(
name=name,
version=pants_version(),
description=description,
long_description=(
_read_contents("src/python/pants/ABOUT.rst") + _read_contents("src/python/pants/CHANGELOG.rst")
),
url="https://github.com/pantsbuild/pants",
license="Apache License, Version 2.0",
zip_safe=True,
classifiers=list(classifiers),
**kwargs
)
def pants_setup_py(name, description, additional_classifiers=None, **kwargs):
"""Creates the setup_py for a pants artifact.
:param str name: The name of the package.
:param str description: A brief description of what the package provides.
:param list additional_classifiers: Any additional trove classifiers that apply to the package,
see: https://pypi.python.org/pypi?%3Aaction=list_classifiers
:param kwargs: Any additional keyword arguments to be passed to `setuptools.setup
<https://pythonhosted.org/setuptools/setuptools.html>`_.
:returns: A setup_py suitable for building and publishing pants components.
"""
if not name.startswith('pantsbuild.pants'):
raise ValueError(
"Pants distribution package names must start with 'pantsbuild.pants', "
"given {}".format(name))
standard_classifiers = [
'Intended Audience :: Developers',
'License :: OSI Approved :: Apache Software License',
# We know for a fact these OSs work but, for example, know Windows
# does not work yet. Take the conservative approach and only list OSs
# we know pants works with for now.
'Operating System :: MacOS :: MacOS X',
'Operating System :: POSIX :: Linux',
'Programming Language :: Python',
'Topic :: Software Development :: Build Tools'
]
classifiers = OrderedSet(standard_classifiers +
(additional_classifiers or []))
def _read_contents(path):
with open(os.path.join(get_buildroot(), path), 'rb') as fp:
return fp.read()
return PythonArtifact(
name=name,
version=pants_version(),
description=description,
long_description=(_read_contents('src/python/pants/ABOUT.rst') +
_read_contents('src/python/pants/CHANGELOG.rst')),
url='https://github.com/pantsbuild/pants',
license='Apache License, Version 2.0',
zip_safe=True,
classifiers=list(classifiers),
**kwargs)
def pants_requirement(parse_context, name=None):
"""Exports a `python_requirement_library` pointing at the active pants' corresponding sdist.
This requirement is useful for custom plugin authors who want to build and test their plugin with
pants itself. Using the resulting target as a dependency of their plugin target ensures the
dependency stays true to the surrounding repo's version of pants.
NB: The requirement generated is for official pants releases on pypi; so may not be appropriate
for use in a repo that tracks `pantsbuild/pants` or otherwise uses custom pants sdists.
:param string name: The name to use for the target, defaults to the parent dir name.
"""
name = name or os.path.basename(parse_context.rel_path)
requirement = PythonRequirement(
requirement='pantsbuild.pants=={}'.format(pants_version()))
parse_context.create_object(PythonRequirementLibrary,
name=name,
requirements=[requirement])
def _run():
# Place the registration of the unhandled exception hook as early as possible in the code.
sys.excepthook = _unhandled_exception_hook
logging.basicConfig()
version = pants_version()
if len(sys.argv) == 2 and sys.argv[1] == _VERSION_OPTION:
_do_exit(msg=version, out=sys.stdout)
root_dir = get_buildroot()
if not os.path.exists(root_dir):
_exit_and_fail('PANTS_BUILD_ROOT does not point to a valid path: %s' %
root_dir)
goal_runner = GoalRunner(root_dir)
goal_runner.setup()
result = goal_runner.run()
_do_exit(result)
def __call__(self, name='pants', with_testinfra=False):
cur_pants_version = pants_version()
all_reqs = []
pants_req = self._parse_context.create_object(
'python_requirement',
'pantsbuild.pants=={}'.format(cur_pants_version))
all_reqs.append(pants_req)
if with_testinfra:
testinfra_req = self._parse_context.create_object(
'python_requirement',
'pantsbuild.pants.testinfra=={}'.format(cur_pants_version))
all_reqs.append(testinfra_req)
self._parse_context.create_object('python_requirement_library',
name=name,
requirements=[pants_req] + all_reqs)
def create(
cls,
options_bootstrapper: OptionsBootstrapper,
build_configuration: BuildConfiguration,
) -> Options:
global_bootstrap_options = options_bootstrapper.get_bootstrap_options(
).for_global_scope()
if global_bootstrap_options.pants_version != pants_version():
raise BuildConfigurationError(
f"Version mismatch: Requested version was {global_bootstrap_options.pants_version}, "
f"our version is {pants_version()}.")
# Parse and register options.
known_scope_infos = [
si for optionable in build_configuration.all_optionables
for si in optionable.known_scope_infos()
]
options = options_bootstrapper.get_full_options(known_scope_infos)
GlobalOptions.validate_instance(options.for_global_scope())
return options
def print_help(self):
"""Print help to the console.
:return: 0 on success, 1 on failure
"""
def print_hint():
print('Use `pants goals` to list goals.')
print('Use `pants help` to get help.')
if isinstance(self._help_request, VersionHelp):
print(pants_version())
elif isinstance(self._help_request, OptionsHelp):
self._print_options_help()
elif isinstance(self._help_request, UnknownGoalHelp):
print('Unknown goals: {}'.format(', '.join(self._help_request.unknown_goals)))
print_hint()
return 1
elif isinstance(self._help_request, NoGoalHelp):
print('No goals specified.')
print_hint()
return 1
return 0
def print_help(self) -> Literal[0, 1]:
"""Print help to the console."""
def print_hint() -> None:
print(f"Use `{self.bin_name} goals` to list goals.")
print(f"Use `{self.bin_name} help` to get help.")
if isinstance(self._help_request, VersionHelp):
print(pants_version())
elif isinstance(self._help_request, OptionsHelp):
self._print_options_help()
elif isinstance(self._help_request, GoalsHelp):
self._print_goals_help()
elif isinstance(self._help_request, UnknownGoalHelp):
print("Unknown goals: {}".format(", ".join(
self._help_request.unknown_goals)))
print_hint()
return 1
elif isinstance(self._help_request, NoGoalHelp):
print("No goals specified.")
print_hint()
return 1
return 0
def pants_setup_py(name, description, namespace_packages=None, additional_classifiers=None):
"""Creates the setup_py for a pants artifact.
:param str name: The name of the package.
:param str description: A brief description of what the package provides.
:param list additional_classifiers: Any additional trove classifiers that apply to the package,
see: https://pypi.python.org/pypi?%3Aaction=list_classifiers
:returns: A setup_py suitable for building and publishing pants components.
"""
standard_classifiers = [
'Intended Audience :: Developers',
'License :: OSI Approved :: Apache Software License',
# We know for a fact these OSs work but, for example, know Windows
# does not work yet. Take the conservative approach and only list OSs
# we know pants works with for now.
'Operating System :: MacOS :: MacOS X',
'Operating System :: POSIX :: Linux',
'Programming Language :: Python',
'Topic :: Software Development :: Build Tools']
classifiers = OrderedSet(standard_classifiers + (additional_classifiers or []))
def _read_contents(path):
with open(os.path.join(get_buildroot(), path), 'rb') as fp:
return fp.read()
return PythonArtifact(
name=name,
version=pants_version(),
description=description,
long_description=(_read_contents('src/python/pants/ABOUT.rst') +
_read_contents('src/python/pants/CHANGELOG.rst')),
url='https://github.com/pantsbuild/pants',
license='Apache License, Version 2.0',
zip_safe=True,
namespace_packages=namespace_packages,
classifiers=list(classifiers))
def register_bootstrap_options(cls, register):
"""Register bootstrap options.
"Bootstrap options" are a small set of options whose values are useful when registering other
options. Therefore we must bootstrap them early, before other options are registered, let
alone parsed.
Bootstrap option values can be interpolated into the config file, and can be referenced
programatically in registration code, e.g., as register.bootstrap.pants_workdir.
Note that regular code can also access these options as normal global-scope options. Their
status as "bootstrap options" is only pertinent during option registration.
"""
buildroot = get_buildroot()
# Although logging supports the WARN level, its not documented and could conceivably be yanked.
# Since pants has supported 'warn' since inception, leave the 'warn' choice as-is but explicitly
# setup a 'WARN' logging level name that maps to 'WARNING'.
logging.addLevelName(logging.WARNING, 'WARN')
register('-l',
'--level',
choices=['debug', 'info', 'warn'],
default='info',
recursive=True,
help='Set the logging level.')
register('-q',
'--quiet',
type=bool,
recursive=True,
help='Squelches most console output.')
# Not really needed in bootstrap options, but putting it here means it displays right
# after -l and -q in help output, which is conveniently contextual.
register('--colors',
type=bool,
default=sys.stdout.isatty(),
recursive=True,
help='Set whether log messages are displayed in color.')
# Pants code uses this only to verify that we are of the requested version. However
# setup scripts, runner scripts, IDE plugins, etc., may grep this out of pants.ini
# and use it to select the right version.
# Note that to print the version of the pants instance you're running, use -v, -V or --version.
register('--pants-version',
advanced=True,
default=pants_version(),
help='Use this pants version.')
register('--plugins',
advanced=True,
type=list,
help='Load these plugins.')
register('--plugin-cache-dir',
advanced=True,
default=os.path.join(get_pants_cachedir(), 'plugins'),
help='Cache resolved plugin requirements here.')
register(
'--backend-packages',
advanced=True,
type=list,
default=[
'pants.backend.graph_info', 'pants.backend.python',
'pants.backend.jvm', 'pants.backend.codegen.antlr.java',
'pants.backend.codegen.antlr.python',
'pants.backend.codegen.jaxb',
'pants.backend.codegen.protobuf.java',
'pants.backend.codegen.ragel.java',
'pants.backend.codegen.thrift.java',
'pants.backend.codegen.thrift.python',
'pants.backend.codegen.wire.java', 'pants.backend.project_info'
],
help=
'Load backends from these packages that are already on the path. '
'Add contrib and custom backends to this list.')
register('--pants-bootstrapdir',
advanced=True,
metavar='<dir>',
default=get_pants_cachedir(),
help='Use this dir for global cache.')
register('--pants-configdir',
advanced=True,
metavar='<dir>',
default=get_pants_configdir(),
help='Use this dir for global config files.')
register('--pants-workdir',
advanced=True,
metavar='<dir>',
default=os.path.join(buildroot, '.pants.d'),
help='Write intermediate output files to this dir.')
register('--pants-supportdir',
advanced=True,
metavar='<dir>',
default=os.path.join(buildroot, 'build-support'),
help='Use support files from this dir.')
register('--pants-distdir',
advanced=True,
metavar='<dir>',
default=os.path.join(buildroot, 'dist'),
help='Write end-product artifacts to this dir.')
register(
'--pants-subprocessdir',
advanced=True,
default=os.path.join(buildroot, '.pids'),
help=
'The directory to use for tracking subprocess metadata, if any. This should '
'live outside of the dir used by `--pants-workdir` to allow for tracking '
'subprocesses that outlive the workdir data (e.g. `./pants server`).'
)
register('--pants-config-files',
advanced=True,
type=list,
default=[get_default_pants_config_file()],
help='Paths to Pants config files.')
# TODO: Deprecate the --pantsrc/--pantsrc-files options? This would require being able
# to set extra config file locations in an initial bootstrap config file.
register('--config-override',
advanced=True,
type=list,
metavar='<path>',
removal_version='1.6.0.dev0',
removal_hint=
'Use --pants-config-files=<second config file path> instead.',
help='A second config file, to override pants.ini.')
register('--pantsrc',
advanced=True,
type=bool,
default=True,
help='Use pantsrc files.')
register('--pantsrc-files',
advanced=True,
type=list,
metavar='<path>',
default=['/etc/pantsrc', '~/.pants.rc'],
help='Override config with values from these files. '
'Later files override earlier ones.')
register(
'--pythonpath',
advanced=True,
type=list,
help='Add these directories to PYTHONPATH to search for plugins.')
register('--target-spec-file',
type=list,
dest='target_spec_files',
help='Read additional specs from this file, one per line')
register(
'--verify-config',
type=bool,
default=True,
help=
'Verify that all config file values correspond to known options.')
# These logging options are registered in the bootstrap phase so that plugins can log during
# registration and not so that their values can be interpolated in configs.
register('-d',
'--logdir',
advanced=True,
metavar='<dir>',
help='Write logs to files under this directory.')
# This facilitates bootstrap-time configuration of pantsd usage such that we can
# determine whether or not to use the Pailgun client to invoke a given pants run
# without resorting to heavier options parsing.
register(
'--enable-pantsd',
advanced=True,
type=bool,
default=False,
help=
'Enables use of the pants daemon (and implicitly, the v2 engine). (Beta)'
)
# This facilitates use of the v2 engine, sans daemon.
# TODO: Add removal_version='1.5.0.dev0' before 1.4 lands.
register('--enable-v2-engine',
advanced=True,
type=bool,
default=True,
help='Enables use of the v2 engine.')
# These facilitate configuring the native engine.
register('--native-engine-version',
advanced=True,
default=pkg_resources.resource_string(
'pants.engine', 'native_engine_version').strip(),
help='Native engine version.')
register(
'--native-engine-supportdir',
advanced=True,
default='bin/native-engine',
help=
'Find native engine binaries under this dir. Used as part of the path to '
'lookup the binary with --binary-util-baseurls and --pants-bootstrapdir.'
)
register(
'--native-engine-visualize-to',
advanced=True,
default=None,
type=dir_option,
help=
'A directory to write execution and rule graphs to as `dot` files. The contents '
'of the directory will be overwritten if any filenames collide.')
# BinaryUtil options.
register(
'--binaries-baseurls',
type=list,
advanced=True,
default=['https://binaries.pantsbuild.org'],
help=
'List of URLs from which binary tools are downloaded. URLs are searched in '
'order until the requested path is found.')
register(
'--binaries-fetch-timeout-secs',
type=int,
default=30,
advanced=True,
help=
'Timeout in seconds for URL reads when fetching binary tools from the '
'repos specified by --baseurls.')
register(
'--binaries-path-by-id',
type=dict,
advanced=True,
help=
('Maps output of uname for a machine to a binary search path. e.g. '
'{("darwin", "15"): ["mac", "10.11"]), ("linux", "arm32"): ["linux", "arm32"]}'
))
def register_bootstrap_options(cls, register):
"""Register bootstrap options.
"Bootstrap options" are a small set of options whose values are useful when registering other
options. Therefore we must bootstrap them early, before other options are registered, let
alone parsed.
Bootstrap option values can be interpolated into the config file, and can be referenced
programatically in registration code, e.g., as register.bootstrap.pants_workdir.
Note that regular code can also access these options as normal global-scope options. Their
status as "bootstrap options" is only pertinent during option registration.
"""
buildroot = get_buildroot()
default_distdir_name = 'dist'
default_distdir = os.path.join(buildroot, default_distdir_name)
default_rel_distdir = '/{}/'.format(default_distdir_name)
register('-l', '--level', choices=['trace', 'debug', 'info', 'warn'], default='info',
recursive=True, help='Set the logging level.')
register('-q', '--quiet', type=bool, recursive=True, daemon=False,
help='Squelches most console output. NOTE: Some tasks default to behaving quietly: '
'inverting this option supports making them noisier than they would be otherwise.')
register('--log-show-rust-3rdparty', type=bool, default=False, advanced=True,
help='Whether to show/hide logging done by 3rdparty rust crates used by the pants '
'engine.')
# Not really needed in bootstrap options, but putting it here means it displays right
# after -l and -q in help output, which is conveniently contextual.
register('--colors', type=bool, default=sys.stdout.isatty(), recursive=True, daemon=False,
help='Set whether log messages are displayed in color.')
# TODO(#7203): make a regexp option type!
register('--ignore-pants-warnings', type=list, member_type=str, default=[],
help='Regexps matching warning strings to ignore, e.g. '
'["DEPRECATED: scope some_scope will be removed"]. The regexps will be matched '
'from the start of the warning string, and will always be case-insensitive. '
'See the `warnings` module documentation for more background on these are used.')
register('--option-name-check-distance', advanced=True, type=int, default=2,
help='The maximum Levenshtein distance to use when offering suggestions for invalid '
'option names.')
register('--pants-version', advanced=True, default=pants_version(),
help='Use this pants version. Note Pants code only uses this to verify that you are '
'using the requested version, as Pants cannot dynamically change the version it '
'is using once the program is already running. This option is useful to set in '
'your pants.ini, however, and then you can grep the value to select which '
'version to use for setup scripts (e.g. `./pants`), runner scripts, IDE plugins, '
'etc. For example, the setup script we distribute at https://www.pantsbuild.org/install.html#recommended-installation '
'uses this value to determine which Python version to run with. You may find the '
'version of the pants instance you are running using -v, -V, or --version.')
register('--pants-runtime-python-version', advanced=True,
removal_version='1.19.0.dev0',
deprecation_start_version='1.17.0.dev0',
removal_hint=dedent("""
This option was only used to help with Pants' migration to run on Python 3. \
Pants will now correctly default to whichever Python versions are supported for \
the current `pants_version` you are using. Please make sure you are using the \
most up-to-date version of the `./pants` script with:
curl -L -O https://pantsbuild.github.io/setup/pants
and then unset this option."""),
help='Use this Python version to run Pants. The option expects the major and minor '
'version, e.g. 2.7 or 3.6. Note Pants code only uses this to verify that you are '
'using the requested interpreter, as Pants cannot dynamically change the '
'interpreter it is using once the program is already running. This option is '
'useful to set in your pants.ini, however, and then you can grep the value to '
'select which interpreter to use for setup scripts (e.g. `./pants`), runner '
'scripts, IDE plugins, etc. For example, the setup script we distribute at '
'https://www.pantsbuild.org/install.html#recommended-installation uses this '
'value to determine which Python version to run with. Also note this does not mean '
'your own code must use this Python version. See '
'https://www.pantsbuild.org/python_readme.html#configure-the-python-version '
'for how to configure your code\'s compatibility.')
register('--plugins', advanced=True, type=list, help='Load these plugins.')
register('--plugin-cache-dir', advanced=True,
default=os.path.join(get_pants_cachedir(), 'plugins'),
help='Cache resolved plugin requirements here.')
register('--backend-packages', advanced=True, type=list,
default=['pants.backend.graph_info',
'pants.backend.python',
'pants.backend.jvm',
'pants.backend.native',
# TODO: Move into the graph_info backend.
'pants.rules.core',
'pants.backend.codegen.antlr.java',
'pants.backend.codegen.antlr.python',
'pants.backend.codegen.jaxb',
'pants.backend.codegen.protobuf.java',
'pants.backend.codegen.ragel.java',
'pants.backend.codegen.thrift.java',
'pants.backend.codegen.thrift.python',
'pants.backend.codegen.grpcio.python',
'pants.backend.codegen.wire.java',
'pants.backend.project_info'],
help='Load backends from these packages that are already on the path. '
'Add contrib and custom backends to this list.')
register('--pants-bootstrapdir', advanced=True, metavar='<dir>', default=get_pants_cachedir(),
help='Use this dir for global cache.')
register('--pants-configdir', advanced=True, metavar='<dir>', default=get_pants_configdir(),
help='Use this dir for global config files.')
register('--pants-workdir', advanced=True, metavar='<dir>',
default=os.path.join(buildroot, '.pants.d'),
help='Write intermediate output files to this dir.')
register('--pants-supportdir', advanced=True, metavar='<dir>',
default=os.path.join(buildroot, 'build-support'),
help='Use support files from this dir.')
register('--pants-distdir', advanced=True, metavar='<dir>',
default=default_distdir,
help='Write end-product artifacts to this dir. If you modify this path, you '
'should also update --build-ignore and --pants-ignore to include the '
'custom dist dir path as well.')
register('--pants-subprocessdir', advanced=True, default=os.path.join(buildroot, '.pids'),
help='The directory to use for tracking subprocess metadata, if any. This should '
'live outside of the dir used by `--pants-workdir` to allow for tracking '
'subprocesses that outlive the workdir data (e.g. `./pants server`).')
register('--pants-config-files', advanced=True, type=list, daemon=False,
default=[get_default_pants_config_file()], help='Paths to Pants config files.')
# TODO: Deprecate the --pantsrc/--pantsrc-files options? This would require being able
# to set extra config file locations in an initial bootstrap config file.
register('--pantsrc', advanced=True, type=bool, default=True,
help='Use pantsrc files.')
register('--pantsrc-files', advanced=True, type=list, metavar='<path>', daemon=False,
default=['/etc/pantsrc', '~/.pants.rc'],
help='Override config with values from these files. '
'Later files override earlier ones.')
register('--pythonpath', advanced=True, type=list,
help='Add these directories to PYTHONPATH to search for plugins.')
register('--target-spec-file', type=list, dest='target_spec_files', daemon=False,
help='Read additional specs from this file, one per line')
register('--verify-config', type=bool, default=True, daemon=False,
advanced=True,
help='Verify that all config file values correspond to known options.')
register('--build-ignore', advanced=True, type=list,
default=['.*/', default_rel_distdir, 'bower_components/',
'node_modules/', '*.egg-info/'],
help='Paths to ignore when identifying BUILD files. '
'This does not affect any other filesystem operations. '
'Patterns use the gitignore pattern syntax (https://git-scm.com/docs/gitignore).')
register('--pants-ignore', advanced=True, type=list,
default=['.*/', default_rel_distdir],
help='Paths to ignore for all filesystem operations performed by pants '
'(e.g. BUILD file scanning, glob matching, etc). '
'Patterns use the gitignore syntax (https://git-scm.com/docs/gitignore).')
register('--glob-expansion-failure', advanced=True,
default=GlobMatchErrorBehavior.warn, type=GlobMatchErrorBehavior,
help="Raise an exception if any targets declaring source files "
"fail to match any glob provided in the 'sources' argument.")
# TODO(#7203): make a regexp option type!
register('--exclude-target-regexp', advanced=True, type=list, default=[], daemon=False,
metavar='<regexp>', help='Exclude target roots that match these regexes.')
register('--subproject-roots', type=list, advanced=True, default=[],
help='Paths that correspond with build roots for any subproject that this '
'project depends on.')
register('--owner-of', type=list, member_type=file_option, default=[], daemon=False, metavar='<path>',
help='Select the targets that own these files. '
'This is the third target calculation strategy along with the --changed-* '
'options and specifying the targets directly. These three types of target '
'selection are mutually exclusive.')
# These logging options are registered in the bootstrap phase so that plugins can log during
# registration and not so that their values can be interpolated in configs.
register('-d', '--logdir', advanced=True, metavar='<dir>',
help='Write logs to files under this directory.')
# This facilitates bootstrap-time configuration of pantsd usage such that we can
# determine whether or not to use the Pailgun client to invoke a given pants run
# without resorting to heavier options parsing.
register('--enable-pantsd', advanced=True, type=bool, default=False,
help='Enables use of the pants daemon (and implicitly, the v2 engine). (Beta)')
# Shutdown pantsd after the current run.
# This needs to be accessed at the same time as enable_pantsd,
# so we register it at bootstrap time.
register('--shutdown-pantsd-after-run', advanced=True, type=bool, default=False,
help='Create a new pantsd server, and use it, and shut it down immediately after. '
'If pantsd is already running, it will shut it down and spawn a new instance (Beta)')
# These facilitate configuring the native engine.
register('--native-engine-visualize-to', advanced=True, default=None, type=dir_option, daemon=False,
help='A directory to write execution and rule graphs to as `dot` files. The contents '
'of the directory will be overwritten if any filenames collide.')
register('--print-exception-stacktrace', advanced=True, type=bool,
help='Print to console the full exception stack trace if encountered.')
# BinaryUtil options.
register('--binaries-baseurls', type=list, advanced=True,
default=['https://binaries.pantsbuild.org'],
help='List of URLs from which binary tools are downloaded. URLs are '
'searched in order until the requested path is found.')
register('--binaries-fetch-timeout-secs', type=int, default=30, advanced=True, daemon=False,
help='Timeout in seconds for URL reads when fetching binary tools from the '
'repos specified by --baseurls.')
register('--binaries-path-by-id', type=dict, advanced=True,
help=("Maps output of uname for a machine to a binary search path: "
"(sysname, id) -> (os, arch), e.g. {('darwin', '15'): ('mac', '10.11'), "
"('linux', 'arm32'): ('linux', 'arm32')}."))
register('--allow-external-binary-tool-downloads', type=bool, default=True, advanced=True,
help="If False, require BinaryTool subclasses to download their contents from urls "
"generated from --binaries-baseurls, even if the tool has an external url "
"generator. This can be necessary if using Pants in an environment which cannot "
"contact the wider Internet.")
# Pants Daemon options.
register('--pantsd-pailgun-host', advanced=True, default='127.0.0.1',
help='The host to bind the pants nailgun server to.')
register('--pantsd-pailgun-port', advanced=True, type=int, default=0,
help='The port to bind the pants nailgun server to. Defaults to a random port.')
# TODO(#7514): Make this default to 1.0 seconds if stdin is a tty!
register('--pantsd-pailgun-quit-timeout', advanced=True, type=float, default=5.0,
help='The length of time (in seconds) to wait for further output after sending a '
'signal to the remote pantsd process before killing it.')
register('--pantsd-log-dir', advanced=True, default=None,
help='The directory to log pantsd output to.')
register('--pantsd-invalidation-globs', advanced=True, type=list, default=[],
help='Filesystem events matching any of these globs will trigger a daemon restart.')
# Watchman options.
register('--watchman-version', advanced=True, default='4.9.0-pants1', help='Watchman version.')
register('--watchman-supportdir', advanced=True, default='bin/watchman',
help='Find watchman binaries under this dir. Used as part of the path to lookup '
'the binary with --binaries-baseurls and --pants-bootstrapdir.')
register('--watchman-startup-timeout', type=float, advanced=True, default=30.0,
help='The watchman socket timeout (in seconds) for the initial `watch-project` command. '
'This may need to be set higher for larger repos due to watchman startup cost.')
register('--watchman-socket-timeout', type=float, advanced=True, default=0.1,
help='The watchman client socket timeout in seconds. Setting this to too high a '
'value can negatively impact the latency of runs forked by pantsd.')
register('--watchman-socket-path', type=str, advanced=True, default=None,
help='The path to the watchman UNIX socket. This can be overridden if the default '
'absolute path length exceeds the maximum allowed by the OS.')
# This option changes the parser behavior in a fundamental way (which currently invalidates
# all caches), and needs to be parsed out early, so we make it a bootstrap option.
register('--build-file-imports', choices=['allow', 'warn', 'error'], default='warn',
advanced=True,
help='Whether to allow import statements in BUILD files')
register('--local-store-dir', advanced=True,
help="Directory to use for engine's local file store.",
# This default is also hard-coded into the engine's rust code in
# fs::Store::default_path
default=os.path.expanduser('~/.cache/pants/lmdb_store'))
register('--remote-store-server', advanced=True, type=list, default=[],
help='host:port of grpc server to use as remote execution file store.')
register('--remote-store-thread-count', type=int, advanced=True,
default=DEFAULT_EXECUTION_OPTIONS.remote_store_thread_count,
help='Thread count to use for the pool that interacts with the remote file store.')
register('--remote-execution-server', advanced=True,
help='host:port of grpc server to use as remote execution scheduler.')
register('--remote-store-chunk-bytes', type=int, advanced=True,
default=DEFAULT_EXECUTION_OPTIONS.remote_store_chunk_bytes,
help='Size in bytes of chunks transferred to/from the remote file store.')
register('--remote-store-chunk-upload-timeout-seconds', type=int, advanced=True,
default=DEFAULT_EXECUTION_OPTIONS.remote_store_chunk_upload_timeout_seconds,
help='Timeout (in seconds) for uploads of individual chunks to the remote file store.')
register('--remote-store-rpc-retries', type=int, advanced=True,
default=DEFAULT_EXECUTION_OPTIONS.remote_store_rpc_retries,
help='Number of times to retry any RPC to the remote store before giving up.')
register('--remote-execution-process-cache-namespace', advanced=True,
help="The cache namespace for remote process execution. "
"Bump this to invalidate every artifact's remote execution. "
"This is the remote execution equivalent of the legacy cache-key-gen-version "
"flag.")
register('--remote-instance-name', advanced=True,
help='Name of the remote execution instance to use. Used for routing within '
'--remote-execution-server and --remote-store-server.')
register('--remote-ca-certs-path', advanced=True,
help='Path to a PEM file containing CA certificates used for verifying secure '
'connections to --remote-execution-server and --remote-store-server. '
'If not specified, TLS will not be used.')
register('--remote-oauth-bearer-token-path', advanced=True,
help='Path to a file containing an oauth token to use for grpc connections to '
'--remote-execution-server and --remote-store-server. If not specified, no '
'authorization will be performed.')
register('--remote-execution-extra-platform-properties', advanced=True,
help='Platform properties to set on remote execution requests. '
'Format: property=value. Multiple values should be specified as multiple '
'occurrences of this flag. Pants itself may add additional platform properties.',
type=list, default=[])
# This should eventually deprecate the RunTracker worker count, which is used for legacy cache
# lookups via CacheSetup in TaskBase.
register('--process-execution-parallelism', type=int, default=multiprocessing.cpu_count(),
advanced=True,
help='Number of concurrent processes that may be executed either locally and remotely.')
register('--process-execution-cleanup-local-dirs', type=bool, default=True, advanced=True,
help='Whether or not to cleanup directories used for local process execution '
'(primarily useful for e.g. debugging).')
def register_bootstrap_options(cls, register):
"""Register bootstrap options.
"Bootstrap options" are a small set of options whose values are useful when registering other
options. Therefore we must bootstrap them early, before other options are registered, let
alone parsed.
Bootstrap option values can be interpolated into the config file, and can be referenced
programatically in registration code, e.g., as register.bootstrap.pants_workdir.
Note that regular code can also access these options as normal global-scope options. Their
status as "bootstrap options" is only pertinent during option registration.
"""
buildroot = get_buildroot()
# Although logging supports the WARN level, its not documented and could conceivably be yanked.
# Since pants has supported 'warn' since inception, leave the 'warn' choice as-is but explicitly
# setup a 'WARN' logging level name that maps to 'WARNING'.
logging.addLevelName(logging.WARNING, 'WARN')
register('-l', '--level', choices=['debug', 'info', 'warn'], default='info', recursive=True,
help='Set the logging level.')
register('-q', '--quiet', type=bool, recursive=True,
help='Squelches most console output.')
# Not really needed in bootstrap options, but putting it here means it displays right
# after -l and -q in help output, which is conveniently contextual.
register('--colors', type=bool, default=True, recursive=True,
help='Set whether log messages are displayed in color.')
# Pants code uses this only to verify that we are of the requested version. However
# setup scripts, runner scripts, IDE plugins, etc., may grep this out of pants.ini
# and use it to select the right version.
# Note that to print the version of the pants instance you're running, use -v, -V or --version.
register('--pants-version', advanced=True, default=pants_version(),
help='Use this pants version.')
register('--plugins', advanced=True, type=list, help='Load these plugins.')
register('--plugin-cache-dir', advanced=True,
default=os.path.join(get_pants_cachedir(), 'plugins'),
help='Cache resolved plugin requirements here.')
register('--backend-packages', advanced=True, type=list,
help='Load backends from these packages that are already on the path.')
register('--pants-bootstrapdir', advanced=True, metavar='<dir>', default=get_pants_cachedir(),
help='Use this dir for global cache.')
register('--pants-configdir', advanced=True, metavar='<dir>', default=get_pants_configdir(),
help='Use this dir for global config files.')
register('--pants-workdir', advanced=True, metavar='<dir>',
default=os.path.join(buildroot, '.pants.d'),
help='Write intermediate output files to this dir.')
register('--pants-supportdir', advanced=True, metavar='<dir>',
default=os.path.join(buildroot, 'build-support'),
help='Use support files from this dir.')
register('--pants-distdir', advanced=True, metavar='<dir>',
default=os.path.join(buildroot, 'dist'),
help='Write end-product artifacts to this dir.')
register('--pants-config-files', advanced=True, type=list,
default=[get_default_pants_config_file()], help='Paths to Pants config files.')
# TODO: Deprecate --config-override in favor of --pants-config-files.
# But only once we're able to both append and override list-valued options, as there are
# use-cases for both here.
# TODO: Deprecate the --pantsrc/--pantsrc-files options? This would require being able
# to set extra config file locations in an initial bootstrap config file.
register('--config-override', advanced=True, type=list, metavar='<path>',
help='A second config file, to override pants.ini.')
register('--pantsrc', advanced=True, type=bool, default=True,
help='Use pantsrc files.')
register('--pantsrc-files', advanced=True, type=list, metavar='<path>',
default=['/etc/pantsrc', '~/.pants.rc'],
help='Override config with values from these files. '
'Later files override earlier ones.')
register('--pythonpath', advanced=True, type=list,
help='Add these directories to PYTHONPATH to search for plugins.')
register('--target-spec-file', type=list, dest='target_spec_files',
help='Read additional specs from this file, one per line')
register('--verify-config', type=bool, default=True,
help='Verify that all config file values correspond to known options.')
# These logging options are registered in the bootstrap phase so that plugins can log during
# registration and not so that their values can be interpolated in configs.
register('-d', '--logdir', advanced=True, metavar='<dir>',
help='Write logs to files under this directory.')
# This facilitates bootstrap-time configuration of pantsd usage such that we can
# determine whether or not to use the Pailgun client to invoke a given pants run
# without resorting to heavier options parsing.
register('--enable-pantsd', advanced=True, type=bool, default=False,
help='Enables use of the pants daemon. (Beta)')
def register_bootstrap_options(cls, register):
"""Register bootstrap options.
"Bootstrap options" are a small set of options whose values are useful when registering other
options. Therefore we must bootstrap them early, before other options are registered, let
alone parsed.
Bootstrap option values can be interpolated into the config file, and can be referenced
programatically in registration code, e.g., as register.bootstrap.pants_workdir.
Note that regular code can also access these options as normal global-scope options. Their
status as "bootstrap options" is only pertinent during option registration.
"""
buildroot = get_buildroot()
# Although logging supports the WARN level, its not documented and could conceivably be yanked.
# Since pants has supported 'warn' since inception, leave the 'warn' choice as-is but explicitly
# setup a 'WARN' logging level name that maps to 'WARNING'.
logging.addLevelName(logging.WARNING, "WARN")
register(
"-l",
"--level",
choices=["debug", "info", "warn"],
default="info",
recursive=True,
help="Set the logging level.",
)
register("-q", "--quiet", type=bool, recursive=True, help="Squelches most console output.")
# Not really needed in bootstrap options, but putting it here means it displays right
# after -l and -q in help output, which is conveniently contextual.
register(
"--colors", type=bool, default=True, recursive=True, help="Set whether log messages are displayed in color."
)
# Pants code uses this only to verify that we are of the requested version. However
# setup scripts, runner scripts, IDE plugins, etc., may grep this out of pants.ini
# and use it to select the right version.
# Note that to print the version of the pants instance you're running, use -v, -V or --version.
register("--pants-version", advanced=True, default=pants_version(), help="Use this pants version.")
register("--plugins", advanced=True, type=list, help="Load these plugins.")
register(
"--plugin-cache-dir",
advanced=True,
default=os.path.join(get_pants_cachedir(), "plugins"),
help="Cache resolved plugin requirements here.",
)
register(
"--backend-packages",
advanced=True,
type=list,
default=[
"pants.backend.graph_info",
"pants.backend.python",
"pants.backend.jvm",
"pants.backend.codegen",
"pants.backend.project_info",
],
help="Load backends from these packages that are already on the path. "
"Add contrib and custom backends to this list.",
)
register(
"--default-backend-packages",
advanced=True,
type=list,
removal_version="1.3.0",
removal_hint="All backends must be specified using the backend_packages option. "
"That option has the same defaults as this one, and you can append"
"and filter those using +[...] and -[...] syntax, as described here: "
"http://www.pantsbuild.org/options.html#list-options.",
default=[
"pants.backend.graph_info",
"pants.backend.python",
"pants.backend.jvm",
"pants.backend.codegen",
"pants.backend.project_info",
],
help="Load these backends by default. These backends come distributed with Pants. "
"Remove unused backends from this list to speed up execution. "
"Use --backend-packages to configure additional backends with Pants.",
)
register(
"--pants-bootstrapdir",
advanced=True,
metavar="<dir>",
default=get_pants_cachedir(),
help="Use this dir for global cache.",
)
register(
"--pants-configdir",
advanced=True,
metavar="<dir>",
default=get_pants_configdir(),
help="Use this dir for global config files.",
)
register(
"--pants-workdir",
advanced=True,
metavar="<dir>",
default=os.path.join(buildroot, ".pants.d"),
help="Write intermediate output files to this dir.",
)
register(
"--pants-supportdir",
advanced=True,
metavar="<dir>",
default=os.path.join(buildroot, "build-support"),
help="Use support files from this dir.",
)
register(
"--pants-distdir",
advanced=True,
metavar="<dir>",
default=os.path.join(buildroot, "dist"),
help="Write end-product artifacts to this dir.",
)
register(
"--pants-subprocessdir",
advanced=True,
default=os.path.join(buildroot, ".pids"),
help="The directory to use for tracking subprocess metadata, if any. This should "
"live outside of the dir used by `--pants-workdir` to allow for tracking "
"subprocesses that outlive the workdir data (e.g. `./pants server`).",
)
register(
"--pants-config-files",
advanced=True,
type=list,
default=[get_default_pants_config_file()],
help="Paths to Pants config files.",
)
# TODO: Deprecate --config-override in favor of --pants-config-files.
# But only once we're able to both append and override list-valued options, as there are
# use-cases for both here.
# TODO: Deprecate the --pantsrc/--pantsrc-files options? This would require being able
# to set extra config file locations in an initial bootstrap config file.
register(
"--config-override",
advanced=True,
type=list,
metavar="<path>",
help="A second config file, to override pants.ini.",
)
register("--pantsrc", advanced=True, type=bool, default=True, help="Use pantsrc files.")
register(
"--pantsrc-files",
advanced=True,
type=list,
metavar="<path>",
default=["/etc/pantsrc", "~/.pants.rc"],
help="Override config with values from these files. " "Later files override earlier ones.",
)
register(
"--pythonpath", advanced=True, type=list, help="Add these directories to PYTHONPATH to search for plugins."
)
register(
"--target-spec-file",
type=list,
dest="target_spec_files",
help="Read additional specs from this file, one per line",
)
register(
"--verify-config",
type=bool,
default=True,
help="Verify that all config file values correspond to known options.",
)
# These logging options are registered in the bootstrap phase so that plugins can log during
# registration and not so that their values can be interpolated in configs.
register("-d", "--logdir", advanced=True, metavar="<dir>", help="Write logs to files under this directory.")
# This facilitates bootstrap-time configuration of pantsd usage such that we can
# determine whether or not to use the Pailgun client to invoke a given pants run
# without resorting to heavier options parsing.
register(
"--enable-pantsd",
advanced=True,
type=bool,
default=False,
help="Enables use of the pants daemon (and implicitly, the v2 engine). (Beta)",
)
# This facilitates use of the v2 engine for BuildGraph construction, sans daemon.
register(
"--enable-v2-engine", advanced=True, type=bool, default=False, help="Enables use of the v2 engine. (Beta)"
)
def test_version() -> None: assert pants_version() == _VERSION
def register_bootstrap_options(cls, register):
"""Register bootstrap options.
"Bootstrap options" are a small set of options whose values are useful when registering other
options. Therefore we must bootstrap them early, before other options are registered, let
alone parsed.
Bootstrap option values can be interpolated into the config file, and can be referenced
programatically in registration code, e.g., as register.bootstrap.pants_workdir.
Note that regular code can also access these options as normal global-scope options. Their
status as "bootstrap options" is only pertinent during option registration.
"""
buildroot = get_buildroot()
default_distdir_name = 'dist'
default_distdir = os.path.join(buildroot, default_distdir_name)
default_rel_distdir = '/{}/'.format(default_distdir_name)
register('-l',
'--level',
choices=['trace', 'debug', 'info', 'warn'],
default='info',
recursive=True,
help='Set the logging level.')
register(
'-q',
'--quiet',
type=bool,
recursive=True,
daemon=False,
help=
'Squelches most console output. NOTE: Some tasks default to behaving quietly: '
'inverting this option supports making them noisier than they would be otherwise.'
)
register(
'--log-show-rust-3rdparty',
type=bool,
default=False,
advanced=True,
help=
'Whether to show/hide logging done by 3rdparty rust crates used by the pants '
'engine.')
# Not really needed in bootstrap options, but putting it here means it displays right
# after -l and -q in help output, which is conveniently contextual.
register('--colors',
type=bool,
default=sys.stdout.isatty(),
recursive=True,
daemon=False,
help='Set whether log messages are displayed in color.')
# TODO(#7203): make a regexp option type!
register(
'--ignore-pants-warnings',
type=list,
member_type=str,
default=[],
help='Regexps matching warning strings to ignore, e.g. '
'["DEPRECATED: scope some_scope will be removed"]. The regexps will be matched '
'from the start of the warning string, and will always be case-insensitive. '
'See the `warnings` module documentation for more background on these are used.'
)
register(
'--option-name-check-distance',
advanced=True,
type=int,
default=2,
help=
'The maximum Levenshtein distance to use when offering suggestions for invalid '
'option names.')
register(
'--pants-version',
advanced=True,
default=pants_version(),
help=
'Use this pants version. Note Pants code only uses this to verify that you are '
'using the requested version, as Pants cannot dynamically change the version it '
'is using once the program is already running. This option is useful to set in '
'your pants.ini, however, and then you can grep the value to select which '
'version to use for setup scripts (e.g. `./pants`), runner scripts, IDE plugins, '
'etc. For example, the setup script we distribute at https://www.pantsbuild.org/install.html#recommended-installation '
'uses this value to determine which Python version to run with. You may find the '
'version of the pants instance you are running using -v, -V, or --version.'
)
register('--plugins',
advanced=True,
type=list,
help='Load these plugins.')
register('--plugin-cache-dir',
advanced=True,
default=os.path.join(get_pants_cachedir(), 'plugins'),
help='Cache resolved plugin requirements here.')
register(
'--backend-packages',
advanced=True,
type=list,
default=[
'pants.backend.graph_info', 'pants.backend.python',
'pants.backend.jvm', 'pants.backend.native',
'pants.backend.codegen.antlr.java',
'pants.backend.codegen.antlr.python',
'pants.backend.codegen.jaxb',
'pants.backend.codegen.protobuf.java',
'pants.backend.codegen.ragel.java',
'pants.backend.codegen.thrift.java',
'pants.backend.codegen.thrift.python',
'pants.backend.codegen.grpcio.python',
'pants.backend.codegen.wire.java', 'pants.backend.project_info'
],
help=
'Load backends from these packages that are already on the path. '
'Add contrib and custom backends to this list.')
register('--pants-bootstrapdir',
advanced=True,
metavar='<dir>',
default=get_pants_cachedir(),
help='Use this dir for global cache.')
register('--pants-configdir',
advanced=True,
metavar='<dir>',
default=get_pants_configdir(),
help='Use this dir for global config files.')
register('--pants-workdir',
advanced=True,
metavar='<dir>',
default=os.path.join(buildroot, '.pants.d'),
help='Write intermediate output files to this dir.')
register('--pants-supportdir',
advanced=True,
metavar='<dir>',
default=os.path.join(buildroot, 'build-support'),
help='Use support files from this dir.')
register(
'--pants-distdir',
advanced=True,
metavar='<dir>',
default=default_distdir,
help=
'Write end-product artifacts to this dir. If you modify this path, you '
'should also update --build-ignore and --pants-ignore to include the '
'custom dist dir path as well.')
register(
'--pants-subprocessdir',
advanced=True,
default=os.path.join(buildroot, '.pids'),
help=
'The directory to use for tracking subprocess metadata, if any. This should '
'live outside of the dir used by `--pants-workdir` to allow for tracking '
'subprocesses that outlive the workdir data (e.g. `./pants server`).'
)
register('--pants-config-files',
advanced=True,
type=list,
daemon=False,
default=[get_default_pants_config_file()],
help='Paths to Pants config files.')
# TODO: Deprecate the --pantsrc/--pantsrc-files options? This would require being able
# to set extra config file locations in an initial bootstrap config file.
register('--pantsrc',
advanced=True,
type=bool,
default=True,
help='Use pantsrc files.')
register('--pantsrc-files',
advanced=True,
type=list,
metavar='<path>',
daemon=False,
default=['/etc/pantsrc', '~/.pants.rc'],
help='Override config with values from these files. '
'Later files override earlier ones.')
register(
'--pythonpath',
advanced=True,
type=list,
help='Add these directories to PYTHONPATH to search for plugins.')
register('--target-spec-file',
type=list,
dest='target_spec_files',
daemon=False,
help='Read additional specs from this file, one per line')
register(
'--verify-config',
type=bool,
default=True,
daemon=False,
advanced=True,
help=
'Verify that all config file values correspond to known options.')
register(
'--build-ignore',
advanced=True,
type=list,
default=[
'.*/', default_rel_distdir, 'bower_components/',
'node_modules/', '*.egg-info/'
],
help='Paths to ignore when identifying BUILD files. '
'This does not affect any other filesystem operations. '
'Patterns use the gitignore pattern syntax (https://git-scm.com/docs/gitignore).'
)
register(
'--pants-ignore',
advanced=True,
type=list,
default=['.*/', default_rel_distdir],
help=
'Paths to ignore for all filesystem operations performed by pants '
'(e.g. BUILD file scanning, glob matching, etc). '
'Patterns use the gitignore syntax (https://git-scm.com/docs/gitignore).'
)
register(
'--glob-expansion-failure',
advanced=True,
default=GlobMatchErrorBehavior.warn,
type=GlobMatchErrorBehavior,
help="Raise an exception if any targets declaring source files "
"fail to match any glob provided in the 'sources' argument.")
# TODO(#7203): make a regexp option type!
register('--exclude-target-regexp',
advanced=True,
type=list,
default=[],
daemon=False,
metavar='<regexp>',
help='Exclude target roots that match these regexes.')
register(
'--subproject-roots',
type=list,
advanced=True,
default=[],
help=
'Paths that correspond with build roots for any subproject that this '
'project depends on.')
register(
'--owner-of',
type=list,
member_type=file_option,
default=[],
daemon=False,
metavar='<path>',
help='Select the targets that own these files. '
'This is the third target calculation strategy along with the --changed-* '
'options and specifying the targets directly. These three types of target '
'selection are mutually exclusive.')
# These logging options are registered in the bootstrap phase so that plugins can log during
# registration and not so that their values can be interpolated in configs.
register('-d',
'--logdir',
advanced=True,
metavar='<dir>',
help='Write logs to files under this directory.')
# This facilitates bootstrap-time configuration of pantsd usage such that we can
# determine whether or not to use the Pailgun client to invoke a given pants run
# without resorting to heavier options parsing.
register(
'--enable-pantsd',
advanced=True,
type=bool,
default=False,
help=
'Enables use of the pants daemon (and implicitly, the v2 engine). (Beta)'
)
# Whether or not to make necessary arrangements to have concurrent runs in pants.
# In practice, this means that if this is set, a run will not even try to use pantsd.
# NB: Eventually, we would like to deprecate this flag in favor of making pantsd runs parallelizable.
register(
'--concurrent',
advanced=True,
type=bool,
default=False,
daemon=False,
help=
'Enable concurrent runs of pants. Without this enabled, pants will '
'start up all concurrent invocations (e.g. in other terminals) without pantsd. '
'Enabling this option requires parallel pants invocations to block on the first'
)
# Shutdown pantsd after the current run.
# This needs to be accessed at the same time as enable_pantsd,
# so we register it at bootstrap time.
register(
'--shutdown-pantsd-after-run',
advanced=True,
type=bool,
default=False,
help=
'Create a new pantsd server, and use it, and shut it down immediately after. '
'If pantsd is already running, it will shut it down and spawn a new instance (Beta)'
)
# NB: We really don't want this option to invalidate the daemon, because different clients might have
# different needs. For instance, an IDE might have a very long timeout because it only wants to refresh
# a project in the background, while a user might want a shorter timeout for interactivity.
register(
'--pantsd-timeout-when-multiple-invocations',
advanced=True,
type=float,
default=60.0,
daemon=False,
help=
'The maximum amount of time to wait for the invocation to start until '
'raising a timeout exception. '
'Because pantsd currently does not support parallel runs, '
'any prior running Pants command must be finished for the current one to start. '
'To never timeout, use the value -1.')
# These facilitate configuring the native engine.
register(
'--native-engine-visualize-to',
advanced=True,
default=None,
type=dir_option,
daemon=False,
help=
'A directory to write execution and rule graphs to as `dot` files. The contents '
'of the directory will be overwritten if any filenames collide.')
register(
'--print-exception-stacktrace',
advanced=True,
type=bool,
help=
'Print to console the full exception stack trace if encountered.')
# BinaryUtil options.
register(
'--binaries-baseurls',
type=list,
advanced=True,
default=['https://binaries.pantsbuild.org'],
help='List of URLs from which binary tools are downloaded. URLs are '
'searched in order until the requested path is found.')
register(
'--binaries-fetch-timeout-secs',
type=int,
default=30,
advanced=True,
daemon=False,
help=
'Timeout in seconds for URL reads when fetching binary tools from the '
'repos specified by --baseurls.')
register(
'--binaries-path-by-id',
type=dict,
advanced=True,
help=
("Maps output of uname for a machine to a binary search path: "
"(sysname, id) -> (os, arch), e.g. {('darwin', '15'): ('mac', '10.11'), "
"('linux', 'arm32'): ('linux', 'arm32')}."))
register(
'--allow-external-binary-tool-downloads',
type=bool,
default=True,
advanced=True,
help=
"If False, require BinaryTool subclasses to download their contents from urls "
"generated from --binaries-baseurls, even if the tool has an external url "
"generator. This can be necessary if using Pants in an environment which cannot "
"contact the wider Internet.")
# Pants Daemon options.
register('--pantsd-pailgun-host',
advanced=True,
default='127.0.0.1',
help='The host to bind the pants nailgun server to.')
register(
'--pantsd-pailgun-port',
advanced=True,
type=int,
default=0,
help=
'The port to bind the pants nailgun server to. Defaults to a random port.'
)
# TODO(#7514): Make this default to 1.0 seconds if stdin is a tty!
register(
'--pantsd-pailgun-quit-timeout',
advanced=True,
type=float,
default=5.0,
help=
'The length of time (in seconds) to wait for further output after sending a '
'signal to the remote pantsd process before killing it.')
register('--pantsd-log-dir',
advanced=True,
default=None,
help='The directory to log pantsd output to.')
register(
'--pantsd-invalidation-globs',
advanced=True,
type=list,
default=[],
help=
'Filesystem events matching any of these globs will trigger a daemon restart.'
)
# Watchman options.
register('--watchman-version',
advanced=True,
default='4.9.0-pants1',
help='Watchman version.')
register(
'--watchman-supportdir',
advanced=True,
default='bin/watchman',
help=
'Find watchman binaries under this dir. Used as part of the path to lookup '
'the binary with --binaries-baseurls and --pants-bootstrapdir.')
register(
'--watchman-startup-timeout',
type=float,
advanced=True,
default=30.0,
help=
'The watchman socket timeout (in seconds) for the initial `watch-project` command. '
'This may need to be set higher for larger repos due to watchman startup cost.'
)
register(
'--watchman-socket-timeout',
type=float,
advanced=True,
default=0.1,
help=
'The watchman client socket timeout in seconds. Setting this to too high a '
'value can negatively impact the latency of runs forked by pantsd.'
)
register(
'--watchman-socket-path',
type=str,
advanced=True,
default=None,
help=
'The path to the watchman UNIX socket. This can be overridden if the default '
'absolute path length exceeds the maximum allowed by the OS.')
# This option changes the parser behavior in a fundamental way (which currently invalidates
# all caches), and needs to be parsed out early, so we make it a bootstrap option.
register('--build-file-imports',
choices=['allow', 'warn', 'error'],
default='warn',
advanced=True,
help='Whether to allow import statements in BUILD files')
register(
'--local-store-dir',
advanced=True,
help="Directory to use for engine's local file store.",
# This default is also hard-coded into the engine's rust code in
# fs::Store::default_path
default=os.path.expanduser('~/.cache/pants/lmdb_store'))
register(
'--remote-execution',
advanced=True,
type=bool,
default=DEFAULT_EXECUTION_OPTIONS.remote_execution,
help="Enables remote workers for increased parallelism. (Alpha)")
register(
'--remote-store-server',
advanced=True,
type=list,
default=[],
help=
'host:port of grpc server to use as remote execution file store.')
register(
'--remote-store-thread-count',
type=int,
advanced=True,
default=DEFAULT_EXECUTION_OPTIONS.remote_store_thread_count,
help=
'Thread count to use for the pool that interacts with the remote file store.'
)
register(
'--remote-execution-server',
advanced=True,
help=
'host:port of grpc server to use as remote execution scheduler.')
register(
'--remote-store-chunk-bytes',
type=int,
advanced=True,
default=DEFAULT_EXECUTION_OPTIONS.remote_store_chunk_bytes,
help=
'Size in bytes of chunks transferred to/from the remote file store.'
)
register(
'--remote-store-chunk-upload-timeout-seconds',
type=int,
advanced=True,
default=DEFAULT_EXECUTION_OPTIONS.
remote_store_chunk_upload_timeout_seconds,
help=
'Timeout (in seconds) for uploads of individual chunks to the remote file store.'
)
register(
'--remote-store-rpc-retries',
type=int,
advanced=True,
default=DEFAULT_EXECUTION_OPTIONS.remote_store_rpc_retries,
help=
'Number of times to retry any RPC to the remote store before giving up.'
)
register(
'--remote-execution-process-cache-namespace',
advanced=True,
help="The cache namespace for remote process execution. "
"Bump this to invalidate every artifact's remote execution. "
"This is the remote execution equivalent of the legacy cache-key-gen-version "
"flag.")
register(
'--remote-instance-name',
advanced=True,
help=
'Name of the remote execution instance to use. Used for routing within '
'--remote-execution-server and --remote-store-server.')
register(
'--remote-ca-certs-path',
advanced=True,
help=
'Path to a PEM file containing CA certificates used for verifying secure '
'connections to --remote-execution-server and --remote-store-server. '
'If not specified, TLS will not be used.')
register(
'--remote-oauth-bearer-token-path',
advanced=True,
help=
'Path to a file containing an oauth token to use for grpc connections to '
'--remote-execution-server and --remote-store-server. If not specified, no '
'authorization will be performed.')
register(
'--remote-execution-extra-platform-properties',
advanced=True,
help='Platform properties to set on remote execution requests. '
'Format: property=value. Multiple values should be specified as multiple '
'occurrences of this flag. Pants itself may add additional platform properties.',
type=list,
default=[])
# This should eventually deprecate the RunTracker worker count, which is used for legacy cache
# lookups via CacheSetup in TaskBase.
register(
'--process-execution-parallelism',
type=int,
dest='local_execution_parallelism',
removal_version='1.20.0.dev2',
advanced=True,
removal_hint=
'Use --process-execution-local-parallelism, and/or --process-execution-remote-parallelism instead.',
help='Number of concurrent processes that may be executed locally.'
)
register(
'--process-execution-local-parallelism',
type=int,
default=DEFAULT_EXECUTION_OPTIONS.
process_execution_local_parallelism,
advanced=True,
help='Number of concurrent processes that may be executed locally.'
)
register(
'--process-execution-remote-parallelism',
type=int,
default=DEFAULT_EXECUTION_OPTIONS.
process_execution_remote_parallelism,
advanced=True,
help='Number of concurrent processes that may be executed remotely.'
)
register(
'--process-execution-cleanup-local-dirs',
type=bool,
default=True,
advanced=True,
help=
'Whether or not to cleanup directories used for local process execution '
'(primarily useful for e.g. debugging).')
register(
'--process-execution-speculation-delay',
type=float,
default=DEFAULT_EXECUTION_OPTIONS.
process_execution_speculation_delay,
advanced=True,
help=
'Number of seconds to wait before speculating a second request for a slow process. '
' see `--process-execution-speculation-strategy`')
register(
'--process-execution-speculation-strategy',
choices=['remote_first', 'local_first', 'none'],
default=DEFAULT_EXECUTION_OPTIONS.
process_execution_speculation_strategy,
help=
"Speculate a second request for an underlying process if the first one does not complete within "
'`--process-execution-speculation-delay` seconds.\n'
'`local_first` (default): Try to run the process locally first, '
'and fall back to remote execution if available.\n'
'`remote_first`: Run the process on the remote execution backend if available, '
'and fall back to the local host if remote calls take longer than the speculation timeout.\n'
'`none`: Do not speculate about long running processes.',
advanced=True)
register(
'--process-execution-use-local-cache',
type=bool,
default=True,
advanced=True,
help=
'Whether to keep process executions in a local cache persisted to disk.'
)
def assert_pants_requirement(self, python_requirement_library):
self.assertIsInstance(python_requirement_library, PythonRequirementLibrary)
pants_requirement = PythonRequirement('pantsbuild.pants=={}'.format(pants_version()))
self.assertEqual([pants_requirement.requirement],
list(pr.requirement for pr in python_requirement_library.payload.requirements))
def __call__(self, name=None, dist=None):
"""
:param string name: The name to use for the target, defaults to the dist name if specified and
otherwise the parent dir name.
:param string dist: The pants dist to create a requirement for. This must be a
'pantsbuild.pants*' distribution; eg:
'pantsbuild.pants.contrib.python.checks'.
"""
name = name or dist or os.path.basename(self._parse_context.rel_path)
dist = dist or 'pantsbuild.pants'
if not (dist == 'pantsbuild.pants' or dist.startswith('pantsbuild.pants.')):
target = Address(spec_path=self._parse_context.rel_path, target_name=name)
raise TargetDefinitionException(target=target,
msg='The {} target only works for pantsbuild.pants '
'distributions, given {}'.format(self.alias, dist))
requirement = PythonRequirement(requirement="{key}=={version}".format(key=dist, version=pants_version()))
self._parse_context.create_object('python_requirement_library',
name=name,
requirements=[requirement])
def test_version(self): self.assertEqual(pants_version(), _VERSION)
def register_bootstrap_options(cls, register):
"""Register bootstrap options.
"Bootstrap options" are a small set of options whose values are useful when registering other
options. Therefore we must bootstrap them early, before other options are registered, let
alone parsed.
Bootstrap option values can be interpolated into the config file, and can be referenced
programatically in registration code, e.g., as register.bootstrap.pants_workdir.
Note that regular code can also access these options as normal global-scope options. Their
status as "bootstrap options" is only pertinent during option registration.
"""
buildroot = get_buildroot()
default_distdir_name = 'dist'
default_distdir = os.path.join(buildroot, default_distdir_name)
default_rel_distdir = '/{}/'.format(default_distdir_name)
# Although logging supports the WARN level, its not documented and could conceivably be yanked.
# Since pants has supported 'warn' since inception, leave the 'warn' choice as-is but explicitly
# setup a 'WARN' logging level name that maps to 'WARNING'.
logging.addLevelName(logging.WARNING, 'WARN')
register('-l', '--level', choices=['debug', 'info', 'warn'], default='info', recursive=True,
help='Set the logging level.')
register('-q', '--quiet', type=bool, recursive=True, daemon=False,
help='Squelches most console output. NOTE: Some tasks default to behaving quietly: '
'inverting this option supports making them noisier than they would be otherwise.')
# Not really needed in bootstrap options, but putting it here means it displays right
# after -l and -q in help output, which is conveniently contextual.
register('--colors', type=bool, default=sys.stdout.isatty(), recursive=True, daemon=False,
help='Set whether log messages are displayed in color.')
# Pants code uses this only to verify that we are of the requested version. However
# setup scripts, runner scripts, IDE plugins, etc., may grep this out of pants.ini
# and use it to select the right version.
# Note that to print the version of the pants instance you're running, use -v, -V or --version.
register('--pants-version', advanced=True, default=pants_version(),
help='Use this pants version.')
register('--plugins', advanced=True, type=list, help='Load these plugins.')
register('--plugin-cache-dir', advanced=True,
default=os.path.join(get_pants_cachedir(), 'plugins'),
help='Cache resolved plugin requirements here.')
register('--backend-packages', advanced=True, type=list,
default=['pants.backend.graph_info',
'pants.backend.python',
'pants.backend.jvm',
'pants.backend.native',
'pants.backend.codegen.antlr.java',
'pants.backend.codegen.antlr.python',
'pants.backend.codegen.jaxb',
'pants.backend.codegen.protobuf.java',
'pants.backend.codegen.ragel.java',
'pants.backend.codegen.thrift.java',
'pants.backend.codegen.thrift.python',
'pants.backend.codegen.wire.java',
'pants.backend.project_info'],
help='Load backends from these packages that are already on the path. '
'Add contrib and custom backends to this list.')
register('--pants-bootstrapdir', advanced=True, metavar='<dir>', default=get_pants_cachedir(),
help='Use this dir for global cache.')
register('--pants-configdir', advanced=True, metavar='<dir>', default=get_pants_configdir(),
help='Use this dir for global config files.')
register('--pants-workdir', advanced=True, metavar='<dir>',
default=os.path.join(buildroot, '.pants.d'),
help='Write intermediate output files to this dir.')
register('--pants-supportdir', advanced=True, metavar='<dir>',
default=os.path.join(buildroot, 'build-support'),
help='Use support files from this dir.')
register('--pants-distdir', advanced=True, metavar='<dir>',
default=default_distdir,
help='Write end-product artifacts to this dir. If you modify this path, you '
'should also update --build-ignore and --pants-ignore to include the '
'custom dist dir path as well.')
register('--pants-subprocessdir', advanced=True, default=os.path.join(buildroot, '.pids'),
help='The directory to use for tracking subprocess metadata, if any. This should '
'live outside of the dir used by `--pants-workdir` to allow for tracking '
'subprocesses that outlive the workdir data (e.g. `./pants server`).')
register('--pants-config-files', advanced=True, type=list, daemon=False,
default=[get_default_pants_config_file()], help='Paths to Pants config files.')
# TODO: Deprecate the --pantsrc/--pantsrc-files options? This would require being able
# to set extra config file locations in an initial bootstrap config file.
register('--pantsrc', advanced=True, type=bool, default=True,
help='Use pantsrc files.')
register('--pantsrc-files', advanced=True, type=list, metavar='<path>', daemon=False,
default=['/etc/pantsrc', '~/.pants.rc'],
help='Override config with values from these files. '
'Later files override earlier ones.')
register('--pythonpath', advanced=True, type=list,
help='Add these directories to PYTHONPATH to search for plugins.')
register('--target-spec-file', type=list, dest='target_spec_files', daemon=False,
help='Read additional specs from this file, one per line')
register('--verify-config', type=bool, default=True, daemon=False,
help='Verify that all config file values correspond to known options.')
register('--build-ignore', advanced=True, type=list, fromfile=True,
default=['.*/', default_rel_distdir, 'bower_components/',
'node_modules/', '*.egg-info/'],
help='Paths to ignore when identifying BUILD files. '
'This does not affect any other filesystem operations. '
'Patterns use the gitignore pattern syntax (https://git-scm.com/docs/gitignore).')
register('--pants-ignore', advanced=True, type=list, fromfile=True,
default=['.*/', default_rel_distdir],
help='Paths to ignore for all filesystem operations performed by pants '
'(e.g. BUILD file scanning, glob matching, etc). '
'Patterns use the gitignore syntax (https://git-scm.com/docs/gitignore).')
register('--glob-expansion-failure', type=str,
choices=GlobMatchErrorBehavior.allowed_values,
default=GlobMatchErrorBehavior.default_option_value,
help="Raise an exception if any targets declaring source files "
"fail to match any glob provided in the 'sources' argument.")
register('--exclude-target-regexp', advanced=True, type=list, default=[], daemon=False,
metavar='<regexp>', help='Exclude target roots that match these regexes.')
register('--subproject-roots', type=list, advanced=True, fromfile=True, default=[],
help='Paths that correspond with build roots for any subproject that this '
'project depends on.')
register('--owner-of', type=list, default=[], metavar='<path>',
help='Select the targets that own these files. '
'This is the third target calculation strategy along with the --changed '
'options and specifying the targets directly. These three types of target '
'selection are mutually exclusive.')
# These logging options are registered in the bootstrap phase so that plugins can log during
# registration and not so that their values can be interpolated in configs.
register('-d', '--logdir', advanced=True, metavar='<dir>',
help='Write logs to files under this directory.')
# This facilitates bootstrap-time configuration of pantsd usage such that we can
# determine whether or not to use the Pailgun client to invoke a given pants run
# without resorting to heavier options parsing.
register('--enable-pantsd', advanced=True, type=bool, default=False,
help='Enables use of the pants daemon (and implicitly, the v2 engine). (Beta)')
# These facilitate configuring the native engine.
register('--native-engine-visualize-to', advanced=True, default=None, type=dir_option, daemon=False,
help='A directory to write execution and rule graphs to as `dot` files. The contents '
'of the directory will be overwritten if any filenames collide.')
register('--print-exception-stacktrace', advanced=True, type=bool,
help='Print to console the full exception stack trace if encountered.')
# BinaryUtil options.
register('--binaries-baseurls', type=list, advanced=True,
default=['https://binaries.pantsbuild.org'],
help='List of URLs from which binary tools are downloaded. URLs are '
'searched in order until the requested path is found.')
register('--binaries-fetch-timeout-secs', type=int, default=30, advanced=True, daemon=False,
help='Timeout in seconds for URL reads when fetching binary tools from the '
'repos specified by --baseurls.')
register('--binaries-path-by-id', type=dict, advanced=True,
help=("Maps output of uname for a machine to a binary search path: "
"(sysname, id) -> (os, arch), e.g. {('darwin', '15'): ('mac', '10.11'), "
"('linux', 'arm32'): ('linux', 'arm32')}."))
register('--allow-external-binary-tool-downloads', type=bool, default=True, advanced=True,
help="If False, require BinaryTool subclasses to download their contents from urls "
"generated from --binaries-baseurls, even if the tool has an external url "
"generator. This can be necessary if using Pants in an environment which cannot "
"contact the wider Internet.")
# Pants Daemon options.
register('--pantsd-pailgun-host', advanced=True, default='127.0.0.1',
help='The host to bind the pants nailgun server to.')
register('--pantsd-pailgun-port', advanced=True, type=int, default=0,
help='The port to bind the pants nailgun server to. Defaults to a random port.')
register('--pantsd-log-dir', advanced=True, default=None,
help='The directory to log pantsd output to.')
register('--pantsd-fs-event-workers', advanced=True, type=int, default=4,
help='The number of workers to use for the filesystem event service executor pool.')
register('--pantsd-invalidation-globs', advanced=True, type=list, fromfile=True, default=[],
help='Filesystem events matching any of these globs will trigger a daemon restart.')
# Watchman options.
register('--watchman-version', advanced=True, default='4.9.0-pants1', help='Watchman version.')
register('--watchman-supportdir', advanced=True, default='bin/watchman',
help='Find watchman binaries under this dir. Used as part of the path to lookup '
'the binary with --binaries-baseurls and --pants-bootstrapdir.')
register('--watchman-startup-timeout', type=float, advanced=True, default=30.0,
help='The watchman socket timeout (in seconds) for the initial `watch-project` command. '
'This may need to be set higher for larger repos due to watchman startup cost.')
register('--watchman-socket-timeout', type=float, advanced=True, default=5.0,
help='The watchman client socket timeout in seconds.')
register('--watchman-socket-path', type=str, advanced=True, default=None,
help='The path to the watchman UNIX socket. This can be overridden if the default '
'absolute path length exceeds the maximum allowed by the OS.')
# This option changes the parser behavior in a fundamental way (which currently invalidates
# all caches), and needs to be parsed out early, so we make it a bootstrap option.
register('--build-file-imports', choices=['allow', 'warn', 'error'], default='warn',
help='Whether to allow import statements in BUILD files')
register('--remote-store-server',
help='host:port of grpc server to use as remote execution file store')
register('--remote-execution-server',
help='host:port of grpc server to use as remote execution scheduler')
def register_bootstrap_options(cls, register):
"""Register bootstrap options.
"Bootstrap options" are a small set of options whose values are useful when registering other
options. Therefore we must bootstrap them early, before other options are registered, let
alone parsed.
Bootstrap option values can be interpolated into the config file, and can be referenced
programatically in registration code, e.g., as register.bootstrap.pants_workdir.
Note that regular code can also access these options as normal global-scope options. Their
status as "bootstrap options" is only pertinent during option registration.
"""
buildroot = get_buildroot()
default_distdir_name = 'dist'
default_distdir = os.path.join(buildroot, default_distdir_name)
default_rel_distdir = '/{}/'.format(default_distdir_name)
# Although logging supports the WARN level, its not documented and could conceivably be yanked.
# Since pants has supported 'warn' since inception, leave the 'warn' choice as-is but explicitly
# setup a 'WARN' logging level name that maps to 'WARNING'.
logging.addLevelName(logging.WARNING, 'WARN')
register('-l',
'--level',
choices=['debug', 'info', 'warn'],
default='info',
recursive=True,
help='Set the logging level.')
register(
'-q',
'--quiet',
type=bool,
recursive=True,
daemon=False,
help=
'Squelches most console output. NOTE: Some tasks default to behaving quietly: '
'inverting this option supports making them noisier than they would be otherwise.'
)
# Not really needed in bootstrap options, but putting it here means it displays right
# after -l and -q in help output, which is conveniently contextual.
register('--colors',
type=bool,
default=sys.stdout.isatty(),
recursive=True,
daemon=False,
help='Set whether log messages are displayed in color.')
# Pants code uses this only to verify that we are of the requested version. However
# setup scripts, runner scripts, IDE plugins, etc., may grep this out of pants.ini
# and use it to select the right version.
# Note that to print the version of the pants instance you're running, use -v, -V or --version.
register('--pants-version',
advanced=True,
default=pants_version(),
help='Use this pants version.')
register('--plugins',
advanced=True,
type=list,
help='Load these plugins.')
register('--plugin-cache-dir',
advanced=True,
default=os.path.join(get_pants_cachedir(), 'plugins'),
help='Cache resolved plugin requirements here.')
register(
'--backend-packages',
advanced=True,
type=list,
default=[
'pants.backend.graph_info', 'pants.backend.python',
'pants.backend.jvm', 'pants.backend.native',
'pants.backend.codegen.antlr.java',
'pants.backend.codegen.antlr.python',
'pants.backend.codegen.jaxb',
'pants.backend.codegen.protobuf.java',
'pants.backend.codegen.ragel.java',
'pants.backend.codegen.thrift.java',
'pants.backend.codegen.thrift.python',
'pants.backend.codegen.wire.java', 'pants.backend.project_info'
],
help=
'Load backends from these packages that are already on the path. '
'Add contrib and custom backends to this list.')
register('--pants-bootstrapdir',
advanced=True,
metavar='<dir>',
default=get_pants_cachedir(),
help='Use this dir for global cache.')
register('--pants-configdir',
advanced=True,
metavar='<dir>',
default=get_pants_configdir(),
help='Use this dir for global config files.')
register('--pants-workdir',
advanced=True,
metavar='<dir>',
default=os.path.join(buildroot, '.pants.d'),
help='Write intermediate output files to this dir.')
register('--pants-supportdir',
advanced=True,
metavar='<dir>',
default=os.path.join(buildroot, 'build-support'),
help='Use support files from this dir.')
register(
'--pants-distdir',
advanced=True,
metavar='<dir>',
default=default_distdir,
help=
'Write end-product artifacts to this dir. If you modify this path, you '
'should also update --build-ignore and --pants-ignore to include the '
'custom dist dir path as well.')
register(
'--pants-subprocessdir',
advanced=True,
default=os.path.join(buildroot, '.pids'),
help=
'The directory to use for tracking subprocess metadata, if any. This should '
'live outside of the dir used by `--pants-workdir` to allow for tracking '
'subprocesses that outlive the workdir data (e.g. `./pants server`).'
)
register('--pants-config-files',
advanced=True,
type=list,
daemon=False,
default=[get_default_pants_config_file()],
help='Paths to Pants config files.')
# TODO: Deprecate the --pantsrc/--pantsrc-files options? This would require being able
# to set extra config file locations in an initial bootstrap config file.
register('--pantsrc',
advanced=True,
type=bool,
default=True,
help='Use pantsrc files.')
register('--pantsrc-files',
advanced=True,
type=list,
metavar='<path>',
daemon=False,
default=['/etc/pantsrc', '~/.pants.rc'],
help='Override config with values from these files. '
'Later files override earlier ones.')
register(
'--pythonpath',
advanced=True,
type=list,
help='Add these directories to PYTHONPATH to search for plugins.')
register('--target-spec-file',
type=list,
dest='target_spec_files',
daemon=False,
help='Read additional specs from this file, one per line')
register(
'--verify-config',
type=bool,
default=True,
daemon=False,
help=
'Verify that all config file values correspond to known options.')
register(
'--build-ignore',
advanced=True,
type=list,
fromfile=True,
default=[
'.*/', default_rel_distdir, 'bower_components/',
'node_modules/', '*.egg-info/'
],
help='Paths to ignore when identifying BUILD files. '
'This does not affect any other filesystem operations. '
'Patterns use the gitignore pattern syntax (https://git-scm.com/docs/gitignore).'
)
register(
'--pants-ignore',
advanced=True,
type=list,
fromfile=True,
default=['.*/', default_rel_distdir],
help=
'Paths to ignore for all filesystem operations performed by pants '
'(e.g. BUILD file scanning, glob matching, etc). '
'Patterns use the gitignore syntax (https://git-scm.com/docs/gitignore).'
)
register('--exclude-target-regexp',
advanced=True,
type=list,
default=[],
daemon=False,
metavar='<regexp>',
help='Exclude target roots that match these regexes.')
register(
'--subproject-roots',
type=list,
advanced=True,
fromfile=True,
default=[],
help=
'Paths that correspond with build roots for any subproject that this '
'project depends on.')
# These logging options are registered in the bootstrap phase so that plugins can log during
# registration and not so that their values can be interpolated in configs.
register('-d',
'--logdir',
advanced=True,
metavar='<dir>',
help='Write logs to files under this directory.')
# This facilitates bootstrap-time configuration of pantsd usage such that we can
# determine whether or not to use the Pailgun client to invoke a given pants run
# without resorting to heavier options parsing.
register(
'--enable-pantsd',
advanced=True,
type=bool,
default=False,
help=
'Enables use of the pants daemon (and implicitly, the v2 engine). (Beta)'
)
# These facilitate configuring the native engine.
register(
'--native-engine-visualize-to',
advanced=True,
default=None,
type=dir_option,
daemon=False,
help=
'A directory to write execution and rule graphs to as `dot` files. The contents '
'of the directory will be overwritten if any filenames collide.')
# BinaryUtil options.
register(
'--binaries-baseurls',
type=list,
advanced=True,
default=['https://binaries.pantsbuild.org'],
help='List of URLs from which binary tools are downloaded. URLs are '
'searched in order until the requested path is found.')
register(
'--binaries-fetch-timeout-secs',
type=int,
default=30,
advanced=True,
daemon=False,
help=
'Timeout in seconds for URL reads when fetching binary tools from the '
'repos specified by --baseurls.')
register(
'--binaries-path-by-id',
type=dict,
advanced=True,
help=
("Maps output of uname for a machine to a binary search path: "
"(sysname, id) -> (os, arch), e.g. {('darwin', '15'): ('mac', '10.11'), "
"('linux', 'arm32'): ('linux', 'arm32')}."))
register(
'--allow-external-binary-tool-downloads',
type=bool,
default=True,
advanced=True,
help=
"If False, require BinaryTool subclasses to download their contents from urls "
"generated from --binaries-baseurls, even if the tool has an external url "
"generator. This can be necessary if using Pants in an environment which cannot "
"contact the wider Internet.")
# Pants Daemon options.
register('--pantsd-pailgun-host',
advanced=True,
default='127.0.0.1',
help='The host to bind the pants nailgun server to.')
register(
'--pantsd-pailgun-port',
advanced=True,
type=int,
default=0,
help=
'The port to bind the pants nailgun server to. Defaults to a random port.'
)
register('--pantsd-log-dir',
advanced=True,
default=None,
help='The directory to log pantsd output to.')
register(
'--pantsd-fs-event-workers',
advanced=True,
type=int,
default=4,
help=
'The number of workers to use for the filesystem event service executor pool.'
)
register(
'--pantsd-invalidation-globs',
advanced=True,
type=list,
fromfile=True,
default=[],
help=
'Filesystem events matching any of these globs will trigger a daemon restart.'
)
# Watchman options.
register('--watchman-version',
advanced=True,
default='4.9.0-pants1',
help='Watchman version.')
register(
'--watchman-supportdir',
advanced=True,
default='bin/watchman',
help=
'Find watchman binaries under this dir. Used as part of the path to lookup '
'the binary with --binaries-baseurls and --pants-bootstrapdir.')
register(
'--watchman-startup-timeout',
type=float,
advanced=True,
default=30.0,
help=
'The watchman socket timeout (in seconds) for the initial `watch-project` command. '
'This may need to be set higher for larger repos due to watchman startup cost.'
)
register('--watchman-socket-timeout',
type=float,
advanced=True,
default=5.0,
help='The watchman client socket timeout in seconds.')
register(
'--watchman-socket-path',
type=str,
advanced=True,
default=None,
help=
'The path to the watchman UNIX socket. This can be overridden if the default '
'absolute path length exceeds the maximum allowed by the OS.')
# This option changes the parser behavior in a fundamental way (which currently invalidates
# all caches), and needs to be parsed out early, so we make it a bootstrap option.
register('--build-file-imports',
choices=['allow', 'warn', 'error'],
default='warn',
help='Whether to allow import statements in BUILD files')
def register_bootstrap_options(cls, register):
"""Register bootstrap options.
"Bootstrap options" are a small set of options whose values are useful when registering other
options. Therefore we must bootstrap them early, before other options are registered, let
alone parsed.
Bootstrap option values can be interpolated into the config file, and can be referenced
programatically in registration code, e.g., as register.bootstrap.pants_workdir.
Note that regular code can also access these options as normal global-scope options. Their
status as "bootstrap options" is only pertinent during option registration.
"""
buildroot = get_buildroot()
# Although logging supports the WARN level, its not documented and could conceivably be yanked.
# Since pants has supported 'warn' since inception, leave the 'warn' choice as-is but explicitly
# setup a 'WARN' logging level name that maps to 'WARNING'.
logging.addLevelName(logging.WARNING, "WARN")
register(
"-l",
"--level",
choices=["debug", "info", "warn"],
default="info",
recursive=True,
help="Set the logging level.",
)
register("-q", "--quiet", action="store_true", recursive=True, help="Squelches most console output.")
# Not really needed in bootstrap options, but putting it here means it displays right
# after -l and -q in help output, which is conveniently contextual.
register(
"--colors",
action="store_true",
default=True,
recursive=True,
help="Set whether log messages are displayed in color.",
)
# Pants code uses this only to verify that we are of the requested version. However
# setup scripts, runner scripts, IDE plugins, etc., may grep this out of pants.ini
# and use it to select the right version.
# Note that to print the version of the pants instance you're running, use -v, -V or --version.
register("--pants-version", advanced=True, default=pants_version(), help="Use this pants version.")
register("--plugins", advanced=True, type=list_option, help="Load these plugins.")
register(
"--plugin-cache-dir",
advanced=True,
default=os.path.join(get_pants_cachedir(), "plugins"),
help="Cache resolved plugin requirements here.",
)
register(
"--backend-packages",
advanced=True,
type=list_option,
help="Load backends from these packages that are already on the path.",
)
register(
"--pants-bootstrapdir",
advanced=True,
metavar="<dir>",
default=get_pants_cachedir(),
help="Use this dir for global cache.",
)
register(
"--pants-configdir",
advanced=True,
metavar="<dir>",
default=get_pants_configdir(),
help="Use this dir for global config files.",
)
register(
"--pants-workdir",
advanced=True,
metavar="<dir>",
default=os.path.join(buildroot, ".pants.d"),
help="Write intermediate output files to this dir.",
)
register(
"--pants-supportdir",
advanced=True,
metavar="<dir>",
default=os.path.join(buildroot, "build-support"),
help="Use support files from this dir.",
)
register(
"--pants-distdir",
advanced=True,
metavar="<dir>",
default=os.path.join(buildroot, "dist"),
help="Write end-product artifacts to this dir.",
)
register(
"--config-override",
advanced=True,
action="append",
metavar="<path>",
help="A second config file, to override pants.ini.",
)
register("--pantsrc", advanced=True, action="store_true", default=True, help="Use pantsrc files.")
register(
"--pantsrc-files",
advanced=True,
action="append",
metavar="<path>",
default=["/etc/pantsrc", "~/.pants.rc"],
help="Override config with values from these files. " "Later files override earlier ones.",
)
register(
"--pythonpath",
advanced=True,
action="append",
help="Add these directories to PYTHONPATH to search for plugins.",
)
register(
"--target-spec-file",
action="append",
dest="target_spec_files",
help="Read additional specs from this file, one per line",
)
# These logging options are registered in the bootstrap phase so that plugins can log during
# registration and not so that their values can be interpolated in configs.
register("-d", "--logdir", advanced=True, metavar="<dir>", help="Write logs to files under this directory.")
# This facilitates bootstrap-time configuration of pantsd usage such that we can
# determine whether or not to use the Pailgun client to invoke a given pants run
# without resorting to heavier options parsing.
register(
"--enable-pantsd",
advanced=True,
action="store_true",
default=False,
help="Enables use of the pants daemon. (Beta)",
)
def register_bootstrap_options(cls, register):
"""Register bootstrap options.
"Bootstrap options" are a small set of options whose values are useful when registering other
options. Therefore we must bootstrap them early, before other options are registered, let
alone parsed.
Bootstrap option values can be interpolated into the config file, and can be referenced
programmatically in registration code, e.g., as register.bootstrap.pants_workdir.
Note that regular code can also access these options as normal global-scope options. Their
status as "bootstrap options" is only pertinent during option registration.
"""
buildroot = get_buildroot()
default_distdir_name = "dist"
default_rel_distdir = f"/{default_distdir_name}/"
register(
"-l",
"--level",
type=LogLevel,
default=LogLevel.INFO,
recursive=True,
help="Set the logging level.",
)
register(
"--log-show-rust-3rdparty",
type=bool,
default=False,
advanced=True,
help=
"Whether to show/hide logging done by 3rdparty rust crates used by the pants "
"engine.",
)
# Toggles v1/v2 `Task` vs `@rule` pipelines on/off.
# Having these in bootstrap options allows them to affect registration of non-bootstrap options.
register("--v1",
advanced=True,
type=bool,
default=True,
help="Enables execution of v1 Tasks.")
register(
"--v2",
advanced=True,
type=bool,
default=True,
help="Enables execution of v2 @goal_rules.",
)
# TODO(#7203): make a regexp option type!
register(
"--ignore-pants-warnings",
type=list,
member_type=str,
default=[],
advanced=True,
help="Regexps matching warning strings to ignore, e.g. "
'["DEPRECATED: scope some_scope will be removed"]. The regexps will be matched '
"from the start of the warning string, and will always be case-insensitive. "
"See the `warnings` module documentation for more background on these are used.",
)
register(
"--option-name-check-distance",
advanced=True,
type=int,
default=2,
help=
"The maximum Levenshtein distance to use when offering suggestions for invalid "
"option names.",
)
register(
"--pants-version",
advanced=True,
default=pants_version(),
help=
"Use this pants version. Note Pants code only uses this to verify that you are "
"using the requested version, as Pants cannot dynamically change the version it "
"is using once the program is already running. This option is useful to set in "
"your pants.toml, however, and then you can grep the value to select which "
"version to use for setup scripts (e.g. `./pants`), runner scripts, IDE plugins, "
"etc. For example, the setup script we distribute at https://www.pantsbuild.org/install.html#recommended-installation "
"uses this value to determine which Python version to run with. You may find the "
"version of the pants instance you are running using -v, -V, or --version.",
)
register(
"--pants-bin-name",
advanced=True,
default="./pants",
help="The name of the script or binary used to invoke pants. "
"Useful when printing help messages.",
)
register(
"--plugins",
advanced=True,
type=list,
help=
"Allow v1 backends to be loaded from these plugins. The default backends for "
"each plugin will be loaded automatically. Other backends in a plugin can be "
"loaded by listing them in --backend-packages.",
)
register(
"--plugins2",
advanced=True,
type=list,
help=
"Allow v2 backends to be loaded from these plugins. The default backends for "
"each plugin will be loaded automatically. Other backends in a plugin can be "
"loaded by listing them in --backend-packages.",
)
register(
"--plugins-force-resolve",
advanced=True,
type=bool,
default=False,
help="Re-resolve plugins even if previously resolved.",
)
register(
"--plugin-cache-dir",
advanced=True,
default=os.path.join(get_pants_cachedir(), "plugins"),
help="Cache resolved plugin requirements here.",
)
register(
"--backend-packages",
advanced=True,
type=list,
default=[
"pants.backend.graph_info",
"pants.backend.python",
"pants.backend.python.lint.isort",
"pants.backend.jvm",
"pants.backend.native",
"pants.backend.codegen.protobuf.java",
"pants.backend.codegen.thrift.java",
"pants.backend.codegen.thrift.python",
"pants.backend.codegen.grpcio.python",
"pants.backend.project_info",
"pants.cache",
],
help=
("Register v1 tasks from these backends. The backend packages must be present on "
"the PYTHONPATH, typically because they are in the Pants core dist, in a "
"plugin dist, or available as sources in the repo."),
)
register(
"--backend-packages2",
advanced=True,
type=list,
default=[],
help=
("Register v2 rules from these backends. The backend packages must be present on "
"the PYTHONPATH, typically because they are in the Pants core dist, in a "
"plugin dist, or available as sources in the repo."),
)
register(
"--pants-bootstrapdir",
advanced=True,
metavar="<dir>",
default=get_pants_cachedir(),
help="Use this dir for global cache.",
)
register(
"--pants-configdir",
advanced=True,
metavar="<dir>",
default=get_pants_configdir(),
help="Use this dir for global config files.",
)
register(
"--pants-workdir",
advanced=True,
metavar="<dir>",
default=os.path.join(buildroot, ".pants.d"),
help="Write intermediate output files to this dir.",
)
register(
"--pants-physical-workdir-base",
advanced=True,
metavar="<dir>",
default=None,
help=
"When set, a base directory in which to store `--pants-workdir` contents. "
"If this option is a set, the workdir will be created as symlink into a "
"per-workspace subdirectory.",
)
register(
"--pants-supportdir",
advanced=True,
metavar="<dir>",
default=os.path.join(buildroot, "build-support"),
help="Use support files from this dir.",
)
register(
"--pants-distdir",
advanced=True,
metavar="<dir>",
default=os.path.join(buildroot, "dist"),
help="Write end-product artifacts to this dir.",
)
register(
"--pants-subprocessdir",
advanced=True,
default=os.path.join(buildroot, ".pids"),
help=
"The directory to use for tracking subprocess metadata, if any. This should "
"live outside of the dir used by `--pants-workdir` to allow for tracking "
"subprocesses that outlive the workdir data (e.g. `./pants server`).",
)
register(
"--pants-config-files",
advanced=True,
type=list,
daemon=False,
default=[get_default_pants_config_file()],
help="Paths to Pants config files.",
)
# TODO: Deprecate the --pantsrc/--pantsrc-files options? This would require being able
# to set extra config file locations in an initial bootstrap config file.
register("--pantsrc",
advanced=True,
type=bool,
default=True,
help="Use pantsrc files.")
register(
"--pantsrc-files",
advanced=True,
type=list,
metavar="<path>",
daemon=False,
default=["/etc/pantsrc", "~/.pants.rc"],
help="Override config with values from these files. "
"Later files override earlier ones.",
)
register(
"--pythonpath",
advanced=True,
type=list,
help="Add these directories to PYTHONPATH to search for plugins.",
)
register(
"--spec-file",
type=list,
dest="spec_files",
daemon=False,
help=
"Read additional specs from this file (e.g. target addresses or file names). "
"Each spec should be one per line.",
)
register(
"--verify-config",
type=bool,
default=True,
daemon=False,
advanced=True,
help=
"Verify that all config file values correspond to known options.",
)
register(
"--build-ignore",
advanced=True,
type=list,
default=[
".*/", "bower_components/", "node_modules/", "*.egg-info/"
],
help="Paths to ignore when identifying BUILD files. "
"This does not affect any other filesystem operations. "
"Patterns use the gitignore pattern syntax (https://git-scm.com/docs/gitignore).",
)
register(
"--pants-ignore",
advanced=True,
type=list,
member_type=str,
default=[".*/", default_rel_distdir],
help=
"Paths to ignore for all filesystem operations performed by pants "
"(e.g. BUILD file scanning, glob matching, etc). "
"Patterns use the gitignore syntax (https://git-scm.com/docs/gitignore). "
"The `--pants-distdir` and `--pants-workdir` locations are inherently ignored."
"--pants-ignore can be used in tandem with --pants-ignore-use-gitignore, and any rules "
"specified here apply after rules specified in a .gitignore file.",
)
register(
"--pants-ignore-use-gitignore",
advanced=True,
type=bool,
default=True,
help=
"Make use of a root .gitignore file when determining whether to ignore filesystem "
"operations performed by pants. If used together with `--pants-ignore`, any exclude/include "
"patterns specified there apply after .gitignore rules.",
)
register(
"--owners-not-found-behavior",
advanced=True,
type=OwnersNotFoundBehavior,
default=OwnersNotFoundBehavior.error,
help=
"What to do when file arguments do not have any owning target. This happens when there "
"are no targets whose `sources` fields include the file argument.",
)
register(
"--files-not-found-behavior",
advanced=True,
type=FileNotFoundBehavior,
default=FileNotFoundBehavior.warn,
help=
"What to do when files and globs specified in BUILD files, such as in the "
"`sources` field, cannot be found. This happens when the files do not exist on "
"your machine or when they are ignored by the `--pants-ignore` option.",
)
# TODO(#7203): make a regexp option type!
register(
"--exclude-target-regexp",
advanced=True,
type=list,
default=[],
daemon=False,
metavar="<regexp>",
help="Exclude target roots that match these regexes.",
)
register(
"--subproject-roots",
type=list,
advanced=True,
default=[],
help=
"Paths that correspond with build roots for any subproject that this "
"project depends on.",
)
# These logging options are registered in the bootstrap phase so that plugins can log during
# registration and not so that their values can be interpolated in configs.
register(
"-d",
"--logdir",
advanced=True,
metavar="<dir>",
help="Write logs to files under this directory.",
)
# This facilitates bootstrap-time configuration of pantsd usage such that we can
# determine whether or not to use the Pailgun client to invoke a given pants run
# without resorting to heavier options parsing.
register(
"--enable-pantsd",
advanced=True,
type=bool,
default=False,
help=
"Enables use of the pants daemon (and implicitly, the v2 engine). (Beta)",
)
# Whether or not to make necessary arrangements to have concurrent runs in pants.
# In practice, this means that if this is set, a run will not even try to use pantsd.
# NB: Eventually, we would like to deprecate this flag in favor of making pantsd runs parallelizable.
register(
"--concurrent",
advanced=True,
type=bool,
default=False,
daemon=False,
help=
"Enable concurrent runs of pants. Without this enabled, pants will "
"start up all concurrent invocations (e.g. in other terminals) without pantsd. "
"Enabling this option requires parallel pants invocations to block on the first",
)
# Calling pants command (inner run) from other pants command is unusual behaviour,
# and most users should never set this flag.
# It is automatically set by pants when an inner run is detected.
# Currently, pants commands with this option set don't use pantsd,
# but this effect should not be relied upon.
# This option allows us to know who was the parent of pants inner runs for informational purposes.
register(
"--parent-build-id",
advanced=True,
default=None,
help=
"The build ID of the other pants run which spawned this one, if any.",
)
# Shutdown pantsd after the current run.
# This needs to be accessed at the same time as enable_pantsd,
# so we register it at bootstrap time.
register(
"--shutdown-pantsd-after-run",
advanced=True,
type=bool,
default=False,
removal_version="1.29.0.dev2",
removal_hint=
"Not widely used, and will soon be rewritten to be inherent.",
help=
"Create a new pantsd server, and use it, and shut it down immediately after. "
"If pantsd is already running, it will shut it down and spawn a new instance (Beta)",
)
# NB: We really don't want this option to invalidate the daemon, because different clients might have
# different needs. For instance, an IDE might have a very long timeout because it only wants to refresh
# a project in the background, while a user might want a shorter timeout for interactivity.
register(
"--pantsd-timeout-when-multiple-invocations",
advanced=True,
type=float,
default=60.0,
daemon=False,
help=
"The maximum amount of time to wait for the invocation to start until "
"raising a timeout exception. "
"Because pantsd currently does not support parallel runs, "
"any prior running Pants command must be finished for the current one to start. "
"To never timeout, use the value -1.",
)
# These facilitate configuring the native engine.
register(
"--native-engine-visualize-to",
advanced=True,
default=None,
type=dir_option,
daemon=False,
help=
"A directory to write execution and rule graphs to as `dot` files. The contents "
"of the directory will be overwritten if any filenames collide.",
)
register(
"--print-exception-stacktrace",
advanced=True,
type=bool,
help=
"Print to console the full exception stack trace if encountered.",
)
# BinaryUtil options.
register(
"--binaries-baseurls",
type=list,
advanced=True,
default=["https://binaries.pantsbuild.org"],
help="List of URLs from which binary tools are downloaded. URLs are "
"searched in order until the requested path is found.",
)
register(
"--binaries-fetch-timeout-secs",
type=int,
default=30,
advanced=True,
daemon=False,
help=
"Timeout in seconds for URL reads when fetching binary tools from the "
"repos specified by --baseurls.",
)
register(
"--binaries-path-by-id",
type=dict,
advanced=True,
help=
("Maps output of uname for a machine to a binary search path: "
"(sysname, id) -> (os, arch), e.g. {('darwin', '15'): ('mac', '10.11'), "
"('linux', 'arm32'): ('linux', 'arm32')}."),
)
register(
"--allow-external-binary-tool-downloads",
type=bool,
default=True,
advanced=True,
help=
"If False, require BinaryTool subclasses to download their contents from urls "
"generated from --binaries-baseurls, even if the tool has an external url "
"generator. This can be necessary if using Pants in an environment which cannot "
"contact the wider Internet.",
)
# Pants Daemon options.
register(
"--pantsd-pailgun-host",
advanced=True,
default="127.0.0.1",
removal_version="1.30.0.dev0",
removal_hint=
"The nailgun protocol is not authenticated, and so only binds to "
"127.0.0.1.",
help="The host to bind the pants nailgun server to.",
)
register(
"--pantsd-pailgun-port",
advanced=True,
type=int,
default=0,
help=
"The port to bind the pants nailgun server to. Defaults to a random port.",
)
# TODO(#7514): Make this default to 1.0 seconds if stdin is a tty!
register(
"--pantsd-pailgun-quit-timeout",
advanced=True,
type=float,
default=5.0,
help=
"The length of time (in seconds) to wait for further output after sending a "
"signal to the remote pantsd process before killing it.",
)
register(
"--pantsd-log-dir",
advanced=True,
default=None,
help="The directory to log pantsd output to.",
)
register(
"--pantsd-invalidation-globs",
advanced=True,
type=list,
default=[],
help=
"Filesystem events matching any of these globs will trigger a daemon restart. "
"Pants' own code, plugins, and `--pants-config-files` are inherently invalidated.",
)
# Watchman options.
register(
"--watchman-enable",
type=bool,
advanced=True,
default=False,
removal_version="1.30.0.dev0",
removal_hint=
"The native watcher is now sufficient to monitor for filesystem changes.",
help=
"Use the watchman daemon filesystem event watcher to watch for changes "
"in the buildroot in addition to the built in watcher.",
)
register("--watchman-version",
advanced=True,
default="4.9.0-pants1",
help="Watchman version.")
register(
"--watchman-supportdir",
advanced=True,
default="bin/watchman",
help=
"Find watchman binaries under this dir. Used as part of the path to lookup "
"the binary with --binaries-baseurls and --pants-bootstrapdir.",
)
register(
"--watchman-startup-timeout",
type=float,
advanced=True,
default=60.0,
help=
"The watchman socket timeout (in seconds) for the initial `watch-project` command. "
"This may need to be set higher for larger repos due to watchman startup cost.",
)
register(
"--watchman-socket-timeout",
type=float,
advanced=True,
default=0.1,
help=
"The watchman client socket timeout in seconds. Setting this to too high a "
"value can negatively impact the latency of runs forked by pantsd.",
)
register(
"--watchman-socket-path",
type=str,
advanced=True,
default=None,
help=
"The path to the watchman UNIX socket. This can be overridden if the default "
"absolute path length exceeds the maximum allowed by the OS.",
)
register(
"--build-file-prelude-globs",
advanced=True,
type=list,
default=[],
help=
"Python files to evaluate and whose symbols should be exposed to all BUILD files ."
"This allows for writing functions which create multiple rules, or set default "
"arguments for rules. The order these files will be evaluated is undefined - they should not rely on each "
"other, or override symbols from each other.",
)
register(
"--local-store-dir",
advanced=True,
help="Directory to use for engine's local file store.",
# This default is also hard-coded into the engine's rust code in
# fs::Store::default_path
default=os.path.expanduser("~/.cache/pants/lmdb_store"),
)
register(
"--local-execution-root-dir",
advanced=True,
help=
"Directory to use for engine's local process execution sandboxing.",
default=tempfile.gettempdir(),
)
register(
"--remote-execution",
advanced=True,
type=bool,
default=DEFAULT_EXECUTION_OPTIONS.remote_execution,
help="Enables remote workers for increased parallelism. (Alpha)",
)
register(
"--remote-store-server",
advanced=True,
type=list,
default=[],
help=
"host:port of grpc server to use as remote execution file store.",
)
# TODO: Infer this from remote-store-connection-limit.
register(
"--remote-store-thread-count",
type=int,
advanced=True,
default=DEFAULT_EXECUTION_OPTIONS.remote_store_thread_count,
help=
"Thread count to use for the pool that interacts with the remote file store.",
)
register(
"--remote-execution-server",
advanced=True,
help=
"host:port of grpc server to use as remote execution scheduler.",
)
register(
"--remote-store-chunk-bytes",
type=int,
advanced=True,
default=DEFAULT_EXECUTION_OPTIONS.remote_store_chunk_bytes,
help=
"Size in bytes of chunks transferred to/from the remote file store.",
)
register(
"--remote-store-chunk-upload-timeout-seconds",
type=int,
advanced=True,
default=DEFAULT_EXECUTION_OPTIONS.
remote_store_chunk_upload_timeout_seconds,
help=
"Timeout (in seconds) for uploads of individual chunks to the remote file store.",
)
register(
"--remote-store-rpc-retries",
type=int,
advanced=True,
default=DEFAULT_EXECUTION_OPTIONS.remote_store_rpc_retries,
help=
"Number of times to retry any RPC to the remote store before giving up.",
)
register(
"--remote-store-connection-limit",
type=int,
advanced=True,
default=DEFAULT_EXECUTION_OPTIONS.remote_store_connection_limit,
help=
"Number of remote stores to concurrently allow connections to.",
)
register(
"--remote-execution-process-cache-namespace",
advanced=True,
help="The cache namespace for remote process execution. "
"Bump this to invalidate every artifact's remote execution. "
"This is the remote execution equivalent of the legacy cache-key-gen-version "
"flag.",
)
register(
"--remote-instance-name",
advanced=True,
help=
"Name of the remote execution instance to use. Used for routing within "
"--remote-execution-server and --remote-store-server.",
)
register(
"--remote-ca-certs-path",
advanced=True,
help=
"Path to a PEM file containing CA certificates used for verifying secure "
"connections to --remote-execution-server and --remote-store-server. "
"If not specified, TLS will not be used.",
)
register(
"--remote-oauth-bearer-token-path",
advanced=True,
help=
"Path to a file containing an oauth token to use for grpc connections to "
"--remote-execution-server and --remote-store-server. If not specified, no "
"authorization will be performed.",
)
register(
"--remote-execution-extra-platform-properties",
advanced=True,
help="Platform properties to set on remote execution requests. "
"Format: property=value. Multiple values should be specified as multiple "
"occurrences of this flag. Pants itself may add additional platform properties.",
type=list,
default=[],
)
register(
"--remote-execution-headers",
advanced=True,
help="Headers to set on remote execution requests. "
"Format: header=value. Pants itself may add additional headers.",
type=dict,
default={},
)
register(
"--process-execution-local-parallelism",
type=int,
default=DEFAULT_EXECUTION_OPTIONS.
process_execution_local_parallelism,
advanced=True,
help="Number of concurrent processes that may be executed locally.",
)
register(
"--process-execution-remote-parallelism",
type=int,
default=DEFAULT_EXECUTION_OPTIONS.
process_execution_remote_parallelism,
advanced=True,
help=
"Number of concurrent processes that may be executed remotely.",
)
register(
"--process-execution-cleanup-local-dirs",
type=bool,
default=True,
advanced=True,
help=
"Whether or not to cleanup directories used for local process execution "
"(primarily useful for e.g. debugging).",
)
register(
"--process-execution-speculation-delay",
type=float,
default=DEFAULT_EXECUTION_OPTIONS.
process_execution_speculation_delay,
advanced=True,
help=
"Number of seconds to wait before speculating a second request for a slow process. "
" see `--process-execution-speculation-strategy`",
)
register(
"--process-execution-speculation-strategy",
choices=["remote_first", "local_first", "none"],
default=DEFAULT_EXECUTION_OPTIONS.
process_execution_speculation_strategy,
help=
"Speculate a second request for an underlying process if the first one does not complete within "
"`--process-execution-speculation-delay` seconds.\n"
"`local_first` (default): Try to run the process locally first, "
"and fall back to remote execution if available.\n"
"`remote_first`: Run the process on the remote execution backend if available, "
"and fall back to the local host if remote calls take longer than the speculation timeout.\n"
"`none`: Do not speculate about long running processes.",
advanced=True,
)
register(
"--process-execution-use-local-cache",
type=bool,
default=True,
advanced=True,
help=
"Whether to keep process executions in a local cache persisted to disk.",
)
register(
"--process-execution-local-enable-nailgun",
type=bool,
default=DEFAULT_EXECUTION_OPTIONS.
process_execution_local_enable_nailgun,
help=
"Whether or not to use nailgun to run the requests that are marked as nailgunnable.",
advanced=True,
)
register(
"--experimental-fs-watcher",
type=bool,
default=True,
advanced=True,
removal_version="1.30.0.dev0",
removal_hint="Enabled by default: flag is disabled.",
help=
"Whether to use the engine filesystem watcher which registers the workspace"
" for kernel file change events",
)
def register_bootstrap_options(cls, register):
"""Register bootstrap options.
"Bootstrap options" are a small set of options whose values are useful when registering other
options. Therefore we must bootstrap them early, before other options are registered, let
alone parsed.
Bootstrap option values can be interpolated into the config file, and can be referenced
programatically in registration code, e.g., as register.bootstrap.pants_workdir.
Note that regular code can also access these options as normal global-scope options. Their
status as "bootstrap options" is only pertinent during option registration.
"""
buildroot = get_buildroot()
# Although logging supports the WARN level, its not documented and could conceivably be yanked.
# Since pants has supported 'warn' since inception, leave the 'warn' choice as-is but explicitly
# setup a 'WARN' logging level name that maps to 'WARNING'.
logging.addLevelName(logging.WARNING, 'WARN')
register('-l', '--level', choices=['debug', 'info', 'warn'], default='info', recursive=True,
help='Set the logging level.')
register('-q', '--quiet', type=bool, recursive=True,
help='Squelches most console output.')
# Not really needed in bootstrap options, but putting it here means it displays right
# after -l and -q in help output, which is conveniently contextual.
register('--colors', type=bool, default=sys.stdout.isatty(), recursive=True,
help='Set whether log messages are displayed in color.')
# Pants code uses this only to verify that we are of the requested version. However
# setup scripts, runner scripts, IDE plugins, etc., may grep this out of pants.ini
# and use it to select the right version.
# Note that to print the version of the pants instance you're running, use -v, -V or --version.
register('--pants-version', advanced=True, default=pants_version(),
help='Use this pants version.')
register('--plugins', advanced=True, type=list, help='Load these plugins.')
register('--plugin-cache-dir', advanced=True,
default=os.path.join(get_pants_cachedir(), 'plugins'),
help='Cache resolved plugin requirements here.')
register('--backend-packages', advanced=True, type=list,
default=['pants.backend.graph_info',
'pants.backend.python',
'pants.backend.jvm',
'pants.backend.codegen.antlr.java',
'pants.backend.codegen.antlr.python',
'pants.backend.codegen.jaxb',
'pants.backend.codegen.protobuf.java',
'pants.backend.codegen.ragel.java',
'pants.backend.codegen.thrift.java',
'pants.backend.codegen.thrift.python',
'pants.backend.codegen.wire.java',
'pants.backend.project_info'],
help='Load backends from these packages that are already on the path. '
'Add contrib and custom backends to this list.')
register('--pants-bootstrapdir', advanced=True, metavar='<dir>', default=get_pants_cachedir(),
help='Use this dir for global cache.')
register('--pants-configdir', advanced=True, metavar='<dir>', default=get_pants_configdir(),
help='Use this dir for global config files.')
register('--pants-workdir', advanced=True, metavar='<dir>',
default=os.path.join(buildroot, '.pants.d'),
help='Write intermediate output files to this dir.')
register('--pants-supportdir', advanced=True, metavar='<dir>',
default=os.path.join(buildroot, 'build-support'),
help='Use support files from this dir.')
register('--pants-distdir', advanced=True, metavar='<dir>',
default=os.path.join(buildroot, 'dist'),
help='Write end-product artifacts to this dir.')
register('--pants-subprocessdir', advanced=True, default=os.path.join(buildroot, '.pids'),
help='The directory to use for tracking subprocess metadata, if any. This should '
'live outside of the dir used by `--pants-workdir` to allow for tracking '
'subprocesses that outlive the workdir data (e.g. `./pants server`).')
register('--pants-config-files', advanced=True, type=list,
default=[get_default_pants_config_file()], help='Paths to Pants config files.')
# TODO: Deprecate the --pantsrc/--pantsrc-files options? This would require being able
# to set extra config file locations in an initial bootstrap config file.
register('--config-override', advanced=True, type=list, metavar='<path>',
removal_version='1.6.0.dev0',
removal_hint='Use --pants-config-files=<second config file path> instead.',
help='A second config file, to override pants.ini.')
register('--pantsrc', advanced=True, type=bool, default=True,
help='Use pantsrc files.')
register('--pantsrc-files', advanced=True, type=list, metavar='<path>',
default=['/etc/pantsrc', '~/.pants.rc'],
help='Override config with values from these files. '
'Later files override earlier ones.')
register('--pythonpath', advanced=True, type=list,
help='Add these directories to PYTHONPATH to search for plugins.')
register('--target-spec-file', type=list, dest='target_spec_files',
help='Read additional specs from this file, one per line')
register('--verify-config', type=bool, default=True,
help='Verify that all config file values correspond to known options.')
# These logging options are registered in the bootstrap phase so that plugins can log during
# registration and not so that their values can be interpolated in configs.
register('-d', '--logdir', advanced=True, metavar='<dir>',
help='Write logs to files under this directory.')
# This facilitates bootstrap-time configuration of pantsd usage such that we can
# determine whether or not to use the Pailgun client to invoke a given pants run
# without resorting to heavier options parsing.
register('--enable-pantsd', advanced=True, type=bool, default=False,
help='Enables use of the pants daemon (and implicitly, the v2 engine). (Beta)')
# This facilitates use of the v2 engine, sans daemon.
# TODO: Add removal_version='1.5.0.dev0' before 1.4 lands.
register('--enable-v2-engine', advanced=True, type=bool, default=True,
help='Enables use of the v2 engine.')
# These facilitate configuring the native engine.
register('--native-engine-version', advanced=True,
default=pkg_resources.resource_string('pants.engine', 'native_engine_version').strip(),
help='Native engine version.')
register('--native-engine-supportdir', advanced=True, default='bin/native-engine',
help='Find native engine binaries under this dir. Used as part of the path to '
'lookup the binary with --binary-util-baseurls and --pants-bootstrapdir.')
register('--native-engine-visualize-to', advanced=True, default=None, type=dir_option,
help='A directory to write execution and rule graphs to as `dot` files. The contents '
'of the directory will be overwritten if any filenames collide.')
def register_bootstrap_options(cls, register):
"""Register bootstrap options.
"Bootstrap options" are a small set of options whose values are useful when registering other
options. Therefore we must bootstrap them early, before other options are registered, let
alone parsed.
Bootstrap option values can be interpolated into the config file, and can be referenced
programatically in registration code, e.g., as register.bootstrap.pants_workdir.
Note that regular code can also access these options as normal global-scope options. Their
status as "bootstrap options" is only pertinent during option registration.
"""
buildroot = get_buildroot()
# Although logging supports the WARN level, its not documented and could conceivably be yanked.
# Since pants has supported 'warn' since inception, leave the 'warn' choice as-is but explicitly
# setup a 'WARN' logging level name that maps to 'WARNING'.
logging.addLevelName(logging.WARNING, 'WARN')
register('-l', '--level', choices=['debug', 'info', 'warn'], default='info', recursive=True,
help='Set the logging level.')
register('-q', '--quiet', action='store_true',
help='Squelches all console output apart from errors.')
# Not really needed in bootstrap options, but putting it here means it displays right
# after -l and -q in help output, which is conveniently contextual.
register('--colors', action='store_true', default=True, recursive=True,
help='Set whether log messages are displayed in color.')
# NB: Right now this option is a placeholder that is unused within pants itself except when
# specified on the command line to print the OSS pants version. Both the IntelliJ Pants plugin
# and the pantsbuild/setup bootstrap script grep for pants_version though so this option
# registration serves in part as documentation of the dependency.
# TODO(John Sirois): Move pantsbuild.pants bootstrapping into pants itself and have it use this
# version option directly.
register('-V', '--pants-version', '--version', # NB: pants_version is the 1st long option
# since that's the one read from pants.ini;
# the version form only works from the CLI.
nargs='?', # Allows using the flag with no args on the CLI to print version as well
# as setting the version in pants.ini
default=pants_version(), # Displays the current version correctly in `./pants -h`.
const=pants_version(), # Displays the current version via `./pants -V`.
help="Prints pants' version number and exits.")
register('--plugins', advanced=True, type=list_option, help='Load these plugins.')
register('--plugin-cache-dir', advanced=True,
default=os.path.join(get_pants_cachedir(), 'plugins'),
help='Cache resolved plugin requirements here.')
register('--backend-packages', advanced=True, type=list_option,
help='Load backends from these packages that are already on the path.')
register('--pants-bootstrapdir', advanced=True, metavar='<dir>', default=get_pants_cachedir(),
help='Use this dir for global cache.')
register('--pants-configdir', advanced=True, metavar='<dir>', default=get_pants_configdir(),
help='Use this dir for global config files.')
register('--pants-workdir', advanced=True, metavar='<dir>',
default=os.path.join(buildroot, '.pants.d'),
help='Write intermediate output files to this dir.')
register('--pants-supportdir', advanced=True, metavar='<dir>',
default=os.path.join(buildroot, 'build-support'),
help='Use support files from this dir.')
register('--pants-distdir', advanced=True, metavar='<dir>',
default=os.path.join(buildroot, 'dist'),
help='Write end-product artifacts to this dir.')
register('--config-override', advanced=True, action='append', metavar='<path>',
help='A second config file, to override pants.ini.')
register('--pantsrc', advanced=True, action='store_true', default=True,
help='Use pantsrc files.')
register('--pantsrc-files', advanced=True, action='append', metavar='<path>',
default=['/etc/pantsrc', '~/.pants.rc'],
help='Override config with values from these files. '
'Later files override earlier ones.')
register('--pythonpath', advanced=True, action='append',
help='Add these directories to PYTHONPATH to search for plugins.')
register('--target-spec-file', action='append', dest='target_spec_files',
help='Read additional specs from this file, one per line')
# These logging options are registered in the bootstrap phase so that plugins can log during
# registration and not so that their values can be interpolated in configs.
register('-d', '--logdir', advanced=True, metavar='<dir>',
help='Write logs to files under this directory.')
def _run():
# Place the registration of the unhandled exception hook as early as possible in the code.
sys.excepthook = _unhandled_exception_hook
"""
To add additional paths to sys.path, add a block to the config similar to the following:
[main]
roots: ['src/python/pants_internal/test/',]
"""
logging.basicConfig()
version = pants_version()
if len(sys.argv) == 2 and sys.argv[1] == _VERSION_OPTION:
_do_exit(msg=version, out=sys.stdout)
root_dir = get_buildroot()
if not os.path.exists(root_dir):
_exit_and_fail('PANTS_BUILD_ROOT does not point to a valid path: %s' % root_dir)
if len(sys.argv) < 2:
argv = ['goal']
else:
argv = sys.argv[1:]
# Hack to force ./pants -h etc. to redirect to goal.
if argv[0] != 'goal' and set(['-h', '--help', 'help']).intersection(argv):
argv = ['goal'] + argv
parser = optparse.OptionParser(add_help_option=False, version=version)
RcFile.install_disable_rc_option(parser)
parser.add_option(_LOG_EXIT_OPTION,
action='store_true',
default=False,
dest='log_exit',
help='Log an exit message on success or failure.')
config = Config.load()
# XXX(wickman) This should be in the command goal, not in pants_exe.py!
run_tracker = RunTracker.from_config(config)
report = initial_reporting(config, run_tracker)
run_tracker.start(report)
url = run_tracker.run_info.get_info('report_url')
if url:
run_tracker.log(Report.INFO, 'See a report at: %s' % url)
else:
run_tracker.log(Report.INFO, '(To run a reporting server: ./pants goal server)')
backend_packages = config.getlist('backends', 'packages')
build_configuration = load_build_configuration_from_source(additional_backends=backend_packages)
build_file_parser = BuildFileParser(build_configuration=build_configuration,
root_dir=root_dir,
run_tracker=run_tracker)
address_mapper = BuildFileAddressMapper(build_file_parser)
build_graph = BuildGraph(run_tracker=run_tracker, address_mapper=address_mapper)
command_class, command_args = _parse_command(root_dir, argv)
command = command_class(run_tracker,
root_dir,
parser,
command_args,
build_file_parser,
address_mapper,
build_graph)
try:
if command.serialized():
def onwait(pid):
process = psutil.Process(pid)
print('Waiting on pants process %d (%s) to complete' %
(pid, ' '.join(process.cmdline)), file=sys.stderr)
return True
runfile = os.path.join(root_dir, '.pants.run')
lock = Lock.acquire(runfile, onwait=onwait)
else:
lock = Lock.unlocked()
try:
result = command.run(lock)
if result:
run_tracker.set_root_outcome(WorkUnit.FAILURE)
_do_exit(result)
except KeyboardInterrupt:
command.cleanup()
raise
except Exception:
run_tracker.set_root_outcome(WorkUnit.FAILURE)
raise
finally:
lock.release()
finally:
run_tracker.end()
# Must kill nailguns only after run_tracker.end() is called, because there may still
# be pending background work that needs a nailgun.
if (hasattr(command.old_options, 'cleanup_nailguns') and command.old_options.cleanup_nailguns) \
or config.get('nailgun', 'autokill', default=False):
NailgunTask.killall(None)
