From 870b2237082b8ce45b50487b56f2c92c4f62917c Mon Sep 17 00:00:00 2001 From: Phil de Joux Date: Wed, 19 Aug 2026 12:11:23 -0400 Subject: [PATCH] Add command --help Makefile recipes - Strip absolute path from help.txt - Reproduce and mitigate failure locally .DELETE_ON_ERROR - Remove build step, run is enough - Setup.hs copy output has bad ending --- .github/workflows/cmd-help.yml | 50 +++ doc/Makefile | 118 +++++++ doc/cmd-v1-help/bench.txt | 56 ++++ doc/cmd-v1-help/build.txt | 43 +++ doc/cmd-v1-help/clean.txt | 26 ++ doc/cmd-v1-help/configure.txt | 226 +++++++++++++ doc/cmd-v1-help/copy.txt | 31 ++ doc/cmd-v1-help/freeze.txt | 86 +++++ doc/cmd-v1-help/gen-bounds.txt | 22 ++ doc/cmd-v1-help/haddock.txt | 60 ++++ doc/cmd-v1-help/install.txt | 396 +++++++++++++++++++++++ doc/cmd-v1-help/reconfigure.txt | 222 +++++++++++++ doc/cmd-v1-help/register.txt | 33 ++ doc/cmd-v1-help/repl.txt | 53 +++ doc/cmd-v1-help/run.txt | 42 +++ doc/cmd-v1-help/test.txt | 72 +++++ doc/cmd-v2-help/bench.txt | 383 ++++++++++++++++++++++ doc/cmd-v2-help/build.txt | 385 ++++++++++++++++++++++ doc/cmd-v2-help/clean.txt | 22 ++ doc/cmd-v2-help/configure.txt | 392 +++++++++++++++++++++++ doc/cmd-v2-help/exec.txt | 373 ++++++++++++++++++++++ doc/cmd-v2-help/fetch.txt | 76 +++++ doc/cmd-v2-help/freeze.txt | 387 ++++++++++++++++++++++ doc/cmd-v2-help/gen-bounds.txt | 370 +++++++++++++++++++++ doc/cmd-v2-help/get.txt | 39 +++ doc/cmd-v2-help/haddock-project.txt | 41 +++ doc/cmd-v2-help/haddock.txt | 382 ++++++++++++++++++++++ doc/cmd-v2-help/help.txt | 115 +++++++ doc/cmd-v2-help/hscolour.txt | 22 ++ doc/cmd-v2-help/info.txt | 18 ++ doc/cmd-v2-help/init.txt | 87 +++++ doc/cmd-v2-help/install.txt | 375 ++++++++++++++++++++++ doc/cmd-v2-help/list-bin.txt | 365 +++++++++++++++++++++ doc/cmd-v2-help/list.txt | 31 ++ doc/cmd-v2-help/outdated.txt | 378 ++++++++++++++++++++++ doc/cmd-v2-help/path.txt | 388 ++++++++++++++++++++++ doc/cmd-v2-help/repl.txt | 408 ++++++++++++++++++++++++ doc/cmd-v2-help/report.txt | 19 ++ doc/cmd-v2-help/run.txt | 389 ++++++++++++++++++++++ doc/cmd-v2-help/sdist.txt | 25 ++ doc/cmd-v2-help/target.txt | 405 +++++++++++++++++++++++ doc/cmd-v2-help/test.txt | 385 ++++++++++++++++++++++ doc/cmd-v2-help/unpack.txt | 39 +++ doc/cmd-v2-help/update.txt | 383 ++++++++++++++++++++++ doc/cmd-v2-help/upload.txt | 33 ++ doc/cmd-v2-help/user-config.txt | 29 ++ doc/cmd-v2-hidden-help/act-as-setup.txt | 7 + doc/cmd-v2-hidden-help/format.txt | 6 + doc/cmd-v2-hidden-help/man.txt | 11 + doc/setup-help/bench.txt | 31 ++ doc/setup-help/build.txt | 34 ++ doc/setup-help/clean.txt | 17 + doc/setup-help/configure.txt | 196 ++++++++++++ doc/setup-help/copy.txt | 23 ++ doc/setup-help/haddock.txt | 51 +++ doc/setup-help/help.txt | 38 +++ doc/setup-help/hscolour.txt | 22 ++ doc/setup-help/install.txt | 27 ++ doc/setup-help/register.txt | 24 ++ doc/setup-help/repl.txt | 44 +++ doc/setup-help/sdist.txt | 17 + doc/setup-help/test.txt | 46 +++ doc/setup-help/unregister.txt | 18 ++ fix-whitespace.yaml | 1 + 64 files changed, 8893 insertions(+) create mode 100644 .github/workflows/cmd-help.yml create mode 100644 doc/cmd-v1-help/bench.txt create mode 100644 doc/cmd-v1-help/build.txt create mode 100644 doc/cmd-v1-help/clean.txt create mode 100644 doc/cmd-v1-help/configure.txt create mode 100644 doc/cmd-v1-help/copy.txt create mode 100644 doc/cmd-v1-help/freeze.txt create mode 100644 doc/cmd-v1-help/gen-bounds.txt create mode 100644 doc/cmd-v1-help/haddock.txt create mode 100644 doc/cmd-v1-help/install.txt create mode 100644 doc/cmd-v1-help/reconfigure.txt create mode 100644 doc/cmd-v1-help/register.txt create mode 100644 doc/cmd-v1-help/repl.txt create mode 100644 doc/cmd-v1-help/run.txt create mode 100644 doc/cmd-v1-help/test.txt create mode 100644 doc/cmd-v2-help/bench.txt create mode 100644 doc/cmd-v2-help/build.txt create mode 100644 doc/cmd-v2-help/clean.txt create mode 100644 doc/cmd-v2-help/configure.txt create mode 100644 doc/cmd-v2-help/exec.txt create mode 100644 doc/cmd-v2-help/fetch.txt create mode 100644 doc/cmd-v2-help/freeze.txt create mode 100644 doc/cmd-v2-help/gen-bounds.txt create mode 100644 doc/cmd-v2-help/get.txt create mode 100644 doc/cmd-v2-help/haddock-project.txt create mode 100644 doc/cmd-v2-help/haddock.txt create mode 100644 doc/cmd-v2-help/help.txt create mode 100644 doc/cmd-v2-help/hscolour.txt create mode 100644 doc/cmd-v2-help/info.txt create mode 100644 doc/cmd-v2-help/init.txt create mode 100644 doc/cmd-v2-help/install.txt create mode 100644 doc/cmd-v2-help/list-bin.txt create mode 100644 doc/cmd-v2-help/list.txt create mode 100644 doc/cmd-v2-help/outdated.txt create mode 100644 doc/cmd-v2-help/path.txt create mode 100644 doc/cmd-v2-help/repl.txt create mode 100644 doc/cmd-v2-help/report.txt create mode 100644 doc/cmd-v2-help/run.txt create mode 100644 doc/cmd-v2-help/sdist.txt create mode 100644 doc/cmd-v2-help/target.txt create mode 100644 doc/cmd-v2-help/test.txt create mode 100644 doc/cmd-v2-help/unpack.txt create mode 100644 doc/cmd-v2-help/update.txt create mode 100644 doc/cmd-v2-help/upload.txt create mode 100644 doc/cmd-v2-help/user-config.txt create mode 100644 doc/cmd-v2-hidden-help/act-as-setup.txt create mode 100644 doc/cmd-v2-hidden-help/format.txt create mode 100644 doc/cmd-v2-hidden-help/man.txt create mode 100644 doc/setup-help/bench.txt create mode 100644 doc/setup-help/build.txt create mode 100644 doc/setup-help/clean.txt create mode 100644 doc/setup-help/configure.txt create mode 100644 doc/setup-help/copy.txt create mode 100644 doc/setup-help/haddock.txt create mode 100644 doc/setup-help/help.txt create mode 100644 doc/setup-help/hscolour.txt create mode 100644 doc/setup-help/install.txt create mode 100644 doc/setup-help/register.txt create mode 100644 doc/setup-help/repl.txt create mode 100644 doc/setup-help/sdist.txt create mode 100644 doc/setup-help/test.txt create mode 100644 doc/setup-help/unregister.txt diff --git a/.github/workflows/cmd-help.yml b/.github/workflows/cmd-help.yml new file mode 100644 index 00000000000..bf2148c49ad --- /dev/null +++ b/.github/workflows/cmd-help.yml @@ -0,0 +1,50 @@ +name: Command help docs + +# See: https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#concurrency. +concurrency: + group: ${{ github.ref }}-${{ github.workflow }} + cancel-in-progress: true + +on: + push: + branches: + - master + paths: &paths + - doc/Makefile + - doc/cmd-v1-help/** + - doc/cmd-v2-help/** + - doc/cmd-v2-hidden-help/** + - doc/setup-help/** + - cabal-install/src/Distribution/Client/Cmd*.hs + - cabal-install/src/Distribution/Client/Main.hs + - cabal-install/src/Distribution/Client/Setup.hs + - Cabal/src/Distribution/Simple.hs + - Cabal/src/Distribution/Simple/Setup/** + pull_request: + paths: *paths + workflow_dispatch: {} + +jobs: + cmd-help: + name: Check command help docs are up to date + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + - uses: haskell-actions/setup@v2 + with: + ghc-version: 9.12.2 + cabal-version: latest + - run: cabal v2-update + - name: Cache dependencies + uses: actions/cache@v6 + with: + path: ~/.local/state/cabal + key: ${{ runner.os }}-cmd-help-${{ hashFiles('cabal.project', 'cabal-install/cabal-install.cabal', 'Cabal/Cabal.cabal') }} + restore-keys: ${{ runner.os }}-cmd-help- + - name: Regenerate command help docs + run: make -B -C doc cmd-help + - name: Check that diff is clean + run: | + git status --porcelain=v1 doc + git diff --stat doc + git diff -p --exit-code doc diff --git a/doc/Makefile b/doc/Makefile index 1cbedb71f82..b7b7cff5717 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -1,5 +1,9 @@ # Build and safety-check requirements.txt +# Remove a target if its recipe fails, so a failed `cabal run` can't leave a +# truncated *-help/*.txt behind for `git diff` to find. +.DELETE_ON_ERROR: + # skjold needs a personal github access token. This needs no permissions, # it is only required to query the GitHub GraphQL API v4. # See: https://pythonawesome.com/security-audit-python-project-dependencies-against-security-advisory-databases/ @@ -53,4 +57,118 @@ debug: @echo "SKJOLD_GITHUB_API_TOKEN = $${SKJOLD_GITHUB_API_TOKEN}" @echo "Is SKJOLD_GITHUB_API_TOKEN set? $${SKJOLD_GITHUB_API_TOKEN:+yes}" +CABAL_V1_COMMANDS := \ + bench \ + build \ + clean \ + configure \ + copy \ + freeze \ + gen-bounds \ + haddock \ + install \ + reconfigure \ + register \ + repl \ + run \ + test + +CABAL_COMMANDS := \ + bench \ + build \ + clean \ + configure \ + exec \ + fetch \ + freeze \ + gen-bounds \ + get \ + haddock \ + haddock-project \ + hscolour \ + info \ + init \ + install \ + list \ + list-bin \ + outdated \ + path \ + repl \ + report \ + run \ + sdist \ + target \ + test \ + unpack \ + update \ + upload \ + user-config + +CABAL_HIDDEN_COMMANDS := \ + act-as-setup \ + format \ + man + +# Distribution.Simple.defaultMain's commands, for build-type: Simple. +SETUP_COMMANDS := \ + bench \ + build \ + clean \ + configure \ + copy \ + haddock \ + hscolour \ + install \ + register \ + repl \ + sdist \ + test \ + unregister + +# NOTE: To silence the following warning, redirect stderr to /dev/null: +# Warning: this is a debug build of cabal-install with assertions enabled. +cmd-v1-help/%.txt: + @mkdir -p $(@D) + @cabal run -v0 cabal-install:exe:cabal -- v1-$* --help > $@ 2>/dev/null + +cmd-v2-help/%.txt: + @mkdir -p $(@D) + @cabal run -v0 cabal-install:exe:cabal -- $* --help > $@ 2>/dev/null + +# The "You can edit the cabal configuration file..." footer embeds an +# absolute, machine-specific config path, so strip it for reproducibility. +cmd-v2-help/help.txt: + @mkdir -p $(@D) + @cabal run -v0 cabal-install:exe:cabal -- --help 2>/dev/null \ + | sed '/^You can edit the cabal configuration file to set defaults:$$/,$$d' > $@ + +cmd-v2-hidden-help/%.txt: + @mkdir -p $(@D) + @cabal run -v0 cabal-install:exe:cabal -- $* --help > $@ 2>/dev/null + +# act-as-setup runs Distribution.Simple.defaultMainArgs directly; the "--" +# forwards args after it verbatim instead of being parsed by cabal itself. +setup-help/%.txt: + @mkdir -p $(@D) + @cabal run -v0 cabal-install:exe:cabal -- act-as-setup -- $* --help > $@ 2>/dev/null + +setup-help/help.txt: + @mkdir -p $(@D) + @cabal run -v0 cabal-install:exe:cabal -- act-as-setup -- --help > $@ 2>/dev/null + +.PHONY: cmd-v1-help +cmd-v1-help: $(addsuffix .txt,$(addprefix cmd-v1-help/,$(CABAL_V1_COMMANDS))) + +.PHONY: cmd-v2-help +cmd-v2-help: cmd-v2-help/help.txt $(addsuffix .txt,$(addprefix cmd-v2-help/,$(CABAL_COMMANDS))) + +.PHONY: cmd-v2-hidden-help +cmd-v2-hidden-help: $(addsuffix .txt,$(addprefix cmd-v2-hidden-help/,$(CABAL_HIDDEN_COMMANDS))) + +.PHONY: setup-help +setup-help: setup-help/help.txt $(addsuffix .txt,$(addprefix setup-help/,$(SETUP_COMMANDS))) + +.PHONY: cmd-help +cmd-help: cmd-v2-help cmd-v1-help cmd-v2-hidden-help setup-help + # EOF diff --git a/doc/cmd-v1-help/bench.txt b/doc/cmd-v1-help/bench.txt new file mode 100644 index 00000000000..d4e7d33b17a --- /dev/null +++ b/doc/cmd-v1-help/bench.txt @@ -0,0 +1,56 @@ +Run all/specific benchmarks. + +Usage: cabal v1-bench [FLAGS] + or: cabal v1-bench BENCHCOMPONENTS [FLAGS] + +If necessary (re)configures with `--enable-benchmarks` flag and builds the +benchmarks. + +Remember that the benchmarks' dependencies must be installed if there are +additional ones; e.g. with `cabal v1-install --only-dependencies +--enable-benchmarks`. + +By defining UserHooks in a custom Setup.hs, the package can define actions to +be executed before and after running benchmarks. + +Flags for v1-bench: + -h, --help # Show this help text + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + --builddir=DIR # The directory where Cabal puts generated build + files (default dist) + --cabal-file=PATH # use this Cabal file + --keep-temp-files # Keep temporary files. + -j[NUM], --jobs[=NUM] # Run NUM jobs simultaneously (or '$ncpus' if no + NUM is given). + --semaphore=SEMAPHORE # Use the specified semaphore identifier so GHC + can compile components in parallel + --with-PROG=PATH # Give the path to PROG + --PROG-option=OPT # Give an extra option to PROG (passed directly + to PROG as a single argument) + --PROG-options=OPTS # Give extra options to PROG (split on spaces, + use "" to prevent splitting) + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + --builddir=DIR # The directory where Cabal puts generated build + files (default dist) + --cabal-file=PATH # use this Cabal file + --keep-temp-files # Keep temporary files. + --benchmark-options=TEMPLATES + # Give extra options to benchmark executables + (split on spaces, use "" to prevent splitting; + name templates can use $pkgid, $compiler, $os, + $arch, $benchmark) + --benchmark-option=TEMPLATE # Give extra option to benchmark executables + (passed directly as a single argument; name + template can use $pkgid, $compiler, $os, + $arch, $benchmark) + +The v1-bench command is a part of the legacy v1 style of cabal usage. + +It is a legacy feature and will be removed in a future release of +cabal-install. Please file a bug if you cannot replicate a working v1- use +case with the nix-style commands. + +For more information, see: +https://cabal.readthedocs.io/en/latest/nix-local-build-overview.html diff --git a/doc/cmd-v1-help/build.txt b/doc/cmd-v1-help/build.txt new file mode 100644 index 00000000000..d8ef015e678 --- /dev/null +++ b/doc/cmd-v1-help/build.txt @@ -0,0 +1,43 @@ +Compile all/specific components. + +Usage: cabal v1-build [FLAGS] + or: cabal v1-build COMPONENTS [FLAGS] + +Components encompass executables, tests, and benchmarks. + +Affected by configuration options, see `v1-configure`. + +Flags for v1-build: + -h, --help # Show this help text + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + --builddir=DIR # The directory where Cabal puts generated build + files (default dist) + --cabal-file=PATH # use this Cabal file + --keep-temp-files # Keep temporary files. + -j[NUM], --jobs[=NUM] # Run NUM jobs simultaneously (or '$ncpus' if no + NUM is given). + --semaphore=SEMAPHORE # Use the specified semaphore identifier so GHC + can compile components in parallel + --with-PROG=PATH # Give the path to PROG + --PROG-option=OPT # Give an extra option to PROG (passed directly + to PROG as a single argument) + --PROG-options=OPTS # Give extra options to PROG (split on spaces, + use "" to prevent splitting) + +Examples: + cabal v1-build All the components in the package + cabal v1-build foo A component (i.e. lib, exe, test suite) + +The flags --with-PROG and --PROG-option(s) can be used with the following programs: + alex ar c2hs cpphs doctest gcc ghc ghc-pkg ghcjs ghcjs-pkg haddock happy hpc + hsc2hs hscolour jhc ld pkg-config runghc strip tar uhc + +The v1-build command is a part of the legacy v1 style of cabal usage. + +It is a legacy feature and will be removed in a future release of +cabal-install. Please file a bug if you cannot replicate a working v1- use +case with the nix-style commands. + +For more information, see: +https://cabal.readthedocs.io/en/latest/nix-local-build-overview.html diff --git a/doc/cmd-v1-help/clean.txt b/doc/cmd-v1-help/clean.txt new file mode 100644 index 00000000000..5ffb5fdea79 --- /dev/null +++ b/doc/cmd-v1-help/clean.txt @@ -0,0 +1,26 @@ +Clean up after a build. + +Usage: cabal v1-clean [FLAGS] + +Removes .hi, .o, preprocessed sources, etc. + +Flags for v1-clean: + -h, --help # Show this help text + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + --builddir=DIR # The directory where Cabal puts generated build + files (default dist) + --cabal-file=PATH # use this Cabal file + --keep-temp-files # Keep temporary files. + -s, --save-configure # Do not remove the configuration file + (dist/setup-config) during cleaning. Saves + need to reconfigure. + +The v1-clean command is a part of the legacy v1 style of cabal usage. + +It is a legacy feature and will be removed in a future release of +cabal-install. Please file a bug if you cannot replicate a working v1- use +case with the nix-style commands. + +For more information, see: +https://cabal.readthedocs.io/en/latest/nix-local-build-overview.html diff --git a/doc/cmd-v1-help/configure.txt b/doc/cmd-v1-help/configure.txt new file mode 100644 index 00000000000..7059ef5d400 --- /dev/null +++ b/doc/cmd-v1-help/configure.txt @@ -0,0 +1,226 @@ +Prepare to build the package. + +Usage: cabal v1-configure [FLAGS] + +Configure how the package is built by setting package (and other) flags. + +The configuration affects several other commands, including v1-build, v1-test, +v1-bench, v1-run, v1-repl. + +Flags for v1-configure: + -h, --help # Show this help text + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + --builddir=DIR # The directory where Cabal puts generated build + files (default dist) + --cabal-file=PATH # use this Cabal file + --keep-temp-files # Keep temporary files. + -g, --ghc # Compile with GHC + --ghcjs # Compile with GHCJS + --uhc # Compile with UHC + -w PATH or -wPATH, --with-compiler=PATH + # Give the path to a particular compiler + --with-hc-pkg=PATH # Give the path to the package tool + --prefix=DIR # Bake this prefix in preparation of + installation + --bindir=DIR # Installation directory for executables + --libdir=DIR # Installation directory for libraries + --libsubdir=DIR # Subdirectory of libdir in which libs are + installed + --dynlibdir=DIR # Installation directory for dynamic libraries + --bytecodelibdir=DIR # Installation directory for bytecode libraries + --libexecdir=DIR # Installation directory for program executables + --libexecsubdir=DIR # Subdirectory of libexecdir in which private + executables are installed + --datadir=DIR # Installation directory for read-only data + --datasubdir=DIR # Subdirectory of datadir in which data files + are installed + --docdir=DIR # Installation directory for documentation + --htmldir=DIR # Installation directory for HTML documentation + --haddockdir=DIR # Installation directory for haddock interfaces + --sysconfdir=DIR # Installation directory for configuration files + --program-prefix=PREFIX # Prefix to be applied to installed executables + --program-suffix=SUFFIX # Suffix to be applied to installed executables + --enable-library-vanilla # Enable Vanilla libraries + --disable-library-vanilla # Disable Vanilla libraries + -p, --enable-library-profiling + # Enable Library profiling + --disable-library-profiling # Disable Library profiling + --enable-shared # Enable Shared library + --disable-shared # Disable Shared library + --enable-static # Enable Static library + --disable-static # Disable Static library + --enable-library-bytecode # Enable Bytecode library + --disable-library-bytecode # Disable Bytecode library + --enable-executable-dynamic # Enable Executable dynamic linking + --disable-executable-dynamic # Disable Executable dynamic linking + --enable-executable-static # Enable Executable fully static linking + --disable-executable-static # Disable Executable fully static linking + --enable-profiling # Enable Executable and library profiling + --disable-profiling # Disable Executable and library profiling + --enable-profiling-shared # Enable Build profiling shared libraries + --disable-profiling-shared # Disable Build profiling shared libraries + --enable-executable-profiling + # Enable Executable profiling (DEPRECATED) + --disable-executable-profiling + # Disable Executable profiling (DEPRECATED) + --profiling-detail=level # Profiling detail level for executable and + library (default, none, exported-functions, + toplevel-functions, all-functions, late). + --library-profiling-detail=level + # Profiling detail level for libraries only. + -O[n], --enable-optimization[=n] + # Build with optimization (n is 0--2, default is + 1) + --disable-optimization # Build without optimization + --enable-debug-info[=n] # Emit debug info (n is 0--3, default is 0) + --disable-debug-info # Don't emit debug info + --enable-build-info # Enable build information generation during + project building + --disable-build-info # Disable build information generation during + project building + --enable-library-for-ghci # Enable compile library for use with GHCi + --disable-library-for-ghci # Disable compile library for use with GHCi + --enable-split-sections # Enable compile library code such that unneeded + definitions can be dropped from the final + executable (GHC 7.8+) + --disable-split-sections # Disable compile library code such that + unneeded definitions can be dropped from the + final executable (GHC 7.8+) + --enable-split-objs # Enable split library into smaller objects to + reduce binary sizes (GHC 6.6+) + --disable-split-objs # Disable split library into smaller objects to + reduce binary sizes (GHC 6.6+) + --enable-executable-stripping + # Enable strip executables upon installation to + reduce binary sizes + --disable-executable-stripping + # Disable strip executables upon installation to + reduce binary sizes + --enable-library-stripping # Enable strip libraries upon installation to + reduce binary sizes + --disable-library-stripping # Disable strip libraries upon installation to + reduce binary sizes + --configure-option=OPT # Extra option for configure + --user # Enable doing a per-user installation + --global # Disable doing a per-user installation + --package-db=DB # Append the given package database to the list + of package databases used (to satisfy + dependencies and register into). May be a + specific file, 'global' or 'user'. The initial + list is ['global'], ['global', 'user'], or + ['global', $sandbox], depending on context. + Use 'clear' to reset the list to empty. See + the user guide for details. + -f FLAGS or -fFLAGS, --flags=FLAGS + # Force values for the given flags in Cabal + conditionals in the .cabal file. E.g., + --flags="debug -usebytestrings" forces the + flag "debug" to true and "usebytestrings" to + false. + --extra-include-dirs=PATH # A list of directories to search for header + files + --enable-deterministic # Enable Try to be as deterministic as possible + (used by the test suite) + --disable-deterministic # Disable Try to be as deterministic as possible + (used by the test suite) + --ipid=IPID # Installed package ID to compile this package + as + --cid=CID # Installed component ID to compile this + component as + --extra-lib-dirs=PATH # A list of directories to search for external + libraries + --extra-lib-dirs-static=PATH # A list of directories to search for external + libraries when linking fully static + executables + --extra-framework-dirs=PATH # A list of directories to search for external + frameworks (OS X only) + --extra-prog-path=PATH # A list of directories to search for required + programs (in addition to the normal search + locations) + --instantiate-with=NAME=MOD # A mapping of signature names to concrete + module instantiations. + --enable-tests # Enable dependency checking and compilation for + test suites listed in the package description + file. + --disable-tests # Disable dependency checking and compilation + for test suites listed in the package + description file. + --enable-coverage # Enable build package with Haskell Program + Coverage. (GHC only) + --disable-coverage # Disable build package with Haskell Program + Coverage. (GHC only) + --enable-library-coverage # Enable build package with Haskell Program + Coverage. (GHC only) (DEPRECATED) + --disable-library-coverage # Disable build package with Haskell Program + Coverage. (GHC only) (DEPRECATED) + --enable-benchmarks # Enable dependency checking and compilation for + benchmarks listed in the package description + file. + --disable-benchmarks # Disable dependency checking and compilation + for benchmarks listed in the package + description file. + --enable-relocatable # Enable building a package that is relocatable. + (GHC only) + --disable-relocatable # Disable building a package that is + relocatable. (GHC only) + --disable-response-files # Enable workaround for old versions of programs + like "ar" that do not support @file arguments + --allow-depending-on-private-libs + # Allow depending on private libraries. If set, + the library visibility check MUST be done + externally. + --coverage-for=UNITID # A list of unit-ids of libraries to include in + the Haskell Program Coverage report. + --ignore-build-tools # Ignore build tool dependencies. If set, + declared build tools needn't be found for + compilation to proceed. + --with-PROG=PATH # Give the path to PROG + --PROG-option=OPT # Give an extra option to PROG (passed directly + to PROG as a single argument) + --PROG-options=OPTS # Give extra options to PROG (split on spaces, + use "" to prevent splitting) + --cabal-lib-version=VERSION # Select which version of the Cabal lib to use + to build packages (useful for testing). + --enable-append # Enable appending the new config to the old + config file + --disable-append # Disable appending the new config to the old + config file + --enable-backup # Enable the backup of the config file before + any alterations + --disable-backup # Disable the backup of the config file before + any alterations + -c CONSTRAINT or -cCONSTRAINT, --constraint=CONSTRAINT + # Specify constraints on a package (version, + installed/source, flags) + --preference=CONSTRAINT # Specify preferences (soft constraints) on the + version of a package + --solver=SOLVER # Select dependency solver to use (default: + modular). Choices: modular. + --allow-older[=DEPS] # Ignore lower bounds in all dependencies or + DEPS + --allow-newer[=DEPS] # Ignore upper bounds in all dependencies or + DEPS + --write-ghc-environment-files=always|never|ghc8.4.4+ + # Whether to create a .ghc.environment file + after a successful build (v2-build only) + +The flags --with-PROG and --PROG-option(s) can be used with the following programs: + alex ar c2hs cpphs doctest gcc ghc ghc-pkg ghcjs ghcjs-pkg haddock happy hpc + hsc2hs hscolour jhc ld pkg-config runghc strip tar uhc + +Examples: + cabal v1-configure + Configure with defaults; + cabal v1-configure --enable-tests -fcustomflag + Configure building package including tests, + with some package-specific flag. + +The v1-configure command is a part of the legacy v1 style of cabal usage. + +It is a legacy feature and will be removed in a future release of +cabal-install. Please file a bug if you cannot replicate a working v1- use +case with the nix-style commands. + +For more information, see: +https://cabal.readthedocs.io/en/latest/nix-local-build-overview.html diff --git a/doc/cmd-v1-help/copy.txt b/doc/cmd-v1-help/copy.txt new file mode 100644 index 00000000000..b446d91b46b --- /dev/null +++ b/doc/cmd-v1-help/copy.txt @@ -0,0 +1,31 @@ +Copy the files of all/specific components to install locations. + +Usage: cabal v1-copy [FLAGS] + or: cabal v1-copy COMPONENTS [FLAGS] + +Components encompass executables and libraries. Does not call register, and +allows a prefix at install time. Without the --destdir flag, configure +determines location. + +Flags for v1-copy: + -h, --help # Show this help text + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + --builddir=DIR # The directory where Cabal puts generated build + files (default dist) + --cabal-file=PATH # use this Cabal file + --keep-temp-files # Keep temporary files. + --destdir=DIR # directory to copy files to, prepended to + installation directories + +Examples: + cabal v1-copy All the components in the package + cabal v1-copy foo A component (i.e. lib, exe, test suite) +The v1-copy command is a part of the legacy v1 style of cabal usage. + +It is a legacy feature and will be removed in a future release of +cabal-install. Please file a bug if you cannot replicate a working v1- use +case with the nix-style commands. + +For more information, see: +https://cabal.readthedocs.io/en/latest/nix-local-build-overview.html diff --git a/doc/cmd-v1-help/freeze.txt b/doc/cmd-v1-help/freeze.txt new file mode 100644 index 00000000000..2357900bdf0 --- /dev/null +++ b/doc/cmd-v1-help/freeze.txt @@ -0,0 +1,86 @@ +Freeze dependencies. + +Usage: cabal freeze [FLAGS] + +Calculates a valid set of dependencies and their exact versions. If +successful, saves the result to the file `cabal.config`. + +The package versions specified in `cabal.config` will be used for any future +installs. + +An existing `cabal.config` is ignored and overwritten. + +Flags for v1-freeze: + -h, --help # Show this help text + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + --dry-run # Do not freeze anything, only print what would + be frozen + --enable-tests # Enable freezing of the dependencies of any + tests suites in the package description file. + --disable-tests # Disable freezing of the dependencies of any + tests suites in the package description file. + --enable-benchmarks # Enable freezing of the dependencies of any + benchmarks suites in the package description + file. + --disable-benchmarks # Disable freezing of the dependencies of any + benchmarks suites in the package description + file. + --solver=SOLVER # Select dependency solver to use (default: + modular). Choices: modular. + --max-backjumps=NUM # Maximum number of backjumps allowed while + solving (default: 4000). Use a negative number + to enable unlimited backtracking. Use 0 to + disable backtracking completely. + --reorder-goals # Try to reorder goals according to certain + heuristics. Slows things down on average, but + may make backtracking faster for some + packages. + --count-conflicts # Try to speed up solving by preferring goals + that are involved in a lot of conflicts + (default). + --fine-grained-conflicts # Skip a version of a package if it does not + resolve the conflicts encountered in the last + version, as a solver optimization (default). + --minimize-conflict-set # When there is no solution, try to improve the + error message by finding a minimal conflict + set (default: false). May increase run time + significantly. + --independent-goals # Treat several goals on the command line as + independent. If several goals depend on the + same package, different versions can be + chosen. + --prefer-oldest # Prefer the oldest (instead of the latest) + versions of packages available. Useful to + determine lower bounds in the build-depends + section. + --prefer-version=oldest|latest|installed-or-latest + # Select which version of a package that the + solver should prefer. Oldest is useful to + determine lower bounds in build-depends + section. Latest will prefer the latest + version. Installed-or-latest will prefer + installed versions and the latest version + otherwise. + --shadow-installed-packages # If multiple package instances of the same + version are installed, treat all but one as + shadowed. + --strong-flags # Do not defer flag choices (this used to be the + default in cabal-install <= 1.20). + --allow-boot-library-installs + # Allow cabal to install base, ghc-prim, + integer-simple, integer-gmp, and + template-haskell. + --reject-unconstrained-dependencies=none|all + # Require these packages to have constraints on + them if they are to be selected (default: + none). + +The v1-freeze command is a part of the legacy v1 style of cabal usage. + +It is a legacy feature and will be removed in a future release of +cabal-install. Please file a bug if you cannot replicate a working v1- use +case with the nix-style commands. + +For more information, see: +https://cabal.readthedocs.io/en/latest/nix-local-build-overview.html diff --git a/doc/cmd-v1-help/gen-bounds.txt b/doc/cmd-v1-help/gen-bounds.txt new file mode 100644 index 00000000000..ed0a72ab8f7 --- /dev/null +++ b/doc/cmd-v1-help/gen-bounds.txt @@ -0,0 +1,22 @@ +Generate dependency bounds. + +Usage: cabal gen-bounds [FLAGS] + +Generates bounds for all dependencies that do not currently have them. +Generated bounds are printed to stdout. You can then paste them into your +.cabal file. + + +Flags for v1-gen-bounds: + -h, --help # Show this help text + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + +The v1-gen-bounds command is a part of the legacy v1 style of cabal usage. + +It is a legacy feature and will be removed in a future release of +cabal-install. Please file a bug if you cannot replicate a working v1- use +case with the nix-style commands. + +For more information, see: +https://cabal.readthedocs.io/en/latest/nix-local-build-overview.html diff --git a/doc/cmd-v1-help/haddock.txt b/doc/cmd-v1-help/haddock.txt new file mode 100644 index 00000000000..ab52ac9a910 --- /dev/null +++ b/doc/cmd-v1-help/haddock.txt @@ -0,0 +1,60 @@ +Generate Haddock HTML documentation. + +Usage: cabal v1-haddock [FLAGS] + or: cabal v1-haddock COMPONENTS [FLAGS] + +Requires the program haddock, version 2.x. + +Flags for v1-haddock: + -h, --help # Show this help text + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + --builddir=DIR # The directory where Cabal puts generated build + files (default dist) + --cabal-file=PATH # use this Cabal file + --keep-temp-files # Keep temporary files. + --hoogle # Generate a hoogle database + --html # Generate HTML documentation (the default) + --html-location=URL # Location of HTML documentation for + pre-requisite packages + --for-hackage # Collection of flags to generate documentation + suitable for upload to hackage + --executables # Run haddock for Executables targets + --tests # Run haddock for Test Suite targets + --benchmarks # Run haddock for Benchmark targets + --foreign-libraries # Run haddock for Foreign Library targets + --all # Run haddock for all targets + --internal # Run haddock for internal modules and include + all symbols + --css=PATH # Use PATH as the haddock stylesheet + --hyperlink-source # Hyperlink the documentation to the source code + --quickjump # Generate an index for interactive + documentation navigation + --hscolour-css=PATH # Use PATH as the HsColour stylesheet + --contents-location=URL # Bake URL in as the location for the contents + page + --index-location=URL # Use a separately-generated HTML index + --base-url=URL # Base URL for static files. + --resources-dir=DIR # Location of Haddocks static / auxiliary files + --output-dir=DIR # Generate haddock documentation into this + directory. This flag is provided as a + technology preview and is subject to change in + the next releases. + --use-unicode # Pass --use-unicode option to haddock + --with-ghc=PATH # Give the path to ghc + --with-haddock=PATH # Give the path to haddock + --PROG-option=OPT # Give an extra option to PROG (passed directly + to PROG as a single argument) + --ghc-options=OPTS # Give extra options to ghc (split on spaces, + use "" to prevent splitting) + --haddock-options=OPTS # Give extra options to haddock (split on + spaces, use "" to prevent splitting) + +The v1-haddock command is a part of the legacy v1 style of cabal usage. + +It is a legacy feature and will be removed in a future release of +cabal-install. Please file a bug if you cannot replicate a working v1- use +case with the nix-style commands. + +For more information, see: +https://cabal.readthedocs.io/en/latest/nix-local-build-overview.html diff --git a/doc/cmd-v1-help/install.txt b/doc/cmd-v1-help/install.txt new file mode 100644 index 00000000000..b4937a719cc --- /dev/null +++ b/doc/cmd-v1-help/install.txt @@ -0,0 +1,396 @@ +Install packages. + +Usage: cabal v1-install [FLAGS] + or: cabal v1-install [FLAGS] PACKAGES + +Installs one or more packages. By default, the installed package will be +registered in the user's package database. +If PACKAGES are specified, downloads and installs those packages. Otherwise, +install the package in the current directory (and/or its dependencies) (there +must be exactly one .cabal file in the current directory). + +The flags to `v1-install` are saved and affect future commands such as +`v1-build` and `v1-repl`. See the help for `v1-configure` for a list of +commands being affected. + +Installed executables will by default be put into `~/.local/bin/`. If you want +installed executable to be available globally, make sure that the PATH +environment variable contains that directory. + + +Flags for v1-install: + -h, --help # Show this help text + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + --builddir=DIR # The directory where Cabal puts generated build + files (default dist) + --cabal-file=PATH # use this Cabal file + --keep-temp-files # Keep temporary files. + -g, --ghc # Compile with GHC + --ghcjs # Compile with GHCJS + --uhc # Compile with UHC + -w PATH or -wPATH, --with-compiler=PATH + # Give the path to a particular compiler + --with-hc-pkg=PATH # Give the path to the package tool + --prefix=DIR # Bake this prefix in preparation of + installation + --bindir=DIR # Installation directory for executables + --libdir=DIR # Installation directory for libraries + --libsubdir=DIR # Subdirectory of libdir in which libs are + installed + --dynlibdir=DIR # Installation directory for dynamic libraries + --bytecodelibdir=DIR # Installation directory for bytecode libraries + --libexecdir=DIR # Installation directory for program executables + --libexecsubdir=DIR # Subdirectory of libexecdir in which private + executables are installed + --datadir=DIR # Installation directory for read-only data + --datasubdir=DIR # Subdirectory of datadir in which data files + are installed + --docdir=DIR # Installation directory for documentation + --htmldir=DIR # Installation directory for HTML documentation + --haddockdir=DIR # Installation directory for haddock interfaces + --sysconfdir=DIR # Installation directory for configuration files + --program-prefix=PREFIX # Prefix to be applied to installed executables + --program-suffix=SUFFIX # Suffix to be applied to installed executables + --enable-library-vanilla # Enable Vanilla libraries + --disable-library-vanilla # Disable Vanilla libraries + -p, --enable-library-profiling + # Enable Library profiling + --disable-library-profiling # Disable Library profiling + --enable-shared # Enable Shared library + --disable-shared # Disable Shared library + --enable-static # Enable Static library + --disable-static # Disable Static library + --enable-library-bytecode # Enable Bytecode library + --disable-library-bytecode # Disable Bytecode library + --enable-executable-dynamic # Enable Executable dynamic linking + --disable-executable-dynamic # Disable Executable dynamic linking + --enable-executable-static # Enable Executable fully static linking + --disable-executable-static # Disable Executable fully static linking + --enable-profiling # Enable Executable and library profiling + --disable-profiling # Disable Executable and library profiling + --enable-profiling-shared # Enable Build profiling shared libraries + --disable-profiling-shared # Disable Build profiling shared libraries + --enable-executable-profiling + # Enable Executable profiling (DEPRECATED) + --disable-executable-profiling + # Disable Executable profiling (DEPRECATED) + --profiling-detail=level # Profiling detail level for executable and + library (default, none, exported-functions, + toplevel-functions, all-functions, late). + --library-profiling-detail=level + # Profiling detail level for libraries only. + -O[n], --enable-optimization[=n] + # Build with optimization (n is 0--2, default is + 1) + --disable-optimization # Build without optimization + --enable-debug-info[=n] # Emit debug info (n is 0--3, default is 0) + --disable-debug-info # Don't emit debug info + --enable-build-info # Enable build information generation during + project building + --disable-build-info # Disable build information generation during + project building + --enable-library-for-ghci # Enable compile library for use with GHCi + --disable-library-for-ghci # Disable compile library for use with GHCi + --enable-split-sections # Enable compile library code such that unneeded + definitions can be dropped from the final + executable (GHC 7.8+) + --disable-split-sections # Disable compile library code such that + unneeded definitions can be dropped from the + final executable (GHC 7.8+) + --enable-split-objs # Enable split library into smaller objects to + reduce binary sizes (GHC 6.6+) + --disable-split-objs # Disable split library into smaller objects to + reduce binary sizes (GHC 6.6+) + --enable-executable-stripping + # Enable strip executables upon installation to + reduce binary sizes + --disable-executable-stripping + # Disable strip executables upon installation to + reduce binary sizes + --enable-library-stripping # Enable strip libraries upon installation to + reduce binary sizes + --disable-library-stripping # Disable strip libraries upon installation to + reduce binary sizes + --configure-option=OPT # Extra option for configure + --user # Enable doing a per-user installation + --global # Disable doing a per-user installation + --package-db=DB # Append the given package database to the list + of package databases used (to satisfy + dependencies and register into). May be a + specific file, 'global' or 'user'. The initial + list is ['global'], ['global', 'user'], or + ['global', $sandbox], depending on context. + Use 'clear' to reset the list to empty. See + the user guide for details. + -f FLAGS or -fFLAGS, --flags=FLAGS + # Force values for the given flags in Cabal + conditionals in the .cabal file. E.g., + --flags="debug -usebytestrings" forces the + flag "debug" to true and "usebytestrings" to + false. + --extra-include-dirs=PATH # A list of directories to search for header + files + --enable-deterministic # Enable Try to be as deterministic as possible + (used by the test suite) + --disable-deterministic # Disable Try to be as deterministic as possible + (used by the test suite) + --ipid=IPID # Installed package ID to compile this package + as + --cid=CID # Installed component ID to compile this + component as + --extra-lib-dirs=PATH # A list of directories to search for external + libraries + --extra-lib-dirs-static=PATH # A list of directories to search for external + libraries when linking fully static + executables + --extra-framework-dirs=PATH # A list of directories to search for external + frameworks (OS X only) + --extra-prog-path=PATH # A list of directories to search for required + programs (in addition to the normal search + locations) + --instantiate-with=NAME=MOD # A mapping of signature names to concrete + module instantiations. + --enable-tests # Enable dependency checking and compilation for + test suites listed in the package description + file. + --disable-tests # Disable dependency checking and compilation + for test suites listed in the package + description file. + --enable-coverage # Enable build package with Haskell Program + Coverage. (GHC only) + --disable-coverage # Disable build package with Haskell Program + Coverage. (GHC only) + --enable-library-coverage # Enable build package with Haskell Program + Coverage. (GHC only) (DEPRECATED) + --disable-library-coverage # Disable build package with Haskell Program + Coverage. (GHC only) (DEPRECATED) + --enable-benchmarks # Enable dependency checking and compilation for + benchmarks listed in the package description + file. + --disable-benchmarks # Disable dependency checking and compilation + for benchmarks listed in the package + description file. + --enable-relocatable # Enable building a package that is relocatable. + (GHC only) + --disable-relocatable # Disable building a package that is + relocatable. (GHC only) + --disable-response-files # Enable workaround for old versions of programs + like "ar" that do not support @file arguments + --allow-depending-on-private-libs + # Allow depending on private libraries. If set, + the library visibility check MUST be done + externally. + --coverage-for=UNITID # A list of unit-ids of libraries to include in + the Haskell Program Coverage report. + --ignore-build-tools # Ignore build tool dependencies. If set, + declared build tools needn't be found for + compilation to proceed. + --with-PROG=PATH # Give the path to PROG + --PROG-option=OPT # Give an extra option to PROG (passed directly + to PROG as a single argument) + --PROG-options=OPTS # Give extra options to PROG (split on spaces, + use "" to prevent splitting) + --cabal-lib-version=VERSION # Select which version of the Cabal lib to use + to build packages (useful for testing). + --enable-append # Enable appending the new config to the old + config file + --disable-append # Disable appending the new config to the old + config file + --enable-backup # Enable the backup of the config file before + any alterations + --disable-backup # Disable the backup of the config file before + any alterations + -c CONSTRAINT or -cCONSTRAINT, --constraint=CONSTRAINT + # Specify constraints on a package (version, + installed/source, flags) + --preference=CONSTRAINT # Specify preferences (soft constraints) on the + version of a package + --solver=SOLVER # Select dependency solver to use (default: + modular). Choices: modular. + --allow-older[=DEPS] # Ignore lower bounds in all dependencies or + DEPS + --allow-newer[=DEPS] # Ignore upper bounds in all dependencies or + DEPS + --write-ghc-environment-files=always|never|ghc8.4.4+ + # Whether to create a .ghc.environment file + after a successful build (v2-build only) + --enable-documentation # Enable building of documentation + --disable-documentation # Disable building of documentation + --doc-index-file=TEMPLATE # A central index of haddock API documentation + (template cannot use $pkgid) + --dry-run # Do not install anything, only print what would + be installed. + --only-download # Do not build anything, only fetch the + packages. + --max-backjumps=NUM # Maximum number of backjumps allowed while + solving (default: 4000). Use a negative number + to enable unlimited backtracking. Use 0 to + disable backtracking completely. + --reorder-goals # Try to reorder goals according to certain + heuristics. Slows things down on average, but + may make backtracking faster for some + packages. + --count-conflicts # Try to speed up solving by preferring goals + that are involved in a lot of conflicts + (default). + --fine-grained-conflicts # Skip a version of a package if it does not + resolve the conflicts encountered in the last + version, as a solver optimization (default). + --minimize-conflict-set # When there is no solution, try to improve the + error message by finding a minimal conflict + set (default: false). May increase run time + significantly. + --independent-goals # Treat several goals on the command line as + independent. If several goals depend on the + same package, different versions can be + chosen. + --prefer-oldest # Prefer the oldest (instead of the latest) + versions of packages available. Useful to + determine lower bounds in the build-depends + section. + --prefer-version=oldest|latest|installed-or-latest + # Select which version of a package that the + solver should prefer. Oldest is useful to + determine lower bounds in build-depends + section. Latest will prefer the latest + version. Installed-or-latest will prefer + installed versions and the latest version + otherwise. + --shadow-installed-packages # If multiple package instances of the same + version are installed, treat all but one as + shadowed. + --strong-flags # Do not defer flag choices (this used to be the + default in cabal-install <= 1.20). + --allow-boot-library-installs + # Allow cabal to install base, ghc-prim, + integer-simple, integer-gmp, and + template-haskell. + --reject-unconstrained-dependencies=none|all + # Require these packages to have constraints on + them if they are to be selected (default: + none). + --reinstall # Install even if it means installing the same + version again. + --avoid-reinstalls # Do not select versions that would + destructively overwrite installed packages. + --force-reinstalls # Reinstall packages even if they will most + likely break other installed packages. + --upgrade-dependencies # Pick the latest version for all dependencies, + rather than trying to pick an installed + version. + --only-dependencies # Install only the dependencies necessary to + build the given packages + --dependencies-only # A synonym for --only-dependencies + --index-state=STATE # Use source package index state as it existed + at a previous time. Accepts unix-timestamps + (e.g. '@1474732068'), ISO8601 UTC timestamps + (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' + (default: 'HEAD'). + --root-cmd=COMMAND # (No longer supported, do not use.) + --symlink-bindir=DIR # Add symlinks to installed executables into + this directory. + --build-summary=TEMPLATE # Save build summaries to file (name template + can use $pkgid, $compiler, $os, $arch) + --build-log=TEMPLATE # Log all builds to file (name template can use + $pkgid, $compiler, $os, $arch) + --remote-build-reporting=LEVEL + # Generate build reports to send to a remote + server (none, anonymous or detailed). + --report-planning-failure # Generate build reports when the dependency + solver fails. This is used by the Hackage + build bot. + --enable-per-component # Enable Per-component builds when possible + --disable-per-component # Disable Per-component builds when possible + --run-tests # Run package test suites during installation. + --semaphore # Use a semaphore so GHC can compile components + in parallel + -j[NUM], --jobs[=NUM] # Run NUM jobs simultaneously (or '$ncpus' if no + NUM is given). + --keep-going # After a build failure, continue to build other + unaffected packages. + --offline # Don't download packages from the Internet. + --build-timings # Print elapsed time for each build phase. + --haddock-hoogle # Generate a hoogle database + --haddock-html # Generate HTML documentation (the default) + --haddock-html-location=URL # Location of HTML documentation for + pre-requisite packages + --haddock-for-hackage # Collection of flags to generate documentation + suitable for upload to hackage + --haddock-executables # Run haddock for Executables targets + --haddock-tests # Run haddock for Test Suite targets + --haddock-benchmarks # Run haddock for Benchmark targets + --haddock-all # Run haddock for all targets + --haddock-internal # Run haddock for internal modules and include + all symbols + --haddock-css=PATH # Use PATH as the haddock stylesheet + --haddock-hyperlink-source # Hyperlink the documentation to the source code + --haddock-quickjump # Generate an index for interactive + documentation navigation + --haddock-hscolour-css=PATH # Use PATH as the HsColour stylesheet + --haddock-contents-location=URL + # Bake URL in as the location for the contents + page + --haddock-base-url=URL # Base URL for static files. + --haddock-resources-dir=DIR # Location of Haddocks static / auxiliary files + --haddock-output-dir=DIR # Generate haddock documentation into this + directory. This flag is provided as a + technology preview and is subject to change in + the next releases. + --haddock-use-unicode # Pass --use-unicode option to haddock + --test-log=TEMPLATE # Log all test suite results to file (name + template can use $pkgid, $compiler, $os, + $arch, $test-suite, $result) + --test-machine-log=TEMPLATE # Produce a machine-readable log file (name + template can use $pkgid, $compiler, $os, + $arch, $result) + --test-show-details=FILTER # 'always': always show results of individual + test cases. 'never': never show results of + individual test cases. 'failures': show + results of failing test cases. 'streaming': + show results of test cases in real + time.'direct': send results of test cases in + real time; no log file. + --test-keep-tix-files # Keep .tix files for HPC between test runs + --test-wrapper=FILE # Run test through a wrapper. + --test-fail-when-no-test-suites + # Exit with failure when no test suites are + found. + --test-options=TEMPLATES # Give extra options to test executables (split + on spaces, use "" to prevent splitting; name + templates can use $pkgid, $compiler, $os, + $arch, $test-suite) + --test-option=TEMPLATE # Give extra option to test executables (passed + directly as a single argument; name template + can use $pkgid, $compiler, $os, $arch, + $test-suite) + --benchmark-options=TEMPLATES + # Give extra options to benchmark executables + (split on spaces, use "" to prevent splitting; + name templates can use $pkgid, $compiler, $os, + $arch, $benchmark) + --benchmark-option=TEMPLATE # Give extra option to benchmark executables + (passed directly as a single argument; name + template can use $pkgid, $compiler, $os, + $arch, $benchmark) + +The flags --with-PROG and --PROG-option(s) can be used with the following programs: + alex ar c2hs cpphs doctest gcc ghc ghc-pkg ghcjs ghcjs-pkg haddock happy hpc + hsc2hs hscolour jhc ld pkg-config runghc strip tar uhc + +Examples: + cabal v1-install Package in the current directory + cabal v1-install foo Package from the hackage server + cabal v1-install foo-1.0 Specific version of a package + cabal v1-install 'foo < 2' Constrained package version + cabal v1-install haddock --bindir=$HOME/hask-bin/ --datadir=$HOME/hask-data/ + Change installation destination + +The v1-install command is a part of the legacy v1 style of cabal usage. + +It is a legacy feature and will be removed in a future release of +cabal-install. Please file a bug if you cannot replicate a working v1- use +case with the nix-style commands. + +For more information, see: +https://cabal.readthedocs.io/en/latest/nix-local-build-overview.html diff --git a/doc/cmd-v1-help/reconfigure.txt b/doc/cmd-v1-help/reconfigure.txt new file mode 100644 index 00000000000..15d821d1358 --- /dev/null +++ b/doc/cmd-v1-help/reconfigure.txt @@ -0,0 +1,222 @@ +Reconfigure the package if necessary. + +Usage: cabal v1-reconfigure [FLAGS] + +Run `configure` with the most recently used flags, or append FLAGS to the most +recently used configuration. Accepts the same flags as `cabal v1-configure'. +If the package has never been configured, the default flags are used. + +Flags for v1-reconfigure: + -h, --help # Show this help text + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + --builddir=DIR # The directory where Cabal puts generated build + files (default dist) + --cabal-file=PATH # use this Cabal file + --keep-temp-files # Keep temporary files. + -g, --ghc # Compile with GHC + --ghcjs # Compile with GHCJS + --uhc # Compile with UHC + -w PATH or -wPATH, --with-compiler=PATH + # Give the path to a particular compiler + --with-hc-pkg=PATH # Give the path to the package tool + --prefix=DIR # Bake this prefix in preparation of + installation + --bindir=DIR # Installation directory for executables + --libdir=DIR # Installation directory for libraries + --libsubdir=DIR # Subdirectory of libdir in which libs are + installed + --dynlibdir=DIR # Installation directory for dynamic libraries + --bytecodelibdir=DIR # Installation directory for bytecode libraries + --libexecdir=DIR # Installation directory for program executables + --libexecsubdir=DIR # Subdirectory of libexecdir in which private + executables are installed + --datadir=DIR # Installation directory for read-only data + --datasubdir=DIR # Subdirectory of datadir in which data files + are installed + --docdir=DIR # Installation directory for documentation + --htmldir=DIR # Installation directory for HTML documentation + --haddockdir=DIR # Installation directory for haddock interfaces + --sysconfdir=DIR # Installation directory for configuration files + --program-prefix=PREFIX # Prefix to be applied to installed executables + --program-suffix=SUFFIX # Suffix to be applied to installed executables + --enable-library-vanilla # Enable Vanilla libraries + --disable-library-vanilla # Disable Vanilla libraries + -p, --enable-library-profiling + # Enable Library profiling + --disable-library-profiling # Disable Library profiling + --enable-shared # Enable Shared library + --disable-shared # Disable Shared library + --enable-static # Enable Static library + --disable-static # Disable Static library + --enable-library-bytecode # Enable Bytecode library + --disable-library-bytecode # Disable Bytecode library + --enable-executable-dynamic # Enable Executable dynamic linking + --disable-executable-dynamic # Disable Executable dynamic linking + --enable-executable-static # Enable Executable fully static linking + --disable-executable-static # Disable Executable fully static linking + --enable-profiling # Enable Executable and library profiling + --disable-profiling # Disable Executable and library profiling + --enable-profiling-shared # Enable Build profiling shared libraries + --disable-profiling-shared # Disable Build profiling shared libraries + --enable-executable-profiling + # Enable Executable profiling (DEPRECATED) + --disable-executable-profiling + # Disable Executable profiling (DEPRECATED) + --profiling-detail=level # Profiling detail level for executable and + library (default, none, exported-functions, + toplevel-functions, all-functions, late). + --library-profiling-detail=level + # Profiling detail level for libraries only. + -O[n], --enable-optimization[=n] + # Build with optimization (n is 0--2, default is + 1) + --disable-optimization # Build without optimization + --enable-debug-info[=n] # Emit debug info (n is 0--3, default is 0) + --disable-debug-info # Don't emit debug info + --enable-build-info # Enable build information generation during + project building + --disable-build-info # Disable build information generation during + project building + --enable-library-for-ghci # Enable compile library for use with GHCi + --disable-library-for-ghci # Disable compile library for use with GHCi + --enable-split-sections # Enable compile library code such that unneeded + definitions can be dropped from the final + executable (GHC 7.8+) + --disable-split-sections # Disable compile library code such that + unneeded definitions can be dropped from the + final executable (GHC 7.8+) + --enable-split-objs # Enable split library into smaller objects to + reduce binary sizes (GHC 6.6+) + --disable-split-objs # Disable split library into smaller objects to + reduce binary sizes (GHC 6.6+) + --enable-executable-stripping + # Enable strip executables upon installation to + reduce binary sizes + --disable-executable-stripping + # Disable strip executables upon installation to + reduce binary sizes + --enable-library-stripping # Enable strip libraries upon installation to + reduce binary sizes + --disable-library-stripping # Disable strip libraries upon installation to + reduce binary sizes + --configure-option=OPT # Extra option for configure + --user # Enable doing a per-user installation + --global # Disable doing a per-user installation + --package-db=DB # Append the given package database to the list + of package databases used (to satisfy + dependencies and register into). May be a + specific file, 'global' or 'user'. The initial + list is ['global'], ['global', 'user'], or + ['global', $sandbox], depending on context. + Use 'clear' to reset the list to empty. See + the user guide for details. + -f FLAGS or -fFLAGS, --flags=FLAGS + # Force values for the given flags in Cabal + conditionals in the .cabal file. E.g., + --flags="debug -usebytestrings" forces the + flag "debug" to true and "usebytestrings" to + false. + --extra-include-dirs=PATH # A list of directories to search for header + files + --enable-deterministic # Enable Try to be as deterministic as possible + (used by the test suite) + --disable-deterministic # Disable Try to be as deterministic as possible + (used by the test suite) + --ipid=IPID # Installed package ID to compile this package + as + --cid=CID # Installed component ID to compile this + component as + --extra-lib-dirs=PATH # A list of directories to search for external + libraries + --extra-lib-dirs-static=PATH # A list of directories to search for external + libraries when linking fully static + executables + --extra-framework-dirs=PATH # A list of directories to search for external + frameworks (OS X only) + --extra-prog-path=PATH # A list of directories to search for required + programs (in addition to the normal search + locations) + --instantiate-with=NAME=MOD # A mapping of signature names to concrete + module instantiations. + --enable-tests # Enable dependency checking and compilation for + test suites listed in the package description + file. + --disable-tests # Disable dependency checking and compilation + for test suites listed in the package + description file. + --enable-coverage # Enable build package with Haskell Program + Coverage. (GHC only) + --disable-coverage # Disable build package with Haskell Program + Coverage. (GHC only) + --enable-library-coverage # Enable build package with Haskell Program + Coverage. (GHC only) (DEPRECATED) + --disable-library-coverage # Disable build package with Haskell Program + Coverage. (GHC only) (DEPRECATED) + --enable-benchmarks # Enable dependency checking and compilation for + benchmarks listed in the package description + file. + --disable-benchmarks # Disable dependency checking and compilation + for benchmarks listed in the package + description file. + --enable-relocatable # Enable building a package that is relocatable. + (GHC only) + --disable-relocatable # Disable building a package that is + relocatable. (GHC only) + --disable-response-files # Enable workaround for old versions of programs + like "ar" that do not support @file arguments + --allow-depending-on-private-libs + # Allow depending on private libraries. If set, + the library visibility check MUST be done + externally. + --coverage-for=UNITID # A list of unit-ids of libraries to include in + the Haskell Program Coverage report. + --ignore-build-tools # Ignore build tool dependencies. If set, + declared build tools needn't be found for + compilation to proceed. + --with-PROG=PATH # Give the path to PROG + --PROG-option=OPT # Give an extra option to PROG (passed directly + to PROG as a single argument) + --PROG-options=OPTS # Give extra options to PROG (split on spaces, + use "" to prevent splitting) + --cabal-lib-version=VERSION # Select which version of the Cabal lib to use + to build packages (useful for testing). + --enable-append # Enable appending the new config to the old + config file + --disable-append # Disable appending the new config to the old + config file + --enable-backup # Enable the backup of the config file before + any alterations + --disable-backup # Disable the backup of the config file before + any alterations + -c CONSTRAINT or -cCONSTRAINT, --constraint=CONSTRAINT + # Specify constraints on a package (version, + installed/source, flags) + --preference=CONSTRAINT # Specify preferences (soft constraints) on the + version of a package + --solver=SOLVER # Select dependency solver to use (default: + modular). Choices: modular. + --allow-older[=DEPS] # Ignore lower bounds in all dependencies or + DEPS + --allow-newer[=DEPS] # Ignore upper bounds in all dependencies or + DEPS + --write-ghc-environment-files=always|never|ghc8.4.4+ + # Whether to create a .ghc.environment file + after a successful build (v2-build only) + +Examples: + cabal v1-reconfigure + Configure with the most recently used flags. + cabal v1-reconfigure -w PATH + Reconfigure with the most recently used flags, + but use the compiler at PATH. + + +The v1-reconfigure command is a part of the legacy v1 style of cabal usage. + +It is a legacy feature and will be removed in a future release of +cabal-install. Please file a bug if you cannot replicate a working v1- use +case with the nix-style commands. + +For more information, see: +https://cabal.readthedocs.io/en/latest/nix-local-build-overview.html diff --git a/doc/cmd-v1-help/register.txt b/doc/cmd-v1-help/register.txt new file mode 100644 index 00000000000..329aff4e3ea --- /dev/null +++ b/doc/cmd-v1-help/register.txt @@ -0,0 +1,33 @@ +Register this package with the compiler. + +Usage: cabal v1-register [FLAGS] + +Flags for v1-register: + -h, --help # Show this help text + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + --builddir=DIR # The directory where Cabal puts generated build + files (default dist) + --cabal-file=PATH # use this Cabal file + --keep-temp-files # Keep temporary files. + --user # upon registration, register this package in + the user's local package database + --global # (default)upon registration, register this + package in the system-wide package database + --inplace # register the package in the build location, so + it can be used without being installed + --gen-script # instead of registering, generate a script to + register later + --gen-pkg-config[=PKG] # instead of registering, generate a package + registration file/directory + --print-ipid # print the installed package ID calculated for + this package + +The v1-register command is a part of the legacy v1 style of cabal usage. + +It is a legacy feature and will be removed in a future release of +cabal-install. Please file a bug if you cannot replicate a working v1- use +case with the nix-style commands. + +For more information, see: +https://cabal.readthedocs.io/en/latest/nix-local-build-overview.html diff --git a/doc/cmd-v1-help/repl.txt b/doc/cmd-v1-help/repl.txt new file mode 100644 index 00000000000..2f10e0b4b8f --- /dev/null +++ b/doc/cmd-v1-help/repl.txt @@ -0,0 +1,53 @@ +Open an interpreter session for the given component. + +Usage: cabal v1-repl [COMPONENT] [FLAGS] + +If the current directory contains no package, ignores COMPONENT parameters and +opens an interactive interpreter session; + +Otherwise, (re)configures with the given or default flags, and loads the +interpreter with the relevant modules. For executables, tests and benchmarks, +loads the main module (and its dependencies); for libraries all exposed/other +modules. + +The default component is the library itself, or the executable if that is the +only component. + +Support for loading specific modules is planned but not implemented yet. For +certain scenarios, `cabal v1-exec -- ghci :l Foo` may be used instead. Note +that `v1-exec` will not (re)configure and you will have to specify the +location of other modules, if required. + +Flags for v1-repl: + -h, --help # Show this help text + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + --builddir=DIR # The directory where Cabal puts generated build + files (default dist) + --cabal-file=PATH # use this Cabal file + --keep-temp-files # Keep temporary files. + --with-PROG=PATH # Give the path to PROG + --PROG-option=OPT # Give an extra option to PROG (passed directly + to PROG as a single argument) + --PROG-options=OPTS # Give extra options to PROG (split on spaces, + use "" to prevent splitting) + --repl-no-load # Disable loading of project modules at REPL + startup. + --repl-options=FLAG # Use the option(s) for the repl + --repl-multi-file=DIR # Write repl options to this directory rather + than starting repl mode + --with-repl=PATH # Give the path to a program to use for REPL + +Examples: + cabal v1-repl The first component in the package + cabal v1-repl foo A named component (i.e. lib, exe, test suite) + cabal v1-repl --ghc-options="-lstdc++" Specifying flags for interpreter + +The v1-repl command is a part of the legacy v1 style of cabal usage. + +It is a legacy feature and will be removed in a future release of +cabal-install. Please file a bug if you cannot replicate a working v1- use +case with the nix-style commands. + +For more information, see: +https://cabal.readthedocs.io/en/latest/nix-local-build-overview.html diff --git a/doc/cmd-v1-help/run.txt b/doc/cmd-v1-help/run.txt new file mode 100644 index 00000000000..b1b0a8f85f3 --- /dev/null +++ b/doc/cmd-v1-help/run.txt @@ -0,0 +1,42 @@ +Builds and runs an executable. + +Usage: cabal v1-run [FLAGS] [EXECUTABLE] [-- EXECUTABLE_FLAGS] + +Builds and then runs the specified executable. If no executable is specified, +but the package contains just one executable, that one is built and executed. + +Use `cabal v1-test --show-details=streaming` to run a test-suite and get its +full output. + +Flags for v1-run: + -h, --help # Show this help text + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + --builddir=DIR # The directory where Cabal puts generated build + files (default dist) + --cabal-file=PATH # use this Cabal file + --keep-temp-files # Keep temporary files. + -j[NUM], --jobs[=NUM] # Run NUM jobs simultaneously (or '$ncpus' if no + NUM is given). + --semaphore=SEMAPHORE # Use the specified semaphore identifier so GHC + can compile components in parallel + --with-PROG=PATH # Give the path to PROG + --PROG-option=OPT # Give an extra option to PROG (passed directly + to PROG as a single argument) + --PROG-options=OPTS # Give extra options to PROG (split on spaces, + use "" to prevent splitting) + +Examples: + cabal v1-run + Run the only executable in the current package; + cabal v1-run foo -- --fooflag + Works similar to `./foo --fooflag`. + +The v1-run command is a part of the legacy v1 style of cabal usage. + +It is a legacy feature and will be removed in a future release of +cabal-install. Please file a bug if you cannot replicate a working v1- use +case with the nix-style commands. + +For more information, see: +https://cabal.readthedocs.io/en/latest/nix-local-build-overview.html diff --git a/doc/cmd-v1-help/test.txt b/doc/cmd-v1-help/test.txt new file mode 100644 index 00000000000..6732042f66a --- /dev/null +++ b/doc/cmd-v1-help/test.txt @@ -0,0 +1,72 @@ +Run all/specific tests in the test suite. + +Usage: cabal v1-test [FLAGS] + or: cabal v1-test TESTCOMPONENTS [FLAGS] + +If necessary (re)configures with `--enable-tests` flag and builds the test +suite. + +Remember that the tests' dependencies must be installed if there are +additional ones; e.g. with `cabal v1-install --only-dependencies +--enable-tests`. + +By defining UserHooks in a custom Setup.hs, the package can define actions to +be executed before and after running tests. + +Flags for v1-test: + -h, --help # Show this help text + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + --builddir=DIR # The directory where Cabal puts generated build + files (default dist) + --cabal-file=PATH # use this Cabal file + --keep-temp-files # Keep temporary files. + -j[NUM], --jobs[=NUM] # Run NUM jobs simultaneously (or '$ncpus' if no + NUM is given). + --semaphore=SEMAPHORE # Use the specified semaphore identifier so GHC + can compile components in parallel + --with-PROG=PATH # Give the path to PROG + --PROG-option=OPT # Give an extra option to PROG (passed directly + to PROG as a single argument) + --PROG-options=OPTS # Give extra options to PROG (split on spaces, + use "" to prevent splitting) + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + --builddir=DIR # The directory where Cabal puts generated build + files (default dist) + --cabal-file=PATH # use this Cabal file + --keep-temp-files # Keep temporary files. + --log=TEMPLATE # Log all test suite results to file (name + template can use $pkgid, $compiler, $os, + $arch, $test-suite, $result) + --machine-log=TEMPLATE # Produce a machine-readable log file (name + template can use $pkgid, $compiler, $os, + $arch, $result) + --show-details=FILTER # 'always': always show results of individual + test cases. 'never': never show results of + individual test cases. 'failures': show + results of failing test cases. 'streaming': + show results of test cases in real + time.'direct': send results of test cases in + real time; no log file. + --keep-tix-files # Keep .tix files for HPC between test runs + --test-wrapper=FILE # Run test through a wrapper. + --fail-when-no-test-suites # Exit with failure when no test suites are + found. + --test-options=TEMPLATES # Give extra options to test executables (split + on spaces, use "" to prevent splitting; name + templates can use $pkgid, $compiler, $os, + $arch, $test-suite) + --test-option=TEMPLATE # Give extra option to test executables (passed + directly as a single argument; name template + can use $pkgid, $compiler, $os, $arch, + $test-suite) + +The v1-test command is a part of the legacy v1 style of cabal usage. + +It is a legacy feature and will be removed in a future release of +cabal-install. Please file a bug if you cannot replicate a working v1- use +case with the nix-style commands. + +For more information, see: +https://cabal.readthedocs.io/en/latest/nix-local-build-overview.html diff --git a/doc/cmd-v2-help/bench.txt b/doc/cmd-v2-help/bench.txt new file mode 100644 index 00000000000..c5ba5a99f02 --- /dev/null +++ b/doc/cmd-v2-help/bench.txt @@ -0,0 +1,383 @@ +Run benchmarks. + +Usage: cabal bench [TARGETS] [FLAGS] + +Runs the specified benchmarks, first ensuring they are up to date. + +Any benchmark in any package in the project can be specified. A package can be +specified in which case all the benchmarks in the package are run. The default +is to run all the benchmarks in the package in the current directory. + +Dependencies are built or rebuilt as necessary. Additional configuration flags +can be specified on the command line and these extend the project +configuration from the 'cabal.project', 'cabal.project.local' and other files. + +Flags for bench: + -h, --help # Show this help text + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + --builddir=DIR # The directory where Cabal puts generated build + files (default dist) + --keep-temp-files # Keep temporary files. + -g, --ghc # Compile with GHC + --ghcjs # Compile with GHCJS + --uhc # Compile with UHC + -w PATH or -wPATH, --with-compiler=PATH + # Give the path to a particular compiler + --with-hc-pkg=PATH # Give the path to the package tool + --prefix=DIR # Bake this prefix in preparation of + installation + --bindir=DIR # Installation directory for executables + --libdir=DIR # Installation directory for libraries + --libsubdir=DIR # Subdirectory of libdir in which libs are + installed + --dynlibdir=DIR # Installation directory for dynamic libraries + --bytecodelibdir=DIR # Installation directory for bytecode libraries + --libexecdir=DIR # Installation directory for program executables + --libexecsubdir=DIR # Subdirectory of libexecdir in which private + executables are installed + --datadir=DIR # Installation directory for read-only data + --datasubdir=DIR # Subdirectory of datadir in which data files + are installed + --docdir=DIR # Installation directory for documentation + --htmldir=DIR # Installation directory for HTML documentation + --haddockdir=DIR # Installation directory for haddock interfaces + --sysconfdir=DIR # Installation directory for configuration files + --program-prefix=PREFIX # Prefix to be applied to installed executables + --program-suffix=SUFFIX # Suffix to be applied to installed executables + --enable-library-vanilla # Enable Vanilla libraries + --disable-library-vanilla # Disable Vanilla libraries + -p, --enable-library-profiling + # Enable Library profiling + --disable-library-profiling # Disable Library profiling + --enable-shared # Enable Shared library + --disable-shared # Disable Shared library + --enable-static # Enable Static library + --disable-static # Disable Static library + --enable-library-bytecode # Enable Bytecode library + --disable-library-bytecode # Disable Bytecode library + --enable-executable-dynamic # Enable Executable dynamic linking + --disable-executable-dynamic # Disable Executable dynamic linking + --enable-executable-static # Enable Executable fully static linking + --disable-executable-static # Disable Executable fully static linking + --enable-profiling # Enable Executable and library profiling + --disable-profiling # Disable Executable and library profiling + --enable-profiling-shared # Enable Build profiling shared libraries + --disable-profiling-shared # Disable Build profiling shared libraries + --enable-executable-profiling + # Enable Executable profiling (DEPRECATED) + --disable-executable-profiling + # Disable Executable profiling (DEPRECATED) + --profiling-detail=level # Profiling detail level for executable and + library (default, none, exported-functions, + toplevel-functions, all-functions, late). + --library-profiling-detail=level + # Profiling detail level for libraries only. + -O[n], --enable-optimization[=n] + # Build with optimization (n is 0--2, default is + 1) + --disable-optimization # Build without optimization + --enable-debug-info[=n] # Emit debug info (n is 0--3, default is 0) + --disable-debug-info # Don't emit debug info + --enable-build-info # Enable build information generation during + project building + --disable-build-info # Disable build information generation during + project building + --enable-library-for-ghci # Enable compile library for use with GHCi + --disable-library-for-ghci # Disable compile library for use with GHCi + --enable-split-sections # Enable compile library code such that unneeded + definitions can be dropped from the final + executable (GHC 7.8+) + --disable-split-sections # Disable compile library code such that + unneeded definitions can be dropped from the + final executable (GHC 7.8+) + --enable-split-objs # Enable split library into smaller objects to + reduce binary sizes (GHC 6.6+) + --disable-split-objs # Disable split library into smaller objects to + reduce binary sizes (GHC 6.6+) + --enable-executable-stripping + # Enable strip executables upon installation to + reduce binary sizes + --disable-executable-stripping + # Disable strip executables upon installation to + reduce binary sizes + --enable-library-stripping # Enable strip libraries upon installation to + reduce binary sizes + --disable-library-stripping # Disable strip libraries upon installation to + reduce binary sizes + --configure-option=OPT # Extra option for configure + --user # Enable doing a per-user installation + --global # Disable doing a per-user installation + --package-db=DB # Append the given package database to the list + of package databases used (to satisfy + dependencies and register into). May be a + specific file, 'global' or 'user'. The initial + list is ['global'], ['global', 'user'], or + ['global', $sandbox], depending on context. + Use 'clear' to reset the list to empty. See + the user guide for details. + -f FLAGS or -fFLAGS, --flags=FLAGS + # Force values for the given flags in Cabal + conditionals in the .cabal file. E.g., + --flags="debug -usebytestrings" forces the + flag "debug" to true and "usebytestrings" to + false. + --extra-include-dirs=PATH # A list of directories to search for header + files + --enable-deterministic # Enable Try to be as deterministic as possible + (used by the test suite) + --disable-deterministic # Disable Try to be as deterministic as possible + (used by the test suite) + --ipid=IPID # Installed package ID to compile this package + as + --cid=CID # Installed component ID to compile this + component as + --extra-lib-dirs=PATH # A list of directories to search for external + libraries + --extra-lib-dirs-static=PATH # A list of directories to search for external + libraries when linking fully static + executables + --extra-framework-dirs=PATH # A list of directories to search for external + frameworks (OS X only) + --extra-prog-path=PATH # A list of directories to search for required + programs (in addition to the normal search + locations) + --instantiate-with=NAME=MOD # A mapping of signature names to concrete + module instantiations. + --enable-tests # Enable dependency checking and compilation for + test suites listed in the package description + file. + --disable-tests # Disable dependency checking and compilation + for test suites listed in the package + description file. + --enable-coverage # Enable build package with Haskell Program + Coverage. (GHC only) + --disable-coverage # Disable build package with Haskell Program + Coverage. (GHC only) + --enable-library-coverage # Enable build package with Haskell Program + Coverage. (GHC only) (DEPRECATED) + --disable-library-coverage # Disable build package with Haskell Program + Coverage. (GHC only) (DEPRECATED) + --enable-benchmarks # Enable dependency checking and compilation for + benchmarks listed in the package description + file. + --disable-benchmarks # Disable dependency checking and compilation + for benchmarks listed in the package + description file. + --enable-relocatable # Enable building a package that is relocatable. + (GHC only) + --disable-relocatable # Disable building a package that is + relocatable. (GHC only) + --disable-response-files # Enable workaround for old versions of programs + like "ar" that do not support @file arguments + --allow-depending-on-private-libs + # Allow depending on private libraries. If set, + the library visibility check MUST be done + externally. + --coverage-for=UNITID # A list of unit-ids of libraries to include in + the Haskell Program Coverage report. + --ignore-build-tools # Ignore build tool dependencies. If set, + declared build tools needn't be found for + compilation to proceed. + --with-PROG=PATH # Give the path to PROG + --PROG-option=OPT # Give an extra option to PROG (passed directly + to PROG as a single argument) + --PROG-options=OPTS # Give extra options to PROG (split on spaces, + use "" to prevent splitting) + --cabal-lib-version=VERSION # Select which version of the Cabal lib to use + to build packages (useful for testing). + --enable-append # Enable appending the new config to the old + config file + --disable-append # Disable appending the new config to the old + config file + --enable-backup # Enable the backup of the config file before + any alterations + --disable-backup # Disable the backup of the config file before + any alterations + -c CONSTRAINT or -cCONSTRAINT, --constraint=CONSTRAINT + # Specify constraints on a package (version, + installed/source, flags) + --preference=CONSTRAINT # Specify preferences (soft constraints) on the + version of a package + --solver=SOLVER # Select dependency solver to use (default: + modular). Choices: modular. + --allow-older[=DEPS] # Ignore lower bounds in all dependencies or + DEPS + --allow-newer[=DEPS] # Ignore upper bounds in all dependencies or + DEPS + --write-ghc-environment-files=always|never|ghc8.4.4+ + # Whether to create a .ghc.environment file + after a successful build (v2-build only) + --enable-documentation # Enable building of documentation + --disable-documentation # Disable building of documentation + --doc-index-file=TEMPLATE # A central index of haddock API documentation + (template cannot use $pkgid) + --dry-run # Do not install anything, only print what would + be installed. + --only-download # Do not build anything, only fetch the + packages. + --max-backjumps=NUM # Maximum number of backjumps allowed while + solving (default: 4000). Use a negative number + to enable unlimited backtracking. Use 0 to + disable backtracking completely. + --reorder-goals # Try to reorder goals according to certain + heuristics. Slows things down on average, but + may make backtracking faster for some + packages. + --count-conflicts # Try to speed up solving by preferring goals + that are involved in a lot of conflicts + (default). + --fine-grained-conflicts # Skip a version of a package if it does not + resolve the conflicts encountered in the last + version, as a solver optimization (default). + --minimize-conflict-set # When there is no solution, try to improve the + error message by finding a minimal conflict + set (default: false). May increase run time + significantly. + --independent-goals # Treat several goals on the command line as + independent. If several goals depend on the + same package, different versions can be + chosen. + --prefer-oldest # Prefer the oldest (instead of the latest) + versions of packages available. Useful to + determine lower bounds in the build-depends + section. + --prefer-version=oldest|latest|installed-or-latest + # Select which version of a package that the + solver should prefer. Oldest is useful to + determine lower bounds in build-depends + section. Latest will prefer the latest + version. Installed-or-latest will prefer + installed versions and the latest version + otherwise. + --shadow-installed-packages # If multiple package instances of the same + version are installed, treat all but one as + shadowed. + --strong-flags # Do not defer flag choices (this used to be the + default in cabal-install <= 1.20). + --allow-boot-library-installs + # Allow cabal to install base, ghc-prim, + integer-simple, integer-gmp, and + template-haskell. + --reject-unconstrained-dependencies=none|all + # Require these packages to have constraints on + them if they are to be selected (default: + none). + --reinstall # Install even if it means installing the same + version again. + --avoid-reinstalls # Do not select versions that would + destructively overwrite installed packages. + --force-reinstalls # Reinstall packages even if they will most + likely break other installed packages. + --upgrade-dependencies # Pick the latest version for all dependencies, + rather than trying to pick an installed + version. + --only-dependencies # Install only the dependencies necessary to + build the given packages + --dependencies-only # A synonym for --only-dependencies + --index-state=STATE # Use source package index state as it existed + at a previous time. Accepts unix-timestamps + (e.g. '@1474732068'), ISO8601 UTC timestamps + (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' + (default: 'HEAD'). + --root-cmd=COMMAND # (No longer supported, do not use.) + --build-summary=TEMPLATE # Save build summaries to file (name template + can use $pkgid, $compiler, $os, $arch) + --build-log=TEMPLATE # Log all builds to file (name template can use + $pkgid, $compiler, $os, $arch) + --remote-build-reporting=LEVEL + # Generate build reports to send to a remote + server (none, anonymous or detailed). + --report-planning-failure # Generate build reports when the dependency + solver fails. This is used by the Hackage + build bot. + --enable-per-component # Enable Per-component builds when possible + --disable-per-component # Disable Per-component builds when possible + --run-tests # Run package test suites during installation. + --semaphore # Use a semaphore so GHC can compile components + in parallel + -j[NUM], --jobs[=NUM] # Run NUM jobs simultaneously (or '$ncpus' if no + NUM is given). + --keep-going # After a build failure, continue to build other + unaffected packages. + --offline # Don't download packages from the Internet. + --build-timings # Print elapsed time for each build phase. + --haddock-hoogle # Generate a hoogle database + --haddock-html # Generate HTML documentation (the default) + --haddock-html-location=URL # Location of HTML documentation for + pre-requisite packages + --haddock-for-hackage # Collection of flags to generate documentation + suitable for upload to hackage + --haddock-executables # Run haddock for Executables targets + --haddock-tests # Run haddock for Test Suite targets + --haddock-benchmarks # Run haddock for Benchmark targets + --haddock-all # Run haddock for all targets + --haddock-internal # Run haddock for internal modules and include + all symbols + --haddock-css=PATH # Use PATH as the haddock stylesheet + --haddock-hyperlink-source # Hyperlink the documentation to the source code + --haddock-quickjump # Generate an index for interactive + documentation navigation + --haddock-hscolour-css=PATH # Use PATH as the HsColour stylesheet + --haddock-contents-location=URL + # Bake URL in as the location for the contents + page + --haddock-base-url=URL # Base URL for static files. + --haddock-resources-dir=DIR # Location of Haddocks static / auxiliary files + --haddock-output-dir=DIR # Generate haddock documentation into this + directory. This flag is provided as a + technology preview and is subject to change in + the next releases. + --haddock-use-unicode # Pass --use-unicode option to haddock + --test-log=TEMPLATE # Log all test suite results to file (name + template can use $pkgid, $compiler, $os, + $arch, $test-suite, $result) + --test-machine-log=TEMPLATE # Produce a machine-readable log file (name + template can use $pkgid, $compiler, $os, + $arch, $result) + --test-show-details=FILTER # 'always': always show results of individual + test cases. 'never': never show results of + individual test cases. 'failures': show + results of failing test cases. 'streaming': + show results of test cases in real + time.'direct': send results of test cases in + real time; no log file. + --test-keep-tix-files # Keep .tix files for HPC between test runs + --test-wrapper=FILE # Run test through a wrapper. + --test-fail-when-no-test-suites + # Exit with failure when no test suites are + found. + --test-options=TEMPLATES # Give extra options to test executables (split + on spaces, use "" to prevent splitting; name + templates can use $pkgid, $compiler, $os, + $arch, $test-suite) + --test-option=TEMPLATE # Give extra option to test executables (passed + directly as a single argument; name template + can use $pkgid, $compiler, $os, $arch, + $test-suite) + --benchmark-options=TEMPLATES + # Give extra options to benchmark executables + (split on spaces, use "" to prevent splitting; + name templates can use $pkgid, $compiler, $os, + $arch, $benchmark) + --benchmark-option=TEMPLATE # Give extra option to benchmark executables + (passed directly as a single argument; name + template can use $pkgid, $compiler, $os, + $arch, $benchmark) + --project-dir=DIR # Set the path of the project directory + --project-file=FILE # Set the path of the cabal.project file + (relative to the project directory when + relative) + -z, --ignore-project # Ignore local project configuration (unless + --project-dir or --project-file is also set) + --project-file-parser=PARSER # Set the parser to use for the project file + +Examples: + cabal bench + Run all the benchmarks in the package in the current directory + cabal bench pkgname + Run all the benchmarks in the package named pkgname + cabal bench cname + Run the benchmark named cname + cabal bench cname -O2 + Run the benchmark built with '-O2' (including local libs used) diff --git a/doc/cmd-v2-help/build.txt b/doc/cmd-v2-help/build.txt new file mode 100644 index 00000000000..c4d2f57a62f --- /dev/null +++ b/doc/cmd-v2-help/build.txt @@ -0,0 +1,385 @@ +Compile targets within the project. + +Usage: cabal build [TARGETS] [FLAGS] + +Build one or more targets from within the project. The available targets are +the packages in the project as well as individual components within those +packages, including libraries, executables, test-suites or benchmarks. Targets +can be specified by name or location. If no target is specified then the +default is to build the package in the current directory. + +Dependencies are built or rebuilt as necessary. Additional configuration flags +can be specified on the command line and these extend the project +configuration from the 'cabal.project', 'cabal.project.local' and other files. + +Flags for build: + -h, --help # Show this help text + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + --builddir=DIR # The directory where Cabal puts generated build + files (default dist) + --keep-temp-files # Keep temporary files. + -g, --ghc # Compile with GHC + --ghcjs # Compile with GHCJS + --uhc # Compile with UHC + -w PATH or -wPATH, --with-compiler=PATH + # Give the path to a particular compiler + --with-hc-pkg=PATH # Give the path to the package tool + --prefix=DIR # Bake this prefix in preparation of + installation + --bindir=DIR # Installation directory for executables + --libdir=DIR # Installation directory for libraries + --libsubdir=DIR # Subdirectory of libdir in which libs are + installed + --dynlibdir=DIR # Installation directory for dynamic libraries + --bytecodelibdir=DIR # Installation directory for bytecode libraries + --libexecdir=DIR # Installation directory for program executables + --libexecsubdir=DIR # Subdirectory of libexecdir in which private + executables are installed + --datadir=DIR # Installation directory for read-only data + --datasubdir=DIR # Subdirectory of datadir in which data files + are installed + --docdir=DIR # Installation directory for documentation + --htmldir=DIR # Installation directory for HTML documentation + --haddockdir=DIR # Installation directory for haddock interfaces + --sysconfdir=DIR # Installation directory for configuration files + --program-prefix=PREFIX # Prefix to be applied to installed executables + --program-suffix=SUFFIX # Suffix to be applied to installed executables + --enable-library-vanilla # Enable Vanilla libraries + --disable-library-vanilla # Disable Vanilla libraries + -p, --enable-library-profiling + # Enable Library profiling + --disable-library-profiling # Disable Library profiling + --enable-shared # Enable Shared library + --disable-shared # Disable Shared library + --enable-static # Enable Static library + --disable-static # Disable Static library + --enable-library-bytecode # Enable Bytecode library + --disable-library-bytecode # Disable Bytecode library + --enable-executable-dynamic # Enable Executable dynamic linking + --disable-executable-dynamic # Disable Executable dynamic linking + --enable-executable-static # Enable Executable fully static linking + --disable-executable-static # Disable Executable fully static linking + --enable-profiling # Enable Executable and library profiling + --disable-profiling # Disable Executable and library profiling + --enable-profiling-shared # Enable Build profiling shared libraries + --disable-profiling-shared # Disable Build profiling shared libraries + --enable-executable-profiling + # Enable Executable profiling (DEPRECATED) + --disable-executable-profiling + # Disable Executable profiling (DEPRECATED) + --profiling-detail=level # Profiling detail level for executable and + library (default, none, exported-functions, + toplevel-functions, all-functions, late). + --library-profiling-detail=level + # Profiling detail level for libraries only. + -O[n], --enable-optimization[=n] + # Build with optimization (n is 0--2, default is + 1) + --disable-optimization # Build without optimization + --enable-debug-info[=n] # Emit debug info (n is 0--3, default is 0) + --disable-debug-info # Don't emit debug info + --enable-build-info # Enable build information generation during + project building + --disable-build-info # Disable build information generation during + project building + --enable-library-for-ghci # Enable compile library for use with GHCi + --disable-library-for-ghci # Disable compile library for use with GHCi + --enable-split-sections # Enable compile library code such that unneeded + definitions can be dropped from the final + executable (GHC 7.8+) + --disable-split-sections # Disable compile library code such that + unneeded definitions can be dropped from the + final executable (GHC 7.8+) + --enable-split-objs # Enable split library into smaller objects to + reduce binary sizes (GHC 6.6+) + --disable-split-objs # Disable split library into smaller objects to + reduce binary sizes (GHC 6.6+) + --enable-executable-stripping + # Enable strip executables upon installation to + reduce binary sizes + --disable-executable-stripping + # Disable strip executables upon installation to + reduce binary sizes + --enable-library-stripping # Enable strip libraries upon installation to + reduce binary sizes + --disable-library-stripping # Disable strip libraries upon installation to + reduce binary sizes + --configure-option=OPT # Extra option for configure + --user # Enable doing a per-user installation + --global # Disable doing a per-user installation + --package-db=DB # Append the given package database to the list + of package databases used (to satisfy + dependencies and register into). May be a + specific file, 'global' or 'user'. The initial + list is ['global'], ['global', 'user'], or + ['global', $sandbox], depending on context. + Use 'clear' to reset the list to empty. See + the user guide for details. + -f FLAGS or -fFLAGS, --flags=FLAGS + # Force values for the given flags in Cabal + conditionals in the .cabal file. E.g., + --flags="debug -usebytestrings" forces the + flag "debug" to true and "usebytestrings" to + false. + --extra-include-dirs=PATH # A list of directories to search for header + files + --enable-deterministic # Enable Try to be as deterministic as possible + (used by the test suite) + --disable-deterministic # Disable Try to be as deterministic as possible + (used by the test suite) + --ipid=IPID # Installed package ID to compile this package + as + --cid=CID # Installed component ID to compile this + component as + --extra-lib-dirs=PATH # A list of directories to search for external + libraries + --extra-lib-dirs-static=PATH # A list of directories to search for external + libraries when linking fully static + executables + --extra-framework-dirs=PATH # A list of directories to search for external + frameworks (OS X only) + --extra-prog-path=PATH # A list of directories to search for required + programs (in addition to the normal search + locations) + --instantiate-with=NAME=MOD # A mapping of signature names to concrete + module instantiations. + --enable-tests # Enable dependency checking and compilation for + test suites listed in the package description + file. + --disable-tests # Disable dependency checking and compilation + for test suites listed in the package + description file. + --enable-coverage # Enable build package with Haskell Program + Coverage. (GHC only) + --disable-coverage # Disable build package with Haskell Program + Coverage. (GHC only) + --enable-library-coverage # Enable build package with Haskell Program + Coverage. (GHC only) (DEPRECATED) + --disable-library-coverage # Disable build package with Haskell Program + Coverage. (GHC only) (DEPRECATED) + --enable-benchmarks # Enable dependency checking and compilation for + benchmarks listed in the package description + file. + --disable-benchmarks # Disable dependency checking and compilation + for benchmarks listed in the package + description file. + --enable-relocatable # Enable building a package that is relocatable. + (GHC only) + --disable-relocatable # Disable building a package that is + relocatable. (GHC only) + --disable-response-files # Enable workaround for old versions of programs + like "ar" that do not support @file arguments + --allow-depending-on-private-libs + # Allow depending on private libraries. If set, + the library visibility check MUST be done + externally. + --coverage-for=UNITID # A list of unit-ids of libraries to include in + the Haskell Program Coverage report. + --ignore-build-tools # Ignore build tool dependencies. If set, + declared build tools needn't be found for + compilation to proceed. + --with-PROG=PATH # Give the path to PROG + --PROG-option=OPT # Give an extra option to PROG (passed directly + to PROG as a single argument) + --PROG-options=OPTS # Give extra options to PROG (split on spaces, + use "" to prevent splitting) + --cabal-lib-version=VERSION # Select which version of the Cabal lib to use + to build packages (useful for testing). + --enable-append # Enable appending the new config to the old + config file + --disable-append # Disable appending the new config to the old + config file + --enable-backup # Enable the backup of the config file before + any alterations + --disable-backup # Disable the backup of the config file before + any alterations + -c CONSTRAINT or -cCONSTRAINT, --constraint=CONSTRAINT + # Specify constraints on a package (version, + installed/source, flags) + --preference=CONSTRAINT # Specify preferences (soft constraints) on the + version of a package + --solver=SOLVER # Select dependency solver to use (default: + modular). Choices: modular. + --allow-older[=DEPS] # Ignore lower bounds in all dependencies or + DEPS + --allow-newer[=DEPS] # Ignore upper bounds in all dependencies or + DEPS + --write-ghc-environment-files=always|never|ghc8.4.4+ + # Whether to create a .ghc.environment file + after a successful build (v2-build only) + --enable-documentation # Enable building of documentation + --disable-documentation # Disable building of documentation + --doc-index-file=TEMPLATE # A central index of haddock API documentation + (template cannot use $pkgid) + --dry-run # Do not install anything, only print what would + be installed. + --only-download # Do not build anything, only fetch the + packages. + --max-backjumps=NUM # Maximum number of backjumps allowed while + solving (default: 4000). Use a negative number + to enable unlimited backtracking. Use 0 to + disable backtracking completely. + --reorder-goals # Try to reorder goals according to certain + heuristics. Slows things down on average, but + may make backtracking faster for some + packages. + --count-conflicts # Try to speed up solving by preferring goals + that are involved in a lot of conflicts + (default). + --fine-grained-conflicts # Skip a version of a package if it does not + resolve the conflicts encountered in the last + version, as a solver optimization (default). + --minimize-conflict-set # When there is no solution, try to improve the + error message by finding a minimal conflict + set (default: false). May increase run time + significantly. + --independent-goals # Treat several goals on the command line as + independent. If several goals depend on the + same package, different versions can be + chosen. + --prefer-oldest # Prefer the oldest (instead of the latest) + versions of packages available. Useful to + determine lower bounds in the build-depends + section. + --prefer-version=oldest|latest|installed-or-latest + # Select which version of a package that the + solver should prefer. Oldest is useful to + determine lower bounds in build-depends + section. Latest will prefer the latest + version. Installed-or-latest will prefer + installed versions and the latest version + otherwise. + --shadow-installed-packages # If multiple package instances of the same + version are installed, treat all but one as + shadowed. + --strong-flags # Do not defer flag choices (this used to be the + default in cabal-install <= 1.20). + --allow-boot-library-installs + # Allow cabal to install base, ghc-prim, + integer-simple, integer-gmp, and + template-haskell. + --reject-unconstrained-dependencies=none|all + # Require these packages to have constraints on + them if they are to be selected (default: + none). + --reinstall # Install even if it means installing the same + version again. + --avoid-reinstalls # Do not select versions that would + destructively overwrite installed packages. + --force-reinstalls # Reinstall packages even if they will most + likely break other installed packages. + --upgrade-dependencies # Pick the latest version for all dependencies, + rather than trying to pick an installed + version. + --only-dependencies # Install only the dependencies necessary to + build the given packages + --dependencies-only # A synonym for --only-dependencies + --index-state=STATE # Use source package index state as it existed + at a previous time. Accepts unix-timestamps + (e.g. '@1474732068'), ISO8601 UTC timestamps + (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' + (default: 'HEAD'). + --root-cmd=COMMAND # (No longer supported, do not use.) + --build-summary=TEMPLATE # Save build summaries to file (name template + can use $pkgid, $compiler, $os, $arch) + --build-log=TEMPLATE # Log all builds to file (name template can use + $pkgid, $compiler, $os, $arch) + --remote-build-reporting=LEVEL + # Generate build reports to send to a remote + server (none, anonymous or detailed). + --report-planning-failure # Generate build reports when the dependency + solver fails. This is used by the Hackage + build bot. + --enable-per-component # Enable Per-component builds when possible + --disable-per-component # Disable Per-component builds when possible + --run-tests # Run package test suites during installation. + --semaphore # Use a semaphore so GHC can compile components + in parallel + -j[NUM], --jobs[=NUM] # Run NUM jobs simultaneously (or '$ncpus' if no + NUM is given). + --keep-going # After a build failure, continue to build other + unaffected packages. + --offline # Don't download packages from the Internet. + --build-timings # Print elapsed time for each build phase. + --haddock-hoogle # Generate a hoogle database + --haddock-html # Generate HTML documentation (the default) + --haddock-html-location=URL # Location of HTML documentation for + pre-requisite packages + --haddock-for-hackage # Collection of flags to generate documentation + suitable for upload to hackage + --haddock-executables # Run haddock for Executables targets + --haddock-tests # Run haddock for Test Suite targets + --haddock-benchmarks # Run haddock for Benchmark targets + --haddock-all # Run haddock for all targets + --haddock-internal # Run haddock for internal modules and include + all symbols + --haddock-css=PATH # Use PATH as the haddock stylesheet + --haddock-hyperlink-source # Hyperlink the documentation to the source code + --haddock-quickjump # Generate an index for interactive + documentation navigation + --haddock-hscolour-css=PATH # Use PATH as the HsColour stylesheet + --haddock-contents-location=URL + # Bake URL in as the location for the contents + page + --haddock-base-url=URL # Base URL for static files. + --haddock-resources-dir=DIR # Location of Haddocks static / auxiliary files + --haddock-output-dir=DIR # Generate haddock documentation into this + directory. This flag is provided as a + technology preview and is subject to change in + the next releases. + --haddock-use-unicode # Pass --use-unicode option to haddock + --test-log=TEMPLATE # Log all test suite results to file (name + template can use $pkgid, $compiler, $os, + $arch, $test-suite, $result) + --test-machine-log=TEMPLATE # Produce a machine-readable log file (name + template can use $pkgid, $compiler, $os, + $arch, $result) + --test-show-details=FILTER # 'always': always show results of individual + test cases. 'never': never show results of + individual test cases. 'failures': show + results of failing test cases. 'streaming': + show results of test cases in real + time.'direct': send results of test cases in + real time; no log file. + --test-keep-tix-files # Keep .tix files for HPC between test runs + --test-wrapper=FILE # Run test through a wrapper. + --test-fail-when-no-test-suites + # Exit with failure when no test suites are + found. + --test-options=TEMPLATES # Give extra options to test executables (split + on spaces, use "" to prevent splitting; name + templates can use $pkgid, $compiler, $os, + $arch, $test-suite) + --test-option=TEMPLATE # Give extra option to test executables (passed + directly as a single argument; name template + can use $pkgid, $compiler, $os, $arch, + $test-suite) + --benchmark-options=TEMPLATES + # Give extra options to benchmark executables + (split on spaces, use "" to prevent splitting; + name templates can use $pkgid, $compiler, $os, + $arch, $benchmark) + --benchmark-option=TEMPLATE # Give extra option to benchmark executables + (passed directly as a single argument; name + template can use $pkgid, $compiler, $os, + $arch, $benchmark) + --project-dir=DIR # Set the path of the project directory + --project-file=FILE # Set the path of the cabal.project file + (relative to the project directory when + relative) + --project-file-parser=PARSER # Set the parser to use for the project file + --only-configure # Instead of performing a full build just run + the configure step + +Examples: + cabal build + Build the package in the current directory or all packages in the project + cabal build pkgname + Build the package named pkgname in the project + cabal build ./pkgfoo + Build the package in the ./pkgfoo directory + cabal build cname + Build the component named cname in the project + cabal build cname --enable-profiling + Build the component in profiling mode (including dependencies as needed) diff --git a/doc/cmd-v2-help/clean.txt b/doc/cmd-v2-help/clean.txt new file mode 100644 index 00000000000..159ba0e2a12 --- /dev/null +++ b/doc/cmd-v2-help/clean.txt @@ -0,0 +1,22 @@ +Clean the package store and remove temporary files. + +Usage: cabal clean [FLAGS] + +Removes all temporary files created during the building process (.hi, .o, +preprocessed sources, etc.) and also empties out the local caches (by +default). + + +Flags for clean: + -h, --help # Show this help text + --project-dir=DIR # Set the path of the project directory + --project-file=FILE # Set the path of the cabal.project file + (relative to the project directory when + relative) + --project-file-parser=PARSER # Set the parser to use for the project file + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + --builddir=DIR # The directory where Cabal puts generated build + files (default dist) + -s, --save-config # Save configuration, only remove build + artifacts diff --git a/doc/cmd-v2-help/configure.txt b/doc/cmd-v2-help/configure.txt new file mode 100644 index 00000000000..c97f66063b1 --- /dev/null +++ b/doc/cmd-v2-help/configure.txt @@ -0,0 +1,392 @@ +Add extra project configuration. + +Usage: cabal configure [FLAGS] + +Adjust how the project is built by setting additional package flags and other +flags. + +The configuration options are written to the 'cabal.project.local' file (or +'$project_file.local', if '--project-file' is specified) which extends the +configuration from the 'cabal.project' file (if any). This combination is used +as the project configuration for all other commands (such as 'build', +'repl' etc) though it can be extended/overridden on a per-command basis. + +The configure command also checks that the project configuration will work. +In particular it checks that there is a consistent set of dependencies for the +project as a whole. + +The 'cabal.project.local' file persists across 'clean' but is overwritten +on the next use of the 'configure' command. The intention is that the +'cabal.project' file should be kept in source control but the +'cabal.project.local' should not. + +It is never necessary to use the 'configure' command. It is merely a +convenience in cases where you do not want to specify flags to 'build' (and +other commands) every time and yet do not want to alter the 'cabal.project' +persistently. + +Flags for configure: + -h, --help # Show this help text + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + --builddir=DIR # The directory where Cabal puts generated build + files (default dist) + --keep-temp-files # Keep temporary files. + -g, --ghc # Compile with GHC + --ghcjs # Compile with GHCJS + --uhc # Compile with UHC + -w PATH or -wPATH, --with-compiler=PATH + # Give the path to a particular compiler + --with-hc-pkg=PATH # Give the path to the package tool + --prefix=DIR # Bake this prefix in preparation of + installation + --bindir=DIR # Installation directory for executables + --libdir=DIR # Installation directory for libraries + --libsubdir=DIR # Subdirectory of libdir in which libs are + installed + --dynlibdir=DIR # Installation directory for dynamic libraries + --bytecodelibdir=DIR # Installation directory for bytecode libraries + --libexecdir=DIR # Installation directory for program executables + --libexecsubdir=DIR # Subdirectory of libexecdir in which private + executables are installed + --datadir=DIR # Installation directory for read-only data + --datasubdir=DIR # Subdirectory of datadir in which data files + are installed + --docdir=DIR # Installation directory for documentation + --htmldir=DIR # Installation directory for HTML documentation + --haddockdir=DIR # Installation directory for haddock interfaces + --sysconfdir=DIR # Installation directory for configuration files + --program-prefix=PREFIX # Prefix to be applied to installed executables + --program-suffix=SUFFIX # Suffix to be applied to installed executables + --enable-library-vanilla # Enable Vanilla libraries + --disable-library-vanilla # Disable Vanilla libraries + -p, --enable-library-profiling + # Enable Library profiling + --disable-library-profiling # Disable Library profiling + --enable-shared # Enable Shared library + --disable-shared # Disable Shared library + --enable-static # Enable Static library + --disable-static # Disable Static library + --enable-library-bytecode # Enable Bytecode library + --disable-library-bytecode # Disable Bytecode library + --enable-executable-dynamic # Enable Executable dynamic linking + --disable-executable-dynamic # Disable Executable dynamic linking + --enable-executable-static # Enable Executable fully static linking + --disable-executable-static # Disable Executable fully static linking + --enable-profiling # Enable Executable and library profiling + --disable-profiling # Disable Executable and library profiling + --enable-profiling-shared # Enable Build profiling shared libraries + --disable-profiling-shared # Disable Build profiling shared libraries + --enable-executable-profiling + # Enable Executable profiling (DEPRECATED) + --disable-executable-profiling + # Disable Executable profiling (DEPRECATED) + --profiling-detail=level # Profiling detail level for executable and + library (default, none, exported-functions, + toplevel-functions, all-functions, late). + --library-profiling-detail=level + # Profiling detail level for libraries only. + -O[n], --enable-optimization[=n] + # Build with optimization (n is 0--2, default is + 1) + --disable-optimization # Build without optimization + --enable-debug-info[=n] # Emit debug info (n is 0--3, default is 0) + --disable-debug-info # Don't emit debug info + --enable-build-info # Enable build information generation during + project building + --disable-build-info # Disable build information generation during + project building + --enable-library-for-ghci # Enable compile library for use with GHCi + --disable-library-for-ghci # Disable compile library for use with GHCi + --enable-split-sections # Enable compile library code such that unneeded + definitions can be dropped from the final + executable (GHC 7.8+) + --disable-split-sections # Disable compile library code such that + unneeded definitions can be dropped from the + final executable (GHC 7.8+) + --enable-split-objs # Enable split library into smaller objects to + reduce binary sizes (GHC 6.6+) + --disable-split-objs # Disable split library into smaller objects to + reduce binary sizes (GHC 6.6+) + --enable-executable-stripping + # Enable strip executables upon installation to + reduce binary sizes + --disable-executable-stripping + # Disable strip executables upon installation to + reduce binary sizes + --enable-library-stripping # Enable strip libraries upon installation to + reduce binary sizes + --disable-library-stripping # Disable strip libraries upon installation to + reduce binary sizes + --configure-option=OPT # Extra option for configure + --user # Enable doing a per-user installation + --global # Disable doing a per-user installation + --package-db=DB # Append the given package database to the list + of package databases used (to satisfy + dependencies and register into). May be a + specific file, 'global' or 'user'. The initial + list is ['global'], ['global', 'user'], or + ['global', $sandbox], depending on context. + Use 'clear' to reset the list to empty. See + the user guide for details. + -f FLAGS or -fFLAGS, --flags=FLAGS + # Force values for the given flags in Cabal + conditionals in the .cabal file. E.g., + --flags="debug -usebytestrings" forces the + flag "debug" to true and "usebytestrings" to + false. + --extra-include-dirs=PATH # A list of directories to search for header + files + --enable-deterministic # Enable Try to be as deterministic as possible + (used by the test suite) + --disable-deterministic # Disable Try to be as deterministic as possible + (used by the test suite) + --ipid=IPID # Installed package ID to compile this package + as + --cid=CID # Installed component ID to compile this + component as + --extra-lib-dirs=PATH # A list of directories to search for external + libraries + --extra-lib-dirs-static=PATH # A list of directories to search for external + libraries when linking fully static + executables + --extra-framework-dirs=PATH # A list of directories to search for external + frameworks (OS X only) + --extra-prog-path=PATH # A list of directories to search for required + programs (in addition to the normal search + locations) + --instantiate-with=NAME=MOD # A mapping of signature names to concrete + module instantiations. + --enable-tests # Enable dependency checking and compilation for + test suites listed in the package description + file. + --disable-tests # Disable dependency checking and compilation + for test suites listed in the package + description file. + --enable-coverage # Enable build package with Haskell Program + Coverage. (GHC only) + --disable-coverage # Disable build package with Haskell Program + Coverage. (GHC only) + --enable-library-coverage # Enable build package with Haskell Program + Coverage. (GHC only) (DEPRECATED) + --disable-library-coverage # Disable build package with Haskell Program + Coverage. (GHC only) (DEPRECATED) + --enable-benchmarks # Enable dependency checking and compilation for + benchmarks listed in the package description + file. + --disable-benchmarks # Disable dependency checking and compilation + for benchmarks listed in the package + description file. + --enable-relocatable # Enable building a package that is relocatable. + (GHC only) + --disable-relocatable # Disable building a package that is + relocatable. (GHC only) + --disable-response-files # Enable workaround for old versions of programs + like "ar" that do not support @file arguments + --allow-depending-on-private-libs + # Allow depending on private libraries. If set, + the library visibility check MUST be done + externally. + --coverage-for=UNITID # A list of unit-ids of libraries to include in + the Haskell Program Coverage report. + --ignore-build-tools # Ignore build tool dependencies. If set, + declared build tools needn't be found for + compilation to proceed. + --with-PROG=PATH # Give the path to PROG + --PROG-option=OPT # Give an extra option to PROG (passed directly + to PROG as a single argument) + --PROG-options=OPTS # Give extra options to PROG (split on spaces, + use "" to prevent splitting) + --cabal-lib-version=VERSION # Select which version of the Cabal lib to use + to build packages (useful for testing). + --enable-append # Enable appending the new config to the old + config file + --disable-append # Disable appending the new config to the old + config file + --enable-backup # Enable the backup of the config file before + any alterations + --disable-backup # Disable the backup of the config file before + any alterations + -c CONSTRAINT or -cCONSTRAINT, --constraint=CONSTRAINT + # Specify constraints on a package (version, + installed/source, flags) + --preference=CONSTRAINT # Specify preferences (soft constraints) on the + version of a package + --solver=SOLVER # Select dependency solver to use (default: + modular). Choices: modular. + --allow-older[=DEPS] # Ignore lower bounds in all dependencies or + DEPS + --allow-newer[=DEPS] # Ignore upper bounds in all dependencies or + DEPS + --write-ghc-environment-files=always|never|ghc8.4.4+ + # Whether to create a .ghc.environment file + after a successful build (v2-build only) + --enable-documentation # Enable building of documentation + --disable-documentation # Disable building of documentation + --doc-index-file=TEMPLATE # A central index of haddock API documentation + (template cannot use $pkgid) + --dry-run # Do not install anything, only print what would + be installed. + --only-download # Do not build anything, only fetch the + packages. + --max-backjumps=NUM # Maximum number of backjumps allowed while + solving (default: 4000). Use a negative number + to enable unlimited backtracking. Use 0 to + disable backtracking completely. + --reorder-goals # Try to reorder goals according to certain + heuristics. Slows things down on average, but + may make backtracking faster for some + packages. + --count-conflicts # Try to speed up solving by preferring goals + that are involved in a lot of conflicts + (default). + --fine-grained-conflicts # Skip a version of a package if it does not + resolve the conflicts encountered in the last + version, as a solver optimization (default). + --minimize-conflict-set # When there is no solution, try to improve the + error message by finding a minimal conflict + set (default: false). May increase run time + significantly. + --independent-goals # Treat several goals on the command line as + independent. If several goals depend on the + same package, different versions can be + chosen. + --prefer-oldest # Prefer the oldest (instead of the latest) + versions of packages available. Useful to + determine lower bounds in the build-depends + section. + --prefer-version=oldest|latest|installed-or-latest + # Select which version of a package that the + solver should prefer. Oldest is useful to + determine lower bounds in build-depends + section. Latest will prefer the latest + version. Installed-or-latest will prefer + installed versions and the latest version + otherwise. + --shadow-installed-packages # If multiple package instances of the same + version are installed, treat all but one as + shadowed. + --strong-flags # Do not defer flag choices (this used to be the + default in cabal-install <= 1.20). + --allow-boot-library-installs + # Allow cabal to install base, ghc-prim, + integer-simple, integer-gmp, and + template-haskell. + --reject-unconstrained-dependencies=none|all + # Require these packages to have constraints on + them if they are to be selected (default: + none). + --reinstall # Install even if it means installing the same + version again. + --avoid-reinstalls # Do not select versions that would + destructively overwrite installed packages. + --force-reinstalls # Reinstall packages even if they will most + likely break other installed packages. + --upgrade-dependencies # Pick the latest version for all dependencies, + rather than trying to pick an installed + version. + --only-dependencies # Install only the dependencies necessary to + build the given packages + --dependencies-only # A synonym for --only-dependencies + --index-state=STATE # Use source package index state as it existed + at a previous time. Accepts unix-timestamps + (e.g. '@1474732068'), ISO8601 UTC timestamps + (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' + (default: 'HEAD'). + --root-cmd=COMMAND # (No longer supported, do not use.) + --build-summary=TEMPLATE # Save build summaries to file (name template + can use $pkgid, $compiler, $os, $arch) + --build-log=TEMPLATE # Log all builds to file (name template can use + $pkgid, $compiler, $os, $arch) + --remote-build-reporting=LEVEL + # Generate build reports to send to a remote + server (none, anonymous or detailed). + --report-planning-failure # Generate build reports when the dependency + solver fails. This is used by the Hackage + build bot. + --enable-per-component # Enable Per-component builds when possible + --disable-per-component # Disable Per-component builds when possible + --run-tests # Run package test suites during installation. + --semaphore # Use a semaphore so GHC can compile components + in parallel + -j[NUM], --jobs[=NUM] # Run NUM jobs simultaneously (or '$ncpus' if no + NUM is given). + --keep-going # After a build failure, continue to build other + unaffected packages. + --offline # Don't download packages from the Internet. + --build-timings # Print elapsed time for each build phase. + --haddock-hoogle # Generate a hoogle database + --haddock-html # Generate HTML documentation (the default) + --haddock-html-location=URL # Location of HTML documentation for + pre-requisite packages + --haddock-for-hackage # Collection of flags to generate documentation + suitable for upload to hackage + --haddock-executables # Run haddock for Executables targets + --haddock-tests # Run haddock for Test Suite targets + --haddock-benchmarks # Run haddock for Benchmark targets + --haddock-all # Run haddock for all targets + --haddock-internal # Run haddock for internal modules and include + all symbols + --haddock-css=PATH # Use PATH as the haddock stylesheet + --haddock-hyperlink-source # Hyperlink the documentation to the source code + --haddock-quickjump # Generate an index for interactive + documentation navigation + --haddock-hscolour-css=PATH # Use PATH as the HsColour stylesheet + --haddock-contents-location=URL + # Bake URL in as the location for the contents + page + --haddock-base-url=URL # Base URL for static files. + --haddock-resources-dir=DIR # Location of Haddocks static / auxiliary files + --haddock-output-dir=DIR # Generate haddock documentation into this + directory. This flag is provided as a + technology preview and is subject to change in + the next releases. + --haddock-use-unicode # Pass --use-unicode option to haddock + --test-log=TEMPLATE # Log all test suite results to file (name + template can use $pkgid, $compiler, $os, + $arch, $test-suite, $result) + --test-machine-log=TEMPLATE # Produce a machine-readable log file (name + template can use $pkgid, $compiler, $os, + $arch, $result) + --test-show-details=FILTER # 'always': always show results of individual + test cases. 'never': never show results of + individual test cases. 'failures': show + results of failing test cases. 'streaming': + show results of test cases in real + time.'direct': send results of test cases in + real time; no log file. + --test-keep-tix-files # Keep .tix files for HPC between test runs + --test-wrapper=FILE # Run test through a wrapper. + --test-fail-when-no-test-suites + # Exit with failure when no test suites are + found. + --test-options=TEMPLATES # Give extra options to test executables (split + on spaces, use "" to prevent splitting; name + templates can use $pkgid, $compiler, $os, + $arch, $test-suite) + --test-option=TEMPLATE # Give extra option to test executables (passed + directly as a single argument; name template + can use $pkgid, $compiler, $os, $arch, + $test-suite) + --benchmark-options=TEMPLATES + # Give extra options to benchmark executables + (split on spaces, use "" to prevent splitting; + name templates can use $pkgid, $compiler, $os, + $arch, $benchmark) + --benchmark-option=TEMPLATE # Give extra option to benchmark executables + (passed directly as a single argument; name + template can use $pkgid, $compiler, $os, + $arch, $benchmark) + --project-dir=DIR # Set the path of the project directory + --project-file=FILE # Set the path of the cabal.project file + (relative to the project directory when + relative) + --project-file-parser=PARSER # Set the parser to use for the project file + +Examples: + cabal configure --with-compiler ghc-7.10.3 + Adjust the project configuration to use the given compiler + program and check the resulting configuration works. + cabal configure + Reset the local configuration to empty. To check that the + project configuration works, use 'cabal build'. diff --git a/doc/cmd-v2-help/exec.txt b/doc/cmd-v2-help/exec.txt new file mode 100644 index 00000000000..ea4368e9cd8 --- /dev/null +++ b/doc/cmd-v2-help/exec.txt @@ -0,0 +1,373 @@ +Give a command access to the store. + +Usage: cabal exec [FLAGS] [--] COMMAND [--] [ARGS] + +During development it is often useful to run build tasks and perform one-off +program executions to experiment with the behavior of build tools. It is +convenient to run these tools in the same way cabal itself would. The `cabal +exec` command provides a way to do so. + +Compiler tools will be configured to see the same subset of the store that +builds would see. The PATH is modified to make all executables in the +dependency tree available (provided they have been built already). Commands +are also rewritten in the way cabal itself would. For example, `cabal exec +ghc` will consult the configuration to choose an appropriate version of ghc +and to include any ghc-specific flags requested. + +Flags for exec: + -h, --help # Show this help text + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + --builddir=DIR # The directory where Cabal puts generated build + files (default dist) + --keep-temp-files # Keep temporary files. + -g, --ghc # Compile with GHC + --ghcjs # Compile with GHCJS + --uhc # Compile with UHC + -w PATH or -wPATH, --with-compiler=PATH + # Give the path to a particular compiler + --with-hc-pkg=PATH # Give the path to the package tool + --prefix=DIR # Bake this prefix in preparation of + installation + --bindir=DIR # Installation directory for executables + --libdir=DIR # Installation directory for libraries + --libsubdir=DIR # Subdirectory of libdir in which libs are + installed + --dynlibdir=DIR # Installation directory for dynamic libraries + --bytecodelibdir=DIR # Installation directory for bytecode libraries + --libexecdir=DIR # Installation directory for program executables + --libexecsubdir=DIR # Subdirectory of libexecdir in which private + executables are installed + --datadir=DIR # Installation directory for read-only data + --datasubdir=DIR # Subdirectory of datadir in which data files + are installed + --docdir=DIR # Installation directory for documentation + --htmldir=DIR # Installation directory for HTML documentation + --haddockdir=DIR # Installation directory for haddock interfaces + --sysconfdir=DIR # Installation directory for configuration files + --program-prefix=PREFIX # Prefix to be applied to installed executables + --program-suffix=SUFFIX # Suffix to be applied to installed executables + --enable-library-vanilla # Enable Vanilla libraries + --disable-library-vanilla # Disable Vanilla libraries + -p, --enable-library-profiling + # Enable Library profiling + --disable-library-profiling # Disable Library profiling + --enable-shared # Enable Shared library + --disable-shared # Disable Shared library + --enable-static # Enable Static library + --disable-static # Disable Static library + --enable-library-bytecode # Enable Bytecode library + --disable-library-bytecode # Disable Bytecode library + --enable-executable-dynamic # Enable Executable dynamic linking + --disable-executable-dynamic # Disable Executable dynamic linking + --enable-executable-static # Enable Executable fully static linking + --disable-executable-static # Disable Executable fully static linking + --enable-profiling # Enable Executable and library profiling + --disable-profiling # Disable Executable and library profiling + --enable-profiling-shared # Enable Build profiling shared libraries + --disable-profiling-shared # Disable Build profiling shared libraries + --enable-executable-profiling + # Enable Executable profiling (DEPRECATED) + --disable-executable-profiling + # Disable Executable profiling (DEPRECATED) + --profiling-detail=level # Profiling detail level for executable and + library (default, none, exported-functions, + toplevel-functions, all-functions, late). + --library-profiling-detail=level + # Profiling detail level for libraries only. + -O[n], --enable-optimization[=n] + # Build with optimization (n is 0--2, default is + 1) + --disable-optimization # Build without optimization + --enable-debug-info[=n] # Emit debug info (n is 0--3, default is 0) + --disable-debug-info # Don't emit debug info + --enable-build-info # Enable build information generation during + project building + --disable-build-info # Disable build information generation during + project building + --enable-library-for-ghci # Enable compile library for use with GHCi + --disable-library-for-ghci # Disable compile library for use with GHCi + --enable-split-sections # Enable compile library code such that unneeded + definitions can be dropped from the final + executable (GHC 7.8+) + --disable-split-sections # Disable compile library code such that + unneeded definitions can be dropped from the + final executable (GHC 7.8+) + --enable-split-objs # Enable split library into smaller objects to + reduce binary sizes (GHC 6.6+) + --disable-split-objs # Disable split library into smaller objects to + reduce binary sizes (GHC 6.6+) + --enable-executable-stripping + # Enable strip executables upon installation to + reduce binary sizes + --disable-executable-stripping + # Disable strip executables upon installation to + reduce binary sizes + --enable-library-stripping # Enable strip libraries upon installation to + reduce binary sizes + --disable-library-stripping # Disable strip libraries upon installation to + reduce binary sizes + --configure-option=OPT # Extra option for configure + --user # Enable doing a per-user installation + --global # Disable doing a per-user installation + --package-db=DB # Append the given package database to the list + of package databases used (to satisfy + dependencies and register into). May be a + specific file, 'global' or 'user'. The initial + list is ['global'], ['global', 'user'], or + ['global', $sandbox], depending on context. + Use 'clear' to reset the list to empty. See + the user guide for details. + -f FLAGS or -fFLAGS, --flags=FLAGS + # Force values for the given flags in Cabal + conditionals in the .cabal file. E.g., + --flags="debug -usebytestrings" forces the + flag "debug" to true and "usebytestrings" to + false. + --extra-include-dirs=PATH # A list of directories to search for header + files + --enable-deterministic # Enable Try to be as deterministic as possible + (used by the test suite) + --disable-deterministic # Disable Try to be as deterministic as possible + (used by the test suite) + --ipid=IPID # Installed package ID to compile this package + as + --cid=CID # Installed component ID to compile this + component as + --extra-lib-dirs=PATH # A list of directories to search for external + libraries + --extra-lib-dirs-static=PATH # A list of directories to search for external + libraries when linking fully static + executables + --extra-framework-dirs=PATH # A list of directories to search for external + frameworks (OS X only) + --extra-prog-path=PATH # A list of directories to search for required + programs (in addition to the normal search + locations) + --instantiate-with=NAME=MOD # A mapping of signature names to concrete + module instantiations. + --enable-tests # Enable dependency checking and compilation for + test suites listed in the package description + file. + --disable-tests # Disable dependency checking and compilation + for test suites listed in the package + description file. + --enable-coverage # Enable build package with Haskell Program + Coverage. (GHC only) + --disable-coverage # Disable build package with Haskell Program + Coverage. (GHC only) + --enable-library-coverage # Enable build package with Haskell Program + Coverage. (GHC only) (DEPRECATED) + --disable-library-coverage # Disable build package with Haskell Program + Coverage. (GHC only) (DEPRECATED) + --enable-benchmarks # Enable dependency checking and compilation for + benchmarks listed in the package description + file. + --disable-benchmarks # Disable dependency checking and compilation + for benchmarks listed in the package + description file. + --enable-relocatable # Enable building a package that is relocatable. + (GHC only) + --disable-relocatable # Disable building a package that is + relocatable. (GHC only) + --disable-response-files # Enable workaround for old versions of programs + like "ar" that do not support @file arguments + --allow-depending-on-private-libs + # Allow depending on private libraries. If set, + the library visibility check MUST be done + externally. + --coverage-for=UNITID # A list of unit-ids of libraries to include in + the Haskell Program Coverage report. + --ignore-build-tools # Ignore build tool dependencies. If set, + declared build tools needn't be found for + compilation to proceed. + --with-PROG=PATH # Give the path to PROG + --PROG-option=OPT # Give an extra option to PROG (passed directly + to PROG as a single argument) + --PROG-options=OPTS # Give extra options to PROG (split on spaces, + use "" to prevent splitting) + --cabal-lib-version=VERSION # Select which version of the Cabal lib to use + to build packages (useful for testing). + --enable-append # Enable appending the new config to the old + config file + --disable-append # Disable appending the new config to the old + config file + --enable-backup # Enable the backup of the config file before + any alterations + --disable-backup # Disable the backup of the config file before + any alterations + -c CONSTRAINT or -cCONSTRAINT, --constraint=CONSTRAINT + # Specify constraints on a package (version, + installed/source, flags) + --preference=CONSTRAINT # Specify preferences (soft constraints) on the + version of a package + --solver=SOLVER # Select dependency solver to use (default: + modular). Choices: modular. + --allow-older[=DEPS] # Ignore lower bounds in all dependencies or + DEPS + --allow-newer[=DEPS] # Ignore upper bounds in all dependencies or + DEPS + --write-ghc-environment-files=always|never|ghc8.4.4+ + # Whether to create a .ghc.environment file + after a successful build (v2-build only) + --enable-documentation # Enable building of documentation + --disable-documentation # Disable building of documentation + --doc-index-file=TEMPLATE # A central index of haddock API documentation + (template cannot use $pkgid) + --dry-run # Do not install anything, only print what would + be installed. + --only-download # Do not build anything, only fetch the + packages. + --max-backjumps=NUM # Maximum number of backjumps allowed while + solving (default: 4000). Use a negative number + to enable unlimited backtracking. Use 0 to + disable backtracking completely. + --reorder-goals # Try to reorder goals according to certain + heuristics. Slows things down on average, but + may make backtracking faster for some + packages. + --count-conflicts # Try to speed up solving by preferring goals + that are involved in a lot of conflicts + (default). + --fine-grained-conflicts # Skip a version of a package if it does not + resolve the conflicts encountered in the last + version, as a solver optimization (default). + --minimize-conflict-set # When there is no solution, try to improve the + error message by finding a minimal conflict + set (default: false). May increase run time + significantly. + --independent-goals # Treat several goals on the command line as + independent. If several goals depend on the + same package, different versions can be + chosen. + --prefer-oldest # Prefer the oldest (instead of the latest) + versions of packages available. Useful to + determine lower bounds in the build-depends + section. + --prefer-version=oldest|latest|installed-or-latest + # Select which version of a package that the + solver should prefer. Oldest is useful to + determine lower bounds in build-depends + section. Latest will prefer the latest + version. Installed-or-latest will prefer + installed versions and the latest version + otherwise. + --shadow-installed-packages # If multiple package instances of the same + version are installed, treat all but one as + shadowed. + --strong-flags # Do not defer flag choices (this used to be the + default in cabal-install <= 1.20). + --allow-boot-library-installs + # Allow cabal to install base, ghc-prim, + integer-simple, integer-gmp, and + template-haskell. + --reject-unconstrained-dependencies=none|all + # Require these packages to have constraints on + them if they are to be selected (default: + none). + --reinstall # Install even if it means installing the same + version again. + --avoid-reinstalls # Do not select versions that would + destructively overwrite installed packages. + --force-reinstalls # Reinstall packages even if they will most + likely break other installed packages. + --upgrade-dependencies # Pick the latest version for all dependencies, + rather than trying to pick an installed + version. + --only-dependencies # Install only the dependencies necessary to + build the given packages + --dependencies-only # A synonym for --only-dependencies + --index-state=STATE # Use source package index state as it existed + at a previous time. Accepts unix-timestamps + (e.g. '@1474732068'), ISO8601 UTC timestamps + (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' + (default: 'HEAD'). + --root-cmd=COMMAND # (No longer supported, do not use.) + --build-summary=TEMPLATE # Save build summaries to file (name template + can use $pkgid, $compiler, $os, $arch) + --build-log=TEMPLATE # Log all builds to file (name template can use + $pkgid, $compiler, $os, $arch) + --remote-build-reporting=LEVEL + # Generate build reports to send to a remote + server (none, anonymous or detailed). + --report-planning-failure # Generate build reports when the dependency + solver fails. This is used by the Hackage + build bot. + --enable-per-component # Enable Per-component builds when possible + --disable-per-component # Disable Per-component builds when possible + --run-tests # Run package test suites during installation. + --semaphore # Use a semaphore so GHC can compile components + in parallel + -j[NUM], --jobs[=NUM] # Run NUM jobs simultaneously (or '$ncpus' if no + NUM is given). + --keep-going # After a build failure, continue to build other + unaffected packages. + --offline # Don't download packages from the Internet. + --build-timings # Print elapsed time for each build phase. + --haddock-hoogle # Generate a hoogle database + --haddock-html # Generate HTML documentation (the default) + --haddock-html-location=URL # Location of HTML documentation for + pre-requisite packages + --haddock-for-hackage # Collection of flags to generate documentation + suitable for upload to hackage + --haddock-executables # Run haddock for Executables targets + --haddock-tests # Run haddock for Test Suite targets + --haddock-benchmarks # Run haddock for Benchmark targets + --haddock-all # Run haddock for all targets + --haddock-internal # Run haddock for internal modules and include + all symbols + --haddock-css=PATH # Use PATH as the haddock stylesheet + --haddock-hyperlink-source # Hyperlink the documentation to the source code + --haddock-quickjump # Generate an index for interactive + documentation navigation + --haddock-hscolour-css=PATH # Use PATH as the HsColour stylesheet + --haddock-contents-location=URL + # Bake URL in as the location for the contents + page + --haddock-base-url=URL # Base URL for static files. + --haddock-resources-dir=DIR # Location of Haddocks static / auxiliary files + --haddock-output-dir=DIR # Generate haddock documentation into this + directory. This flag is provided as a + technology preview and is subject to change in + the next releases. + --haddock-use-unicode # Pass --use-unicode option to haddock + --test-log=TEMPLATE # Log all test suite results to file (name + template can use $pkgid, $compiler, $os, + $arch, $test-suite, $result) + --test-machine-log=TEMPLATE # Produce a machine-readable log file (name + template can use $pkgid, $compiler, $os, + $arch, $result) + --test-show-details=FILTER # 'always': always show results of individual + test cases. 'never': never show results of + individual test cases. 'failures': show + results of failing test cases. 'streaming': + show results of test cases in real + time.'direct': send results of test cases in + real time; no log file. + --test-keep-tix-files # Keep .tix files for HPC between test runs + --test-wrapper=FILE # Run test through a wrapper. + --test-fail-when-no-test-suites + # Exit with failure when no test suites are + found. + --test-options=TEMPLATES # Give extra options to test executables (split + on spaces, use "" to prevent splitting; name + templates can use $pkgid, $compiler, $os, + $arch, $test-suite) + --test-option=TEMPLATE # Give extra option to test executables (passed + directly as a single argument; name template + can use $pkgid, $compiler, $os, $arch, + $test-suite) + --benchmark-options=TEMPLATES + # Give extra options to benchmark executables + (split on spaces, use "" to prevent splitting; + name templates can use $pkgid, $compiler, $os, + $arch, $benchmark) + --benchmark-option=TEMPLATE # Give extra option to benchmark executables + (passed directly as a single argument; name + template can use $pkgid, $compiler, $os, + $arch, $benchmark) + --project-dir=DIR # Set the path of the project directory + --project-file=FILE # Set the path of the cabal.project file + (relative to the project directory when + relative) + --project-file-parser=PARSER # Set the parser to use for the project file diff --git a/doc/cmd-v2-help/fetch.txt b/doc/cmd-v2-help/fetch.txt new file mode 100644 index 00000000000..b66044ab234 --- /dev/null +++ b/doc/cmd-v2-help/fetch.txt @@ -0,0 +1,76 @@ +Downloads packages for later installation. + +Usage: cabal fetch [FLAGS] PACKAGES + +Note that it currently is not possible to fetch the dependencies for a +package in the current directory. + +Flags for fetch: + -h, --help # Show this help text + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + --dependencies # Resolve and fetch dependencies (default) + --no-dependencies # Ignore dependencies + --dry-run # Do not install anything, only print what would + be installed. + --enable-tests # Enable dependency checking and compilation for + test suites listed in the package description + file. + --disable-tests # Disable dependency checking and compilation + for test suites listed in the package + description file. + --enable-benchmarks # Enable dependency checking and compilation for + benchmarks listed in the package description + file. + --disable-benchmarks # Disable dependency checking and compilation + for benchmarks listed in the package + description file. + --solver=SOLVER # Select dependency solver to use (default: + modular). Choices: modular. + --max-backjumps=NUM # Maximum number of backjumps allowed while + solving (default: 4000). Use a negative number + to enable unlimited backtracking. Use 0 to + disable backtracking completely. + --reorder-goals # Try to reorder goals according to certain + heuristics. Slows things down on average, but + may make backtracking faster for some + packages. + --count-conflicts # Try to speed up solving by preferring goals + that are involved in a lot of conflicts + (default). + --fine-grained-conflicts # Skip a version of a package if it does not + resolve the conflicts encountered in the last + version, as a solver optimization (default). + --minimize-conflict-set # When there is no solution, try to improve the + error message by finding a minimal conflict + set (default: false). May increase run time + significantly. + --independent-goals # Treat several goals on the command line as + independent. If several goals depend on the + same package, different versions can be + chosen. + --prefer-oldest # Prefer the oldest (instead of the latest) + versions of packages available. Useful to + determine lower bounds in the build-depends + section. + --prefer-version=oldest|latest|installed-or-latest + # Select which version of a package that the + solver should prefer. Oldest is useful to + determine lower bounds in build-depends + section. Latest will prefer the latest + version. Installed-or-latest will prefer + installed versions and the latest version + otherwise. + --shadow-installed-packages # If multiple package instances of the same + version are installed, treat all but one as + shadowed. + --strong-flags # Do not defer flag choices (this used to be the + default in cabal-install <= 1.20). + --allow-boot-library-installs + # Allow cabal to install base, ghc-prim, + integer-simple, integer-gmp, and + template-haskell. + --reject-unconstrained-dependencies=none|all + # Require these packages to have constraints on + them if they are to be selected (default: + none). diff --git a/doc/cmd-v2-help/freeze.txt b/doc/cmd-v2-help/freeze.txt new file mode 100644 index 00000000000..64269ce7f8e --- /dev/null +++ b/doc/cmd-v2-help/freeze.txt @@ -0,0 +1,387 @@ +Freeze dependencies. + +Usage: cabal freeze [FLAGS] + +The project configuration is frozen so that it will be reproducible in future. + +The precise dependency configuration for the project is written to the +'cabal.project.freeze' file (or '$project_file.freeze' if '--project-file' is +specified). This file extends the configuration from the 'cabal.project' file +and thus is used as the project configuration for all other commands (such as +'build', 'repl' etc). + +The freeze file can be kept in source control. To make small adjustments it +may be edited manually, or to make bigger changes you may wish to delete the +file and re-freeze. For more control, one approach is to try variations using +'build --dry-run' with solver flags such as '--constraint="pkg < 1.2"' and +once you have a satisfactory solution to freeze it using the 'freeze' +command with the same set of flags. + +Flags for freeze: + -h, --help # Show this help text + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + --builddir=DIR # The directory where Cabal puts generated build + files (default dist) + --keep-temp-files # Keep temporary files. + -g, --ghc # Compile with GHC + --ghcjs # Compile with GHCJS + --uhc # Compile with UHC + -w PATH or -wPATH, --with-compiler=PATH + # Give the path to a particular compiler + --with-hc-pkg=PATH # Give the path to the package tool + --prefix=DIR # Bake this prefix in preparation of + installation + --bindir=DIR # Installation directory for executables + --libdir=DIR # Installation directory for libraries + --libsubdir=DIR # Subdirectory of libdir in which libs are + installed + --dynlibdir=DIR # Installation directory for dynamic libraries + --bytecodelibdir=DIR # Installation directory for bytecode libraries + --libexecdir=DIR # Installation directory for program executables + --libexecsubdir=DIR # Subdirectory of libexecdir in which private + executables are installed + --datadir=DIR # Installation directory for read-only data + --datasubdir=DIR # Subdirectory of datadir in which data files + are installed + --docdir=DIR # Installation directory for documentation + --htmldir=DIR # Installation directory for HTML documentation + --haddockdir=DIR # Installation directory for haddock interfaces + --sysconfdir=DIR # Installation directory for configuration files + --program-prefix=PREFIX # Prefix to be applied to installed executables + --program-suffix=SUFFIX # Suffix to be applied to installed executables + --enable-library-vanilla # Enable Vanilla libraries + --disable-library-vanilla # Disable Vanilla libraries + -p, --enable-library-profiling + # Enable Library profiling + --disable-library-profiling # Disable Library profiling + --enable-shared # Enable Shared library + --disable-shared # Disable Shared library + --enable-static # Enable Static library + --disable-static # Disable Static library + --enable-library-bytecode # Enable Bytecode library + --disable-library-bytecode # Disable Bytecode library + --enable-executable-dynamic # Enable Executable dynamic linking + --disable-executable-dynamic # Disable Executable dynamic linking + --enable-executable-static # Enable Executable fully static linking + --disable-executable-static # Disable Executable fully static linking + --enable-profiling # Enable Executable and library profiling + --disable-profiling # Disable Executable and library profiling + --enable-profiling-shared # Enable Build profiling shared libraries + --disable-profiling-shared # Disable Build profiling shared libraries + --enable-executable-profiling + # Enable Executable profiling (DEPRECATED) + --disable-executable-profiling + # Disable Executable profiling (DEPRECATED) + --profiling-detail=level # Profiling detail level for executable and + library (default, none, exported-functions, + toplevel-functions, all-functions, late). + --library-profiling-detail=level + # Profiling detail level for libraries only. + -O[n], --enable-optimization[=n] + # Build with optimization (n is 0--2, default is + 1) + --disable-optimization # Build without optimization + --enable-debug-info[=n] # Emit debug info (n is 0--3, default is 0) + --disable-debug-info # Don't emit debug info + --enable-build-info # Enable build information generation during + project building + --disable-build-info # Disable build information generation during + project building + --enable-library-for-ghci # Enable compile library for use with GHCi + --disable-library-for-ghci # Disable compile library for use with GHCi + --enable-split-sections # Enable compile library code such that unneeded + definitions can be dropped from the final + executable (GHC 7.8+) + --disable-split-sections # Disable compile library code such that + unneeded definitions can be dropped from the + final executable (GHC 7.8+) + --enable-split-objs # Enable split library into smaller objects to + reduce binary sizes (GHC 6.6+) + --disable-split-objs # Disable split library into smaller objects to + reduce binary sizes (GHC 6.6+) + --enable-executable-stripping + # Enable strip executables upon installation to + reduce binary sizes + --disable-executable-stripping + # Disable strip executables upon installation to + reduce binary sizes + --enable-library-stripping # Enable strip libraries upon installation to + reduce binary sizes + --disable-library-stripping # Disable strip libraries upon installation to + reduce binary sizes + --configure-option=OPT # Extra option for configure + --user # Enable doing a per-user installation + --global # Disable doing a per-user installation + --package-db=DB # Append the given package database to the list + of package databases used (to satisfy + dependencies and register into). May be a + specific file, 'global' or 'user'. The initial + list is ['global'], ['global', 'user'], or + ['global', $sandbox], depending on context. + Use 'clear' to reset the list to empty. See + the user guide for details. + -f FLAGS or -fFLAGS, --flags=FLAGS + # Force values for the given flags in Cabal + conditionals in the .cabal file. E.g., + --flags="debug -usebytestrings" forces the + flag "debug" to true and "usebytestrings" to + false. + --extra-include-dirs=PATH # A list of directories to search for header + files + --enable-deterministic # Enable Try to be as deterministic as possible + (used by the test suite) + --disable-deterministic # Disable Try to be as deterministic as possible + (used by the test suite) + --ipid=IPID # Installed package ID to compile this package + as + --cid=CID # Installed component ID to compile this + component as + --extra-lib-dirs=PATH # A list of directories to search for external + libraries + --extra-lib-dirs-static=PATH # A list of directories to search for external + libraries when linking fully static + executables + --extra-framework-dirs=PATH # A list of directories to search for external + frameworks (OS X only) + --extra-prog-path=PATH # A list of directories to search for required + programs (in addition to the normal search + locations) + --instantiate-with=NAME=MOD # A mapping of signature names to concrete + module instantiations. + --enable-tests # Enable dependency checking and compilation for + test suites listed in the package description + file. + --disable-tests # Disable dependency checking and compilation + for test suites listed in the package + description file. + --enable-coverage # Enable build package with Haskell Program + Coverage. (GHC only) + --disable-coverage # Disable build package with Haskell Program + Coverage. (GHC only) + --enable-library-coverage # Enable build package with Haskell Program + Coverage. (GHC only) (DEPRECATED) + --disable-library-coverage # Disable build package with Haskell Program + Coverage. (GHC only) (DEPRECATED) + --enable-benchmarks # Enable dependency checking and compilation for + benchmarks listed in the package description + file. + --disable-benchmarks # Disable dependency checking and compilation + for benchmarks listed in the package + description file. + --enable-relocatable # Enable building a package that is relocatable. + (GHC only) + --disable-relocatable # Disable building a package that is + relocatable. (GHC only) + --disable-response-files # Enable workaround for old versions of programs + like "ar" that do not support @file arguments + --allow-depending-on-private-libs + # Allow depending on private libraries. If set, + the library visibility check MUST be done + externally. + --coverage-for=UNITID # A list of unit-ids of libraries to include in + the Haskell Program Coverage report. + --ignore-build-tools # Ignore build tool dependencies. If set, + declared build tools needn't be found for + compilation to proceed. + --with-PROG=PATH # Give the path to PROG + --PROG-option=OPT # Give an extra option to PROG (passed directly + to PROG as a single argument) + --PROG-options=OPTS # Give extra options to PROG (split on spaces, + use "" to prevent splitting) + --cabal-lib-version=VERSION # Select which version of the Cabal lib to use + to build packages (useful for testing). + --enable-append # Enable appending the new config to the old + config file + --disable-append # Disable appending the new config to the old + config file + --enable-backup # Enable the backup of the config file before + any alterations + --disable-backup # Disable the backup of the config file before + any alterations + -c CONSTRAINT or -cCONSTRAINT, --constraint=CONSTRAINT + # Specify constraints on a package (version, + installed/source, flags) + --preference=CONSTRAINT # Specify preferences (soft constraints) on the + version of a package + --solver=SOLVER # Select dependency solver to use (default: + modular). Choices: modular. + --allow-older[=DEPS] # Ignore lower bounds in all dependencies or + DEPS + --allow-newer[=DEPS] # Ignore upper bounds in all dependencies or + DEPS + --write-ghc-environment-files=always|never|ghc8.4.4+ + # Whether to create a .ghc.environment file + after a successful build (v2-build only) + --enable-documentation # Enable building of documentation + --disable-documentation # Disable building of documentation + --doc-index-file=TEMPLATE # A central index of haddock API documentation + (template cannot use $pkgid) + --dry-run # Do not install anything, only print what would + be installed. + --only-download # Do not build anything, only fetch the + packages. + --max-backjumps=NUM # Maximum number of backjumps allowed while + solving (default: 4000). Use a negative number + to enable unlimited backtracking. Use 0 to + disable backtracking completely. + --reorder-goals # Try to reorder goals according to certain + heuristics. Slows things down on average, but + may make backtracking faster for some + packages. + --count-conflicts # Try to speed up solving by preferring goals + that are involved in a lot of conflicts + (default). + --fine-grained-conflicts # Skip a version of a package if it does not + resolve the conflicts encountered in the last + version, as a solver optimization (default). + --minimize-conflict-set # When there is no solution, try to improve the + error message by finding a minimal conflict + set (default: false). May increase run time + significantly. + --independent-goals # Treat several goals on the command line as + independent. If several goals depend on the + same package, different versions can be + chosen. + --prefer-oldest # Prefer the oldest (instead of the latest) + versions of packages available. Useful to + determine lower bounds in the build-depends + section. + --prefer-version=oldest|latest|installed-or-latest + # Select which version of a package that the + solver should prefer. Oldest is useful to + determine lower bounds in build-depends + section. Latest will prefer the latest + version. Installed-or-latest will prefer + installed versions and the latest version + otherwise. + --shadow-installed-packages # If multiple package instances of the same + version are installed, treat all but one as + shadowed. + --strong-flags # Do not defer flag choices (this used to be the + default in cabal-install <= 1.20). + --allow-boot-library-installs + # Allow cabal to install base, ghc-prim, + integer-simple, integer-gmp, and + template-haskell. + --reject-unconstrained-dependencies=none|all + # Require these packages to have constraints on + them if they are to be selected (default: + none). + --reinstall # Install even if it means installing the same + version again. + --avoid-reinstalls # Do not select versions that would + destructively overwrite installed packages. + --force-reinstalls # Reinstall packages even if they will most + likely break other installed packages. + --upgrade-dependencies # Pick the latest version for all dependencies, + rather than trying to pick an installed + version. + --only-dependencies # Install only the dependencies necessary to + build the given packages + --dependencies-only # A synonym for --only-dependencies + --index-state=STATE # Use source package index state as it existed + at a previous time. Accepts unix-timestamps + (e.g. '@1474732068'), ISO8601 UTC timestamps + (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' + (default: 'HEAD'). + --root-cmd=COMMAND # (No longer supported, do not use.) + --build-summary=TEMPLATE # Save build summaries to file (name template + can use $pkgid, $compiler, $os, $arch) + --build-log=TEMPLATE # Log all builds to file (name template can use + $pkgid, $compiler, $os, $arch) + --remote-build-reporting=LEVEL + # Generate build reports to send to a remote + server (none, anonymous or detailed). + --report-planning-failure # Generate build reports when the dependency + solver fails. This is used by the Hackage + build bot. + --enable-per-component # Enable Per-component builds when possible + --disable-per-component # Disable Per-component builds when possible + --run-tests # Run package test suites during installation. + --semaphore # Use a semaphore so GHC can compile components + in parallel + -j[NUM], --jobs[=NUM] # Run NUM jobs simultaneously (or '$ncpus' if no + NUM is given). + --keep-going # After a build failure, continue to build other + unaffected packages. + --offline # Don't download packages from the Internet. + --build-timings # Print elapsed time for each build phase. + --haddock-hoogle # Generate a hoogle database + --haddock-html # Generate HTML documentation (the default) + --haddock-html-location=URL # Location of HTML documentation for + pre-requisite packages + --haddock-for-hackage # Collection of flags to generate documentation + suitable for upload to hackage + --haddock-executables # Run haddock for Executables targets + --haddock-tests # Run haddock for Test Suite targets + --haddock-benchmarks # Run haddock for Benchmark targets + --haddock-all # Run haddock for all targets + --haddock-internal # Run haddock for internal modules and include + all symbols + --haddock-css=PATH # Use PATH as the haddock stylesheet + --haddock-hyperlink-source # Hyperlink the documentation to the source code + --haddock-quickjump # Generate an index for interactive + documentation navigation + --haddock-hscolour-css=PATH # Use PATH as the HsColour stylesheet + --haddock-contents-location=URL + # Bake URL in as the location for the contents + page + --haddock-base-url=URL # Base URL for static files. + --haddock-resources-dir=DIR # Location of Haddocks static / auxiliary files + --haddock-output-dir=DIR # Generate haddock documentation into this + directory. This flag is provided as a + technology preview and is subject to change in + the next releases. + --haddock-use-unicode # Pass --use-unicode option to haddock + --test-log=TEMPLATE # Log all test suite results to file (name + template can use $pkgid, $compiler, $os, + $arch, $test-suite, $result) + --test-machine-log=TEMPLATE # Produce a machine-readable log file (name + template can use $pkgid, $compiler, $os, + $arch, $result) + --test-show-details=FILTER # 'always': always show results of individual + test cases. 'never': never show results of + individual test cases. 'failures': show + results of failing test cases. 'streaming': + show results of test cases in real + time.'direct': send results of test cases in + real time; no log file. + --test-keep-tix-files # Keep .tix files for HPC between test runs + --test-wrapper=FILE # Run test through a wrapper. + --test-fail-when-no-test-suites + # Exit with failure when no test suites are + found. + --test-options=TEMPLATES # Give extra options to test executables (split + on spaces, use "" to prevent splitting; name + templates can use $pkgid, $compiler, $os, + $arch, $test-suite) + --test-option=TEMPLATE # Give extra option to test executables (passed + directly as a single argument; name template + can use $pkgid, $compiler, $os, $arch, + $test-suite) + --benchmark-options=TEMPLATES + # Give extra options to benchmark executables + (split on spaces, use "" to prevent splitting; + name templates can use $pkgid, $compiler, $os, + $arch, $benchmark) + --benchmark-option=TEMPLATE # Give extra option to benchmark executables + (passed directly as a single argument; name + template can use $pkgid, $compiler, $os, + $arch, $benchmark) + --project-dir=DIR # Set the path of the project directory + --project-file=FILE # Set the path of the cabal.project file + (relative to the project directory when + relative) + -z, --ignore-project # Ignore local project configuration (unless + --project-dir or --project-file is also set) + --project-file-parser=PARSER # Set the parser to use for the project file + +Examples: + cabal freeze + Freeze the configuration of the current project + + cabal build --dry-run --constraint="aeson < 1" + Check what a solution with the given constraints would look like + cabal freeze --constraint="aeson < 1" + Freeze a solution using the given constraints diff --git a/doc/cmd-v2-help/gen-bounds.txt b/doc/cmd-v2-help/gen-bounds.txt new file mode 100644 index 00000000000..8764aac5bda --- /dev/null +++ b/doc/cmd-v2-help/gen-bounds.txt @@ -0,0 +1,370 @@ +Generate dependency bounds for packages in the project. + +Usage: cabal gen-bounds [TARGETS] [FLAGS] + +Generate PVP-compliant dependency bounds for packages in the project. +Flags for gen-bounds: + -h, --help # Show this help text + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + --builddir=DIR # The directory where Cabal puts generated build + files (default dist) + --keep-temp-files # Keep temporary files. + -g, --ghc # Compile with GHC + --ghcjs # Compile with GHCJS + --uhc # Compile with UHC + -w PATH or -wPATH, --with-compiler=PATH + # Give the path to a particular compiler + --with-hc-pkg=PATH # Give the path to the package tool + --prefix=DIR # Bake this prefix in preparation of + installation + --bindir=DIR # Installation directory for executables + --libdir=DIR # Installation directory for libraries + --libsubdir=DIR # Subdirectory of libdir in which libs are + installed + --dynlibdir=DIR # Installation directory for dynamic libraries + --bytecodelibdir=DIR # Installation directory for bytecode libraries + --libexecdir=DIR # Installation directory for program executables + --libexecsubdir=DIR # Subdirectory of libexecdir in which private + executables are installed + --datadir=DIR # Installation directory for read-only data + --datasubdir=DIR # Subdirectory of datadir in which data files + are installed + --docdir=DIR # Installation directory for documentation + --htmldir=DIR # Installation directory for HTML documentation + --haddockdir=DIR # Installation directory for haddock interfaces + --sysconfdir=DIR # Installation directory for configuration files + --program-prefix=PREFIX # Prefix to be applied to installed executables + --program-suffix=SUFFIX # Suffix to be applied to installed executables + --enable-library-vanilla # Enable Vanilla libraries + --disable-library-vanilla # Disable Vanilla libraries + -p, --enable-library-profiling + # Enable Library profiling + --disable-library-profiling # Disable Library profiling + --enable-shared # Enable Shared library + --disable-shared # Disable Shared library + --enable-static # Enable Static library + --disable-static # Disable Static library + --enable-library-bytecode # Enable Bytecode library + --disable-library-bytecode # Disable Bytecode library + --enable-executable-dynamic # Enable Executable dynamic linking + --disable-executable-dynamic # Disable Executable dynamic linking + --enable-executable-static # Enable Executable fully static linking + --disable-executable-static # Disable Executable fully static linking + --enable-profiling # Enable Executable and library profiling + --disable-profiling # Disable Executable and library profiling + --enable-profiling-shared # Enable Build profiling shared libraries + --disable-profiling-shared # Disable Build profiling shared libraries + --enable-executable-profiling + # Enable Executable profiling (DEPRECATED) + --disable-executable-profiling + # Disable Executable profiling (DEPRECATED) + --profiling-detail=level # Profiling detail level for executable and + library (default, none, exported-functions, + toplevel-functions, all-functions, late). + --library-profiling-detail=level + # Profiling detail level for libraries only. + -O[n], --enable-optimization[=n] + # Build with optimization (n is 0--2, default is + 1) + --disable-optimization # Build without optimization + --enable-debug-info[=n] # Emit debug info (n is 0--3, default is 0) + --disable-debug-info # Don't emit debug info + --enable-build-info # Enable build information generation during + project building + --disable-build-info # Disable build information generation during + project building + --enable-library-for-ghci # Enable compile library for use with GHCi + --disable-library-for-ghci # Disable compile library for use with GHCi + --enable-split-sections # Enable compile library code such that unneeded + definitions can be dropped from the final + executable (GHC 7.8+) + --disable-split-sections # Disable compile library code such that + unneeded definitions can be dropped from the + final executable (GHC 7.8+) + --enable-split-objs # Enable split library into smaller objects to + reduce binary sizes (GHC 6.6+) + --disable-split-objs # Disable split library into smaller objects to + reduce binary sizes (GHC 6.6+) + --enable-executable-stripping + # Enable strip executables upon installation to + reduce binary sizes + --disable-executable-stripping + # Disable strip executables upon installation to + reduce binary sizes + --enable-library-stripping # Enable strip libraries upon installation to + reduce binary sizes + --disable-library-stripping # Disable strip libraries upon installation to + reduce binary sizes + --configure-option=OPT # Extra option for configure + --user # Enable doing a per-user installation + --global # Disable doing a per-user installation + --package-db=DB # Append the given package database to the list + of package databases used (to satisfy + dependencies and register into). May be a + specific file, 'global' or 'user'. The initial + list is ['global'], ['global', 'user'], or + ['global', $sandbox], depending on context. + Use 'clear' to reset the list to empty. See + the user guide for details. + -f FLAGS or -fFLAGS, --flags=FLAGS + # Force values for the given flags in Cabal + conditionals in the .cabal file. E.g., + --flags="debug -usebytestrings" forces the + flag "debug" to true and "usebytestrings" to + false. + --extra-include-dirs=PATH # A list of directories to search for header + files + --enable-deterministic # Enable Try to be as deterministic as possible + (used by the test suite) + --disable-deterministic # Disable Try to be as deterministic as possible + (used by the test suite) + --ipid=IPID # Installed package ID to compile this package + as + --cid=CID # Installed component ID to compile this + component as + --extra-lib-dirs=PATH # A list of directories to search for external + libraries + --extra-lib-dirs-static=PATH # A list of directories to search for external + libraries when linking fully static + executables + --extra-framework-dirs=PATH # A list of directories to search for external + frameworks (OS X only) + --extra-prog-path=PATH # A list of directories to search for required + programs (in addition to the normal search + locations) + --instantiate-with=NAME=MOD # A mapping of signature names to concrete + module instantiations. + --enable-tests # Enable dependency checking and compilation for + test suites listed in the package description + file. + --disable-tests # Disable dependency checking and compilation + for test suites listed in the package + description file. + --enable-coverage # Enable build package with Haskell Program + Coverage. (GHC only) + --disable-coverage # Disable build package with Haskell Program + Coverage. (GHC only) + --enable-library-coverage # Enable build package with Haskell Program + Coverage. (GHC only) (DEPRECATED) + --disable-library-coverage # Disable build package with Haskell Program + Coverage. (GHC only) (DEPRECATED) + --enable-benchmarks # Enable dependency checking and compilation for + benchmarks listed in the package description + file. + --disable-benchmarks # Disable dependency checking and compilation + for benchmarks listed in the package + description file. + --enable-relocatable # Enable building a package that is relocatable. + (GHC only) + --disable-relocatable # Disable building a package that is + relocatable. (GHC only) + --disable-response-files # Enable workaround for old versions of programs + like "ar" that do not support @file arguments + --allow-depending-on-private-libs + # Allow depending on private libraries. If set, + the library visibility check MUST be done + externally. + --coverage-for=UNITID # A list of unit-ids of libraries to include in + the Haskell Program Coverage report. + --ignore-build-tools # Ignore build tool dependencies. If set, + declared build tools needn't be found for + compilation to proceed. + --with-PROG=PATH # Give the path to PROG + --PROG-option=OPT # Give an extra option to PROG (passed directly + to PROG as a single argument) + --PROG-options=OPTS # Give extra options to PROG (split on spaces, + use "" to prevent splitting) + --cabal-lib-version=VERSION # Select which version of the Cabal lib to use + to build packages (useful for testing). + --enable-append # Enable appending the new config to the old + config file + --disable-append # Disable appending the new config to the old + config file + --enable-backup # Enable the backup of the config file before + any alterations + --disable-backup # Disable the backup of the config file before + any alterations + -c CONSTRAINT or -cCONSTRAINT, --constraint=CONSTRAINT + # Specify constraints on a package (version, + installed/source, flags) + --preference=CONSTRAINT # Specify preferences (soft constraints) on the + version of a package + --solver=SOLVER # Select dependency solver to use (default: + modular). Choices: modular. + --allow-older[=DEPS] # Ignore lower bounds in all dependencies or + DEPS + --allow-newer[=DEPS] # Ignore upper bounds in all dependencies or + DEPS + --write-ghc-environment-files=always|never|ghc8.4.4+ + # Whether to create a .ghc.environment file + after a successful build (v2-build only) + --enable-documentation # Enable building of documentation + --disable-documentation # Disable building of documentation + --doc-index-file=TEMPLATE # A central index of haddock API documentation + (template cannot use $pkgid) + --dry-run # Do not install anything, only print what would + be installed. + --only-download # Do not build anything, only fetch the + packages. + --max-backjumps=NUM # Maximum number of backjumps allowed while + solving (default: 4000). Use a negative number + to enable unlimited backtracking. Use 0 to + disable backtracking completely. + --reorder-goals # Try to reorder goals according to certain + heuristics. Slows things down on average, but + may make backtracking faster for some + packages. + --count-conflicts # Try to speed up solving by preferring goals + that are involved in a lot of conflicts + (default). + --fine-grained-conflicts # Skip a version of a package if it does not + resolve the conflicts encountered in the last + version, as a solver optimization (default). + --minimize-conflict-set # When there is no solution, try to improve the + error message by finding a minimal conflict + set (default: false). May increase run time + significantly. + --independent-goals # Treat several goals on the command line as + independent. If several goals depend on the + same package, different versions can be + chosen. + --prefer-oldest # Prefer the oldest (instead of the latest) + versions of packages available. Useful to + determine lower bounds in the build-depends + section. + --prefer-version=oldest|latest|installed-or-latest + # Select which version of a package that the + solver should prefer. Oldest is useful to + determine lower bounds in build-depends + section. Latest will prefer the latest + version. Installed-or-latest will prefer + installed versions and the latest version + otherwise. + --shadow-installed-packages # If multiple package instances of the same + version are installed, treat all but one as + shadowed. + --strong-flags # Do not defer flag choices (this used to be the + default in cabal-install <= 1.20). + --allow-boot-library-installs + # Allow cabal to install base, ghc-prim, + integer-simple, integer-gmp, and + template-haskell. + --reject-unconstrained-dependencies=none|all + # Require these packages to have constraints on + them if they are to be selected (default: + none). + --reinstall # Install even if it means installing the same + version again. + --avoid-reinstalls # Do not select versions that would + destructively overwrite installed packages. + --force-reinstalls # Reinstall packages even if they will most + likely break other installed packages. + --upgrade-dependencies # Pick the latest version for all dependencies, + rather than trying to pick an installed + version. + --only-dependencies # Install only the dependencies necessary to + build the given packages + --dependencies-only # A synonym for --only-dependencies + --index-state=STATE # Use source package index state as it existed + at a previous time. Accepts unix-timestamps + (e.g. '@1474732068'), ISO8601 UTC timestamps + (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' + (default: 'HEAD'). + --root-cmd=COMMAND # (No longer supported, do not use.) + --build-summary=TEMPLATE # Save build summaries to file (name template + can use $pkgid, $compiler, $os, $arch) + --build-log=TEMPLATE # Log all builds to file (name template can use + $pkgid, $compiler, $os, $arch) + --remote-build-reporting=LEVEL + # Generate build reports to send to a remote + server (none, anonymous or detailed). + --report-planning-failure # Generate build reports when the dependency + solver fails. This is used by the Hackage + build bot. + --enable-per-component # Enable Per-component builds when possible + --disable-per-component # Disable Per-component builds when possible + --run-tests # Run package test suites during installation. + --semaphore # Use a semaphore so GHC can compile components + in parallel + -j[NUM], --jobs[=NUM] # Run NUM jobs simultaneously (or '$ncpus' if no + NUM is given). + --keep-going # After a build failure, continue to build other + unaffected packages. + --offline # Don't download packages from the Internet. + --build-timings # Print elapsed time for each build phase. + --haddock-hoogle # Generate a hoogle database + --haddock-html # Generate HTML documentation (the default) + --haddock-html-location=URL # Location of HTML documentation for + pre-requisite packages + --haddock-for-hackage # Collection of flags to generate documentation + suitable for upload to hackage + --haddock-executables # Run haddock for Executables targets + --haddock-tests # Run haddock for Test Suite targets + --haddock-benchmarks # Run haddock for Benchmark targets + --haddock-all # Run haddock for all targets + --haddock-internal # Run haddock for internal modules and include + all symbols + --haddock-css=PATH # Use PATH as the haddock stylesheet + --haddock-hyperlink-source # Hyperlink the documentation to the source code + --haddock-quickjump # Generate an index for interactive + documentation navigation + --haddock-hscolour-css=PATH # Use PATH as the HsColour stylesheet + --haddock-contents-location=URL + # Bake URL in as the location for the contents + page + --haddock-base-url=URL # Base URL for static files. + --haddock-resources-dir=DIR # Location of Haddocks static / auxiliary files + --haddock-output-dir=DIR # Generate haddock documentation into this + directory. This flag is provided as a + technology preview and is subject to change in + the next releases. + --haddock-use-unicode # Pass --use-unicode option to haddock + --test-log=TEMPLATE # Log all test suite results to file (name + template can use $pkgid, $compiler, $os, + $arch, $test-suite, $result) + --test-machine-log=TEMPLATE # Produce a machine-readable log file (name + template can use $pkgid, $compiler, $os, + $arch, $result) + --test-show-details=FILTER # 'always': always show results of individual + test cases. 'never': never show results of + individual test cases. 'failures': show + results of failing test cases. 'streaming': + show results of test cases in real + time.'direct': send results of test cases in + real time; no log file. + --test-keep-tix-files # Keep .tix files for HPC between test runs + --test-wrapper=FILE # Run test through a wrapper. + --test-fail-when-no-test-suites + # Exit with failure when no test suites are + found. + --test-options=TEMPLATES # Give extra options to test executables (split + on spaces, use "" to prevent splitting; name + templates can use $pkgid, $compiler, $os, + $arch, $test-suite) + --test-option=TEMPLATE # Give extra option to test executables (passed + directly as a single argument; name template + can use $pkgid, $compiler, $os, $arch, + $test-suite) + --benchmark-options=TEMPLATES + # Give extra options to benchmark executables + (split on spaces, use "" to prevent splitting; + name templates can use $pkgid, $compiler, $os, + $arch, $benchmark) + --benchmark-option=TEMPLATE # Give extra option to benchmark executables + (passed directly as a single argument; name + template can use $pkgid, $compiler, $os, + $arch, $benchmark) + --project-dir=DIR # Set the path of the project directory + --project-file=FILE # Set the path of the cabal.project file + (relative to the project directory when + relative) + --project-file-parser=PARSER # Set the parser to use for the project file + +Examples: + cabal gen-bounds + Generate bounds for the package in the current directory or all packages in the project + cabal gen-bounds pkgname + Generate bounds for the package named pkgname in the project + cabal gen-bounds ./pkgfoo + Generate bounds for the package in the ./pkgfoo directory diff --git a/doc/cmd-v2-help/get.txt b/doc/cmd-v2-help/get.txt new file mode 100644 index 00000000000..8f4331e5cf4 --- /dev/null +++ b/doc/cmd-v2-help/get.txt @@ -0,0 +1,39 @@ +Download/Extract a package's source code (repository). + +Usage: cabal get [PACKAGES] + +Creates a local copy of a package's source code. By default it gets the source +tarball and unpacks it in a local subdirectory. Alternatively, with -s it will +get the code from the source repository specified by the package. + +Flags for get: + -h, --help # Show this help text + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + -d PATH or -dPATH, --destdir=PATH + # Where to place the package source, defaults to + the current directory. + -s[[head|this|...]], --source-repository[=[head|this|...]] + # Copy the package's source repository (ie git + clone, darcs get, etc as appropriate). + --index-state=STATE # Use source package index state as it existed + at a previous time. Accepts unix-timestamps + (e.g. '@1474732068'), ISO8601 UTC timestamps + (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' + (default: 'HEAD'). This determines which + package versions are available as well as + .cabal file revision is selected (unless + --pristine is used). + --only-package-description # Unpack only the package description file. + --package-description-only # A synonym for --only-package-description. + --pristine # Unpack the original pristine tarball, rather + than updating the .cabal file with the latest + revision from the package archive. + -R REPOSITORY or -RREPOSITORY, --repository=REPOSITORY + # Package repository to fetch from. + +Examples: + cabal get hlint + Download the latest stable version of hlint; + cabal get lens --source-repository=head + Download the source repository of lens (i.e. git clone from github). diff --git a/doc/cmd-v2-help/haddock-project.txt b/doc/cmd-v2-help/haddock-project.txt new file mode 100644 index 00000000000..bc92c06f752 --- /dev/null +++ b/doc/cmd-v2-help/haddock-project.txt @@ -0,0 +1,41 @@ +Generate Haddocks HTML documentation for the cabal project. + +Usage: cabal haddock-project [FLAGS] + or: cabal haddock-project COMPONENTS [FLAGS] + +Requires the program haddock, version 2.26. + +Flags for haddock-project: + -h, --help # Show this help text + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + --builddir=DIR # The directory where Cabal puts generated build + files (default dist) + --cabal-file=PATH # use this Cabal file + --keep-temp-files # Keep temporary files. + --hackage # A short-cut option to build documentation + linked to hackage. + --output[=DIRECTORY] # Output directory + --prologue[=PATH] # File path to a prologue file in haddock format + --hoogle # Generate a hoogle database + --html-location=URL # Location of HTML documentation for + pre-requisite packages + --executables # Run haddock for Executables targets + --tests # Run haddock for Test Suite targets + --benchmarks # Run haddock for Benchmark targets + --foreign-libraries # Run haddock for Foreign Library targets + --all # Run haddock for all targets + --internal # Run haddock for internal modules and include + all symbols + --css=PATH # Use PATH as the haddock stylesheet + --hscolour-css=PATH # Use PATH as the HsColour stylesheet + --resources-dir=DIR # Location of Haddocks static / auxiliary files + --use-unicode # Pass --use-unicode option to haddock + --with-ghc=PATH # Give the path to ghc + --with-haddock=PATH # Give the path to haddock + --PROG-option=OPT # Give an extra option to PROG (passed directly + to PROG as a single argument) + --ghc-options=OPTS # Give extra options to ghc (split on spaces, + use "" to prevent splitting) + --haddock-options=OPTS # Give extra options to haddock (split on + spaces, use "" to prevent splitting) diff --git a/doc/cmd-v2-help/haddock.txt b/doc/cmd-v2-help/haddock.txt new file mode 100644 index 00000000000..2e5046e47f7 --- /dev/null +++ b/doc/cmd-v2-help/haddock.txt @@ -0,0 +1,382 @@ +Build Haddock documentation. + +Usage: cabal haddock [FLAGS] TARGET + +Build Haddock documentation for the specified packages within the project. + +Any package in the project can be specified. If no package is specified, the +default is to build the documentation for the package in the current +directory. The default behaviour is to build documentation for the exposed +modules of the library component (if any). This can be changed with the +'--internal', '--executables', '--tests', '--benchmarks' or '--all' flags. + +Currently, documentation for dependencies is NOT built. This behavior may +change in future. + +Additional configuration flags can be specified on the command line and these +extend the project configuration from the 'cabal.project', +'cabal.project.local' and other files. + +Flags for haddock: + -h, --help # Show this help text + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + --builddir=DIR # The directory where Cabal puts generated build + files (default dist) + --keep-temp-files # Keep temporary files. + -g, --ghc # Compile with GHC + --ghcjs # Compile with GHCJS + --uhc # Compile with UHC + -w PATH or -wPATH, --with-compiler=PATH + # Give the path to a particular compiler + --with-hc-pkg=PATH # Give the path to the package tool + --prefix=DIR # Bake this prefix in preparation of + installation + --bindir=DIR # Installation directory for executables + --libdir=DIR # Installation directory for libraries + --libsubdir=DIR # Subdirectory of libdir in which libs are + installed + --dynlibdir=DIR # Installation directory for dynamic libraries + --bytecodelibdir=DIR # Installation directory for bytecode libraries + --libexecdir=DIR # Installation directory for program executables + --libexecsubdir=DIR # Subdirectory of libexecdir in which private + executables are installed + --datadir=DIR # Installation directory for read-only data + --datasubdir=DIR # Subdirectory of datadir in which data files + are installed + --docdir=DIR # Installation directory for documentation + --htmldir=DIR # Installation directory for HTML documentation + --haddockdir=DIR # Installation directory for haddock interfaces + --sysconfdir=DIR # Installation directory for configuration files + --program-prefix=PREFIX # Prefix to be applied to installed executables + --program-suffix=SUFFIX # Suffix to be applied to installed executables + --enable-library-vanilla # Enable Vanilla libraries + --disable-library-vanilla # Disable Vanilla libraries + -p, --enable-library-profiling + # Enable Library profiling + --disable-library-profiling # Disable Library profiling + --enable-shared # Enable Shared library + --disable-shared # Disable Shared library + --enable-static # Enable Static library + --disable-static # Disable Static library + --enable-library-bytecode # Enable Bytecode library + --disable-library-bytecode # Disable Bytecode library + --enable-executable-dynamic # Enable Executable dynamic linking + --disable-executable-dynamic # Disable Executable dynamic linking + --enable-executable-static # Enable Executable fully static linking + --disable-executable-static # Disable Executable fully static linking + --enable-profiling # Enable Executable and library profiling + --disable-profiling # Disable Executable and library profiling + --enable-profiling-shared # Enable Build profiling shared libraries + --disable-profiling-shared # Disable Build profiling shared libraries + --enable-executable-profiling + # Enable Executable profiling (DEPRECATED) + --disable-executable-profiling + # Disable Executable profiling (DEPRECATED) + --profiling-detail=level # Profiling detail level for executable and + library (default, none, exported-functions, + toplevel-functions, all-functions, late). + --library-profiling-detail=level + # Profiling detail level for libraries only. + -O[n], --enable-optimization[=n] + # Build with optimization (n is 0--2, default is + 1) + --disable-optimization # Build without optimization + --enable-debug-info[=n] # Emit debug info (n is 0--3, default is 0) + --disable-debug-info # Don't emit debug info + --enable-build-info # Enable build information generation during + project building + --disable-build-info # Disable build information generation during + project building + --enable-library-for-ghci # Enable compile library for use with GHCi + --disable-library-for-ghci # Disable compile library for use with GHCi + --enable-split-sections # Enable compile library code such that unneeded + definitions can be dropped from the final + executable (GHC 7.8+) + --disable-split-sections # Disable compile library code such that + unneeded definitions can be dropped from the + final executable (GHC 7.8+) + --enable-split-objs # Enable split library into smaller objects to + reduce binary sizes (GHC 6.6+) + --disable-split-objs # Disable split library into smaller objects to + reduce binary sizes (GHC 6.6+) + --enable-executable-stripping + # Enable strip executables upon installation to + reduce binary sizes + --disable-executable-stripping + # Disable strip executables upon installation to + reduce binary sizes + --enable-library-stripping # Enable strip libraries upon installation to + reduce binary sizes + --disable-library-stripping # Disable strip libraries upon installation to + reduce binary sizes + --configure-option=OPT # Extra option for configure + --user # Enable doing a per-user installation + --global # Disable doing a per-user installation + --package-db=DB # Append the given package database to the list + of package databases used (to satisfy + dependencies and register into). May be a + specific file, 'global' or 'user'. The initial + list is ['global'], ['global', 'user'], or + ['global', $sandbox], depending on context. + Use 'clear' to reset the list to empty. See + the user guide for details. + -f FLAGS or -fFLAGS, --flags=FLAGS + # Force values for the given flags in Cabal + conditionals in the .cabal file. E.g., + --flags="debug -usebytestrings" forces the + flag "debug" to true and "usebytestrings" to + false. + --extra-include-dirs=PATH # A list of directories to search for header + files + --enable-deterministic # Enable Try to be as deterministic as possible + (used by the test suite) + --disable-deterministic # Disable Try to be as deterministic as possible + (used by the test suite) + --ipid=IPID # Installed package ID to compile this package + as + --cid=CID # Installed component ID to compile this + component as + --extra-lib-dirs=PATH # A list of directories to search for external + libraries + --extra-lib-dirs-static=PATH # A list of directories to search for external + libraries when linking fully static + executables + --extra-framework-dirs=PATH # A list of directories to search for external + frameworks (OS X only) + --extra-prog-path=PATH # A list of directories to search for required + programs (in addition to the normal search + locations) + --instantiate-with=NAME=MOD # A mapping of signature names to concrete + module instantiations. + --enable-tests # Enable dependency checking and compilation for + test suites listed in the package description + file. + --disable-tests # Disable dependency checking and compilation + for test suites listed in the package + description file. + --enable-coverage # Enable build package with Haskell Program + Coverage. (GHC only) + --disable-coverage # Disable build package with Haskell Program + Coverage. (GHC only) + --enable-library-coverage # Enable build package with Haskell Program + Coverage. (GHC only) (DEPRECATED) + --disable-library-coverage # Disable build package with Haskell Program + Coverage. (GHC only) (DEPRECATED) + --enable-benchmarks # Enable dependency checking and compilation for + benchmarks listed in the package description + file. + --disable-benchmarks # Disable dependency checking and compilation + for benchmarks listed in the package + description file. + --enable-relocatable # Enable building a package that is relocatable. + (GHC only) + --disable-relocatable # Disable building a package that is + relocatable. (GHC only) + --disable-response-files # Enable workaround for old versions of programs + like "ar" that do not support @file arguments + --allow-depending-on-private-libs + # Allow depending on private libraries. If set, + the library visibility check MUST be done + externally. + --coverage-for=UNITID # A list of unit-ids of libraries to include in + the Haskell Program Coverage report. + --ignore-build-tools # Ignore build tool dependencies. If set, + declared build tools needn't be found for + compilation to proceed. + --with-PROG=PATH # Give the path to PROG + --PROG-option=OPT # Give an extra option to PROG (passed directly + to PROG as a single argument) + --PROG-options=OPTS # Give extra options to PROG (split on spaces, + use "" to prevent splitting) + --cabal-lib-version=VERSION # Select which version of the Cabal lib to use + to build packages (useful for testing). + --enable-append # Enable appending the new config to the old + config file + --disable-append # Disable appending the new config to the old + config file + --enable-backup # Enable the backup of the config file before + any alterations + --disable-backup # Disable the backup of the config file before + any alterations + -c CONSTRAINT or -cCONSTRAINT, --constraint=CONSTRAINT + # Specify constraints on a package (version, + installed/source, flags) + --preference=CONSTRAINT # Specify preferences (soft constraints) on the + version of a package + --solver=SOLVER # Select dependency solver to use (default: + modular). Choices: modular. + --allow-older[=DEPS] # Ignore lower bounds in all dependencies or + DEPS + --allow-newer[=DEPS] # Ignore upper bounds in all dependencies or + DEPS + --write-ghc-environment-files=always|never|ghc8.4.4+ + # Whether to create a .ghc.environment file + after a successful build (v2-build only) + --enable-documentation # Enable building of documentation + --disable-documentation # Disable building of documentation + --doc-index-file=TEMPLATE # A central index of haddock API documentation + (template cannot use $pkgid) + --dry-run # Do not install anything, only print what would + be installed. + --only-download # Do not build anything, only fetch the + packages. + --max-backjumps=NUM # Maximum number of backjumps allowed while + solving (default: 4000). Use a negative number + to enable unlimited backtracking. Use 0 to + disable backtracking completely. + --reorder-goals # Try to reorder goals according to certain + heuristics. Slows things down on average, but + may make backtracking faster for some + packages. + --count-conflicts # Try to speed up solving by preferring goals + that are involved in a lot of conflicts + (default). + --fine-grained-conflicts # Skip a version of a package if it does not + resolve the conflicts encountered in the last + version, as a solver optimization (default). + --minimize-conflict-set # When there is no solution, try to improve the + error message by finding a minimal conflict + set (default: false). May increase run time + significantly. + --independent-goals # Treat several goals on the command line as + independent. If several goals depend on the + same package, different versions can be + chosen. + --prefer-oldest # Prefer the oldest (instead of the latest) + versions of packages available. Useful to + determine lower bounds in the build-depends + section. + --prefer-version=oldest|latest|installed-or-latest + # Select which version of a package that the + solver should prefer. Oldest is useful to + determine lower bounds in build-depends + section. Latest will prefer the latest + version. Installed-or-latest will prefer + installed versions and the latest version + otherwise. + --shadow-installed-packages # If multiple package instances of the same + version are installed, treat all but one as + shadowed. + --strong-flags # Do not defer flag choices (this used to be the + default in cabal-install <= 1.20). + --allow-boot-library-installs + # Allow cabal to install base, ghc-prim, + integer-simple, integer-gmp, and + template-haskell. + --reject-unconstrained-dependencies=none|all + # Require these packages to have constraints on + them if they are to be selected (default: + none). + --reinstall # Install even if it means installing the same + version again. + --avoid-reinstalls # Do not select versions that would + destructively overwrite installed packages. + --force-reinstalls # Reinstall packages even if they will most + likely break other installed packages. + --upgrade-dependencies # Pick the latest version for all dependencies, + rather than trying to pick an installed + version. + --only-dependencies # Install only the dependencies necessary to + build the given packages + --dependencies-only # A synonym for --only-dependencies + --index-state=STATE # Use source package index state as it existed + at a previous time. Accepts unix-timestamps + (e.g. '@1474732068'), ISO8601 UTC timestamps + (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' + (default: 'HEAD'). + --root-cmd=COMMAND # (No longer supported, do not use.) + --build-summary=TEMPLATE # Save build summaries to file (name template + can use $pkgid, $compiler, $os, $arch) + --build-log=TEMPLATE # Log all builds to file (name template can use + $pkgid, $compiler, $os, $arch) + --remote-build-reporting=LEVEL + # Generate build reports to send to a remote + server (none, anonymous or detailed). + --report-planning-failure # Generate build reports when the dependency + solver fails. This is used by the Hackage + build bot. + --enable-per-component # Enable Per-component builds when possible + --disable-per-component # Disable Per-component builds when possible + --run-tests # Run package test suites during installation. + --semaphore # Use a semaphore so GHC can compile components + in parallel + -j[NUM], --jobs[=NUM] # Run NUM jobs simultaneously (or '$ncpus' if no + NUM is given). + --keep-going # After a build failure, continue to build other + unaffected packages. + --offline # Don't download packages from the Internet. + --build-timings # Print elapsed time for each build phase. + --haddock-hoogle # Generate a hoogle database + --haddock-html # Generate HTML documentation (the default) + --haddock-html-location=URL # Location of HTML documentation for + pre-requisite packages + --haddock-for-hackage # Collection of flags to generate documentation + suitable for upload to hackage + --haddock-executables # Run haddock for Executables targets + --haddock-tests # Run haddock for Test Suite targets + --haddock-benchmarks # Run haddock for Benchmark targets + --haddock-all # Run haddock for all targets + --haddock-internal # Run haddock for internal modules and include + all symbols + --haddock-css=PATH # Use PATH as the haddock stylesheet + --haddock-hyperlink-source # Hyperlink the documentation to the source code + --haddock-quickjump # Generate an index for interactive + documentation navigation + --haddock-hscolour-css=PATH # Use PATH as the HsColour stylesheet + --haddock-contents-location=URL + # Bake URL in as the location for the contents + page + --haddock-base-url=URL # Base URL for static files. + --haddock-resources-dir=DIR # Location of Haddocks static / auxiliary files + --haddock-output-dir=DIR # Generate haddock documentation into this + directory. This flag is provided as a + technology preview and is subject to change in + the next releases. + --haddock-use-unicode # Pass --use-unicode option to haddock + --test-log=TEMPLATE # Log all test suite results to file (name + template can use $pkgid, $compiler, $os, + $arch, $test-suite, $result) + --test-machine-log=TEMPLATE # Produce a machine-readable log file (name + template can use $pkgid, $compiler, $os, + $arch, $result) + --test-show-details=FILTER # 'always': always show results of individual + test cases. 'never': never show results of + individual test cases. 'failures': show + results of failing test cases. 'streaming': + show results of test cases in real + time.'direct': send results of test cases in + real time; no log file. + --test-keep-tix-files # Keep .tix files for HPC between test runs + --test-wrapper=FILE # Run test through a wrapper. + --test-fail-when-no-test-suites + # Exit with failure when no test suites are + found. + --test-options=TEMPLATES # Give extra options to test executables (split + on spaces, use "" to prevent splitting; name + templates can use $pkgid, $compiler, $os, + $arch, $test-suite) + --test-option=TEMPLATE # Give extra option to test executables (passed + directly as a single argument; name template + can use $pkgid, $compiler, $os, $arch, + $test-suite) + --benchmark-options=TEMPLATES + # Give extra options to benchmark executables + (split on spaces, use "" to prevent splitting; + name templates can use $pkgid, $compiler, $os, + $arch, $benchmark) + --benchmark-option=TEMPLATE # Give extra option to benchmark executables + (passed directly as a single argument; name + template can use $pkgid, $compiler, $os, + $arch, $benchmark) + --project-dir=DIR # Set the path of the project directory + --project-file=FILE # Set the path of the cabal.project file + (relative to the project directory when + relative) + -z, --ignore-project # Ignore local project configuration (unless + --project-dir or --project-file is also set) + --project-file-parser=PARSER # Set the parser to use for the project file + --open # Open generated documentation in the browser + +Examples: + cabal haddock pkgname Build documentation for the package named pkgname diff --git a/doc/cmd-v2-help/help.txt b/doc/cmd-v2-help/help.txt new file mode 100644 index 00000000000..dba7ffe6948 --- /dev/null +++ b/doc/cmd-v2-help/help.txt @@ -0,0 +1,115 @@ +Command line interface to the Haskell Cabal infrastructure. + +See http://www.haskell.org/cabal/ for more information. + +Usage: cabal [GLOBAL FLAGS] [COMMAND [FLAGS]] + +Commands: + [global] + user-config Display and update the user's global cabal configuration. + help Help about commands. + + [package database] + update Updates list of known packages. + list List packages matching a search string. + info Display detailed information about a particular package. + + [initialization and download] + init Create a new cabal package. + fetch Downloads packages for later installation. + get Download/Extract a package's source code (repository). + + [project configuration] + configure Add extra project configuration. + freeze Freeze dependencies. + gen-bounds Generate dependency bounds for packages in the project. + outdated Check for outdated dependencies. + path Query for simple project information. + target Target a subset of all targets. + + [project building and installing] + build Compile targets within the project. + install Install packages. + haddock Build Haddock documentation. + haddock-project Generate Haddocks HTML documentation for the cabal project. + clean Clean the package store and remove temporary files. + + [running and testing] + list-bin List the path to a single executable. + repl Open an interactive session for the given component. + run Run an executable. + bench Run benchmarks. + test Run test-suites. + exec Give a command access to the store. + + [sanity checks and shipping] + check Check the package for common mistakes. + sdist Generate a source distribution file (.tar.gz). + upload Uploads source packages or documentation to Hackage. + report Upload build reports to a remote server. + + [deprecated] + unpack Deprecated alias for 'get'. + hscolour Generate HsColour colourised code, in HTML format. + + [new-style projects (forwards-compatible aliases)] + v2-target Target a subset of all targets. + v2-build Compile targets within the project. + v2-configure Add extra project configuration. + v2-repl Open an interactive session for the given component. + v2-run Run an executable. + v2-test Run test-suites. + v2-bench Run benchmarks. + v2-freeze Freeze dependencies. + v2-haddock Build Haddock documentation. + v2-exec Give a command access to the store. + v2-update Updates list of known packages. + v2-install Install packages. + v2-clean Clean the package store and remove temporary files. + v2-sdist Generate a source distribution file (.tar.gz). + v2-outdated Check for outdated dependencies. + v2-gen-bounds Generate dependency bounds for packages in the project. + + [legacy command aliases] + v1-build Compile all/specific components. + v1-configure Prepare to build the package. + v1-repl Open an interpreter session for the given component. + v1-run Builds and runs an executable. + v1-test Run all/specific tests in the test suite. + v1-bench Run all/specific benchmarks. + v1-freeze Freeze dependencies. + v1-haddock Generate Haddock HTML documentation. + v1-install Install packages. + v1-clean Clean up after a build. + v1-copy Copy the files of all/specific components to install locations. + v1-register Register this package with the compiler. + v1-reconfigure Reconfigure the package if necessary. + v1-gen-bounds Generate dependency bounds. + +For more information about a command use: + cabal COMMAND --help +or cabal help COMMAND + +To install Cabal packages from hackage use: + cabal install foo [--dry-run] + +Occasionally you need to update the list of available packages: + cabal update + +Global flags: + -h, --help # Show this help text + -V, --version # Print version information + --full-version # Print full version information with git + revision (if available) and compiler + --numeric-version # Print just the version number + --config-file=FILE # Set an alternate location for the config file + --ignore-expiry # Ignore expiry dates on signed metadata (use + only in exceptional circumstances) + --http-transport=HttpTransport + # Set a transport for http(s) requests. Accepts + 'curl', 'wget', 'powershell', and + 'plain-http'. (default: 'curl') + --store-dir=DIR # The location of the build store + --active-repositories=REPOS # The active package repositories (set to + ':none' to disable all repositories) + diff --git a/doc/cmd-v2-help/hscolour.txt b/doc/cmd-v2-help/hscolour.txt new file mode 100644 index 00000000000..f307d39229a --- /dev/null +++ b/doc/cmd-v2-help/hscolour.txt @@ -0,0 +1,22 @@ +Generate HsColour colourised code, in HTML format. + +Usage: cabal hscolour [FLAGS] + +Requires the hscolour program. + +Flags for hscolour: + -h, --help # Show this help text + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + --builddir=DIR # The directory where Cabal puts generated build + files (default dist) + --cabal-file=PATH # use this Cabal file + --keep-temp-files # Keep temporary files. + --executables # Run hscolour for Executables targets + --tests # Run hscolour for Test Suite targets + --benchmarks # Run hscolour for Benchmark targets + --foreign-libraries # Run hscolour for Foreign Library targets + --all # Run hscolour for all targets + --css=PATH # Use a cascading style sheet + +Deprecated in favour of 'cabal haddock --hyperlink-source'. diff --git a/doc/cmd-v2-help/info.txt b/doc/cmd-v2-help/info.txt new file mode 100644 index 00000000000..ba42007ac1a --- /dev/null +++ b/doc/cmd-v2-help/info.txt @@ -0,0 +1,18 @@ +Display detailed information about a particular package. + +Usage: cabal info [FLAGS] PACKAGES + +Use the package database specified with --package-db. If not specified, use +the user package database. + +Flags for info: + -h, --help # Show this help text + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + --package-db=DB # Append the given package database to the list + of package databases used (to satisfy + dependencies and register into). May be a + specific file, 'global' or 'user'. The initial + list is ['global'], ['global', 'user'], + depending on context. Use 'clear' to reset the + list to empty. See the user guide for details. diff --git a/doc/cmd-v2-help/init.txt b/doc/cmd-v2-help/init.txt new file mode 100644 index 00000000000..d1d1a35f140 --- /dev/null +++ b/doc/cmd-v2-help/init.txt @@ -0,0 +1,87 @@ +Create a new cabal package. + +Usage: cabal init [PROJECT ROOT] [FLAGS] + +Create a .cabal, CHANGELOG.md, minimal initial Haskell code and optionally a +LICENSE file. + +Calling init with no arguments runs interactive mode by default, which will +try to guess as much as possible and prompt you for the rest. +Non-interactive mode can be invoked by the -n/--non-interactive flag, which +will let you specify the options via flags and will either use the defaults +for the rest, or attempt to infer sensible defaults from your local +development environment (e.g. $PATH). +For a basic simple project with minimal prompting and sensible defaults, issue +the --simple flag. + +Flags for init: + -h, --help # Show this help text + -i, --interactive # Enable Interactive mode. Creates a prompt tree + for project creation. If -n/--non-interactive + is issued, a simple project with inferred + defaults is created. If --simple is issued, + then sensible defaults will be chosen as well. + -n, --non-interactive # Disable Interactive mode. Creates a prompt + tree for project creation. If + -n/--non-interactive is issued, a simple + project with inferred defaults is created. If + --simple is issued, then sensible defaults + will be chosen as well. + -q, --quiet # Do not generate log messages to stdout. + --no-comments # Do not generate explanatory comments in the + .cabal file. + -m, --minimal # Generate a minimal .cabal file, that is, do + not include extra empty fields. Also implies + --no-comments. + --overwrite # Overwrite any existing .cabal, LICENSE, or + Setup.hs files without warning. + --package-dir=DIRECTORY # Root directory of the package (default = + current directory). + -p PACKAGE or -pPACKAGE, --package-name=PACKAGE + # Name of the Cabal package to create. + --version=VERSION # Initial version of the package. + --cabal-version=CABALSPECVERSION + # Version of the Cabal specification. + -l LICENSE or -lLICENSE, --license=LICENSE + # Project license. + -a NAME or -aNAME, --author=NAME + # Name of the project's author. + -e EMAIL or -eEMAIL, --email=EMAIL + # Email address of the maintainer. + -u URL or -uURL, --homepage=URL + # Project homepage and/or repository. + -s TEXT or -sTEXT, --synopsis=TEXT + # Short project synopsis. + -c CATEGORY or -cCATEGORY, --category=CATEGORY + # Project category. + -x FILE or -xFILE, --extra-source-file=FILE + # Extra source file to be distributed with + tarball. + --extra-doc-file=FILE # Extra doc file to be distributed with tarball. + --lib # Build a library. + --exe # Build an executable. + --libandexe # Build a library and an executable. + --tests # Generate a test suite, standalone or for a + library. + --test-dir=DIR # Directory containing tests. + --simple # Create a simple project with sensible + defaults. + --main-is=FILE # Specify the main module. + --language=LANGUAGE # Specify the default language. + -o MODULE or -oMODULE, --expose-module=MODULE + # Export a module from the package. + --extension=EXTENSION # Use a LANGUAGE extension (in the + other-extensions field). + -d DEPENDENCIES or -dDEPENDENCIES, --dependency=DEPENDENCIES + # Package dependencies. Permits comma separated + list of dependencies. + --application-dir=DIR # Directory containing package application + executable. + --source-dir=DIR # Directory containing package library source. + --build-tool=TOOL # Required external build tool. + -w PATH or -wPATH, --with-compiler=PATH + # Give the path to a particular compiler. For + 'init', this flag is used to set the bounds + inferred for the 'base' package. + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) diff --git a/doc/cmd-v2-help/install.txt b/doc/cmd-v2-help/install.txt new file mode 100644 index 00000000000..8850a2a2890 --- /dev/null +++ b/doc/cmd-v2-help/install.txt @@ -0,0 +1,375 @@ +Install packages. + +Usage: cabal install [TARGETS] [FLAGS] + +Installs one or more packages. This is done by installing them in the store +and symlinking or copying the executables in the directory specified by the +--installdir flag (`~/.local/bin/` by default). If you want the installed +executables to be available globally, make sure that the PATH environment +variable contains that directory. + +If TARGET is a library and --lib (provisional) is used, it will be added to +the global environment. When doing this, cabal will try to build a plan that +includes all the previously installed libraries. This is currently not +implemented. + +Flags for install: + -h, --help # Show this help text + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + --builddir=DIR # The directory where Cabal puts generated build + files (default dist) + --keep-temp-files # Keep temporary files. + -g, --ghc # Compile with GHC + --ghcjs # Compile with GHCJS + --uhc # Compile with UHC + -w PATH or -wPATH, --with-compiler=PATH + # Give the path to a particular compiler + --with-hc-pkg=PATH # Give the path to the package tool + --program-prefix=PREFIX # Prefix to be applied to installed executables + --program-suffix=SUFFIX # Suffix to be applied to installed executables + --enable-library-vanilla # Enable Vanilla libraries + --disable-library-vanilla # Disable Vanilla libraries + -p, --enable-library-profiling + # Enable Library profiling + --disable-library-profiling # Disable Library profiling + --enable-shared # Enable Shared library + --disable-shared # Disable Shared library + --enable-static # Enable Static library + --disable-static # Disable Static library + --enable-library-bytecode # Enable Bytecode library + --disable-library-bytecode # Disable Bytecode library + --enable-executable-dynamic # Enable Executable dynamic linking + --disable-executable-dynamic # Disable Executable dynamic linking + --enable-executable-static # Enable Executable fully static linking + --disable-executable-static # Disable Executable fully static linking + --enable-profiling # Enable Executable and library profiling + --disable-profiling # Disable Executable and library profiling + --enable-profiling-shared # Enable Build profiling shared libraries + --disable-profiling-shared # Disable Build profiling shared libraries + --enable-executable-profiling + # Enable Executable profiling (DEPRECATED) + --disable-executable-profiling + # Disable Executable profiling (DEPRECATED) + --profiling-detail=level # Profiling detail level for executable and + library (default, none, exported-functions, + toplevel-functions, all-functions, late). + --library-profiling-detail=level + # Profiling detail level for libraries only. + -O[n], --enable-optimization[=n] + # Build with optimization (n is 0--2, default is + 1) + --disable-optimization # Build without optimization + --enable-debug-info[=n] # Emit debug info (n is 0--3, default is 0) + --disable-debug-info # Don't emit debug info + --enable-build-info # Enable build information generation during + project building + --disable-build-info # Disable build information generation during + project building + --enable-library-for-ghci # Enable compile library for use with GHCi + --disable-library-for-ghci # Disable compile library for use with GHCi + --enable-split-sections # Enable compile library code such that unneeded + definitions can be dropped from the final + executable (GHC 7.8+) + --disable-split-sections # Disable compile library code such that + unneeded definitions can be dropped from the + final executable (GHC 7.8+) + --enable-split-objs # Enable split library into smaller objects to + reduce binary sizes (GHC 6.6+) + --disable-split-objs # Disable split library into smaller objects to + reduce binary sizes (GHC 6.6+) + --enable-executable-stripping + # Enable strip executables upon installation to + reduce binary sizes + --disable-executable-stripping + # Disable strip executables upon installation to + reduce binary sizes + --enable-library-stripping # Enable strip libraries upon installation to + reduce binary sizes + --disable-library-stripping # Disable strip libraries upon installation to + reduce binary sizes + --configure-option=OPT # Extra option for configure + --user # Enable doing a per-user installation + --global # Disable doing a per-user installation + --package-db=DB # Append the given package database to the list + of package databases used (to satisfy + dependencies and register into). May be a + specific file, 'global' or 'user'. The initial + list is ['global'], ['global', 'user'], or + ['global', $sandbox], depending on context. + Use 'clear' to reset the list to empty. See + the user guide for details. + -f FLAGS or -fFLAGS, --flags=FLAGS + # Force values for the given flags in Cabal + conditionals in the .cabal file. E.g., + --flags="debug -usebytestrings" forces the + flag "debug" to true and "usebytestrings" to + false. + --extra-include-dirs=PATH # A list of directories to search for header + files + --enable-deterministic # Enable Try to be as deterministic as possible + (used by the test suite) + --disable-deterministic # Disable Try to be as deterministic as possible + (used by the test suite) + --ipid=IPID # Installed package ID to compile this package + as + --cid=CID # Installed component ID to compile this + component as + --extra-lib-dirs=PATH # A list of directories to search for external + libraries + --extra-lib-dirs-static=PATH # A list of directories to search for external + libraries when linking fully static + executables + --extra-framework-dirs=PATH # A list of directories to search for external + frameworks (OS X only) + --extra-prog-path=PATH # A list of directories to search for required + programs (in addition to the normal search + locations) + --instantiate-with=NAME=MOD # A mapping of signature names to concrete + module instantiations. + --enable-tests # Enable dependency checking and compilation for + test suites listed in the package description + file. + --disable-tests # Disable dependency checking and compilation + for test suites listed in the package + description file. + --enable-coverage # Enable build package with Haskell Program + Coverage. (GHC only) + --disable-coverage # Disable build package with Haskell Program + Coverage. (GHC only) + --enable-library-coverage # Enable build package with Haskell Program + Coverage. (GHC only) (DEPRECATED) + --disable-library-coverage # Disable build package with Haskell Program + Coverage. (GHC only) (DEPRECATED) + --enable-benchmarks # Enable dependency checking and compilation for + benchmarks listed in the package description + file. + --disable-benchmarks # Disable dependency checking and compilation + for benchmarks listed in the package + description file. + --enable-relocatable # Enable building a package that is relocatable. + (GHC only) + --disable-relocatable # Disable building a package that is + relocatable. (GHC only) + --disable-response-files # Enable workaround for old versions of programs + like "ar" that do not support @file arguments + --allow-depending-on-private-libs + # Allow depending on private libraries. If set, + the library visibility check MUST be done + externally. + --coverage-for=UNITID # A list of unit-ids of libraries to include in + the Haskell Program Coverage report. + --ignore-build-tools # Ignore build tool dependencies. If set, + declared build tools needn't be found for + compilation to proceed. + --with-PROG=PATH # Give the path to PROG + --PROG-option=OPT # Give an extra option to PROG (passed directly + to PROG as a single argument) + --PROG-options=OPTS # Give extra options to PROG (split on spaces, + use "" to prevent splitting) + --cabal-lib-version=VERSION # Select which version of the Cabal lib to use + to build packages (useful for testing). + --enable-append # Enable appending the new config to the old + config file + --disable-append # Disable appending the new config to the old + config file + --enable-backup # Enable the backup of the config file before + any alterations + --disable-backup # Disable the backup of the config file before + any alterations + -c CONSTRAINT or -cCONSTRAINT, --constraint=CONSTRAINT + # Specify constraints on a package (version, + installed/source, flags) + --preference=CONSTRAINT # Specify preferences (soft constraints) on the + version of a package + --solver=SOLVER # Select dependency solver to use (default: + modular). Choices: modular. + --allow-older[=DEPS] # Ignore lower bounds in all dependencies or + DEPS + --allow-newer[=DEPS] # Ignore upper bounds in all dependencies or + DEPS + --write-ghc-environment-files=always|never|ghc8.4.4+ + # Whether to create a .ghc.environment file + after a successful build (v2-build only) + --enable-documentation # Enable building of documentation + --disable-documentation # Disable building of documentation + --doc-index-file=TEMPLATE # A central index of haddock API documentation + (template cannot use $pkgid) + --dry-run # Do not install anything, only print what would + be installed. + --only-download # Do not build anything, only fetch the + packages. + --max-backjumps=NUM # Maximum number of backjumps allowed while + solving (default: 4000). Use a negative number + to enable unlimited backtracking. Use 0 to + disable backtracking completely. + --reorder-goals # Try to reorder goals according to certain + heuristics. Slows things down on average, but + may make backtracking faster for some + packages. + --count-conflicts # Try to speed up solving by preferring goals + that are involved in a lot of conflicts + (default). + --fine-grained-conflicts # Skip a version of a package if it does not + resolve the conflicts encountered in the last + version, as a solver optimization (default). + --minimize-conflict-set # When there is no solution, try to improve the + error message by finding a minimal conflict + set (default: false). May increase run time + significantly. + --independent-goals # Treat several goals on the command line as + independent. If several goals depend on the + same package, different versions can be + chosen. + --prefer-oldest # Prefer the oldest (instead of the latest) + versions of packages available. Useful to + determine lower bounds in the build-depends + section. + --prefer-version=oldest|latest|installed-or-latest + # Select which version of a package that the + solver should prefer. Oldest is useful to + determine lower bounds in build-depends + section. Latest will prefer the latest + version. Installed-or-latest will prefer + installed versions and the latest version + otherwise. + --shadow-installed-packages # If multiple package instances of the same + version are installed, treat all but one as + shadowed. + --strong-flags # Do not defer flag choices (this used to be the + default in cabal-install <= 1.20). + --allow-boot-library-installs + # Allow cabal to install base, ghc-prim, + integer-simple, integer-gmp, and + template-haskell. + --reject-unconstrained-dependencies=none|all + # Require these packages to have constraints on + them if they are to be selected (default: + none). + --reinstall # Install even if it means installing the same + version again. + --avoid-reinstalls # Do not select versions that would + destructively overwrite installed packages. + --force-reinstalls # Reinstall packages even if they will most + likely break other installed packages. + --upgrade-dependencies # Pick the latest version for all dependencies, + rather than trying to pick an installed + version. + --only-dependencies # Install only the dependencies necessary to + build the given packages + --dependencies-only # A synonym for --only-dependencies + --index-state=STATE # Use source package index state as it existed + at a previous time. Accepts unix-timestamps + (e.g. '@1474732068'), ISO8601 UTC timestamps + (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' + (default: 'HEAD'). + --root-cmd=COMMAND # (No longer supported, do not use.) + --build-summary=TEMPLATE # Save build summaries to file (name template + can use $pkgid, $compiler, $os, $arch) + --build-log=TEMPLATE # Log all builds to file (name template can use + $pkgid, $compiler, $os, $arch) + --remote-build-reporting=LEVEL + # Generate build reports to send to a remote + server (none, anonymous or detailed). + --report-planning-failure # Generate build reports when the dependency + solver fails. This is used by the Hackage + build bot. + --enable-per-component # Enable Per-component builds when possible + --disable-per-component # Disable Per-component builds when possible + --run-tests # Run package test suites during installation. + --semaphore # Use a semaphore so GHC can compile components + in parallel + -j[NUM], --jobs[=NUM] # Run NUM jobs simultaneously (or '$ncpus' if no + NUM is given). + --keep-going # After a build failure, continue to build other + unaffected packages. + --offline # Don't download packages from the Internet. + --build-timings # Print elapsed time for each build phase. + --haddock-hoogle # Generate a hoogle database + --haddock-html # Generate HTML documentation (the default) + --haddock-html-location=URL # Location of HTML documentation for + pre-requisite packages + --haddock-for-hackage # Collection of flags to generate documentation + suitable for upload to hackage + --haddock-executables # Run haddock for Executables targets + --haddock-tests # Run haddock for Test Suite targets + --haddock-benchmarks # Run haddock for Benchmark targets + --haddock-all # Run haddock for all targets + --haddock-internal # Run haddock for internal modules and include + all symbols + --haddock-css=PATH # Use PATH as the haddock stylesheet + --haddock-hyperlink-source # Hyperlink the documentation to the source code + --haddock-quickjump # Generate an index for interactive + documentation navigation + --haddock-hscolour-css=PATH # Use PATH as the HsColour stylesheet + --haddock-contents-location=URL + # Bake URL in as the location for the contents + page + --haddock-base-url=URL # Base URL for static files. + --haddock-resources-dir=DIR # Location of Haddocks static / auxiliary files + --haddock-output-dir=DIR # Generate haddock documentation into this + directory. This flag is provided as a + technology preview and is subject to change in + the next releases. + --haddock-use-unicode # Pass --use-unicode option to haddock + --test-log=TEMPLATE # Log all test suite results to file (name + template can use $pkgid, $compiler, $os, + $arch, $test-suite, $result) + --test-machine-log=TEMPLATE # Produce a machine-readable log file (name + template can use $pkgid, $compiler, $os, + $arch, $result) + --test-show-details=FILTER # 'always': always show results of individual + test cases. 'never': never show results of + individual test cases. 'failures': show + results of failing test cases. 'streaming': + show results of test cases in real + time.'direct': send results of test cases in + real time; no log file. + --test-keep-tix-files # Keep .tix files for HPC between test runs + --test-wrapper=FILE # Run test through a wrapper. + --test-fail-when-no-test-suites + # Exit with failure when no test suites are + found. + --test-options=TEMPLATES # Give extra options to test executables (split + on spaces, use "" to prevent splitting; name + templates can use $pkgid, $compiler, $os, + $arch, $test-suite) + --test-option=TEMPLATE # Give extra option to test executables (passed + directly as a single argument; name template + can use $pkgid, $compiler, $os, $arch, + $test-suite) + --benchmark-options=TEMPLATES + # Give extra options to benchmark executables + (split on spaces, use "" to prevent splitting; + name templates can use $pkgid, $compiler, $os, + $arch, $benchmark) + --benchmark-option=TEMPLATE # Give extra option to benchmark executables + (passed directly as a single argument; name + template can use $pkgid, $compiler, $os, + $arch, $benchmark) + --project-dir=DIR # Set the path of the project directory + --project-file=FILE # Set the path of the cabal.project file + (relative to the project directory when + relative) + -z, --ignore-project # Ignore local project configuration (unless + --project-dir or --project-file is also set) + --project-file-parser=PARSER # Set the parser to use for the project file + --lib # Install libraries rather than executables from + the target package (provisional, see + https://github.com/haskell/cabal/issues/6481 + for more information). + --package-env=ENV # Set the environment file that may be modified. + --overwrite-policy=always|never|prompt + # How to handle already existing symlinks. + --install-method=default|copy|symlink + # How to install the executables. + --installdir=DIR # Where to install (by symlinking or copying) + the executables in. + +Examples: + cabal install + Install the package in the current directory + cabal install pkgname + Install the package named pkgname (fetching it from hackage if necessary) + cabal install ./pkgfoo + Install the package in the ./pkgfoo directory diff --git a/doc/cmd-v2-help/list-bin.txt b/doc/cmd-v2-help/list-bin.txt new file mode 100644 index 00000000000..3b8b8f01156 --- /dev/null +++ b/doc/cmd-v2-help/list-bin.txt @@ -0,0 +1,365 @@ +List the path to a single executable. + +Usage: cabal list-bin [FLAGS] TARGET + +List the path to a build product. + +Flags for list-bin: + -h, --help # Show this help text + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + --builddir=DIR # The directory where Cabal puts generated build + files (default dist) + --keep-temp-files # Keep temporary files. + -g, --ghc # Compile with GHC + --ghcjs # Compile with GHCJS + --uhc # Compile with UHC + -w PATH or -wPATH, --with-compiler=PATH + # Give the path to a particular compiler + --with-hc-pkg=PATH # Give the path to the package tool + --prefix=DIR # Bake this prefix in preparation of + installation + --bindir=DIR # Installation directory for executables + --libdir=DIR # Installation directory for libraries + --libsubdir=DIR # Subdirectory of libdir in which libs are + installed + --dynlibdir=DIR # Installation directory for dynamic libraries + --bytecodelibdir=DIR # Installation directory for bytecode libraries + --libexecdir=DIR # Installation directory for program executables + --libexecsubdir=DIR # Subdirectory of libexecdir in which private + executables are installed + --datadir=DIR # Installation directory for read-only data + --datasubdir=DIR # Subdirectory of datadir in which data files + are installed + --docdir=DIR # Installation directory for documentation + --htmldir=DIR # Installation directory for HTML documentation + --haddockdir=DIR # Installation directory for haddock interfaces + --sysconfdir=DIR # Installation directory for configuration files + --program-prefix=PREFIX # Prefix to be applied to installed executables + --program-suffix=SUFFIX # Suffix to be applied to installed executables + --enable-library-vanilla # Enable Vanilla libraries + --disable-library-vanilla # Disable Vanilla libraries + -p, --enable-library-profiling + # Enable Library profiling + --disable-library-profiling # Disable Library profiling + --enable-shared # Enable Shared library + --disable-shared # Disable Shared library + --enable-static # Enable Static library + --disable-static # Disable Static library + --enable-library-bytecode # Enable Bytecode library + --disable-library-bytecode # Disable Bytecode library + --enable-executable-dynamic # Enable Executable dynamic linking + --disable-executable-dynamic # Disable Executable dynamic linking + --enable-executable-static # Enable Executable fully static linking + --disable-executable-static # Disable Executable fully static linking + --enable-profiling # Enable Executable and library profiling + --disable-profiling # Disable Executable and library profiling + --enable-profiling-shared # Enable Build profiling shared libraries + --disable-profiling-shared # Disable Build profiling shared libraries + --enable-executable-profiling + # Enable Executable profiling (DEPRECATED) + --disable-executable-profiling + # Disable Executable profiling (DEPRECATED) + --profiling-detail=level # Profiling detail level for executable and + library (default, none, exported-functions, + toplevel-functions, all-functions, late). + --library-profiling-detail=level + # Profiling detail level for libraries only. + -O[n], --enable-optimization[=n] + # Build with optimization (n is 0--2, default is + 1) + --disable-optimization # Build without optimization + --enable-debug-info[=n] # Emit debug info (n is 0--3, default is 0) + --disable-debug-info # Don't emit debug info + --enable-build-info # Enable build information generation during + project building + --disable-build-info # Disable build information generation during + project building + --enable-library-for-ghci # Enable compile library for use with GHCi + --disable-library-for-ghci # Disable compile library for use with GHCi + --enable-split-sections # Enable compile library code such that unneeded + definitions can be dropped from the final + executable (GHC 7.8+) + --disable-split-sections # Disable compile library code such that + unneeded definitions can be dropped from the + final executable (GHC 7.8+) + --enable-split-objs # Enable split library into smaller objects to + reduce binary sizes (GHC 6.6+) + --disable-split-objs # Disable split library into smaller objects to + reduce binary sizes (GHC 6.6+) + --enable-executable-stripping + # Enable strip executables upon installation to + reduce binary sizes + --disable-executable-stripping + # Disable strip executables upon installation to + reduce binary sizes + --enable-library-stripping # Enable strip libraries upon installation to + reduce binary sizes + --disable-library-stripping # Disable strip libraries upon installation to + reduce binary sizes + --configure-option=OPT # Extra option for configure + --user # Enable doing a per-user installation + --global # Disable doing a per-user installation + --package-db=DB # Append the given package database to the list + of package databases used (to satisfy + dependencies and register into). May be a + specific file, 'global' or 'user'. The initial + list is ['global'], ['global', 'user'], or + ['global', $sandbox], depending on context. + Use 'clear' to reset the list to empty. See + the user guide for details. + -f FLAGS or -fFLAGS, --flags=FLAGS + # Force values for the given flags in Cabal + conditionals in the .cabal file. E.g., + --flags="debug -usebytestrings" forces the + flag "debug" to true and "usebytestrings" to + false. + --extra-include-dirs=PATH # A list of directories to search for header + files + --enable-deterministic # Enable Try to be as deterministic as possible + (used by the test suite) + --disable-deterministic # Disable Try to be as deterministic as possible + (used by the test suite) + --ipid=IPID # Installed package ID to compile this package + as + --cid=CID # Installed component ID to compile this + component as + --extra-lib-dirs=PATH # A list of directories to search for external + libraries + --extra-lib-dirs-static=PATH # A list of directories to search for external + libraries when linking fully static + executables + --extra-framework-dirs=PATH # A list of directories to search for external + frameworks (OS X only) + --extra-prog-path=PATH # A list of directories to search for required + programs (in addition to the normal search + locations) + --instantiate-with=NAME=MOD # A mapping of signature names to concrete + module instantiations. + --enable-tests # Enable dependency checking and compilation for + test suites listed in the package description + file. + --disable-tests # Disable dependency checking and compilation + for test suites listed in the package + description file. + --enable-coverage # Enable build package with Haskell Program + Coverage. (GHC only) + --disable-coverage # Disable build package with Haskell Program + Coverage. (GHC only) + --enable-library-coverage # Enable build package with Haskell Program + Coverage. (GHC only) (DEPRECATED) + --disable-library-coverage # Disable build package with Haskell Program + Coverage. (GHC only) (DEPRECATED) + --enable-benchmarks # Enable dependency checking and compilation for + benchmarks listed in the package description + file. + --disable-benchmarks # Disable dependency checking and compilation + for benchmarks listed in the package + description file. + --enable-relocatable # Enable building a package that is relocatable. + (GHC only) + --disable-relocatable # Disable building a package that is + relocatable. (GHC only) + --disable-response-files # Enable workaround for old versions of programs + like "ar" that do not support @file arguments + --allow-depending-on-private-libs + # Allow depending on private libraries. If set, + the library visibility check MUST be done + externally. + --coverage-for=UNITID # A list of unit-ids of libraries to include in + the Haskell Program Coverage report. + --ignore-build-tools # Ignore build tool dependencies. If set, + declared build tools needn't be found for + compilation to proceed. + --with-PROG=PATH # Give the path to PROG + --PROG-option=OPT # Give an extra option to PROG (passed directly + to PROG as a single argument) + --PROG-options=OPTS # Give extra options to PROG (split on spaces, + use "" to prevent splitting) + --cabal-lib-version=VERSION # Select which version of the Cabal lib to use + to build packages (useful for testing). + --enable-append # Enable appending the new config to the old + config file + --disable-append # Disable appending the new config to the old + config file + --enable-backup # Enable the backup of the config file before + any alterations + --disable-backup # Disable the backup of the config file before + any alterations + -c CONSTRAINT or -cCONSTRAINT, --constraint=CONSTRAINT + # Specify constraints on a package (version, + installed/source, flags) + --preference=CONSTRAINT # Specify preferences (soft constraints) on the + version of a package + --solver=SOLVER # Select dependency solver to use (default: + modular). Choices: modular. + --allow-older[=DEPS] # Ignore lower bounds in all dependencies or + DEPS + --allow-newer[=DEPS] # Ignore upper bounds in all dependencies or + DEPS + --write-ghc-environment-files=always|never|ghc8.4.4+ + # Whether to create a .ghc.environment file + after a successful build (v2-build only) + --enable-documentation # Enable building of documentation + --disable-documentation # Disable building of documentation + --doc-index-file=TEMPLATE # A central index of haddock API documentation + (template cannot use $pkgid) + --dry-run # Do not install anything, only print what would + be installed. + --only-download # Do not build anything, only fetch the + packages. + --max-backjumps=NUM # Maximum number of backjumps allowed while + solving (default: 4000). Use a negative number + to enable unlimited backtracking. Use 0 to + disable backtracking completely. + --reorder-goals # Try to reorder goals according to certain + heuristics. Slows things down on average, but + may make backtracking faster for some + packages. + --count-conflicts # Try to speed up solving by preferring goals + that are involved in a lot of conflicts + (default). + --fine-grained-conflicts # Skip a version of a package if it does not + resolve the conflicts encountered in the last + version, as a solver optimization (default). + --minimize-conflict-set # When there is no solution, try to improve the + error message by finding a minimal conflict + set (default: false). May increase run time + significantly. + --independent-goals # Treat several goals on the command line as + independent. If several goals depend on the + same package, different versions can be + chosen. + --prefer-oldest # Prefer the oldest (instead of the latest) + versions of packages available. Useful to + determine lower bounds in the build-depends + section. + --prefer-version=oldest|latest|installed-or-latest + # Select which version of a package that the + solver should prefer. Oldest is useful to + determine lower bounds in build-depends + section. Latest will prefer the latest + version. Installed-or-latest will prefer + installed versions and the latest version + otherwise. + --shadow-installed-packages # If multiple package instances of the same + version are installed, treat all but one as + shadowed. + --strong-flags # Do not defer flag choices (this used to be the + default in cabal-install <= 1.20). + --allow-boot-library-installs + # Allow cabal to install base, ghc-prim, + integer-simple, integer-gmp, and + template-haskell. + --reject-unconstrained-dependencies=none|all + # Require these packages to have constraints on + them if they are to be selected (default: + none). + --reinstall # Install even if it means installing the same + version again. + --avoid-reinstalls # Do not select versions that would + destructively overwrite installed packages. + --force-reinstalls # Reinstall packages even if they will most + likely break other installed packages. + --upgrade-dependencies # Pick the latest version for all dependencies, + rather than trying to pick an installed + version. + --only-dependencies # Install only the dependencies necessary to + build the given packages + --dependencies-only # A synonym for --only-dependencies + --index-state=STATE # Use source package index state as it existed + at a previous time. Accepts unix-timestamps + (e.g. '@1474732068'), ISO8601 UTC timestamps + (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' + (default: 'HEAD'). + --root-cmd=COMMAND # (No longer supported, do not use.) + --build-summary=TEMPLATE # Save build summaries to file (name template + can use $pkgid, $compiler, $os, $arch) + --build-log=TEMPLATE # Log all builds to file (name template can use + $pkgid, $compiler, $os, $arch) + --remote-build-reporting=LEVEL + # Generate build reports to send to a remote + server (none, anonymous or detailed). + --report-planning-failure # Generate build reports when the dependency + solver fails. This is used by the Hackage + build bot. + --enable-per-component # Enable Per-component builds when possible + --disable-per-component # Disable Per-component builds when possible + --run-tests # Run package test suites during installation. + --semaphore # Use a semaphore so GHC can compile components + in parallel + -j[NUM], --jobs[=NUM] # Run NUM jobs simultaneously (or '$ncpus' if no + NUM is given). + --keep-going # After a build failure, continue to build other + unaffected packages. + --offline # Don't download packages from the Internet. + --build-timings # Print elapsed time for each build phase. + --haddock-hoogle # Generate a hoogle database + --haddock-html # Generate HTML documentation (the default) + --haddock-html-location=URL # Location of HTML documentation for + pre-requisite packages + --haddock-for-hackage # Collection of flags to generate documentation + suitable for upload to hackage + --haddock-executables # Run haddock for Executables targets + --haddock-tests # Run haddock for Test Suite targets + --haddock-benchmarks # Run haddock for Benchmark targets + --haddock-all # Run haddock for all targets + --haddock-internal # Run haddock for internal modules and include + all symbols + --haddock-css=PATH # Use PATH as the haddock stylesheet + --haddock-hyperlink-source # Hyperlink the documentation to the source code + --haddock-quickjump # Generate an index for interactive + documentation navigation + --haddock-hscolour-css=PATH # Use PATH as the HsColour stylesheet + --haddock-contents-location=URL + # Bake URL in as the location for the contents + page + --haddock-base-url=URL # Base URL for static files. + --haddock-resources-dir=DIR # Location of Haddocks static / auxiliary files + --haddock-output-dir=DIR # Generate haddock documentation into this + directory. This flag is provided as a + technology preview and is subject to change in + the next releases. + --haddock-use-unicode # Pass --use-unicode option to haddock + --test-log=TEMPLATE # Log all test suite results to file (name + template can use $pkgid, $compiler, $os, + $arch, $test-suite, $result) + --test-machine-log=TEMPLATE # Produce a machine-readable log file (name + template can use $pkgid, $compiler, $os, + $arch, $result) + --test-show-details=FILTER # 'always': always show results of individual + test cases. 'never': never show results of + individual test cases. 'failures': show + results of failing test cases. 'streaming': + show results of test cases in real + time.'direct': send results of test cases in + real time; no log file. + --test-keep-tix-files # Keep .tix files for HPC between test runs + --test-wrapper=FILE # Run test through a wrapper. + --test-fail-when-no-test-suites + # Exit with failure when no test suites are + found. + --test-options=TEMPLATES # Give extra options to test executables (split + on spaces, use "" to prevent splitting; name + templates can use $pkgid, $compiler, $os, + $arch, $test-suite) + --test-option=TEMPLATE # Give extra option to test executables (passed + directly as a single argument; name template + can use $pkgid, $compiler, $os, $arch, + $test-suite) + --benchmark-options=TEMPLATES + # Give extra options to benchmark executables + (split on spaces, use "" to prevent splitting; + name templates can use $pkgid, $compiler, $os, + $arch, $benchmark) + --benchmark-option=TEMPLATE # Give extra option to benchmark executables + (passed directly as a single argument; name + template can use $pkgid, $compiler, $os, + $arch, $benchmark) + --project-dir=DIR # Set the path of the project directory + --project-file=FILE # Set the path of the cabal.project file + (relative to the project directory when + relative) + -z, --ignore-project # Ignore local project configuration (unless + --project-dir or --project-file is also set) + --project-file-parser=PARSER # Set the parser to use for the project file diff --git a/doc/cmd-v2-help/list.txt b/doc/cmd-v2-help/list.txt new file mode 100644 index 00000000000..215a0029560 --- /dev/null +++ b/doc/cmd-v2-help/list.txt @@ -0,0 +1,31 @@ +List packages matching a search string. + +Usage: cabal list [FLAGS] + or: cabal list [FLAGS] STRINGS + +List all packages, or all packages matching one of the search strings. + +Use the package database specified with --package-db. If not specified, use +the user package database. + +Flags for list: + -h, --help # Show this help text + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + --installed # Only print installed packages + --simple-output # Print in a easy-to-parse format + -i, --ignore-case # Enable Ignore case distinctions + -I, --strict-case # Disable Ignore case distinctions + --package-db=DB # Append the given package database to the list + of package databases used (to satisfy + dependencies and register into). May be a + specific file, 'global' or 'user'. The initial + list is ['global'], ['global', 'user'], + depending on context. Use 'clear' to reset the + list to empty. See the user guide for details. + -w PATH or -wPATH, --with-compiler=PATH + # Give the path to a particular compiler + +Examples: + cabal list pandoc + Will find pandoc, pandoc-citeproc, pandoc-lens, ... diff --git a/doc/cmd-v2-help/outdated.txt b/doc/cmd-v2-help/outdated.txt new file mode 100644 index 00000000000..85a07dd7493 --- /dev/null +++ b/doc/cmd-v2-help/outdated.txt @@ -0,0 +1,378 @@ +Check for outdated dependencies. + +Usage: cabal outdated [FLAGS] [PACKAGES] + +Checks for outdated dependencies in the package description file or freeze +file + +Flags for outdated: + -h, --help # Show this help text + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + --builddir=DIR # The directory where Cabal puts generated build + files (default dist) + --keep-temp-files # Keep temporary files. + -g, --ghc # Compile with GHC + --ghcjs # Compile with GHCJS + --uhc # Compile with UHC + -w PATH or -wPATH, --with-compiler=PATH + # Give the path to a particular compiler + --with-hc-pkg=PATH # Give the path to the package tool + --prefix=DIR # Bake this prefix in preparation of + installation + --bindir=DIR # Installation directory for executables + --libdir=DIR # Installation directory for libraries + --libsubdir=DIR # Subdirectory of libdir in which libs are + installed + --dynlibdir=DIR # Installation directory for dynamic libraries + --bytecodelibdir=DIR # Installation directory for bytecode libraries + --libexecdir=DIR # Installation directory for program executables + --libexecsubdir=DIR # Subdirectory of libexecdir in which private + executables are installed + --datadir=DIR # Installation directory for read-only data + --datasubdir=DIR # Subdirectory of datadir in which data files + are installed + --docdir=DIR # Installation directory for documentation + --htmldir=DIR # Installation directory for HTML documentation + --haddockdir=DIR # Installation directory for haddock interfaces + --sysconfdir=DIR # Installation directory for configuration files + --program-prefix=PREFIX # Prefix to be applied to installed executables + --program-suffix=SUFFIX # Suffix to be applied to installed executables + --enable-library-vanilla # Enable Vanilla libraries + --disable-library-vanilla # Disable Vanilla libraries + -p, --enable-library-profiling + # Enable Library profiling + --disable-library-profiling # Disable Library profiling + --enable-shared # Enable Shared library + --disable-shared # Disable Shared library + --enable-static # Enable Static library + --disable-static # Disable Static library + --enable-library-bytecode # Enable Bytecode library + --disable-library-bytecode # Disable Bytecode library + --enable-executable-dynamic # Enable Executable dynamic linking + --disable-executable-dynamic # Disable Executable dynamic linking + --enable-executable-static # Enable Executable fully static linking + --disable-executable-static # Disable Executable fully static linking + --enable-profiling # Enable Executable and library profiling + --disable-profiling # Disable Executable and library profiling + --enable-profiling-shared # Enable Build profiling shared libraries + --disable-profiling-shared # Disable Build profiling shared libraries + --enable-executable-profiling + # Enable Executable profiling (DEPRECATED) + --disable-executable-profiling + # Disable Executable profiling (DEPRECATED) + --profiling-detail=level # Profiling detail level for executable and + library (default, none, exported-functions, + toplevel-functions, all-functions, late). + --library-profiling-detail=level + # Profiling detail level for libraries only. + -O[n], --enable-optimization[=n] + # Build with optimization (n is 0--2, default is + 1) + --disable-optimization # Build without optimization + --enable-debug-info[=n] # Emit debug info (n is 0--3, default is 0) + --disable-debug-info # Don't emit debug info + --enable-build-info # Enable build information generation during + project building + --disable-build-info # Disable build information generation during + project building + --enable-library-for-ghci # Enable compile library for use with GHCi + --disable-library-for-ghci # Disable compile library for use with GHCi + --enable-split-sections # Enable compile library code such that unneeded + definitions can be dropped from the final + executable (GHC 7.8+) + --disable-split-sections # Disable compile library code such that + unneeded definitions can be dropped from the + final executable (GHC 7.8+) + --enable-split-objs # Enable split library into smaller objects to + reduce binary sizes (GHC 6.6+) + --disable-split-objs # Disable split library into smaller objects to + reduce binary sizes (GHC 6.6+) + --enable-executable-stripping + # Enable strip executables upon installation to + reduce binary sizes + --disable-executable-stripping + # Disable strip executables upon installation to + reduce binary sizes + --enable-library-stripping # Enable strip libraries upon installation to + reduce binary sizes + --disable-library-stripping # Disable strip libraries upon installation to + reduce binary sizes + --configure-option=OPT # Extra option for configure + --user # Enable doing a per-user installation + --global # Disable doing a per-user installation + --package-db=DB # Append the given package database to the list + of package databases used (to satisfy + dependencies and register into). May be a + specific file, 'global' or 'user'. The initial + list is ['global'], ['global', 'user'], or + ['global', $sandbox], depending on context. + Use 'clear' to reset the list to empty. See + the user guide for details. + -f FLAGS or -fFLAGS, --flags=FLAGS + # Force values for the given flags in Cabal + conditionals in the .cabal file. E.g., + --flags="debug -usebytestrings" forces the + flag "debug" to true and "usebytestrings" to + false. + --extra-include-dirs=PATH # A list of directories to search for header + files + --enable-deterministic # Enable Try to be as deterministic as possible + (used by the test suite) + --disable-deterministic # Disable Try to be as deterministic as possible + (used by the test suite) + --ipid=IPID # Installed package ID to compile this package + as + --cid=CID # Installed component ID to compile this + component as + --extra-lib-dirs=PATH # A list of directories to search for external + libraries + --extra-lib-dirs-static=PATH # A list of directories to search for external + libraries when linking fully static + executables + --extra-framework-dirs=PATH # A list of directories to search for external + frameworks (OS X only) + --extra-prog-path=PATH # A list of directories to search for required + programs (in addition to the normal search + locations) + --instantiate-with=NAME=MOD # A mapping of signature names to concrete + module instantiations. + --enable-tests # Enable dependency checking and compilation for + test suites listed in the package description + file. + --disable-tests # Disable dependency checking and compilation + for test suites listed in the package + description file. + --enable-coverage # Enable build package with Haskell Program + Coverage. (GHC only) + --disable-coverage # Disable build package with Haskell Program + Coverage. (GHC only) + --enable-library-coverage # Enable build package with Haskell Program + Coverage. (GHC only) (DEPRECATED) + --disable-library-coverage # Disable build package with Haskell Program + Coverage. (GHC only) (DEPRECATED) + --enable-benchmarks # Enable dependency checking and compilation for + benchmarks listed in the package description + file. + --disable-benchmarks # Disable dependency checking and compilation + for benchmarks listed in the package + description file. + --enable-relocatable # Enable building a package that is relocatable. + (GHC only) + --disable-relocatable # Disable building a package that is + relocatable. (GHC only) + --disable-response-files # Enable workaround for old versions of programs + like "ar" that do not support @file arguments + --allow-depending-on-private-libs + # Allow depending on private libraries. If set, + the library visibility check MUST be done + externally. + --coverage-for=UNITID # A list of unit-ids of libraries to include in + the Haskell Program Coverage report. + --ignore-build-tools # Ignore build tool dependencies. If set, + declared build tools needn't be found for + compilation to proceed. + --with-PROG=PATH # Give the path to PROG + --PROG-option=OPT # Give an extra option to PROG (passed directly + to PROG as a single argument) + --PROG-options=OPTS # Give extra options to PROG (split on spaces, + use "" to prevent splitting) + --cabal-lib-version=VERSION # Select which version of the Cabal lib to use + to build packages (useful for testing). + --enable-append # Enable appending the new config to the old + config file + --disable-append # Disable appending the new config to the old + config file + --enable-backup # Enable the backup of the config file before + any alterations + --disable-backup # Disable the backup of the config file before + any alterations + -c CONSTRAINT or -cCONSTRAINT, --constraint=CONSTRAINT + # Specify constraints on a package (version, + installed/source, flags) + --preference=CONSTRAINT # Specify preferences (soft constraints) on the + version of a package + --solver=SOLVER # Select dependency solver to use (default: + modular). Choices: modular. + --allow-older[=DEPS] # Ignore lower bounds in all dependencies or + DEPS + --allow-newer[=DEPS] # Ignore upper bounds in all dependencies or + DEPS + --write-ghc-environment-files=always|never|ghc8.4.4+ + # Whether to create a .ghc.environment file + after a successful build (v2-build only) + --enable-documentation # Enable building of documentation + --disable-documentation # Disable building of documentation + --doc-index-file=TEMPLATE # A central index of haddock API documentation + (template cannot use $pkgid) + --dry-run # Do not install anything, only print what would + be installed. + --only-download # Do not build anything, only fetch the + packages. + --max-backjumps=NUM # Maximum number of backjumps allowed while + solving (default: 4000). Use a negative number + to enable unlimited backtracking. Use 0 to + disable backtracking completely. + --reorder-goals # Try to reorder goals according to certain + heuristics. Slows things down on average, but + may make backtracking faster for some + packages. + --count-conflicts # Try to speed up solving by preferring goals + that are involved in a lot of conflicts + (default). + --fine-grained-conflicts # Skip a version of a package if it does not + resolve the conflicts encountered in the last + version, as a solver optimization (default). + --minimize-conflict-set # When there is no solution, try to improve the + error message by finding a minimal conflict + set (default: false). May increase run time + significantly. + --independent-goals # Treat several goals on the command line as + independent. If several goals depend on the + same package, different versions can be + chosen. + --prefer-oldest # Prefer the oldest (instead of the latest) + versions of packages available. Useful to + determine lower bounds in the build-depends + section. + --prefer-version=oldest|latest|installed-or-latest + # Select which version of a package that the + solver should prefer. Oldest is useful to + determine lower bounds in build-depends + section. Latest will prefer the latest + version. Installed-or-latest will prefer + installed versions and the latest version + otherwise. + --shadow-installed-packages # If multiple package instances of the same + version are installed, treat all but one as + shadowed. + --strong-flags # Do not defer flag choices (this used to be the + default in cabal-install <= 1.20). + --allow-boot-library-installs + # Allow cabal to install base, ghc-prim, + integer-simple, integer-gmp, and + template-haskell. + --reject-unconstrained-dependencies=none|all + # Require these packages to have constraints on + them if they are to be selected (default: + none). + --reinstall # Install even if it means installing the same + version again. + --avoid-reinstalls # Do not select versions that would + destructively overwrite installed packages. + --force-reinstalls # Reinstall packages even if they will most + likely break other installed packages. + --upgrade-dependencies # Pick the latest version for all dependencies, + rather than trying to pick an installed + version. + --only-dependencies # Install only the dependencies necessary to + build the given packages + --dependencies-only # A synonym for --only-dependencies + --index-state=STATE # Use source package index state as it existed + at a previous time. Accepts unix-timestamps + (e.g. '@1474732068'), ISO8601 UTC timestamps + (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' + (default: 'HEAD'). + --root-cmd=COMMAND # (No longer supported, do not use.) + --build-summary=TEMPLATE # Save build summaries to file (name template + can use $pkgid, $compiler, $os, $arch) + --build-log=TEMPLATE # Log all builds to file (name template can use + $pkgid, $compiler, $os, $arch) + --remote-build-reporting=LEVEL + # Generate build reports to send to a remote + server (none, anonymous or detailed). + --report-planning-failure # Generate build reports when the dependency + solver fails. This is used by the Hackage + build bot. + --enable-per-component # Enable Per-component builds when possible + --disable-per-component # Disable Per-component builds when possible + --run-tests # Run package test suites during installation. + --semaphore # Use a semaphore so GHC can compile components + in parallel + -j[NUM], --jobs[=NUM] # Run NUM jobs simultaneously (or '$ncpus' if no + NUM is given). + --keep-going # After a build failure, continue to build other + unaffected packages. + --offline # Don't download packages from the Internet. + --build-timings # Print elapsed time for each build phase. + --haddock-hoogle # Generate a hoogle database + --haddock-html # Generate HTML documentation (the default) + --haddock-html-location=URL # Location of HTML documentation for + pre-requisite packages + --haddock-for-hackage # Collection of flags to generate documentation + suitable for upload to hackage + --haddock-executables # Run haddock for Executables targets + --haddock-tests # Run haddock for Test Suite targets + --haddock-benchmarks # Run haddock for Benchmark targets + --haddock-all # Run haddock for all targets + --haddock-internal # Run haddock for internal modules and include + all symbols + --haddock-css=PATH # Use PATH as the haddock stylesheet + --haddock-hyperlink-source # Hyperlink the documentation to the source code + --haddock-quickjump # Generate an index for interactive + documentation navigation + --haddock-hscolour-css=PATH # Use PATH as the HsColour stylesheet + --haddock-contents-location=URL + # Bake URL in as the location for the contents + page + --haddock-base-url=URL # Base URL for static files. + --haddock-resources-dir=DIR # Location of Haddocks static / auxiliary files + --haddock-output-dir=DIR # Generate haddock documentation into this + directory. This flag is provided as a + technology preview and is subject to change in + the next releases. + --haddock-use-unicode # Pass --use-unicode option to haddock + --test-log=TEMPLATE # Log all test suite results to file (name + template can use $pkgid, $compiler, $os, + $arch, $test-suite, $result) + --test-machine-log=TEMPLATE # Produce a machine-readable log file (name + template can use $pkgid, $compiler, $os, + $arch, $result) + --test-show-details=FILTER # 'always': always show results of individual + test cases. 'never': never show results of + individual test cases. 'failures': show + results of failing test cases. 'streaming': + show results of test cases in real + time.'direct': send results of test cases in + real time; no log file. + --test-keep-tix-files # Keep .tix files for HPC between test runs + --test-wrapper=FILE # Run test through a wrapper. + --test-fail-when-no-test-suites + # Exit with failure when no test suites are + found. + --test-options=TEMPLATES # Give extra options to test executables (split + on spaces, use "" to prevent splitting; name + templates can use $pkgid, $compiler, $os, + $arch, $test-suite) + --test-option=TEMPLATE # Give extra option to test executables (passed + directly as a single argument; name template + can use $pkgid, $compiler, $os, $arch, + $test-suite) + --benchmark-options=TEMPLATES + # Give extra options to benchmark executables + (split on spaces, use "" to prevent splitting; + name templates can use $pkgid, $compiler, $os, + $arch, $benchmark) + --benchmark-option=TEMPLATE # Give extra option to benchmark executables + (passed directly as a single argument; name + template can use $pkgid, $compiler, $os, + $arch, $benchmark) + --project-dir=DIR # Set the path of the project directory + --project-file=FILE # Set the path of the cabal.project file + (relative to the project directory when + relative) + -z, --ignore-project # Ignore local project configuration (unless + --project-dir or --project-file is also set) + --project-file-parser=PARSER # Set the parser to use for the project file + --freeze-file # Act on the freeze file + --project-context # Check for outdated dependencies in the project + context, for example, dependencies specified + in cabal.project orcabal.project.freeze. + --simple-output # Only print names of outdated dependencies, one + per line + --exit-code # Exit with non-zero when there are outdated + dependencies + -q, --quiet # Don't print any output. Implies '--exit-code' + and '-v0' + --ignore=PKGS # Packages to ignore + --minor[=PKGS] # Ignore major version bumps for these packages diff --git a/doc/cmd-v2-help/path.txt b/doc/cmd-v2-help/path.txt new file mode 100644 index 00000000000..74f4a3b3355 --- /dev/null +++ b/doc/cmd-v2-help/path.txt @@ -0,0 +1,388 @@ +Query for simple project information. + +Usage: cabal path [FLAGS] + +Query for configuration and project information such as project GHC. +The output order of query keys is implementation defined and should not be +relied on. + +Flags for path: + -h, --help # Show this help text + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + --builddir=DIR # The directory where Cabal puts generated build + files (default dist) + --keep-temp-files # Keep temporary files. + -g, --ghc # Compile with GHC + --ghcjs # Compile with GHCJS + --uhc # Compile with UHC + -w PATH or -wPATH, --with-compiler=PATH + # Give the path to a particular compiler + --with-hc-pkg=PATH # Give the path to the package tool + --prefix=DIR # Bake this prefix in preparation of + installation + --bindir=DIR # Installation directory for executables + --libdir=DIR # Installation directory for libraries + --libsubdir=DIR # Subdirectory of libdir in which libs are + installed + --dynlibdir=DIR # Installation directory for dynamic libraries + --bytecodelibdir=DIR # Installation directory for bytecode libraries + --libexecdir=DIR # Installation directory for program executables + --libexecsubdir=DIR # Subdirectory of libexecdir in which private + executables are installed + --datadir=DIR # Installation directory for read-only data + --datasubdir=DIR # Subdirectory of datadir in which data files + are installed + --docdir=DIR # Installation directory for documentation + --htmldir=DIR # Installation directory for HTML documentation + --haddockdir=DIR # Installation directory for haddock interfaces + --sysconfdir=DIR # Installation directory for configuration files + --program-prefix=PREFIX # Prefix to be applied to installed executables + --program-suffix=SUFFIX # Suffix to be applied to installed executables + --enable-library-vanilla # Enable Vanilla libraries + --disable-library-vanilla # Disable Vanilla libraries + -p, --enable-library-profiling + # Enable Library profiling + --disable-library-profiling # Disable Library profiling + --enable-shared # Enable Shared library + --disable-shared # Disable Shared library + --enable-static # Enable Static library + --disable-static # Disable Static library + --enable-library-bytecode # Enable Bytecode library + --disable-library-bytecode # Disable Bytecode library + --enable-executable-dynamic # Enable Executable dynamic linking + --disable-executable-dynamic # Disable Executable dynamic linking + --enable-executable-static # Enable Executable fully static linking + --disable-executable-static # Disable Executable fully static linking + --enable-profiling # Enable Executable and library profiling + --disable-profiling # Disable Executable and library profiling + --enable-profiling-shared # Enable Build profiling shared libraries + --disable-profiling-shared # Disable Build profiling shared libraries + --enable-executable-profiling + # Enable Executable profiling (DEPRECATED) + --disable-executable-profiling + # Disable Executable profiling (DEPRECATED) + --profiling-detail=level # Profiling detail level for executable and + library (default, none, exported-functions, + toplevel-functions, all-functions, late). + --library-profiling-detail=level + # Profiling detail level for libraries only. + -O[n], --enable-optimization[=n] + # Build with optimization (n is 0--2, default is + 1) + --disable-optimization # Build without optimization + --enable-debug-info[=n] # Emit debug info (n is 0--3, default is 0) + --disable-debug-info # Don't emit debug info + --enable-build-info # Enable build information generation during + project building + --disable-build-info # Disable build information generation during + project building + --enable-library-for-ghci # Enable compile library for use with GHCi + --disable-library-for-ghci # Disable compile library for use with GHCi + --enable-split-sections # Enable compile library code such that unneeded + definitions can be dropped from the final + executable (GHC 7.8+) + --disable-split-sections # Disable compile library code such that + unneeded definitions can be dropped from the + final executable (GHC 7.8+) + --enable-split-objs # Enable split library into smaller objects to + reduce binary sizes (GHC 6.6+) + --disable-split-objs # Disable split library into smaller objects to + reduce binary sizes (GHC 6.6+) + --enable-executable-stripping + # Enable strip executables upon installation to + reduce binary sizes + --disable-executable-stripping + # Disable strip executables upon installation to + reduce binary sizes + --enable-library-stripping # Enable strip libraries upon installation to + reduce binary sizes + --disable-library-stripping # Disable strip libraries upon installation to + reduce binary sizes + --configure-option=OPT # Extra option for configure + --user # Enable doing a per-user installation + --global # Disable doing a per-user installation + --package-db=DB # Append the given package database to the list + of package databases used (to satisfy + dependencies and register into). May be a + specific file, 'global' or 'user'. The initial + list is ['global'], ['global', 'user'], or + ['global', $sandbox], depending on context. + Use 'clear' to reset the list to empty. See + the user guide for details. + -f FLAGS or -fFLAGS, --flags=FLAGS + # Force values for the given flags in Cabal + conditionals in the .cabal file. E.g., + --flags="debug -usebytestrings" forces the + flag "debug" to true and "usebytestrings" to + false. + --extra-include-dirs=PATH # A list of directories to search for header + files + --enable-deterministic # Enable Try to be as deterministic as possible + (used by the test suite) + --disable-deterministic # Disable Try to be as deterministic as possible + (used by the test suite) + --ipid=IPID # Installed package ID to compile this package + as + --cid=CID # Installed component ID to compile this + component as + --extra-lib-dirs=PATH # A list of directories to search for external + libraries + --extra-lib-dirs-static=PATH # A list of directories to search for external + libraries when linking fully static + executables + --extra-framework-dirs=PATH # A list of directories to search for external + frameworks (OS X only) + --extra-prog-path=PATH # A list of directories to search for required + programs (in addition to the normal search + locations) + --instantiate-with=NAME=MOD # A mapping of signature names to concrete + module instantiations. + --enable-tests # Enable dependency checking and compilation for + test suites listed in the package description + file. + --disable-tests # Disable dependency checking and compilation + for test suites listed in the package + description file. + --enable-coverage # Enable build package with Haskell Program + Coverage. (GHC only) + --disable-coverage # Disable build package with Haskell Program + Coverage. (GHC only) + --enable-library-coverage # Enable build package with Haskell Program + Coverage. (GHC only) (DEPRECATED) + --disable-library-coverage # Disable build package with Haskell Program + Coverage. (GHC only) (DEPRECATED) + --enable-benchmarks # Enable dependency checking and compilation for + benchmarks listed in the package description + file. + --disable-benchmarks # Disable dependency checking and compilation + for benchmarks listed in the package + description file. + --enable-relocatable # Enable building a package that is relocatable. + (GHC only) + --disable-relocatable # Disable building a package that is + relocatable. (GHC only) + --disable-response-files # Enable workaround for old versions of programs + like "ar" that do not support @file arguments + --allow-depending-on-private-libs + # Allow depending on private libraries. If set, + the library visibility check MUST be done + externally. + --coverage-for=UNITID # A list of unit-ids of libraries to include in + the Haskell Program Coverage report. + --ignore-build-tools # Ignore build tool dependencies. If set, + declared build tools needn't be found for + compilation to proceed. + --with-PROG=PATH # Give the path to PROG + --PROG-option=OPT # Give an extra option to PROG (passed directly + to PROG as a single argument) + --PROG-options=OPTS # Give extra options to PROG (split on spaces, + use "" to prevent splitting) + --cabal-lib-version=VERSION # Select which version of the Cabal lib to use + to build packages (useful for testing). + --enable-append # Enable appending the new config to the old + config file + --disable-append # Disable appending the new config to the old + config file + --enable-backup # Enable the backup of the config file before + any alterations + --disable-backup # Disable the backup of the config file before + any alterations + -c CONSTRAINT or -cCONSTRAINT, --constraint=CONSTRAINT + # Specify constraints on a package (version, + installed/source, flags) + --preference=CONSTRAINT # Specify preferences (soft constraints) on the + version of a package + --solver=SOLVER # Select dependency solver to use (default: + modular). Choices: modular. + --allow-older[=DEPS] # Ignore lower bounds in all dependencies or + DEPS + --allow-newer[=DEPS] # Ignore upper bounds in all dependencies or + DEPS + --write-ghc-environment-files=always|never|ghc8.4.4+ + # Whether to create a .ghc.environment file + after a successful build (v2-build only) + --enable-documentation # Enable building of documentation + --disable-documentation # Disable building of documentation + --doc-index-file=TEMPLATE # A central index of haddock API documentation + (template cannot use $pkgid) + --dry-run # Do not install anything, only print what would + be installed. + --only-download # Do not build anything, only fetch the + packages. + --max-backjumps=NUM # Maximum number of backjumps allowed while + solving (default: 4000). Use a negative number + to enable unlimited backtracking. Use 0 to + disable backtracking completely. + --reorder-goals # Try to reorder goals according to certain + heuristics. Slows things down on average, but + may make backtracking faster for some + packages. + --count-conflicts # Try to speed up solving by preferring goals + that are involved in a lot of conflicts + (default). + --fine-grained-conflicts # Skip a version of a package if it does not + resolve the conflicts encountered in the last + version, as a solver optimization (default). + --minimize-conflict-set # When there is no solution, try to improve the + error message by finding a minimal conflict + set (default: false). May increase run time + significantly. + --independent-goals # Treat several goals on the command line as + independent. If several goals depend on the + same package, different versions can be + chosen. + --prefer-oldest # Prefer the oldest (instead of the latest) + versions of packages available. Useful to + determine lower bounds in the build-depends + section. + --prefer-version=oldest|latest|installed-or-latest + # Select which version of a package that the + solver should prefer. Oldest is useful to + determine lower bounds in build-depends + section. Latest will prefer the latest + version. Installed-or-latest will prefer + installed versions and the latest version + otherwise. + --shadow-installed-packages # If multiple package instances of the same + version are installed, treat all but one as + shadowed. + --strong-flags # Do not defer flag choices (this used to be the + default in cabal-install <= 1.20). + --allow-boot-library-installs + # Allow cabal to install base, ghc-prim, + integer-simple, integer-gmp, and + template-haskell. + --reject-unconstrained-dependencies=none|all + # Require these packages to have constraints on + them if they are to be selected (default: + none). + --reinstall # Install even if it means installing the same + version again. + --avoid-reinstalls # Do not select versions that would + destructively overwrite installed packages. + --force-reinstalls # Reinstall packages even if they will most + likely break other installed packages. + --upgrade-dependencies # Pick the latest version for all dependencies, + rather than trying to pick an installed + version. + --only-dependencies # Install only the dependencies necessary to + build the given packages + --dependencies-only # A synonym for --only-dependencies + --index-state=STATE # Use source package index state as it existed + at a previous time. Accepts unix-timestamps + (e.g. '@1474732068'), ISO8601 UTC timestamps + (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' + (default: 'HEAD'). + --root-cmd=COMMAND # (No longer supported, do not use.) + --build-summary=TEMPLATE # Save build summaries to file (name template + can use $pkgid, $compiler, $os, $arch) + --build-log=TEMPLATE # Log all builds to file (name template can use + $pkgid, $compiler, $os, $arch) + --remote-build-reporting=LEVEL + # Generate build reports to send to a remote + server (none, anonymous or detailed). + --report-planning-failure # Generate build reports when the dependency + solver fails. This is used by the Hackage + build bot. + --enable-per-component # Enable Per-component builds when possible + --disable-per-component # Disable Per-component builds when possible + --run-tests # Run package test suites during installation. + --semaphore # Use a semaphore so GHC can compile components + in parallel + -j[NUM], --jobs[=NUM] # Run NUM jobs simultaneously (or '$ncpus' if no + NUM is given). + --keep-going # After a build failure, continue to build other + unaffected packages. + --offline # Don't download packages from the Internet. + --build-timings # Print elapsed time for each build phase. + --haddock-hoogle # Generate a hoogle database + --haddock-html # Generate HTML documentation (the default) + --haddock-html-location=URL # Location of HTML documentation for + pre-requisite packages + --haddock-for-hackage # Collection of flags to generate documentation + suitable for upload to hackage + --haddock-executables # Run haddock for Executables targets + --haddock-tests # Run haddock for Test Suite targets + --haddock-benchmarks # Run haddock for Benchmark targets + --haddock-all # Run haddock for all targets + --haddock-internal # Run haddock for internal modules and include + all symbols + --haddock-css=PATH # Use PATH as the haddock stylesheet + --haddock-hyperlink-source # Hyperlink the documentation to the source code + --haddock-quickjump # Generate an index for interactive + documentation navigation + --haddock-hscolour-css=PATH # Use PATH as the HsColour stylesheet + --haddock-contents-location=URL + # Bake URL in as the location for the contents + page + --haddock-base-url=URL # Base URL for static files. + --haddock-resources-dir=DIR # Location of Haddocks static / auxiliary files + --haddock-output-dir=DIR # Generate haddock documentation into this + directory. This flag is provided as a + technology preview and is subject to change in + the next releases. + --haddock-use-unicode # Pass --use-unicode option to haddock + --test-log=TEMPLATE # Log all test suite results to file (name + template can use $pkgid, $compiler, $os, + $arch, $test-suite, $result) + --test-machine-log=TEMPLATE # Produce a machine-readable log file (name + template can use $pkgid, $compiler, $os, + $arch, $result) + --test-show-details=FILTER # 'always': always show results of individual + test cases. 'never': never show results of + individual test cases. 'failures': show + results of failing test cases. 'streaming': + show results of test cases in real + time.'direct': send results of test cases in + real time; no log file. + --test-keep-tix-files # Keep .tix files for HPC between test runs + --test-wrapper=FILE # Run test through a wrapper. + --test-fail-when-no-test-suites + # Exit with failure when no test suites are + found. + --test-options=TEMPLATES # Give extra options to test executables (split + on spaces, use "" to prevent splitting; name + templates can use $pkgid, $compiler, $os, + $arch, $test-suite) + --test-option=TEMPLATE # Give extra option to test executables (passed + directly as a single argument; name template + can use $pkgid, $compiler, $os, $arch, + $test-suite) + --benchmark-options=TEMPLATES + # Give extra options to benchmark executables + (split on spaces, use "" to prevent splitting; + name templates can use $pkgid, $compiler, $os, + $arch, $benchmark) + --benchmark-option=TEMPLATE # Give extra option to benchmark executables + (passed directly as a single argument; name + template can use $pkgid, $compiler, $os, + $arch, $benchmark) + --project-dir=DIR # Set the path of the project directory + --project-file=FILE # Set the path of the cabal.project file + (relative to the project directory when + relative) + -z, --ignore-project # Ignore local project configuration (unless + --project-dir or --project-file is also set) + --project-file-parser=PARSER # Set the parser to use for the project file + --output-format=json|key-value + # Output format of the requested path locations + --compiler-info # Print information of the project compiler + --cache-home # Print cabal's cache-home + --remote-repo-cache # Print cabal's remote-repo-cache + --logs-dir # Print cabal's logs-dir + --store-dir # Print cabal's store-dir + --config-file # Print cabal's config-file + --installdir # Print cabal's installdir + +Examples: + cabal path --store-dir + Print the store-dir location of cabal. + cabal path --output-format=json --compiler-info + Print compiler information in json format. + cabal path --output-format=json --installdir --compiler-info + Print compiler information and installation directory in json format. + cabal path --output-format=key-value --installdir + Print the installation directory, taking project information into account. + cabal path -z --output-format=key-value --installdir + Print the installation directory, without taking project information into account. diff --git a/doc/cmd-v2-help/repl.txt b/doc/cmd-v2-help/repl.txt new file mode 100644 index 00000000000..5a27cf19588 --- /dev/null +++ b/doc/cmd-v2-help/repl.txt @@ -0,0 +1,408 @@ +Open an interactive session for the given component. + +Usage: cabal repl [TARGET] [FLAGS] + +Open an interactive session for a single component within the project or for +multiple components at once if multi-repl is enabled. + +The available targets are the same as for the 'build' command: individual +components within packages in the project, including libraries, executables, +test-suites or benchmarks. Packages can also be specified in which case the +library component in the package will be used, or the (first listed) +executable in the package if there is no library. + +Dependencies are built or rebuilt as necessary. Additional configuration flags +can be specified on the command line and these extend the project +configuration from the 'cabal.project', 'cabal.project.local' and other files. + +Flags for repl: + -h, --help # Show this help text + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + --builddir=DIR # The directory where Cabal puts generated build + files (default dist) + --keep-temp-files # Keep temporary files. + -g, --ghc # Compile with GHC + --ghcjs # Compile with GHCJS + --uhc # Compile with UHC + -w PATH or -wPATH, --with-compiler=PATH + # Give the path to a particular compiler + --with-hc-pkg=PATH # Give the path to the package tool + --prefix=DIR # Bake this prefix in preparation of + installation + --bindir=DIR # Installation directory for executables + --libdir=DIR # Installation directory for libraries + --libsubdir=DIR # Subdirectory of libdir in which libs are + installed + --dynlibdir=DIR # Installation directory for dynamic libraries + --bytecodelibdir=DIR # Installation directory for bytecode libraries + --libexecdir=DIR # Installation directory for program executables + --libexecsubdir=DIR # Subdirectory of libexecdir in which private + executables are installed + --datadir=DIR # Installation directory for read-only data + --datasubdir=DIR # Subdirectory of datadir in which data files + are installed + --docdir=DIR # Installation directory for documentation + --htmldir=DIR # Installation directory for HTML documentation + --haddockdir=DIR # Installation directory for haddock interfaces + --sysconfdir=DIR # Installation directory for configuration files + --program-prefix=PREFIX # Prefix to be applied to installed executables + --program-suffix=SUFFIX # Suffix to be applied to installed executables + --enable-library-vanilla # Enable Vanilla libraries + --disable-library-vanilla # Disable Vanilla libraries + -p, --enable-library-profiling + # Enable Library profiling + --disable-library-profiling # Disable Library profiling + --enable-shared # Enable Shared library + --disable-shared # Disable Shared library + --enable-static # Enable Static library + --disable-static # Disable Static library + --enable-library-bytecode # Enable Bytecode library + --disable-library-bytecode # Disable Bytecode library + --enable-executable-dynamic # Enable Executable dynamic linking + --disable-executable-dynamic # Disable Executable dynamic linking + --enable-executable-static # Enable Executable fully static linking + --disable-executable-static # Disable Executable fully static linking + --enable-profiling # Enable Executable and library profiling + --disable-profiling # Disable Executable and library profiling + --enable-profiling-shared # Enable Build profiling shared libraries + --disable-profiling-shared # Disable Build profiling shared libraries + --enable-executable-profiling + # Enable Executable profiling (DEPRECATED) + --disable-executable-profiling + # Disable Executable profiling (DEPRECATED) + --profiling-detail=level # Profiling detail level for executable and + library (default, none, exported-functions, + toplevel-functions, all-functions, late). + --library-profiling-detail=level + # Profiling detail level for libraries only. + -O[n], --enable-optimization[=n] + # Build with optimization (n is 0--2, default is + 1) + --disable-optimization # Build without optimization + --enable-debug-info[=n] # Emit debug info (n is 0--3, default is 0) + --disable-debug-info # Don't emit debug info + --enable-build-info # Enable build information generation during + project building + --disable-build-info # Disable build information generation during + project building + --enable-library-for-ghci # Enable compile library for use with GHCi + --disable-library-for-ghci # Disable compile library for use with GHCi + --enable-split-sections # Enable compile library code such that unneeded + definitions can be dropped from the final + executable (GHC 7.8+) + --disable-split-sections # Disable compile library code such that + unneeded definitions can be dropped from the + final executable (GHC 7.8+) + --enable-split-objs # Enable split library into smaller objects to + reduce binary sizes (GHC 6.6+) + --disable-split-objs # Disable split library into smaller objects to + reduce binary sizes (GHC 6.6+) + --enable-executable-stripping + # Enable strip executables upon installation to + reduce binary sizes + --disable-executable-stripping + # Disable strip executables upon installation to + reduce binary sizes + --enable-library-stripping # Enable strip libraries upon installation to + reduce binary sizes + --disable-library-stripping # Disable strip libraries upon installation to + reduce binary sizes + --configure-option=OPT # Extra option for configure + --user # Enable doing a per-user installation + --global # Disable doing a per-user installation + --package-db=DB # Append the given package database to the list + of package databases used (to satisfy + dependencies and register into). May be a + specific file, 'global' or 'user'. The initial + list is ['global'], ['global', 'user'], or + ['global', $sandbox], depending on context. + Use 'clear' to reset the list to empty. See + the user guide for details. + -f FLAGS or -fFLAGS, --flags=FLAGS + # Force values for the given flags in Cabal + conditionals in the .cabal file. E.g., + --flags="debug -usebytestrings" forces the + flag "debug" to true and "usebytestrings" to + false. + --extra-include-dirs=PATH # A list of directories to search for header + files + --enable-deterministic # Enable Try to be as deterministic as possible + (used by the test suite) + --disable-deterministic # Disable Try to be as deterministic as possible + (used by the test suite) + --ipid=IPID # Installed package ID to compile this package + as + --cid=CID # Installed component ID to compile this + component as + --extra-lib-dirs=PATH # A list of directories to search for external + libraries + --extra-lib-dirs-static=PATH # A list of directories to search for external + libraries when linking fully static + executables + --extra-framework-dirs=PATH # A list of directories to search for external + frameworks (OS X only) + --extra-prog-path=PATH # A list of directories to search for required + programs (in addition to the normal search + locations) + --instantiate-with=NAME=MOD # A mapping of signature names to concrete + module instantiations. + --enable-tests # Enable dependency checking and compilation for + test suites listed in the package description + file. + --disable-tests # Disable dependency checking and compilation + for test suites listed in the package + description file. + --enable-coverage # Enable build package with Haskell Program + Coverage. (GHC only) + --disable-coverage # Disable build package with Haskell Program + Coverage. (GHC only) + --enable-library-coverage # Enable build package with Haskell Program + Coverage. (GHC only) (DEPRECATED) + --disable-library-coverage # Disable build package with Haskell Program + Coverage. (GHC only) (DEPRECATED) + --enable-benchmarks # Enable dependency checking and compilation for + benchmarks listed in the package description + file. + --disable-benchmarks # Disable dependency checking and compilation + for benchmarks listed in the package + description file. + --enable-relocatable # Enable building a package that is relocatable. + (GHC only) + --disable-relocatable # Disable building a package that is + relocatable. (GHC only) + --disable-response-files # Enable workaround for old versions of programs + like "ar" that do not support @file arguments + --allow-depending-on-private-libs + # Allow depending on private libraries. If set, + the library visibility check MUST be done + externally. + --coverage-for=UNITID # A list of unit-ids of libraries to include in + the Haskell Program Coverage report. + --ignore-build-tools # Ignore build tool dependencies. If set, + declared build tools needn't be found for + compilation to proceed. + --with-PROG=PATH # Give the path to PROG + --PROG-option=OPT # Give an extra option to PROG (passed directly + to PROG as a single argument) + --PROG-options=OPTS # Give extra options to PROG (split on spaces, + use "" to prevent splitting) + --cabal-lib-version=VERSION # Select which version of the Cabal lib to use + to build packages (useful for testing). + --enable-append # Enable appending the new config to the old + config file + --disable-append # Disable appending the new config to the old + config file + --enable-backup # Enable the backup of the config file before + any alterations + --disable-backup # Disable the backup of the config file before + any alterations + -c CONSTRAINT or -cCONSTRAINT, --constraint=CONSTRAINT + # Specify constraints on a package (version, + installed/source, flags) + --preference=CONSTRAINT # Specify preferences (soft constraints) on the + version of a package + --solver=SOLVER # Select dependency solver to use (default: + modular). Choices: modular. + --allow-older[=DEPS] # Ignore lower bounds in all dependencies or + DEPS + --allow-newer[=DEPS] # Ignore upper bounds in all dependencies or + DEPS + --write-ghc-environment-files=always|never|ghc8.4.4+ + # Whether to create a .ghc.environment file + after a successful build (v2-build only) + --enable-documentation # Enable building of documentation + --disable-documentation # Disable building of documentation + --doc-index-file=TEMPLATE # A central index of haddock API documentation + (template cannot use $pkgid) + --dry-run # Do not install anything, only print what would + be installed. + --only-download # Do not build anything, only fetch the + packages. + --max-backjumps=NUM # Maximum number of backjumps allowed while + solving (default: 4000). Use a negative number + to enable unlimited backtracking. Use 0 to + disable backtracking completely. + --reorder-goals # Try to reorder goals according to certain + heuristics. Slows things down on average, but + may make backtracking faster for some + packages. + --count-conflicts # Try to speed up solving by preferring goals + that are involved in a lot of conflicts + (default). + --fine-grained-conflicts # Skip a version of a package if it does not + resolve the conflicts encountered in the last + version, as a solver optimization (default). + --minimize-conflict-set # When there is no solution, try to improve the + error message by finding a minimal conflict + set (default: false). May increase run time + significantly. + --independent-goals # Treat several goals on the command line as + independent. If several goals depend on the + same package, different versions can be + chosen. + --prefer-oldest # Prefer the oldest (instead of the latest) + versions of packages available. Useful to + determine lower bounds in the build-depends + section. + --prefer-version=oldest|latest|installed-or-latest + # Select which version of a package that the + solver should prefer. Oldest is useful to + determine lower bounds in build-depends + section. Latest will prefer the latest + version. Installed-or-latest will prefer + installed versions and the latest version + otherwise. + --shadow-installed-packages # If multiple package instances of the same + version are installed, treat all but one as + shadowed. + --strong-flags # Do not defer flag choices (this used to be the + default in cabal-install <= 1.20). + --allow-boot-library-installs + # Allow cabal to install base, ghc-prim, + integer-simple, integer-gmp, and + template-haskell. + --reject-unconstrained-dependencies=none|all + # Require these packages to have constraints on + them if they are to be selected (default: + none). + --reinstall # Install even if it means installing the same + version again. + --avoid-reinstalls # Do not select versions that would + destructively overwrite installed packages. + --force-reinstalls # Reinstall packages even if they will most + likely break other installed packages. + --upgrade-dependencies # Pick the latest version for all dependencies, + rather than trying to pick an installed + version. + --only-dependencies # Install only the dependencies necessary to + build the given packages + --dependencies-only # A synonym for --only-dependencies + --index-state=STATE # Use source package index state as it existed + at a previous time. Accepts unix-timestamps + (e.g. '@1474732068'), ISO8601 UTC timestamps + (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' + (default: 'HEAD'). + --root-cmd=COMMAND # (No longer supported, do not use.) + --build-summary=TEMPLATE # Save build summaries to file (name template + can use $pkgid, $compiler, $os, $arch) + --build-log=TEMPLATE # Log all builds to file (name template can use + $pkgid, $compiler, $os, $arch) + --remote-build-reporting=LEVEL + # Generate build reports to send to a remote + server (none, anonymous or detailed). + --report-planning-failure # Generate build reports when the dependency + solver fails. This is used by the Hackage + build bot. + --enable-per-component # Enable Per-component builds when possible + --disable-per-component # Disable Per-component builds when possible + --run-tests # Run package test suites during installation. + --semaphore # Use a semaphore so GHC can compile components + in parallel + -j[NUM], --jobs[=NUM] # Run NUM jobs simultaneously (or '$ncpus' if no + NUM is given). + --keep-going # After a build failure, continue to build other + unaffected packages. + --offline # Don't download packages from the Internet. + --build-timings # Print elapsed time for each build phase. + --haddock-hoogle # Generate a hoogle database + --haddock-html # Generate HTML documentation (the default) + --haddock-html-location=URL # Location of HTML documentation for + pre-requisite packages + --haddock-for-hackage # Collection of flags to generate documentation + suitable for upload to hackage + --haddock-executables # Run haddock for Executables targets + --haddock-tests # Run haddock for Test Suite targets + --haddock-benchmarks # Run haddock for Benchmark targets + --haddock-all # Run haddock for all targets + --haddock-internal # Run haddock for internal modules and include + all symbols + --haddock-css=PATH # Use PATH as the haddock stylesheet + --haddock-hyperlink-source # Hyperlink the documentation to the source code + --haddock-quickjump # Generate an index for interactive + documentation navigation + --haddock-hscolour-css=PATH # Use PATH as the HsColour stylesheet + --haddock-contents-location=URL + # Bake URL in as the location for the contents + page + --haddock-base-url=URL # Base URL for static files. + --haddock-resources-dir=DIR # Location of Haddocks static / auxiliary files + --haddock-output-dir=DIR # Generate haddock documentation into this + directory. This flag is provided as a + technology preview and is subject to change in + the next releases. + --haddock-use-unicode # Pass --use-unicode option to haddock + --test-log=TEMPLATE # Log all test suite results to file (name + template can use $pkgid, $compiler, $os, + $arch, $test-suite, $result) + --test-machine-log=TEMPLATE # Produce a machine-readable log file (name + template can use $pkgid, $compiler, $os, + $arch, $result) + --test-show-details=FILTER # 'always': always show results of individual + test cases. 'never': never show results of + individual test cases. 'failures': show + results of failing test cases. 'streaming': + show results of test cases in real + time.'direct': send results of test cases in + real time; no log file. + --test-keep-tix-files # Keep .tix files for HPC between test runs + --test-wrapper=FILE # Run test through a wrapper. + --test-fail-when-no-test-suites + # Exit with failure when no test suites are + found. + --test-options=TEMPLATES # Give extra options to test executables (split + on spaces, use "" to prevent splitting; name + templates can use $pkgid, $compiler, $os, + $arch, $test-suite) + --test-option=TEMPLATE # Give extra option to test executables (passed + directly as a single argument; name template + can use $pkgid, $compiler, $os, $arch, + $test-suite) + --benchmark-options=TEMPLATES + # Give extra options to benchmark executables + (split on spaces, use "" to prevent splitting; + name templates can use $pkgid, $compiler, $os, + $arch, $benchmark) + --benchmark-option=TEMPLATE # Give extra option to benchmark executables + (passed directly as a single argument; name + template can use $pkgid, $compiler, $os, + $arch, $benchmark) + --project-dir=DIR # Set the path of the project directory + --project-file=FILE # Set the path of the cabal.project file + (relative to the project directory when + relative) + -z, --ignore-project # Ignore local project configuration (unless + --project-dir or --project-file is also set) + --project-file-parser=PARSER # Set the parser to use for the project file + --repl-no-load # Disable loading of project modules at REPL + startup. + --repl-options=FLAG # Use the option(s) for the repl + --repl-multi-file=DIR # Write repl options to this directory rather + than starting repl mode + --with-repl=PATH # Give the path to a program to use for REPL + -b DEPENDENCIES or -bDEPENDENCIES, --build-depends=DEPENDENCIES + # Include additional packages in the environment + presented to GHCi. + --no-transitive-deps # Don't automatically include transitive + dependencies of requested packages. + --enable-multi-repl # Enable multi-component repl sessions + --disable-multi-repl # Disable multi-component repl sessions + +Examples, open an interactive session: + cabal repl + for the default component in the package in the current directory + cabal repl pkgname + for the default component in the package named 'pkgname' + cabal repl ./pkgfoo + for the default component in the package in the ./pkgfoo directory + cabal repl cname + for the component named 'cname' + cabal repl pkgname:cname + for the component 'cname' in the package 'pkgname' + + cabal repl --build-depends lens + add the latest version of the library 'lens' to the default component (or no componentif there is no project present) + cabal repl --build-depends "lens >= 4.15 && < 4.18" + add a version (constrained between 4.15 and 4.18) of the library 'lens' to the default component (or no component if there is no project present) + cabal repl pkg:cabal-install-solver pkg:Cabal-syntax --enable-multi-repl + for default (in this case library) components in two packages diff --git a/doc/cmd-v2-help/report.txt b/doc/cmd-v2-help/report.txt new file mode 100644 index 00000000000..34ddedce86d --- /dev/null +++ b/doc/cmd-v2-help/report.txt @@ -0,0 +1,19 @@ +Upload build reports to a remote server. + +Usage: cabal report [FLAGS] + +Flags for report: + -h, --help # Show this help text + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + -t TOKEN or -tTOKEN, --token=TOKEN + # Hackage authentication Token. + -u USERNAME or -uUSERNAME, --username=USERNAME + # Hackage username. + -p PASSWORD or -pPASSWORD, --password=PASSWORD + # Hackage password. + -R REPOSITORY or -RREPOSITORY, --repository=REPOSITORY + # Package repository to upload to. + +You can store your Hackage login in the ~/.config/cabal/config file +(the %APPDATA%\cabal\config file on Windows) diff --git a/doc/cmd-v2-help/run.txt b/doc/cmd-v2-help/run.txt new file mode 100644 index 00000000000..f8dd2b32a58 --- /dev/null +++ b/doc/cmd-v2-help/run.txt @@ -0,0 +1,389 @@ +Run an executable. + +Usage: cabal run [TARGET] [FLAGS] [-- EXECUTABLE_FLAGS] + +Runs the specified executable-like component (an executable, a test, or a +benchmark), first ensuring it is up to date. + +Any executable-like component in any package in the project can be specified. +A package can be specified if contains just one executable-like, preferring a +single executable. The default is to use the package in the current directory +if it contains just one executable-like. + +Extra arguments can be passed to the program, but use '--' to separate +arguments for the program from arguments for cabal. The executable is run in +an environment where it can find its data files inplace in the build tree. + +Dependencies are built or rebuilt as necessary. Additional configuration flags +can be specified on the command line and these extend the project +configuration from the 'cabal.project', 'cabal.project.local' and other files. + +Flags for run: + -h, --help # Show this help text + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + --builddir=DIR # The directory where Cabal puts generated build + files (default dist) + --keep-temp-files # Keep temporary files. + -g, --ghc # Compile with GHC + --ghcjs # Compile with GHCJS + --uhc # Compile with UHC + -w PATH or -wPATH, --with-compiler=PATH + # Give the path to a particular compiler + --with-hc-pkg=PATH # Give the path to the package tool + --prefix=DIR # Bake this prefix in preparation of + installation + --bindir=DIR # Installation directory for executables + --libdir=DIR # Installation directory for libraries + --libsubdir=DIR # Subdirectory of libdir in which libs are + installed + --dynlibdir=DIR # Installation directory for dynamic libraries + --bytecodelibdir=DIR # Installation directory for bytecode libraries + --libexecdir=DIR # Installation directory for program executables + --libexecsubdir=DIR # Subdirectory of libexecdir in which private + executables are installed + --datadir=DIR # Installation directory for read-only data + --datasubdir=DIR # Subdirectory of datadir in which data files + are installed + --docdir=DIR # Installation directory for documentation + --htmldir=DIR # Installation directory for HTML documentation + --haddockdir=DIR # Installation directory for haddock interfaces + --sysconfdir=DIR # Installation directory for configuration files + --program-prefix=PREFIX # Prefix to be applied to installed executables + --program-suffix=SUFFIX # Suffix to be applied to installed executables + --enable-library-vanilla # Enable Vanilla libraries + --disable-library-vanilla # Disable Vanilla libraries + -p, --enable-library-profiling + # Enable Library profiling + --disable-library-profiling # Disable Library profiling + --enable-shared # Enable Shared library + --disable-shared # Disable Shared library + --enable-static # Enable Static library + --disable-static # Disable Static library + --enable-library-bytecode # Enable Bytecode library + --disable-library-bytecode # Disable Bytecode library + --enable-executable-dynamic # Enable Executable dynamic linking + --disable-executable-dynamic # Disable Executable dynamic linking + --enable-executable-static # Enable Executable fully static linking + --disable-executable-static # Disable Executable fully static linking + --enable-profiling # Enable Executable and library profiling + --disable-profiling # Disable Executable and library profiling + --enable-profiling-shared # Enable Build profiling shared libraries + --disable-profiling-shared # Disable Build profiling shared libraries + --enable-executable-profiling + # Enable Executable profiling (DEPRECATED) + --disable-executable-profiling + # Disable Executable profiling (DEPRECATED) + --profiling-detail=level # Profiling detail level for executable and + library (default, none, exported-functions, + toplevel-functions, all-functions, late). + --library-profiling-detail=level + # Profiling detail level for libraries only. + -O[n], --enable-optimization[=n] + # Build with optimization (n is 0--2, default is + 1) + --disable-optimization # Build without optimization + --enable-debug-info[=n] # Emit debug info (n is 0--3, default is 0) + --disable-debug-info # Don't emit debug info + --enable-build-info # Enable build information generation during + project building + --disable-build-info # Disable build information generation during + project building + --enable-library-for-ghci # Enable compile library for use with GHCi + --disable-library-for-ghci # Disable compile library for use with GHCi + --enable-split-sections # Enable compile library code such that unneeded + definitions can be dropped from the final + executable (GHC 7.8+) + --disable-split-sections # Disable compile library code such that + unneeded definitions can be dropped from the + final executable (GHC 7.8+) + --enable-split-objs # Enable split library into smaller objects to + reduce binary sizes (GHC 6.6+) + --disable-split-objs # Disable split library into smaller objects to + reduce binary sizes (GHC 6.6+) + --enable-executable-stripping + # Enable strip executables upon installation to + reduce binary sizes + --disable-executable-stripping + # Disable strip executables upon installation to + reduce binary sizes + --enable-library-stripping # Enable strip libraries upon installation to + reduce binary sizes + --disable-library-stripping # Disable strip libraries upon installation to + reduce binary sizes + --configure-option=OPT # Extra option for configure + --user # Enable doing a per-user installation + --global # Disable doing a per-user installation + --package-db=DB # Append the given package database to the list + of package databases used (to satisfy + dependencies and register into). May be a + specific file, 'global' or 'user'. The initial + list is ['global'], ['global', 'user'], or + ['global', $sandbox], depending on context. + Use 'clear' to reset the list to empty. See + the user guide for details. + -f FLAGS or -fFLAGS, --flags=FLAGS + # Force values for the given flags in Cabal + conditionals in the .cabal file. E.g., + --flags="debug -usebytestrings" forces the + flag "debug" to true and "usebytestrings" to + false. + --extra-include-dirs=PATH # A list of directories to search for header + files + --enable-deterministic # Enable Try to be as deterministic as possible + (used by the test suite) + --disable-deterministic # Disable Try to be as deterministic as possible + (used by the test suite) + --ipid=IPID # Installed package ID to compile this package + as + --cid=CID # Installed component ID to compile this + component as + --extra-lib-dirs=PATH # A list of directories to search for external + libraries + --extra-lib-dirs-static=PATH # A list of directories to search for external + libraries when linking fully static + executables + --extra-framework-dirs=PATH # A list of directories to search for external + frameworks (OS X only) + --extra-prog-path=PATH # A list of directories to search for required + programs (in addition to the normal search + locations) + --instantiate-with=NAME=MOD # A mapping of signature names to concrete + module instantiations. + --enable-tests # Enable dependency checking and compilation for + test suites listed in the package description + file. + --disable-tests # Disable dependency checking and compilation + for test suites listed in the package + description file. + --enable-coverage # Enable build package with Haskell Program + Coverage. (GHC only) + --disable-coverage # Disable build package with Haskell Program + Coverage. (GHC only) + --enable-library-coverage # Enable build package with Haskell Program + Coverage. (GHC only) (DEPRECATED) + --disable-library-coverage # Disable build package with Haskell Program + Coverage. (GHC only) (DEPRECATED) + --enable-benchmarks # Enable dependency checking and compilation for + benchmarks listed in the package description + file. + --disable-benchmarks # Disable dependency checking and compilation + for benchmarks listed in the package + description file. + --enable-relocatable # Enable building a package that is relocatable. + (GHC only) + --disable-relocatable # Disable building a package that is + relocatable. (GHC only) + --disable-response-files # Enable workaround for old versions of programs + like "ar" that do not support @file arguments + --allow-depending-on-private-libs + # Allow depending on private libraries. If set, + the library visibility check MUST be done + externally. + --coverage-for=UNITID # A list of unit-ids of libraries to include in + the Haskell Program Coverage report. + --ignore-build-tools # Ignore build tool dependencies. If set, + declared build tools needn't be found for + compilation to proceed. + --with-PROG=PATH # Give the path to PROG + --PROG-option=OPT # Give an extra option to PROG (passed directly + to PROG as a single argument) + --PROG-options=OPTS # Give extra options to PROG (split on spaces, + use "" to prevent splitting) + --cabal-lib-version=VERSION # Select which version of the Cabal lib to use + to build packages (useful for testing). + --enable-append # Enable appending the new config to the old + config file + --disable-append # Disable appending the new config to the old + config file + --enable-backup # Enable the backup of the config file before + any alterations + --disable-backup # Disable the backup of the config file before + any alterations + -c CONSTRAINT or -cCONSTRAINT, --constraint=CONSTRAINT + # Specify constraints on a package (version, + installed/source, flags) + --preference=CONSTRAINT # Specify preferences (soft constraints) on the + version of a package + --solver=SOLVER # Select dependency solver to use (default: + modular). Choices: modular. + --allow-older[=DEPS] # Ignore lower bounds in all dependencies or + DEPS + --allow-newer[=DEPS] # Ignore upper bounds in all dependencies or + DEPS + --write-ghc-environment-files=always|never|ghc8.4.4+ + # Whether to create a .ghc.environment file + after a successful build (v2-build only) + --enable-documentation # Enable building of documentation + --disable-documentation # Disable building of documentation + --doc-index-file=TEMPLATE # A central index of haddock API documentation + (template cannot use $pkgid) + --dry-run # Do not install anything, only print what would + be installed. + --only-download # Do not build anything, only fetch the + packages. + --max-backjumps=NUM # Maximum number of backjumps allowed while + solving (default: 4000). Use a negative number + to enable unlimited backtracking. Use 0 to + disable backtracking completely. + --reorder-goals # Try to reorder goals according to certain + heuristics. Slows things down on average, but + may make backtracking faster for some + packages. + --count-conflicts # Try to speed up solving by preferring goals + that are involved in a lot of conflicts + (default). + --fine-grained-conflicts # Skip a version of a package if it does not + resolve the conflicts encountered in the last + version, as a solver optimization (default). + --minimize-conflict-set # When there is no solution, try to improve the + error message by finding a minimal conflict + set (default: false). May increase run time + significantly. + --independent-goals # Treat several goals on the command line as + independent. If several goals depend on the + same package, different versions can be + chosen. + --prefer-oldest # Prefer the oldest (instead of the latest) + versions of packages available. Useful to + determine lower bounds in the build-depends + section. + --prefer-version=oldest|latest|installed-or-latest + # Select which version of a package that the + solver should prefer. Oldest is useful to + determine lower bounds in build-depends + section. Latest will prefer the latest + version. Installed-or-latest will prefer + installed versions and the latest version + otherwise. + --shadow-installed-packages # If multiple package instances of the same + version are installed, treat all but one as + shadowed. + --strong-flags # Do not defer flag choices (this used to be the + default in cabal-install <= 1.20). + --allow-boot-library-installs + # Allow cabal to install base, ghc-prim, + integer-simple, integer-gmp, and + template-haskell. + --reject-unconstrained-dependencies=none|all + # Require these packages to have constraints on + them if they are to be selected (default: + none). + --reinstall # Install even if it means installing the same + version again. + --avoid-reinstalls # Do not select versions that would + destructively overwrite installed packages. + --force-reinstalls # Reinstall packages even if they will most + likely break other installed packages. + --upgrade-dependencies # Pick the latest version for all dependencies, + rather than trying to pick an installed + version. + --only-dependencies # Install only the dependencies necessary to + build the given packages + --dependencies-only # A synonym for --only-dependencies + --index-state=STATE # Use source package index state as it existed + at a previous time. Accepts unix-timestamps + (e.g. '@1474732068'), ISO8601 UTC timestamps + (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' + (default: 'HEAD'). + --root-cmd=COMMAND # (No longer supported, do not use.) + --build-summary=TEMPLATE # Save build summaries to file (name template + can use $pkgid, $compiler, $os, $arch) + --build-log=TEMPLATE # Log all builds to file (name template can use + $pkgid, $compiler, $os, $arch) + --remote-build-reporting=LEVEL + # Generate build reports to send to a remote + server (none, anonymous or detailed). + --report-planning-failure # Generate build reports when the dependency + solver fails. This is used by the Hackage + build bot. + --enable-per-component # Enable Per-component builds when possible + --disable-per-component # Disable Per-component builds when possible + --run-tests # Run package test suites during installation. + --semaphore # Use a semaphore so GHC can compile components + in parallel + -j[NUM], --jobs[=NUM] # Run NUM jobs simultaneously (or '$ncpus' if no + NUM is given). + --keep-going # After a build failure, continue to build other + unaffected packages. + --offline # Don't download packages from the Internet. + --build-timings # Print elapsed time for each build phase. + --haddock-hoogle # Generate a hoogle database + --haddock-html # Generate HTML documentation (the default) + --haddock-html-location=URL # Location of HTML documentation for + pre-requisite packages + --haddock-for-hackage # Collection of flags to generate documentation + suitable for upload to hackage + --haddock-executables # Run haddock for Executables targets + --haddock-tests # Run haddock for Test Suite targets + --haddock-benchmarks # Run haddock for Benchmark targets + --haddock-all # Run haddock for all targets + --haddock-internal # Run haddock for internal modules and include + all symbols + --haddock-css=PATH # Use PATH as the haddock stylesheet + --haddock-hyperlink-source # Hyperlink the documentation to the source code + --haddock-quickjump # Generate an index for interactive + documentation navigation + --haddock-hscolour-css=PATH # Use PATH as the HsColour stylesheet + --haddock-contents-location=URL + # Bake URL in as the location for the contents + page + --haddock-base-url=URL # Base URL for static files. + --haddock-resources-dir=DIR # Location of Haddocks static / auxiliary files + --haddock-output-dir=DIR # Generate haddock documentation into this + directory. This flag is provided as a + technology preview and is subject to change in + the next releases. + --haddock-use-unicode # Pass --use-unicode option to haddock + --test-log=TEMPLATE # Log all test suite results to file (name + template can use $pkgid, $compiler, $os, + $arch, $test-suite, $result) + --test-machine-log=TEMPLATE # Produce a machine-readable log file (name + template can use $pkgid, $compiler, $os, + $arch, $result) + --test-show-details=FILTER # 'always': always show results of individual + test cases. 'never': never show results of + individual test cases. 'failures': show + results of failing test cases. 'streaming': + show results of test cases in real + time.'direct': send results of test cases in + real time; no log file. + --test-keep-tix-files # Keep .tix files for HPC between test runs + --test-wrapper=FILE # Run test through a wrapper. + --test-fail-when-no-test-suites + # Exit with failure when no test suites are + found. + --test-options=TEMPLATES # Give extra options to test executables (split + on spaces, use "" to prevent splitting; name + templates can use $pkgid, $compiler, $os, + $arch, $test-suite) + --test-option=TEMPLATE # Give extra option to test executables (passed + directly as a single argument; name template + can use $pkgid, $compiler, $os, $arch, + $test-suite) + --benchmark-options=TEMPLATES + # Give extra options to benchmark executables + (split on spaces, use "" to prevent splitting; + name templates can use $pkgid, $compiler, $os, + $arch, $benchmark) + --benchmark-option=TEMPLATE # Give extra option to benchmark executables + (passed directly as a single argument; name + template can use $pkgid, $compiler, $os, + $arch, $benchmark) + --project-dir=DIR # Set the path of the project directory + --project-file=FILE # Set the path of the cabal.project file + (relative to the project directory when + relative) + -z, --ignore-project # Ignore local project configuration (unless + --project-dir or --project-file is also set) + --project-file-parser=PARSER # Set the parser to use for the project file + +Examples: + cabal run + Run the executable-like in the package in the current directory + cabal run foo-tool + Run the named executable-like (in any package in the project) + cabal run pkgfoo:foo-tool + Run the executable-like 'foo-tool' in the package 'pkgfoo' + cabal run foo -O2 -- dothing --fooflag + Build with '-O2' and run the program, passing it extra arguments. diff --git a/doc/cmd-v2-help/sdist.txt b/doc/cmd-v2-help/sdist.txt new file mode 100644 index 00000000000..8b40e1127a5 --- /dev/null +++ b/doc/cmd-v2-help/sdist.txt @@ -0,0 +1,25 @@ +Generate a source distribution file (.tar.gz). + +Usage: cabal sdist [FLAGS] [PACKAGES] + +Generates tarballs of project packages suitable for upload to Hackage. + +Flags for sdist: + -h, --help # Show this help text + --project-dir=DIR # Set the path of the project directory + --project-file=FILE # Set the path of the cabal.project file + (relative to the project directory when + relative) + -z, --ignore-project # Ignore local project configuration (unless + --project-dir or --project-file is also set) + --project-file-parser=PARSER # Set the parser to use for the project file + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + --builddir=DIR # The directory where Cabal puts generated build + files (default dist) + -l, --list-only # Just list the sources, do not make a tarball + --null-sep # Separate the source files with NUL bytes + rather than newlines. + -o PATH or -oPATH, --output-directory=PATH + # Choose the output directory of this command. + '-' sends all output to stdout diff --git a/doc/cmd-v2-help/target.txt b/doc/cmd-v2-help/target.txt new file mode 100644 index 00000000000..6dddae62364 --- /dev/null +++ b/doc/cmd-v2-help/target.txt @@ -0,0 +1,405 @@ +Target a subset of all targets. + +Usage: cabal target [TARGETS] + +Discover targets in a project for use with other commands taking [TARGETS]. + +This command, like many others, takes [TARGETS]. Taken together, these will +select for a set of targets in the project. When none are supplied, the +command acts as if 'all' was supplied. Targets in the returned subset are +shown sorted and fully-qualified. + +A [TARGETS] item can be one of these target forms: + - a package target (e.g. [pkg:]package) + - a component target (e.g. [package:][ctype:]component) + - all packages (e.g. all) + - components of a particular type (e.g. package:ctypes or all:ctypes) + - a module target: (e.g. [package:][ctype:]module) + - a filepath target: (e.g. [package:][ctype:]filepath) + +The ctypes, in short form and (long form), can be one of: + - libs (libraries) + - exes (executables) + - tests + - benches (benchmarks) + - flibs (foreign-libraries) + +WARNING: For a package, all, module or filepath target, cabal target [TARGETS] +will only show 'libs' and 'exes' of the [TARGETS] by default. To also show +tests and benchmarks, enable them with '--enable-tests' and +'--enable-benchmarks'. + +NOTE: For commands expecting a unique TARGET, a fully-qualified target is the +safe way to go but it may be convenient to type out a shorter TARGET. For +example, if the set of 'cabal target all:exes' has one item then 'cabal +list-bin all:exes' will work too. + +Flags for target: + -h, --help # Show this help text + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + --builddir=DIR # The directory where Cabal puts generated build + files (default dist) + --keep-temp-files # Keep temporary files. + -g, --ghc # Compile with GHC + --ghcjs # Compile with GHCJS + --uhc # Compile with UHC + -w PATH or -wPATH, --with-compiler=PATH + # Give the path to a particular compiler + --with-hc-pkg=PATH # Give the path to the package tool + --prefix=DIR # Bake this prefix in preparation of + installation + --bindir=DIR # Installation directory for executables + --libdir=DIR # Installation directory for libraries + --libsubdir=DIR # Subdirectory of libdir in which libs are + installed + --dynlibdir=DIR # Installation directory for dynamic libraries + --bytecodelibdir=DIR # Installation directory for bytecode libraries + --libexecdir=DIR # Installation directory for program executables + --libexecsubdir=DIR # Subdirectory of libexecdir in which private + executables are installed + --datadir=DIR # Installation directory for read-only data + --datasubdir=DIR # Subdirectory of datadir in which data files + are installed + --docdir=DIR # Installation directory for documentation + --htmldir=DIR # Installation directory for HTML documentation + --haddockdir=DIR # Installation directory for haddock interfaces + --sysconfdir=DIR # Installation directory for configuration files + --program-prefix=PREFIX # Prefix to be applied to installed executables + --program-suffix=SUFFIX # Suffix to be applied to installed executables + --enable-library-vanilla # Enable Vanilla libraries + --disable-library-vanilla # Disable Vanilla libraries + -p, --enable-library-profiling + # Enable Library profiling + --disable-library-profiling # Disable Library profiling + --enable-shared # Enable Shared library + --disable-shared # Disable Shared library + --enable-static # Enable Static library + --disable-static # Disable Static library + --enable-library-bytecode # Enable Bytecode library + --disable-library-bytecode # Disable Bytecode library + --enable-executable-dynamic # Enable Executable dynamic linking + --disable-executable-dynamic # Disable Executable dynamic linking + --enable-executable-static # Enable Executable fully static linking + --disable-executable-static # Disable Executable fully static linking + --enable-profiling # Enable Executable and library profiling + --disable-profiling # Disable Executable and library profiling + --enable-profiling-shared # Enable Build profiling shared libraries + --disable-profiling-shared # Disable Build profiling shared libraries + --enable-executable-profiling + # Enable Executable profiling (DEPRECATED) + --disable-executable-profiling + # Disable Executable profiling (DEPRECATED) + --profiling-detail=level # Profiling detail level for executable and + library (default, none, exported-functions, + toplevel-functions, all-functions, late). + --library-profiling-detail=level + # Profiling detail level for libraries only. + -O[n], --enable-optimization[=n] + # Build with optimization (n is 0--2, default is + 1) + --disable-optimization # Build without optimization + --enable-debug-info[=n] # Emit debug info (n is 0--3, default is 0) + --disable-debug-info # Don't emit debug info + --enable-build-info # Enable build information generation during + project building + --disable-build-info # Disable build information generation during + project building + --enable-library-for-ghci # Enable compile library for use with GHCi + --disable-library-for-ghci # Disable compile library for use with GHCi + --enable-split-sections # Enable compile library code such that unneeded + definitions can be dropped from the final + executable (GHC 7.8+) + --disable-split-sections # Disable compile library code such that + unneeded definitions can be dropped from the + final executable (GHC 7.8+) + --enable-split-objs # Enable split library into smaller objects to + reduce binary sizes (GHC 6.6+) + --disable-split-objs # Disable split library into smaller objects to + reduce binary sizes (GHC 6.6+) + --enable-executable-stripping + # Enable strip executables upon installation to + reduce binary sizes + --disable-executable-stripping + # Disable strip executables upon installation to + reduce binary sizes + --enable-library-stripping # Enable strip libraries upon installation to + reduce binary sizes + --disable-library-stripping # Disable strip libraries upon installation to + reduce binary sizes + --configure-option=OPT # Extra option for configure + --user # Enable doing a per-user installation + --global # Disable doing a per-user installation + --package-db=DB # Append the given package database to the list + of package databases used (to satisfy + dependencies and register into). May be a + specific file, 'global' or 'user'. The initial + list is ['global'], ['global', 'user'], or + ['global', $sandbox], depending on context. + Use 'clear' to reset the list to empty. See + the user guide for details. + -f FLAGS or -fFLAGS, --flags=FLAGS + # Force values for the given flags in Cabal + conditionals in the .cabal file. E.g., + --flags="debug -usebytestrings" forces the + flag "debug" to true and "usebytestrings" to + false. + --extra-include-dirs=PATH # A list of directories to search for header + files + --enable-deterministic # Enable Try to be as deterministic as possible + (used by the test suite) + --disable-deterministic # Disable Try to be as deterministic as possible + (used by the test suite) + --ipid=IPID # Installed package ID to compile this package + as + --cid=CID # Installed component ID to compile this + component as + --extra-lib-dirs=PATH # A list of directories to search for external + libraries + --extra-lib-dirs-static=PATH # A list of directories to search for external + libraries when linking fully static + executables + --extra-framework-dirs=PATH # A list of directories to search for external + frameworks (OS X only) + --extra-prog-path=PATH # A list of directories to search for required + programs (in addition to the normal search + locations) + --instantiate-with=NAME=MOD # A mapping of signature names to concrete + module instantiations. + --enable-tests # Enable dependency checking and compilation for + test suites listed in the package description + file. + --disable-tests # Disable dependency checking and compilation + for test suites listed in the package + description file. + --enable-coverage # Enable build package with Haskell Program + Coverage. (GHC only) + --disable-coverage # Disable build package with Haskell Program + Coverage. (GHC only) + --enable-library-coverage # Enable build package with Haskell Program + Coverage. (GHC only) (DEPRECATED) + --disable-library-coverage # Disable build package with Haskell Program + Coverage. (GHC only) (DEPRECATED) + --enable-benchmarks # Enable dependency checking and compilation for + benchmarks listed in the package description + file. + --disable-benchmarks # Disable dependency checking and compilation + for benchmarks listed in the package + description file. + --enable-relocatable # Enable building a package that is relocatable. + (GHC only) + --disable-relocatable # Disable building a package that is + relocatable. (GHC only) + --disable-response-files # Enable workaround for old versions of programs + like "ar" that do not support @file arguments + --allow-depending-on-private-libs + # Allow depending on private libraries. If set, + the library visibility check MUST be done + externally. + --coverage-for=UNITID # A list of unit-ids of libraries to include in + the Haskell Program Coverage report. + --ignore-build-tools # Ignore build tool dependencies. If set, + declared build tools needn't be found for + compilation to proceed. + --with-PROG=PATH # Give the path to PROG + --PROG-option=OPT # Give an extra option to PROG (passed directly + to PROG as a single argument) + --PROG-options=OPTS # Give extra options to PROG (split on spaces, + use "" to prevent splitting) + --cabal-lib-version=VERSION # Select which version of the Cabal lib to use + to build packages (useful for testing). + --enable-append # Enable appending the new config to the old + config file + --disable-append # Disable appending the new config to the old + config file + --enable-backup # Enable the backup of the config file before + any alterations + --disable-backup # Disable the backup of the config file before + any alterations + -c CONSTRAINT or -cCONSTRAINT, --constraint=CONSTRAINT + # Specify constraints on a package (version, + installed/source, flags) + --preference=CONSTRAINT # Specify preferences (soft constraints) on the + version of a package + --solver=SOLVER # Select dependency solver to use (default: + modular). Choices: modular. + --allow-older[=DEPS] # Ignore lower bounds in all dependencies or + DEPS + --allow-newer[=DEPS] # Ignore upper bounds in all dependencies or + DEPS + --write-ghc-environment-files=always|never|ghc8.4.4+ + # Whether to create a .ghc.environment file + after a successful build (v2-build only) + --enable-documentation # Enable building of documentation + --disable-documentation # Disable building of documentation + --doc-index-file=TEMPLATE # A central index of haddock API documentation + (template cannot use $pkgid) + --dry-run # Do not install anything, only print what would + be installed. + --only-download # Do not build anything, only fetch the + packages. + --max-backjumps=NUM # Maximum number of backjumps allowed while + solving (default: 4000). Use a negative number + to enable unlimited backtracking. Use 0 to + disable backtracking completely. + --reorder-goals # Try to reorder goals according to certain + heuristics. Slows things down on average, but + may make backtracking faster for some + packages. + --count-conflicts # Try to speed up solving by preferring goals + that are involved in a lot of conflicts + (default). + --fine-grained-conflicts # Skip a version of a package if it does not + resolve the conflicts encountered in the last + version, as a solver optimization (default). + --minimize-conflict-set # When there is no solution, try to improve the + error message by finding a minimal conflict + set (default: false). May increase run time + significantly. + --independent-goals # Treat several goals on the command line as + independent. If several goals depend on the + same package, different versions can be + chosen. + --prefer-oldest # Prefer the oldest (instead of the latest) + versions of packages available. Useful to + determine lower bounds in the build-depends + section. + --prefer-version=oldest|latest|installed-or-latest + # Select which version of a package that the + solver should prefer. Oldest is useful to + determine lower bounds in build-depends + section. Latest will prefer the latest + version. Installed-or-latest will prefer + installed versions and the latest version + otherwise. + --shadow-installed-packages # If multiple package instances of the same + version are installed, treat all but one as + shadowed. + --strong-flags # Do not defer flag choices (this used to be the + default in cabal-install <= 1.20). + --allow-boot-library-installs + # Allow cabal to install base, ghc-prim, + integer-simple, integer-gmp, and + template-haskell. + --reject-unconstrained-dependencies=none|all + # Require these packages to have constraints on + them if they are to be selected (default: + none). + --reinstall # Install even if it means installing the same + version again. + --avoid-reinstalls # Do not select versions that would + destructively overwrite installed packages. + --force-reinstalls # Reinstall packages even if they will most + likely break other installed packages. + --upgrade-dependencies # Pick the latest version for all dependencies, + rather than trying to pick an installed + version. + --only-dependencies # Install only the dependencies necessary to + build the given packages + --dependencies-only # A synonym for --only-dependencies + --index-state=STATE # Use source package index state as it existed + at a previous time. Accepts unix-timestamps + (e.g. '@1474732068'), ISO8601 UTC timestamps + (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' + (default: 'HEAD'). + --root-cmd=COMMAND # (No longer supported, do not use.) + --build-summary=TEMPLATE # Save build summaries to file (name template + can use $pkgid, $compiler, $os, $arch) + --build-log=TEMPLATE # Log all builds to file (name template can use + $pkgid, $compiler, $os, $arch) + --remote-build-reporting=LEVEL + # Generate build reports to send to a remote + server (none, anonymous or detailed). + --report-planning-failure # Generate build reports when the dependency + solver fails. This is used by the Hackage + build bot. + --enable-per-component # Enable Per-component builds when possible + --disable-per-component # Disable Per-component builds when possible + --run-tests # Run package test suites during installation. + --semaphore # Use a semaphore so GHC can compile components + in parallel + -j[NUM], --jobs[=NUM] # Run NUM jobs simultaneously (or '$ncpus' if no + NUM is given). + --keep-going # After a build failure, continue to build other + unaffected packages. + --offline # Don't download packages from the Internet. + --build-timings # Print elapsed time for each build phase. + --haddock-hoogle # Generate a hoogle database + --haddock-html # Generate HTML documentation (the default) + --haddock-html-location=URL # Location of HTML documentation for + pre-requisite packages + --haddock-for-hackage # Collection of flags to generate documentation + suitable for upload to hackage + --haddock-executables # Run haddock for Executables targets + --haddock-tests # Run haddock for Test Suite targets + --haddock-benchmarks # Run haddock for Benchmark targets + --haddock-all # Run haddock for all targets + --haddock-internal # Run haddock for internal modules and include + all symbols + --haddock-css=PATH # Use PATH as the haddock stylesheet + --haddock-hyperlink-source # Hyperlink the documentation to the source code + --haddock-quickjump # Generate an index for interactive + documentation navigation + --haddock-hscolour-css=PATH # Use PATH as the HsColour stylesheet + --haddock-contents-location=URL + # Bake URL in as the location for the contents + page + --haddock-base-url=URL # Base URL for static files. + --haddock-resources-dir=DIR # Location of Haddocks static / auxiliary files + --haddock-output-dir=DIR # Generate haddock documentation into this + directory. This flag is provided as a + technology preview and is subject to change in + the next releases. + --haddock-use-unicode # Pass --use-unicode option to haddock + --test-log=TEMPLATE # Log all test suite results to file (name + template can use $pkgid, $compiler, $os, + $arch, $test-suite, $result) + --test-machine-log=TEMPLATE # Produce a machine-readable log file (name + template can use $pkgid, $compiler, $os, + $arch, $result) + --test-show-details=FILTER # 'always': always show results of individual + test cases. 'never': never show results of + individual test cases. 'failures': show + results of failing test cases. 'streaming': + show results of test cases in real + time.'direct': send results of test cases in + real time; no log file. + --test-keep-tix-files # Keep .tix files for HPC between test runs + --test-wrapper=FILE # Run test through a wrapper. + --test-fail-when-no-test-suites + # Exit with failure when no test suites are + found. + --test-options=TEMPLATES # Give extra options to test executables (split + on spaces, use "" to prevent splitting; name + templates can use $pkgid, $compiler, $os, + $arch, $test-suite) + --test-option=TEMPLATE # Give extra option to test executables (passed + directly as a single argument; name template + can use $pkgid, $compiler, $os, $arch, + $test-suite) + --benchmark-options=TEMPLATES + # Give extra options to benchmark executables + (split on spaces, use "" to prevent splitting; + name templates can use $pkgid, $compiler, $os, + $arch, $benchmark) + --benchmark-option=TEMPLATE # Give extra option to benchmark executables + (passed directly as a single argument; name + template can use $pkgid, $compiler, $os, + $arch, $benchmark) + --project-dir=DIR # Set the path of the project directory + --project-file=FILE # Set the path of the cabal.project file + (relative to the project directory when + relative) + -z, --ignore-project # Ignore local project configuration (unless + --project-dir or --project-file is also set) + --project-file-parser=PARSER # Set the parser to use for the project file + +Examples: + cabal target all + Targets of the package in the current directory or all packages in the project + cabal target pkgname + Targets of the package named pkgname in the project + cabal target ./pkgfoo + Targets of the package in the ./pkgfoo directory + cabal target cname + Targets of the component named cname in the project diff --git a/doc/cmd-v2-help/test.txt b/doc/cmd-v2-help/test.txt new file mode 100644 index 00000000000..00c529d1a3b --- /dev/null +++ b/doc/cmd-v2-help/test.txt @@ -0,0 +1,385 @@ +Run test-suites. + +Usage: cabal test [TARGETS] [FLAGS] + +Runs the specified test-suites, first ensuring they are up to date. + +Any test-suite in any package in the project can be specified. A package can +be specified in which case all the test-suites in the package are run. The +default is to run all the test-suites in the package in the current directory. + +Dependencies are built or rebuilt as necessary. Additional configuration flags +can be specified on the command line and these extend the project +configuration from the 'cabal.project', 'cabal.project.local' and other files. + +To pass command-line arguments to a test suite, see the run command. + +Flags for test: + -h, --help # Show this help text + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + --builddir=DIR # The directory where Cabal puts generated build + files (default dist) + --keep-temp-files # Keep temporary files. + -g, --ghc # Compile with GHC + --ghcjs # Compile with GHCJS + --uhc # Compile with UHC + -w PATH or -wPATH, --with-compiler=PATH + # Give the path to a particular compiler + --with-hc-pkg=PATH # Give the path to the package tool + --prefix=DIR # Bake this prefix in preparation of + installation + --bindir=DIR # Installation directory for executables + --libdir=DIR # Installation directory for libraries + --libsubdir=DIR # Subdirectory of libdir in which libs are + installed + --dynlibdir=DIR # Installation directory for dynamic libraries + --bytecodelibdir=DIR # Installation directory for bytecode libraries + --libexecdir=DIR # Installation directory for program executables + --libexecsubdir=DIR # Subdirectory of libexecdir in which private + executables are installed + --datadir=DIR # Installation directory for read-only data + --datasubdir=DIR # Subdirectory of datadir in which data files + are installed + --docdir=DIR # Installation directory for documentation + --htmldir=DIR # Installation directory for HTML documentation + --haddockdir=DIR # Installation directory for haddock interfaces + --sysconfdir=DIR # Installation directory for configuration files + --program-prefix=PREFIX # Prefix to be applied to installed executables + --program-suffix=SUFFIX # Suffix to be applied to installed executables + --enable-library-vanilla # Enable Vanilla libraries + --disable-library-vanilla # Disable Vanilla libraries + -p, --enable-library-profiling + # Enable Library profiling + --disable-library-profiling # Disable Library profiling + --enable-shared # Enable Shared library + --disable-shared # Disable Shared library + --enable-static # Enable Static library + --disable-static # Disable Static library + --enable-library-bytecode # Enable Bytecode library + --disable-library-bytecode # Disable Bytecode library + --enable-executable-dynamic # Enable Executable dynamic linking + --disable-executable-dynamic # Disable Executable dynamic linking + --enable-executable-static # Enable Executable fully static linking + --disable-executable-static # Disable Executable fully static linking + --enable-profiling # Enable Executable and library profiling + --disable-profiling # Disable Executable and library profiling + --enable-profiling-shared # Enable Build profiling shared libraries + --disable-profiling-shared # Disable Build profiling shared libraries + --enable-executable-profiling + # Enable Executable profiling (DEPRECATED) + --disable-executable-profiling + # Disable Executable profiling (DEPRECATED) + --profiling-detail=level # Profiling detail level for executable and + library (default, none, exported-functions, + toplevel-functions, all-functions, late). + --library-profiling-detail=level + # Profiling detail level for libraries only. + -O[n], --enable-optimization[=n] + # Build with optimization (n is 0--2, default is + 1) + --disable-optimization # Build without optimization + --enable-debug-info[=n] # Emit debug info (n is 0--3, default is 0) + --disable-debug-info # Don't emit debug info + --enable-build-info # Enable build information generation during + project building + --disable-build-info # Disable build information generation during + project building + --enable-library-for-ghci # Enable compile library for use with GHCi + --disable-library-for-ghci # Disable compile library for use with GHCi + --enable-split-sections # Enable compile library code such that unneeded + definitions can be dropped from the final + executable (GHC 7.8+) + --disable-split-sections # Disable compile library code such that + unneeded definitions can be dropped from the + final executable (GHC 7.8+) + --enable-split-objs # Enable split library into smaller objects to + reduce binary sizes (GHC 6.6+) + --disable-split-objs # Disable split library into smaller objects to + reduce binary sizes (GHC 6.6+) + --enable-executable-stripping + # Enable strip executables upon installation to + reduce binary sizes + --disable-executable-stripping + # Disable strip executables upon installation to + reduce binary sizes + --enable-library-stripping # Enable strip libraries upon installation to + reduce binary sizes + --disable-library-stripping # Disable strip libraries upon installation to + reduce binary sizes + --configure-option=OPT # Extra option for configure + --user # Enable doing a per-user installation + --global # Disable doing a per-user installation + --package-db=DB # Append the given package database to the list + of package databases used (to satisfy + dependencies and register into). May be a + specific file, 'global' or 'user'. The initial + list is ['global'], ['global', 'user'], or + ['global', $sandbox], depending on context. + Use 'clear' to reset the list to empty. See + the user guide for details. + -f FLAGS or -fFLAGS, --flags=FLAGS + # Force values for the given flags in Cabal + conditionals in the .cabal file. E.g., + --flags="debug -usebytestrings" forces the + flag "debug" to true and "usebytestrings" to + false. + --extra-include-dirs=PATH # A list of directories to search for header + files + --enable-deterministic # Enable Try to be as deterministic as possible + (used by the test suite) + --disable-deterministic # Disable Try to be as deterministic as possible + (used by the test suite) + --ipid=IPID # Installed package ID to compile this package + as + --cid=CID # Installed component ID to compile this + component as + --extra-lib-dirs=PATH # A list of directories to search for external + libraries + --extra-lib-dirs-static=PATH # A list of directories to search for external + libraries when linking fully static + executables + --extra-framework-dirs=PATH # A list of directories to search for external + frameworks (OS X only) + --extra-prog-path=PATH # A list of directories to search for required + programs (in addition to the normal search + locations) + --instantiate-with=NAME=MOD # A mapping of signature names to concrete + module instantiations. + --enable-tests # Enable dependency checking and compilation for + test suites listed in the package description + file. + --disable-tests # Disable dependency checking and compilation + for test suites listed in the package + description file. + --enable-coverage # Enable build package with Haskell Program + Coverage. (GHC only) + --disable-coverage # Disable build package with Haskell Program + Coverage. (GHC only) + --enable-library-coverage # Enable build package with Haskell Program + Coverage. (GHC only) (DEPRECATED) + --disable-library-coverage # Disable build package with Haskell Program + Coverage. (GHC only) (DEPRECATED) + --enable-benchmarks # Enable dependency checking and compilation for + benchmarks listed in the package description + file. + --disable-benchmarks # Disable dependency checking and compilation + for benchmarks listed in the package + description file. + --enable-relocatable # Enable building a package that is relocatable. + (GHC only) + --disable-relocatable # Disable building a package that is + relocatable. (GHC only) + --disable-response-files # Enable workaround for old versions of programs + like "ar" that do not support @file arguments + --allow-depending-on-private-libs + # Allow depending on private libraries. If set, + the library visibility check MUST be done + externally. + --coverage-for=UNITID # A list of unit-ids of libraries to include in + the Haskell Program Coverage report. + --ignore-build-tools # Ignore build tool dependencies. If set, + declared build tools needn't be found for + compilation to proceed. + --with-PROG=PATH # Give the path to PROG + --PROG-option=OPT # Give an extra option to PROG (passed directly + to PROG as a single argument) + --PROG-options=OPTS # Give extra options to PROG (split on spaces, + use "" to prevent splitting) + --cabal-lib-version=VERSION # Select which version of the Cabal lib to use + to build packages (useful for testing). + --enable-append # Enable appending the new config to the old + config file + --disable-append # Disable appending the new config to the old + config file + --enable-backup # Enable the backup of the config file before + any alterations + --disable-backup # Disable the backup of the config file before + any alterations + -c CONSTRAINT or -cCONSTRAINT, --constraint=CONSTRAINT + # Specify constraints on a package (version, + installed/source, flags) + --preference=CONSTRAINT # Specify preferences (soft constraints) on the + version of a package + --solver=SOLVER # Select dependency solver to use (default: + modular). Choices: modular. + --allow-older[=DEPS] # Ignore lower bounds in all dependencies or + DEPS + --allow-newer[=DEPS] # Ignore upper bounds in all dependencies or + DEPS + --write-ghc-environment-files=always|never|ghc8.4.4+ + # Whether to create a .ghc.environment file + after a successful build (v2-build only) + --enable-documentation # Enable building of documentation + --disable-documentation # Disable building of documentation + --doc-index-file=TEMPLATE # A central index of haddock API documentation + (template cannot use $pkgid) + --dry-run # Do not install anything, only print what would + be installed. + --only-download # Do not build anything, only fetch the + packages. + --max-backjumps=NUM # Maximum number of backjumps allowed while + solving (default: 4000). Use a negative number + to enable unlimited backtracking. Use 0 to + disable backtracking completely. + --reorder-goals # Try to reorder goals according to certain + heuristics. Slows things down on average, but + may make backtracking faster for some + packages. + --count-conflicts # Try to speed up solving by preferring goals + that are involved in a lot of conflicts + (default). + --fine-grained-conflicts # Skip a version of a package if it does not + resolve the conflicts encountered in the last + version, as a solver optimization (default). + --minimize-conflict-set # When there is no solution, try to improve the + error message by finding a minimal conflict + set (default: false). May increase run time + significantly. + --independent-goals # Treat several goals on the command line as + independent. If several goals depend on the + same package, different versions can be + chosen. + --prefer-oldest # Prefer the oldest (instead of the latest) + versions of packages available. Useful to + determine lower bounds in the build-depends + section. + --prefer-version=oldest|latest|installed-or-latest + # Select which version of a package that the + solver should prefer. Oldest is useful to + determine lower bounds in build-depends + section. Latest will prefer the latest + version. Installed-or-latest will prefer + installed versions and the latest version + otherwise. + --shadow-installed-packages # If multiple package instances of the same + version are installed, treat all but one as + shadowed. + --strong-flags # Do not defer flag choices (this used to be the + default in cabal-install <= 1.20). + --allow-boot-library-installs + # Allow cabal to install base, ghc-prim, + integer-simple, integer-gmp, and + template-haskell. + --reject-unconstrained-dependencies=none|all + # Require these packages to have constraints on + them if they are to be selected (default: + none). + --reinstall # Install even if it means installing the same + version again. + --avoid-reinstalls # Do not select versions that would + destructively overwrite installed packages. + --force-reinstalls # Reinstall packages even if they will most + likely break other installed packages. + --upgrade-dependencies # Pick the latest version for all dependencies, + rather than trying to pick an installed + version. + --only-dependencies # Install only the dependencies necessary to + build the given packages + --dependencies-only # A synonym for --only-dependencies + --index-state=STATE # Use source package index state as it existed + at a previous time. Accepts unix-timestamps + (e.g. '@1474732068'), ISO8601 UTC timestamps + (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' + (default: 'HEAD'). + --root-cmd=COMMAND # (No longer supported, do not use.) + --build-summary=TEMPLATE # Save build summaries to file (name template + can use $pkgid, $compiler, $os, $arch) + --build-log=TEMPLATE # Log all builds to file (name template can use + $pkgid, $compiler, $os, $arch) + --remote-build-reporting=LEVEL + # Generate build reports to send to a remote + server (none, anonymous or detailed). + --report-planning-failure # Generate build reports when the dependency + solver fails. This is used by the Hackage + build bot. + --enable-per-component # Enable Per-component builds when possible + --disable-per-component # Disable Per-component builds when possible + --run-tests # Run package test suites during installation. + --semaphore # Use a semaphore so GHC can compile components + in parallel + -j[NUM], --jobs[=NUM] # Run NUM jobs simultaneously (or '$ncpus' if no + NUM is given). + --keep-going # After a build failure, continue to build other + unaffected packages. + --offline # Don't download packages from the Internet. + --build-timings # Print elapsed time for each build phase. + --haddock-hoogle # Generate a hoogle database + --haddock-html # Generate HTML documentation (the default) + --haddock-html-location=URL # Location of HTML documentation for + pre-requisite packages + --haddock-for-hackage # Collection of flags to generate documentation + suitable for upload to hackage + --haddock-executables # Run haddock for Executables targets + --haddock-tests # Run haddock for Test Suite targets + --haddock-benchmarks # Run haddock for Benchmark targets + --haddock-all # Run haddock for all targets + --haddock-internal # Run haddock for internal modules and include + all symbols + --haddock-css=PATH # Use PATH as the haddock stylesheet + --haddock-hyperlink-source # Hyperlink the documentation to the source code + --haddock-quickjump # Generate an index for interactive + documentation navigation + --haddock-hscolour-css=PATH # Use PATH as the HsColour stylesheet + --haddock-contents-location=URL + # Bake URL in as the location for the contents + page + --haddock-base-url=URL # Base URL for static files. + --haddock-resources-dir=DIR # Location of Haddocks static / auxiliary files + --haddock-output-dir=DIR # Generate haddock documentation into this + directory. This flag is provided as a + technology preview and is subject to change in + the next releases. + --haddock-use-unicode # Pass --use-unicode option to haddock + --test-log=TEMPLATE # Log all test suite results to file (name + template can use $pkgid, $compiler, $os, + $arch, $test-suite, $result) + --test-machine-log=TEMPLATE # Produce a machine-readable log file (name + template can use $pkgid, $compiler, $os, + $arch, $result) + --test-show-details=FILTER # 'always': always show results of individual + test cases. 'never': never show results of + individual test cases. 'failures': show + results of failing test cases. 'streaming': + show results of test cases in real + time.'direct': send results of test cases in + real time; no log file. + --test-keep-tix-files # Keep .tix files for HPC between test runs + --test-wrapper=FILE # Run test through a wrapper. + --test-fail-when-no-test-suites + # Exit with failure when no test suites are + found. + --test-options=TEMPLATES # Give extra options to test executables (split + on spaces, use "" to prevent splitting; name + templates can use $pkgid, $compiler, $os, + $arch, $test-suite) + --test-option=TEMPLATE # Give extra option to test executables (passed + directly as a single argument; name template + can use $pkgid, $compiler, $os, $arch, + $test-suite) + --benchmark-options=TEMPLATES + # Give extra options to benchmark executables + (split on spaces, use "" to prevent splitting; + name templates can use $pkgid, $compiler, $os, + $arch, $benchmark) + --benchmark-option=TEMPLATE # Give extra option to benchmark executables + (passed directly as a single argument; name + template can use $pkgid, $compiler, $os, + $arch, $benchmark) + --project-dir=DIR # Set the path of the project directory + --project-file=FILE # Set the path of the cabal.project file + (relative to the project directory when + relative) + -z, --ignore-project # Ignore local project configuration (unless + --project-dir or --project-file is also set) + --project-file-parser=PARSER # Set the parser to use for the project file + +Examples: + cabal test + Run all the test-suites in the package in the current directory + cabal test pkgname + Run all the test-suites in the package named pkgname + cabal test cname + Run the test-suite named cname + cabal test cname --enable-coverage + Run the test-suite built with code coverage (including local libs used) diff --git a/doc/cmd-v2-help/unpack.txt b/doc/cmd-v2-help/unpack.txt new file mode 100644 index 00000000000..415b4eb007d --- /dev/null +++ b/doc/cmd-v2-help/unpack.txt @@ -0,0 +1,39 @@ +Deprecated alias for 'get'. + +Usage: cabal unpack [PACKAGES] + +Creates a local copy of a package's source code. By default it gets the source +tarball and unpacks it in a local subdirectory. Alternatively, with -s it will +get the code from the source repository specified by the package. + +Flags for unpack: + -h, --help # Show this help text + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + -d PATH or -dPATH, --destdir=PATH + # Where to place the package source, defaults to + the current directory. + -s[[head|this|...]], --source-repository[=[head|this|...]] + # Copy the package's source repository (ie git + clone, darcs get, etc as appropriate). + --index-state=STATE # Use source package index state as it existed + at a previous time. Accepts unix-timestamps + (e.g. '@1474732068'), ISO8601 UTC timestamps + (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' + (default: 'HEAD'). This determines which + package versions are available as well as + .cabal file revision is selected (unless + --pristine is used). + --only-package-description # Unpack only the package description file. + --package-description-only # A synonym for --only-package-description. + --pristine # Unpack the original pristine tarball, rather + than updating the .cabal file with the latest + revision from the package archive. + -R REPOSITORY or -RREPOSITORY, --repository=REPOSITORY + # Package repository to fetch from. + +Examples: + cabal unpack hlint + Download the latest stable version of hlint; + cabal unpack lens --source-repository=head + Download the source repository of lens (i.e. git clone from github). diff --git a/doc/cmd-v2-help/update.txt b/doc/cmd-v2-help/update.txt new file mode 100644 index 00000000000..cc4e6a3ea26 --- /dev/null +++ b/doc/cmd-v2-help/update.txt @@ -0,0 +1,383 @@ +Updates list of known packages. + +Usage: cabal update [FLAGS] [REPOS] + +For all known remote repositories, download the package list. + +Flags for update: + -h, --help # Show this help text + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + --builddir=DIR # The directory where Cabal puts generated build + files (default dist) + --keep-temp-files # Keep temporary files. + -g, --ghc # Compile with GHC + --ghcjs # Compile with GHCJS + --uhc # Compile with UHC + -w PATH or -wPATH, --with-compiler=PATH + # Give the path to a particular compiler + --with-hc-pkg=PATH # Give the path to the package tool + --prefix=DIR # Bake this prefix in preparation of + installation + --bindir=DIR # Installation directory for executables + --libdir=DIR # Installation directory for libraries + --libsubdir=DIR # Subdirectory of libdir in which libs are + installed + --dynlibdir=DIR # Installation directory for dynamic libraries + --bytecodelibdir=DIR # Installation directory for bytecode libraries + --libexecdir=DIR # Installation directory for program executables + --libexecsubdir=DIR # Subdirectory of libexecdir in which private + executables are installed + --datadir=DIR # Installation directory for read-only data + --datasubdir=DIR # Subdirectory of datadir in which data files + are installed + --docdir=DIR # Installation directory for documentation + --htmldir=DIR # Installation directory for HTML documentation + --haddockdir=DIR # Installation directory for haddock interfaces + --sysconfdir=DIR # Installation directory for configuration files + --program-prefix=PREFIX # Prefix to be applied to installed executables + --program-suffix=SUFFIX # Suffix to be applied to installed executables + --enable-library-vanilla # Enable Vanilla libraries + --disable-library-vanilla # Disable Vanilla libraries + -p, --enable-library-profiling + # Enable Library profiling + --disable-library-profiling # Disable Library profiling + --enable-shared # Enable Shared library + --disable-shared # Disable Shared library + --enable-static # Enable Static library + --disable-static # Disable Static library + --enable-library-bytecode # Enable Bytecode library + --disable-library-bytecode # Disable Bytecode library + --enable-executable-dynamic # Enable Executable dynamic linking + --disable-executable-dynamic # Disable Executable dynamic linking + --enable-executable-static # Enable Executable fully static linking + --disable-executable-static # Disable Executable fully static linking + --enable-profiling # Enable Executable and library profiling + --disable-profiling # Disable Executable and library profiling + --enable-profiling-shared # Enable Build profiling shared libraries + --disable-profiling-shared # Disable Build profiling shared libraries + --enable-executable-profiling + # Enable Executable profiling (DEPRECATED) + --disable-executable-profiling + # Disable Executable profiling (DEPRECATED) + --profiling-detail=level # Profiling detail level for executable and + library (default, none, exported-functions, + toplevel-functions, all-functions, late). + --library-profiling-detail=level + # Profiling detail level for libraries only. + -O[n], --enable-optimization[=n] + # Build with optimization (n is 0--2, default is + 1) + --disable-optimization # Build without optimization + --enable-debug-info[=n] # Emit debug info (n is 0--3, default is 0) + --disable-debug-info # Don't emit debug info + --enable-build-info # Enable build information generation during + project building + --disable-build-info # Disable build information generation during + project building + --enable-library-for-ghci # Enable compile library for use with GHCi + --disable-library-for-ghci # Disable compile library for use with GHCi + --enable-split-sections # Enable compile library code such that unneeded + definitions can be dropped from the final + executable (GHC 7.8+) + --disable-split-sections # Disable compile library code such that + unneeded definitions can be dropped from the + final executable (GHC 7.8+) + --enable-split-objs # Enable split library into smaller objects to + reduce binary sizes (GHC 6.6+) + --disable-split-objs # Disable split library into smaller objects to + reduce binary sizes (GHC 6.6+) + --enable-executable-stripping + # Enable strip executables upon installation to + reduce binary sizes + --disable-executable-stripping + # Disable strip executables upon installation to + reduce binary sizes + --enable-library-stripping # Enable strip libraries upon installation to + reduce binary sizes + --disable-library-stripping # Disable strip libraries upon installation to + reduce binary sizes + --configure-option=OPT # Extra option for configure + --user # Enable doing a per-user installation + --global # Disable doing a per-user installation + --package-db=DB # Append the given package database to the list + of package databases used (to satisfy + dependencies and register into). May be a + specific file, 'global' or 'user'. The initial + list is ['global'], ['global', 'user'], or + ['global', $sandbox], depending on context. + Use 'clear' to reset the list to empty. See + the user guide for details. + -f FLAGS or -fFLAGS, --flags=FLAGS + # Force values for the given flags in Cabal + conditionals in the .cabal file. E.g., + --flags="debug -usebytestrings" forces the + flag "debug" to true and "usebytestrings" to + false. + --extra-include-dirs=PATH # A list of directories to search for header + files + --enable-deterministic # Enable Try to be as deterministic as possible + (used by the test suite) + --disable-deterministic # Disable Try to be as deterministic as possible + (used by the test suite) + --ipid=IPID # Installed package ID to compile this package + as + --cid=CID # Installed component ID to compile this + component as + --extra-lib-dirs=PATH # A list of directories to search for external + libraries + --extra-lib-dirs-static=PATH # A list of directories to search for external + libraries when linking fully static + executables + --extra-framework-dirs=PATH # A list of directories to search for external + frameworks (OS X only) + --extra-prog-path=PATH # A list of directories to search for required + programs (in addition to the normal search + locations) + --instantiate-with=NAME=MOD # A mapping of signature names to concrete + module instantiations. + --enable-tests # Enable dependency checking and compilation for + test suites listed in the package description + file. + --disable-tests # Disable dependency checking and compilation + for test suites listed in the package + description file. + --enable-coverage # Enable build package with Haskell Program + Coverage. (GHC only) + --disable-coverage # Disable build package with Haskell Program + Coverage. (GHC only) + --enable-library-coverage # Enable build package with Haskell Program + Coverage. (GHC only) (DEPRECATED) + --disable-library-coverage # Disable build package with Haskell Program + Coverage. (GHC only) (DEPRECATED) + --enable-benchmarks # Enable dependency checking and compilation for + benchmarks listed in the package description + file. + --disable-benchmarks # Disable dependency checking and compilation + for benchmarks listed in the package + description file. + --enable-relocatable # Enable building a package that is relocatable. + (GHC only) + --disable-relocatable # Disable building a package that is + relocatable. (GHC only) + --disable-response-files # Enable workaround for old versions of programs + like "ar" that do not support @file arguments + --allow-depending-on-private-libs + # Allow depending on private libraries. If set, + the library visibility check MUST be done + externally. + --coverage-for=UNITID # A list of unit-ids of libraries to include in + the Haskell Program Coverage report. + --ignore-build-tools # Ignore build tool dependencies. If set, + declared build tools needn't be found for + compilation to proceed. + --with-PROG=PATH # Give the path to PROG + --PROG-option=OPT # Give an extra option to PROG (passed directly + to PROG as a single argument) + --PROG-options=OPTS # Give extra options to PROG (split on spaces, + use "" to prevent splitting) + --cabal-lib-version=VERSION # Select which version of the Cabal lib to use + to build packages (useful for testing). + --enable-append # Enable appending the new config to the old + config file + --disable-append # Disable appending the new config to the old + config file + --enable-backup # Enable the backup of the config file before + any alterations + --disable-backup # Disable the backup of the config file before + any alterations + -c CONSTRAINT or -cCONSTRAINT, --constraint=CONSTRAINT + # Specify constraints on a package (version, + installed/source, flags) + --preference=CONSTRAINT # Specify preferences (soft constraints) on the + version of a package + --solver=SOLVER # Select dependency solver to use (default: + modular). Choices: modular. + --allow-older[=DEPS] # Ignore lower bounds in all dependencies or + DEPS + --allow-newer[=DEPS] # Ignore upper bounds in all dependencies or + DEPS + --write-ghc-environment-files=always|never|ghc8.4.4+ + # Whether to create a .ghc.environment file + after a successful build (v2-build only) + --enable-documentation # Enable building of documentation + --disable-documentation # Disable building of documentation + --doc-index-file=TEMPLATE # A central index of haddock API documentation + (template cannot use $pkgid) + --dry-run # Do not install anything, only print what would + be installed. + --only-download # Do not build anything, only fetch the + packages. + --max-backjumps=NUM # Maximum number of backjumps allowed while + solving (default: 4000). Use a negative number + to enable unlimited backtracking. Use 0 to + disable backtracking completely. + --reorder-goals # Try to reorder goals according to certain + heuristics. Slows things down on average, but + may make backtracking faster for some + packages. + --count-conflicts # Try to speed up solving by preferring goals + that are involved in a lot of conflicts + (default). + --fine-grained-conflicts # Skip a version of a package if it does not + resolve the conflicts encountered in the last + version, as a solver optimization (default). + --minimize-conflict-set # When there is no solution, try to improve the + error message by finding a minimal conflict + set (default: false). May increase run time + significantly. + --independent-goals # Treat several goals on the command line as + independent. If several goals depend on the + same package, different versions can be + chosen. + --prefer-oldest # Prefer the oldest (instead of the latest) + versions of packages available. Useful to + determine lower bounds in the build-depends + section. + --prefer-version=oldest|latest|installed-or-latest + # Select which version of a package that the + solver should prefer. Oldest is useful to + determine lower bounds in build-depends + section. Latest will prefer the latest + version. Installed-or-latest will prefer + installed versions and the latest version + otherwise. + --shadow-installed-packages # If multiple package instances of the same + version are installed, treat all but one as + shadowed. + --strong-flags # Do not defer flag choices (this used to be the + default in cabal-install <= 1.20). + --allow-boot-library-installs + # Allow cabal to install base, ghc-prim, + integer-simple, integer-gmp, and + template-haskell. + --reject-unconstrained-dependencies=none|all + # Require these packages to have constraints on + them if they are to be selected (default: + none). + --reinstall # Install even if it means installing the same + version again. + --avoid-reinstalls # Do not select versions that would + destructively overwrite installed packages. + --force-reinstalls # Reinstall packages even if they will most + likely break other installed packages. + --upgrade-dependencies # Pick the latest version for all dependencies, + rather than trying to pick an installed + version. + --only-dependencies # Install only the dependencies necessary to + build the given packages + --dependencies-only # A synonym for --only-dependencies + --index-state=STATE # Use source package index state as it existed + at a previous time. Accepts unix-timestamps + (e.g. '@1474732068'), ISO8601 UTC timestamps + (e.g. '2016-09-24T17:47:48Z'), or 'HEAD' + (default: 'HEAD'). + --root-cmd=COMMAND # (No longer supported, do not use.) + --build-summary=TEMPLATE # Save build summaries to file (name template + can use $pkgid, $compiler, $os, $arch) + --build-log=TEMPLATE # Log all builds to file (name template can use + $pkgid, $compiler, $os, $arch) + --remote-build-reporting=LEVEL + # Generate build reports to send to a remote + server (none, anonymous or detailed). + --report-planning-failure # Generate build reports when the dependency + solver fails. This is used by the Hackage + build bot. + --enable-per-component # Enable Per-component builds when possible + --disable-per-component # Disable Per-component builds when possible + --run-tests # Run package test suites during installation. + --semaphore # Use a semaphore so GHC can compile components + in parallel + -j[NUM], --jobs[=NUM] # Run NUM jobs simultaneously (or '$ncpus' if no + NUM is given). + --keep-going # After a build failure, continue to build other + unaffected packages. + --offline # Don't download packages from the Internet. + --build-timings # Print elapsed time for each build phase. + --haddock-hoogle # Generate a hoogle database + --haddock-html # Generate HTML documentation (the default) + --haddock-html-location=URL # Location of HTML documentation for + pre-requisite packages + --haddock-for-hackage # Collection of flags to generate documentation + suitable for upload to hackage + --haddock-executables # Run haddock for Executables targets + --haddock-tests # Run haddock for Test Suite targets + --haddock-benchmarks # Run haddock for Benchmark targets + --haddock-all # Run haddock for all targets + --haddock-internal # Run haddock for internal modules and include + all symbols + --haddock-css=PATH # Use PATH as the haddock stylesheet + --haddock-hyperlink-source # Hyperlink the documentation to the source code + --haddock-quickjump # Generate an index for interactive + documentation navigation + --haddock-hscolour-css=PATH # Use PATH as the HsColour stylesheet + --haddock-contents-location=URL + # Bake URL in as the location for the contents + page + --haddock-base-url=URL # Base URL for static files. + --haddock-resources-dir=DIR # Location of Haddocks static / auxiliary files + --haddock-output-dir=DIR # Generate haddock documentation into this + directory. This flag is provided as a + technology preview and is subject to change in + the next releases. + --haddock-use-unicode # Pass --use-unicode option to haddock + --test-log=TEMPLATE # Log all test suite results to file (name + template can use $pkgid, $compiler, $os, + $arch, $test-suite, $result) + --test-machine-log=TEMPLATE # Produce a machine-readable log file (name + template can use $pkgid, $compiler, $os, + $arch, $result) + --test-show-details=FILTER # 'always': always show results of individual + test cases. 'never': never show results of + individual test cases. 'failures': show + results of failing test cases. 'streaming': + show results of test cases in real + time.'direct': send results of test cases in + real time; no log file. + --test-keep-tix-files # Keep .tix files for HPC between test runs + --test-wrapper=FILE # Run test through a wrapper. + --test-fail-when-no-test-suites + # Exit with failure when no test suites are + found. + --test-options=TEMPLATES # Give extra options to test executables (split + on spaces, use "" to prevent splitting; name + templates can use $pkgid, $compiler, $os, + $arch, $test-suite) + --test-option=TEMPLATE # Give extra option to test executables (passed + directly as a single argument; name template + can use $pkgid, $compiler, $os, $arch, + $test-suite) + --benchmark-options=TEMPLATES + # Give extra options to benchmark executables + (split on spaces, use "" to prevent splitting; + name templates can use $pkgid, $compiler, $os, + $arch, $benchmark) + --benchmark-option=TEMPLATE # Give extra option to benchmark executables + (passed directly as a single argument; name + template can use $pkgid, $compiler, $os, + $arch, $benchmark) + --project-dir=DIR # Set the path of the project directory + --project-file=FILE # Set the path of the cabal.project file + (relative to the project directory when + relative) + -z, --ignore-project # Ignore local project configuration (unless + --project-dir or --project-file is also set) + --project-file-parser=PARSER # Set the parser to use for the project file + +REPO has the format [,] where index-state follows +the same format and syntax that is supported by the --index-state flag. + +Examples: + cabal update + Download the package list for all known remote repositories. + + cabal update hackage.haskell.org,@1474732068 + cabal update hackage.haskell.org,2016-09-24T17:47:48Z + cabal update hackage.haskell.org,HEAD + cabal update hackage.haskell.org + Download hackage.haskell.org at a specific index state. + + cabal update hackage.haskell.org head.hackage + Download hackage.haskell.org and head.hackage + head.hackage must be a known repo-id. E.g. from + your cabal.project(.local) file. diff --git a/doc/cmd-v2-help/upload.txt b/doc/cmd-v2-help/upload.txt new file mode 100644 index 00000000000..86bb0697eee --- /dev/null +++ b/doc/cmd-v2-help/upload.txt @@ -0,0 +1,33 @@ +Uploads source packages or documentation to Hackage. + +Usage: cabal upload [FLAGS] TARFILES + +Flags for upload: + -h, --help # Show this help text + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + --publish # Publish the package instead of uploading it as + a candidate. + -d, --documentation # Upload documentation instead of a source + package. By default, this uploads + documentation for a package candidate. To + upload documentation for a published package, + combine with --publish. + -t TOKEN or -tTOKEN, --token=TOKEN + # Hackage authentication token. + -u USERNAME or -uUSERNAME, --username=USERNAME + # Hackage username. + -p PASSWORD or -pPASSWORD, --password=PASSWORD + # Hackage password. + -P COMMAND or -PCOMMAND, --password-command=COMMAND + # Command to get Hackage password. + -R REPOSITORY or -RREPOSITORY, --repository=REPOSITORY + # Package repository to upload to. + +You can store your Hackage login in the ~/.config/cabal/config file +(the %APPDATA%\cabal\config file on Windows) +Relevant global configuration keys: + token + username + password + password-command diff --git a/doc/cmd-v2-help/user-config.txt b/doc/cmd-v2-help/user-config.txt new file mode 100644 index 00000000000..1a54e235217 --- /dev/null +++ b/doc/cmd-v2-help/user-config.txt @@ -0,0 +1,29 @@ +Display and update the user's global cabal configuration. + +Usage: cabal user-config init + or: cabal user-config diff + or: cabal user-config update + +When upgrading cabal, the set of configuration keys and their default values +may change. This command provides means to merge the existing config in +~/.config/cabal/config (i.e. all bindings that are actually defined and not +commented out) and the default config of the new version. + +init: Creates a new config file at either ~/.config/cabal/config or as +specified by --config-file, if given. An existing file won't be overwritten +unless -f or --force is given. +diff: Shows a pseudo-diff of the user's ~/.config/cabal/config file and the +default configuration that would be created by cabal if the config file did +not exist. +update: Applies the pseudo-diff to the configuration that would be created by +default, and write the result back to ~/.config/cabal/config. + +Flags for user-config: + -h, --help # Show this help text + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + -f, --force # Overwrite the config file if it already + exists. + -a CONFIGLINE or -aCONFIGLINE, --augment=CONFIGLINE + # Additional setting to augment the config file + (replacing a previous setting if it existed). diff --git a/doc/cmd-v2-hidden-help/act-as-setup.txt b/doc/cmd-v2-hidden-help/act-as-setup.txt new file mode 100644 index 00000000000..8a369fe706e --- /dev/null +++ b/doc/cmd-v2-hidden-help/act-as-setup.txt @@ -0,0 +1,7 @@ +Run as-if this was a Setup.hs + +Usage: cabal act-as-setup + +Flags for act-as-setup: + -h, --help # Show this help text + --build-type=BUILD-TYPE # Use the given build type. diff --git a/doc/cmd-v2-hidden-help/format.txt b/doc/cmd-v2-hidden-help/format.txt new file mode 100644 index 00000000000..79b6c036507 --- /dev/null +++ b/doc/cmd-v2-hidden-help/format.txt @@ -0,0 +1,6 @@ +Reformat the .cabal file using the standard style. + +Usage: cabal format [FILE] + +Flags for format: + -h, --help # Show this help text diff --git a/doc/cmd-v2-hidden-help/man.txt b/doc/cmd-v2-hidden-help/man.txt new file mode 100644 index 00000000000..215c29f9962 --- /dev/null +++ b/doc/cmd-v2-hidden-help/man.txt @@ -0,0 +1,11 @@ +Outputs manpage source. + +Usage: cabal man [FLAGS] + +Output manpage source to STDOUT. + +Flags for man: + -h, --help # Show this help text + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + --raw # Output raw troff content diff --git a/doc/setup-help/bench.txt b/doc/setup-help/bench.txt new file mode 100644 index 00000000000..7aa38a70c78 --- /dev/null +++ b/doc/setup-help/bench.txt @@ -0,0 +1,31 @@ +Run all/specific benchmarks. + +Usage: cabal bench [FLAGS] + or: cabal bench BENCHCOMPONENTS [FLAGS] + +The package must have been build with configuration flag +`--enable-benchmarks`. + +Note that additional dependencies of the benchmarks must have already been +installed. + +By defining UserHooks in a custom Setup.hs, the package can define actions to +be executed before and after running benchmarks. + +Flags for bench: + -h, --help # Show this help text + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + --builddir=DIR # The directory where Cabal puts generated build + files (default dist) + --cabal-file=PATH # use this Cabal file + --keep-temp-files # Keep temporary files. + --benchmark-options=TEMPLATES + # Give extra options to benchmark executables + (split on spaces, use "" to prevent splitting; + name templates can use $pkgid, $compiler, $os, + $arch, $benchmark) + --benchmark-option=TEMPLATE # Give extra option to benchmark executables + (passed directly as a single argument; name + template can use $pkgid, $compiler, $os, + $arch, $benchmark) diff --git a/doc/setup-help/build.txt b/doc/setup-help/build.txt new file mode 100644 index 00000000000..720d2ef784a --- /dev/null +++ b/doc/setup-help/build.txt @@ -0,0 +1,34 @@ +Compile all/specific components. + +Usage: cabal build [FLAGS] + or: cabal build COMPONENTS [FLAGS] + +Components encompass executables, tests, and benchmarks. + +Affected by configuration options, see `configure`. + +Flags for build: + -h, --help # Show this help text + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + --builddir=DIR # The directory where Cabal puts generated build + files (default dist) + --cabal-file=PATH # use this Cabal file + --keep-temp-files # Keep temporary files. + -j[NUM], --jobs[=NUM] # Run NUM jobs simultaneously (or '$ncpus' if no + NUM is given). + --semaphore=SEMAPHORE # Use the specified semaphore identifier so GHC + can compile components in parallel + --with-PROG=PATH # Give the path to PROG + --PROG-option=OPT # Give an extra option to PROG (passed directly + to PROG as a single argument) + --PROG-options=OPTS # Give extra options to PROG (split on spaces, + use "" to prevent splitting) + +Examples: + cabal build All the components in the package + cabal build foo A component (i.e. lib, exe, test suite) + +The flags --with-PROG and --PROG-option(s) can be used with the following programs: + alex ar c2hs cpphs doctest gcc ghc ghc-pkg ghcjs ghcjs-pkg haddock happy hpc + hsc2hs hscolour jhc ld pkg-config runghc strip tar uhc diff --git a/doc/setup-help/clean.txt b/doc/setup-help/clean.txt new file mode 100644 index 00000000000..227bd8db913 --- /dev/null +++ b/doc/setup-help/clean.txt @@ -0,0 +1,17 @@ +Clean up after a build. + +Usage: cabal clean [FLAGS] + +Removes .hi, .o, preprocessed sources, etc. + +Flags for clean: + -h, --help # Show this help text + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + --builddir=DIR # The directory where Cabal puts generated build + files (default dist) + --cabal-file=PATH # use this Cabal file + --keep-temp-files # Keep temporary files. + -s, --save-configure # Do not remove the configuration file + (dist/setup-config) during cleaning. Saves + need to reconfigure. diff --git a/doc/setup-help/configure.txt b/doc/setup-help/configure.txt new file mode 100644 index 00000000000..a5b3587cdd3 --- /dev/null +++ b/doc/setup-help/configure.txt @@ -0,0 +1,196 @@ +Prepare to build the package. + +Usage: cabal configure [FLAGS] + +Configure how the package is built by setting package (and other) flags. + +The configuration affects several other commands, including build, test, +bench, run, repl. + +Flags for configure: + -h, --help # Show this help text + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + --builddir=DIR # The directory where Cabal puts generated build + files (default dist) + --cabal-file=PATH # use this Cabal file + --keep-temp-files # Keep temporary files. + -g, --ghc # Compile with GHC + --ghcjs # Compile with GHCJS + --uhc # Compile with UHC + -w PATH or -wPATH, --with-compiler=PATH + # Give the path to a particular compiler + --with-hc-pkg=PATH # Give the path to the package tool + --prefix=DIR # Bake this prefix in preparation of + installation + --bindir=DIR # Installation directory for executables + --libdir=DIR # Installation directory for libraries + --libsubdir=DIR # Subdirectory of libdir in which libs are + installed + --dynlibdir=DIR # Installation directory for dynamic libraries + --bytecodelibdir=DIR # Installation directory for bytecode libraries + --libexecdir=DIR # Installation directory for program executables + --libexecsubdir=DIR # Subdirectory of libexecdir in which private + executables are installed + --datadir=DIR # Installation directory for read-only data + --datasubdir=DIR # Subdirectory of datadir in which data files + are installed + --docdir=DIR # Installation directory for documentation + --htmldir=DIR # Installation directory for HTML documentation + --haddockdir=DIR # Installation directory for haddock interfaces + --sysconfdir=DIR # Installation directory for configuration files + --program-prefix=PREFIX # Prefix to be applied to installed executables + --program-suffix=SUFFIX # Suffix to be applied to installed executables + --enable-library-vanilla # Enable Vanilla libraries + --disable-library-vanilla # Disable Vanilla libraries + -p, --enable-library-profiling + # Enable Library profiling + --disable-library-profiling # Disable Library profiling + --enable-shared # Enable Shared library + --disable-shared # Disable Shared library + --enable-static # Enable Static library + --disable-static # Disable Static library + --enable-library-bytecode # Enable Bytecode library + --disable-library-bytecode # Disable Bytecode library + --enable-executable-dynamic # Enable Executable dynamic linking + --disable-executable-dynamic # Disable Executable dynamic linking + --enable-executable-static # Enable Executable fully static linking + --disable-executable-static # Disable Executable fully static linking + --enable-profiling # Enable Executable and library profiling + --disable-profiling # Disable Executable and library profiling + --enable-profiling-shared # Enable Build profiling shared libraries + --disable-profiling-shared # Disable Build profiling shared libraries + --enable-executable-profiling + # Enable Executable profiling (DEPRECATED) + --disable-executable-profiling + # Disable Executable profiling (DEPRECATED) + --profiling-detail=level # Profiling detail level for executable and + library (default, none, exported-functions, + toplevel-functions, all-functions, late). + --library-profiling-detail=level + # Profiling detail level for libraries only. + -O[n], --enable-optimization[=n] + # Build with optimization (n is 0--2, default is + 1) + --disable-optimization # Build without optimization + --enable-debug-info[=n] # Emit debug info (n is 0--3, default is 0) + --disable-debug-info # Don't emit debug info + --enable-build-info # Enable build information generation during + project building + --disable-build-info # Disable build information generation during + project building + --enable-library-for-ghci # Enable compile library for use with GHCi + --disable-library-for-ghci # Disable compile library for use with GHCi + --enable-split-sections # Enable compile library code such that unneeded + definitions can be dropped from the final + executable (GHC 7.8+) + --disable-split-sections # Disable compile library code such that + unneeded definitions can be dropped from the + final executable (GHC 7.8+) + --enable-split-objs # Enable split library into smaller objects to + reduce binary sizes (GHC 6.6+) + --disable-split-objs # Disable split library into smaller objects to + reduce binary sizes (GHC 6.6+) + --enable-executable-stripping + # Enable strip executables upon installation to + reduce binary sizes + --disable-executable-stripping + # Disable strip executables upon installation to + reduce binary sizes + --enable-library-stripping # Enable strip libraries upon installation to + reduce binary sizes + --disable-library-stripping # Disable strip libraries upon installation to + reduce binary sizes + --configure-option=OPT # Extra option for configure + --user # Enable doing a per-user installation + --global # Disable doing a per-user installation + --package-db=DB # Append the given package database to the list + of package databases used (to satisfy + dependencies and register into). May be a + specific file, 'global' or 'user'. The initial + list is ['global'], ['global', 'user'], or + ['global', $sandbox], depending on context. + Use 'clear' to reset the list to empty. See + the user guide for details. + -f FLAGS or -fFLAGS, --flags=FLAGS + # Force values for the given flags in Cabal + conditionals in the .cabal file. E.g., + --flags="debug -usebytestrings" forces the + flag "debug" to true and "usebytestrings" to + false. + --extra-include-dirs=PATH # A list of directories to search for header + files + --enable-deterministic # Enable Try to be as deterministic as possible + (used by the test suite) + --disable-deterministic # Disable Try to be as deterministic as possible + (used by the test suite) + --ipid=IPID # Installed package ID to compile this package + as + --cid=CID # Installed component ID to compile this + component as + --extra-lib-dirs=PATH # A list of directories to search for external + libraries + --extra-lib-dirs-static=PATH # A list of directories to search for external + libraries when linking fully static + executables + --extra-framework-dirs=PATH # A list of directories to search for external + frameworks (OS X only) + --extra-prog-path=PATH # A list of directories to search for required + programs (in addition to the normal search + locations) + --constraint=DEPENDENCY # A list of additional constraints on the + dependencies. + --dependency=NAME[:COMPONENT_NAME]=CID + # A list of exact dependencies. E.g., + --dependency="void=void-0.5.8-177d5cdf20962d0581fe2e4932a6c309" + --promised-dependency=NAME-VER[:COMPONENT_NAME]=CID + # A list of promised dependencies. E.g., + --promised-dependency="void-0.5.8=void-0.5.8-177d5cdf20962d0581fe2e4932a6c309" + --instantiate-with=NAME=MOD # A mapping of signature names to concrete + module instantiations. + --enable-tests # Enable dependency checking and compilation for + test suites listed in the package description + file. + --disable-tests # Disable dependency checking and compilation + for test suites listed in the package + description file. + --enable-coverage # Enable build package with Haskell Program + Coverage. (GHC only) + --disable-coverage # Disable build package with Haskell Program + Coverage. (GHC only) + --enable-library-coverage # Enable build package with Haskell Program + Coverage. (GHC only) (DEPRECATED) + --disable-library-coverage # Disable build package with Haskell Program + Coverage. (GHC only) (DEPRECATED) + --exact-configuration # All direct dependencies and flags are provided + on the command line. + --enable-benchmarks # Enable dependency checking and compilation for + benchmarks listed in the package description + file. + --disable-benchmarks # Disable dependency checking and compilation + for benchmarks listed in the package + description file. + --enable-relocatable # Enable building a package that is relocatable. + (GHC only) + --disable-relocatable # Disable building a package that is + relocatable. (GHC only) + --disable-response-files # Enable workaround for old versions of programs + like "ar" that do not support @file arguments + --allow-depending-on-private-libs + # Allow depending on private libraries. If set, + the library visibility check MUST be done + externally. + --coverage-for=UNITID # A list of unit-ids of libraries to include in + the Haskell Program Coverage report. + --ignore-build-tools # Ignore build tool dependencies. If set, + declared build tools needn't be found for + compilation to proceed. + --with-PROG=PATH # Give the path to PROG + --PROG-option=OPT # Give an extra option to PROG (passed directly + to PROG as a single argument) + --PROG-options=OPTS # Give extra options to PROG (split on spaces, + use "" to prevent splitting) + +The flags --with-PROG and --PROG-option(s) can be used with the following programs: + alex ar c2hs cpphs doctest gcc ghc ghc-pkg ghcjs ghcjs-pkg haddock happy hpc + hsc2hs hscolour jhc ld pkg-config runghc strip tar uhc diff --git a/doc/setup-help/copy.txt b/doc/setup-help/copy.txt new file mode 100644 index 00000000000..9f62204ac36 --- /dev/null +++ b/doc/setup-help/copy.txt @@ -0,0 +1,23 @@ +Copy the files of all/specific components to install locations. + +Usage: cabal copy [FLAGS] + or: cabal copy COMPONENTS [FLAGS] + +Components encompass executables and libraries. Does not call register, and +allows a prefix at install time. Without the --destdir flag, configure +determines location. + +Flags for copy: + -h, --help # Show this help text + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + --builddir=DIR # The directory where Cabal puts generated build + files (default dist) + --cabal-file=PATH # use this Cabal file + --keep-temp-files # Keep temporary files. + --destdir=DIR # directory to copy files to, prepended to + installation directories + +Examples: + cabal copy All the components in the package + cabal copy foo A component (i.e. lib, exe, test suite) \ No newline at end of file diff --git a/doc/setup-help/haddock.txt b/doc/setup-help/haddock.txt new file mode 100644 index 00000000000..1f281d39842 --- /dev/null +++ b/doc/setup-help/haddock.txt @@ -0,0 +1,51 @@ +Generate Haddock HTML documentation. + +Usage: cabal haddock [FLAGS] + or: cabal haddock COMPONENTS [FLAGS] + +Requires the program haddock, version 2.x. + +Flags for haddock: + -h, --help # Show this help text + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + --builddir=DIR # The directory where Cabal puts generated build + files (default dist) + --cabal-file=PATH # use this Cabal file + --keep-temp-files # Keep temporary files. + --hoogle # Generate a hoogle database + --html # Generate HTML documentation (the default) + --html-location=URL # Location of HTML documentation for + pre-requisite packages + --for-hackage # Collection of flags to generate documentation + suitable for upload to hackage + --executables # Run haddock for Executables targets + --tests # Run haddock for Test Suite targets + --benchmarks # Run haddock for Benchmark targets + --foreign-libraries # Run haddock for Foreign Library targets + --all # Run haddock for all targets + --internal # Run haddock for internal modules and include + all symbols + --css=PATH # Use PATH as the haddock stylesheet + --hyperlink-source # Hyperlink the documentation to the source code + --quickjump # Generate an index for interactive + documentation navigation + --hscolour-css=PATH # Use PATH as the HsColour stylesheet + --contents-location=URL # Bake URL in as the location for the contents + page + --index-location=URL # Use a separately-generated HTML index + --base-url=URL # Base URL for static files. + --resources-dir=DIR # Location of Haddocks static / auxiliary files + --output-dir=DIR # Generate haddock documentation into this + directory. This flag is provided as a + technology preview and is subject to change in + the next releases. + --use-unicode # Pass --use-unicode option to haddock + --with-ghc=PATH # Give the path to ghc + --with-haddock=PATH # Give the path to haddock + --PROG-option=OPT # Give an extra option to PROG (passed directly + to PROG as a single argument) + --ghc-options=OPTS # Give extra options to ghc (split on spaces, + use "" to prevent splitting) + --haddock-options=OPTS # Give extra options to haddock (split on + spaces, use "" to prevent splitting) diff --git a/doc/setup-help/help.txt b/doc/setup-help/help.txt new file mode 100644 index 00000000000..94e61535028 --- /dev/null +++ b/doc/setup-help/help.txt @@ -0,0 +1,38 @@ + + +This Setup program uses the Haskell Cabal Infrastructure. +See http://www.haskell.org/cabal/ for more information. + +Usage: cabal [GLOBAL FLAGS] [COMMAND [FLAGS]] + +Commands: + configure Prepare to build the package. + build Compile all/specific components. + repl Open an interpreter session for the given component. + install Copy the files into the install locations. Run register. + copy Copy the files of all/specific components to install locations. + haddock Generate Haddock HTML documentation. + clean Clean up after a build. + sdist Generate a source distribution file (.tar.gz). + hscolour Generate HsColour colourised code, in HTML format. + register Register this package with the compiler. + unregister Unregister this package with the compiler. + test Run all/specific tests in the test suite. + bench Run all/specific benchmarks. + help Help about commands. + +For more information about a command use + cabal COMMAND --help + +Typical steps for installing Cabal packages: + cabal configure + cabal build + cabal install + +Global flags: + -h, --help # Show this help text + -V, --version # Print version information + --full-version # Print the version, Git revision if available, + and compiler information + --numeric-version # Print just the version number + --working-dir=DIR # Set working directory diff --git a/doc/setup-help/hscolour.txt b/doc/setup-help/hscolour.txt new file mode 100644 index 00000000000..f307d39229a --- /dev/null +++ b/doc/setup-help/hscolour.txt @@ -0,0 +1,22 @@ +Generate HsColour colourised code, in HTML format. + +Usage: cabal hscolour [FLAGS] + +Requires the hscolour program. + +Flags for hscolour: + -h, --help # Show this help text + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + --builddir=DIR # The directory where Cabal puts generated build + files (default dist) + --cabal-file=PATH # use this Cabal file + --keep-temp-files # Keep temporary files. + --executables # Run hscolour for Executables targets + --tests # Run hscolour for Test Suite targets + --benchmarks # Run hscolour for Benchmark targets + --foreign-libraries # Run hscolour for Foreign Library targets + --all # Run hscolour for all targets + --css=PATH # Use a cascading style sheet + +Deprecated in favour of 'cabal haddock --hyperlink-source'. diff --git a/doc/setup-help/install.txt b/doc/setup-help/install.txt new file mode 100644 index 00000000000..4aa64d05a4f --- /dev/null +++ b/doc/setup-help/install.txt @@ -0,0 +1,27 @@ +Copy the files into the install locations. Run register. + +Usage: cabal install [FLAGS] + +Unlike the copy command, install calls the register command. If you want to +install into a location that is not what was specified in the configure step, +use the copy command. + +Flags for install: + -h, --help # Show this help text + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + --builddir=DIR # The directory where Cabal puts generated build + files (default dist) + --cabal-file=PATH # use this Cabal file + --keep-temp-files # Keep temporary files. + --inplace # install the package in the install + subdirectory of the dist prefix, so it can be + used without being installed + --enable-shell-wrappers # Enable using shell script wrappers around + executables + --disable-shell-wrappers # Disable using shell script wrappers around + executables + --user # upon configuration register this package in + the user's local package database + --global # (default) upon configuration register this + package in the system-wide package database diff --git a/doc/setup-help/register.txt b/doc/setup-help/register.txt new file mode 100644 index 00000000000..776cbc0585b --- /dev/null +++ b/doc/setup-help/register.txt @@ -0,0 +1,24 @@ +Register this package with the compiler. + +Usage: cabal register [FLAGS] + +Flags for register: + -h, --help # Show this help text + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + --builddir=DIR # The directory where Cabal puts generated build + files (default dist) + --cabal-file=PATH # use this Cabal file + --keep-temp-files # Keep temporary files. + --user # upon registration, register this package in + the user's local package database + --global # (default)upon registration, register this + package in the system-wide package database + --inplace # register the package in the build location, so + it can be used without being installed + --gen-script # instead of registering, generate a script to + register later + --gen-pkg-config[=PKG] # instead of registering, generate a package + registration file/directory + --print-ipid # print the installed package ID calculated for + this package diff --git a/doc/setup-help/repl.txt b/doc/setup-help/repl.txt new file mode 100644 index 00000000000..f843b57796f --- /dev/null +++ b/doc/setup-help/repl.txt @@ -0,0 +1,44 @@ +Open an interpreter session for the given component. + +Usage: cabal repl [COMPONENT] [FLAGS] + +If the current directory contains no package, ignores COMPONENT parameters and +opens an interactive interpreter session. + +Otherwise, (re)configures with the given or default flags, and loads the +interpreter with the relevant modules. For executables, tests and benchmarks, +loads the main module (and its dependencies); for libraries all exposed/other +modules. + +The default component is the library itself, or the executable if that is the +only component. + +Support for loading specific modules is planned but not implemented yet. For +certain scenarios, `cabal exec -- ghci :l Foo` may be used instead. Note that +`exec` will not (re)configure and you will have to specify the location of +other modules, if required. + +Flags for repl: + -h, --help # Show this help text + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + --builddir=DIR # The directory where Cabal puts generated build + files (default dist) + --cabal-file=PATH # use this Cabal file + --keep-temp-files # Keep temporary files. + --with-PROG=PATH # Give the path to PROG + --PROG-option=OPT # Give an extra option to PROG (passed directly + to PROG as a single argument) + --PROG-options=OPTS # Give extra options to PROG (split on spaces, + use "" to prevent splitting) + --repl-no-load # Disable loading of project modules at REPL + startup. + --repl-options=FLAG # Use the option(s) for the repl + --repl-multi-file=DIR # Write repl options to this directory rather + than starting repl mode + --with-repl=PATH # Give the path to a program to use for REPL + +Examples: + cabal repl The first component in the package + cabal repl foo A named component (i.e. lib, exe, test suite) + cabal repl --repl-options="-lstdc++" Specifying flags for interpreter diff --git a/doc/setup-help/sdist.txt b/doc/setup-help/sdist.txt new file mode 100644 index 00000000000..a8aec92c4a0 --- /dev/null +++ b/doc/setup-help/sdist.txt @@ -0,0 +1,17 @@ +Generate a source distribution file (.tar.gz). + +Usage: cabal sdist [FLAGS] + +Flags for sdist: + -h, --help # Show this help text + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + --builddir=DIR # The directory where Cabal puts generated build + files (default dist) + --cabal-file=PATH # use this Cabal file + --keep-temp-files # Keep temporary files. + --list-sources=FILE # Just write a list of the package's sources to + a file + --snapshot # Produce a snapshot source distribution + --output-directory=DIR # Generate a source distribution in the given + directory, without creating a tarball diff --git a/doc/setup-help/test.txt b/doc/setup-help/test.txt new file mode 100644 index 00000000000..3ebe170302e --- /dev/null +++ b/doc/setup-help/test.txt @@ -0,0 +1,46 @@ +Run all/specific tests in the test suite. + +Usage: cabal test [FLAGS] + or: cabal test TESTCOMPONENTS [FLAGS] + +The package must have been build with configuration flag `--enable-tests`. + +Note that additional dependencies of the tests must have already been +installed. + +By defining UserHooks in a custom Setup.hs, the package can define actions to +be executed before and after running tests. + +Flags for test: + -h, --help # Show this help text + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + --builddir=DIR # The directory where Cabal puts generated build + files (default dist) + --cabal-file=PATH # use this Cabal file + --keep-temp-files # Keep temporary files. + --log=TEMPLATE # Log all test suite results to file (name + template can use $pkgid, $compiler, $os, + $arch, $test-suite, $result) + --machine-log=TEMPLATE # Produce a machine-readable log file (name + template can use $pkgid, $compiler, $os, + $arch, $result) + --show-details=FILTER # 'always': always show results of individual + test cases. 'never': never show results of + individual test cases. 'failures': show + results of failing test cases. 'streaming': + show results of test cases in real + time.'direct': send results of test cases in + real time; no log file. + --keep-tix-files # Keep .tix files for HPC between test runs + --test-wrapper=FILE # Run test through a wrapper. + --fail-when-no-test-suites # Exit with failure when no test suites are + found. + --test-options=TEMPLATES # Give extra options to test executables (split + on spaces, use "" to prevent splitting; name + templates can use $pkgid, $compiler, $os, + $arch, $test-suite) + --test-option=TEMPLATE # Give extra option to test executables (passed + directly as a single argument; name template + can use $pkgid, $compiler, $os, $arch, + $test-suite) diff --git a/doc/setup-help/unregister.txt b/doc/setup-help/unregister.txt new file mode 100644 index 00000000000..1fb6f8629fe --- /dev/null +++ b/doc/setup-help/unregister.txt @@ -0,0 +1,18 @@ +Unregister this package with the compiler. + +Usage: cabal unregister [FLAGS] + +Flags for unregister: + -h, --help # Show this help text + -v[n], --verbose[=n] # Control verbosity (n is 0--3, default + verbosity level is 1) + --builddir=DIR # The directory where Cabal puts generated build + files (default dist) + --cabal-file=PATH # use this Cabal file + --keep-temp-files # Keep temporary files. + --user # unregister this package in the user's local + package database + --global # (default) unregister this package in the + system-wide package database + --gen-script # Instead of performing the unregister command, + generate a script to unregister later diff --git a/fix-whitespace.yaml b/fix-whitespace.yaml index bce2c040cea..73a7aeb902b 100644 --- a/fix-whitespace.yaml +++ b/fix-whitespace.yaml @@ -123,6 +123,7 @@ excluded-files: - "*.log" - "*.out" - doc/buildinfo-fields-reference.rst + - doc/setup-help/copy.txt # Binary files - "*.a"