Clutch 🪺 run Swift scripts from a nest of dependencies

Community Showcase
, ,
1

https://github.com/swift-nest/clutch

Scripting in Swift felt like a hassle until I automated the process of creating/building/running scattered scripts with common dependencies. Now it's a small pleasure, as I start from templates, build delays are hardly noticeable, and git repos are consolidated.

A "nest" (e.g., HOME/git/Nest) is a package with a common library and "peer" executable's for each associated script.

  • Put #!/usr/bin/env clutch on the first line of tool.swift.

  • When tool.swift is run, clutch creates, updates, and/or builds the nest peer.

  • tool depends on the nest library and its dependencies like Swift Argument Parser or Shwift.

Here's the quickstart from the README...

Assuming ~/git, PATH has ~/bin along with swift and git (and you're ok with Sources and nests/simple/Nest)...

# Build clutch and put on PATH (for `/usr/bin/env`)
git clone https://github.com/swift-clutch/clutch.git
cd clutch && swift build
cp .build/debug/clutch ~/bin

# Grab a sample nest package and try hello-world
cp -rf nests/simple/Nest ~/git/Nest
cat > hello <<EOF
#!/usr/bin/env clutch
let you = CommandLine.arguments[1...].first ?? "World"
print("Hello \(you)")

EOF

chmod +x hello
./hello friend # builds, runs `~/git/Nest/Sources/hello/main.swift`

clutch also helps manage peers and nests; it can list peers in a nest, emit peer source as a starting-point for a new script, etc. The nest location and script mapping are configurable by name and environment variable. You can have nests for builds, voice, video, etc. It works back at least to 5.6 on Linux and macOS 12.

clutch hello # run by name from anywhere
clutch hello.Nest # specify nest if not the default
clutch cat-hello # output peer source (`clutch cat-start > newscript.swift`)
clutch path-hello # echo peer path (`vi "$(clutch path-hello)"`)

clutch peers-Nest # list peers known in nest `Nest`
clutch dir-Nest # emit location of nest `Nest`

For details, see the README.

The closest alternative is https://github.com/mxcl/swift-sh, which parses import comments and manages a private package for each script.

For those who find the clutch code too cluttered by configuration, error, testing, and system-isolation hoo-ha, clatch is a 1-file executable to just create/build/run nest peers in ~/git: https://github.com/swift-nest/clutch/blob/main/Sources/clatch/clatch.swift

I hope this tiny tool saves you time and makes scripting in Swift easier. Feedback welcome!

1 Like
2

Took the quickest of glances at README but I did not get it…

I don’t understand:

When tool.swift is run, clutch creates and builds a peer as needed in a nest.

What is a “peer” and what is a “nest” ?

3

Thanks for taking a look.

What is a “peer” and what is a “nest” ?

A script file (something like {name}.swift) lives anywhere on your system.

Its peer -- equivalent source -- is a nest package executable product, with the peer source file {nest}/Sources/{name}/main.swift (or .../{name}.swift).

The "nest" is a Swift package with executable products, one per peer, and a library (of the same name) that each script depends on.

But more to the point, sorry for the confusion. I'll update the start of the README to define the jargon before use.