-
-
Notifications
You must be signed in to change notification settings - Fork 13.5k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add a meta.instructions
field
#267284
Comments
I think that a fair number of use cases for this should just be other options in the module to enable it instead of telling them to go and do something else, that just feels against the ideas of making it declarative. |
What do you mean by other options in the module? My recommendation would be to target the package directly, not the module (a module might not even exist for this package). Then, I agree that the instructions should not be too large… yet I still believe that it would be useful for several reasons. First, nixpkgs wants the wiki to be as small as possible, and recommends that all documentation should be moved to the manual and removed from the wiki (I don't really agree with this policy, as Arch managed to show that a wiki can be extremely complete and more helpful than a manual… but it is another topic). But adding an entry in the manual has two issues:
Also, printing the instructions when installing the software is useful to explain the user why they are doing something that is unlikely to work, and what they should do instead to get it working (personally, my first reflex when installing a software is to… install it, as it is what anyone would do on a standard distribution, not trying to search in the manual if there is something written about it). So at least adding in the meta a link to the documentation in the manual would be a first step towards discoverability of documentation, if there is a clear policy saying that any package that uses udev should get a new entry in the manual. Also, I don't quite agree with comment in a source-code is of no use to a user since users are not expecting to read the source code. |
When is a program installed for the first time? The first time a store path for it is realized? |
Ahah, that's a good question. So first, it might be a good idea to define different levels of verbosity (some people might want to disable all together these instructions), e.g. based on some environment variables/command flags. Since I’m not aware of all the internals of nix, I might also not be the best one to give the best answer here. So the first answer might be "whatever is easier to implement". Then, to go into more details, the problem of using the creation of a store path is that it is dependent on garbage collection (or maybe "realized" means something different for you than created? I’m not so sure about the actual terms), and if user A already installed the package, user B might not get the info (ok, this is maybe not so important after all). But if nix provides a way to check the list of "reachable" store paths (like "in the path"), then one might just be able to do a diff of the reachable store paths before and after running the command, and print the appropriate warning messages… One can also only make it work for imperative commands like |
To "realize a store path" means to either fetch it from a substituter (cache.nixos.org) or build it (Nix reference).
Indeed it is. If the user collects garbage between nix-shell runs, the same package would be installed "for the first time" again.
I suspect most NixOS installations are effectively single-user. Or at least the NixOS installations where this proposed feature would be useful.
That and |
I also agree that searching the manual isn't the best, but more often then not wikis fall behind and are hard to maintain, the arch wiki being one of them that do work well. Yet I am not sure this is the correct solution. This can be useful if limited to something like adding to udev, but udev is only one of the few options things that would be an instruction. The issue is that you would be maintaining not just a manual that gives this information, but it would also be in the code. Anytime you state something twice, there will be times when one of them is out of sync, and that is one of the reasons for not wanting to maintain a wiki as well as a manual. I don't think that it is really an issue with needing more data on the package, as the manual has the information (or atleast should), but maybe adding manual links or snips to the nixpkgs search when you click on a package, as that has the same effect you are looking for while not adding multiple sources of information. It is not an issue of lack of information (as it should be int he manual), but of lack of convenience which I think is the problem. I could not think of other cases for instructions that would be useful, and should not be in the manual (tell me if you can think of any). |
Right now (as far as I know), there is no way to properly document the instructions to follow in order to get started with a package. These instructions might be arbitrary, but the main application I have in mind concern stuff to add in
configuration.nix
(or equivalent command for non-NixOs devices) to allow the program to run smoothly, or the instructions to follow to get started (for instance, if you install a driver, you might need to start a program to get the driver running).Level 1
The simpler thing to implement could be to add a field
meta.instructions
containing arbitrary instructions. For instance when installing a driver, one often needs to also add the package toservices.udev.packages
so that udev is properly configured. So I would love to document a driver using something like:This information should be displayed when installing a program for the first time, and this
instructions
message should also be displayed in https://search.nixos.org.Level 2
Then, it could also be nice to add more computer-parsable fields (but this needs more time to think about what is needed and what is not), to help the system to automatically flag a warning message if the user improperly configured a program. For instance, it could be interesting to add a field like:
in order to print a warning message if the program is installed without being added in
udev
. One could also add some fields pointing to the nix documentation, like:to help the user getting started, or possibly add some instructions to say that the program should be used inside a module:
While the exact set of meta-attribute to provide might require a bit of time to choose appropriately, should we agree that
instructions
could be used for generic human-readable instructions, and start to print them at install time and in search.nixos.org/?The text was updated successfully, but these errors were encountered: