Re commercialhaskell#6492 Further prefer 'project packages' to 'local packages'

Also seeks to distinguish where 'local packages' is intended to refer to project packages and local extra-deps, for example in the context of the contents of the mutable package database (the local package database).

Author: mpilgrem

src/Stack/Build.hs

@@ -272,11 +272,11 @@ warnIfExecutablesWithSameNameCouldBeOverwritten locals plan = do
          | not (null otherLocals)
          ]
  where
-  -- Cases of several local packages having executables with the same name.
+  -- Cases of several project packages having executables with the same name.
   -- The Map entries have the following form:
   --
   --  executable name: ( package names for executables that are being built
-  --                   , package names for other local packages that have an
+  --                   , package names for other project packages that have an
   --                     executable with the same name
   --                   )
   warnings :: Map Text ([PackageName],[PackageName])
@@ -285,16 +285,16 @@ warnIfExecutablesWithSameNameCouldBeOverwritten locals plan = do
       (\(pkgsToBuild, localPkgs) ->
         case (pkgsToBuild, NE.toList localPkgs \\ NE.toList pkgsToBuild) of
           (_ :| [], []) ->
-            -- We want to build the executable of single local package
-            -- and there are no other local packages with an executable of
+            -- We want to build the executable of single project package
+            -- and there are no other project packages with an executable of
             -- the same name. Nothing to warn about, ignore.
             Nothing
           (_, otherLocals) ->
             -- We could be here for two reasons (or their combination):
             -- 1) We are building two or more executables with the same
             --    name that will end up overwriting each other.
             -- 2) In addition to the executable(s) that we want to build
-            --    there are other local packages with an executable of the
+            --    there are other project packages with an executable of the
             --    same name that might get overwritten.
             -- Both cases warrant a warning.
             Just (NE.toList pkgsToBuild, otherLocals))

src/Stack/Build/ConstructPlan.hs

@@ -97,7 +97,7 @@ import           System.Environment ( lookupEnv )
 -- and the interdependencies among the build 'Task's. In particular:
 --
 -- 1) It determines which packages need to be built, based on the transitive
--- deps of the current targets. For local packages, this is indicated by the
+-- deps of the current targets. For project packages, this is indicated by the
 -- 'lpWanted' boolean. For extra packages to build, this comes from the
 -- @extraToBuild0@ argument of type @Set PackageName@. These are usually
 -- packages that have been specified on the command line.
@@ -312,7 +312,7 @@ constructPlan
     pure $ pPackages <> deps
 
 -- | Determine which packages to unregister based on the given tasks and
--- already registered local packages.
+-- already registered project packages and local extra-deps.
 mkUnregisterLocal ::
      Map PackageName Task
      -- ^ Tasks

src/Stack/Build/Execute.hs

@@ -210,7 +210,7 @@ executePlan :: HasEnvConfig env
             -> [LocalPackage]
             -> [DumpPackage] -- ^ global packages
             -> [DumpPackage] -- ^ snapshot packages
-            -> [DumpPackage] -- ^ local packages
+            -> [DumpPackage] -- ^ project packages and local extra-deps
             -> InstalledMap
             -> Map PackageName Target
             -> Plan

src/Stack/Build/ExecuteEnv.hs

@@ -251,7 +251,7 @@ withExecuteEnv ::
   -> [LocalPackage]
   -> [DumpPackage] -- ^ global packages
   -> [DumpPackage] -- ^ snapshot packages
-  -> [DumpPackage] -- ^ local packages
+  -> [DumpPackage] -- ^ project packages and local extra-deps
   -> Maybe Int -- ^ largest package name, for nicer interleaved output
   -> (ExecuteEnv -> RIO env a)
   -> RIO env a

src/Stack/Build/Haddock.hs

@@ -116,7 +116,7 @@ shouldHaddockPackage bopts wanted name =
 shouldHaddockDeps :: BuildOpts -> Bool
 shouldHaddockDeps bopts = fromMaybe bopts.buildHaddocks bopts.haddockDeps
 
--- | Generate Haddock index and contents for local packages.
+-- | Generate Haddock index and contents for project packages.
 generateLocalHaddockIndex ::
      (HasCompiler env, HasProcessContext env, HasTerm env)
   => BaseConfigOpts
@@ -141,7 +141,7 @@ generateLocalHaddockIndex bco localDumpPkgs locals = do
     "."
     (localDocDir bco)
 
--- | Generate Haddock index and contents for local packages and their
+-- | Generate Haddock index and contents for project packages and their
 -- dependencies.
 generateDepsHaddockIndex ::
      (HasCompiler env, HasProcessContext env, HasTerm env)
