| ---- |
| Packaging Applications in NPanday |
| ---- |
| ---- |
| 2012-01-09 |
| ---- |
| ~~Licensed to the Apache Software Foundation (ASF) under one |
| ~~or more contributor license agreements. See the NOTICE file |
| ~~distributed with this work for additional information |
| ~~regarding copyright ownership. The ASF licenses this file |
| ~~to you under the Apache License, Version 2.0 (the |
| ~~"License"); you may not use this file except in compliance |
| ~~with the License. You may obtain a copy of the License at |
| ~~ |
| ~~ http://www.apache.org/licenses/LICENSE-2.0 |
| ~~ |
| ~~Unless required by applicable law or agreed to in writing, |
| ~~software distributed under the License is distributed on an |
| ~~"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| ~~KIND, either express or implied. See the License for the |
| ~~specific language governing permissions and limitations |
| ~~under the License. |
| |
| Packaging Applications in NPanday |
| |
| Ususally an application needs more than a EXE or DLL in order to be executed. This topic is about how to |
| package your application in a way that makes it runnable. |
| |
| The packaging itself is done by various Maven plugins, depending on the package format; but all handle packaging in |
| a similar fashion. |
| |
| [[1]] <<<pre-package:>>> Collect the needed files (including dependencies) into a directory |
| in <<<target/packages/*>>> and possibly filter/transform configuration settings. |
| |
| [[2]] <<<package:>>> Somehow pack up the collected files in the desired format and attach it |
| as project artifact. |
| |
| [] |
| |
| Collecting files for a package utilizes components from the |
| {{{http://maven.apache.org/plugins/maven-assembly-plugin/}Maven Assembly Plugin}} and hence supports both the |
| {{{http://maven.apache.org/plugins/maven-assembly-plugin/assembly.html}Assembly Descriptor}} and the |
| {{{http://maven.apache.org/plugins/maven-assembly-plugin/component.html}Component Descriptor}}. |
| |
| The two main project types that require packaging are web applications and executables (dll/exe). Packaging for |
| these is delivered by each its plugin, the {{{../../plugins/aspnet-maven-plugin/index.html}aspnet-maven-plugin}} |
| and {{{../../plugins/aspnet-maven-plugin/index.html}application-maven-plugin}}. |
| |
| * Apply configuration transformations |
| |
| NPanday supports configuration transformations through |
| {{{http://msdn.microsoft.com/en-us/library/dd465326.aspx}Microsoft Xml Document Transform}}, also called XDT. This |
| enables modifications for config files before they make it into the package. While Visual Studio (2008+) only supports |
| XDT for web.config, NPanday can apply it to all config files, even with other extensions than <<<*.config>>> |
| |
| By default, NPanday will transform all <<<\<name\>.config>>> files using a corresponding XDT transformation named |
| <<<\<name\>.package.config>>>. |
| |
| <<XDT currently only works with .NET 3.5 and 4.0!>> |
| |
| Read about the <<<process-configs>>> goals in the plugin reference for packaging mojos in order to find out, how you |
| tweak the config handling. |
| |
| * Take control over what gets packaged |
| |
| NPandays packaging plugins try to find sensible defaults for the required package format, but those can be overridden |
| in three different ways: |
| |
| * <<Extend:>> The simplest is to <add> files to the packaging through custom component descriptors. These can be |
| as local files, or through embedded jar resources. |
| |
| Usually this is done through the plugin configuration property <<<mixinAssemblyComponentDescriptors>>> like this: |
| |
| +---+ |
| <configuration> |
| <mixinAssemblyComponentDescriptors> |
| <mixinAssemblyComponentDescriptor>custom-assembly-component.xml</mixinAssemblyComponentDescriptor> |
| </mixinAssemblyComponentDescriptors> |
| </configuration> |
| +---+ |
| |
| And then by provide the file: <<<$basedir\custom-assembly-component.xml>>> |
| |
| +---+ |
| <component xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/component/1.1.2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
| xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/component/1.1.2 http://maven.apache.org/xsd/component-1.1.2.xsd"> |
| <fileSets> |
| <fileSet> |
| <useDefaultExcludes>true</useDefaultExcludes> |
| <directory>\${project.basedir}</directory> |
| <outputDirectory>/</outputDirectory> |
| <includes> |
| <include>copy-also.txt</include> |
| </includes> |
| </fileSet> |
| </fileSets> |
| </component> |
| +---+ |
| |
| * <<Replace:>> If the default packaging doesn't fit at all, or includes files, it shouldn't include, you |
| can completely take control over the files to include in the package: |
| |
| Configuration: |
| |
| +---+ |
| <configuration> |
| <assemblyDescriptor>custom-assembly.xml</assemblyDescriptor> |
| </configuration> |
| +---+ |
| |
| And the file: |
| |
| +---+ |
| <assembly xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2" |
| xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
| xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.2 http://maven.apache.org/xsd/assembly-1.1.2.xsd"> |
| <id>custom-assembly</id> |
| <includeBaseDirectory>false</includeBaseDirectory> |
| <formats> |
| <format>dir</format> |
| </formats> |
| <fileSets> |
| <fileSet> |
| <useDefaultExcludes>true</useDefaultExcludes> |
| <directory>\${project.basedir}</directory> |
| <outputDirectory>/</outputDirectory> |
| <includes> |
| <include>please-copy.aspx</include> |
| </includes> |
| </fileSet> |
| </fileSets> |
| </assembly> |
| +---+ |
| |
| * <<Compose:>> This is a mix of the previous two. You replace by using a custom assembly descriptor, but you then |
| use some of the component descriptors provided by NPanday: |
| |
| +---+ |
| <assembly ..> |
| [..] |
| <componentDescriptors> |
| <componentDescriptor>/assemblies/components/aspnet-webapp-binaries.xml</componentDescriptor> |
| [..] |
| </componentDescriptors> |
| [..] |
| </assembly> |
| +---+ |
| |
| |