RFE: clarifications in documentation

[djerius]

Hi! There are a few places in the documentation that I think could be improved:

--root

The documentation for --root is

build in root

root isn't defined, so I'm not sure what this means

--prefix

The documentation indicates that this must be used with -f, but not if the alienfile is in the current directory, and is optional when combined with -c. It's not obvious why the prefix should depend upon where the alienfile is located. Shouldn't this always default to the Perl site directories? I find this a little too magical; I can't figure out the logic.

install

I keep expecting af install to actually run the tests as well, but it's really focused on the alienfile, not the distribution. I can't imagine installation without the tests, so this seems a little counter-intuitive; maybe some extra words would help.

[plicease]

Hi! There are a few places in the documentation that I think could be improved:

--root

The documentation for --root is

build in root

root isn't defined, so I'm not sure what this means

I agree this is not well worded or even complete! The --root option is for setting the build root directory. It is usually under a temporary directory that is cleaned up when the tool terminates (the stage directory is a sibling and prefix is as well if you are running under --dry-run) . The reason that you might want to use this option is if you want to keep the build directory around to figure out what went wrong if it fails. For debugging an alienfile it probably makes sense to have an option to keep both the build and stage directories around (and possibly prefix in the case of --dry-run).

--prefix

The documentation indicates that this must be used with -f, but not if the alienfile is in the current directory, and is optional when combined with -c. It's not obvious why the prefix should depend upon where the alienfile is located. Shouldn't this always default to the Perl site directories? I find this a little too magical; I can't figure out the logic.

This option is supposed to work similar to how --prefix does for an autoconf configure script. The reason that you don't need it when you use the -c option is that option is intended to re-download/build the alienized package of an Alien that is already installed, and install the alienized package into the share directory without having to go through the process of installing the full distribution. (this is why the alienfile and patch directories are installed in the share directory).

The --prefix option is also not necessary when the --dry-run option is specified (the --dry-run option just sets the prefix to a temporary directory that gets removed automatically on exit; handy for when you want to see it run but don't want to keep the result).

install

I keep expecting af install to actually run the tests as well, but it's really focused on the alienfile, not the distribution. I can't imagine installation without the tests, so this seems a little counter-intuitive; maybe some extra words would help.

Correct, the AB/alienfile system doesn't have any understanding of the distribution installer (including the Perl .t test files). The code linking these two worlds is Alien::Build::MM and Alien::Build::MB, which are thin wrappers around AB which make it relatively simple to integrate AB into current and future distribution installers. That design decision was informed by the previous ABMB installer which was IMO too closely integrated to Module::Build. Agree that clarifying that in the documentation is probably helpful.

However, I there is also a test phase for the AB system which lets you run the native tests of the alienized package. It looks to me as though this is not currently run by the install or build commands (probably because af originally predates the test phase and I didn't get around to updating it). If so I consider that a bug. We should also have an option to skip the test phase when that gets fixed.

Thank you for raising these confusing parts of the documentation. I will try to reword or clarify some of these points in the documentation, and feel free to further comment here as necessary.

[plicease]

--prefix

The documentation indicates that this must be used with -f, but not if the alienfile is in the current directory, and is optional when combined with -c. It's not obvious why the prefix should depend upon where the alienfile is located. Shouldn't this always default to the Perl site directories? I find this a little too magical; I can't figure out the logic.

Just to further clarify, when using the -c option you can determine the correct share directory because the alien has already been installed in something/something/Alien-foo/. With a bare uninstalled alienfile we don't know what the something/something part or the Alien-foo part, which are determined by the distribution installer.