Skip to content

Commit 3c9ac93

Browse files
deempdeemp
committed
upd readme
1 parent 365e7b4 commit 3c9ac93

File tree

1 file changed

+94
-31
lines changed

1 file changed

+94
-31
lines changed

‎README.md‎

Lines changed: 94 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -6,36 +6,53 @@ This action is based on [actions/cache](https://github.com/actions/cache).
66

77
## Approach
88

9-
The [nix-quick-install-action](https://github.com/nixbuild/nix-quick-install-action) action makes `/nix/store` owned by an unpriviliged user.
10-
That's why, the `cache-nix-action` action can restore and save `/nix`.
9+
1. The [nix-quick-install-action](https://github.com/nixbuild/nix-quick-install-action) action makes `/nix/store` owned by an unpriviliged user.
10+
1. `cache-nix-action` restores `/nix`.
1111

12-
When there is a cache hit, restoring `/nix/store` from a cache is faster than downloading multiple paths from binary caches (see [ci.yaml](.github/workflows/ci.yaml) and related [Actions](https://github.com/nix-community/cache-nix-action/actions/workflows/ci.yaml)).
12+
* When there's a cache hit, restoring `/nix/store` from a cache is faster than downloading multiple paths from binary caches.
13+
* You can compare run times of jobs with and without store caching in [Actions](https://github.com/nix-community/cache-nix-action/actions/workflows/ci.yaml).
14+
* Open a run and click on the time under `Total duration`.
1315

14-
The [Approaches](#approaches) section compares this approach with other caching approaches.
16+
1. Optionally, `cache-nix-action` purges old caches.
17+
* As Nix (flake) inputs may change, it's necessary to use fresher caches.
18+
* Caches can be purged by `created` or `last accessed` time (see [Configuration](#configuration)).
19+
20+
1. Optionally, `cache-nix-action` collects garbage in the Nix store (see [Garbage Collection](#garbage-collection)).
21+
* The store may contain useless paths from previous runs.
22+
* This action allows to limit nix store size (see [Configuration](#configuration)).
23+
24+
1. `cache-nix-action` saves a new cache.
1525

1626
## Limitations
1727

18-
* Restores and saves a full `/nix` directory.
19-
* Requires `nix-quick-install-action` (see [Approach](#approach)).
20-
* Store size is limited by a runner storage size ([lnk](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources)).
28+
* `cache-nix-action` restores and saves the whole `/nix` directory.
29+
* `cache-nix-action` requires `nix-quick-install-action` (see [Approach](#approach)).
30+
* Store size is limited by a runner storage size ([link](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources)).
2131
* Caches are isolated between branches ([link](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows#restrictions-for-accessing-a-cache)).
22-
* When restoring, this action writes cached Nix store paths into a read-only `/nix/store` of a runner. Some of these paths may already be present, so this action will show `File exists` errors and a warning that it failed to restore. It's OK.
23-
* May be necessary to purge old caches (see [Example workflow](#example-workflow)).
32+
* When restoring, `cache-nix-action` writes cached Nix store paths into a read-only `/nix/store` of a runner.
33+
Some of these paths may already be present, so the action will show `File exists` errors and a warning that it failed to restore.
34+
It's OK.
35+
* It may be necessary to purge old caches (see [Example workflow](#example-workflow)) and [New inputs](#new-inputs).
2436

2537
## Configuration
2638

2739
See [action.yaml](action.yaml).
2840

2941
This action inherits some [inputs](#inputs) and [outputs](#outputs) of `actions/cache`.
42+
Other inputs are new or override the inherited inputs.
3043

3144
### New inputs
3245

33-
| `name` | `description` | `required` | `default` |
34-
| ---------------------- | ------------------------------------------------------------------------------------------- | ---------- | --------- |
35-
| `macos-gc-enabled` | When `true`, enables conditional garbage collection before saving a cache on macOS runners. | `false` | `false` |
36-
| `macos-max-cache-size` | Maximum Nix store size in bytes on macOS runners. Requires `macos-gc-enabled: true`. | `false` | |
37-
| `linux-gc-enabled` | When `true`, enables conditional garbage collection before saving a cache on Linux runners. | `false` | `false` |
38-
| `linux-max-cache-size` | Maximum Nix store size in bytes on Linux runners. Requires `linux-gc-enabled: true`. | `false` | |
46+
| `name` | `description` | `required` | `default` |
47+
| ------------------------- | ------------------------------------------------------------------------------------------- | ---------- | --------- |
48+
| `gc-enabled-macos` | When `true`, enables on `macOS` runners Nix store garbage collection before saving a cache. | `false` | `false` |
49+
| `gc-max-cache-size-macos` | Maximum Nix store size in bytes on `macOS` runners. Requires `gc-enabled-macos: true`. | `false` | |
50+
| `gc-enabled-linux` | When `true`, enables on `Linux` runners Nix store garbage collection before saving a cache. | `false` | `false` |
51+
| `gc-max-cache-size-linux` | Maximum Nix store size in bytes on `Linux` runners. Requires `gc-enabled-linux: true`. | `false` | |
52+
| `purge-enabled` | When `true`, old caches will be purged before saving a cache. | `false` | `false` |
53+
| `purge-max-age` | Purge all caches older than this value in seconds. Requires `purge-enabled: true`. | `false` | `604800` |
54+
| `purge-by-accessed-time` | When `true`, delete caches by `last accessed` time. Requires `purge-enabled: true`. | `false` | `false` |
55+
| `purge-by-created-time` | When `true`, delete caches by `created` time. Requires `purge-enabled: true`. | `false` | `true` |
3956

4057
### Default cached directories
4158

@@ -44,21 +61,19 @@ Instead, the `cache-nix-action` caches `/nix`, `~/.cache/nix`, `~root/.cache/nix
4461

4562
### Garbage collection parameters
4663

47-
On `macOS` runners, when `macos-gc-enabled` is `true`, when a cache size is greater than `macos-max-cache-size`, this action will run `nix store gc --max R` before saving a cache.
48-
Here, `R` is `max(0, S - macos-max-store-size)`, where `S` is the current store size.
64+
On `macOS` runners, when `gc-enabled-macos` is `true`, when a cache size is greater than `gc-max-cache-size-macos`, this action will run `nix store gc --max R` before saving a cache.
65+
Here, `R` is `max(0, S - gc-max-store-size-macos)`, where `S` is the current store size.
4966
Respective conditions hold for `Linux` runners.
5067

51-
Tip: if you need to save a path from caching, `nix profile install` it (see [Example workflow](#example-workflow))
52-
5368
There are alternative approaches to garbage collection (see [Garbage collection](#garbage-collection)).
5469

5570
## Usage
5671

5772
* This action **must** be used with [nix-quick-install-action](https://github.com/nixbuild/nix-quick-install-action).
58-
* Maximum Nix store size on `Linux` runners will be `512MB` due to `linux-max-store-size: 536870912`.
73+
* Maximum Nix store size on `Linux` runners will be `512MB` due to `gc-max-store-size-linux: 536870912`.
5974
* If the store has a larger size, it will be garbage collected to reach this limit (See [Garbage collection parameters](#garbage-collection-parameters)).
6075
* Maximum Nix store size on `macOS` runners will be limited by the runner storage size.
61-
* Stores won't be garbage collected since `macos-gc-enabled: true` isn't set.
76+
* Stores won't be garbage collected since `gc-enabled-macos: true` isn't set.
6277

6378
```yaml
6479
- uses: nixbuild/nix-quick-install-action@v25
@@ -69,13 +84,19 @@ There are alternative approaches to garbage collection (see [Garbage collection]
6984
keep-outputs = true
7085
7186
- name: Restore and cache Nix store
72-
uses: nix-community/cache-nix-action@v1
87+
uses: nix-community/cache-nix-action@v2
7388
with:
74-
linux-gc-enabled: true
75-
linux-max-store-size: 536870912
76-
key: cache-${{ matrix.os }}-${{ hashFiles('**/*') }}
89+
gc-enabled-linux: true
90+
gc-max-store-size-linux: 1000000000
91+
92+
purge-enabled: true
93+
purge-max-age: 86400
94+
purge-by-created-time: true
95+
purge-by-accessed-time: true
96+
97+
key: cache-${{ matrix.os }}-${{ hashFiles('**/*.nix') }}
7798
restore-keys: |
78-
cache-${{ matrix.os }}
99+
cache-${{ matrix.os }}-
79100
```
80101
81102
## Example workflow
@@ -86,10 +107,6 @@ See [ci.yaml](.github/workflows/ci.yaml).
86107
87108
* Use [action-tmate](https://github.com/mxschmitt/action-tmate) to debug on a runner via SSH.
88109
89-
## Garbage collection
90-
91-
Discussed [here](https://github.com/nix-community/cache-nix-action/issues/4).
92-
93110
## Approaches
94111
95112
Discussed in more details [here](https://github.com/DeterminateSystems/magic-nix-cache-action/issues/16) and [here](https://github.com/nixbuild/nix-quick-install-action/issues/33).
@@ -109,7 +126,7 @@ Pros:
109126
* Free.
110127
* Uses `GitHub Actions Cache` and works fast.
111128
* Easy to set up.
112-
* Allows to save a store of at most a given size (see [Garbage collection](#garbage-collection-parameters)).
129+
* Allows to save a store of at most a given size (see [Garbage collection parameters](#garbage-collection-parameters)).
113130
* Allows to save output from garbage collection (see [Garbage collection](#garbage-collection)).
114131

115132
Cons: see [Limitations](#limitations)
@@ -167,6 +184,52 @@ Cons:
167184
* Need good bandwidth for receiving and pushing paths over the Internet.
168185
* Can be down.
169186

187+
## Garbage collection
188+
189+
When restoring a Nix store from a cache, the store may contain old unnecessary paths.
190+
These paths should be removed sometimes to limit cache size and ensure the fastest restore/save steps.
191+
192+
### GC approach 1
193+
194+
Produce a cache once, use it multiple times. Don't collect garbage.
195+
196+
Advantages:
197+
198+
* Unnecessary paths are saved to a cache only during a new save.
199+
200+
Disadvantages:
201+
202+
* Unnecessary paths can accumulate between new saves.
203+
* A job at the firs run produces a path `A` and saves a cache.
204+
* The job at the second run restores the cache, produces a path `B`, and saves a cache. The cache has both `A` and `B`.
205+
* etc.
206+
207+
### GC approach 2
208+
209+
Collect garbage before saving a cache.
210+
211+
Advantages:
212+
213+
* Automatically keep cache at a minimal/limited size
214+
215+
Disadvantages:
216+
217+
* No standard way to gc only old paths.
218+
219+
### Save a path from GC
220+
221+
* Use `nix profile install` to save installables from garbage collection.
222+
* Get store paths of `inputs` via `nix flake archive` (see [comment](https://github.com/NixOS/nix/issues/4250#issuecomment-1146878407)).
223+
* Get outputs via `nix flake show --json | jq '.packages."x86_64-linux"|keys[]'| xargs -I {}` on `x86_64-linux` (see this [issue](https://github.com/NixOS/nix/issues/7165)).
224+
* Keep inputs (see this [issue](https://github.com/NixOS/nix/issues/4250) and this [issue](https://github.com/NixOS/nix/issues/6895)).
225+
* Start [direnv](https://github.com/nix-community/nix-direnv) in background.
226+
227+
### Garbage collection approaches
228+
229+
* Use [nix-heuristic-gc](https://github.com/risicle/nix-heuristic-gc) for cache eviction via `atime`
230+
* gc via gc roots [nix-cache-cut](https://github.com/astro/nix-cache-cut)
231+
* gc based on time [cache-gc](https://github.com/lheckemann/cache-gc)
232+
170233
# Cache action
171234

172235
## !!! This documentation was inherited from actions/cache and may be partially irrelevant to cache-nix-action

0 commit comments

Comments
 (0)