Skip to content

Commit 7d30976

Browse files
authored
Merge branch 'master' into invertable-attribute
2 parents 148542b + 6a2edd9 commit 7d30976

File tree

1 file changed

+49
-9
lines changed

1 file changed

+49
-9
lines changed

README.md

Lines changed: 49 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1903,14 +1903,20 @@ for details.
19031903
@echo '{{ style("error") }}OH NO{{ NORMAL }}'
19041904
```
19051905

1906-
##### XDG Directories<sup>1.23.0</sup>
1906+
##### User Directories<sup>1.23.0</sup>
19071907

19081908
These functions return paths to user-specific directories for things like
1909-
configuration, data, caches, executables, and the user's home directory. These
1910-
functions follow the
1911-
[XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html),
1912-
and are implemented with the
1913-
[`dirs`](https://docs.rs/dirs/latest/dirs/index.html) crate.
1909+
configuration, data, caches, executables, and the user's home directory.
1910+
1911+
On Unix, these functions follow the
1912+
[XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html).
1913+
1914+
On MacOS and Windows, these functions return the system-specified user-specific
1915+
directories. For example, `cache_directory()` returns `~/Library/Caches` on
1916+
MacOS and `{FOLDERID_LocalAppData}` on Windows.
1917+
1918+
See the [`dirs`](https://docs.rs/dirs/latest/dirs/index.html) crate for more
1919+
details.
19141920

19151921
- `cache_directory()` - The user-specific cache directory.
19161922
- `config_directory()` - The user-specific configuration directory.
@@ -1920,6 +1926,10 @@ and are implemented with the
19201926
- `executable_directory()` - The user-specific executable directory.
19211927
- `home_directory()` - The user's home directory.
19221928

1929+
If you would like to use XDG base directories on all platforms you can use the
1930+
`env(…)` function with the appropriate environment variable, e.g.,
1931+
`env('XDG_CACHE_HOME')`.
1932+
19231933
### Constants
19241934

19251935
A number of constants are predefined:
@@ -3482,9 +3492,39 @@ and recipes defined after the `import` statement.
34823492
Imported files can themselves contain `import`s, which are processed
34833493
recursively.
34843494

3485-
When `allow-duplicate-recipes` is set, recipes in parent modules override
3486-
recipes in imports. In a similar manner, when `allow-duplicate-variables` is
3487-
set, variables in parent modules override variables in imports.
3495+
`allow-duplicate-recipes` and `allow-duplicate-variables` allow duplicate
3496+
recipes and variables, respectively, to override each other, instead of
3497+
producing an error.
3498+
3499+
Within a module, later definitions override earlier definitions:
3500+
3501+
```just
3502+
set allow-duplicate-recipes
3503+
3504+
foo:
3505+
3506+
foo:
3507+
echo 'yes'
3508+
```
3509+
3510+
When `import`s are involved, things unfortunately get much more complicated and
3511+
hard to explain.
3512+
3513+
Shallower definitions always override deeper definitions, so recipes at the top
3514+
level will override recipes in imports, and recipes in an import will override
3515+
recipes in an import which itself imports those recipes.
3516+
3517+
When two duplicate definitions are imported and are at the same depth, the one
3518+
from the earlier import will override the one from the later import.
3519+
3520+
This is because `just` uses a stack when processing imports, pushing imports
3521+
onto the stack in source-order, and always processing the top of the stack
3522+
next, so earlier imports are actually handled later by the compiler.
3523+
3524+
This is definitely a bug, but since `just` has very strong backwards
3525+
compatibility guarantees and we take enormous pains not to break anyone's
3526+
`justfile`, we have created issue #2540 to discuss whether or not we can
3527+
actually fix it.
34883528

34893529
Imports may be made optional by putting a `?` after the `import` keyword:
34903530

0 commit comments

Comments
 (0)