I have a Perl application which is used in two contexts: It can be used as a diagnostic tool which displays information about a system, or as a testing tool which sends Modbus commands to that system. The problem I have is that allowing the user to send commands to the system in a diagnostic context is a potential safety risk, so I want to create two executables: A testing version that includes the Modbus module and a diagnostic one that does not.
My current solution is to include the Modbus module like this:
BEGIN { eval { require Modbus; }; Modbus->import; }
This only includes the Modbus module if I use the option -M Modbus while building the .exe with PAR Packager. The issue with this approach is that it fails unless this is the only place where Modbus is imported. So if another developer who isn't aware of this risk comes along, it only takes one require statement to bypass this fix.
Is there a way for me to prevent a specific module from being included in the executable unless I explicitly want it to be (either with the -M option or some other method)? I've been trying to figure something out with Devel::Hide, but haven't had much luck. All the solutions I've found so far fail the "other developer who doesn't know about this" test.
I'm using Strawberry Perl 5.20.3.3, but I can upgrade if necessary.
When I've done this sort of thing, I've created a small module that is included if it is present and not included if it is not:
eval { require MaybeItsThere }
In my Makefile (or whatever build system you want), I have targets for development and production builds. One of the subtasks for the dev build creates that MaybeItsThere file. It can also set whatever it needs for PERL5LIB and so on such that only the dev build can load it.
However, as you say, the enterprising developer can quickly find out what they need to do to get the features they want.
Having read through your comments, it seems that you're not going to be able to enforce correct usage. (You gave examples how the module has already been misused by people sidestepping your build process.) I would suggest an alternative approach.
Document the problem at that place where someone would find a workaround.
In other words, if some other developers is going to look at the code or at the build to see the name of the missing module, let them see a warning about the dangers right there. Put a comment block explaining why the Modbus module should only be used when diagnostics are disabled or filtered. Make the build's failure put a warning right there at the same place as the name of the missing module; use a die "Modbus should not be used when user interaction is enabled."; or something similar to convey the message in the same place where the other developer would be looking for the solution.
Ultimately, you can't force someone to use your build tools, but you can try to educate them while they're trying to work around you, instead of documenting the problem somewhere else that they might not see.
Related
This is a canonical question for the above problem, inspired by this answer and this question. Please edit and improve it.
I'm trying to install a module from CPAN, using the CPAN/cpanm/CPANPLUS client. However, I'm getting build or test errors when I try to install it. What should I do?
Does it build at all?
The first thing to consider is, is your module building at all? If it isn't building, you should check for existing bug reports, file one if necessary, and perhaps try to fix the issue yourself (steps 2 and 3b/3c below).
If it builds but tests fail, follow these steps.
1. Determine if the test is valid
The purpose of these tests is to test. If there's a problem, you need to know about it, and not sweep it under the rug. Resolve the issue one way or another. Is there a problem with something on your system, or is this a problem with the test itself. If this is a problem with the test, does it still affect you? If this is a system problem, is this something you might run into? For example, let's say there's a test that checks for connectivity between your system and a Windows system. If you don't connect to Windows systems, maybe that particular test doesn't apply to you.
2. Check MetaCPAN for bug reports
If you have a test failure, go to the MetaCPAN webpage for that module, and check the left hand side for RT issues to see if someone else is getting the same errors. If no one is, you should open an RT ticket, or a ticket in the project's bug tracker of choice.
There may be patches available from other users. If the patches make sense to you, you can try applying them and rerunning the tests.
You can also click on the Testers link on MetaCPAN. The QA testers webpage will show you the various Perl versions, module versions, platforms, and show you which tests are failing on particular platforms on which versions. You might need to install an alternative version of the module.
At this point, there are a few paths you can take.
3a. Force the installation
Only once you've determined that the failed test doesn't necessarily apply to you, do a force install:
cpan> force install Date::Calc
This will run through the entire install, except that it will skip all testing. (Or maybe it still tests, but doesn't fail if a test fails.). The module will still fail on compiler errors, or if something can't get written to your system. It merely ignores tests.
This should be the last desperate attempt to get something installed. You've should have already resolved that the failed tests are bugs or not meaningful for you. Or, someone is standing beside you with a gun to your head saying, "Install that module, or I'll pull the trigger!".
3b. Find an alternative module
Or, you can decide to use another module. CPAN is full of various approaches to problems (TMTOWTDI), so there many be one there that does what you want.
3c. Write some code
Or, you can analyze why the test is failing and either fix the module or the code. Bug reports with potential patches are often appreciated by busy module authors. If it doesn't look like the author wants to take your fix, you can always fork an existing module, or write a fresh one.
If the author has gone MIA, you may be able to adopt the module and maintain it yourself. The general process for adopting a module is first to try to submit code to the author that fixes it, and then wait a while, maybe a month, for the author to pick it up. If there's no response, try alternative means of contact, email, Google+, whatever you can find. After that, you can go on Perl IRC chats, mailing lists, etc, looking for someone who knows where the author might be. If none of that works after a few months, the PAUSE admins can investigate and turn the module over to you.
This is based on this excellent answer
I am writing a perl program that I want to share with others, eventually via cpan. it's getting to the point where I should start thinking about this on a bigger scale.
a decade ago, I used the h2xs package maker once. is this still the most recommended way to get started? there used to be a couple of alternatives. because I am starting from scratch with very little recollection, anything simple will do at this point.
I need to read a few long text files (not perl modules) for configuration. where do I put them and how do I access them, no matter where the module is installed? (FindBin?) _DATA_ is inconvenient.
I need to provide an executable (linux and osx). can putting an executable into the user's path be part of the module installation? (how?)
I would like to be able to continue developing it, run it for test purposes, have a new version, repack it, and reupload it easily.
before uploading to cpan, can I share a cpan bundle for easy local installation to downloaders and testers?
# cpan < mybundle.cpanbundle
advice appreciated.
regards,
/iaw
If anything I say conflicts with Andy Lester, listen to him instead. He knows more than I ever will.
Module::Starter is a good, simple way to generate module scaffolding. My take is it's been the default for this sort of thing for a few years now.
For configuration/support files, I think you probably want File::ShareDir. Might be worth considering Data::Section if it's just a matter of needing multiple __DATA__ sections though.
You can certainly put scripts in the bin subdirectory of your distribution, the build tool will put it in the right place at install time.
A build tool will take care of the work-flow you describe.
Bundles are something different. You make a distribution and share the tarball/archive.
If you set up PERL5LIB appropriately, then repeat make test, make install, make dist to your heart's content. For development/sharing purposes a lot of projects do their work on github or similar - makes it easy to share. They have private accounts for business purposes too. Very useful if you want to rewind and see where/when a problem was introduced.
If you get a copy of cpanm (simple to install, fairly lightweight) then it can install from a tar.gz file or even direct from a git repository. You can also tell it to install to a local dir (local::lib compatible - another utility that's very useful).
Hopefully that's reasonably up-to-date as of 2014. You may see Dist::Zilla mentioned for module development. My understanding is that it's most useful for those with a large family of CPAN distributions to manage. Oh - if you (or other readers) aren't aware of them, do check out autodie and Try::Tiny around errors and exceptions, Moose (for a full-featured object-oriented framework) and Moo (for a smaller lightweight version).
I think that advice is all reasonably non-controversial. I find cpanm to be much more pleasant than the "full" cpan client, and Moo seems pretty popular nowadays too.
Take a look at Module::Starter and its much more capable (and complex) successor Dist::Zilla.
Whatever you do, don't use h2xs. Module::Starter was created specifically because h2xs was such an inappropriate tool for creating distributions.
I have a couple of Dist::Zilla plugins that I wrote when I was very new to Moose and to Dist::Zilla both, and I'm currently trying to update them to make them a bit more robust, and less error-prone.
One thing I would like to do is to give the user feedback if I detect that they have given me contradictory or impossible instructions. Things like:
[ MyPlugin ]
include = all
exclude = all
Dist::Zilla does appear to have an (undocumented) internal logging system which I originally hooked into when I wrote my plugins, but which no longer seems to work (probably due to internal changes). So, how should I give the user feedback these days?
(Meant to put this in the comment but hit length limit).
Caveat: I've only written a couple of small dzil plugins myself, and am not very familiar with its internals.
dzil uses Log::Dispatchouli, which is also written by rjbs. Log::Dispatchouli is used by several other projects (including projects started by people other than rjbs), so it's not exactly an internal dzil logging system.
From what I understand, Log::Dispatchouli only has two logging levels, normal and debug. Debug logs are not normally seen in output; you have to enable debugging first. Normal (and debug) logs can be muted if you enable muting.
To enable debugging in dzil, add a -v command-line switch. This does not seem to be documented in 'dzil help' nor 'dzil help COMMAND'. But rjbs blogged about it.
Now to produce logs inside the dzil plugins, you just call $self->log(...) or $self->log_debug(...). The second one will be seen only if user passes -v option.
I downloaded some module from CPAN and added to it extra functionality. Could I post the newest module on the CPAN? If yes, how should I do this? Is it possible at all? Should I contact the person who wrote the original module? Could someone help about the procedure to update this specific module?
You won't be able to upload and index a module as the same name unless you are a co-maintainer. Uploading it as a different name isn't very productive for the community as there are now two (or more) slightly different versions.
Contact the author
Submit your patches to the RT queue for the module (or the issue tracker it specifies in its docs)
If it's on Github, fork the project, make the change, and submit a pull request
If the author is unresponsive (which means no response, not a negative response), we have ways to pass on maintainership of abandoned modules. We take this process very slowly because we want to give the original author or current maintainer every chance to respond. Some people might be swamped at work, on holiday, and so on. However, most situations turn out very well.
You can upload anything that you like to PAUSE, but if you are not some sort of maintainer, PAUSE won't index it. It will still show up in your CPAN account and people can still download it through the CPAN website, but the CPAN clients won't see it (since they work according to the index). Some of the search sites will show it as an "Unauthorized release".
It would be unhelpful to blindly upload a module that you've added functionality to under the same name as the module that it's based on (it happens sometimes and often creates a mess). But you do have options that would be helpful:
First, you could contact the module's author or maintainer, emailing a diff or patch showing what you would like to see added. Be sure to supply relevant documentation as well, and explain your rationale.
It could be that the module author will accept the patch and apply it to an update of the module himself. Or it could be that by way of prevention of creeping featurism, the author/maintainer rejects the upgraded functionality, and that leads you to a second option.
The second option is to get your own PAUSE account, and either subclass or otherwise extend the module. But be sure to give it your own new module name, full documentation, and probably an explanation within the documentation that this is an extension of xyz module with the following additional functionality... If you're extending Math::BigInt, you might call it Math::BigInt::Frobcinate (just an example).
When you do attempt to make contact with the module author, please be patient. Sometimes it takes awhile to let things run their proper course.
I recommend that you attempt to contact the author.
Additionally, you can upload your module changes as a patch via rt.cpan.org; there should be a link from the module's website on CPAN. Refer to the CPAN FAQ: How do I report/fix a bug in a module/script? This tracking system is used for requests such as yours, not just for reporting bugs.
How can someone distribute native (non-"compiled/perl2exe/...") Perl scripts without forcing users to be aware of the custom (non-CPAN) modules that the scripts needs in order to run?
The problem is users will inevitably copy the script somewhere else on the system and take the script out of its native environment and then it can no longer find the modules it needs to run.
I've sometimes settled with just copying the module into the actual script, but I'd prefer a cleaner solution.
Update: I better clarify. I distribute a bunch of scripts which happen to use similar modules in the backend. The users understand how to run Perl scripts, but rather than relying on telling them "no don't move the script" I'd prefer to simply allow them to move the files. The path of least resistence.
The right way is to tell them "Don't do that!" I would hope that they wouldn't expect to move an exe file and have the program continue to work. This is no different.
That said, there are a couple of alternatives. One is replacing the script with a wrapper (e.g. pl2bat) that knows the full path to the real script. Another is to use PAR, but that would require PAR and/or parl (from PAR::Packer) to be installed.
If a script that your prepared for a client needs "custom" modules, simply pack your modules as if you were trying to upload them to cpan. Then give the package to the client and he can use the cpan utility to install the script and the modules.
Distribute an installer along with the script. The installer will need to be run with root privileges and it will put the custom modules into the standard system location (/usr/local/lib/perl5/site_perl or whatever).
I've not tried this, but Module::Install looks helpful in this regard. It's described as a:
Standalone, extensible Perl module installer
As a variant of the "put your modules all in one place and make your applications aware of it" that will even work across multiple computers and networks, maybe you should check out PAR::Repository and respectively PAR::Repository::Client. You'd just provide a single binary client executable that connects to the repository (via file system or https) and executes any of the arbitrary number of programs (using an arbitrary set of modules) provided by the repository that the user asks for.
If there are many users, this also has a benefit for maintenance: Simply update the software provided by the repository and the users will start using the updated code for their system when they next start the programs.
It would be really nice if you could just use a NeXTSTEP style application bundle. Since you probably aren't developing for a platform that uses bundles, you'll have to make do.
Put all support files in a known location, and point your executable at those files for access to settings and libraries. The easiest way to do this is with a simple installer.
For example, with an app called foo, put all your required files in /opt/xlyd_apps/foo, libraries in /opt/xlyd_apps/foo/lib, configuration in/opt/xlyd_apps/foo/etc, and so on. Put the executable in /opt/xlyd_apps/foo/bin.
The important thing is to make sure the executable knows to look in /opt/xlyd_apps/foo for all its goodies, so if the customer/client move the foo script to a new location the install still works.
So, while you can't make the whole thing self contained and relocatable, you have made the actual calling script relocatable.
I've actually come up with my own solution, and I'm kind of curious what kind of reception it will have.
I've written a script that reads a perl script and looks for "use/require" statements. Upon finding them it checks if the module is part of the standard library (looks at module path for /perl5/\d+.\d+[\d.]+/) and then rewrites the use/require line in two different ways depending on usage.
If require is found:
{
... inline the entire module here...
}
If use is found:
BEGIN {
... inline the entire module here...
}
If use has imports, immediately follow above with:
BEGIN { import Module ...imports seen... }
I understand this doesn't work with modules that use XS, but I was fine with this. Mostly I need to support only pure perl modules.