Re: Writing my first module

[haukex]

1. Do I need to put "use strict; use warnings;" at the top of my module?

Yes, Use strict and warnings applies to modules as well. If you see modules not doing that, then likey they are very old and/or not following best practices (or in some modern cases, they may be useing a module that enables them automatically - one example would be use Mojo::Base -strict;).

2. Should I start the perl module with #!/usr/bin/perl or is it okay to leave this off?

It's usually fine to leave it off. The shebang's primary use is when executing scripts from the shell on *NIX systems, or for CGI scripts, and since modules typically don't get executed directly, only used, the shebang isn't needed for that. (I did use to have a text editor that used the shebang to detect Perl scripts for its syntax highlighting, so a lot of my modules start with #!perl, but that's usually not needed otherwise.)

3. I think, I am going to write "use MyPackage;" in my perl program, and then myPackage.pm will be placed in my Perl's INC directory. Is this how it should be done?

Yes, that's the standard practice. require executes at runtime, while use executes at compile time, meaning that errors will be caught earlier, and also it calls the module's sub import if it has one, so it's the standard way of loading modules. You may also want to look into Exporter to provide the import functionality for you.

4. I've noticed that some modules have "our $VERSION = ..." but I start my module with "my $VERSION" Is that okay?
5. Btw what's the purpose of the $VERSION string? Is there a part of Perl that will try to access that value at some point during my program's execution?

our $VERSION is better, because some Perl utilities need access to the variable (like UNIVERSAL's ->VERSION), and some parse the $VERSION out of modules (like the CPAN indexer, IIRC).

6. What if my module's name conflicts with another module that exists out there?

The best thing would be to check the CPAN to avoid such conflicts entirely. But if it can't be avoided - one valid reason might be if you're monkey patching a module - and you don't plan on uploading your module to the CPAN, then the typical way to avoid conflicts on your local machine is to add a directory to @INC where you install the modules, making sure that directory appears first in @INC.

I notice you wrote "the INC directory" in several places; note there is more than one, and Perl searches them in order for modules, and you can add your own entries to the list in several different ways, e.g. use lib or the PERL5LIB environment variable. And typically, you wouldn't manually place your module into Perl's standard @INC directories, because that's the job of tools like cpanm, so instead you'd add your own directory to @INC so that you can manually modify the contents of that directory without messing up your Perl installation by accident.

7. What if my module tries to achieve the same result that another popular module does but mine goes about doing it very differently? How should I name my module?

That depends; if you plan to publish your code to the CPAN then I would recommend you ask for suggestions here by telling us what the modules are and how yours differs (both in functionality and in its API).

8. Is it important to upload a module to CPAN, or can I just put it on my website and host it there?

The advantage of the CPAN is that standard tools like cpanm can be used to install modules from there, and as you said, that it is likely to be around for longer. But putting modules on the CPAN does require a bit more work, since you have to put them in a distribution, providing proper documentation, a test suite, a Makefile.PL, and so on. You might want to look at module-starter for that.

9. When I open some pm files in the INC directory, I notice that a lot of them seem to have plain text mixed with program code. The text or documentation is preceded by something like "=head1 DESCRIPTION" and I am not sure what this is.
10. Is it's okay if I put my documentation on simple comment lines started with "#" instead of "=" ?

That's Plain Old Documentation (POD), and is described in perlpod (plus perlpodstyle, perlmodstyle, and perlpodspec). It's much better to use that instead of comments because the standard Perl tools like perldoc will automatically turn that into the nicely-formatted documentation you get when you run perldoc MyModule.pm and when you visit the CPAN website.

Here's all that applied to your example code:

package MyPackage;
use warnings;
use strict;
use Exporter 'import';

our @EXPORT_OK = qw/ myFunc /;

our $VERSION = "1.00";

=head1 myFunc()

This function is just a test.

=cut

my $PRIVATE = 444;

sub myFunc
{
  $PRIVATE++;
  print "\nPackage MyPackage::myFunc(@_)\nPRIVATE = $PRIVATE\n";
}

1;

And an example main code, where one quick way you can tell Perl how to find the module is perl -Ipath/to/package script.pl:

use warnings;
use strict;
use MyPackage qw/myFunc/;

myFunc();

[harangzsolt33]

Wow, thank you so much for answering all my questions so quickly and in such great detail!!!

I have one more question. I guess, I can look this up myself. My assumption is if the shebang is not mandatory for pm files in Linux (because pm files are not meant to be executed from command line), then I guess the file's permissions can be 644. They are not required to be 755. Correct?

[haukex]

My assumption is if the shebang is not mandatory for pm files in Linux (because pm files are not meant to be executed from command line), then I guess the file's permissions can be 644. They are not required to be 755. Correct?

Yes!

[eyepopslikeamosquito]

My assumption is if the shebang is not mandatory for pm files in Linux (because pm files are not meant to be executed from command line), then I guess the file's permissions can be 644. They are not required to be 755.

Yes. For cheap thrills, I ran these commands on my recently installed perl 5.38 on Ubuntu:

~/localperl$ find . -name '*.pm' -ls >pm.tmp
~/localperl$ find . -name '*.pl' -ls >pl.tmp

All the .pm files have permissions like this:

-r--r--r--   ... ./lib/5.38.0/Carp.pm

The perl commands in the bin directory designed to be run as commands have permissions like this example of the prove command:

-rwxr-xr-x  ... prove

These text files also tend to start with a shebang line like:

#!/home/youruser/localperl/bin/perl

There are also plenty of .pl files lying around with permissions like this:

-r--r--r-- ... somefile.pl

which is fine because you can still run them manually via:

perl /somepath/somefile.pl

[Marshall]

I came back - my back is hurting and couldn't sleep....

There is one trick that I sometimes use....
It is possible for your module to know if it was "used" versus executed directly. This allows me to put a test driver in the module itself that I use during development that presents more info that just a "pass/fail". If you do this, you will want your .pm to be an executable file under Unix.

#Normal module preamble here...
sub test{
   print "this is a dev test...\n";
}

test() if not caller; ### Run test() if run directly

#Normal rest of module code here....
1;

[harangzsolt33]

Oh, what a nice trick! That's so cool!! :-)

[ForgotPasswordAgain]

Also for #1 where something else enables them, use can implicitly enable strict or warnings depending on the version.

See use VERSION