@@ -319,11 +319,11 @@ lookupDumpPackage ghcPkgId dumpPkgs =
 haddockIndexFile :: Path Abs Dir -> Path Abs File
 haddockIndexFile destDir = destDir </> relFileIndexHtml
 
--- | Path of local packages documentation directory.
+-- | Path of project packages documentation directory.
 localDocDir :: BaseConfigOpts -> Path Abs Dir
 localDocDir bco = bco.localInstallRoot </> docDirSuffix
 
--- | Path of documentation directory for the dependencies of local packages
+-- | Path of documentation directory for the dependencies of project packages
 localDepsDocDir :: BaseConfigOpts -> Path Abs Dir
 localDepsDocDir bco = localDocDir bco </> relDirAll
 

src/Stack/Build/Source.hs

@@ -209,7 +209,7 @@ depPackageHashableContent dp =
         <> getUtf8Builder (mconcat ghcOptions)
         <> getUtf8Builder (mconcat cabalConfigOpts)
 
--- | All flags for a local package.
+-- | All flags for a project package.
 getLocalFlags ::
      BuildOptsCLI
   -> PackageName

src/Stack/Build/Target.hs

@@ -171,8 +171,8 @@ parseRawTargetDirs root locals ri =
             [] -> pure $ Left $
               fillSep
                 [ style Dir (fromString $ T.unpack t)
-                , flow "is not a local package directory and it is not a \
-                       \parent directory of any local package directory."
+                , flow "is not a local directory for a package and it is not a \
+                       \parent directory of any such directory."
                 ]
             names -> pure $ Right $ map ((ri, ) . RTPackage) names
  where
@@ -316,7 +316,7 @@ resolveRawTarget sma allLocs (rawInput, rt) =
     case Map.lookup name locals of
       Nothing -> pure $ Left $
         fillSep
-          [ flow "Unknown local package:"
+          [ flow "Unknown project package:"
           , style Target (fromPackageName name) <> "."
           ]
       Just pp -> do

src/Stack/Clean.hs

@@ -49,8 +49,8 @@ instance Exception CleanException where
 data CleanOpts
   = CleanShallow [PackageName]
     -- ^ Delete the "dist directories" as defined in
-    -- 'Stack.Constants.Config.distRelativeDir' for the given local packages. If
-    -- no packages are given, all project packages should be cleaned.
+    -- 'Stack.Constants.Config.distRelativeDir' for the given project packages.
+    -- If no project packages are given, all project packages should be cleaned.
   | CleanFull
     -- ^ Delete all work directories in the project.
 

src/Stack/Dot.hs

@@ -27,11 +27,11 @@ dotCmd dotOpts = do
   printGraph dotOpts localNames prunedGraph
 
 -- | Print a graphviz graph of the edges in the Map and highlight the given
--- local packages
+-- project packages
 printGraph ::
      (Applicative m, MonadIO m)
   => DotOpts
-  -> Set PackageName -- ^ all locals
+  -> Set PackageName -- ^ All project packages.
   -> Map PackageName (Set PackageName, DotPayload)
   -> m ()
 printGraph dotOpts locals graph = do
@@ -44,7 +44,8 @@ printGraph dotOpts locals graph = do
   filteredLocals =
     Set.filter (\local' -> local' `Set.notMember` dotOpts.prune) locals
 
--- | Print the local nodes with a different style depending on options
+-- | Print the project packages nodes with a different style, depending on
+-- options
 printLocalNodes ::
      (F.Foldable t, MonadIO m)
   => DotOpts

src/Stack/Ghci.hs

@@ -219,9 +219,8 @@ ghciCmd ghciOpts =
               }
         local (set buildOptsL boptsLocal) (ghci ghciOpts)
 
--- | Launch a GHCi session for the given local package targets with the
--- given options and configure it with the load paths and extensions
--- of those targets.
+-- | Launch a GHCi session for the given project package targets with the given
+-- options and configure it with the load paths and extensions of those targets.
 ghci :: HasEnvConfig env => GhciOpts -> RIO env ()
 ghci opts = do
   let buildOptsCLI = defaultBuildOptsCLI
@@ -280,7 +279,7 @@ ghci opts = do
         case targets of
           TargetAll _  -> [T.pack (packageNameString pn)]
           TargetComps comps -> [renderPkgComponent (pn, c) | c <- toList comps]
