sbt-native-packager

80 Pages·2017·0.34 MB·English

sbt-native-packager
Release 1.0a1
Josh Suereth
Feb 19, 2023

Contents
1 Introduction 1
1.1 Goals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.2 Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.3 CoreConcepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2 GettingStarted 5
2.1 Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.2 Yourfirstpackage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
3 PackagingFormats 7
3.1 UniversalPlugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
3.2 LinuxPlugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
3.3 DebianPlugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
3.4 RpmPlugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
3.5 DockerPlugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
3.6 WindowsPlugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
3.7 JDKPackagerPlugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
3.8 GraalVMNativeImagePlugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
4 ProjectArchetypes 47
4.1 JavaApplicationArchetype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
4.2 JavaServerApplicationArchetype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
4.3 Systemloaders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
4.4 ConfigurationArchetypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
4.5 JlinkPlugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
4.6 ArchetypeCheatsheet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
5 Recipes 71
5.1 CustomPackageFormats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
5.2 Dealingwithlongclasspaths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
5.3 Play2Packaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
5.4 Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
5.5 ScalaJSpackaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
5.6 Buildthesamepackagewithdifferentconfigs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
5.7 EmbeddingJVMinUniversal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
5.8 Settingtheumaskforyourprocess . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
i
ii
1
CHAPTER
Introduction
SBTnativepackagerletsyoubuildapplicationpackagesinnativeformatsandoffersdifferentarchetypesforcommon
configurations,suchassimpleJavaappsorserverapplications.
Thissectionprovidesageneraloverviewofnativepackageranditscoreconcepts. Ifyouwantaquickstart,gotothe
gettingstartedsection. Howeverwerecommendunderstandingthecoreconcepts,whichwillhelpyoutogetstarted
evenquicker.
1.1 Goals
Nativepackagerdefinesprojectgoalsinordertosetexpectationsandscopeforthisproject.
1. Nativeformatsshouldbuildontheirrespectiveplatform This allows native packager to support a wide
range of formats as the packaging plugin serves as a wrapper around the actual packaging tool. How-
ever,alternativepackagingpluginsmaybeprovidedifajava/scalaimplementationexists. Asanexample
debianpackagesshouldalwaysbuildondebiansystems,howevernativepackagerprovidesanadditional
pluginthatintegratesJDebforaplatformindependentpackagingstrategy.
2. Providearchetypesforzeroconfigurationbuilds Whilepackagingpluginsprovidethehowapackageiscre-
ated, archetypes provide the configuration for what gets packaged. Archetypes configure your build to
create a package for a certain purpose. While an archetype may not support all packaging formats, it
shouldworkwithoutconfigurationforthesupportedformats.
3. Enforcebest-practices There is no single way to create a package. Native packager tries to create packages
followingbestpractices,e.g. forfilenames,installationpathsorscriptlayouts.
1.2 Scope
Whilenativepackagerprovidesawiderangeofformatsandarchetypeconfigurations,itsscopeisrelativelynarrow.
Nativepackageronlytakescareofpackaging,theactofputtingalistofmappings(sourcefiletoinstalltargetpath)
intoadistinctpackageformat(zip,rpm,etc.).
1
sbt-native-packager,Release1.0a1
Archetypes like Java Application Archetype or Java Server Application Archetype only add additional files to the
mappingsenrichingthecreatedpackage,buttheydon’tprovideanynewfeaturesfornative-packagercorefunction-
ality. Muchlikethepackagingformatplugins,thearchetypesrelyonfunctionalityalreadyavailableonyourdeploy
target.
Thesethingsareoutofnativepackagersscope
1. Providingapplicationlifecylemanagement. TheJavaServerApplicationArchetypeprovidesconfigurations
forcommonsystem-loaderslikeSystemV,UpstartorSystemD.Howevercreatingacustomsolutionwhich
includesstopscripts,PIDmanagement,etc. arenotpartofnativepackager.
2. Providingdeploymentconfigurations NativepackagerproducesartifactswiththepackageBintask. What
youdowiththeseispartofanotherstepinyourprocess.
1.3 Core Concepts
Nativepackagerisbasedonafewsimpleconcepts. Ifyouunderstandthese,youwillbeabletocustomizeyourbuild,
createownpackagingformatsanddeploymoreeffectively.
1. Separationofconcernswithtwokindsofplugins
• formatpluginsdefinehowapackageiscreated
• archetypepluginsdefinewhatapackageshouldcontain
2. Mappingsdefinehowyourbuildfilesshouldbeorganizedonthetargetsystem.
MappingsareaSeq[(File, String)],whichtranslatesto“alistoftuples,whereeachtuple
definesasourcefilethatgetsmappedtoapathonthetargetsystem”.
Thefollowingsectionsdescribetheseconceptsinmoredetail.
1.3.1 Format Plugins
Formatpluginsprovidetheimplementationtocreatepackage,thehowapackageiscreated. ForexampletheDebian
Plugin provides a way to package debian packages. Each format plugin has its own documentation. Each plugin
providesacommonsetoffeatures:
1. Provideanewconfigurationscope Formatsdefinetheirownconfigurationscopetobeabletocustomizeevery
sharedsettingortask.
2. Providepackageformatrelatedsettingsandtasks Each format plugin may add additional settings or tasks
thatareonlyusedbythisplugin. Normallythesesettingsstartwiththepluginname,e.g. rpmXYZ.
3. Implementpackagetask packageBinorpublishLocaltasksprovidetheactualactiontocreateapack-
age.
Byenablingaformatpluginonlywith
enablePlugins(SomePackageFormatPlugin)
theresultingpackagewillbeemptybecauseaformatplugindoesn’tprovideanyconfigurationotherthanthedefault
settingsfortheformatplugin’sspecificsettings.
2 Chapter1. Introduction
sbt-native-packager,Release1.0a1
1.3.2 Archetype Plugins
Whileformatpluginsprovidethehow,archetypesprovidethewhatgetspackaged. Anarchetypechangestheconfig-
urationinallsupportedpackageformatscopes;theydon’taddconfigurationscopes.
Afulllistofarchetypescanbefoundhere.
Anarchetypemayprovidethefollowing:
1. Archetyperelatedsettingsandtasks
2. Newfilesinyourpackage
Byenablinganarchetypepluginwith
enablePlugins(SomeArchetypePlugin)
allconfigurationchangeswillbeappliedaswellasallsupportedformatpluginswillbeenabled.
Tip: Anarchetypepluginshouldbethestartingpointforcreatingpackages!
1.3.3 Mappings
Mappingsaretheheartofnativepackager. Thistaskdefineswhatfilesinyourbuildshouldbemappedwhereonthe
targetsystem. Thetypesignatureforthemappingstaskis
mappings: TaskKey[Seq[(File, String)]]
Thefilepartofthetuplemustbeavailableduringthepackagingphase. TheStringpartrepresentsthepathinsidethe
installationdirectory.
TheUniversalPluginrepresentsthebaseforallotherplugins. Ithasabigsectiononhowtocustomizemappings.
1.3.4 Architecture
Thearchitecturecanbesummarizedwiththisdiagram
When using the full power of the plugin, all of the packaging is driven from the Universal / mappings set-
ting, which defines what files will be included in the package. These files are automatically moved around for the
appropriatenativepackagingasneeded.
1.3. CoreConcepts 3
sbt-native-packager,Release1.0a1
4 Chapter1. Introduction
2
CHAPTER
Getting Started
2.1 Setup
Sbt-native-packagerisanAutoPlugin. Addittoyourplugins.sbt
addSbtPlugin("com.github.sbt" % "sbt-native-packager" % "x.y.z")
2.1.1 Native Tools
Dependingonthepackageformatyouwanttocreate,youmayneedadditionaltoolsavailableonyourmachine. Each
packagingformathasarequirementssection.
2.2 Your first package
Nativepackagerprovidespackagingformatpluginsandarchetypepluginstoseparateconfigurationandactualpack-
aging. TogetstartedweusethebasicJavaApplicationArchetype. Formorearchetypesseethearchetypespage.
Inyourbuild.sbtyouneedtoenablethearchetypelikethis
enablePlugins(JavaAppPackaging)
Thiswillalsoenableallsupportedformatplugins.
2.2.1 Run the app
Nativepackagercanstageyourappsoyoucanrunitlocallywithouthavingtheapppackaged.
sbt stage
./target/universal/stage/bin/<your-app>
5
sbt-native-packager,Release1.0a1
2.2.2 Create a package
Wecangenerateotherpackagesviathefollowingtasks. Notethateachpackagingformatmayneedssomeadditional
configurationandnativetoolsavailable. Here’sacompletelistofcurrentformats.
• Universal/packageBin-Generatesauniversalzipfile
• Universal/packageZipTarball-Generatesauniversaltgzfile
• Debian/packageBin-Generatesadeb
• Docker/publishLocal-BuildsaDockerimageusingthelocalDockerserver
• Rpm/packageBin-Generatesanrpm
• Universal/packageOsxDmg-GeneratesaDMGfilewiththesamecontentsastheuniversalzip/tgz.
• Windows/packageBin-GeneratesanMSI
6 Chapter2. GettingStarted