Open nrdvana opened 1 year ago
I'm proposing a fairly large restructuring here, but this is what I envision would be the most helpful document to consult when I'm trying to remember how to write an alien module:
... an alienfile ...
... a Installer ...
... a package ...
Example dir list
Note about wanting static libs
Other general points about plugins etc.
Here's an example alienfile
... the probe phase returns 'system' or 'share' ...
... don't perform work in this block because it can be skipped with env variables ...
The shorthand notation probe [...]
means ...
The longhand probe sub { ... }
should take these steps and do these things.
...You can find this information in these install variables....
... you need to fetch the code ... extract the code to (directory) ...
... build it using automake etc ...
... gather the details to be made available at runtime ...
There might be extra deps that building needs that sys doesn't. You can add 'requires' directives etc.
... use these common tools to get your code ... (start_url, download, extract)
Mention various common plugins.
warnings/advice about choosing versions
At the end, the files need to be extracted at this location etc. so the build plugins can find them.
Apply patches to the files like this.
You start with this var pointing to the extracted sources, you need to populate that directory, etc.
... common patterns of automake or cmake ...
reference all the notations usable in 'build' rules. Maybe link to external docs.
How to expose 'configure' options to the end user? Recommendations, tools?
If you need to modify the files before they get installed, do like this.
This phase can either be inside the 'Share' or 'sys' sections or at root scope of the alienfile if it applies to both modes.
Common patterns. pkg-info. make sure these vars are set. relation between libs
, libs_static
, libs_dynamic
, etc.
current section "nonstandard configuration"
give a brief summary of all the useful plugins and which steps they replace. Link to plugin for futher details.
Big example
Link
Small example
Mention extra methods for exporting custom things
I do really like this structure, when I get time I will try and rewrite some of the documentation appropriately.
I wrote an alien module for FluentBit, and its make process generates a broken fluent-bit.h. While I'm waiting to get this fixed upstream, I needed to just inject my own header into the staging directory after the "make install" runs. I had a difficult time with the documentation to figure out how to do this.
The first point of confusion (reading the Author Manual) was the example of
which would indicate that the build process is actually installing to
->install_prop->{prefix}
, but this is not the case. (I was using cmake, but just assumed it would follow the same pattern as automake)The second confusion was the example where it shows
which would also indicate
->install_prop->{prefix}
was pointing to the staging directory at some stage of the build. My testing (again, with the cmake plugin) seems to indicate that the {prefix} variables always point to the final installation path, which doesn't exist at the time the module is first installed.The
->{stage}
variable isn't mentioned in the entire Author Documentation, but when I found that I assumed it was what I was looking for, but it seems it doesn't get populated until some time after the 'Gather' stage.I finally dug into the source for ::Plugin::Gather::IsolateDynamic and found
which seems to be what I needed.
My resulting solution to my problem is Alien::FluentBit alienfile
Proposed Changes
For the Author, I think it would be helpful to structure the documentation per each each phase of the alienfile, describing the initial state of things, what the directives are supposed to accomplish, and the resulting state that should be achieved.
I get the idea that DESTDIR is an implementation detail that complicated the original clean plan for staging the builds? If so, there should at least be some wrapper around that so that alien authors can find the location of the directory that 'make install' just wrote to so that they can perform final adjustments to those files during the 'build' phase. Ideally it would be the same code for automake and cmake, regardless of where they are actually writing their directories. It could be something as simple as running the above code and storing it in
->install_prop->{make_install_dir}
.