Perl package guidelines - ArchWiki

This section serves as an introduction to the concept of perl packaging, from the point of view of Arch Linux; that is, package management ... HomePackagesForumsWikiBugsSecurityAURDownload Jumptocontent Namespaces PageDiscussion English expanded collapsed Views ReadViewsourceViewhistory More expanded collapsed Navigation MainpageTableofcontentsGettinginvolvedWikinewsRandompage Interaction HelpContributingRecentchangesRecenttalksNewpagesStatisticsRequests Tools WhatlinkshereRelatedchangesSpecialpagesPrintableversionPermanentlinkPageinformation Archpackageguidelines 32-bit–CLR–CMake–Cross–DKMS–Eclipse–Electron–Font–FreePascal–GNOME–Go–Haskell–Java–KDE–Kernel–Lisp–Meson–MinGW–Node.js–Nonfree–OCaml–Perl–PHP–Python–R–Ruby–Rust–Shell–VCS–Web–Wine ThisdocumentcoversthecreationofPKGBUILDsforperlmodulesdistributedoverCPAN,theComprehensivePerlAuthorsNetwork.Thetargetaudienceofthisdocumentisintendedtobepackagersofperlmodules.ForPerlpoliciesseePerlPolicy. Contents 1ArchLinuxPackagingConventions 1.1Packagenames 1.2Packagefileplacement 1.3Architecture 1.4Automation 2PKGBUILDExamples 3CPANModuleMechanics 3.1Modules 3.2Distributions 3.3CPAN 3.4Moduledependencies 3.5Dependencydefinition 3.6Metainformation 4Installationmodules 4.1ExtUtils::MakeMaker 4.2Module::Build 4.3Module::Build::Tiny 4.4Module::Install 4.5Environmentvariables 4.5.1PERL_MM_USE_DEFAULT 4.5.2PERL_AUTOINSTALL 4.5.3PERL_MM_OPT 4.5.4PERL_MB_OPT 4.5.5MODULEBUILDRC 4.5.6PERL5LIB 4.5.7PERL_LOCAL_LIB_ROOT 5Problemswithuser-installedperl ArchLinuxPackagingConventions Thefollowingconventionsshouldbeusedtokeepperlmodulepackagesconsistent.Thissectionservesasanintroductiontotheconceptofperlpackaging,fromthepointofviewofArchLinux;thatis,packagemanagementandsystemadministration.InanefforttopleasethecasualTL;DRreader,theeasiestand/ormostpopularmaterialisatthetop. Packagenames Formodulesthepackagenameshouldbeginwithperl-andtherestofthenameshouldbeconstructedfromthemodulenamebyconvertingittolowercaseandthenreplacingcolonswithhyphens.ForexamplethepackagenamecorrespondingtoHTML::Parserwillbeperl-html-parser.Perlapplicationsshouldhavethesamenameasthatoftheapplicationbutinlowercase. Packagefileplacement Perlpackagesshouldinstallmodulefilesinto/usr/lib/perl5/$version/vendor_perl/(useperl-V:vendorarchinscripts),or/usr/share/perl5/vendor_perl/.ThisisdonebysettingtheINSTALLDIRScommandlineparametertovendorasshownbelow.Nofilesshouldbestoredin/usr/lib/perl5/$version/site_perl/asthatdirectoryisreservedforusebythesystemadministratortoinstallPerlpackagesoutsidethepackagemanagementsystem.Whenauserinstallsmodulessystem-widebyusingthecpanshell,modulesendupinthesite-perlsub-directories. Thefilesperllocal.podand.packlistalsoshouldnotbepresent;thisistakencareofbytheexamplePKGBUILDdescribedbelow. Architecture Inmostcases,thearcharrayshouldcontain'any'becausemostPerlpackagesarearchitectureindependent.XSmodulesarecompiledintodynamicallyloadedlibraries(.sofiles)andshouldexplicitlysettheirarchitectureto('x86_64')inordertoindicatethattheyarearchitecturedependentwhenbuilt.AnXSmoduleusuallycontainsoneormore.xsfileswhichdynamicallygenerate.cfiles. Automation Apluginforthesecond-generationCPANshell,CPANPLUS,isavailableintheperl-cpanplus-dist-archpackage.ThispluginpackagesdistributionsontheflyastheyareinstalledbyCPANPLUS.Onlinedocumentationisavailableathttps://metacpan.org/release/CPANPLUS-Dist-Arch PKGBUILDExamples AnexamplePKGBUILDcanbefoundat[1]. ThefollowingtwoPKGBUILDexamplesusetechniques,introducedinthispage,thatareintendedtomakeaPKGBUILDmoreresilienttomoresophisticatedproblems.Becausetherearetwostylesofbuildscripts,therearetwoexamplePKGBUILDS.ThefirstPKGBUILDisanexampleofhowtopackageadistributionthatusesMakefile.PL.ThesecondPKGBUILDcanbeusedasastartingpointforadistributionwhichusesBuild.PL. PKGBUILD #Contributor:YourName pkgname=perl-foo-bar pkgver=1.0 pkgrel=1 pkgdesc='ThispackagestheFoo-Bardistribution,containingtheFoo::Barmodule!' _dist=Foo-Bar arch=('any') url="https://metacpan.org/release/$_dist" license=('GPL''PerlArtistic') depends=(perl) options=('!emptydirs'purge) source=("http://search.cpan.org/CPAN/authors/id/BAZ/$_dist-$pkgver.tar.gz") md5sums=(...) build(){ cd"$srcdir/$_dist-$pkgver" unsetPERL5LIBPERL_MM_OPTPERL_LOCAL_LIB_ROOT exportPERL_MM_USE_DEFAULT=1PERL_AUTOINSTALL=--skipdeps /usr/bin/perlMakefile.PL make } check(){ cd"$srcdir/$_dist-$pkgver" unsetPERL5LIBPERL_MM_OPTPERL_LOCAL_LIB_ROOT exportPERL_MM_USE_DEFAULT=1 maketest } package(){ cd"$srcdir/$_dist-$pkgver" unsetPERL5LIBPERL_MM_OPTPERL_LOCAL_LIB_ROOT makeinstallINSTALLDIRS=vendorDESTDIR="$pkgdir" } PKGBUILD #Contributor:YourName pkgname=perl-foo-bar pkgver=1.0 pkgrel=1 pkgdesc='ThispackagestheFoo-Bardistribution,containingtheFoo::Barmodule!' _dist=Foo-Bar arch=('any') url="https://metacpan.org/release/$_dist" license=('GPL''PerlArtistic') depends=(perl) options=('!emptydirs'purge) source=("http://search.cpan.org/CPAN/authors/id/BAZ/$_dist-$pkgver.tar.gz") md5sums=(...) build(){ cd"$srcdir/$_dist-$pkgver" unsetPERL5LIBPERL_MM_OPTPERL_MB_OPTPERL_LOCAL_LIB_ROOT exportPERL_MM_USE_DEFAULT=1MODULEBUILDRC=/dev/null /usr/bin/perlBuild.PL ./Build } check(){ cd"$srcdir/$_dist-$pkgver" unsetPERL5LIBPERL_MM_OPTPERL_MB_OPTPERL_LOCAL_LIB_ROOT exportPERL_MM_USE_DEFAULT=1 ./Buildtest } package(){ cd"$srcdir/$_dist-$pkgver" unsetPERL5LIBPERL_MM_OPTPERL_MB_OPTPERL_LOCAL_LIB_ROOT ./Buildinstall--installdirs=vendor--destdir="$pkgdir" } JustificationfortheaddedcomplexityofthesePKGBUILDsisattemptedinthelattersections. CPANModuleMechanics Thereareanumberofcarefully,andnotsocarefully,designedmechanicsthatworktogethertocreatethemodulesystem.WhenmakinguseoftheCPAN,proceduresmustbefollowedtofetchthesourcecodeofamodule,buildthatfetchedmodule,andinsertitintothesystemsoftwareforlaterexecution.Inordertounderstandhowmodulesshouldbepackaged,ithelpsimmenselyifoneunderstandshowmodulesworkwithoutanyinvolvementfrompacmanandArchLinuxpackages.Ourgoalintheendistotrytobeunobtrusiveaspossible,whileimprovingorganizationandconsistencyintheendproduct. Modules Modulesaredeclaredwiththepackagekeywordinperl.Modulesarecontainedinsidea.pm("dot-pee-em")file.Thoughitispossiblemorethanonemodule(package)isinthefile.Moduleshavenamespacesseparatedwith::(doublecolons),like:Archlinux::Module.Whenloadingamodule,the::sarereplacedwithdirectoryseparators.Forexample:Archlinux/Module.pmwillbeloadedforthemoduleArchlinux::Module. Coremodulesareincludedwithaninstallationofperl.Somecoremodulesareonlyavailablebundledwithperl.OthermodulescanstillbedownloadedandinstalledseparatelyfromCPAN. Distributions (akadist,package)ThisistheequivalentofanArchLinuxpackageinCPAN-lingo.Distributionsare.tar.gzarchivesfulloffiles.Thesearchivescontainprimarily.pmmodulefiles,testsfortheincludedmodules,documentationforthemodules,andwhateverelseisdeemednecessary. Usuallyadistributioncontainsaprimarymodulewiththesamename.Sometimesthisisnottrue,likewiththeTemplate-Toolkitdistribution.Thelatestpackage,Template-Toolkit-2.22.tar.gz,fortheTemplate-Toolkitdist,containsnoTemplate::Toolkitmodule! Sometimesbecausedistributionsarenamedafteramainmodule,theirnamesareusedinterchangeablyandtheygetmuddledtogether.Howeveritissometimesusefultoconsiderthemaseparateentity(likeinTemplate-Toolkit'scase). CPAN EachCPANmirrorcontainsindicesthatlistthedistributionsonCPAN,themodulesinthedists,andthenameoftheauthorwhouploadedthedist.Thesearesimplytextfiles.Themostusefulindexisinthe/modules/02packages.details.txt.gzfileavailablefromeachCPANmirror.Theterm"packages"herereferstothepackagekeywordintheperllanguageitself,notsomethingsimilartopacmanpackages.TheCPANshell,referredtoaslowercased,italicizedcpan,issimplythevenerableperlscriptwhichnavigatesindicestofindthemoduleyouwanttoinstall. Modulesarefoundinthe02packages.details.txt.gzlist.Onthesamelineasthemodule/packagenameisthepathtothedistributiontarballthatcontainsthemodule.Whenyouaskcpantoinstallamodule,itwilllookupthemoduleandinstalltherelevantdistribution.Asthedistributionisinstallingitwillgeneratealistofmoduledependencies.Cpanwilltrytoloadeachmoduledependencyintotheperlinterpreter.Ifamoduleofthegivenversioncannotbeloadedtheprocessisrepeated. Thecpanshelldoesnothavetoworryaboutwhatversionoftherequiredmoduleitisinstalling.cpancanrelyonthefactthatthelatestversionofthemodulemustsatisfytherequirementsoftheoriginalmodulethatitbeganinstallinginthefirstplace.Onlythelatestversionsofmodulesarelistedinthepackagesdetailsfile.Unfortunatelyfortheperlpackageauthor,wecannotalwaysrelyonthefactthatourpackagesofferthemostrecentversionofaperldistributionandthemodulescontainedwithin.Pacmandependencycheckingismuchmorestaticandstronglyenforced. Moduledependencies Perlhasauniquewayofdefiningdependenciescomparedtosimilarsystemslikepythoneggsandrubygems.Eggsdefinedependenciesonothereggs.Gemsdependongems.Perldistsdependonmodules.ModulesareonlyavailablefromCPANdistributionssoinawayperldistributionsdependondistributionsonlyindirectly.Modulescandefinetheirownversionsindependentfromdistributionsinsidethemodulesourcecode.Thisisdonebydefiningapackagevariablecalled$VERSION.Whenusingstrictandwarnings,thisisdefinedwiththeourkeyword.Forexample: packageFoo::Module; usewarnings; usestrict; our$VERSION='1.00'; Modulescanchangetheirversionshowevertheylikeandevenhaveaversiondistinctfromthedistributionversion.Theutilityofthisisquestionablebutitisimportanttokeepinmind.Moduleversionsaremoredifficulttodeterminefromoutsideoftheperlinterpreterandrequireparsingtheperlcodeitselfandmaybeevenloadingthemoduleintoperl.Theadvantageisthatfrominsidetheperlinterpretermoduleversionsareeasytodetermine.Forexample: useFoo::Module; print$Foo::Module::VERSION,"\n"; Dependencydefinition Wherearedependenciesdefinedinperldistributions?Theyare"defined"insideoftheMakefile.PLorBuild.PLscript.Forexample,insideoftheMakefile.PLscripttheWriteMakeFilefunctioniscalledtogeneratetheMakefilelikethis: useExtUtils::MakeMaker; WriteMakeFile( 'NAME'=>'ArchLinux::Module', 'VERSION'=>'0.01', 'PREREQ_PM'=>{'POSIX'=>'0.01'}, ); ThisisacontrivedexamplebutitisimportanttounderstandthedependenciesarenotfinaluntilaftertheMakefile.PLorBuild.PLscriptisrun.Dependenciesarespecifiedatruntime,whichmeanstheycanbechangedormodifiedusingthefullpowerofperl.Thismeansthemoduleauthorcanadd,remove,orchangeversionsofdependenciesrightbeforethedistributionisinstalled.Somemodulesauthorsusethistodooverlycleverthingslikedependonmodulesonlyiftheyareinstalled.Somemulti-platformdistsalsodependonsystem-specificmoduleswheninstalledondifferentoperatingsystems. Asanexample,theCPANPLUSdistributionlooksforCPANPLUS::Distpluginsthatarecurrentlyinstalled.IfanypluginsareinstalledforthecurrentlyinstalledversionofCPANPLUSitaddsthemtothenewCPANPLUS'sprerequisites.I'mnotquitesurewhy.LuckilyfortheperlpackagermostdependenciesarestaticlikeintheaboveexamplethatrequiresthePOSIXmodulewithaminimumversionof0.01. Metainformation Metafilesareincludedinrecentdistributionswhichcontainmeta-informationaboutdistributionssuchasthename,author,abstractdescription,andmodulerequirements.PreviouslytherewereMETA.ymlfilesintheYAMLformatbutmorerecentlytheswitchhasbeenmadetoMETA.jsonfilesintheJSONformat.Thesefilescan beeditedbyhandbutmoreoftentheyaregeneratedautomaticallybyMakefile.PLorBuild.PLscriptswhenpackagingadistributionforrelease.ThelatestspecificationisdescribedinCPAN::Meta::Spec'sonlinedocs. Rememberthatdependenciescanbechangedatruntime!Forthisreasonanothermetafileisgeneratedafterrunningthebuildscript.ThissecondmetafileiscalledMYMETA.jsonandreflectschangesthescriptmadeatruntimeandmaybedifferentfromthemetafilegeneratedwhenthedistributionwaspackagedforCPAN. ElderlydistributionsontheCPANhavenometafileatall.TheseoldreleasespredatetheideaoftheMETA.ymlfileandonlydescribetheirprerequisitesintheirMakefile.PL. Installationmodules Thisarticleorsectionneedslanguage,wikisyntaxorstyleimprovements.SeeHelp:Styleforreference. Reason:ThissectionanditssubsectionsseemstooinformalforanArchWikiarticle(DiscussinTalk:Perlpackageguidelines) Oneofperl'sgreateststrengthsisthesheernumberofmodulesavailableonCPAN.Nottoosurprisingly,therearealsoseveraldifferentmodulesusedforinstalling...well...modules!TMTOWTDI!Iamnotawareofastandardnameforthesetypesofmodules,soIjustcalledthem"InstallationModules". Thesemodulesareconcernedwithbuildingthedistributionandinstallingmodulefileswherevertheuserprefers.Thisseemsstraightforward,butconsideringthenumberofdifferentsystemsperlrunson,thiscangetcomplex.Installationmodulesallplaceaperlcodefileinsidethedisttarball.Runningthisperlscriptwillinitiatethebuildandinstallprocess.Thescriptalwaysendswiththe.PLsuffixandistermedthe"Buildscript"inthebelowlist. ExtUtils::MakeMaker Buildscript Makefile.PL CPANlink https://search.cpan.org/dist/ExtUtils-MakeMaker Theoriginal,oldestmoduleforinstallingmodulesisExtUtils::MakeMaker.Themajordownsidetothismoduleisthatitrequiresthemakeprogramtobuildandinstalleverything.ThismaynotseemlikeabigdealtolinuxusersbutisarealhassleforWindowspeople! Module::Build Buildscript Build.PL CPANlink https://search.cpan.org/dist/Module-Build ThemainadvantageofModule::Buildisthatitispure-perl.Thismeansitdoesnotrequireamakeprogramtobeinstalledforyoutobuild/installmodules.ItsadoptionwasrockybecauseifModule::Buildwasnotalreadyinstalled,youcouldnotrunthebundledBuild.PLscript!ThisisnotaproblemwithrecentversionsofperlbecauseModule::Buildisacoremodule.(NOTEAsofperl5.22,Module::Buildwillnolongerbeacoremodule) Module::Build::Tiny Buildscript Build.PL CPANlink https://search.cpan.org/dist/Module-Build-Tiny Thisisanotherpure-perlbuildtool.AsaninterfaceitimplementsasubsetofModule::Build'sinterface,inparticularitrequiresdashesbeforeitsarguments(Module::Buildacceptswithandwithout)anddoesnotsupport.modulebuildrc. Module::Install Buildscript Makefile.PL CPANlink https://search.cpan.org/dist/Module-Install Anothermodernbuild/installationmodule,Module::Installstillrequiresthemakeprogrambeinstalledtofunction.MIwasdesignedasadrop-inreplacementforMakeMaker,toaddresssomeofMakeMaker'sshortcomings.Ironically,itdependsonMakeMakerinordertooperate.TheMakefile.PLfilesthataregeneratedbyMIlookmuchdifferentandareimplementedusingasimpledomainspecificlanguage. OneveryinterestingfeatureisthatModule::Installbundlesacompletecopyofitselfintothedistributionfile.Becauseofthis,unlikeMakeMakerorM::B,youdonotneedModule::Installtobeinstalledonyoursystem. Anotherveryuniquefeatureisauto-install.ThoughnotrecommendedbyModule::Install'sauthorsthisfeatureisusedquiteoften.Whenthemoduleauthorenablesauto-installfortheirdistribution,Module::Installwillsearchforandinstallanypre-requisitemodulesthatarenotinstalledwhenMakefile.PLisexecuted.ThisfeatureisskippedwhenModule::InstalldetectsitisbeingrunbyCPANorCPANPLUS.However,thisfeatureisnotskippedwhenruninside...ohIdonotknow...aPKGBUILD!Ihopeyoucanseehowarogueperlprogramdownloadingandinstallingmoduleswilly-nillyinsideaPKGBUILDcanbeaproblem.Seethe#PERL_AUTOINSTALLenvironmentvariabletoseehowtofixthis. Environmentvariables Anumberofenvironmentvariablescanaffectthewaythemodulesarebuiltorinstalled.Somehaveaverydramaticeffectandcancauseproblemsifmisunderstood.Anadvancedusercouldbeusingtheseenvironmentvariables.SomeofthesewillbreakanunsuspectingPKGBUILDorcauseunexpectedbehavior. PERL_MM_USE_DEFAULT Whenthisvariableissettoatruevalue,theinstallationmodulewillpretendthedefaultanswerwasgiventoanyquestionitwouldnormallyask.Thisdoesnotalwayswork,butalloftheinstallationmoduleshonourit.Thatdoesnotmeanthemoduleauthorwill! PERL_AUTOINSTALL Youcanpassadditionalcommand-lineargumentstoModule::Install'sMakefile.PLwiththisvariable.Inordertoturnoffauto-install(highlyrecommended),assign--skipdepstothis. exportPERL_AUTOINSTALL='--skipdeps' PERL_MM_OPT Youcanpassadditionalcommand-lineargumentstoMakefile.PLand/orBuild.PLwiththisvariable.Forexample,youcaninstallmodulesintoyourhome-dirbyusing: exportPERL_MM_OPT=INSTALLBASE=~/perl5 PERL_MB_OPT ThisisthesamethingasPERL_MM_OPTexceptitisonlyforModule::Build.Forexample,youcouldinstallmodulesintoyourhome-dirbyusing: exportPERL_MB_OPT=--install_base=~/perl5 MODULEBUILDRC Module::Buildallowsyoutooverrideitscommand-line-argumentswithanrcfile.Thisdefaultsto~/.modulebuildrc.Thisisconsidereddeprecatedwithintheperltoolchain.YoucanoverridewhichfileitusesbysettingthepathtothercfileinMODULEBUILDRC.TheparanoidmightsetMODULEBUILDRCto/dev/null...justincase. PERL5LIB Thedirectoriessearchedforlibrariescanbesetbytheuser(particularlyiftheyareusingLocal::Lib)bysettingPERL5LIB.Thatshouldbeclearedbeforebuilding. PERL_LOCAL_LIB_ROOT IftheuserisusingLocal::LibitwillsetPERL_LOCAL_LIB_ROOT.Thatshouldbeclearedbeforebuilding. Problemswithuser-installedperl Asubtleproblemisthatadvancedperlprogrammersmayliketohavemultipleversionsofperlinstalled.Thisisusefulfortestingbackwards-compatibilityincreatedprograms.Therearealsospeedbenefitstocompilingyourowncustomperlinterpreter(i.e.withoutthreads).AnotherreasonforacustomperlissimplybecausetheofficialperlArchLinuxpackagesometimeslagsbehindperlreleases.Theusermaybetryingoutthelatestperl...whoknows? Iftheuserhasthecustomperlexecutableintheir$PATH,thecustomperlwillberunwhentheusertypestheperlcommandontheshell.InfactthecustomperlwillruninsidethePKGBUILDaswell!Thiscanleadtoinsidiousproblemsthataredifficulttounderstand. TheproblemliesincompiledXSmodules.ThesemodulesbridgeperlandC.Assuchtheymustuseperl'sinternalCAPItoaccomplishthisbridge.Perl'sCAPIchangesslightlywithdifferentversionsofperl.Iftheuserhasadifferentversionofperlthanthesystemperl(/usr/bin/perl)thenanyXSmodulecompiledwiththeuser'sperlwillbeincompatiblewiththesystem-wideperl.WhentryingtousethecompiledXSmodulewiththesystemperl,themodulewillfailtoloadwithalinkerror. Asimplesolutionistoalwaysusetheabsolutepathofthesystem-wideperlinterpreter(/usr/bin/perl)whenrunningperlinthePKGBUILD. Retrievedfrom"https://wiki.archlinux.org/index.php?title=Perl_package_guidelines&oldid=719092" Category:ArchpackageguidelinesHiddencategory:PagesorsectionsflaggedwithTemplate:Style