Open djerius opened 2 years ago
Hi! There are a few places in the documentation that I think could be improved:
--root
The documentation for
--root
isbuild 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 thealienfile
is in the current directory, and is optional when combined with-c
. It's not obvious why the prefix should depend upon where thealienfile
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 thealienfile
, 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.
--prefix
The documentation indicates that this must be used with
-f
, but not if thealienfile
is in the current directory, and is optional when combined with-c
. It's not obvious why the prefix should depend upon where thealienfile
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.
Hi! There are a few places in the documentation that I think could be improved:
--root
The documentation for
--root
isroot
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 thealienfile
is in the current directory, and is optional when combined with-c
. It's not obvious why the prefix should depend upon where thealienfile
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 thealienfile
, not the distribution. I can't imagine installation without the tests, so this seems a little counter-intuitive; maybe some extra words would help.