From 09e7357cc3bfc8ad63281ec9dfd8d297d025235c Mon Sep 17 00:00:00 2001 From: Phil de Joux Date: Mon, 9 Dec 2024 21:07:56 -0500 Subject: [PATCH] Use terms for cabal and cabal-install --- doc/cabal-commands.rst | 12 +++---- doc/cabal-context.rst | 10 +++--- doc/cabal-package-description-file.rst | 6 ++-- doc/cabal-project-description-file.rst | 12 +++---- doc/config.rst | 50 +++++++++++++------------- doc/external-commands.rst | 10 +++--- doc/getting-started.rst | 6 ++-- doc/how-to-run-in-windows.rst | 2 +- doc/nix-local-build.rst | 8 ++--- doc/package-concepts.rst | 2 +- doc/setup-commands.rst | 2 +- 11 files changed, 60 insertions(+), 60 deletions(-) diff --git a/doc/cabal-commands.rst b/doc/cabal-commands.rst index ed088d14b8d..4ec8b130ebe 100644 --- a/doc/cabal-commands.rst +++ b/doc/cabal-commands.rst @@ -258,7 +258,7 @@ cabal user-config ``cabal user-config [init|diff|update]`` prints and updates user's global cabal preferences. It is very useful when you are e.g. first configuring -``cabal`` on a new machine. +:term:`cabal` on a new machine. - ``cabal user-config init`` creates a new configuration file. @@ -288,7 +288,7 @@ cabal preferences. It is very useful when you are e.g. first configuring cabal path ^^^^^^^^^^ -``cabal path`` allows to query for paths used by ``cabal``. +``cabal path`` allows to query for paths used by :term:`cabal`. For example, it allows to query for the directories of the cache, store, installed binaries, and so on. @@ -695,7 +695,7 @@ Examples: Read dependency version bounds from the v2-style freeze file (by default, ``cabal.project.freeze``) instead of the package description file. ``--new-freeze-file`` is an alias for this flag - that can be used with pre-2.4 ``cabal``. + that can be used with pre-2.4 :term:`cabal`. .. option:: --project-file=FILE @@ -796,8 +796,8 @@ symlinks/copies their executables in ``installdir`` (usually ``~/.local/bin``). than ``all`` as the target. To overwrite an installation, use ``--overwrite-policy=always`` as the default policy is ``never``. -For example this command will build the latest ``cabal-install`` and symlink -its ``cabal`` executable: +For example this command will build the latest :term:`cabal-install:exe:cabal` and symlink +its :term:`cabal` executable: :: @@ -806,7 +806,7 @@ its ``cabal`` executable: In addition, it's possible to use ``cabal install`` to install components of a local project. For example, with an up-to-date Git clone of the Cabal repository, this command will build cabal-install HEAD and symlink the -``cabal`` executable: +:term:`cabal` executable: :: diff --git a/doc/cabal-context.rst b/doc/cabal-context.rst index ce152cca713..6114f456945 100644 --- a/doc/cabal-context.rst +++ b/doc/cabal-context.rst @@ -5,7 +5,7 @@ Haskell_ software. It helps people to configure, build and install Haskell software and to distribute it easily to other users and developers. -There is a command line tool called ``cabal`` for working with Cabal +There is a command line tool called :term:`cabal` for working with Cabal packages. It helps with installing existing packages and also helps people developing their own packages. It can be used to work with local packages or to install packages from online package archives, including @@ -52,7 +52,7 @@ other Haskell implementations). A tool for working with packages -------------------------------- -There is a command line tool, called "``cabal``", that users and +There is a command line tool, called ":term:`cabal`", that users and developers can use to build and install Cabal packages. It can be used for both local packages and for packages available remotely over the network. It can automatically install Cabal packages plus any other @@ -76,7 +76,7 @@ It is also possible to install several local packages at once, e.g. $ cabal install foo/ bar/ Developers and users can use the tool to install packages from remote -Cabal package archives. By default, the ``cabal`` tool is configured to +Cabal package archives. By default, the :term:`cabal` tool is configured to use the central Haskell package archive called Hackage_ but it is possible to use it with any other suitable archive. @@ -102,7 +102,7 @@ which Haskell implementation to use and whether to build optimised code or build with the ability to profile code. It is not expected that users will have to modify any of the information in the ``.cabal`` file. -Note that ``cabal`` is not the only tool for working with Cabal +Note that :term:`cabal` is not the only tool for working with Cabal packages. Due to the standardised format and a library for reading ``.cabal`` files, there are several other special-purpose tools. @@ -134,7 +134,7 @@ Cabal and its associated tools and websites covers: - packaging for distribution - automated package management - - natively using the ``cabal`` command line tool; or + - natively using the :term:`cabal` command line tool; or - by translation into native package formats such as RPM or deb - web and local Cabal package archives diff --git a/doc/cabal-package-description-file.rst b/doc/cabal-package-description-file.rst index 9eb2aef2705..449006dc316 100644 --- a/doc/cabal-package-description-file.rst +++ b/doc/cabal-package-description-file.rst @@ -353,7 +353,7 @@ describe the package as a whole: what syntax to expect and what each part means. The version number you specify will affect both compatibility and - behaviour. Most tools (including the Cabal library and the ``cabal`` + behaviour. Most tools (including the Cabal library and the :term:`cabal` program) understand a range of versions of the Cabal specification. Older tools will of course only work with older versions of the Cabal specification that was known at the time. Most of the time, @@ -429,7 +429,7 @@ describe the package as a whole: If the build type is anything other than ``Custom``, then the ``Setup.hs`` file *must* be exactly the standardized content - discussed below. This is because in these cases, ``cabal`` will + discussed below. This is because in these cases, :term:`cabal` will ignore the ``Setup.hs`` file completely, whereas other methods of package management, such as ``runhaskell Setup.hs [CMD]``, still rely on the ``Setup.hs`` file. @@ -467,7 +467,7 @@ describe the package as a whole: main = defaultMain For build type ``Custom``, the file ``Setup.hs`` can be customized, - and will be used both by ``cabal`` and other tools. + and will be used both by :term:`cabal` and other tools. For most packages, the build type ``Simple`` is sufficient. For more exotic needs, the ``Hooks`` build type is recommended; see :ref:`setup-hooks`. diff --git a/doc/cabal-project-description-file.rst b/doc/cabal-project-description-file.rst index 929ec642f6f..cf2cbb41afe 100644 --- a/doc/cabal-project-description-file.rst +++ b/doc/cabal-project-description-file.rst @@ -42,7 +42,7 @@ directories when there is none in the current directory. Conditionals and imports ------------------------ -As of ``cabal-install`` version 3.8, cabal supports conditional logic and +As of :term:`cabal-install:exe:cabal` version 3.8, cabal supports conditional logic and imports in ``cabal.project`` files. .. warning:: @@ -92,7 +92,7 @@ You *must* provide a non-empty list of local packages in your project, filling out either a ``packages`` field or an ``optional-packages`` field or both to satisfy this requirement. -When ``cabal.project`` doesn't exist, ``cabal-install`` fabricates an ephemeral +When ``cabal.project`` doesn't exist, :term:`cabal-install:exe:cabal` fabricates an ephemeral project for its own use with this simple content, a glob that will find any (but expects to find one) package in the current directory: @@ -315,7 +315,7 @@ package, and thus apply globally: :default: 1 - Control the verbosity of ``cabal`` commands, valid values are from 0 + Control the verbosity of :term:`cabal` commands, valid values are from 0 to 3. The command line variant of this field is ``--verbose=2``; a short @@ -346,7 +346,7 @@ package, and thus apply globally: This option instructs cabal to control parallelism by creating a new system semaphore, whose number of tokens is specified by ``--jobs`` (or ``-j``). This semaphore is passed to GHC, which allows it to use any leftover parallelism - that ``cabal-install`` is not using. + that :term:`cabal-install:exe:cabal` is not using. Requires ``ghc >= 9.8``. @@ -420,9 +420,9 @@ package, and thus apply globally: :since: 3.7 By modifying ``package-dbs`` you can modify the default package environment - which ``cabal`` will see. The package databases you add using ``package-dbs`` + which :term:`cabal` will see. The package databases you add using ``package-dbs`` will not be written into and only used as immutable package stores to initialise - the environment with additional packages that ``cabal`` can choose to use. + the environment with additional packages that :term:`cabal` can choose to use. There are three package databases involved with most builds: diff --git a/doc/config.rst b/doc/config.rst index 36a53f958b0..fc368698cf3 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -6,11 +6,11 @@ Configuration Overview -------- -The global configuration file for ``cabal-install`` is by default -``$XDG_CONFIG_HOME/cabal/config``. If you do not have this file, ``cabal`` will create +The global configuration file for :term:`cabal-install:exe:cabal` is by default +``$XDG_CONFIG_HOME/cabal/config``. If you do not have this file, :term:`cabal` will create it for you on the first call to ``cabal update`` (details see `configuration file discovery`_). -Alternatively, you can explicitly ask ``cabal`` to create it for you using +Alternatively, you can explicitly ask :term:`cabal` to create it for you using .. code-block:: console @@ -40,21 +40,21 @@ executables by default, you would change this line to executable-stripping: False You can also use ``cabal user-config update`` to migrate configuration -files created by older versions of ``cabal``. +files created by older versions of :term:`cabal`. Environment variables --------------------- -Various environment variables affect ``cabal-install``. +Various environment variables affect :term:`cabal-install:exe:cabal`. ``CABAL_CONFIG`` The variable to find global configuration file. ``CABAL_DIR`` - If set, *all* ``cabal-install`` content files will be stored as + If set, *all* :term:`cabal-install:exe:cabal` content files will be stored as subdirectories of this directory, including the configuration file - if ``CABAL_CONFIG`` is unset. If ``CABAL_DIR`` is unset, Cabal + if ``CABAL_CONFIG`` is unset. If ``CABAL_DIR`` is unset, :term:`cabal` will store data files according to the XDG Base Directory Specification (see `directories`_). @@ -63,7 +63,7 @@ Various environment variables affect ``cabal-install``. For backwards compatibility, if the directory ``~/.cabal`` on Unix or ``%APPDATA%\cabal`` on Windows exists, and ``$XDG_CONFIG_HOME/cabal/config`` does not exist, and - ``CABAL_DIR`` is unset, ``cabal-install`` will behave as if + ``CABAL_DIR`` is unset, :term:`cabal-install:exe:cabal` will behave as if ``CABAL_DIR`` was set to point at this directory. ``CABAL_BUILDDIR`` @@ -87,7 +87,7 @@ The configuration file location is determined as follows: If the configuration file does not exist, and it was not given explicitly via ``--config-file`` or ``$CABAL_CONFIG``, then -``cabal-install`` will generate the default one, with directories +:term:`cabal-install:exe:cabal` will generate the default one, with directories based on ``$CABAL_DIR`` (if set) or according to the XDG Base Directory Specification, as listed below. @@ -121,13 +121,13 @@ file: * ``~/.local/bin`` for executables installed with ``cabal install``. You can run ``cabal path`` to see a list of the directories that -``cabal`` will use with the active configuration. +:term:`cabal` will use with the active configuration. Repository specification ------------------------ An important part of the configuration is the specification of the -repository. When ``cabal`` creates a default config file, it configures +repository. When :term:`cabal` creates a default config file, it configures the repository to be the central Hackage server: :: @@ -140,7 +140,7 @@ anything; packages downloaded from this repository will be cached under ``$XDG_CACHE_HOME/cabal/packages/hackage.haskell.org`` (or whatever name you specify; you can change the prefix by changing the value of :cfg-field:`remote-repo-cache`). If you want, you can configure multiple -repositories, and ``cabal`` will combine them and be able to download +repositories, and :term:`cabal` will combine them and be able to download packages from any of them. Using secure repositories @@ -166,21 +166,21 @@ The ```` and ```` values are used for bootstrapping. As part of the TUF infrastructure the repository will contain a file ``root.json`` (for instance, http://hackage.haskell.org/root.json) which the client needs to do -verification. However, how can ``cabal`` verify the ``root.json`` file +verification. However, how can :term:`cabal` verify the ``root.json`` file *itself*? This is known as bootstrapping: if you specify a list of root -key IDs and a corresponding threshold, ``cabal`` will verify that the +key IDs and a corresponding threshold, :term:`cabal` will verify that the downloaded ``root.json`` file has been signed with at least ```` keys from your set of ````. You can, but are not recommended to, omit these two fields. In that case -``cabal`` will download the ``root.json`` field and use it without +:term:`cabal` will download the ``root.json`` field and use it without verification. Although this bootstrapping step is then unsafe, all subsequent access is secure (provided that the downloaded ``root.json`` was not tampered with). Of course, adding ``root-keys`` and ``key-threshold`` to your repository specification only shifts the problem, because now you somehow need to make sure that the key IDs you received were the right ones. How that is done is however outside the -scope of ``cabal`` proper. +scope of :term:`cabal` proper. More information about the security infrastructure can be found at https://github.com/haskell/hackage-security. @@ -196,7 +196,7 @@ repository. repository my-local-repository url: file+noindex:///absolute/path/to/directory -``cabal`` will construct the index automatically from the +:term:`cabal` will construct the index automatically from the ``package-name-version.tar.gz`` files in the directory, and will use optional corresponding ``package-name-version.cabal`` files as new revisions. @@ -208,7 +208,7 @@ For example, if ``/absolute/path/to/directory`` looks like bar-0.2.0.0.tar.gz bar-0.2.0.0.cabal -then ``cabal`` will create an index with two packages: +then :term:`cabal` will create an index with two packages: - ``foo-0.1.0.0`` using the source and ``.cabal`` file inside ``foo-0.1.0.0.tar.gz`` @@ -221,7 +221,7 @@ then the cache will be stored inside the :cfg-field:`remote-repo-cache` director The part of the path will be used to determine the cache key part. .. note:: - ``cabal-install`` creates a ``.cache`` file, and will aggressively use + :term:`cabal-install:exe:cabal` creates a ``.cache`` file, and will aggressively use its contents if it exists. Therefore if you change the contents of the directory, remember to wipe the cache too. @@ -256,13 +256,13 @@ thus, looks similar to a ``package-name.cabal``'s ``build-depends`` section. certain versions or marking a specific version as deprecated. To achieve this, add a local no-index repository to your :ref:`configuration file `, where the directory contains your custom - ``preferred-versions``. After running ``cabal update``, all ``cabal`` operations will honour the + ``preferred-versions``. After running ``cabal update``, all :term:`cabal` operations will honour the configuration. Legacy repositories ^^^^^^^^^^^^^^^^^^^ -Currently ``cabal`` supports single kind of “legacy” repositories. +Currently :term:`cabal` supports single kind of “legacy” repositories. It is specified using :: @@ -303,8 +303,8 @@ can be used to create and manage such repositories. Program options --------------- -Programs that ``cabal`` knows about can be provided with options that will be -passed in whenever the program is invoked by ``cabal``. The configuration file +Programs that :term:`cabal` knows about can be provided with options that will be +passed in whenever the program is invoked by :term:`cabal`. The configuration file can contain a stanza of ``program-default-options`` with ``-options`` fields to specify these. @@ -379,11 +379,11 @@ The list of known programs is: .. warning:: - These options will be used when ``cabal`` invokes the tool as part of the build process or as part of a + These options will be used when :term:`cabal` invokes the tool as part of the build process or as part of a :pkg-field:`build-tool-depends` declaration, not whenever the tool is invoked by third parties. - In particular this means that for example ``gcc-options`` will be used when ``cabal`` + In particular this means that for example ``gcc-options`` will be used when :term:`cabal` invokes ``gcc``, which is **not** when C sources are compiled by GHC (even though GHC might invoke ``gcc`` internally). In order to provide options through GHC for those programs, one has to check the GHC User guide's `Section `_. diff --git a/doc/external-commands.rst b/doc/external-commands.rst index eca76483cc1..0acfe18ff1b 100644 --- a/doc/external-commands.rst +++ b/doc/external-commands.rst @@ -1,22 +1,22 @@ External Commands ================= -``cabal-install`` provides a system for external commands, akin to the ones used by tools like ``git`` or ``cargo``. +:term:`cabal-install:exe:cabal` provides a system for external commands, akin to the ones used by tools like ``git`` or ``cargo``. -If you execute ``cabal ``, ``cabal-install`` will search the path for an executable named ``cabal-`` and execute it. The name of the command is passed as the first argument and +If you execute ``cabal ``, :term:`cabal-install:exe:cabal` will search the path for an executable named ``cabal-`` and execute it. The name of the command is passed as the first argument and the remaining arguments are passed afterwards. An error will be thrown in case the custom command is not found. The exit code of cabal when calling an external command is the same as the exit code of the command. -The ``$CABAL`` environment variable is set to the path of the ``cabal-install`` executable +The ``$CABAL`` environment variable is set to the path of the :term:`cabal-install:exe:cabal` executable which invoked the subcommand. It is strongly recommended that you implement your custom commands by calling the CLI via the ``$CABAL`` variable rather than linking against the ``Cabal`` library. There is no guarantee that the subcommand will link against the same version of the -``Cabal`` library as ``cabal-install`` so it would lead to unexpected results and +``Cabal`` library as :term:`cabal-install:exe:cabal` so it would lead to unexpected results and incompatibilities. -``cabal-install`` can also display the help message of the external command. +:term:`cabal-install:exe:cabal` can also display the help message of the external command. When ``cabal help `` is invoked, then ``cabal- --help`` will be called so your external command can display a help message. diff --git a/doc/getting-started.rst b/doc/getting-started.rst index 9a3d572a3d8..bc438f4ad33 100644 --- a/doc/getting-started.rst +++ b/doc/getting-started.rst @@ -4,7 +4,7 @@ Getting Started Installing Cabal ---------------- -The easiest and recommended way to install the ``cabal`` command-line tool +The easiest and recommended way to install the :term:`cabal` command-line tool on Linux, macOS, FreeBSD or Windows is through `ghcup `__. It installs the “Haskell toolchain”, which includes Cabal, the Haskell compiler `GHC `__ @@ -14,7 +14,7 @@ Creating a new application -------------------------- We create a minimal Haskell application to get a quick overview -of the ``cabal`` command-line tool: +of the :term:`cabal` command-line tool: 1. How to initialize a Haskell package. 2. How files are organized inside a package. @@ -125,7 +125,7 @@ In our application, we'll use a package called `haskell-say terminal with some embellishment. .. TIP:: - If you installed ``cabal`` a while ago but haven't used it recently you may + If you installed :term:`cabal` a while ago but haven't used it recently you may need to update the package index, you can do this by running ``cabal update``. diff --git a/doc/how-to-run-in-windows.rst b/doc/how-to-run-in-windows.rst index 53aeb33b849..43dc0583295 100644 --- a/doc/how-to-run-in-windows.rst +++ b/doc/how-to-run-in-windows.rst @@ -62,7 +62,7 @@ Ensure that Cabal can call the tools it needs Cabal sometimes needs to call tools that do not come with Windows (such as ``make`` or even ``git``). The MSYS2 project makes many of them available on Windows. The directories where those are located need to be made visible in the -``PATH`` when executing ``cabal``. For that, Cabal provides the +``PATH`` when executing :term:`cabal`. For that, Cabal provides the ``extra-prog-path`` configuration option. Your :ref:`global configuration ` should include this option: diff --git a/doc/nix-local-build.rst b/doc/nix-local-build.rst index 6144cea85ba..3830c67b376 100644 --- a/doc/nix-local-build.rst +++ b/doc/nix-local-build.rst @@ -33,7 +33,7 @@ together. To build multiple Cabal packages, you need to first create a ``cabal.project`` file which declares where all the local package directories live. For example, in the Cabal repository, there is a root directory with a folder per package, e.g., the folders ``Cabal`` and -``cabal-install``. The ``cabal.project`` file specifies each folder as +:term:`cabal-install:exe:cabal`. The ``cabal.project`` file specifies each folder as part of the project: .. code-block:: cabal @@ -243,7 +243,7 @@ Caching Nix-style local builds support a robust caching system which helps to reduce the time it takes to execute a rebuild cycle. While the details of how -``cabal-install`` does caching are an implementation detail and may +:term:`cabal-install:exe:cabal` does caching are an implementation detail and may change in the future, knowing what gets cached is helpful for understanding the performance characteristics of invocations to ``build``. The cached intermediate results are stored in @@ -255,7 +255,7 @@ this folder (the most important two are first): ``solver-plan`` (binary) The result of calling the dependency solver, assuming that the - Hackage index, local ``cabal.project`` file, and local ``cabal`` + Hackage index, local ``cabal.project`` file, and local :term:`cabal` files are unmodified. (Notably, we do NOT have to dependency solve again if new build products are stored in the global store; the invocation of the dependency solver is independent of what is @@ -279,7 +279,7 @@ this folder (the most important two are first): into pre-existing copies from the store. ``plan.json`` (JSON) A JSON serialization of the computed install plan intended - for integrating ``cabal`` with external tooling. + for integrating :term:`cabal` with external tooling. The `cabal-plan `__ package provides a library for parsing ``plan.json`` files into a Haskell data structure as well as an example tool showing possible diff --git a/doc/package-concepts.rst b/doc/package-concepts.rst index 25cfeb13fba..77cc6b18317 100644 --- a/doc/package-concepts.rst +++ b/doc/package-concepts.rst @@ -143,7 +143,7 @@ Explicit dependencies and automatic package management Cabal takes the approach that all packages dependencies are specified explicitly and specified in a declarative way. The point is to enable -automatic package management. This means tools like ``cabal`` can +automatic package management. This means tools like :term:`cabal` can resolve dependencies and install a package plus all of its dependencies automatically. Alternatively, it is possible to mechanically (or mostly mechanically) translate Cabal packages into system packages and let the diff --git a/doc/setup-commands.rst b/doc/setup-commands.rst index 69f9e276cf4..b57b643d7ea 100644 --- a/doc/setup-commands.rst +++ b/doc/setup-commands.rst @@ -1006,7 +1006,7 @@ Miscellaneous options ``ld`` that do not support response file arguments (i.e. ``@file`` arguments). You may want this flag only if you specify custom ar executable. For system ``ar`` or the one bundled with ``ghc`` on - Windows the ``cabal`` should do the right thing and hence should + Windows the :term:`cabal` should do the right thing and hence should normally not require this flag. .. _setup-build: