I’ve been reading through the manual and looking through the codebase to better understand how OCaml’s language is architectured. There is a part of the manual I’d like to better understand:
The Obj module is not listed on the Standard Library page, however it is listed on the “Module Stdlib” page.
Looking through the document generator, “Obj” is not listed on the stdlib-blurb.etex page.
Is there a reason for this?
Normally I would submit a pull request with an update to “stdlib-blurb.etex”, but I suspect there may be a reason for it.
Arguably, the Obj module is not part of the OCaml language standard library but rather part of a partially defined introspection library for the OCaml compiler’s implementation of the language.
If I understand correctly, there are technical and practical tradeoffs being weighed. I’m extrapolating from your reply and other discussions I’ve read, so please let me know if I’m off in my reasoning:
At a technical level the stdlib directory contains several directories that are not exposed to the user such as camlInternal*.ml. These are arguably not considered part of the OCaml Standard Library because they handle low-level interfaces that are inherently unsafe.
On the other hand, the Obj module is exposed in the Stdlib module because it has practical utility for developers even though its use is discouraged due to its lack of safety.
I may have an extreme position, so prepare to not take this too seriously but: I think that the most accurate frame of mind for thinking about the Obj module is that its documentation is the source of the compiler and runtime system. Unless one reads and is comfortable with the source, and is prepared to check the difference between versions, they should avoid using Obj. From that perspective, the source of Obj is there with the rest, so it is documented…
That makes sense and I don’t take your comment as particularly extreme. There be dragons for sure.
I’m going through the source to gain a better understanding of OCaml’s language and library design for that purpose, and without an academic background the reason for Obj being in Stdlib and not in the Standard Library documentation eluded me.
The Obj is no more exposed than the camlinternal{Mod,Oo,Lazy} modules. All of those modules are essentially part of the OCaml runtime written in OCaml and not really part of the standard library. But they are interdependent with the standard library, and it would require a good amount of effort to split them in a separate library. Moreover, the features needed to do the split properly on the package and build system side are quite recent (at least compared to the standard library).
In the case of camlinternal{Format, FormatBasics}, I would argue those are part of the standard library, with however a quite rough API and no backward compatibility guarantee for direct users.
Going through the sources of the compiler is a bad way to learn OCaml library design: the compiler is older than most of the library best practices and stands upstream of most tools that make those “best practices” possible.