moved documentation files into documentation directory

[p01arst0rm]

Motivation

Moving the docfiles into the doc directory simplifies packaging when switching to the meson buildsystem. Currently, efforts are stalled due to circular dependencies, which are not legal under the meson dsl.

Context

#3160
NixOS/rfcs#132

[edolstra]

Why is this needed? I don't see the connection with the build system (since files like COPYING and CONTRIBUTING.md aren't touched by the build system).

Also, COPYING is a standard location for the license, not sure about doc/COPYING.

[p01arst0rm]

the files are touched by the install and packaging steps of the build.

[fricklerhandwerk]

I'm all for Meson support, but I'm with @edolstra that moving those "well-known" files would be detrimental to discoverability. Are there different options?

[p01arst0rm]

there are, but they would complicate packaging.

[fricklerhandwerk]

Okay, we'll have to weigh priorities then. @Ericson2314 since you have an eye on Meson developments, what do you think?

[eli-schwartz]

Can you give a quick rundown of the different options or perhaps a pointer to which lines of the proposed meson.build files this would help out with?

[Ericson2314]

Yeah I am not clear why this helps. I would have thought

COPYING = file('COPYING')
subdir(whatever)
```
would work fine.

[p01arst0rm]

Yeah I am not clear why this helps. I would have thought

COPYING = file('COPYING')
subdir(whatever)

would work fine.

it depends on the end goal of the refactoring; whether you want all the subprojects divided up or not, or want to keep it generally as a single project. its not quite clear to me atm which is the goal. my current goal is just to move the doc files used inside the build into the subdirectory instead of /doc to avoid circular dependency (file is generated in /doc a but file a is referenced in nix build, but nix is needed to build the docs. currently nix is a dependency of itself and a goal would be to solve that somewhat)

[eli-schwartz]

If nix is needed to build the docs but the docs are just part of the nix repository and built using the same build system as Nix's own executable, then you simply:

• define a meson build rule for nix
• define a documentation build rule that uses the return value of the first build rule, as the command to build the documentation (this is the nix program, run in the build tree rather than installed)

and all is well.

I am not sure I understand how moving the files around affects that one way or the other -- meson shouldn't care what the filename is, even the filename with its full path, it should only care about which order you define objects in.

The meson DSL doesn't allow you to define a variable on line 5 and use it two lines previously on line 3 -- nor to define a target on line 3, a new variable on line 5, and then on line 7, hotpatch the target on line 3 to have values in its internal struct overwritten with the variable from line 5. That's not really related to what directory a given file is in.

So, I would like to hear more about what practical challenges of the documentation build would be solved by the act of moving the markdown files to a different location.

[p01arst0rm]

absolutely correct :) this doesn't solve problems on its own. its /preparation/ for a full subproject build that was talked about maybe being a goal. at that point, you CAN include variables out of order

libutil= meson.subproject('libutil')

doc_dep = libutil.get_variablr('thing_needed_for_docs')

as you (and i) said it isn't required at all. but it does open up possibilities for neater packaging in the future. as @Ericson2314 said though, there are other options, including leaving doc in a parent project and moving the libs to daughter projects so its not the only option:) meson gives a lot of flexibility, so it really depends how you want to go about things.

as @Ericson2314 said maybe its best to focus on porting efforts before expanding the scope keep it simple silly :)

[Ericson2314]

Yeah sub-projects are supposed to be self-contained in a way we (the Nix authors) haven't really considered yet. I do think that is a separate discussion. If we could symlink the files in to each subproject that needs them, that might be best. I've seen such a thing with repos with multiple libraries packaged up with a language-specific tool before.

[Ericson2314]

(I marked as draft for now, we can come back to later when the initial port is more merged. Also assigned to myself.)

[nixos-discourse]

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2023-04-08-nix-team-meeting-136/42963/1