Compare commits
6 Commits
2.1.0
...
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
|
||||
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: "AsyncAlgorithms", package: "swift-async-algorithms"),
|
||||
.product(name: "Logging", package: "swift-log"),
|
||||
.product(name: "_NIOFileSystem", package: "swift-nio"),
|
||||
.product(name: "Subprocess", package: "swift-subprocess"),
|
||||
.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 {
|
||||
static let fileManager = FileSystem.shared
|
||||
|
||||
public static func resolve(_ paths: String...) async throws -> [FilePath] {
|
||||
try await Self.resolve(paths)
|
||||
public static func resolve(_ paths: String..., excluding itemNames: Set<String> = []) async throws -> [FilePath] {
|
||||
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] = []
|
||||
|
||||
for path in paths {
|
||||
let itemPath = FilePath(path)
|
||||
try await Self.ensure(itemPath, is: .directory)
|
||||
|
||||
let allDirectoriesIncludingSelf = try await getAllSubdirectoriesAndSelf(at: itemPath)
|
||||
resolved.append(contentsOf: allDirectoriesIncludingSelf)
|
||||
let path = FilePath(path)
|
||||
resolved.append(path)
|
||||
try await withSubdirectories(at: path, recursive: true) { subdirectoryPath in
|
||||
guard let basename = subdirectoryPath.lastComponent?.description else { return }
|
||||
guard !itemNames.contains(basename) else { return }
|
||||
resolved.append(subdirectoryPath)
|
||||
}
|
||||
}
|
||||
|
||||
return resolved
|
||||
}
|
||||
|
||||
private static func ensure(_ path: FilePath, is fileType: FileType) 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] = []
|
||||
private static func withSubdirectories(at path: FilePath, recursive: Bool = false, body: (FilePath) async throws -> Void) async throws {
|
||||
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 }
|
||||
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()
|
||||
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 {
|
||||
private let fd: CInt
|
||||
private var excludedItemNames: Set<String> = []
|
||||
private var watches = InotifyWatchManager()
|
||||
private var eventReader: any DispatchSourceRead
|
||||
private var eventStream: AsyncStream<RawInotifyEvent>
|
||||
@@ -18,6 +19,24 @@ public actor Inotify {
|
||||
(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
|
||||
public func addWatch(path: String, mask: InotifyEventMask) throws -> CInt {
|
||||
let wd = inotify_add_watch(self.fd, path, mask.rawValue)
|
||||
@@ -30,7 +49,7 @@ public actor Inotify {
|
||||
|
||||
@discardableResult
|
||||
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] = []
|
||||
for path in directoryPaths {
|
||||
let wd = try self.addWatch(path: path.string, mask: mask)
|
||||
@@ -59,6 +78,7 @@ public actor Inotify {
|
||||
|
||||
private func transform(_ rawEvent: RawInotifyEvent) async -> InotifyEvent? {
|
||||
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)
|
||||
await self.addWatchInCaseOfAutomaticSubtreeWatching(event)
|
||||
return InotifyEvent.init(from: rawEvent, inDirectory: path)
|
||||
|
||||
@@ -4,6 +4,6 @@ import ArgumentParser
|
||||
struct Command: AsyncParsableCommand {
|
||||
static let configuration = CommandConfiguration(
|
||||
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 {
|
||||
try await withTempDir { dir in
|
||||
let subDirectory = "\(dir)/Subfolder"
|
||||
@@ -32,7 +50,7 @@ struct RecursiveEventTests {
|
||||
recursive: .withAutomaticSubtreeWatching
|
||||
) { _ in
|
||||
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")
|
||||
}
|
||||
|
||||
|
||||
@@ -10,9 +10,11 @@ func getEventsForTrigger(
|
||||
in dir: String,
|
||||
mask: InotifyEventMask,
|
||||
recursive: RecursivKind = .nonrecursive,
|
||||
exclude: [String] = [],
|
||||
trigger: @escaping (String) async throws -> Void,
|
||||
) async throws -> [InotifyEvent] {
|
||||
let watcher = try Inotify()
|
||||
await watcher.exclude(names: exclude)
|
||||
switch recursive {
|
||||
case .nonrecursive:
|
||||
try await watcher.addWatch(path: dir, mask: mask)
|
||||
|
||||
Reference in New Issue
Block a user