Merge branch 'master' into dirs

.github/pull_request_template.md

@@ -10,8 +10,7 @@ Include the following checklist in your PR:
 * [ ] Any changes that could be relevant to users [have been recorded in the changelog](https://github.com/haskell/cabal/blob/master/CONTRIBUTING.md#changelog).
 * [ ] The documentation has been updated, if necessary.
 * [ ] [Manual QA notes](https://github.com/haskell/cabal/blob/master/CONTRIBUTING.md#qa-notes) have been included.
-
-Bonus points for added automated tests!
+* [ ] Tests have been added. (*Ask for help if you don’t know how to write them! Ask for an exemption if tests are too complex for too little coverage!*)
 
 ---
 

.github/workflows/format.yml

@@ -10,8 +10,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v4
-    - uses: haskell-actions/run-fourmolu@v8
+    - uses: haskell-actions/run-fourmolu@v9
       with:
+        version: "0.12.0.0"
         pattern: |
           Cabal/**/*.hs
           Cabal-syntax/**/*.hs

.github/workflows/lint.yml

@@ -9,10 +9,10 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v4
-    - uses: haskell/actions/hlint-setup@v2
+    - uses: haskell-actions/hlint-setup@v2
       with:
         version: "3.5"
-    - uses: haskell/actions/hlint-run@v2
+    - uses: haskell-actions/hlint-run@v2
       with:
         path: "."
-        fail-on: suggestion
+        fail-on: suggestion

.github/workflows/validate.skip.yml

@@ -0,0 +1,33 @@
+name: Validate Skip
+
+# This Workflow is special and contains a workaround for a known limitation of GitHub CI.
+#
+# The problem: We don't want to run the "validate" jobs on PRs which contain only changes
+# to the docs, since these jobs take a long time to complete without providing any benefit.
+# We therefore use path-filtering in the workflow triggers for the validate jobs, namely
+# "paths_ignore: doc/**". But the "Validate post job" is a required job, therefore a PR cannot
+# be merged unless the "Validate post job" completes succesfully, which it doesn't do if we 
+# filter it out.
+#
+# The solution: We use a second job with the same name which always returns the exit code 0.
+# The logic implemented for "required" workflows accepts if 1) at least one job with that name
+# runs through, AND 2) If multiple jobs of that name exist, then all jobs of that name have to
+# finish successfully.
+on:
+  push:
+    paths: 'doc/**'
+    branches:
+      - master
+  pull_request:
+    paths: 'doc/**'
+  release:
+    types:
+      - created
+
+jobs:
+  validate-post-job:
+    if: always()
+    name: Validate post job
+    runs-on: ubuntu-latest
+    steps:
+      - run: exit 0

.github/workflows/validate.yml

@@ -11,22 +11,27 @@ concurrency:
   group: ${{ github.ref }}-${{ github.workflow }}
   cancel-in-progress: true
 
+# Note: This workflow file contains the required job "Validate post job". We are using path filtering
+# here to ignore PRs which only change documentation. This can cause a problem, see the workflow file
+# "validate.skip.yml" for a description of the problem and the solution provided in that file.
 on:
   push:
+    paths-ignore: 'doc/**'
     branches:
       - master
   pull_request:
+    paths-ignore: 'doc/**'
   release:
     types:
       - created
 
 env:
   # We choose a stable ghc version across all os's
   # which will be used to do the next release
-  GHC_FOR_RELEASE: '9.2.7'
+  GHC_FOR_RELEASE: '9.2.8'
   # Ideally we should use the version about to be released for hackage tests and benchmarks
-  GHC_FOR_SOLVER_BENCHMARKS: '9.2.7'
-  GHC_FOR_COMPLETE_HACKAGE_TESTS: '9.2.7'
+  GHC_FOR_SOLVER_BENCHMARKS: '9.2.8'
+  GHC_FOR_COMPLETE_HACKAGE_TESTS: '9.2.8'
   COMMON_FLAGS: '-j 2 -v'
 
 jobs:
@@ -38,7 +43,7 @@ jobs:
     strategy:
       matrix:
         os: ["ubuntu-latest", "macos-latest", "windows-latest"]
-        ghc: ["9.6.1", "9.4.4", "9.2.7", "9.0.2", "8.10.7", "8.8.4", "8.6.5", "8.4.4"]
+        ghc: ["9.6.3", "9.4.7", "9.2.8", "9.0.2", "8.10.7", "8.8.4", "8.6.5", "8.4.4"]
         exclude:
           # corrupts GHA cache or the fabric of reality itself, see https://github.com/haskell/cabal/issues/8356
           - os: "windows-latest"
@@ -107,7 +112,7 @@ jobs:
           echo "FLAGS=$FLAGS" >> $GITHUB_ENV
 
       - name: Allow newer dependencies when built with latest GHC
-        if: ${{ matrix.ghc }} == '9.6.1'
+        if: ${{ matrix.ghc }} == '9.6.3'
         run: |
           echo "allow-newer: rere:base, rere:transformers" >> cabal.project.validate
 
@@ -161,15 +166,15 @@ jobs:
         # Have to disable *-suite validation:
         # - the [email protected] problem is tracked at https://github.com/haskell/cabal/issues/8858
         # - but curently can't run it with GHC 9.6, tracking: https://github.com/haskell/cabal/issues/8883
-        if: (runner.os != 'Windows')  || (matrix.ghc != '9.6.1')
+        if: (runner.os != 'Windows')  || (matrix.ghc != '9.6.3')
         run: sh validate.sh $FLAGS -s lib-suite
 
       - name: Validate cli-tests
         run: sh validate.sh $FLAGS -s cli-tests
 
       - name: Validate cli-suite
         # Have to disable *-suite validation, see above the comment for lib-suite
-        if: (runner.os != 'Windows')  || (matrix.ghc != '9.6.1')
+        if: (runner.os != 'Windows')  || (matrix.ghc != '9.6.3')
         run: sh validate.sh $FLAGS -s cli-suite
 
   validate-old-ghcs:

.gitignore

@@ -73,6 +73,8 @@ cabal-testsuite/**/haddocks
 # python artifacts from documentation builds
 *.pyc
 .python-sphinx-virtualenv/
+venv
+.venv
 /doc/.skjold_cache/
 
 # macOS folder metadata
@@ -83,3 +85,6 @@ bench.html
 
 # Emacs
 .projectile
+
+# I'm unsure how to ignore these generated golden files
+cabal-testsuite/PackageTests/NewUpdate/RejectFutureIndexStates/cabal.out

.hlint.yaml

@@ -94,9 +94,10 @@
 - ignore: {name: "Use when"} # 1 hint
 
 - arguments:
+    - --ignore-glob=Cabal-syntax/src/Distribution/Fields/Lexer.hs
     - --ignore-glob=cabal-testsuite/PackageTests/CmmSources/src/Demo.hs
     - --ignore-glob=cabal-testsuite/PackageTests/CmmSourcesDyn/src/Demo.hs
-    - --ignore-glob=Cabal-syntax/src/Distribution/Fields/Lexer.hs
+    - --ignore-glob=cabal-testsuite/PackageTests/CmmSourcesExe/src/Demo.hs
     - --ignore-glob=templates/Paths_pkg.template.hs
     - --ignore-glob=templates/SPDX.LicenseExceptionId.template.hs
     - --ignore-glob=templates/SPDX.LicenseId.template.hs

Cabal-syntax/src/Distribution/Fields/Field.hs

@@ -1,6 +1,8 @@
+{-# LANGUAGE CPP #-}
 {-# LANGUAGE DeriveFoldable #-}
 {-# LANGUAGE DeriveFunctor #-}
 {-# LANGUAGE DeriveTraversable #-}
+{-# LANGUAGE StandaloneDeriving #-}
 
 -- | Cabal-like file AST types: 'Field', 'Section' etc
 --
@@ -36,6 +38,9 @@ import Distribution.Compat.Prelude
 import Distribution.Pretty (showTokenStr)
 import Distribution.Utils.Generic (fromUTF8BS)
 import Prelude ()
+#if MIN_VERSION_base(4,18,0)
+import qualified Data.Foldable1 as F1
+#endif
 
 -------------------------------------------------------------------------------
 -- Cabal file
@@ -47,6 +52,9 @@ data Field ann
   | Section !(Name ann) [SectionArg ann] [Field ann]
   deriving (Eq, Show, Functor, Foldable, Traversable)
 
+-- | @since 3.12.0.0
+deriving instance Ord ann => Ord (Field ann)
+
 -- | Section of field name
 fieldName :: Field ann -> Name ann
 fieldName (Field n _) = n
@@ -69,6 +77,9 @@ fieldUniverse f@(Field _ _) = [f]
 data FieldLine ann = FieldLine !ann !ByteString
   deriving (Eq, Show, Functor, Foldable, Traversable)
 
+-- | @since 3.12.0.0
+deriving instance Ord ann => Ord (FieldLine ann)
+
 -- | @since 3.0.0.0
 fieldLineAnn :: FieldLine ann -> ann
 fieldLineAnn (FieldLine ann _) = ann
@@ -87,6 +98,9 @@ data SectionArg ann
     SecArgOther !ann !ByteString
   deriving (Eq, Show, Functor, Foldable, Traversable)
 
+-- | @since 3.12.0.0
+deriving instance Ord ann => Ord (SectionArg ann)
+
 -- | Extract annotation from 'SectionArg'.
 sectionArgAnn :: SectionArg ann -> ann
 sectionArgAnn (SecArgName ann _) = ann
@@ -105,6 +119,9 @@ type FieldName = ByteString
 data Name ann = Name !ann !FieldName
   deriving (Eq, Show, Functor, Foldable, Traversable)
 
+-- | @since 3.12.0.0
+deriving instance Ord ann => Ord (Name ann)
+
 mkName :: ann -> FieldName -> Name ann
 mkName ann bs = Name ann (B.map Char.toLower bs)
 
@@ -141,3 +158,30 @@ fieldLinesToString =
   intercalate "\n" . map toStr
   where
     toStr (FieldLine _ bs) = fromUTF8BS bs
+
+-------------------------------------------------------------------------------
+-- Foldable1
+-------------------------------------------------------------------------------
+
+#if MIN_VERSION_base(4,18,0)
+
+-- | @since 3.12.0.0
+instance F1.Foldable1 Field where
+  foldMap1 f (Field x ys) =
+    F1.fold1 (F1.foldMap1 f x :| map (F1.foldMap1 f) ys)
+  foldMap1 f (Section x ys zs) =
+    F1.fold1 (F1.foldMap1 f x :| map (F1.foldMap1 f) ys ++ map (F1.foldMap1 f) zs)
+
+-- | @since 3.12.0.0
+instance F1.Foldable1 FieldLine where
+  foldMap1 = (. fieldLineAnn)
+
+-- | @since 3.12.0.0
+instance F1.Foldable1 SectionArg where
+  foldMap1 = (. sectionArgAnn)
+
+-- | @since 3.12.0.0
+instance F1.Foldable1 Name where
+  foldMap1 = (. nameAnn)
+
+#endif

Cabal-tests/Cabal-tests.cabal

@@ -60,15 +60,15 @@ test-suite unit-tests
     , Cabal-QuickCheck
     , containers
     , deepseq
-    , Diff                >=0.4   && <0.5
+    , Diff                >=0.4   && <0.6
     , directory
     , filepath
     , integer-logarithms  >=1.0.2 && <1.1
     , pretty
     , QuickCheck          >=2.14  && <2.15
     , rere                >=0.1   && <0.3
     , tagged
-    , tasty               >=1.2.3 && <1.5
+    , tasty               >=1.2.3 && <1.6
     , tasty-hunit
     , tasty-quickcheck
     , temporary
@@ -84,14 +84,14 @@ test-suite parser-tests
   main-is:          ParserTests.hs
   build-depends:
       base
-    , base-compat       >=0.11.0  && <0.13
+    , base-compat       >=0.11.0  && <0.14
     , bytestring
     , Cabal-syntax
     , Cabal-tree-diff
-    , Diff              >=0.4     && <0.5
+    , Diff              >=0.4     && <0.6
     , directory
     , filepath
-    , tasty             >=1.2.3   && <1.5
+    , tasty             >=1.2.3   && <1.6
     , tasty-golden      >=2.3.1.1 && <2.4
     , tasty-hunit
     , tasty-quickcheck
@@ -109,10 +109,10 @@ test-suite check-tests
     , bytestring
     , Cabal
     , Cabal-syntax
-    , Diff          >=0.4     && <0.5
+    , Diff          >=0.4     && <0.6
     , directory
     , filepath
-    , tasty         >=1.2.3   && <1.5
+    , tasty         >=1.2.3   && <1.6
     , tasty-expected-failure
     , tasty-golden  >=2.3.1.1 && <2.4
 
@@ -155,10 +155,10 @@ test-suite hackage-tests
     , filepath
 
   build-depends:
-      base-compat           >=0.11.0   && <0.13
-    , base-orphans          >=0.6      && <0.9
+      base-compat           >=0.11.0   && <0.14
+    , base-orphans          >=0.6      && <0.10
     , clock                 >=0.8      && <0.9
-    , optparse-applicative  >=0.13.2.0 && <0.17
+    , optparse-applicative  >=0.13.2.0 && <0.19
     , stm                   >=2.4.5.0  && <2.6
     , tar                   >=0.5.0.3  && <0.6
     , tree-diff             >=0.1      && <0.4
@@ -178,7 +178,7 @@ test-suite rpmvercmp
 
   build-depends:
       QuickCheck
-    , tasty             >=1.2.3 && <1.5
+    , tasty             >=1.2.3 && <1.6
     , tasty-hunit
     , tasty-quickcheck
 
@@ -197,7 +197,7 @@ test-suite no-thunks-test
       base
     , bytestring
     , Cabal-syntax
-    , tasty        >=1.2.3 && <1.5
+    , tasty        >=1.2.3 && <1.6
     , tasty-hunit
 
   -- this is test is buildable on old GHCs

Cabal/ChangeLog.md

@@ -1,3 +1,6 @@
+# 3.10.2.1 [Hécate](mailto:[email protected]) October 2023
+* See https://github.com/haskell/cabal/blob/master/release-notes/Cabal-3.10.2.1.md
+
 # 3.10.2.0 [Hécate](mailto:[email protected]) August 2023
 * See https://github.com/haskell/cabal/blob/master/release-notes/Cabal-3.10.2.0.md
 

Cabal/src/Distribution/Compat/ResponseFile.hs

@@ -65,6 +65,12 @@ escape cs c
 
 #endif
 
+-- | The arg file / response file parser.
+--
+-- This is not a well-documented capability, and is a bit eccentric
+-- (try @cabal \@foo \@bar@ to see what that does), but is crucial
+-- for allowing complex arguments to cabal and cabal-install when
+-- using command prompts with strongly-limited argument length.
 expandResponse :: [String] -> IO [String]
 expandResponse = go recursionLimit "."
   where

Cabal/src/Distribution/Lex.hs

@@ -16,6 +16,14 @@ import Distribution.Compat.DList
 import Distribution.Compat.Prelude
 import Prelude ()
 
+-- | A simple parser supporting quoted strings.
+--
+-- Please be aware that this will only split strings when seeing whitespace
+-- outside of quotation marks, i.e, @"foo\"bar baz\"qux quux"@ will be
+-- converted to @["foobar bazqux", "quux"]@.
+--
+-- This behavior can be useful when parsing text like
+-- @"ghc-options: -Wl,\"some option with spaces\""@, for instance.
 tokenizeQuotedWords :: String -> [String]
 tokenizeQuotedWords = filter (not . null) . go False mempty
   where

Cabal/src/Distribution/Make.hs

@@ -88,8 +88,10 @@ defaultMainArgs :: [String] -> IO ()
 defaultMainArgs = defaultMainHelper
 
 defaultMainHelper :: [String] -> IO ()
-defaultMainHelper args =
-  case commandsRun (globalCommand commands) commands args of
+defaultMainHelper args = do
+  command <- commandsRun (globalCommand commands) commands args
+  case command of
+    CommandDelegate -> pure ()
     CommandHelp help -> printHelp help
     CommandList opts -> printOptionsList opts
     CommandErrors errs -> printErrors errs
@@ -98,6 +100,7 @@ defaultMainHelper args =
         _
           | fromFlag (globalVersion flags) -> printVersion
           | fromFlag (globalNumericVersion flags) -> printNumericVersion
+        CommandDelegate -> pure ()
         CommandHelp help -> printHelp help
         CommandList opts -> printOptionsList opts
         CommandErrors errs -> printErrors errs