Permission issue when Swift toolchain/docc is installed as root user

[xtremekforever]

Description

When the Swift toolchain is installed to / or /usr/libexec (as is done with Debian and Fedora distributions), the docc binary throws a permissions issue when attempting to preview or generate documentation:

xtremek@Winter ~/t/swift-async-algorithms (main) [1]> ls -la /usr/libexec/swift/6.0.3/bin/docc
-rwxr-xr-x 1 root root 23984936 Dec 15 19:00 /usr/libexec/swift/6.0.3/bin/docc*
xtremek@Winter ~/t/swift-async-algorithms (main)> /usr/libexec/swift/6.0.3/bin/docc preview
Input: ~/tmp/swift-async-algorithms
Template: /usr/libexec/swift/6.0.3/share/docc/render
Error: Error Domain=NSCocoaErrorDomain Code=513 "You don’t have permission."

However, if the Swift toolchain and docc are installed to a directory under the user, like in the user's home directory or via Swiftly, then it works perfectly fine:

xtremek@Winter ~/t/swift-async-algorithms (main)> ls -la $(which docc)
lrwxrwxrwx 1 xtremek xtremek 32 Jan  4 15:36 ~/.local/bin/docc -> ~/.local/bin/swiftly*
xtremek@Winter ~/t/swift-async-algorithms (main)> ~/.local/bin/docc preview
Input: ~/tmp/swift-async-algorithms
Template: ~/.local/share/swiftly/toolchains/6.0.3/usr/share/docc/render
========================================
Starting Local Preview Server
         Address: http://localhost:8080/documentation/validation
========================================

Any ideas why this happens? It makes it impossible to have Swift installed to the system and then use docc to preview and generate documentation, for example in a CI environment...

Checklist

• If possible, I've reproduced the issue using the main branch of this package.
• This issue hasn't been addressed in an existing GitHub issue.

Expected Behavior

Running docc convert or docc preview when the Swift toolchain is installed to a system directory with root permissions works.

Actual behavior

Running docc convert or docc preview when the Swift toolchain is installed to a system directory with root permissions throws a permissions error:

Error: Error Domain=NSCocoaErrorDomain Code=513 "You don’t have permission."

Steps To Reproduce

1. Install Swift to a system directory such as / or /usr/libexec/swift.
2. Run docc preview from the system directory.
3. Observe that it does not work, but throws a permissions issue.

Swift-DocC Version Information

Swift 6.0.3 Release

Swift Compiler Version Information

Swift version 6.0.3 (swift-6.0.3-RELEASE)
Target: aarch64-unknown-linux-gnu

[RandomHashTags]

Can confirm using Swiftly + manually selecting the toolchain in VS Code and updating the PATH as a workaround (at least for Arch Linux).

[yretenai]

From my limited testing using strace, at some point docc tries to chown the files back to root after copying the renderer assets (which is not permitted.) I don't know if this is a side effect from some copy intrinsic or something docc does deliberately.

Also note that this only started happening in Swift 6. Prior versions do not exhibit this behaviour, at least on my installations.

[yretenai]

Diagnosing Docc directly, it happens here:

swift-docc/Sources/SwiftDocCUtilities/Action/Actions/Action+MoveOutput.swift

Line 29 in 60ebde3

try fileManager.copyItem(at: template, to: targetURL)

copyItem copies all attributes, including ownership and the owning group.

[yretenai]

yretenai@521e2cb I made a small patch that fixes this by manually copying every single file but I am not confident enough to push a PR for this quite yet as I have yet to update the documentation and write a test case for it. (I also don't know if there's a way to tell Swift's FileManager to not copy attributes, it doesn't appear to be so. My code definitely can be improved, however.)

While writing this I also discovered the DOCC_HTML_DIR environment variable, so that can be a convenient workaround without futzing up the system or installing a local copy of swift. (Copying the Swift template dir, which the program outputs and changing owner from root to user and then setting that env variable in something like .zshrc)

[yretenai]

It seems the issue is tracked in Foundation already, unfortunately Swift 6.0, through 6.0.3 (possibly all the way to 6.1) will remain broken unless a patch (like mine) gets merged (that is assuming it gets fixed in Foundation before 6.1/6.0.4 releases)

[xtremekforever]

Well these issues look like "fun". They need to be fixed tho...so even if it happens in 6.2 we'll eventually need them to be resolved!