-  -- Build required dependencies and setup local packages.
+  -- Build required dependencies and setup project packages.
   buildDepsAndInitialSteps opts $
     concatMap (\(pn, (_, t)) -> pkgTargets pn t) localTargets
   targetWarnings localTargets nonLocalTargets mfileTargets
@@ -472,11 +471,11 @@ getAllNonLocalTargets targets = do
 buildDepsAndInitialSteps :: HasEnvConfig env => GhciOpts -> [Text] -> RIO env ()
 buildDepsAndInitialSteps ghciOpts localTargets = do
   let targets = localTargets ++ map T.pack ghciOpts.additionalPackages
-  -- If necessary, do the build, for local packagee targets, only do
+  -- If necessary, do the build, for project packagee targets, only do
   -- 'initialBuildSteps'.
   whenJust (nonEmpty targets) $ \nonEmptyTargets ->
     unless ghciOpts.noBuild $ do
-      -- only new local targets could appear here
+      -- only new project package targets could appear here
       eres <- buildLocalTargets nonEmptyTargets
       case eres of
         Right () -> pure ()
@@ -1133,19 +1132,20 @@ targetWarnings localTargets nonLocalTargets mfileTargets = do
       , parens $ fillSep $ punctuate "," $ map
           (style Good . fromPackageName)
           nonLocalTargets
-      , flow "are not local packages, and so cannot be directly loaded. In \
+      , flow "are not project packages, and so cannot be directly loaded. In \
              \future versions of Stack, this might be supported - see"
-      , style Url "https://github.com/commercialhaskell/stack/issues/1441"
-      , "."
+      , style Url "https://github.com/commercialhaskell/stack/issues/1441" <> "."
       , flow "It can still be useful to specify these, as they will be passed \
-             \to ghci via -package flags."
+             \to ghci via"
+      , style Shell "-package"
+      , "flags."
       ]
   when (null localTargets && isNothing mfileTargets) $ do
     smWanted <- view $ buildConfigL . to (.smWanted)
     stackYaml <- view stackYamlL
     prettyNote $ vsep
