Install docs for a user-scope package that creates collections under an installation-scope package

Questions & Answers
1

Concretely, gui-easy has collections racket/gui/easy, so:

# raco setup --pkgs gui-easy
raco setup: version: 8.17
raco setup: platform: x86_64-linux [cs]
raco setup: target machine: ta6le
raco setup: installation name: 8.17
raco setup: variants: cs
raco setup: main collects: /usr/share/racket/collects/
raco setup: collects paths:
raco setup:   /home/benknoble/.local/share/racket/8.17/collects
raco setup:   /usr/share/racket/collects/
raco setup: main pkgs: /usr/share/racket/pkgs
raco setup: pkgs paths:
raco setup:   /usr/share/racket/pkgs
raco setup:   /home/benknoble/.local/share/racket/8.17/pkgs
raco setup: links files:
raco setup:   /usr/share/racket/links.rktd
raco setup:   /home/benknoble/.local/share/racket/8.17/links.rktd
raco setup: compiled-file roots:
raco setup:   same
raco setup:   /usr/lib64/racket/compiled
raco setup: main docs: /usr/share/doc/racket-8.17
raco setup: --- updating info-domain tables ---                    [17:09:39]
raco setup: --- pre-installing collections ---                     [17:09:39]
raco setup: --- installing foreign libraries ---                   [17:09:39]
raco setup: --- installing shared files ---                        [17:09:39]
raco setup: --- compiling collections ---                          [17:09:39]
raco setup: --- parallel build using 8 jobs ---                    [17:09:39]
raco setup: 0: idle
raco setup: 1: idle
raco setup: 2: idle
raco setup: 3: idle
raco setup: 4: idle
raco setup: 5: idle
raco setup: 6: idle
raco setup: 7: idle
██████████████████▊█████████████████▊██████████████████▊█████████████████▊██████████████████▊█████████████████▊█████████████████▊██████████████████▊█████████████████▊██████████████████ 100%
raco setup: --- creating launchers ---                             [17:09:40]
raco setup: --- installing man pages ---                           [17:09:40]
raco setup: --- building documentation ---                         [17:09:40]
raco setup: --- installing collections ---                         [17:09:41]
raco setup: installing: <collects>/racket
raco setup: installing: <pkgs>/gui-lib/racket/gui
delete-file: cannot delete file
  path: /usr/bin/gracket-text
  system error: Permission non accordée; errno=13
  context...:
   /usr/share/racket/collects/launcher/launcher.rkt:177:0: install-template
   /usr/share/racket/collects/launcher/launcher.rkt:385:0: make-unix-launcher
   /usr/share/racket/pkgs/gui-lib/racket/gui/installer.rkt:48:0: do-installer
   /usr/share/racket/collects/setup/setup-core.rkt:934:2: do-install-part
   body of "/usr/share/racket/collects/setup/main.rkt"
   body of "/usr/share/racket/collects/raco/main.rkt"
raco setup: --- post-installing collections ---                    [17:09:41]
raco setup: --- summary of errors ---                              [17:09:41]
raco setup: error: during general install for <pkgs>/gui-lib/racket/gui
raco setup:   delete-file: cannot delete file
raco setup:     path: /usr/bin/gracket-text
raco setup:     system error: Permission non accordée; errno=13

I think the installation scope is owned by root, since I'm able to rebuild racket/gui as root, for example. I can't do raco setup racket/gui/easy, since that doesn't build and install the docs. What's a guy to do here to get local gui-easy docs?

(PS I didn't have this trouble on macOS, only Linux, but that's probably because the installation scope is managed by Homebrew or something so is not owned by root there.)

2

Does raco setup --avoid-main --pkgs gui-easy work?

Though I thought --avoid-main was implied if operating only on user-scope packages. If it isn't, I think it should be.

I am guessing you have all of the gui-easy-related packages installed in user scope: if I'm misunderstanding that, maybe something else is wrong. But if I do understand correctly, I think it isn't quite right to describe this as “a user-scope package that creates collections under an installation-scope package.” I think the situation is that the gui-easy package in user scope build docs that splice into the racket/gui collection, and other parts of the racket/gui collection come from installation scope packages.

Actually, I would have guessed this would have worked, assuming nothing in the racket/gui/easy collection exists at installation scope …

3

Does raco setup --avoid-main --pkgs gui-easy work?

Yep!

Though I thought --avoid-main was implied if operating only on user-scope packages. If it isn't, I think it should be.

I don't see any docs locally or on racket-lang.org that imply this, though maybe defaults have changed between my distro's stable (8.17) and 9+.

I am guessing you have all of the gui-easy-related packages installed in user scope: if I'm misunderstanding that, maybe something else is wrong. But if I do understand correctly, I think it isn't quite right to describe this as “a user-scope package that creates collections under an installation-scope package.” I think the situation is that the gui-easy package in user scope build docs that splice into the racket/gui collection, and other parts of the racket/gui collection come from installation scope packages.

Yep, that's more accurate. Regardless, --avoid-main or (see below) collect
names seem to do the trick.

I can't do raco setup racket/gui/easy, since that doesn't build and install the docs.

Actually, I would have guessed this would have worked, assuming nothing in the racket/gui/easy collection exists at installation scope …

I think I was confused by outputs indicating no docs were built. This does work, and the best test I have is

raco setup --fast-clean --pkgs gui-easy
<build command of your choice>
raco docs gui-easy

That's more reliable for seeing what works :slight_smile: Otherwise I get confused.