Merge pull request #4280 from JuliaLang/backports-release-1.12

Author: KristofferC

CHANGELOG.md

@@ -5,6 +5,7 @@ Pkg v1.12 Release Notes
   The functions `Pkg.status`, `Pkg.why`, `Pkg.instantiate`, `Pkg.precompile` (and their REPL variants) have been updated
   to take a `workspace` option. Read more about this feature in the manual about the TOML-files.
 - `status` now shows when different versions/sources of dependencies are loaded than that which is expected by the manifest ([#4109])
+- Enhanced fuzzy matching algorithm for package name suggestions.
 
 Pkg v1.11 Release Notes
 =======================

docs/make.jl

@@ -35,6 +35,7 @@ makedocs(
         "managing-packages.md",
         "environments.md",
         "creating-packages.md",
+        "apps.md",
         "compatibility.md",
         "registries.md",
         "artifacts.md",

docs/src/api.md

@@ -1,4 +1,4 @@
-# [**12.** API Reference](@id API-Reference)
+# [**13.** API Reference](@id API-Reference)
 
 This section describes the functional API for interacting with Pkg.jl.
 It is recommended to use the functional API, rather than the Pkg REPL mode,

docs/src/apps.md

@@ -1,4 +1,4 @@
-# [**?.** Apps](@id Apps)
+# [**6.** Apps](@id Apps)
 
 !!! note
     The app support in Pkg is currently considered experimental and some functionality and API may change.
@@ -7,17 +7,16 @@
     - You need to manually make `~/.julia/bin` available on the PATH environment.
     - The path to the julia executable used is the same as the one used to install the app. If this
       julia installation gets removed, you might need to reinstall the app.
-    - You can only have one app installed per package.
 
-Apps are Julia packages that are intended to be run as a "standalone programs" (by e.g. typing the name of the app in the terminal possibly together with some arguments or flags/options).
+Apps are Julia packages that are intended to be run as "standalone programs" (by e.g. typing the name of the app in the terminal possibly together with some arguments or flags/options).
 This is in contrast to most Julia packages that are used as "libraries" and are loaded by other files or in the Julia REPL.
 
 ## Creating a Julia app
 
 A Julia app is structured similar to a standard Julia library with the following additions:
 
 - A `@main` entry point in the package module (see the [Julia help on `@main`](https://docs.julialang.org/en/v1/manual/command-line-interface/#The-Main.main-entry-point) for details)
-- An `[app]` section in the `Project.toml` file listing the executable names that the package provides.
+- An `[apps]` section in the `Project.toml` file listing the executable names that the package provides.
 
 A very simple example of an app that prints the reversed input arguments would be:
 
@@ -49,11 +48,53 @@ After installing this app one could run:
 
 ```
 $ reverse some input string
-emos tupni gnirts
+ emos tupni gnirts
 ```
 
 directly in the terminal.
 
+## Multiple Apps per Package
+
+A single package can define multiple apps by using submodules. Each app can have its own entry point in a different submodule of the package.
+
+```julia
+# src/MyMultiApp.jl
+module MyMultiApp
+
+function (@main)(ARGS)
+    println("Main app: ", join(ARGS, " "))
+end
+
+include("CLI.jl")
+
+end # module
+```
+
+```julia
+# src/CLI.jl
+module CLI
+
+function (@main)(ARGS)
+    println("CLI submodule: ", join(ARGS, " "))
+end
+
+end # module CLI
+```
+
+```toml
+# Project.toml
+
+# standard fields here
+
+[apps]
+main-app = {}
+cli-app = { submodule = "CLI" }
+```
+
+This will create two executables:
+- `main-app` that runs `julia -m MyMultiApp`
+- `cli-app` that runs `julia -m MyMultiApp.CLI`
+
 ## Installing Julia apps
 
-The installation of Julia apps are similar to installing julia libraries but instead of using e.g. `Pkg.add` or `pkg> add` one uses `Pkg.Apps.add` or `pkg> app add` (`develop` is also available).
+The installation of Julia apps is similar to [installing Julia libraries](@ref Managing-Packages) but instead of using e.g. `Pkg.add` or `pkg> add` one uses `Pkg.Apps.add` or `pkg> app add` (`develop` is also available).

docs/src/artifacts.md

@@ -1,4 +1,4 @@
-# [**8.** Artifacts](@id Artifacts)
+# [**9.** Artifacts](@id Artifacts)
 
 `Pkg` can install and manage containers of data that are not Julia packages.  These containers can contain platform-specific binaries, datasets, text, or any other kind of data that would be convenient to place within an immutable, life-cycled datastore.
 These containers, (called "Artifacts") can be created locally, hosted anywhere, and automatically downloaded and unpacked upon installation of your Julia package.

docs/src/compatibility.md

@@ -1,4 +1,4 @@
-# [**6.** Compatibility](@id Compatibility)
+# [**7.** Compatibility](@id Compatibility)
 
 Compatibility refers to the ability to restrict the versions of the dependencies that your project is compatible with.
 If the compatibility for a dependency is not given, the project is assumed to be compatible with all versions of that dependency.
@@ -164,7 +164,7 @@ PkgA = "0.2 - 0"       # 0.2.0 - 0.*.* = [0.2.0, 1.0.0)
 ```
 
 
-## Fixing conflicts
+## [Fixing conflicts](@id Fixing-conflicts)
 
 Version conflicts were introduced previously with an [example](@ref conflicts)
 of a conflict arising in a package `D` used by two other packages, `B` and `C`.

docs/src/creating-packages.md

@@ -11,7 +11,7 @@
 To generate the bare minimum files for a new package, use `pkg> generate`.
 
 ```julia-repl
-(@v1.8) pkg> generate HelloWorld
+(@v1.10) pkg> generate HelloWorld
 ```
 
 This creates a new project `HelloWorld` in a subdirectory by the same name, with the following files (visualized with the external [`tree` command](https://linux.die.net/man/1/tree)):
@@ -118,7 +118,7 @@ describe about public symbols. A public symbol is a symbol that is exported from
 package with the `export` keyword or marked as public with the `public` keyword. When you
 change the behavior of something that was previously public so that the new
 version no longer conforms to the specifications provided in the old version, you should
-adjust your package version number according to [Julia's variant on SemVer](#Version-specifier-format).
+adjust your package version number according to [Julia's variant on SemVer](@ref Version-specifier-format).
 If you would like to include a symbol in your public API without exporting it into the
 global namespace of folks who call `using YourPackage`, you should mark that symbol as
 public with `public that_symbol`. Symbols marked as public with the `public` keyword are
@@ -649,3 +649,10 @@ To support the various use cases in the Julia package ecosystem, the Pkg develop
 * [`Preferences.jl`](https://github.com/JuliaPackaging/Preferences.jl) allows packages to read and write preferences to the top-level `Project.toml`.
   These preferences can be read at runtime or compile-time, to enable or disable different aspects of package behavior.
   Packages previously would write out files to their own package directories to record options set by the user or environment, but this is highly discouraged now that `Preferences` is available.
+
+## See Also
+
+- [Managing Packages](@ref Managing-Packages) - Learn how to add, update, and manage package dependencies
+- [Working with Environments](@ref Working-with-Environments) - Understand environments and reproducible development
+- [Compatibility](@ref Compatibility) - Specify version constraints for dependencies
+- [API Reference](@ref) - Functional API for non-interactive package management

docs/src/environments.md

@@ -10,7 +10,7 @@ It should be pointed out that when two projects use the same package at the same
 In order to create a new project, create a directory for it and then activate that directory to make it the "active project", which package operations manipulate:
 
 ```julia-repl
-(@v1.9) pkg> activate MyProject
+(@v1.10) pkg> activate MyProject
 Activating new environment at `~/MyProject/Project.toml`
 
 (MyProject) pkg> st
@@ -28,7 +28,7 @@ false
    Installed Example ─ v0.5.3
     Updating `~/MyProject/Project.toml`
   [7876af07] + Example v0.5.3
-    Updating `~~/MyProject/Manifest.toml`
+    Updating `~/MyProject/Manifest.toml`
   [7876af07] + Example v0.5.3
 Precompiling environment...
   1 dependency successfully precompiled in 2 seconds
@@ -45,7 +45,7 @@ Example = "7876af07-990d-54b4-ab0e-23690620f79a"
 julia> print(read(joinpath("MyProject", "Manifest.toml"), String))
 # This file is machine-generated - editing it directly is not advised
 
-julia_version = "1.9.4"
+julia_version = "1.10.0"
 manifest_format = "2.0"
 project_hash = "2ca1c6c58cb30e79e021fb54e5626c96d05d5fdc"
 
@@ -66,7 +66,7 @@ shell> git clone https://github.com/JuliaLang/Example.jl.git
 Cloning into 'Example.jl'...
 ...
 
-(@v1.12) pkg> activate Example.jl
+(@v1.10) pkg> activate Example.jl
 Activating project at `~/Example.jl`
 
 (Example) pkg> instantiate
@@ -82,7 +82,7 @@ If you only have a `Project.toml`, a `Manifest.toml` must be generated by "resol
 
 If you already have a resolved `Manifest.toml`, then you will still need to ensure that the packages are installed and with the correct versions. Again `instantiate` does this for you.
 
-In short, `instantiate` is your friend to make sure an environment is ready to use. If there's nothing to do, `instantiate` does nothing.
+In short, [`instantiate`](@ref Pkg.instantiate) is your friend to make sure an environment is ready to use. If there's nothing to do, `instantiate` does nothing.
 
 !!! note "Specifying project on startup"
     Instead of using `activate` from within Julia, you can specify the project on startup using
@@ -103,7 +103,7 @@ also want a scratch space to try out a new package, or a sandbox to resolve vers
 between several incompatible packages.
 
 ```julia-repl
-(@v1.9) pkg> activate --temp # requires Julia 1.5 or later
+(@v1.10) pkg> activate --temp # requires Julia 1.5 or later
   Activating new environment at `/var/folders/34/km3mmt5930gc4pzq1d08jvjw0000gn/T/jl_a31egx/Project.toml`
 
 (jl_a31egx) pkg> add Example
@@ -121,14 +121,14 @@ A "shared" environment is simply an environment that exists in `~/.julia/environ
 therefore a shared environment:
 
 ```julia-repl
-(@v1.9) pkg> st
+(@v1.10) pkg> st
 Status `~/.julia/environments/v1.9/Project.toml`
 ```
 
 Shared environments can be activated with the `--shared` flag to `activate`:
 
 ```julia-repl
-(@v1.9) pkg> activate --shared mysharedenv
+(@v1.10) pkg> activate --shared mysharedenv
   Activating project at `~/.julia/environments/mysharedenv`
 
 (@mysharedenv) pkg>
@@ -151,7 +151,7 @@ or using Pkg's precompile option, which can precompile the entire environment, o
 which can be significantly faster than the code-load route above.
 
 ```julia-repl
-(@v1.9) pkg> precompile
+(@v1.10) pkg> precompile
 Precompiling environment...
   23 dependencies successfully precompiled in 36 seconds
 ```
@@ -165,7 +165,7 @@ By default, any package that is added to a project or updated in a Pkg action wi
 with its dependencies.
 
 ```julia-repl
-(@v1.9) pkg> add Images
+(@v1.10) pkg> add Images
    Resolving package versions...
     Updating `~/.julia/environments/v1.9/Project.toml`
   [916415d5] + Images v0.25.2

docs/src/getting-started.md

@@ -22,18 +22,18 @@ To get back to the Julia REPL, press `Ctrl+C` or backspace (when the REPL cursor
 Upon entering the Pkg REPL, you should see the following prompt:
 
 ```julia-repl
-(@v1.9) pkg>
+(@v1.10) pkg>
 ```
 
 To add a package, use `add`:
 
 ```julia-repl
-(@v1.9) pkg> add Example
+(@v1.10) pkg> add Example
    Resolving package versions...
    Installed Example ─ v0.5.3
-    Updating `~/.julia/environments/v1.9/Project.toml`
+    Updating `~/.julia/environments/v1.10/Project.toml`
   [7876af07] + Example v0.5.3
-    Updating `~/.julia/environments/v1.9/Manifest.toml`
+    Updating `~/.julia/environments/v1.10/Manifest.toml`
   [7876af07] + Example v0.5.3
 ```
 
@@ -49,14 +49,14 @@ julia> Example.hello("friend")
 We can also specify multiple packages at once to install:
 
 ```julia-repl
-(@v1.9) pkg> add JSON StaticArrays
+(@v1.10) pkg> add JSON StaticArrays
 ```
 
 The `status` command (or the shorter `st` command) can be used to see installed packages.
 
 ```julia-repl
-(@v1.9) pkg> st
-Status `~/.julia/environments/v1.6/Project.toml`
+(@v1.10) pkg> st
+Status `~/.julia/environments/v1.10/Project.toml`
   [7876af07] Example v0.5.3
   [682c06a0] JSON v0.21.3
   [90137ffa] StaticArrays v1.5.9
@@ -68,27 +68,27 @@ Status `~/.julia/environments/v1.6/Project.toml`
 To remove packages, use `rm` (or `remove`):
 
 ```julia-repl
-(@v1.9) pkg> rm JSON StaticArrays
+(@v1.10) pkg> rm JSON StaticArrays
 ```
 
 Use `up` (or `update`) to update the installed packages
 
 ```julia-repl
-(@v1.9) pkg> up
+(@v1.10) pkg> up
 ```
 
 If you have been following this guide it is likely that the packages installed are at the latest version
 so `up` will not do anything. Below we show the status output in the case where we deliberately have installed
 an old version of the Example package and then upgrade it:
 
 ```julia-repl
-(@v1.9) pkg> st
-Status `~/.julia/environments/v1.9/Project.toml`
+(@v1.10) pkg> st
+Status `~/.julia/environments/v1.10/Project.toml`
 ⌃ [7876af07] Example v0.5.1
 Info Packages marked with ⌃ have new versions available and may be upgradable.
 
-(@v1.9) pkg> up
-    Updating `~/.julia/environments/v1.9/Project.toml`
+(@v1.10) pkg> up
+    Updating `~/.julia/environments/v1.10/Project.toml`
   [7876af07] ↑ Example v0.5.1 ⇒ v0.5.3
 ```
 
@@ -110,7 +110,7 @@ Let's set up a new environment so we may experiment.
 To set the active environment, use `activate`:
 
 ```julia-repl
-(@v1.9) pkg> activate tutorial
+(@v1.10) pkg> activate tutorial
 [ Info: activating new environment at `~/tutorial/Project.toml`.
 ```
 
@@ -166,16 +166,16 @@ For more information about environments, see the [Working with Environments](@re
 If you are ever stuck, you can ask `Pkg` for help:
 
 ```julia-repl
-(@v1.9) pkg> ?
+(@v1.10) pkg> ?
 ```
 
 You should see a list of available commands along with short descriptions.
 You can ask for more detailed help by specifying a command:
 
 ```julia-repl
-(@v1.9) pkg> ?develop
+(@v1.10) pkg> ?develop
 ```
 
 This guide should help you get started with `Pkg`.
-`Pkg` has much more to offer in terms of powerful package management,
-read the full manual to learn more!
+`Pkg` has much more to offer in terms of powerful package management.
+For more advanced topics, see [Managing Packages](@ref Managing-Packages), [Working with Environments](@ref Working-with-Environments), and [Creating Packages](@ref creating-packages-tutorial).

docs/src/glossary.md

@@ -1,4 +1,4 @@
-# [**9.** Glossary](@id Glossary)
+# [**10.** Glossary](@id Glossary)
 
 **Project:** a source tree with a standard layout, including a `src` directory
 for the main body of Julia code, a `test` directory for testing the project,
@@ -46,7 +46,7 @@ since that could conflict with the configuration of the main application.
 
 **Environment:** the combination of the top-level name map provided by a project
 file combined with the dependency graph and map from packages to their entry points
-provided by a manifest file. For more detail see the manual section on code loading.
+provided by a manifest file. For more detail see the [manual section on code loading](https://docs.julialang.org/en/v1/manual/code-loading/).
 
 - **Explicit environment:** an environment in the form of an explicit project
   file and an optional corresponding manifest file together in a directory. If the