-      [ flow "No local targets specified, so a plain ghci will be started with \
-             \no package hiding or package options."
+      [ flow "No project package targets specified, so a plain ghci will be \
+             \started with no package hiding or package options."
       , ""
       , flow $ T.unpack $ utf8BuilderToText $
                "You are using snapshot: " <>

src/Stack/Init.hs

@@ -671,8 +671,8 @@ cabalPackagesCheck cabaldirs = do
   when (null cabaldirs) $
     prettyWarn $
          fillSep
-           [ flow "Stack did not find any local package directories. You may \
-                  \want to create a package with"
+           [ flow "Stack did not find any local directories containing a \
+                  \package description. You may want to create a package with"
            , style Shell (flow "stack new")
            , flow "instead."
            ]

src/Stack/Ls.hs

@@ -131,7 +131,7 @@ data ListDepsTextFilter
   = FilterPackage PackageName
     -- ^ Item is a package name.
   | FilterLocals
-    -- ^ Item represents all local packages.
+    -- ^ Item represents all project packages.
 
 -- | Type representing command line options for the @stack ls stack-colors@ and
 -- @stack ls stack-colours@ commands.

src/Stack/Options/BuildMonoidParser.hs

@@ -172,8 +172,9 @@ buildOptsMonoidParser hide0 = BuildOptsMonoid
     hide
   forceDirty = firstBoolFlagsFalse
     "force-dirty"
-    "forcing the treatment of all local packages as having dirty files. \
-    \Useful for cases where Stack can't detect a file change."
+    "forcing the treatment of all project packages and local extra-deps as \
+    \having dirty files. Useful for cases where Stack can't detect a file \
+    \change."
     hide
   tests = firstBoolFlagsFalse
     "test"

src/Stack/SDist.hs

@@ -186,7 +186,8 @@ sdistCmd sdistOpts =
     createDirectoryIfMissing True $ FP.takeDirectory targetTarPath
     copyFile (toFilePath tarPath) targetTarPath
 
--- | Given the path to a local package, creates its source distribution tarball.
+-- | Given the path to a package directory, creates a source distribution
+-- tarball for the package.
 --
 -- While this yields a 'FilePath', the name of the tarball, this tarball is not
 -- written to the disk and instead yielded as a lazy bytestring.
@@ -195,7 +196,7 @@ getSDistTarball ::
   => Maybe PvpBounds
      -- ^ Override Config value
   -> Path Abs Dir
-     -- ^ Path to local package
+     -- ^ Path to package directory
   -> RIO
        env
        ( FilePath

src/Stack/Types/ApplyGhcOptions.hs

@@ -10,9 +10,9 @@ import           Stack.Prelude
 
 -- | Which packages do ghc-options on the command line apply to?
 data ApplyGhcOptions
-  = AGOTargets -- ^ all local targets
-  | AGOLocals -- ^ all local packages, even non-targets
-  | AGOEverything -- ^ every package
+  = AGOTargets -- ^ All project packages that are targets.
+  | AGOLocals -- ^ All project packages, even non-targets.
+  | AGOEverything -- ^ All packages, project packages and dependencies.
   deriving (Bounded, Enum, Eq, Ord, Read, Show)
 
 instance FromJSON ApplyGhcOptions where

src/Stack/Types/ApplyProgOptions.hs

@@ -11,9 +11,9 @@ import           Stack.Prelude
 -- | Which packages do all and any --PROG-option options on the command line
 -- apply to?
 data ApplyProgOptions
-  = APOTargets -- ^ All local packages that are targets.
-  | APOLocals -- ^ All local packages (targets or otherwise).
-  | APOEverything -- ^ All packages (local or otherwise).
+  = APOTargets -- ^ All project packages that are targets.
+  | APOLocals -- ^ All project packages (targets or otherwise).
+  | APOEverything -- ^ All packages (project packages or dependencies).
   deriving (Bounded, Enum, Eq, Ord, Read, Show)
 
 instance FromJSON ApplyProgOptions where

src/Stack/Types/Build/ConstructPlan.hs

@@ -236,8 +236,8 @@ instance HasCompiler Ctx where
 instance HasEnvConfig Ctx where
   envConfigL = lens (.ctxEnvConfig) (\x y -> x { ctxEnvConfig = y })
 
--- | State to be maintained during the calculation of local packages to
--- unregister.
+-- | State to be maintained during the calculation of project packages and local
+-- extra-deps to unregister.
 data UnregisterState = UnregisterState
   { toUnregister :: !(Map GhcPkgId (PackageIdentifier, Text))
   , toKeep :: ![DumpPackage]

src/Stack/Types/Build/Exception.hs

@@ -456,9 +456,8 @@ pprintTargetParseErrors errs =
        , style Shell "my-package-0.1.2.3" <> "),"
        , flow "a package component (e.g."
        , style Shell "my-package:test:my-test-suite" <> "),"
-       , flow "or, failing that, a relative path to a directory that is a \
-              \local package directory or a parent directory of one or more \
-              \local package directories."
+       , flow "or, failing that, a relative path to a local directory for a \
+              \package or a parent directory of one or more such directories."
        ]
 
 pprintExceptions ::

src/Stack/Types/BuildOpts.hs

@@ -52,7 +52,8 @@ data BuildOpts = BuildOpts
   , keepTmpFiles :: !Bool
     -- ^ Keep intermediate files and build directories
   , forceDirty :: !Bool
-    -- ^ Force treating all local packages as having dirty files
+    -- ^ Force treating all project packages and local extra-deps as having
+    -- dirty files.
   , tests :: !Bool
     -- ^ Turn on tests for local targets
   , testOpts :: !TestOpts

src/Stack/Types/EnvConfig.hs

@@ -231,7 +231,7 @@ packageDatabaseDeps = do
   root <- installationRootDeps
   pure $ root </> relDirPkgdb
 
--- | Package database for installing local packages into
+-- | Package database for installing project packages and local extra-deps into.
 packageDatabaseLocal :: HasEnvConfig env => RIO env (Path Abs Dir)
 packageDatabaseLocal = do
   root <- installationRootLocal

src/Stack/Types/EnvSettings.hs

@@ -13,7 +13,7 @@ import           Stack.Prelude
 -- | Controls which version of the environment is used
 data EnvSettings = EnvSettings
   { includeLocals :: !Bool
-  -- ^ include local project bin directory, GHC_PACKAGE_PATH, etc
+  -- ^ include project's local bin directory, GHC_PACKAGE_PATH, etc
   , includeGhcPackagePath :: !Bool
   -- ^ include the GHC_PACKAGE_PATH variable
   , stackExe :: !Bool

tests/integration/tests/cabal-sublibrary-dependency/Main.hs

@@ -2,7 +2,7 @@ import Control.Monad (unless)
 import Data.List (isInfixOf)
 import StackTest
 
--- This tests building two local packages, one of which depends on the other
+-- This tests building two project packages, one of which depends on the other
 -- (subproject). The dependency has a library and a visible sub-library named
 -- sub, each of which exposes a module that exports a function.