Added documentation to libdl module

[RichieWilynnton]

Part of #52725

[stevengj]

The current description this PR seems a little bit misleading to me — even without Libdl, you can link Julia code to runtime shared libraries via the ccall intrinsic. The Libdl module provides additional lower-level facilities to manipulate shared libraries: to search for shared libraries in memory or the filesystem, to manually load them (with finer-grained control over the runtime linker options), and to look up library symbols as low-level pointers.

[staticfloat]

The current description this PR seems a little bit misleading to me — even without Libdl, you can link Julia code to runtime shared libraries via the ccall intrinsic.

I think that's a bit of a distinction without a difference; ccall itself loads Libdl and uses the code in it:

julia/src/runtime_ccall.cpp

Lines 75 to 78 in b4d857b

	else if (jl_libdl_dlopen_func != NULL) {
	// Call `dlopen(lib_val)`; this is the correct path for the `LazyLibrary` case,
	// but it also takes any other value, and so we define `dlopen(x::Any) = throw(TypeError(...))`.
	lib_ptr = jl_unbox_voidpointer(jl_apply_generic(jl_libdl_dlopen_func, &lib_val, 1));

[stevengj]

I think that's a bit of a distinction without a difference; ccall itself loads Libdl and uses the code in it:

Good point, but in principle that could change in the future, being an internal implementation detail. My point is that we don't want to imply that ordinary users need to import Libdl in order to call runtime shared libraries.

[RichieWilynnton]

Then shall I reference ccall itself in this documentation?

[RichieWilynnton]

The Libdl module in Julia provides specialized and lower-level facilities for dynamic linking with shared libraries. While Julia
inherently supports linking to runtime shared libraries through the ccall intrinsic, Libdl extends this capability by offering additional, more
granular control. It enables users to search for shared libraries both in memory and the filesystem, manually load them with specific runtime linker options, and look up
library symbols as low-level pointers.

Maybe something like this?

[staticfloat]

Sure, that sounds good to me.

[stevengj]

Now that #52723 is merged, you'll need to update

julia/stdlib/Libdl/test/runtests.jl

Lines 333 to 337 in f286d44

	@testset "Docstrings" begin
	undoc = Docs.undocumented_names(Libdl)
	@test_broken isempty(undoc)
	@test undoc == [:Libdl]
	end

to

@testset "Docstrings" begin
    @test isempty(Docs.undocumented_names(Libdl))
end

[stevengj]

Looks like you had a merge problem, and a whole bunch of unrelated commits are now included in this PR. 😢

[fingolfin]

Can one get a preview of the documentation from CI, or do I need to checkout this branch locally to verify it builds the manual correctly with the recent change to use a @docs block?

[inkydragon]

get a preview of the documentation from CI

We need this #45744 and then upload the generated HTML

[vtjnash]

It looks like doctest is supposed to give you a download link, but fails due to:

2024-02-06 23:31:40 EST	┌ Info: Unable to deploy the documentation: invalid GIT_VERSION_INFO
2024-02-06 23:31:41 EST	│ GIT_VERSION_INFO.tagged_commit: false
2024-02-06 23:31:41 EST	└ GIT_VERSION_INFO.branch: RichieWilynnton:libdlDoc
2024-02-06 23:31:41 EST	Build & deploy of docs finished.
2024-02-06 23:31:41 EST	Compress and upload HTML docs
2024-02-06 23:31:41 EST	2024-02-07 04:31:41 INFO   File not found: julia-f6e0554e38-htmldocs.tar.gz
2024-02-06 23:31:41 EST	2024-02-07 04:31:41 INFO   No files matched paths: julia-f6e0554e38-htmldocs.tar.gz