mirror of
https://github.com/apple/pkl.git
synced 2026-08-27 14:14:02 +02:00
Use XDG base directories and Known Folders on Windows (#1809)
This changes logic that previously read/wrote from `~/.pkl` to use XDG base directories (all OSes), and Known Folders locations on Windows. For example, Pkl will look for `settings.pkl` in: 1. `$XDG_CONFIG_HOME/pkl/settings.pkl` 2. `%APPDATA/pkl/settings.pkl` 3. `~/.pkl/settings.pkl` 4. Path pkl/settings/pkl within `$XDG_CONFIG_DIRS` 5. `/etc/xdg/pkl/settings.pkl` --------- Co-authored-by: Florin Ungur <florin@florinungur.com>
This commit is contained in:
Daniel Chao
co-authored by
Florin Ungur
Florin Ungur
parent
4dd37219c0
commit
6551a59f9e
@@ -360,7 +360,7 @@ at pkl.base#Module.output.text (https://github.com/apple/pkl/blob/e4d8c882d/stdl
|
||||
<6> What Pkl evaluated to discover the error.
|
||||
|
||||
When Pkl prints source locations, it also prints clickable links for easy access.
|
||||
For local files, it generates a link for your development environment (https://pkl-lang.org/main/current/pkl-cli/index.html#settings-file[configurable in `+~/.pkl/settings.pkl+`]).
|
||||
For local files, it generates a link for your development environment (https://pkl-lang.org/main/current/pkl-cli/index.html#settings-file[configurable in `+~/.config/pkl/settings.pkl+`]).
|
||||
For packages imported from elsewhere, if available, Pkl produces `https://` links to their repository.
|
||||
|
||||
Pkl complains about a _type constraint_.
|
||||
|
||||
@@ -1377,14 +1377,24 @@ it works as follows:
|
||||
The Pkl settings file allows to customize the CLI experience.
|
||||
|
||||
A settings file is a Pkl module amending the `pkl.settings` standard library module.
|
||||
Its default location is `~/.pkl/settings.pkl`.
|
||||
|
||||
Unless configured explicitly, Pkl will look in the following locations:
|
||||
|
||||
. `$XDG_CONFIG_HOME/pkl/settings.pkl`
|
||||
. `%APPDATA%/pkl/settings.pkl` (on Windows only)
|
||||
. `~/.config/pkl/settings.pkl`
|
||||
. Subdirectory `pkl/settings.pkl` within one of the paths described by `$XDG_CONFIG_DIRS`
|
||||
. `/etc/xdg/pkl/settings.pkl`
|
||||
. `~/.pkl/settings.pkl` (legacy location used by Pkl 0.32 and lower)
|
||||
|
||||
To use a different settings file, set the `--settings` command line option, for example `--settings mysettings.pkl`.
|
||||
To enforce default settings, use `--settings pkl:settings`.
|
||||
|
||||
The settings file is also honored by (and configurable through) the Gradle plugin and `CliEvaluator` API.
|
||||
|
||||
Here is a typical settings file:
|
||||
|
||||
.~/.pkl/settings.pkl
|
||||
.~/.config/pkl/settings.pkl
|
||||
[source%parsed,{pkl}]
|
||||
----
|
||||
amends "pkl:settings" // <1>
|
||||
@@ -1406,10 +1416,19 @@ When making TLS requests, Pkl comes with its own set of {uri-certificates}[CA ce
|
||||
These certificates can be overridden via either of the two options:
|
||||
|
||||
- Set them directly via the CLI option `--ca-certificates <path>`.
|
||||
- Add them to a directory at path `~/.pkl/cacerts/`.
|
||||
- Add them to a user directory.
|
||||
|
||||
If CA certificates are not explicitly configured, Pkl will look in the following locations:
|
||||
|
||||
. `$XDG_CONFIG_HOME/pkl/cacerts`
|
||||
. `%APPDATA%/pkl/cacerts` (on Windows only)
|
||||
. `~/.config/pkl/cacerts`
|
||||
. Subdirectory `pkl/cacerts` within one of the paths described by `$XDG_CONFIG_DIRS`
|
||||
. `/etc/xdg/pkl/cacerts`
|
||||
. `~/.pkl/cacerts` (legacy location used by Pkl 0.32 and lower)
|
||||
|
||||
Both these options will *replace* the default CA certificates bundled with Pkl. +
|
||||
The CLI option takes precedence over the certificates in `~/.pkl/cacerts/`. +
|
||||
The CLI option takes precedence over the certificates in the cacerts directory. +
|
||||
Certificates need to be X.509 certificates in PEM format.
|
||||
|
||||
[[http-proxy]]
|
||||
|
||||
@@ -36,9 +36,15 @@ Possible values:
|
||||
.--cache-dir
|
||||
[%collapsible]
|
||||
====
|
||||
Default: `~/.pkl/cache` +
|
||||
Example: `/path/to/module/cache/` +
|
||||
|
||||
The cache directory for storing packages.
|
||||
|
||||
If unset, defaults to the following locations:
|
||||
|
||||
. `$XDG_CACHE_HOME/pkl`
|
||||
. `$LOCALAPPDATA/pkl/Cache` (on Windows only)
|
||||
. `~/.cache/pkl` (if `$XDG_CACHE_HOME` and `$LOCALAPPDATA` are both unset)
|
||||
====
|
||||
|
||||
.--no-cache
|
||||
@@ -97,7 +103,7 @@ Any symlinks are resolved before this check is performed.
|
||||
Default: (none) +
|
||||
Example: `mySettings.pkl` +
|
||||
File path of the Pkl settings file to use.
|
||||
If not set, `~/.pkl/settings.pkl` or defaults specified in the `pkl.settings` standard library module are used.
|
||||
If not set, `~/.config/pkl/settings.pkl` on Unix or `%APPDATA%/pkl/settings.pkl` on Windows (or the legacy `~/.pkl/settings.pkl`), or defaults specified in the `pkl.settings` standard library module are used.
|
||||
====
|
||||
|
||||
.-t, --timeout
|
||||
|
||||
@@ -64,7 +64,9 @@ Default: `null` +
|
||||
Example 1: `moduleCacheDir = layout.buildDirectory.dir("pkl-module-cache")` +
|
||||
Example 2: `moduleCacheDir.fileValue file("/absolute/path/to/cache")` +
|
||||
The cache directory for storing packages.
|
||||
If `null`, defaults to `~/.pkl/cache`.
|
||||
If `null`, defaults to `~/.cache/pkl` on Unix or `%LOCALAPPDATA%/pkl/Cache` on Windows.
|
||||
|
||||
This setting can also be configured using the `$XDG_CACHE_HOME` environment variable.
|
||||
====
|
||||
|
||||
.color: Property<Boolean>
|
||||
|
||||
@@ -69,7 +69,7 @@ Example: `settingsModule = layout.projectDirectory.file("mySettings.pkl")` +
|
||||
The Pkl settings module to use.
|
||||
This property accepts the same input types as the `sourceModules` property.
|
||||
|
||||
If `null`, `~/.pkl/settings.pkl` or defaults specified in the `pkl.settings` standard library module are used.
|
||||
If `null`, `~/.config/pkl/settings.pkl` on Unix or `%APPDATA%/pkl/settings.pkl` on Windows (or the legacy `~/.pkl/settings.pkl`), or defaults specified in the `pkl.settings` standard library module are used.
|
||||
====
|
||||
|
||||
include::../partials/gradle-common-properties.adoc[]
|
||||
|
||||
@@ -13,7 +13,43 @@ include::partial$intro.adoc[]
|
||||
|
||||
== Noteworthy [small]#🎶#
|
||||
|
||||
=== XXX
|
||||
=== CLI Changes
|
||||
|
||||
==== Default file locations
|
||||
|
||||
For new setups, the CLI no longer stores anything under `~/.pkl` (https://github.com/apple/pkl/pull/1809[#1809]).
|
||||
|
||||
It uses XDG-style locations on Unix and Known Folder locations on Windows:
|
||||
|
||||
[cols="1,2,2,2",options="header"]
|
||||
|===
|
||||
| Concern | Unix (Linux/macOS) | Windows | Legacy fallback
|
||||
|
||||
| Package cache
|
||||
| `~/.cache/pkl`
|
||||
| `$LOCALAPPDATA/pkl/Cache`
|
||||
| none
|
||||
|
||||
| Settings file
|
||||
| `~/.config/pkl/settings.pkl`
|
||||
| `$APPDATA/pkl/settings.pkl`
|
||||
| `~/.pkl/settings.pkl`
|
||||
|
||||
| CA certificates
|
||||
| `~/.config/pkl/cacerts`
|
||||
| `$APPDATA/pkl/cacerts`
|
||||
| `~/.pkl/cacerts`
|
||||
|
||||
| REPL history
|
||||
| `~/.local/state/pkl/repl-history`
|
||||
| `$LOCALAPPDATA/pkl/repl-history`
|
||||
| none
|
||||
|===
|
||||
|
||||
On every OS, these locations can be overridden with XDG-style env vars.
|
||||
For example, setting `XDG_CACHE_HOME` will configure the cache directory.
|
||||
|
||||
Note that the existing `~/.pkl/cache` directory is ignored, so Pkl will download packages to populate its cache if configured to do so.
|
||||
|
||||
== Breaking Changes [small]#💔#
|
||||
|
||||
|
||||
Reference in New Issue
Block a user