I want to talk about getting packages installed without their docs. I tried the binary and binary lib options of raco setup and they always tell me the package isn't compatible.
I've often had to resort to manually stripping a package of docs and doc dependencies myself.
What makes a package compatible with binary and binary lib options? And is there anything else I can do to avoid having docs on my machine?
Does the Built-Package Catalog help?
Another advantage of a built-package catalog is that it's compatible with “binary library” install mode, as selected with the --binary-lib flag to raco pkg install. In that mode, sources and documentation are stripped away from the package as it is installed, and dependencies that are needed only for compilation or building documentation are not downloaded at all.
So far. Are there other ways to make a package compatible with the binary and binary lib flags? Also where is the system's list of catalogs? I checked the user collects area and system collects area, I didn't find it.
When building racket for a g4 mac mini recently, the build took hours upon hours. Most of that, I expect, was due to building the documentation and the dependencies required to build the documentation(I didn't actually measure it, but it appeared that way).
I think it is strange that packages depend on their docs. I'm not very familiar with the package system so I'd like to ask, is this just a convention or is there some fundamental reason for it? To me, it makes sense for the documentation to reside in a different package, especially if the documentation requires a "build".
I wouldn't say packages depend on their docs, they just come with the docs. And they're still racket files. They can be required by a racket program and I believe they export values. I think you can pass a no docs flag generally to skip building docs.
I haven't heard of a convention for packaging docs with a package. I think it's just more work to separate them. A lot of smaller packages keep them together.
The two conventions I've seen are to package code and docs together, and the other is to split a package up into doc lib test packages.
I just realized that perhaps another solution to my problem is to make a bs racket doc package that's empty and install packages with the no docs option.
Update: this works to avoid installing the racket doc package. That's my main need, individual package docs are a cost I can handle.
I see a --no-docs flag for raco pkg install. Is this the flag you were referring to? I'll have to try it. It skips documentation rendering during setup. That would help.
Yes that's the flag.
Is there anything a package author has to do to make their package compatible with binary and binary lib flags? Are the only compatible packages those built in the built- package catalog?
The best way to get it is raco pkg config catalogs. Note that many commands also accept a --catalog command to override the configured catalogs temporarily.
The key reference for this is 5 Source, Binary, and Built Packages. In brief, package authors write and (if the wish) publish packages in "source" format. The other formats are derived from the "source" package for distribution. The reference gets into the precise details, but the "built" form of a package is basically what you get when you install a "source" package: everything from the "source" package remains, with compiled code and built artifacts added. The "binary" and "binary library" formats are generated by starting from a "built" package and stripping away source files and other unwanted parts, like build-only dependencies, tests, and documentation-generating code. The raco pkg create tool and the pkg/strip library implement the stripping logic.
(I am simplifying the many options a bit. In particular, the compiled code might be in a machine-independent form that requires a fast recompilation step to generate native code.)
This explains why, if you are installing (explicitly or via a catalog) from a package source that provides a package in "source" form[1], you can't jump straight to installing it in "binary" or "binary library" form: the built parts you want haven't been generated yet! At some point, someone has to install the build-only dependencies and build the package. In contrast, when starting from a package source in "built" form, generating any of the other forms is just a matter of stripping some things away, which can be done on the fly during installation.
No.
Racket's package catalogs are extremely lightweight. The essentially just map package names to explicit package sources. While https://pkgs.racket-lang.org is the catalog we talk about most often, the indirection provided by catalogs in fact helps make Racket's package system decentralized. Just by configuring a different catalog, you can use off-line sources, pin versions, or use forked versions of certain packages. Notably, even a default release installation has its first catalog as something like https://download.racket-lang.org/releases/8.14/catalog/, which pins packages that are part of the release process, and a fallback catalog https://planet-compats.racket-lang.org for old PLaneT code.
The built package catalog @spdegabrielle mentioned is generated by the project-run package build service which regularly checks all of the packages in https://pkgs.racket-lang.org for updates, builds them, and runs their test suites. Just as the built documentation is extracted and published at https://docs.racket-lang.org, the built packages themselves are ZIPed up and published in the https://pkg-build.racket-lang.org/server/built/catalog/ catalog.
But there's nothing special about that catalog. You can create built packages yourself, either as a one-off or systematically, and install them in just the same way—you don't even have to generate a catalog structure if you don't want to.
Building documentation can take significant time, especially on less powerful machines. Rather than "packages depend on their docs", though, I'd say that main-distribution depends on docs. Usually, it's the documentation that depends on the implementation, e.g. typed-racket-doc depends on typed-racket-lib (and not the other way around), and the omnibus typed-racket depends on both.
Note that "package source" and "source package" are two distinct concepts! ↩︎