From b34184e057324331d4e0184d7298c752090df08b Mon Sep 17 00:00:00 2001 From: Julia Longtin Date: Sat, 2 Dec 2023 22:33:22 +0000 Subject: [PATCH] add more breadcrumbs for how to use remote packages. documentation change only. (#9386) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * add more breadcrumbs for how to use remote packages. * Hackage should be capitalized * Update doc/cabal-project.rst reword. * Update doc/cabal-project.rst reword. * Update doc/cabal-project.rst clearer. * Update doc/cabal-project.rst clearer! * Update doc/cabal-project.rst good mechanical description. * wrap. * Update doc/cabal-project.rst add missing double ticks. * clarify english, and follow a linguistic pattern better. * Update doc/cabal-project.rst * doc: render math with HTML to make it selectable (fix #8453) (#9361) * doc: render math with HTML to make it selectable (fix #8453) * Update doc/conf.py Co-authored-by: Bryan Richter --------- Co-authored-by: Bryan Richter Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com> * Avoid double space in "Executing install plan ..." * Add a change log entry for double space avoidance * Ignore CmmSourcesExe Demo Ignore because it warns about missing MachDeps.h * [cabal-7825] Implement external command system Fix #2349 and #7825 * Bump to latest dependencies for GHC 9.8.1 * cabal.project: clean out obsolete `allow-newer`s * update GH validate workflow to ghc 9.2.8, 9.4.7, 9.6.3 * Revert #3639 (Don't pass -package-db and -package flags to --abi-hash) (#9384) * Revert #3639 (Don't pass -package-db and -package flags to --abi-hash) With ghc>=9.6 `ghc --abi-hash` initialises the plugins so it will fail if a cabal file specifies `ghc-options: -fplugin=Foo`. Closes: #9375 * Also revert in GHC.hs --------- Co-authored-by: Hamish Mackenzie Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com> * Use the newer haskell-actions organisation * Restructure Cabal documentation top-level parts The goal is for users to easier find pages for typical problems through search engines and page navigation. - The top-level layout is based on the popular documentation structure by https://documentation.divio.com/ to give a clear structure to users and future documentation contributors: * Guides: Present a solution to a single, atomic, typical user problem. * Reference: Describe user API (CLI fields, syntax etc) with technical rigour and completeness. * Explanation: Discuss background information, scope, design decisions etc. - Move existing documentation roughly into these categories with minimal editing as the basis for further editing. - Rename guide titles to mention how-to for improving SEO. - Rename some files to improve SEO since that name becomes part of the URL (often called slug). Important page keywords should appear in the slug as well to make pages rank higher in search engines. * Rename master_doc to root_doc (changed in version 4.0 of Sphynx) * Add instance Ord for Field, FieldLine, SectionArg and Name * Do not run CI for documentation changes The github workflows are not run if the changes are completely contained within the doc/ subdirectory. The only exception is the users-guide.yml github action. * Move Backpack section to user guides * Remove TBW virtual modules section * Add reinstall test to LinkerOptions/NonignoredConfigs * Record install options * Reject index-states after last known index-state (#8944) Co-authored-by: Javier Sagredo Co-authored-by: Andrea Bedini Co-authored-by: Andrea Bedini * Note how to do "not equal" with constraints * Use comma with then Co-authored-by: Artem Pelenitsyn * Use narrow rather than upset * Say something about hackage deprecations * Fix AutogenModulesToggling test By converting this to a setupTest we use the in-tree Cabal library rather than relying on a proxy of the GHC version to provide the right Cabal library version. Supersedes #9398 * Require version 3,11 of Cabal to support --semaphore flag Fixes #9197 * Add dependencies used by `PackageTests` to exe:cabal-tests The runner allows the tests to use extra dependencies and the custom Prelude from 'cabal-testsuite'. However, if the tests use a dependency, say 'directory', and there are two packages with the same unit id available in the store, the test fails since it doesn't know which one to pick. By including an extra dependency to directory, we force the test runner to use a specific version directory, fixing the test failure. * Use Paths_cabal_install for cabal-install version number (#9421) * Use PackageInfo for cabal-install version number * Use Paths_cabal_install instead * Adjust documentation --------- Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com> * Document --profiling-detail in setup-commands. Fixes #9182 * Add test requirement to PR template Adding test becomes a checkmark instead of “bonus points”. * A 'cabal path' command. (#8879) * Add a 'cabal path' command. * Formatting fix. * Another formatting fix. * Categorise "cabal path" as global command. * Allow individual paths to be printed. * Less duplication. * Add config-file to "cabal path". * Use sum type instead of strings. * cabal path: support --installdir. * Add documentation. * Better text. * Formatting. * Add some tests. * Improve tests. * Add changelog entry. * Mention "cabal path" in directory documentation. --------- Co-authored-by: Artem Pelenitsyn * Reimplement `cabal check` (#8427) * Fix Semigroup target instance When two target names are the same, `mappend`ing them should not error but just pick the first name. * Add `desugarBuildToolSimple` * Reimplement cabal check * Reorder test output * Fix autogen modules tests .cabal files * Add a number of tests * Add test for #7423 i.e. Do not warn on -O2 if under off-by-default package configuration flag conditional. * Add a regression for: * Add another -WErrr test This is to make sure we do *not* report it if it is under a user, off-by-default flag. * Add test for non manual user flags. * Add “absolute path in extra-lib-dirs” test * Add if/else test * Add “dircheck on abspath” check * Add Package version internal test * Add PackageVersionsStraddle test * Add changelog for #8427 * Integrate various reviews * Integrate Artem’s review (review) Clarify `combineNames` documentation By explaining the way it operates (working if the two names are equal or one is empty) and renaming the function from `combineName` to `combineNames`. (review) Use guards instead of if/then/else (review) Match inside argument list (review) Replace “white” with “allow” (review) Fix typo in comment (review) Fix typo in Check module documentation (review) Harmonise indentation for `data` decls First field goes in a new line than the data constructor, so we have more space. (review) Rename `Prim` module to `Types` (review) Add checkPackageFilesGPD `checkPackageFiles` — which works on PD — was used to perform IO. We introduce a function that does the same thing but works on GPD (which is more principled). `checkPackageFiles` cannot just be removed, since it is part of the interface of Distribution.PackageDescription.Check. Deprecation can be planned once “new check” is up and running. * Integrate Andreas’ review (review) Add named section to missing upper bound check “miss upper bound” checks will now list target type and name (“On executable 'myexe', these packages miss upper bounds”) for easier fixing by the user. (review) remove `cabal gen-bounds` suggestion Reasonable as `cabal gen-bounds` is stricter than `cabal check`, see https://github.com/haskell/cabal/pull/8427#issuecomment-1446712486 Once `gen-bounds` behaves in line with `check` we can readd the suggestion. (review) Do not warn on shared bounds When a target which depends on an internal library shares some dependencies with the latter, do not warn on upper bounds. An example is clearer library build-depends: text < 5 ⁝ build-depends: myPackage, ← no warning, internal text, ← no warning, shared bound monadacme ← warning! * Integrate Artem’s review /II (review) Split Check.hs Check.hs has been split in multiple file, each une sub 1000 lines: Check 857 lines Check.Common 147 lines Check.Conditional 204 lines Check.Monad 352 lines Check.Paths 387 lines Check.Target 765 lines Check.Warning 865 lines Migration guide: - Check GPD/PD checks plus work-tree checks. - Check.Common common types and functions that are *not* part of monadic checking setup. - Check.Conditional checks on CondTree and related matter (variables, duplicate modules). - Check.Monad Backbone of the checks, monadic inter- face and related functions. - Check.Paths Checks on files, directories, globs. - Check.Target Checks on realised targets (libraries, executables, benchmarks, testsuites). - Check.Warning Datatypes and strings for warnings and severities. (review) remove useless section header (review) Fix typo (review) Add warnings documentation (list) For each warning, we document constructor/brief description in the manual. This might not be much useful as not but it will come handy when introducing `--ignore=WARN` and similar flags. * (review Andreas) Clarify CheckExplanation comment Whoever modifies `CheckExplanation` data constructors needs to be aware that the documentation in doc/cabal-commands.rst has to be updated too. * Move internal Check modules to `other-modules` No need to expose Distribution.PackageDescription.Check.* to the world. API for checking, for cabal-install and other tools, should be in Distribution.PackageDescription.Check. * Make fourmolu happy Cabal codebase has now a formatter/style standard (see #8950). “Ravioli ravioli, give me the formuoli” * Do not check for OptO in scripts See #8963 for reason and clarification requests. * Remove useless PackageId parameter It is now in the Reader part of CheckM monad. * Do not check PVP on internal targets Internal: testsuite, benchmark. See #8361. * Make hlint happy * Fix #9122 When checking internal version ranges, we need to make sure we are not mistaking a libraries with the same name but from different packages. See #9132. * Fix grammar neither…nor, completing what done in #9162 * Integrate Brandon’s review: grammar * Remove unnecessary `-fvia-C` check Brandon’s review/II. --------- Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com> * ci: Enable windows tests for 9.6.3 There were two failing tests: 1. CCompilerOverride, was attempting to use gcc.exe rather than clang.exe without also overriding the C options which led to incorrect options being passed to gcc.exe. The fix is to override to clang.exe on ghc-9.4 or newer. 2. ForeignLibs exposes a bug in GHC (https://gitlab.haskell.org/ghc/ghc/-/issues/24185) and hence is skipped for GHCs newer than 9.4 where it was first introduced. Towards fixing #8451, we just need to fix the shared library issue now. * testsuite: Be explicit about runtime test dependencies Issue #8356 reports occasional errors from running the testsuite about multiple package versions available. This stems from the invokation of `runghc` not being explicit about all dependencies of the testsuite. The solution is provide a component in the cabal file which is explicit about which packages the tests can depend on. This component has a build-depends section which lists all the dependencies that the tests require. It would be better if this component was a library component but we can't do this with a Custom setup because of limitations to do with per-component builds. Then we also enable `-hide-all-packages`, so the dependency will not be available if it is not explicitly listed as a dependency. You could also imagine a future where the Setup.hs script found the test files and compiled a single executable which would run all the tests, rather than invoking runghc on each one individually. Fixes #8356 * hurd: Enable using $ORIGIN in RPATH GNU/Hurd fully supports RPATH and the $ORIGIN development, and we indeed want to use it for relocatable installations shipped in Debian GNU/Hurd. * Fix the platform string for GNU/Hurd Since version 9.4.7-1, ghc fails to build on the GNU/Hurd port of Debian, see https://buildd.debian.org/status/fetch.php?pkg=ghc&arch=hurd-i386&ver=9.4.7-1&stamp=1697717885&raw=0 Error, rule finished running but did not produce file: _build/stage0/lib/i386-gnu-ghc-9.4.6/ghc-boot-th-9.4.7/libHSghc-boot-th-9.4.7.a and indeed, what did get produce was rather _build/stage0/lib/i386-hurd-ghc-9.4.6/ghc-boot-th-9.4.7/libHSghc-boot-th-9.4.7.a (i386-hurd instead of i386-gnu). This is due to confusion between hurd and gnu in various places. Apparently previous versions of ghc were using gnu for the GNU/Hurd port, and thus putting libraries etc. in i386-gnu. So we have to follow the existing practice. * Fix configuation of ldProgram Standard GNU `ld` ues `--relocatable` while `ld.gold` uses a `-relocatable` flag (with a single `-`). Code will now detect both versions. * Chain configuration of ldProgram `ldProgram` gets configured in two places, a seemingly default and a GHC specific version. The later needs to be updated so that it first calls the default configuration and then the new GHC version. * Use linker capability detection to improve linker use The function `comperSupportsGhciLibs` has been renamed to `linkerSupportsGhciLibs` because its about the linker not the compiler. The function `comperSupportsGhciLibs` was using the compiler version as a proxy for whether the linker supports relocatable objects. Now support for relocatable objects is detected by running the linker. * add `merge+no rebase` and a few typos while reviewing * Add support for 64-bit SPARC as a separate architecture Previously, sparc64 was defined as an alias for the 32-bit SPARC architecture which was true while SPARC mainland was mostly 32 bits. More recently, 64-bit SPARC has become a port of its own, so it needs to be treated as a separate architecture. * Remove debug-conflict-sets flag from solver package Fixes #8937. The debug-conflict-sets build flag probably hasn't been used for a long time, and it isn't currently tested. This commit removes the flag, converts the ConflictSet type back to a newtype, and removes an unnecessary instance. * Finish improvements to the CI configuration for documentation changes (#9460) * Add bootstrap postjob to CI config Add a new job to the bootstrap.yml GitHub action config. This job succeeds if, and only if, all the other bootstrap jobs succeed. * Do not run bootstrap CI jobs for documentation changes The approach was already introduced in #9355 for the validate jobs. This commit introduces the same change also for the bootstrap jobs. * Also ignore CONTRIBUTING.md and README.md in CI We do not run the entire CI suite for documentation changes. Previously, only changes which were restricted to the 'docs/' subdirectory were considered to be documentation changes. With this commit we also recognize changes to README.md and CONTRIBUTING.md as documentation changes. * Document improved CI for documentation in CONTRIBUTING.md The CONTRIBUTING.md file now mentions that documentation changes do not waste expensive CI resources. * Recognize all README.md in subdirs as documentation Expensive CI jobs should not run on changes which affect only README.md files. * formatting: Add style-commit makefile target This target allows you to format a range of commits, for example: ``` make style-commit COMMIT=HEAD~1 > Last commit is formatted make style-commit COMMIT=abcde > Commits between HEAD and abcde are formatted ``` * Fix assertion failure when combining build-tool-depends and --enable-documentation The `setDocumentation` function was modifying the elaborated package after the hash was computed. This led to the assertion failing as the computed hash was different to what was computed in the initial install plan. Therefore in order to fix this we either needed to: 1. Set elabBuildHaddocks = False at the point where the hash is initially computed. 2. Verify that elabBuildHaddocks = True will not lead to unexpected results. The latter has been implemented. The elabBuildHaddocks option is only consulted in `hasValidHaddockTargets`, at which point documentation building the executable component is disabled because elabHaddockExecutables is False. In the added test we ensure this by checking that we didn't build documentation for the executable which is built because of build-tool-depends. Fixes #6006 #8313 * testsuite: Improve error message in findDependencyInStore * Only move code to Simple/GHC/Build* * CPP mingw32_HOST_OS for more imports * cabal-install-solver: fix pkgconf 1.9 --modversion regression Check that the numbers of *versions* output is equal to the number of pkgconf's fixes #8923 The pkgconf behavior was reverted upstream in 2.0 (this should cover the case too of checking that equal pkgList lines are output also) * External commands: Add tests for #9402 #9403 #9404 This adds 4 tests which test the new external commands feature: * ExternalCommand - Tests the expected usage of external command invoked via cabal-install * ExternalCommandSetup - Tests that the ./Setup interface does not support external commands (#9403) * ExternalCommandEnv - Tests that environment variables are set and preserved appropiately (#9402) * ExternalCommandHelp - Test that `cabal help ` is interpreted appropiately (#9404) * Finish off the external commands feature * Remove 'CommandDelegate' in favour of abstracting the fallback in 'commandsRun', there is a new variant 'commdandRunWithFallback' which takes a continuation - This restores the modularity between the `Cabal` library and `cabal-install` as now `Cabal` doesn't need to know anything about the external command interface. - Fixes #9403 * Set the $CABAL environment variable to the current executable path - This allows external commands to be implemented by calling $CABAL, which is strongly preferred to linking against the Cabal library as there is no easy way to guantee your tool and `cabal-install` link against the same `Cabal` library. - Fixes #9402 * Pass the name of the argument - This allows external commands to be implemented as symlinks to an executable, and multiple commands can be interpreted by the same executable. - Fixes #9405 * `cabal help ` is interpreted as `cabal- --help` for external commands. - This allows the `help` command to also work for external commands and hence they are better integrated into cabal-install. - Fixes #9404 The tests are updated to test all these additions. These features bring the external command interface up to par with the cargo external command interface. * Use Base16 hash for script path. Issue #9334 shows that `%` characters on Windows result in invalid paths, also `/` characters on Linux create invalid paths. This changes from using base64 to using base16 with the same length we use for unit-ids. * Migrate to haskell-actions/setup As of 2023-09-09, haskell/action/setup is no longer maintained. The comment # latest is mandatory for cabal-testsuite, see https://github.com/haskell/cabal/issues/8133 is removed; as the validate job was already fixing a version of cabal-install. * testsuite: Introduce Cabal-tests library for common testsuite functions I noticed that Distribution.Utils.TempTestDir was only used in the testsuite but defined in the Cabal library. Rather than expose this in the public interface of the `Cabal` library, it is cleaner to refactor it into a separate library (`Cabal-tests`) which can be used by any testsuite component. Also, in future it gives a clearer place to put utility functions which need to be shared across the testsuite but not exposed in Cabal. Cabal-tests can also freely add dependencies (such as exceptions) which we might want to avoid adding to the Cabal library. Fixes #9453 * GHC 9.8 compat: pacify -Wx-partial * GHC 9.8 compat: update hashes of data structures as computed by Structured It seems, GHC 9.8 changed something in the code generation for data types. Structured class is supposed to catch such cases. * GHC 9.8 compat: bump base, update Unknown GHC And bump Cabal's "supported version" of GHC * CI: GHC 9.8 * merge master * Hackage should be capitalized --------- Co-authored-by: Artem Pelenitsyn Co-authored-by: Bryan Richter Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com> Co-authored-by: Phil de Joux Co-authored-by: Yvan Sraka Co-authored-by: Andreas Abel Co-authored-by: Jens Petersen Co-authored-by: Andrea Bedini Co-authored-by: Hamish Mackenzie Co-authored-by: Malte Neuss Co-authored-by: Bodigrim Co-authored-by: David Binder Co-authored-by: David Binder Co-authored-by: Javier Sagredo Co-authored-by: Andrea Bedini Co-authored-by: Matthew Pickering Co-authored-by: Fendor Co-authored-by: Hécate Moonlight Co-authored-by: Andreas Klebinger Co-authored-by: Francesco Ariis Co-authored-by: Troels Henriksen Co-authored-by: Samuel Thibault Co-authored-by: Erik de Castro Lopo Co-authored-by: brandon s allbery kf8nh Co-authored-by: John Paul Adrian Glaubitz Co-authored-by: Kristen Kozak Co-authored-by: Javier Sagredo --- doc/cabal-project-description-file.rst | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/doc/cabal-project-description-file.rst b/doc/cabal-project-description-file.rst index baac75e06f9..1bf238063c7 100644 --- a/doc/cabal-project-description-file.rst +++ b/doc/cabal-project-description-file.rst @@ -193,9 +193,11 @@ Formally, the format is described by the following BNF: Specifying Packages from Remote Version Control Locations ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Starting with Cabal 2.4, there is now a stanza -``source-repository-package`` for specifying packages from an external -version control. +Since version 2.4, the ``source-repository-package`` stanza allows for +specifying packages in a remote version control system that cabal should +consider during package retrieval. This allows use of a package from a +remote version control system, rather than looking for that package in +Hackage. .. code-block:: cabal @@ -218,8 +220,11 @@ version control. tag: e76fdc753e660dfa615af6c8b6a2ad9ddf6afe70 post-checkout-command: autoreconf -i -cabal-install 3.4 sdists the ``source-repository-package`` repositories and uses resulting tarballs as project packages. -This allows sharing of packages across different projects. +Since version 3.4, cabal-install creates tarballs for each package coming +from a ``source-repository-package`` stanza (effectively applying cabal +sdists to such packages). It gathers the names of the packages from the +appropriate .cabal file in the version control repository, and allows +their use just like Hackage or locally defined packages. .. cfg-field:: type: VCS kind @@ -229,7 +234,7 @@ This allows sharing of packages across different projects. .. cfg-field:: subdir: subdirectory list - Use one or more subdirectories of the repository. + Look in one or more subdirectories of the repository for cabal files, rather than the root. .. cfg-field:: post-checkout-command: command