Files
spack/lib/spack/spack/cmd/make_installer.py
Adam J. Stewart bb7f437bf5 Standardize subcommand help strings (#38804)
### Rationale

While working on #29549, I noticed a lot of inconsistencies in our argparse help messages. This is important for fish where these help messages end up as descriptions in the tab completion menu. See https://github.com/spack/spack/pull/29549#issuecomment-1627596477 for some examples of longer or more stylized help messages.

### Implementation

This PR makes the following changes:

- [x] help messages start with a lowercase letter.
- [x] Help messages do not end with a period
- [x] the first line of a help message is short and simple

    longer text is separated by an empty line
- [x] "help messages do not use triple quotes" 

    """(except docstrings)"""
- [x] Parentheses not needed for string concatenation inside function call
- [x] Remove "..." "..." string concatenation leftover from black reformatting
- [x] Remove Sphinx argument docs from help messages

The first 2 choices aren't very controversial, and are designed to match the syntax of the `--help` flag automatically added by argparse. The 3rd choice is more up for debate, and is designed to match our package/module docstrings. The 4th choice is designed to avoid excessive newline characters and indentation. We may actually want to go even further and disallow docstrings altogether.

### Alternatives

Choice 3 in particular has a lot of alternatives. My goal is solely to ensure that fish tab completion looks reasonable. Alternatives include:

1. Get rid of long help messages, only allow short simple messages
2. Move longer help messages to epilog
3. Separate by 2 newline characters instead of 1
4. Separate by period instead of newline. First sentence goes into tab completion description

The number of commands with long help text is actually rather small, and is mostly relegated to `spack ci` and `spack buildcache`. So 1 isn't actually as ridiculous as it sounds.

Let me know if there are any other standardizations or alternatives you would like to suggest.
2023-07-13 00:18:23 -07:00

150 lines
5.3 KiB
Python

# Copyright 2013-2023 Lawrence Livermore National Security, LLC and other
# Spack Project Developers. See the top-level COPYRIGHT file for details.
#
# SPDX-License-Identifier: (Apache-2.0 OR MIT)
import os
import posixpath
import sys
import spack.paths
import spack.util.executable
from spack.spec import Spec
from spack.util.path import convert_to_posix_path
description = "generate Windows installer"
section = "admin"
level = "long"
def txt_to_rtf(file_path):
rtf_header = r"""{{\rtf1\ansi\deff0\nouicompat
{{\fonttbl{{\f0\\fnil\fcharset0 Courier New;}}}}
{{\colortbl ;\red0\green0\blue255;}}
{{\*\generator Riched20 10.0.19041}}\viewkind4\uc1
\f0\fs22\lang1033
{}
}}
"""
def line_to_rtf(str):
return str.replace("\n", "\\par")
contents = ""
with open(file_path, "r+") as f:
for line in f.readlines():
contents += line_to_rtf(line)
return rtf_header.format(contents)
def setup_parser(subparser):
spack_source_group = subparser.add_mutually_exclusive_group(required=True)
spack_source_group.add_argument(
"-v", "--spack-version", default="", help="download given spack version"
)
spack_source_group.add_argument(
"-s", "--spack-source", default="", help="full path to spack source"
)
subparser.add_argument(
"-g",
"--git-installer-verbosity",
default="",
choices=["SILENT", "VERYSILENT"],
help="level of verbosity provided by bundled git installer (default is fully verbose)",
required=False,
action="store",
dest="git_verbosity",
)
subparser.add_argument("output_dir", help="output directory")
def make_installer(parser, args):
"""
Use CMake to generate WIX installer in newly created build directory
"""
if sys.platform == "win32":
output_dir = args.output_dir
cmake_spec = Spec("cmake")
cmake_spec.concretize()
cmake_path = os.path.join(cmake_spec.prefix, "bin", "cmake.exe")
cpack_path = os.path.join(cmake_spec.prefix, "bin", "cpack.exe")
spack_source = args.spack_source
git_verbosity = ""
if args.git_verbosity:
git_verbosity = "/" + args.git_verbosity
if spack_source:
if not os.path.exists(spack_source):
print("%s does not exist" % spack_source)
return
else:
if not os.path.isabs(spack_source):
spack_source = posixpath.abspath(spack_source)
spack_source = convert_to_posix_path(spack_source)
spack_version = args.spack_version
here = os.path.dirname(os.path.abspath(__file__))
source_dir = os.path.join(here, "installer")
posix_root = convert_to_posix_path(spack.paths.spack_root)
spack_license = posixpath.join(posix_root, "LICENSE-APACHE")
rtf_spack_license = txt_to_rtf(spack_license)
spack_license = posixpath.join(source_dir, "LICENSE.rtf")
with open(spack_license, "w") as rtf_license:
written = rtf_license.write(rtf_spack_license)
if written == 0:
raise RuntimeError("Failed to generate properly formatted license file")
spack_logo = posixpath.join(posix_root, "share/spack/logo/favicon.ico")
try:
spack.util.executable.Executable(cmake_path)(
"-S",
source_dir,
"-B",
output_dir,
"-DSPACK_VERSION=%s" % spack_version,
"-DSPACK_SOURCE=%s" % spack_source,
"-DSPACK_LICENSE=%s" % spack_license,
"-DSPACK_LOGO=%s" % spack_logo,
"-DSPACK_GIT_VERBOSITY=%s" % git_verbosity,
)
except spack.util.executable.ProcessError:
print("Failed to generate installer")
return spack.util.executable.ProcessError.returncode
try:
spack.util.executable.Executable(cpack_path)(
"--config", "%s/CPackConfig.cmake" % output_dir, "-B", "%s/" % output_dir
)
except spack.util.executable.ProcessError:
print("Failed to generate installer")
return spack.util.executable.ProcessError.returncode
try:
spack.util.executable.Executable(os.environ.get("WIX") + "/bin/candle.exe")(
"-ext",
"WixBalExtension",
"%s/bundle.wxs" % output_dir,
"-out",
"%s/bundle.wixobj" % output_dir,
)
except spack.util.executable.ProcessError:
print("Failed to generate installer chain")
return spack.util.executable.ProcessError.returncode
try:
spack.util.executable.Executable(os.environ.get("WIX") + "/bin/light.exe")(
"-sw1134",
"-ext",
"WixBalExtension",
"%s/bundle.wixobj" % output_dir,
"-out",
"%s/Spack.exe" % output_dir,
)
except spack.util.executable.ProcessError:
print("Failed to generate installer chain")
return spack.util.executable.ProcessError.returncode
print("Successfully generated Spack.exe in %s" % (output_dir))
else:
print("The make-installer command is currently only supported on Windows.")