|
Re^2: let Makefile.PL to do the Readme file for me -- new target?
by Discipulus (Canon) on Jan 19, 2021 at 18:04 UTC
|
Dont feel irritated LanX, take it easy :)
Yesterday I asked in the chatterbox:
> can I use my Makefile.pl to autogenerate the Readme based on POD of the main module?
and you answered with a nice trick about doing it in a pseudo test file. Nothing bad on both part. I'm investigating the matter.
Your solution is good in the sense it updates the Readme anytime you run prove -l -v so the github/gitlab Readme is always up to date. It is not clean in the sense that tests are for testing.
Using the Makefile.pl on the other hand, will update the Readme only during the make phase so github/gitlab Readme will be always out of date and another git push is needed after make postamble is run.
PS I always look at What are the files in a CPAN distribution? and it says:
> MetaCPAN will display the following documentation files on a release's front page if they exist: ./README / ./README.md / ./README.pod
L*
There are no rules, there are no thumbs..
Reinvent the wheel, then learn The Wheel; may be one day you reinvent one of THE WHEELS.
| [reply]
[d/l]
[select] |
|
|
I'm easy, just curious.
> It is not clean in the sense that tests are for testing.
Well include a check if README is up to date at the end and you got a "clean test". ;-)
You might also want to ensure that these kind of "tests" are only run when authoring on your machine.
| [reply] |
|
|
| [reply] |
Re^2: let Makefile.PL to do the Readme file for me -- new target?
by stevieb (Canon) on Jan 19, 2021 at 17:38 UTC
|
"But AFAIK is makefile.pl only relevant when installing from CPAN on the client side."
Not necessarily if it's part of the make dist routine. The README will get created inside of the repo, and if the file is already added to git, it'll show up in Github because it's generated prior to creating the tarball. It'll also have to be included in the MANIFEST.
At least that's what I envisioned the desire to be.
| [reply]
[d/l] |
|
|
| [reply]
[d/l]
[select] |
|
|
No, the rule can be added to any make targets you want through the power of Makefile dependencies.
| [reply] |
Re^2: let Makefile.PL to do the Readme file for me -- new target?
by bliako (Monsignor) on Jan 20, 2021 at 10:59 UTC
|
But AFAIK is makefile.pl only relevant when installing from CPAN on the client side.
AFAI-do, yes-and-no.
Makefile is my friend and assistant: it runs for me tests, benchmarks and, like Discipulus wants to do: creates a readme from pod in various formats. This is in the tradition of Autotools/automake. In which just one last target (of many): make dist will create a tarball of the project for distributing it to end-users with all dev-related files filtered out. (btw I usually add make push-git to spare me the grory task of interacting with that abomination called git.)
That means that, in this style, there are 2 makefiles, one for the developer and one for the end-user. The latter created automatically, so there is no need to maintain 2 makefiles actually. However, please correct me if I am wrong, but this is not the case with ExtUtils::MakeMaker which, as LanX points out, assumes or imposes that Makefile.PL is for the end-users' benefit only. Assuming that only *they* are the only lazy (or dumb or forgetfull) link in the project's development chain!
Now, if there was a competition for the most lazy developer I would lose it because I would be too busy crafting an automated system for submitting my entry with just make submit && make win ...
So, I claim back my right to laziness and chose to inflate Makefile.PL with targets that the end user will never want to use - (caveat: that entails the danger of exposing sensitive urls/passwords). Because I want to have a functional, development-stage, Makefile fit for my lazy lifestyle.
10 minutes EDIT: See Re: let Makefile.PL to do the Readme file for me -- new target? for an alternative which involves other tools.
bw, bliako | [reply]
[d/l]
[select] |
|
|
Perhaps I am misunderstanding you, but what you have said sounds like a contradiction to me.
You have mentioned the author-only targets (such as make dist) and these can be auto-generated by ExtUtils::MakeMaker but you subsequently say that this module "assumes or imposes that Makefile.PL is for the end-users' benefit only". That is clearly not the case.
| [reply]
[d/l] |
|
|
Yes, my make dist refered to Autotools' which does creates an end-user, client-side, Makefile. Automatically.
But since you mentioned make dist in the context of ExtUtils::MakeMaker, my question is whether it creates a new Makefile.PL tailored-made for the client-side. AFAIK it just copies verbatim the original Makefile.PL into a dist tarball. Which is not the functionality Autotools provides and I referred to. *Edit*: So nothing contradictory.
| [reply]
[d/l]
[select] |
|
|
|
|
|
|
Hello hippo,
maybe I'm confused by the context of this part of the thread (where Autottols has another makefile) but you said:
> author-only targets (such as make dist)
I supposed too this to be true but I'm very disappointed (not by you ;) to discover is not. I'm actually playing with my Makefile.PL to add functionalities only during the author phase (distinct from user phase) and to do this I have overridden dist target (also tried with distdir one).
Actually I have this pattern:
package MY; # so that "SUPER" works right
sub dist {
# SAVE WHAT RECEIVED BY THE ORIGINAL dist
my $inherited = $_[0]->SUPER::dist(@_);
my $ask_for_git = main::prompt ("*** CUSTOM *** Do you want to spe
+cify a git repository?:");
if ( $ask_for_git =~ /^y/i ){
...
But for what I see the dist target is reached by the cpan client too:
io@COMP:c>cpan .
You are visiting the local directory
'.'
without lock, take care that concurrent processes do not do likewise
+.
CPAN: CPAN::SQLite loaded ok (v0.211)
Database was generated on Sun, 24 Jan 2021 14:03:26 GMT
You are visiting the local directory
'c:/ulisse/games-dice-roller-LazyMakefileOK/Games-Dice-Roller-0.04/G
+ames-Dice-Roller-0.04/.'
without lock, take care that concurrent processes do not do likewise
+.
c:/ulisse/games-dice-roller-LazyMakefileOK/Games-Dice-Roller-0.04/Ga
+mes-Dice-Roller-0.04/.
Has already been unwrapped into directory c:/ulisse/games-dice-rolle
+r-LazyMakefileOK/Games-Dice-Roller-0.04/Games-Dice
-Roller-0.04/.
CPAN: CPAN::Meta::Requirements loaded ok (v2.140)
CPAN: Parse::CPAN::Meta loaded ok (v2.150010)
CPAN: CPAN::Meta loaded ok (v2.150010)
CPAN: Module::CoreList loaded ok (v5.20170114_24)
Configuring c:/ulisse/games-dice-roller-LazyMakefileOK/Games-Dice-Roll
+er-0.04/Games-Dice-Roller-0.04/. with Makefile.PL
CPAN: CPAN::Reporter loaded ok (v1.2018)
Reporting via CPAN::Reporter is disabled for local directories
Name "main::meta_merge_args" used only once: possible typo at Makefile
+.PL line 38.
Checking if your kit is complete...
Warning: the following files are missing in your kit:
debug.log
MANIFEST.bak
pm_to_blib
Please inform the author.
*** CUSTOM *** Do you want to specify a git repository?:
...
C:\ulisse\perl5.24-64b\c\bin\dmake.exe install UNINST=1 -- OK
I'd really prefere to use an already present target because of laziness: if I remember to make my_custom_target_do_readme I can also remember to make the readme by hand, no? :)
Both dist and distdir are under ExtUtils::MakeMaker#Distribution-Support where is stated:
> For authors of extensions MakeMaker provides several Makefile targets...
Maybe the cpan client broke the rule? As side note cpan client has no verbose output and I did not found which steps it does to install a module.
Thanks for reading.
L*
There are no rules, there are no thumbs..
Reinvent the wheel, then learn The Wheel; may be one day you reinvent one of THE WHEELS.
| [reply]
[d/l]
[select] |
Re^2: let Makefile.PL to do the Readme file for me -- new target?
by Anonymous Monk on Jan 19, 2021 at 19:51 UTC
|
When ExtUtils::MakeMaker is your authoring tool, you want to hook into it to perform any authoring task, which this would be one. Not necessarily related to make dist, but in the same vein. Personally, I prefer real authoring tools but for people who really like Makefile this is fine. | [reply] |
|
|
| [reply] |
|
|
No, Module::Starter is a scaffolding tool. ExtUtils::MakeMaker is an install and authoring tool. Generating files in the source tree or the distribution build is one function of authoring tools.
| [reply] |
