> Because it's not "split between two files": the details in debhelper(7) I see, fair point, count me as one of the users who could use this information in DH_INSTALL(1) though. I don't think any common user needs to become an expert on the internals of debhelper to get a simple package going, so I'd advocate for pitfalls be listed on all man pages. It took me a while to understand all these tools are even linked.
> How is this contradicting? It's one possible use of the "executable config file" feature. Oh, I understand now. " #!/usr/bin/dh-exec" makes it be processed by some interpreter other than bash, I didn't understand why it would have non-bash syntax. You're right, it's not contradicting. > And what of the documentation in debhelper(7) is not clear enough of how the executable install scripts should "look"? You're right, I meant output. It doesn't say how the install mechanism works, I don't know what sort of commands I'd need to use to manually copy files to my Debian package and how to instruct "dpkg" where to install it. I don't see any reference for further reading. > As a matter of fact, it's often a detail considered hard to imagine, because nobody creates executable files by mistake... Like I said, I'm developing on WSL on a mounted drive and can't get metadata working on it. Of course you might say that having no control over permissions can cause issues on multiple user cases over development and you'd be right, but allowing users to know what they'd done wrong is still important. Working on WSL is quickly becoming common practice, so I wouldn't call it a corner case. I have seen at least two StackOverflow cases that I'm positive were stuck with the exact same problem I had, and didn't have an answer. > If you are hitting issues like this, I recommend you ask for support on the IRC channel #packaging on OFTC Thanks for the advice, I wasn't aware of that channel. I asked on #debian and got nothing. > At which point would you emit said error? Well, the only solution I can think of is outputting a warning whenever an executable fails to parse. > It's not frowned upon, why would it? Because it requires setting a specific warning message to a specific tool, which also makes assumptions on your usage. Like I said I'm all for it, but others might not like the idea of "are you sure you meant for foo.install to be an executable?" appear every time their ".install" file, which they meant to be an executable, doesn't work. I'd like to clarify that the documentation I counted on most was in https://www.debian.org/doc/manuals/maint-guide/dother.en.html#maintscripts . For a layman such as myself, this documentation clearly states that ".install" files are a special config file with its own simple language and nothing more. In fact, while searching the internet, people seemed surprised when they saw ".install" files trying to execute listed files. https://askubuntu.com/questions/982078/install-non-executable-files-with-dh-install/1047319#1047319 So I'd say I'm not the only one confused. In my opinion DH_INSTALL(1), and dother.en.html (being after all part of the official Debian documentation) need to be more clear about the fact ".install" files will be read as executables if possible. Now that I think about it and understanding the " #!/usr/bin/dh-exec" example, I think I have an even better idea: include an example that shows making the file an executable script that uses whatever the default interpreter ".script" files usually use. Surely there is one, right? and it could solve my WSL problem too, by making ".install" files with an executable bit be written with the simple default syntax. On Sun, Jun 17, 2018 at 4:57 PM, Mattia Rizzolo <mat...@debian.org> wrote: > On Sun, Jun 17, 2018 at 04:20:09PM +0300, Nadav Ruskin wrote: > > Thank you for the quick and concise reply. I was looking at DH_INSTALL(1) > > instead. Why is the documentation split between the two files? > > Because it's not "split between two files": the details in debhelper(7) > are about *all* the dh_* commands, not just dh_install. > There is an open bug about having some details like this one shared > between all the dh_* manpages, but the debhelper maintainer of course > wants to avoid having the documentation duplicated amongst dozens of > files. > > > Also, > > looking back at DH_INSTALL(1) I see a line that appears to be > contradicting > > the documentation in debhelper(7): > > > > > dh_install cannot rename files or directories, it can only install them > > > with the names they already have into wherever you want in the package > > > build tree. > > > However, renaming can be achieved by using dh-exec with compatibility > > > level 9 or later. An example debian/ package.install file using dh-exec > > > could look like: > > > #!/usr/bin/dh-exec > > > debian/default.conf => /etc/my-package/start.conf > > > Please remember the following three things: > > > • > > > The package must be using compatibility level 9 or later (see > > > debhelper(7)) > > > • > > > The package will need a build-dependency on dh-exec. > > > • > > > The install file must be marked as executable. > > > > This requires the ".install" file to be both an executable and have a > > simple syntax. Here's another question, is there documentation to how > these > > executable install scripts are supposed to look? I wouldn't know where to > > start. > > How is this contradicting? It's one possible use of the "executable > config file" feature. > > And what of the documentation in debhelper(7) is not clear enough of how > the executable install scripts should "look"? (which is probably the > wrong question, as debhelper obviously doesn't care about their look, > rather their output). > > > In any way, I find the documentation to be lacking. There should be a big > > red flag on setting the ".install" file as an executable. I was not able > to > > find the answer to my woes in online or offline resources for days of > work. > > An error message saying "Are you sure foo.install is meant to be run as > an > > executable"? would be nice, > > At which point would you emit said error? > > If you are hitting issues like this, I recommend you ask for support on > the IRC channel #packaging on OFTC, there you could have had this answer > in few minutes (if you are lucky somebody is online in that moment, > which usually is the case) :) > > > however if such practice is frowned upon a > > notice that is more than a side note in the docs will make a big > > difference. > > It's not frowned upon, why would it? > As a matter of fact, it's often a detail considered hard to imagine, > because nobody creates executable files by mistake... > > -- > regards, > Mattia Rizzolo > > GPG Key: 66AE 2B4A FCCF 3F52 DA18 4D18 4B04 3FCD B944 4540 .''`. > more about me: https://mapreri.org : :' : > Launchpad user: https://launchpad.net/~mapreri `. `'` > Debian QA page: https://qa.debian.org/developer.php?login=mattia `- > -- Regards, Nadav Ruskin
