Compare commits
6 Commits
main
...
a12c20af33
| Author | SHA1 | Date | |
|---|---|---|---|
|
a12c20af33 | ||
|
|
9cb30f6902 | ||
|
|
cec3719b2c | ||
|
|
17676695b0 | ||
|
|
0e3240ca53 | ||
|
|
39fe5c9237 |
61
.github/workflows/docs.yml
vendored
Normal file
61
.github/workflows/docs.yml
vendored
Normal file
@@ -0,0 +1,61 @@
|
|||||||
|
name: Docs
|
||||||
|
|
||||||
|
on:
|
||||||
|
push:
|
||||||
|
branches:
|
||||||
|
- main
|
||||||
|
workflow_dispatch:
|
||||||
|
|
||||||
|
permissions:
|
||||||
|
contents: read
|
||||||
|
pages: write
|
||||||
|
id-token: write
|
||||||
|
|
||||||
|
concurrency:
|
||||||
|
group: "pages"
|
||||||
|
cancel-in-progress: true
|
||||||
|
|
||||||
|
jobs:
|
||||||
|
docs:
|
||||||
|
runs-on: ubuntu-latest
|
||||||
|
|
||||||
|
steps:
|
||||||
|
- uses: actions/checkout@v6
|
||||||
|
- name: Set up Pages
|
||||||
|
uses: actions/configure-pages@v5
|
||||||
|
- name: Set up Swift
|
||||||
|
uses: swift-actions/setup-swift@v3
|
||||||
|
with:
|
||||||
|
skip-verify-signature: true
|
||||||
|
- name: Generate Docs
|
||||||
|
run: |
|
||||||
|
swift package add-dependency --from 1.4.0 "https://github.com/apple/swift-docc-plugin.git"
|
||||||
|
for target in Inotify TaskCLI; do
|
||||||
|
lower="${target,,}"
|
||||||
|
mkdir -p "./public/$lower"
|
||||||
|
swift package --allow-writing-to-directory "./public/$lower" \
|
||||||
|
generate-documentation --disable-indexing --transform-for-static-hosting \
|
||||||
|
--target "$target" \
|
||||||
|
--hosting-base-path "swift-inotify/$lower" \
|
||||||
|
--output-path "./public/$lower"
|
||||||
|
done
|
||||||
|
- name: Copy Index Page
|
||||||
|
run: |
|
||||||
|
cp ./.github/workflows/index.tpl.html public/index.html
|
||||||
|
sed -i -e 's/{{project.name}}/Swift Inotify/g' public/index.html
|
||||||
|
sed -i -e 's/{{project.tagline}}/🗂️ Monitor filesystem events on Linux using modern Swift concurrency/g' public/index.html
|
||||||
|
sed -i -e 's|{{project.links}}|<li><a href="inotify/documentation/inotify/">Inotify</a>: The actual library.</li><li><a href="taskcli/documentation/taskcli/">TaskCLI</a>: The project build command.</li>|g' public/index.html
|
||||||
|
- name: Upload artifact
|
||||||
|
uses: actions/upload-pages-artifact@v4
|
||||||
|
with:
|
||||||
|
path: ./public
|
||||||
|
|
||||||
|
deploy:
|
||||||
|
environment:
|
||||||
|
name: github-pages
|
||||||
|
url: ${{ steps.deployment.outputs.page_url }}
|
||||||
|
runs-on: ubuntu-latest
|
||||||
|
needs: docs
|
||||||
|
steps:
|
||||||
|
- name: Deploy Docs
|
||||||
|
uses: actions/deploy-pages@v4
|
||||||
72
.github/workflows/index.tpl.html
vendored
Normal file
72
.github/workflows/index.tpl.html
vendored
Normal file
@@ -0,0 +1,72 @@
|
|||||||
|
<!doctype html>
|
||||||
|
<html>
|
||||||
|
<head>
|
||||||
|
<title>Astzweig | Swift Inotify</title>
|
||||||
|
<meta name="description" content="Monitor filesystem events on Linux using modern Swift concurrency.">
|
||||||
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||||
|
<meta charset="utf-8">
|
||||||
|
<style>
|
||||||
|
:root {
|
||||||
|
color-scheme: light dark;
|
||||||
|
}
|
||||||
|
|
||||||
|
html, body {
|
||||||
|
font-family: system-ui, sans-serif;
|
||||||
|
background-color: ligh-dark(#ffffff, #000000);
|
||||||
|
color: ligh-dark(#000000, #ffffff);
|
||||||
|
}
|
||||||
|
|
||||||
|
main {
|
||||||
|
max-width: min(40em, 100vw);
|
||||||
|
min-height: 80vh;
|
||||||
|
margin: 1rem auto;
|
||||||
|
display: flex;
|
||||||
|
flex-direction: column;
|
||||||
|
align-items: center;
|
||||||
|
}
|
||||||
|
|
||||||
|
svg {
|
||||||
|
max-width: 12em;
|
||||||
|
margin: 1rem;
|
||||||
|
}
|
||||||
|
|
||||||
|
footer {
|
||||||
|
max-width: min(60em, 100vw);
|
||||||
|
margin: 1rem auto;
|
||||||
|
font-size: .7rem;
|
||||||
|
font-family: ui-monospace, monospace;
|
||||||
|
|
||||||
|
h1 {
|
||||||
|
font-size: 1rem;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
</style>
|
||||||
|
</head>
|
||||||
|
<body>
|
||||||
|
<main>
|
||||||
|
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 531 118"><g fill-rule="evenodd"><style>g { fill: #000; } @media (prefers-color-scheme: dark) { g { fill: #fff; } }</style><g fill-rule="nonzero"><path d="M147.81 96.877q-6.907 0-13.474-1.579t-10.55-4.009l5.703-12.975q3.777 2.3 8.88 3.662t10.034 1.362q4.752 0 6.621-1.01t1.87-2.77q0-1.541-1.732-2.308t-4.578-1.176a920 920 0 0 0-6.258-.874q-3.411-.465-6.859-1.35t-6.293-2.623-4.577-4.71-1.731-7.64q0-5.14 3.057-9.184t8.95-6.424 14.379-2.38q5.783 0 11.612 1.147 5.83 1.147 9.881 3.416l-5.703 12.976q-4.046-2.3-8.033-3.15-3.99-.85-7.58-.85-4.799 0-6.782 1.11-1.984 1.11-1.984 2.7 0 1.602 1.73 2.42 1.732.819 4.578 1.258 2.846.438 6.259.904 3.413.465 6.824 1.385 3.411.918 6.258 2.641t4.578 4.68 1.73 7.594q0 4.932-3.037 8.98t-9.012 6.413-14.76 2.364m59.104 0q-10.4 0-16.173-5.125-5.772-5.124-5.772-15.555V29.652h19v46.314q0 2.966 1.567 4.614t4.126 1.648q3.334 0 5.752-1.748l4.748 13.28q-2.476 1.591-5.97 2.354-3.495.763-7.278.763m-29.88-38.87V43.835h39.252v14.174zM224.539 96V84.831l30.465-35.037 3.203 6.144h-32.931V41.766h48.283v11.168l-30.466 35.038-3.265-6.144h34.739V96zM294.751 96l-19.217-54.234h17.988l15.268 45.362h-8.625l15.969-45.362h16.128l15.363 45.362h-8.417l15.768-45.362h16.697L352.425 96h-18.432l-12.957-37.528h5.543L313.184 96zM404.332 96.877q-9.597 0-16.768-3.639-7.17-3.638-11.115-9.995t-3.946-14.395q0-8.175 3.88-14.498t10.65-9.891q6.77-3.57 15.261-3.57 8.007 0 14.593 3.278t10.504 9.547q3.917 6.27 3.917 15.258 0 1.046-.084 2.34a87 87 0 0 1-.185 2.37H388.1v-9.968h32.863l-7.228 2.806q.031-3.697-1.414-6.397t-3.957-4.213-5.932-1.513-5.983 1.513-3.957 4.23-1.395 6.474v2.903q0 3.966 1.68 6.885t4.776 4.448 7.355 1.53q4.049 0 6.902-1.156t5.584-3.496l10 10.41q-3.876 4.268-9.587 6.503-5.71 2.236-13.475 2.236M439.997 96V41.8h19V96zm9.5-60.2q-5.199 0-8.4-2.9-3.2-2.9-3.2-7.2t3.2-7.2q3.201-2.9 8.4-2.9 5.2 0 8.4 2.75t3.2 7.05q0 4.5-3.15 7.45t-8.45 2.95m48.242 80.477q-7.852 0-14.92-1.779-7.07-1.778-11.985-5.301l6.888-13.26q3.324 2.655 8.413 4.215t9.893 1.559q7.651 0 11.04-3.338t3.388-9.77v-6.369l1-15.23-.087-15.263v-9.975h18.087v44.328q0 15.403-8.304 22.793t-23.413 7.39m-3.376-23.06q-7.18 0-13.226-3.25t-9.7-9.119-3.654-13.845q0-7.975 3.654-13.844 3.654-5.87 9.7-9.07t13.226-3.2q6.976 0 11.836 2.77t7.433 8.572 2.573 14.772q0 8.97-2.573 14.773-2.573 5.804-7.433 8.622-4.86 2.82-11.836 2.82m4.51-15.117q3.444 0 6.103-1.395t4.17-3.907q1.51-2.512 1.51-5.795 0-3.351-1.51-5.829-1.512-2.477-4.17-3.822-2.66-1.344-6.102-1.344-3.346 0-6.054 1.344-2.71 1.345-4.253 3.822-1.545 2.478-1.545 5.83 0 3.282 1.545 5.794 1.544 2.513 4.253 3.907 2.707 1.395 6.054 1.395"/></g><path d="M102.666 13.772h-.014v20.424q2.888.297 5.777.823l.886.167a3.66 3.66 0 0 1 2.96 3.592v53.253a3.66 3.66 0 0 1-2.96 3.595A74 74 0 0 1 95.137 97a75 75 0 0 1-14.267-1.38 3.66 3.66 0 0 1-2.963-3.59V73.025L48.733 58.685l-16.18 12.641a3.66 3.66 0 0 1-4.743-.198 89 89 0 0 1-6.423-6.61V76.41a.84.84 0 0 1-.839.84H9.625v-6.275h5.462V62.61H6.684v5.437H.383V57.175c0-.463.375-.839.838-.839h13.816a90 90 0 0 1-4.592-7.441 3.66 3.66 0 0 1 .95-4.653L55.14 10.064a3.66 3.66 0 0 1 4.743.206 92 92 0 0 1 4.114 4.076L80.529 2.338l-.011-.015c7.448-5.467 22.318-.83 22.148 11.45m-20.448 8.263-7.713 5.812a90 90 0 0 1 2.747 4.647 3.66 3.66 0 0 1-.951 4.654L63.132 47.436l14.773 7.362V38.785a3.66 3.66 0 0 1 2.969-3.596 78 78 0 0 1 4.593-.744v-9.294h-.008v-.387c-.012-1.379-.215-4.408-3.085-2.818zm.946-9.41-12.606 9.497a88 88 0 0 1 2.437 3.42l7.589-5.718-.005-.008.067-.065c1.184-1.096 7.144-4.065 7.558 4.454l.013.324q.01.303.01.622h-.01v8.984q2.065-.194 4.124-.273V19.77h-.036c-.113-7.551-3.735-10.214-8.96-7.25zm-1.004-8.07-16.292 11.83a88 88 0 0 1 3.007 3.563l12.505-9.423-.022-.028q.314-.25.662-.48l.248-.16c4.557-2.813 12.944-2.85 12.838 9.914h-.016l.001 14.038h.045q2.384 0 4.767.155V13.772h-.013c.142-7.384-9.941-14.798-17.73-9.216"/></g></svg>
|
||||||
|
<hgroup>
|
||||||
|
<h1>{{project.name}}</h1>
|
||||||
|
<p>{{project.tagline}}</p>
|
||||||
|
</hgroup>
|
||||||
|
<h2>Documentations</h2>
|
||||||
|
<ul>
|
||||||
|
{{project.links}}
|
||||||
|
</ul>
|
||||||
|
</main>
|
||||||
|
<footer vocab="https://schema.org/" typeof="Organization">
|
||||||
|
© <span property="legalName">Astzweig GmbH & Co. KG</span>,
|
||||||
|
based in
|
||||||
|
<span property="location">Freiburg i. Br.</span>,
|
||||||
|
entered in the commercial register of the Freiburg Local Court under number HRA 703853 and VAT ID number:
|
||||||
|
<span property="vatID">DE297037836</span>.
|
||||||
|
The general partner is
|
||||||
|
<span property="parentOrganization" typeof="Organization">
|
||||||
|
<span property="legalName">Astzweig Verwaltungsgesellschaft mbH</span>
|
||||||
|
based in <span property="location">Freiburg i.Br.</span>,
|
||||||
|
entered in the commercial register of the same court under number HRB 718037 and with a capital of €25,000.00, represented by the managing director
|
||||||
|
<span property="employee" type="Person"><span property="givenName">Thomas R.</span> <span property="familyName">Bernstein</span>.</span>
|
||||||
|
</span>
|
||||||
|
</footer>
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
1
.gitignore
vendored
1
.gitignore
vendored
@@ -1 +1,2 @@
|
|||||||
.build
|
.build
|
||||||
|
public
|
||||||
|
|||||||
5
.spi.yml
Normal file
5
.spi.yml
Normal file
@@ -0,0 +1,5 @@
|
|||||||
|
version: 1
|
||||||
|
builder:
|
||||||
|
configs:
|
||||||
|
- documentation_targets: [Inotify, TaskCLI]
|
||||||
|
platform: Linux
|
||||||
287
LICENSE
Normal file
287
LICENSE
Normal file
@@ -0,0 +1,287 @@
|
|||||||
|
EUROPEAN UNION PUBLIC LICENCE v. 1.2
|
||||||
|
EUPL © the European Union 2007, 2016
|
||||||
|
|
||||||
|
This European Union Public Licence (the ‘EUPL’) applies to the Work (as defined
|
||||||
|
below) which is provided under the terms of this Licence. Any use of the Work,
|
||||||
|
other than as authorised under this Licence is prohibited (to the extent such
|
||||||
|
use is covered by a right of the copyright holder of the Work).
|
||||||
|
|
||||||
|
The Work is provided under the terms of this Licence when the Licensor (as
|
||||||
|
defined below) has placed the following notice immediately following the
|
||||||
|
copyright notice for the Work:
|
||||||
|
|
||||||
|
Licensed under the EUPL
|
||||||
|
|
||||||
|
or has expressed by any other means his willingness to license under the EUPL.
|
||||||
|
|
||||||
|
1. Definitions
|
||||||
|
|
||||||
|
In this Licence, the following terms have the following meaning:
|
||||||
|
|
||||||
|
- ‘The Licence’: this Licence.
|
||||||
|
|
||||||
|
- ‘The Original Work’: the work or software distributed or communicated by the
|
||||||
|
Licensor under this Licence, available as Source Code and also as Executable
|
||||||
|
Code as the case may be.
|
||||||
|
|
||||||
|
- ‘Derivative Works’: the works or software that could be created by the
|
||||||
|
Licensee, based upon the Original Work or modifications thereof. This Licence
|
||||||
|
does not define the extent of modification or dependence on the Original Work
|
||||||
|
required in order to classify a work as a Derivative Work; this extent is
|
||||||
|
determined by copyright law applicable in the country mentioned in Article 15.
|
||||||
|
|
||||||
|
- ‘The Work’: the Original Work or its Derivative Works.
|
||||||
|
|
||||||
|
- ‘The Source Code’: the human-readable form of the Work which is the most
|
||||||
|
convenient for people to study and modify.
|
||||||
|
|
||||||
|
- ‘The Executable Code’: any code which has generally been compiled and which is
|
||||||
|
meant to be interpreted by a computer as a program.
|
||||||
|
|
||||||
|
- ‘The Licensor’: the natural or legal person that distributes or communicates
|
||||||
|
the Work under the Licence.
|
||||||
|
|
||||||
|
- ‘Contributor(s)’: any natural or legal person who modifies the Work under the
|
||||||
|
Licence, or otherwise contributes to the creation of a Derivative Work.
|
||||||
|
|
||||||
|
- ‘The Licensee’ or ‘You’: any natural or legal person who makes any usage of
|
||||||
|
the Work under the terms of the Licence.
|
||||||
|
|
||||||
|
- ‘Distribution’ or ‘Communication’: any act of selling, giving, lending,
|
||||||
|
renting, distributing, communicating, transmitting, or otherwise making
|
||||||
|
available, online or offline, copies of the Work or providing access to its
|
||||||
|
essential functionalities at the disposal of any other natural or legal
|
||||||
|
person.
|
||||||
|
|
||||||
|
2. Scope of the rights granted by the Licence
|
||||||
|
|
||||||
|
The Licensor hereby grants You a worldwide, royalty-free, non-exclusive,
|
||||||
|
sublicensable licence to do the following, for the duration of copyright vested
|
||||||
|
in the Original Work:
|
||||||
|
|
||||||
|
- use the Work in any circumstance and for all usage,
|
||||||
|
- reproduce the Work,
|
||||||
|
- modify the Work, and make Derivative Works based upon the Work,
|
||||||
|
- communicate to the public, including the right to make available or display
|
||||||
|
the Work or copies thereof to the public and perform publicly, as the case may
|
||||||
|
be, the Work,
|
||||||
|
- distribute the Work or copies thereof,
|
||||||
|
- lend and rent the Work or copies thereof,
|
||||||
|
- sublicense rights in the Work or copies thereof.
|
||||||
|
|
||||||
|
Those rights can be exercised on any media, supports and formats, whether now
|
||||||
|
known or later invented, as far as the applicable law permits so.
|
||||||
|
|
||||||
|
In the countries where moral rights apply, the Licensor waives his right to
|
||||||
|
exercise his moral right to the extent allowed by law in order to make effective
|
||||||
|
the licence of the economic rights here above listed.
|
||||||
|
|
||||||
|
The Licensor grants to the Licensee royalty-free, non-exclusive usage rights to
|
||||||
|
any patents held by the Licensor, to the extent necessary to make use of the
|
||||||
|
rights granted on the Work under this Licence.
|
||||||
|
|
||||||
|
3. Communication of the Source Code
|
||||||
|
|
||||||
|
The Licensor may provide the Work either in its Source Code form, or as
|
||||||
|
Executable Code. If the Work is provided as Executable Code, the Licensor
|
||||||
|
provides in addition a machine-readable copy of the Source Code of the Work
|
||||||
|
along with each copy of the Work that the Licensor distributes or indicates, in
|
||||||
|
a notice following the copyright notice attached to the Work, a repository where
|
||||||
|
the Source Code is easily and freely accessible for as long as the Licensor
|
||||||
|
continues to distribute or communicate the Work.
|
||||||
|
|
||||||
|
4. Limitations on copyright
|
||||||
|
|
||||||
|
Nothing in this Licence is intended to deprive the Licensee of the benefits from
|
||||||
|
any exception or limitation to the exclusive rights of the rights owners in the
|
||||||
|
Work, of the exhaustion of those rights or of other applicable limitations
|
||||||
|
thereto.
|
||||||
|
|
||||||
|
5. Obligations of the Licensee
|
||||||
|
|
||||||
|
The grant of the rights mentioned above is subject to some restrictions and
|
||||||
|
obligations imposed on the Licensee. Those obligations are the following:
|
||||||
|
|
||||||
|
Attribution right: The Licensee shall keep intact all copyright, patent or
|
||||||
|
trademarks notices and all notices that refer to the Licence and to the
|
||||||
|
disclaimer of warranties. The Licensee must include a copy of such notices and a
|
||||||
|
copy of the Licence with every copy of the Work he/she distributes or
|
||||||
|
communicates. The Licensee must cause any Derivative Work to carry prominent
|
||||||
|
notices stating that the Work has been modified and the date of modification.
|
||||||
|
|
||||||
|
Copyleft clause: If the Licensee distributes or communicates copies of the
|
||||||
|
Original Works or Derivative Works, this Distribution or Communication will be
|
||||||
|
done under the terms of this Licence or of a later version of this Licence
|
||||||
|
unless the Original Work is expressly distributed only under this version of the
|
||||||
|
Licence — for example by communicating ‘EUPL v. 1.2 only’. The Licensee
|
||||||
|
(becoming Licensor) cannot offer or impose any additional terms or conditions on
|
||||||
|
the Work or Derivative Work that alter or restrict the terms of the Licence.
|
||||||
|
|
||||||
|
Compatibility clause: If the Licensee Distributes or Communicates Derivative
|
||||||
|
Works or copies thereof based upon both the Work and another work licensed under
|
||||||
|
a Compatible Licence, this Distribution or Communication can be done under the
|
||||||
|
terms of this Compatible Licence. For the sake of this clause, ‘Compatible
|
||||||
|
Licence’ refers to the licences listed in the appendix attached to this Licence.
|
||||||
|
Should the Licensee's obligations under the Compatible Licence conflict with
|
||||||
|
his/her obligations under this Licence, the obligations of the Compatible
|
||||||
|
Licence shall prevail.
|
||||||
|
|
||||||
|
Provision of Source Code: When distributing or communicating copies of the Work,
|
||||||
|
the Licensee will provide a machine-readable copy of the Source Code or indicate
|
||||||
|
a repository where this Source will be easily and freely available for as long
|
||||||
|
as the Licensee continues to distribute or communicate the Work.
|
||||||
|
|
||||||
|
Legal Protection: This Licence does not grant permission to use the trade names,
|
||||||
|
trademarks, service marks, or names of the Licensor, except as required for
|
||||||
|
reasonable and customary use in describing the origin of the Work and
|
||||||
|
reproducing the content of the copyright notice.
|
||||||
|
|
||||||
|
6. Chain of Authorship
|
||||||
|
|
||||||
|
The original Licensor warrants that the copyright in the Original Work granted
|
||||||
|
hereunder is owned by him/her or licensed to him/her and that he/she has the
|
||||||
|
power and authority to grant the Licence.
|
||||||
|
|
||||||
|
Each Contributor warrants that the copyright in the modifications he/she brings
|
||||||
|
to the Work are owned by him/her or licensed to him/her and that he/she has the
|
||||||
|
power and authority to grant the Licence.
|
||||||
|
|
||||||
|
Each time You accept the Licence, the original Licensor and subsequent
|
||||||
|
Contributors grant You a licence to their contributions to the Work, under the
|
||||||
|
terms of this Licence.
|
||||||
|
|
||||||
|
7. Disclaimer of Warranty
|
||||||
|
|
||||||
|
The Work is a work in progress, which is continuously improved by numerous
|
||||||
|
Contributors. It is not a finished work and may therefore contain defects or
|
||||||
|
‘bugs’ inherent to this type of development.
|
||||||
|
|
||||||
|
For the above reason, the Work is provided under the Licence on an ‘as is’ basis
|
||||||
|
and without warranties of any kind concerning the Work, including without
|
||||||
|
limitation merchantability, fitness for a particular purpose, absence of defects
|
||||||
|
or errors, accuracy, non-infringement of intellectual property rights other than
|
||||||
|
copyright as stated in Article 6 of this Licence.
|
||||||
|
|
||||||
|
This disclaimer of warranty is an essential part of the Licence and a condition
|
||||||
|
for the grant of any rights to the Work.
|
||||||
|
|
||||||
|
8. Disclaimer of Liability
|
||||||
|
|
||||||
|
Except in the cases of wilful misconduct or damages directly caused to natural
|
||||||
|
persons, the Licensor will in no event be liable for any direct or indirect,
|
||||||
|
material or moral, damages of any kind, arising out of the Licence or of the use
|
||||||
|
of the Work, including without limitation, damages for loss of goodwill, work
|
||||||
|
stoppage, computer failure or malfunction, loss of data or any commercial
|
||||||
|
damage, even if the Licensor has been advised of the possibility of such damage.
|
||||||
|
However, the Licensor will be liable under statutory product liability laws as
|
||||||
|
far such laws apply to the Work.
|
||||||
|
|
||||||
|
9. Additional agreements
|
||||||
|
|
||||||
|
While distributing the Work, You may choose to conclude an additional agreement,
|
||||||
|
defining obligations or services consistent with this Licence. However, if
|
||||||
|
accepting obligations, You may act only on your own behalf and on your sole
|
||||||
|
responsibility, not on behalf of the original Licensor or any other Contributor,
|
||||||
|
and only if You agree to indemnify, defend, and hold each Contributor harmless
|
||||||
|
for any liability incurred by, or claims asserted against such Contributor by
|
||||||
|
the fact You have accepted any warranty or additional liability.
|
||||||
|
|
||||||
|
10. Acceptance of the Licence
|
||||||
|
|
||||||
|
The provisions of this Licence can be accepted by clicking on an icon ‘I agree’
|
||||||
|
placed under the bottom of a window displaying the text of this Licence or by
|
||||||
|
affirming consent in any other similar way, in accordance with the rules of
|
||||||
|
applicable law. Clicking on that icon indicates your clear and irrevocable
|
||||||
|
acceptance of this Licence and all of its terms and conditions.
|
||||||
|
|
||||||
|
Similarly, you irrevocably accept this Licence and all of its terms and
|
||||||
|
conditions by exercising any rights granted to You by Article 2 of this Licence,
|
||||||
|
such as the use of the Work, the creation by You of a Derivative Work or the
|
||||||
|
Distribution or Communication by You of the Work or copies thereof.
|
||||||
|
|
||||||
|
11. Information to the public
|
||||||
|
|
||||||
|
In case of any Distribution or Communication of the Work by means of electronic
|
||||||
|
communication by You (for example, by offering to download the Work from a
|
||||||
|
remote location) the distribution channel or media (for example, a website) must
|
||||||
|
at least provide to the public the information requested by the applicable law
|
||||||
|
regarding the Licensor, the Licence and the way it may be accessible, concluded,
|
||||||
|
stored and reproduced by the Licensee.
|
||||||
|
|
||||||
|
12. Termination of the Licence
|
||||||
|
|
||||||
|
The Licence and the rights granted hereunder will terminate automatically upon
|
||||||
|
any breach by the Licensee of the terms of the Licence.
|
||||||
|
|
||||||
|
Such a termination will not terminate the licences of any person who has
|
||||||
|
received the Work from the Licensee under the Licence, provided such persons
|
||||||
|
remain in full compliance with the Licence.
|
||||||
|
|
||||||
|
13. Miscellaneous
|
||||||
|
|
||||||
|
Without prejudice of Article 9 above, the Licence represents the complete
|
||||||
|
agreement between the Parties as to the Work.
|
||||||
|
|
||||||
|
If any provision of the Licence is invalid or unenforceable under applicable
|
||||||
|
law, this will not affect the validity or enforceability of the Licence as a
|
||||||
|
whole. Such provision will be construed or reformed so as necessary to make it
|
||||||
|
valid and enforceable.
|
||||||
|
|
||||||
|
The European Commission may publish other linguistic versions or new versions of
|
||||||
|
this Licence or updated versions of the Appendix, so far this is required and
|
||||||
|
reasonable, without reducing the scope of the rights granted by the Licence. New
|
||||||
|
versions of the Licence will be published with a unique version number.
|
||||||
|
|
||||||
|
All linguistic versions of this Licence, approved by the European Commission,
|
||||||
|
have identical value. Parties can take advantage of the linguistic version of
|
||||||
|
their choice.
|
||||||
|
|
||||||
|
14. Jurisdiction
|
||||||
|
|
||||||
|
Without prejudice to specific agreement between parties,
|
||||||
|
|
||||||
|
- any litigation resulting from the interpretation of this License, arising
|
||||||
|
between the European Union institutions, bodies, offices or agencies, as a
|
||||||
|
Licensor, and any Licensee, will be subject to the jurisdiction of the Court
|
||||||
|
of Justice of the European Union, as laid down in article 272 of the Treaty on
|
||||||
|
the Functioning of the European Union,
|
||||||
|
|
||||||
|
- any litigation arising between other parties and resulting from the
|
||||||
|
interpretation of this License, will be subject to the exclusive jurisdiction
|
||||||
|
of the competent court where the Licensor resides or conducts its primary
|
||||||
|
business.
|
||||||
|
|
||||||
|
15. Applicable Law
|
||||||
|
|
||||||
|
Without prejudice to specific agreement between parties,
|
||||||
|
|
||||||
|
- this Licence shall be governed by the law of the European Union Member State
|
||||||
|
where the Licensor has his seat, resides or has his registered office,
|
||||||
|
|
||||||
|
- this licence shall be governed by Belgian law if the Licensor has no seat,
|
||||||
|
residence or registered office inside a European Union Member State.
|
||||||
|
|
||||||
|
Appendix
|
||||||
|
|
||||||
|
‘Compatible Licences’ according to Article 5 EUPL are:
|
||||||
|
|
||||||
|
- GNU General Public License (GPL) v. 2, v. 3
|
||||||
|
- GNU Affero General Public License (AGPL) v. 3
|
||||||
|
- Open Software License (OSL) v. 2.1, v. 3.0
|
||||||
|
- Eclipse Public License (EPL) v. 1.0
|
||||||
|
- CeCILL v. 2.0, v. 2.1
|
||||||
|
- Mozilla Public Licence (MPL) v. 2
|
||||||
|
- GNU Lesser General Public Licence (LGPL) v. 2.1, v. 3
|
||||||
|
- Creative Commons Attribution-ShareAlike v. 3.0 Unported (CC BY-SA 3.0) for
|
||||||
|
works other than software
|
||||||
|
- European Union Public Licence (EUPL) v. 1.1, v. 1.2
|
||||||
|
- Québec Free and Open-Source Licence — Reciprocity (LiLiQ-R) or Strong
|
||||||
|
Reciprocity (LiLiQ-R+).
|
||||||
|
|
||||||
|
The European Commission may update this Appendix to later versions of the above
|
||||||
|
licences without producing a new version of the EUPL, as long as they provide
|
||||||
|
the rights granted in Article 2 of this Licence and protect the covered Source
|
||||||
|
Code from exclusive appropriation.
|
||||||
|
|
||||||
|
All other changes or additions to this Appendix require the production of a new
|
||||||
|
EUPL version.
|
||||||
@@ -47,6 +47,7 @@ let package = Package(
|
|||||||
.product(name: "ArgumentParser", package: "swift-argument-parser"),
|
.product(name: "ArgumentParser", package: "swift-argument-parser"),
|
||||||
.product(name: "AsyncAlgorithms", package: "swift-async-algorithms"),
|
.product(name: "AsyncAlgorithms", package: "swift-async-algorithms"),
|
||||||
.product(name: "Logging", package: "swift-log"),
|
.product(name: "Logging", package: "swift-log"),
|
||||||
|
.product(name: "_NIOFileSystem", package: "swift-nio"),
|
||||||
.product(name: "Subprocess", package: "swift-subprocess"),
|
.product(name: "Subprocess", package: "swift-subprocess"),
|
||||||
.product(name: "Noora", package: "Noora")
|
.product(name: "Noora", package: "Noora")
|
||||||
]
|
]
|
||||||
|
|||||||
145
README.md
Normal file
145
README.md
Normal file
@@ -0,0 +1,145 @@
|
|||||||
|
# Inotify
|
||||||
|
|
||||||
|
A Swift wrapper around the Linux [inotify](https://man7.org/linux/man-pages/man7/inotify.7.html) API, built on modern Swift concurrency. It lets you watch individual files or directories for filesystem events, recursively monitor entire subtrees, and optionally have newly created subdirectories watched automatically.
|
||||||
|
|
||||||
|
Events are delivered as an `AsyncSequence`, so you can consume them with a simple `for await` loop.
|
||||||
|
|
||||||
|
## Adding Inotify to Your Project
|
||||||
|
|
||||||
|
Add the package dependency in your `Package.swift`:
|
||||||
|
|
||||||
|
```swift
|
||||||
|
dependencies: [
|
||||||
|
.package(url: "https://github.com/astzweig/swift-inotify.git", from: "1.0.0")
|
||||||
|
]
|
||||||
|
```
|
||||||
|
|
||||||
|
Then add `Inotify` to your target's dependencies:
|
||||||
|
|
||||||
|
```swift
|
||||||
|
.target(
|
||||||
|
...
|
||||||
|
dependencies: [
|
||||||
|
.product(name: "Inotify", package: "swift-inotify")
|
||||||
|
]
|
||||||
|
...
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Quick Start
|
||||||
|
|
||||||
|
```swift
|
||||||
|
import Inotify
|
||||||
|
|
||||||
|
let inotify = try Inotify()
|
||||||
|
|
||||||
|
// Watch a single file for modifications
|
||||||
|
try inotify.addWatch(path: "/tmp/some-existing-file.txt", mask: [.modify])
|
||||||
|
|
||||||
|
// Watch a single directory for file creations and modifications
|
||||||
|
try inotify.addWatch(path: "/tmp/watched", mask: [.create, .modify])
|
||||||
|
|
||||||
|
// Consume events as they arrive
|
||||||
|
for await event in await inotify.events {
|
||||||
|
print("Event at \(event.path): \(event.mask)")
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Watching Subtrees
|
||||||
|
|
||||||
|
Inotify operates on individual watch descriptors, so monitoring a directory does not automatically cover its children. This library provides two convenience methods that handle the recursion for you.
|
||||||
|
|
||||||
|
### Recursive Watch
|
||||||
|
|
||||||
|
`addRecursiveWatch` walks the directory tree at setup time and installs a watch on every existing subdirectory:
|
||||||
|
|
||||||
|
```swift
|
||||||
|
try await inotify.addRecursiveWatch(
|
||||||
|
forDirectory: "/home/user/project",
|
||||||
|
mask: [.create, .modify, .delete]
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
Subdirectories created after the call are **not** watched.
|
||||||
|
|
||||||
|
### Automatic Subtree Watching
|
||||||
|
|
||||||
|
`addWatchWithAutomaticSubtreeWatching` does everything `addRecursiveWatch` does, and additionally listens for `CREATE` events with the `isDir` flag. Whenever a new subdirectory appears, a watch is installed on it automatically:
|
||||||
|
|
||||||
|
```swift
|
||||||
|
try await inotify.addWatchWithAutomaticSubtreeWatching(
|
||||||
|
forDirectory: "/home/user/project",
|
||||||
|
mask: [.create, .modify, .delete]
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
This is the most convenient option when you need full coverage of a growing directory tree.
|
||||||
|
|
||||||
|
## Event Masks
|
||||||
|
|
||||||
|
`InotifyEventMask` is an `OptionSet` that mirrors the native inotify flags. You can combine them freely.
|
||||||
|
|
||||||
|
| Mask | Description |
|
||||||
|
|------|-------------|
|
||||||
|
| `.access` | File was read |
|
||||||
|
| `.attrib` | Metadata changed (permissions, timestamps, ...) |
|
||||||
|
| `.closeWrite` | File opened for writing was closed |
|
||||||
|
| `.closeNoWrite` | File **not** opened for writing was closed |
|
||||||
|
| `.create` | File or directory created in watched directory |
|
||||||
|
| `.delete` | File or directory deleted in watched directory |
|
||||||
|
| `.deleteSelf` | Watched item itself was deleted |
|
||||||
|
| `.modify` | File was written to |
|
||||||
|
| `.moveSelf` | Watched item itself was moved |
|
||||||
|
| `.movedFrom` | File moved **out** of watched directory |
|
||||||
|
| `.movedTo` | File moved **into** watched directory |
|
||||||
|
| `.open` | File was opened |
|
||||||
|
|
||||||
|
Convenience combinations: `.move` (`.movedFrom` + `.movedTo`), `.close` (`.closeWrite` + `.closeNoWrite`), `.allEvents`.
|
||||||
|
|
||||||
|
Watch flags: `.dontFollow`, `.onlyDir`, `.oneShot`.
|
||||||
|
|
||||||
|
Kernel-only flags returned in events: `.isDir`, `.ignored`, `.queueOverflow`, `.unmount`.
|
||||||
|
|
||||||
|
## Removing a Watch
|
||||||
|
|
||||||
|
Every `addWatch` variant returns one or more watch descriptors that you can use to remove the watch later:
|
||||||
|
|
||||||
|
```swift
|
||||||
|
let wd = try inotify.addWatch(path: "/tmp/watched", mask: .create)
|
||||||
|
|
||||||
|
// ... later
|
||||||
|
try inotify.removeWatch(wd)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Build Tool
|
||||||
|
|
||||||
|
The package ships with a `task` executable (the `TaskCLI` target) that serves as the project's build tool. It spins up a Docker container running `swift:latest` on Linux and executes the full test suite inside it, so you can validate everything on the correct platform even when developing on macOS.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
swift run task test
|
||||||
|
```
|
||||||
|
|
||||||
|
Use `-v`, `-vv`, or `-vvv` to increase log verbosity. The command runs two passes: first all tests except `InotifyLimitTests`, then only `InotifyLimitTests` (which manipulate system-level inotify limits and need to run in isolation).
|
||||||
|
|
||||||
|
Docker must be installed and running on your machine.
|
||||||
|
|
||||||
|
### Documentation
|
||||||
|
|
||||||
|
Full API documentation is available as DocC catalogs bundled with the package. Generate them locally with:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
swift run task generate-docs
|
||||||
|
```
|
||||||
|
|
||||||
|
Then open the files in the newly created `public` folder.
|
||||||
|
Or preview in Xcode by selecting **Product > Build Documentation**.
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
|
||||||
|
- Swift 6.0+
|
||||||
|
- Linux (inotify is a Linux-only API)
|
||||||
|
- Docker (for running the test suite via `swift run task test`)
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
See [LICENSE](LICENSE) for details.
|
||||||
@@ -3,42 +3,35 @@ import _NIOFileSystem
|
|||||||
public struct DirectoryResolver {
|
public struct DirectoryResolver {
|
||||||
static let fileManager = FileSystem.shared
|
static let fileManager = FileSystem.shared
|
||||||
|
|
||||||
public static func resolve(_ paths: String...) async throws -> [FilePath] {
|
public static func resolve(_ paths: String..., excluding itemNames: Set<String> = []) async throws -> [FilePath] {
|
||||||
try await Self.resolve(paths)
|
try await Self.resolve(paths, excluding: itemNames)
|
||||||
}
|
}
|
||||||
|
|
||||||
static func resolve(_ paths: [String]) async throws -> [FilePath] {
|
static func resolve(_ paths: [String], excluding itemNames: Set<String> = []) async throws -> [FilePath] {
|
||||||
var resolved: [FilePath] = []
|
var resolved: [FilePath] = []
|
||||||
|
|
||||||
for path in paths {
|
for path in paths {
|
||||||
let itemPath = FilePath(path)
|
let path = FilePath(path)
|
||||||
try await Self.ensure(itemPath, is: .directory)
|
resolved.append(path)
|
||||||
|
try await withSubdirectories(at: path, recursive: true) { subdirectoryPath in
|
||||||
let allDirectoriesIncludingSelf = try await getAllSubdirectoriesAndSelf(at: itemPath)
|
guard let basename = subdirectoryPath.lastComponent?.description else { return }
|
||||||
resolved.append(contentsOf: allDirectoriesIncludingSelf)
|
guard !itemNames.contains(basename) else { return }
|
||||||
|
resolved.append(subdirectoryPath)
|
||||||
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
return resolved
|
return resolved
|
||||||
}
|
}
|
||||||
|
|
||||||
private static func ensure(_ path: FilePath, is fileType: FileType) async throws {
|
private static func withSubdirectories(at path: FilePath, recursive: Bool = false, body: (FilePath) async throws -> Void) async throws {
|
||||||
guard let fileInfo = try await fileManager.info(forFileAt: path) else {
|
|
||||||
throw DirectoryResolverError.pathNotFound(path)
|
|
||||||
}
|
|
||||||
|
|
||||||
guard fileInfo.type == fileType else {
|
|
||||||
throw DirectoryResolverError.pathIsNoDirectory(path)
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
||||||
private static func getAllSubdirectoriesAndSelf(at path: FilePath) async throws -> [FilePath] {
|
|
||||||
var result: [FilePath] = []
|
|
||||||
let directoryHandle = try await fileManager.openDirectory(atPath: path)
|
let directoryHandle = try await fileManager.openDirectory(atPath: path)
|
||||||
for try await childContent in directoryHandle.listContents(recursive: true) {
|
for try await childContent in directoryHandle.listContents() {
|
||||||
guard childContent.type == .directory else { continue }
|
guard childContent.type == .directory else { continue }
|
||||||
result.append(childContent.path)
|
try await body(childContent.path)
|
||||||
|
if recursive {
|
||||||
|
try await withSubdirectories(at: childContent.path, recursive: recursive, body: body)
|
||||||
|
}
|
||||||
}
|
}
|
||||||
try await directoryHandle.close()
|
try await directoryHandle.close()
|
||||||
return result
|
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|||||||
40
Sources/Inotify/Inotify.docc/Inotify.md
Normal file
40
Sources/Inotify/Inotify.docc/Inotify.md
Normal file
@@ -0,0 +1,40 @@
|
|||||||
|
# ``Inotify``
|
||||||
|
|
||||||
|
Monitor filesystem events on Linux using modern Swift concurrency.
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
The Inotify library wraps the Linux [inotify](https://man7.org/linux/man-pages/man7/inotify.7.html) API in a Swift-native interface built around actors and async sequences. You create an ``Inotify/Inotify`` actor, add watches for the paths you care about, and iterate over the ``Inotify/Inotify/events`` property to receive ``InotifyEvent`` values as they occur.
|
||||||
|
|
||||||
|
```swift
|
||||||
|
let inotify = try Inotify()
|
||||||
|
try inotify.addWatch(path: "/tmp/inbox", mask: [.create, .modify])
|
||||||
|
|
||||||
|
for await event in await inotify.events {
|
||||||
|
print("\(event.mask) at \(event.path)")
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Beyond single-directory watches, the library provides two higher-level methods for monitoring entire directory trees:
|
||||||
|
|
||||||
|
- ``Inotify/Inotify/addRecursiveWatch(forDirectory:mask:)`` installs watches on every existing subdirectory at setup time.
|
||||||
|
- ``Inotify/Inotify/addWatchWithAutomaticSubtreeWatching(forDirectory:mask:)`` does the same **and** automatically watches subdirectories that are created after setup.
|
||||||
|
|
||||||
|
All public types conform to `Sendable`, so they can be safely passed across concurrency boundaries.
|
||||||
|
|
||||||
|
## Topics
|
||||||
|
|
||||||
|
### Essentials
|
||||||
|
|
||||||
|
- ``Inotify/Inotify``
|
||||||
|
- ``InotifyEvent``
|
||||||
|
- ``InotifyEventMask``
|
||||||
|
|
||||||
|
### Errors
|
||||||
|
|
||||||
|
- ``InotifyError``
|
||||||
|
- ``DirectoryResolverError``
|
||||||
|
|
||||||
|
### Low-Level Types
|
||||||
|
|
||||||
|
- ``RawInotifyEvent``
|
||||||
42
Sources/Inotify/Inotify.docc/WatchingDirectoryTrees.md
Normal file
42
Sources/Inotify/Inotify.docc/WatchingDirectoryTrees.md
Normal file
@@ -0,0 +1,42 @@
|
|||||||
|
# Watching Directory Trees
|
||||||
|
|
||||||
|
Monitor an entire directory hierarchy for filesystem events.
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
The Linux inotify API watches individual directories — it does not descend into subdirectories automatically. The ``Inotify/Inotify`` actor offers two convenience methods that handle the recursion for you.
|
||||||
|
|
||||||
|
### Recursive Watch
|
||||||
|
|
||||||
|
Call ``Inotify/Inotify/addRecursiveWatch(forDirectory:mask:)`` to walk the directory tree once and install a watch on every subdirectory that exists at the time of the call:
|
||||||
|
|
||||||
|
```swift
|
||||||
|
let inotify = try Inotify()
|
||||||
|
let descriptors = try await inotify.addRecursiveWatch(
|
||||||
|
forDirectory: "/home/user/project",
|
||||||
|
mask: [.create, .modify, .delete]
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
The returned array contains one watch descriptor per directory. Subdirectories created **after** this call are not covered.
|
||||||
|
|
||||||
|
### Automatic Subtree Watching
|
||||||
|
|
||||||
|
When you also want future subdirectories to be picked up, use ``Inotify/Inotify/addWatchWithAutomaticSubtreeWatching(forDirectory:mask:)`` instead:
|
||||||
|
|
||||||
|
```swift
|
||||||
|
let descriptors = try await inotify.addWatchWithAutomaticSubtreeWatching(
|
||||||
|
forDirectory: "/home/user/project",
|
||||||
|
mask: [.create, .modify, .delete]
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
Internally this listens for `CREATE` events carrying the ``InotifyEventMask/isDir`` flag and installs a new watch with the same mask whenever a subdirectory appears.
|
||||||
|
|
||||||
|
### Choosing the Right Method
|
||||||
|
|
||||||
|
| Method | Covers existing subdirectories | Covers new subdirectories |
|
||||||
|
|--------|:----:|:----:|
|
||||||
|
| ``Inotify/Inotify/addWatch(path:mask:)`` | No | No |
|
||||||
|
| ``Inotify/Inotify/addRecursiveWatch(forDirectory:mask:)`` | Yes | No |
|
||||||
|
| ``Inotify/Inotify/addWatchWithAutomaticSubtreeWatching(forDirectory:mask:)`` | Yes | Yes |
|
||||||
@@ -3,6 +3,7 @@ import CInotify
|
|||||||
|
|
||||||
public actor Inotify {
|
public actor Inotify {
|
||||||
private let fd: CInt
|
private let fd: CInt
|
||||||
|
private var excludedItemNames: Set<String> = []
|
||||||
private var watches = InotifyWatchManager()
|
private var watches = InotifyWatchManager()
|
||||||
private var eventReader: any DispatchSourceRead
|
private var eventReader: any DispatchSourceRead
|
||||||
private var eventStream: AsyncStream<RawInotifyEvent>
|
private var eventStream: AsyncStream<RawInotifyEvent>
|
||||||
@@ -18,6 +19,24 @@ public actor Inotify {
|
|||||||
(self.eventReader, self.eventStream) = Self.createEventReader(forFileDescriptor: fd)
|
(self.eventReader, self.eventStream) = Self.createEventReader(forFileDescriptor: fd)
|
||||||
}
|
}
|
||||||
|
|
||||||
|
public func isExcluded(_ name: String) -> Bool {
|
||||||
|
self.excludedItemNames.contains(name)
|
||||||
|
}
|
||||||
|
|
||||||
|
public func exclude(name: String) {
|
||||||
|
self.excludedItemNames.insert(name)
|
||||||
|
}
|
||||||
|
|
||||||
|
public func exclude(names: String...) {
|
||||||
|
self.exclude(names: names)
|
||||||
|
}
|
||||||
|
|
||||||
|
public func exclude(names: [String]) {
|
||||||
|
for name in names {
|
||||||
|
self.excludedItemNames.insert(name)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
@discardableResult
|
@discardableResult
|
||||||
public func addWatch(path: String, mask: InotifyEventMask) throws -> CInt {
|
public func addWatch(path: String, mask: InotifyEventMask) throws -> CInt {
|
||||||
let wd = inotify_add_watch(self.fd, path, mask.rawValue)
|
let wd = inotify_add_watch(self.fd, path, mask.rawValue)
|
||||||
@@ -30,7 +49,7 @@ public actor Inotify {
|
|||||||
|
|
||||||
@discardableResult
|
@discardableResult
|
||||||
public func addRecursiveWatch(forDirectory path: String, mask: InotifyEventMask) async throws -> [CInt] {
|
public func addRecursiveWatch(forDirectory path: String, mask: InotifyEventMask) async throws -> [CInt] {
|
||||||
let directoryPaths = try await DirectoryResolver.resolve(path)
|
let directoryPaths = try await DirectoryResolver.resolve(path, excluding: self.excludedItemNames)
|
||||||
var result: [CInt] = []
|
var result: [CInt] = []
|
||||||
for path in directoryPaths {
|
for path in directoryPaths {
|
||||||
let wd = try self.addWatch(path: path.string, mask: mask)
|
let wd = try self.addWatch(path: path.string, mask: mask)
|
||||||
@@ -59,6 +78,7 @@ public actor Inotify {
|
|||||||
|
|
||||||
private func transform(_ rawEvent: RawInotifyEvent) async -> InotifyEvent? {
|
private func transform(_ rawEvent: RawInotifyEvent) async -> InotifyEvent? {
|
||||||
guard let path = self.watches.path(forId: rawEvent.watchDescriptor) else { return nil }
|
guard let path = self.watches.path(forId: rawEvent.watchDescriptor) else { return nil }
|
||||||
|
guard !self.excludedItemNames.contains(rawEvent.name) else { return nil }
|
||||||
let event = InotifyEvent.init(from: rawEvent, inDirectory: path)
|
let event = InotifyEvent.init(from: rawEvent, inDirectory: path)
|
||||||
await self.addWatchInCaseOfAutomaticSubtreeWatching(event)
|
await self.addWatchInCaseOfAutomaticSubtreeWatching(event)
|
||||||
return InotifyEvent.init(from: rawEvent, inDirectory: path)
|
return InotifyEvent.init(from: rawEvent, inDirectory: path)
|
||||||
|
|||||||
@@ -4,6 +4,6 @@ import ArgumentParser
|
|||||||
struct Command: AsyncParsableCommand {
|
struct Command: AsyncParsableCommand {
|
||||||
static let configuration = CommandConfiguration(
|
static let configuration = CommandConfiguration(
|
||||||
abstract: "Project tasks of Astzweig's Swift Inotify project.",
|
abstract: "Project tasks of Astzweig's Swift Inotify project.",
|
||||||
subcommands: [TestCommand.self]
|
subcommands: [TestCommand.self, GenerateDocumentationCommand.self]
|
||||||
)
|
)
|
||||||
}
|
}
|
||||||
|
|||||||
37
Sources/TaskCLI/DoccFinder.swift
Normal file
37
Sources/TaskCLI/DoccFinder.swift
Normal file
@@ -0,0 +1,37 @@
|
|||||||
|
import _NIOFileSystem
|
||||||
|
|
||||||
|
public struct DoccFinder {
|
||||||
|
static let fileManager = FileSystem.shared
|
||||||
|
|
||||||
|
public static func getTargetsWithDocumentation(at paths: String...) async throws -> [String] {
|
||||||
|
try await Self.getTargetsWithDocumentation(at: paths)
|
||||||
|
}
|
||||||
|
|
||||||
|
static func getTargetsWithDocumentation(at paths: [String]) async throws -> [String] {
|
||||||
|
var resolved: [String] = []
|
||||||
|
|
||||||
|
for path in paths {
|
||||||
|
let itemPath = FilePath(path)
|
||||||
|
|
||||||
|
try await withSubdirectories(at: itemPath) { targetPath in
|
||||||
|
print("Target path is", targetPath.description)
|
||||||
|
try await withSubdirectories(at: targetPath) { subdirectory in
|
||||||
|
guard subdirectory.description.hasSuffix(".docc") else { return }
|
||||||
|
guard let target = targetPath.lastComponent?.description else { return }
|
||||||
|
resolved.append(target)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
return resolved
|
||||||
|
}
|
||||||
|
|
||||||
|
private static func withSubdirectories(at path: FilePath, body: (FilePath) async throws -> Void) async throws {
|
||||||
|
let directoryHandle = try await fileManager.openDirectory(atPath: path)
|
||||||
|
for try await childContent in directoryHandle.listContents() {
|
||||||
|
guard childContent.type == .directory else { continue }
|
||||||
|
try await body(childContent.path)
|
||||||
|
}
|
||||||
|
try await directoryHandle.close()
|
||||||
|
}
|
||||||
|
}
|
||||||
180
Sources/TaskCLI/GenerateDocumentation Command.swift
Normal file
180
Sources/TaskCLI/GenerateDocumentation Command.swift
Normal file
@@ -0,0 +1,180 @@
|
|||||||
|
import ArgumentParser
|
||||||
|
import AsyncAlgorithms
|
||||||
|
import Foundation
|
||||||
|
import Logging
|
||||||
|
import Noora
|
||||||
|
import Subprocess
|
||||||
|
|
||||||
|
struct GenerateDocumentationCommand: AsyncParsableCommand {
|
||||||
|
static let configuration = CommandConfiguration(
|
||||||
|
commandName: "generate-documentation",
|
||||||
|
abstract: "Generate DocC documentation of all targets inside a Linux container.",
|
||||||
|
aliases: ["gd"],
|
||||||
|
)
|
||||||
|
|
||||||
|
@OptionGroup var global: GlobalOptions
|
||||||
|
|
||||||
|
private static let doccPluginURL = "https://github.com/apple/swift-docc-plugin.git"
|
||||||
|
private static let doccPluginMinVersion = "1.4.0"
|
||||||
|
private static let skipItems: Set<String> = [".git", ".build", ".swiftpm", "public"]
|
||||||
|
|
||||||
|
// MARK: - Run
|
||||||
|
|
||||||
|
func run() async throws {
|
||||||
|
let noora = Noora()
|
||||||
|
let logger = global.makeLogger(labeled: "swift-inotify.cli.task.generate-documentation")
|
||||||
|
let fileManager = FileManager.default
|
||||||
|
let projectDirectory = URL(fileURLWithPath: fileManager.currentDirectoryPath)
|
||||||
|
|
||||||
|
let targets = try await Self.targets(for: projectDirectory)
|
||||||
|
|
||||||
|
noora.info("Generating DocC documentation on Linux.")
|
||||||
|
logger.debug("Current directory", metadata: ["current-directory": "\(projectDirectory.path(percentEncoded: false))", "targets": "\(targets.joined(separator: ", "))"])
|
||||||
|
|
||||||
|
let tempDirectory = try copyProject(from: projectDirectory)
|
||||||
|
logger.info("Copied project to temporary directory.", metadata: ["path": "\(tempDirectory.path(percentEncoded: false))"])
|
||||||
|
|
||||||
|
defer {
|
||||||
|
try? fileManager.removeItem(at: tempDirectory)
|
||||||
|
logger.info("Cleaned up temporary directory.")
|
||||||
|
}
|
||||||
|
|
||||||
|
try await injectDoccPluginDependency(in: tempDirectory, logger: logger)
|
||||||
|
let script = Self.makeRunScript(for: targets)
|
||||||
|
|
||||||
|
logger.debug("Container script", metadata: ["script": "\(script)"])
|
||||||
|
let dockerResult = try await Subprocess.run(
|
||||||
|
.name("docker"),
|
||||||
|
arguments: [
|
||||||
|
"run", "--rm",
|
||||||
|
"-v", "\(tempDirectory.path(percentEncoded: false)):/code",
|
||||||
|
"--platform", "linux/arm64",
|
||||||
|
"-w", "/code",
|
||||||
|
"swift:latest",
|
||||||
|
"/bin/bash", "-c", script,
|
||||||
|
],
|
||||||
|
preferredBufferSize: 10,
|
||||||
|
) { execution, standardInput, standardOutput, standardError in
|
||||||
|
print("")
|
||||||
|
let stdout = standardOutput.lines()
|
||||||
|
let stderr = standardError.lines()
|
||||||
|
for try await line in merge(stdout, stderr) {
|
||||||
|
noora.passthrough("\(line)")
|
||||||
|
}
|
||||||
|
print("")
|
||||||
|
}
|
||||||
|
|
||||||
|
guard dockerResult.terminationStatus.isSuccess else {
|
||||||
|
noora.error("Documentation generation failed.")
|
||||||
|
return
|
||||||
|
}
|
||||||
|
|
||||||
|
try copyResults(from: tempDirectory, to: projectDirectory)
|
||||||
|
try Self.generateIndexHTML(
|
||||||
|
templateURL: projectDirectory.appending(path: ".github/workflows/index.tpl.html"),
|
||||||
|
outputURL: projectDirectory.appending(path: "public/index.html")
|
||||||
|
)
|
||||||
|
|
||||||
|
noora.success(
|
||||||
|
.alert("Documentation generated successfully.",
|
||||||
|
takeaways: ["Start a local web server with ./public as document root, i.e. with python3 -m http.server to browse the documentation."]
|
||||||
|
)
|
||||||
|
)
|
||||||
|
}
|
||||||
|
|
||||||
|
private static func generateIndexHTML(templateURL: URL, outputURL: URL) throws {
|
||||||
|
var content = try String(contentsOf: templateURL, encoding: .utf8)
|
||||||
|
|
||||||
|
let replacements: [(String, String)] = [
|
||||||
|
("{{project.name}}", "Swift Inotify"),
|
||||||
|
("{{project.tagline}}", "🗂️ Monitor filesystem events on Linux using modern Swift concurrency"),
|
||||||
|
("{{project.links}}", """
|
||||||
|
<li><a href="inotify/documentation/inotify/">Inotify</a>: The actual library.</li>\
|
||||||
|
<li><a href="taskcli/documentation/taskcli/">TaskCLI</a>: The project build command.</li>
|
||||||
|
"""),
|
||||||
|
]
|
||||||
|
|
||||||
|
for (placeholder, value) in replacements {
|
||||||
|
content = content.replacingOccurrences(of: placeholder, with: value)
|
||||||
|
}
|
||||||
|
|
||||||
|
try FileManager.default.createDirectory(
|
||||||
|
at: outputURL.deletingLastPathComponent(),
|
||||||
|
withIntermediateDirectories: true
|
||||||
|
)
|
||||||
|
try content.write(to: outputURL, atomically: true, encoding: .utf8)
|
||||||
|
}
|
||||||
|
|
||||||
|
private static func targets(for projectDirectory: URL) async throws -> [String] {
|
||||||
|
let sourcesDirectory = projectDirectory.appending(path: "Sources").path
|
||||||
|
let testsDirectory = projectDirectory.appending(path: "Tests").path
|
||||||
|
return try await DoccFinder.getTargetsWithDocumentation(at: sourcesDirectory, testsDirectory)
|
||||||
|
}
|
||||||
|
|
||||||
|
private static func makeRunScript(for targets: [String]) -> String {
|
||||||
|
targets.map {
|
||||||
|
"mkdir -p \"./public/\($0.localizedLowercase)\" && " +
|
||||||
|
"swift package --allow-writing-to-directory \"\($0.localizedLowercase)\" " +
|
||||||
|
"generate-documentation --disable-indexing --transform-for-static-hosting " +
|
||||||
|
"--target \"\($0)\" " +
|
||||||
|
"--hosting-base-path \"\($0.localizedLowercase)\" " +
|
||||||
|
"--output-path \"./public/\($0.localizedLowercase)\""
|
||||||
|
}.joined(separator: " && ")
|
||||||
|
}
|
||||||
|
|
||||||
|
// MARK: - Project Copy
|
||||||
|
|
||||||
|
private func copyProject(from source: URL) throws -> URL {
|
||||||
|
let fileManager = FileManager.default
|
||||||
|
let tempDirectory = fileManager.temporaryDirectory.appending(path: "swift-inotify-docs-\(UUID().uuidString)")
|
||||||
|
try fileManager.createDirectory(at: tempDirectory, withIntermediateDirectories: true)
|
||||||
|
|
||||||
|
let contents = try fileManager.contentsOfDirectory(at: source, includingPropertiesForKeys: nil)
|
||||||
|
for item in contents {
|
||||||
|
guard !Self.skipItems.contains(item.lastPathComponent) else { continue }
|
||||||
|
try fileManager.copyItem(at: item, to: tempDirectory.appending(path: item.lastPathComponent))
|
||||||
|
}
|
||||||
|
|
||||||
|
return tempDirectory
|
||||||
|
}
|
||||||
|
|
||||||
|
private func copyResults(from tempDirectory: URL, to projectDirectory: URL) throws {
|
||||||
|
let fileManager = FileManager.default
|
||||||
|
let source = tempDirectory.appending(path: "public")
|
||||||
|
let destination = projectDirectory.appending(path: "public")
|
||||||
|
|
||||||
|
if fileManager.fileExists(atPath: destination.path(percentEncoded: false)) {
|
||||||
|
try fileManager.removeItem(at: destination)
|
||||||
|
}
|
||||||
|
try fileManager.copyItem(at: source, to: destination)
|
||||||
|
}
|
||||||
|
|
||||||
|
// MARK: - Dependency Injection
|
||||||
|
|
||||||
|
private func injectDoccPluginDependency(in directory: URL, logger: Logger) async throws {
|
||||||
|
let result = try await Subprocess.run(
|
||||||
|
.name("swift"),
|
||||||
|
arguments: [
|
||||||
|
"package", "--package-path", directory.path(percentEncoded: false),
|
||||||
|
"add-dependency", "--from", Self.doccPluginMinVersion, Self.doccPluginURL
|
||||||
|
],
|
||||||
|
) { _ in }
|
||||||
|
|
||||||
|
guard result.terminationStatus.isSuccess else {
|
||||||
|
throw GenerateDocumentationError.dependencyInjectionFailed
|
||||||
|
}
|
||||||
|
|
||||||
|
logger.info("Injected swift-docc-plugin dependency.")
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
enum GenerateDocumentationError: Error, CustomStringConvertible {
|
||||||
|
case dependencyInjectionFailed
|
||||||
|
|
||||||
|
var description: String {
|
||||||
|
switch self {
|
||||||
|
case .dependencyInjectionFailed:
|
||||||
|
"Failed to add swift-docc-plugin dependency to Package.swift."
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
61
Sources/TaskCLI/TaskCLI.docc/TaskCLI.md
Normal file
61
Sources/TaskCLI/TaskCLI.docc/TaskCLI.md
Normal file
@@ -0,0 +1,61 @@
|
|||||||
|
# ``TaskCLI``
|
||||||
|
|
||||||
|
The build tool for the Swift Inotify project.
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
`TaskCLI` is a small command-line executable (exposed as `task` in `Package.swift`) that automates project-level workflows. Its primary purpose is running integration tests and generating documentation inside Linux Docker containers, so you can validate inotify-dependent code on the correct platform even when developing on macOS.
|
||||||
|
|
||||||
|
### Running the Tests
|
||||||
|
|
||||||
|
```bash
|
||||||
|
swift run task test
|
||||||
|
```
|
||||||
|
|
||||||
|
This launches a `swift:latest` Docker container with the repository mounted at `/code`, then executes two test passes:
|
||||||
|
|
||||||
|
1. All tests **except** `InotifyLimitTests` — the regular integration suite.
|
||||||
|
2. Only `InotifyLimitTests` (with `--skip-build`) — tests that manipulate system-level inotify limits and must run in isolation.
|
||||||
|
|
||||||
|
The container is started with `--security-opt systempaths=unconfined` so that the limit tests can write to `/proc/sys/fs/inotify/*`.
|
||||||
|
|
||||||
|
### Generating Documentation
|
||||||
|
|
||||||
|
```bash
|
||||||
|
swift run task generate-documentation
|
||||||
|
```
|
||||||
|
|
||||||
|
This copies the project to a temporary directory, injects the `swift-docc-plugin` dependency via `swift package add-dependency` (if absent), and runs documentation generation inside a `swift:latest` Docker container. The resulting static sites are written to `./public/inotify/` and `./public/taskcli/`, ready for deployment to GitHub Pages.
|
||||||
|
|
||||||
|
The working tree is never modified — all changes happen in the temporary copy, which is cleaned up automatically.
|
||||||
|
|
||||||
|
### Verbosity
|
||||||
|
|
||||||
|
Pass one or more `-v` flags to increase log output:
|
||||||
|
|
||||||
|
| Flag | Level |
|
||||||
|
|------|-------|
|
||||||
|
| *(none)* | `notice` |
|
||||||
|
| `-v` | `info` |
|
||||||
|
| `-vv` | `debug` |
|
||||||
|
| `-vvv` | `trace` |
|
||||||
|
|
||||||
|
### Prerequisites
|
||||||
|
|
||||||
|
Docker must be installed and running on the host machine. The container uses the `linux/arm64` platform by default.
|
||||||
|
|
||||||
|
## Topics
|
||||||
|
|
||||||
|
### Commands
|
||||||
|
|
||||||
|
- ``Command``
|
||||||
|
- ``TestCommand``
|
||||||
|
- ``GenerateDocumentationCommand``
|
||||||
|
|
||||||
|
### Configuration
|
||||||
|
|
||||||
|
- ``GlobalOptions``
|
||||||
|
|
||||||
|
### Errors
|
||||||
|
|
||||||
|
- ``GenerateDocumentationError``
|
||||||
17
Tests/InotifyIntegrationTests/DirectoryResolverTests.swift
Normal file
17
Tests/InotifyIntegrationTests/DirectoryResolverTests.swift
Normal file
@@ -0,0 +1,17 @@
|
|||||||
|
import Foundation
|
||||||
|
import Testing
|
||||||
|
@testable import Inotify
|
||||||
|
|
||||||
|
@Suite("Directory Resolver")
|
||||||
|
struct DirectoryResolverTests {
|
||||||
|
@Test func listsDirectoryTree() async throws {
|
||||||
|
try await withTempDir { dir in
|
||||||
|
let subDirectory = "\(dir)/Subfolder/Folder 01"
|
||||||
|
try FileManager.default.createDirectory(atPath: subDirectory, withIntermediateDirectories: true)
|
||||||
|
let directories = try await DirectoryResolver.resolve(dir)
|
||||||
|
|
||||||
|
#expect(directories.count == 3)
|
||||||
|
#expect(directories.map { $0.description } == [dir, "\(dir)/Subfolder", subDirectory])
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -21,6 +21,24 @@ struct RecursiveEventTests {
|
|||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
@Test func ignoresFileCreationInIgnoredSubfolder() async throws {
|
||||||
|
try await withTempDir { dir in
|
||||||
|
let subDirectory = "\(dir)/Subfolder"
|
||||||
|
let filepath = "\(subDirectory)/modify-target.txt"
|
||||||
|
try FileManager.default.createDirectory(atPath: subDirectory, withIntermediateDirectories: true)
|
||||||
|
|
||||||
|
let events = try await getEventsForTrigger(
|
||||||
|
in: dir,
|
||||||
|
mask: [.create],
|
||||||
|
recursive: .recursive,
|
||||||
|
exclude: ["Subfolder"]
|
||||||
|
) { _ in try createFile(at: "\(filepath)", contents: "hello") }
|
||||||
|
|
||||||
|
let createEvent = events.first { $0.mask.contains(.create) && $0.path.string == filepath }
|
||||||
|
#expect(createEvent == nil, "Did not expect CREATE for '\(filepath)', got: \(events)")
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
@Test func newSubfoldersOfRecursiveWatchAreAutomaticallyWatchedToo() async throws {
|
@Test func newSubfoldersOfRecursiveWatchAreAutomaticallyWatchedToo() async throws {
|
||||||
try await withTempDir { dir in
|
try await withTempDir { dir in
|
||||||
let subDirectory = "\(dir)/Subfolder"
|
let subDirectory = "\(dir)/Subfolder"
|
||||||
@@ -32,7 +50,7 @@ struct RecursiveEventTests {
|
|||||||
recursive: .withAutomaticSubtreeWatching
|
recursive: .withAutomaticSubtreeWatching
|
||||||
) { _ in
|
) { _ in
|
||||||
try FileManager.default.createDirectory(atPath: subDirectory, withIntermediateDirectories: true)
|
try FileManager.default.createDirectory(atPath: subDirectory, withIntermediateDirectories: true)
|
||||||
try await Task.sleep(for: .milliseconds(200))
|
try await Task.sleep(for: .milliseconds(400))
|
||||||
try createFile(at: "\(filepath)", contents: "hello")
|
try createFile(at: "\(filepath)", contents: "hello")
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|||||||
@@ -10,9 +10,11 @@ func getEventsForTrigger(
|
|||||||
in dir: String,
|
in dir: String,
|
||||||
mask: InotifyEventMask,
|
mask: InotifyEventMask,
|
||||||
recursive: RecursivKind = .nonrecursive,
|
recursive: RecursivKind = .nonrecursive,
|
||||||
|
exclude: [String] = [],
|
||||||
trigger: @escaping (String) async throws -> Void,
|
trigger: @escaping (String) async throws -> Void,
|
||||||
) async throws -> [InotifyEvent] {
|
) async throws -> [InotifyEvent] {
|
||||||
let watcher = try Inotify()
|
let watcher = try Inotify()
|
||||||
|
await watcher.exclude(names: exclude)
|
||||||
switch recursive {
|
switch recursive {
|
||||||
case .nonrecursive:
|
case .nonrecursive:
|
||||||
try await watcher.addWatch(path: dir, mask: mask)
|
try await watcher.addWatch(path: dir, mask: mask)
|
||||||
|
|||||||
Reference in New Issue
Block a user