This is an automated email from the ASF dual-hosted git repository. kwin pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/maven-deploy-plugin.git
commit 34eb16cc4fbf7ef631aff022fa34fbb1dba6b703 Author: Konrad Windszus <[email protected]> AuthorDate: Wed Sep 17 16:14:47 2025 +0200 Convert APT to Markdown --- src/site/markdown/examples/deploy-ftp.md | 74 +++++----- .../markdown/examples/deploy-network-issues.md | 141 +++++++++--------- src/site/markdown/examples/deploy-ssh-external.md | 96 ++++++------- .../examples/deploying-in-legacy-layout.md | 65 --------- .../examples/deploying-in-legacy-layout.md.vm | 59 ++++++++ .../markdown/examples/deploying-sources-javadoc.md | 52 ------- .../examples/deploying-sources-javadoc.md.vm | 45 ++++++ .../examples/deploying-with-classifiers.md | 66 --------- .../examples/deploying-with-classifiers.md.vm | 58 ++++++++ .../examples/deploying-with-customized-pom.md | 46 ------ .../examples/deploying-with-customized-pom.md.vm | 39 +++++ .../markdown/examples/disabling-generic-pom.md | 47 ------ .../markdown/examples/disabling-generic-pom.md.vm | 41 ++++++ src/site/markdown/file-deployment.md | 76 +++++----- src/site/markdown/index.md | 121 ---------------- src/site/markdown/index.md.vm | 72 ++++++++++ src/site/markdown/project-deployment.md | 70 ++++----- src/site/markdown/usage.md | 159 ++++++++------------- src/site/site.xml | 22 +-- 19 files changed, 574 insertions(+), 775 deletions(-) diff --git a/src/site/markdown/examples/deploy-ftp.md b/src/site/markdown/examples/deploy-ftp.md index efb4119..d5f81a4 100644 --- a/src/site/markdown/examples/deploy-ftp.md +++ b/src/site/markdown/examples/deploy-ftp.md @@ -1,38 +1,32 @@ - ------ - Deployment of artifacts with FTP - ------ - Jason van Zyl - ------ - 2005-10-12 - ------ +--- +title: Deployment of artifacts with FTP +author: + - Jason van Zyl +date: 2005-10-12 +--- -~~ 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. +<!-- 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.--> -~~ NOTE: For help with the syntax of this file, see: -~~ http://maven.apache.org/doxia/references/apt-format.html +# Deployment of artifacts with FTP -Deployment of artifacts with FTP +In order to deploy artifacts using FTP you must first specify the use of an FTP server in the **distributionManagement** element of your POM as well as specifying an `extension` in your `build` element which will pull in the FTP artifacts required to deploy with FTP: - In order to deploy artifacts using FTP you must first specify the use of an FTP server in the - <<distributionManagement>> element of your POM as well as specifying an <<<extension>>> in your - <<<build>>> element which will pull in the FTP artifacts required to deploy with FTP: - -+----+ +```unknown <project> ... <distributionManagement> @@ -54,12 +48,11 @@ Deployment of artifacts with FTP </build> ... </project> -+----+ +``` - Your <<<settings.xml>>> would contain a <<<server>>> element where the <<<id>>> of that element matches <<<id>>> of the - FTP repository specified in the POM above: +Your `settings.xml` would contain a `server` element where the `id` of that element matches `id` of the FTP repository specified in the POM above: -+----+ +```unknown <settings> ... <servers> @@ -71,12 +64,11 @@ Deployment of artifacts with FTP </servers> ... </settings> -+----+ +``` - You should, of course, make sure that you can login into the specified FTP server by hand before attempting the - deployment with Maven. Once you have verified that everything is setup correctly you can now deploy your artifacts - using Maven: +You should, of course, make sure that you can login into the specified FTP server by hand before attempting the deployment with Maven\. Once you have verified that everything is setup correctly you can now deploy your artifacts using Maven: -+----+ +```unknown mvn deploy -+----+ +``` + diff --git a/src/site/markdown/examples/deploy-network-issues.md b/src/site/markdown/examples/deploy-network-issues.md index eed119e..ad77b29 100644 --- a/src/site/markdown/examples/deploy-network-issues.md +++ b/src/site/markdown/examples/deploy-network-issues.md @@ -1,44 +1,38 @@ - ------ - Deploying With Network Issues - ------ - Hervé Boutemy - ------ - 2019-01-20 - ------ - -~~ 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. - -~~ NOTE: For help with the syntax of this file, see: -~~ http://maven.apache.org/doxia/references/apt-format.html - -Deploying With Network Issues - - Sometimes, network quality from building machine to the remote repository is not perfect. - Of course, improving the network would be the best solution, but it is not always possible. - - There are a few strategies to work around the network issue. - -* Configuring Multiple Tries - - Deploy plugin provides {{{../deploy-mojo.html#retryFailedDeploymentCount}<<<retryFailedDeploymentCount>>> parameter}} - to retry deployment multiple times before giving up and returning a failure for the <<<deploy>>> goal: - -+----+ +--- +title: Deploying With Network Issues +author: + - Hervé Boutemy +date: 2019-01-20 +--- + +<!-- 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.--> + +# Deploying With Network Issues + +Sometimes, network quality from building machine to the remote repository is not perfect\. Of course, improving the network would be the best solution, but it is not always possible\. + +There are a few strategies to work around the network issue\. + +## Configuring Multiple Tries + +Deploy plugin provides [`retryFailedDeploymentCount` parameter](../deploy-mojo.html#retryFailedDeploymentCount) to retry deployment multiple times before giving up and returning a failure for the `deploy` goal: + +```unknown <project> [...] <build> @@ -54,60 +48,52 @@ Deploying With Network Issues </build> [...] </project> -+----+ +``` -* Deploying to a Local Staging Directory +## Deploying to a Local Staging Directory - When the network is really not consistent, a deeper strategy is to deploy in 2 steps: +When the network is really not consistent, a deeper strategy is to deploy in 2 steps: - 1. <<<deploy>>> to a local directory during the build, for example <<<file:./target/staging-deploy>>>, +1\. `deploy` to a local directory during the build, for example `file:./target/staging-deploy`, - 2. then copy from the local area to the target remote repository, retrying as much as necessary. +2\. then copy from the local area to the target remote repository, retrying as much as necessary\. - [] +### Deploying to a Local Directory -** Deploying to a Local Directory +Deploying to a local directory can be done from command line, without changing POM, using [`altDeploymentRepository` parameter](../deploy-mojo.html#altDeploymentRepository): - Deploying to a local directory can be done from command line, without changing POM, using - {{{../deploy-mojo.html#altDeploymentRepository}<<<altDeploymentRepository>>> parameter}}: - -+----+ +```unknown mvn deploy -DaltDeploymentRepository=local::file:./target/staging-deploy -+----+ +``` - or for older 2.x version of maven-deploy-plugin +or for older 2\.x version of maven\-deploy\-plugin -+----+ +```unknown mvn deploy -DaltDeploymentRepository=local::default::file:./target/staging-deploy -+----+ - - Of course, you can configure the repository in your <<<pom.xml>>> if you want to go from a temporary strategy - to the general strategy. - -** Copying from Local Directory to Target Remote Repository - - <<<wagon-maven-plugin>>>'s {{{https://www.mojohaus.org/wagon-maven-plugin/merge-maven-repos-mojo.html}<<<merge-maven-repos>>> goal}} - provides a mechanism to copy from one remote repository to the other, while merging repository metadata. - - <<<wagon-maven-plugin>>>'s {{{https://www.mojohaus.org/wagon-maven-plugin/upload-mojo.html}<<<upload>>> goal}} - will do the same without taking care of repository metadata: use it if you have an empty repository as target, - like a staging repository provided by a repository manager. - - It can be invoked fully from command line (renaming <<<-Dwagon.>>> with <<<wagon.targetId>>> when - {{{https://github.com/mojohaus/wagon-maven-plugin/pull/26}Wagon Maven Plugin 2.0.1 will be released}}): - -+----+ +``` + +Of course, you can configure the repository in your `pom.xml` if you want to go from a temporary strategy to the general strategy\. + +### Copying from Local Directory to Target Remote Repository + +`wagon-maven-plugin`'s [`merge-maven-repos` goal](https://www.mojohaus.org/wagon-maven-plugin/merge-maven-repos-mojo.html) provides a mechanism to copy from one remote repository to the other, while merging repository metadata\. + +`wagon-maven-plugin`'s [`upload` goal](https://www.mojohaus.org/wagon-maven-plugin/upload-mojo.html) will do the same without taking care of repository metadata: use it if you have an empty repository as target, like a staging repository provided by a repository manager\. + +It can be invoked fully from command line \(renaming `-Dwagon.` with `wagon.targetId` when [Wagon Maven Plugin 2\.0\.1 will be released](https://github.com/mojohaus/wagon-maven-plugin/pull/26)\): + +```unknown mvn org.codehaus.mojo:wagon-maven-plugin:2.0.0:merge-maven-repos \ -Dwagon.source=file:./target/staging-deploy \ -Dwagon.target=https://... \ -Dwagon.=id # or once wagon-maven-plugin 2.0.1 is released: -Dwagon.targetId=id -+----+ +``` - or more simply with <<<mvn wagon:merge-maven-repos>>> with configuration in <<<pom.xml>>>: +or more simply with `mvn wagon:merge-maven-repos` with configuration in `pom.xml`: -+----+ +```unknown <project> [...] <build> @@ -126,4 +112,5 @@ mvn org.codehaus.mojo:wagon-maven-plugin:2.0.0:merge-maven-repos \ </build> [...] </project> -+----+ +``` + diff --git a/src/site/markdown/examples/deploy-ssh-external.md b/src/site/markdown/examples/deploy-ssh-external.md index 99849c9..056a769 100644 --- a/src/site/markdown/examples/deploy-ssh-external.md +++ b/src/site/markdown/examples/deploy-ssh-external.md @@ -1,38 +1,32 @@ - ------ - Deployment of artifacts in an external SSH command - ------ - Jason van Zyl - ------ - 2005-10-12 - ------ - -~~ 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. - -~~ NOTE: For help with the syntax of this file, see: -~~ http://maven.apache.org/doxia/references/apt-format.html - -Deployment of artifacts in an external SSH command - - In order to deploy artifacts using SSH you must first specify the use of an SSH server in the - <<distributionManagement>> element of your POM as well as specifying an <<<extension>>> in your - <<<build>>> element which will pull in the SSH artifacts required to deploy with SSH: - -+----+ +--- +title: Deployment of artifacts in an external SSH command +author: + - Jason van Zyl +date: 2005-10-12 +--- + +<!-- 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.--> + +# Deployment of artifacts in an external SSH command + +In order to deploy artifacts using SSH you must first specify the use of an SSH server in the **distributionManagement** element of your POM as well as specifying an `extension` in your `build` element which will pull in the SSH artifacts required to deploy with SSH: + +```unknown <project> ... @@ -55,14 +49,11 @@ Deployment of artifacts in an external SSH command </build> .. </project> +``` -+----+ +If you are deploying from Unix or have Cygwin installed you won't need to any additional configuration in your `settings.xml` file as everything will be taken from the environment\. But if you are on Windows and are using something like `plink` then you will need something like the following: - If you are deploying from Unix or have Cygwin installed you won't need to any additional configuration in your <<<settings.xml>>> - file as everything will be taken from the environment. But if you are on Windows and are using something like <<<plink>>> then - you will need something like the following: - -+----+ +```unknown <settings> ... @@ -80,21 +71,17 @@ Deployment of artifacts in an external SSH command </servers> ... </settings> +``` -+----+ - - You should, of course, make sure that you can login into the specified SSH server by hand before attempting the - deployment with Maven. Once you have verified that everything is setup correctly you can now deploy your artifacts - using Maven: +You should, of course, make sure that you can login into the specified SSH server by hand before attempting the deployment with Maven\. Once you have verified that everything is setup correctly you can now deploy your artifacts using Maven: -+----+ +```unknown mvn deploy -+----+ +``` - Sometimes you may have permissions problems deploying and if so you can set the file and directory permissions - like so: +Sometimes you may have permissions problems deploying and if so you can set the file and directory permissions like so: -+----+ +```unknown <settings> ... @@ -116,10 +103,7 @@ mvn deploy </servers> ... </settings> +``` -+----+ +**NOTE:** If you are using Putty it will expect the private key to be in the `PPK` format and not the standard format so make sure you use `puttygen` to convert your openssh format key to `PPK` format or generate another one\. Windows users can find the Putty tools on the [PuTTY Download Page](https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html)\. - <<NOTE:>> If you are using Putty it will expect the private key to be in the <<<PPK>>> format and not the standard - format so make sure you use <<<puttygen>>> to convert your openssh format key to <<<PPK>>> format or generate another - one. Windows users can find the Putty tools on the - {{{https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html}PuTTY Download Page}}. diff --git a/src/site/markdown/examples/deploying-in-legacy-layout.md b/src/site/markdown/examples/deploying-in-legacy-layout.md deleted file mode 100644 index bc9a88b..0000000 --- a/src/site/markdown/examples/deploying-in-legacy-layout.md +++ /dev/null @@ -1,65 +0,0 @@ - ------ - Deploy an artifact in legacy layout - ------ - Allan Ramirez - ------ - 2006-06-21 - ------ - -~~ 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. - -~~ NOTE: For help with the syntax of this file, see: -~~ http://maven.apache.org/doxia/references/apt-format.html - -Deploy an artifact in legacy layout - - "Legacy" is the layout used in maven 1 repositories while maven 2 uses "default". They are different - in terms of directory structure, timestamp of snapshots in default and existence of metadata files in default. - - * legacy layout directory structure: - -+---+ - groupId - |--artifactId - |--jars - `--artifact -+---+ - - * default layout directory structure: - -+---+ - groupId - |--artifactId - |--version - | `---artifact - |---metadata -+---+ - - In able to deploy an artifact in a legacy layout - of repository, set the <<repositoryLayout>> parameter to <<<legacy>>> value. - -+---+ -mvn ${project.groupId}:${project.artifactId}:${project.version}:deploy-file -Durl=file:///C:/m2-repo \ - -DrepositoryId=some.id \ - -Dfile=your-artifact-1.0.jar \ - -DpomFile=your-pom.xml \ - -DrepositoryLayout=legacy -+---+ - - <<Note>>: By using the fully qualified path of a goal, you're ensured to be using the preferred version of the maven-deploy-plugin. When using <<<mvn deploy:deploy-file>>> - its version depends on its specification in the pom or the version of Apache Maven. diff --git a/src/site/markdown/examples/deploying-in-legacy-layout.md.vm b/src/site/markdown/examples/deploying-in-legacy-layout.md.vm new file mode 100644 index 0000000..48f8116 --- /dev/null +++ b/src/site/markdown/examples/deploying-in-legacy-layout.md.vm @@ -0,0 +1,59 @@ +--- +title: Deploy an artifact in legacy layout +author: + - Allan Ramirez +date: 2006-06-21 +--- + +<!-- 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.--> + +# Deploy an artifact in legacy layout + +"Legacy" is the layout used in maven 1 repositories while maven 2 uses "default"\. They are different in terms of directory structure, timestamp of snapshots in default and existence of metadata files in default\. + +- legacy layout directory structure: + + ```unknown + groupId + |--artifactId + |--jars + `--artifact + ``` + +- default layout directory structure: + + ```unknown + groupId + |--artifactId + |--version + | `---artifact + |---metadata + ``` + + In able to deploy an artifact in a legacy layout of repository, set the **repositoryLayout** parameter to `legacy` value\. + + ```unknown + mvn ${project.groupId}:${project.artifactId}:${project.version}:deploy-file -Durl=file:///C:/m2-repo \ + -DrepositoryId=some.id \ + -Dfile=your-artifact-1.0.jar \ + -DpomFile=your-pom.xml \ + -DrepositoryLayout=legacy + ``` + + **Note**: By using the fully qualified path of a goal, you're ensured to be using the preferred version of the maven\-deploy\-plugin\. When using `mvn deploy:deploy-file` its version depends on its specification in the pom or the version of Apache Maven\. + diff --git a/src/site/markdown/examples/deploying-sources-javadoc.md b/src/site/markdown/examples/deploying-sources-javadoc.md deleted file mode 100644 index 4a7a406..0000000 --- a/src/site/markdown/examples/deploying-sources-javadoc.md +++ /dev/null @@ -1,52 +0,0 @@ - ---- - Deploy sources and javadocs for an artifact - ------ - ------ - 20011-02-23 - ------ - -~~ 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. - -~~ NOTE: For help with the syntax of this file, see: -~~ http://maven.apache.org/doxia/references/apt-format.html - -Deploy sources and javadoc jars - - A project may include a main jar and associated sources and javadoc jars. - -+---+ - artifact-name-1.0.jar - artifact-name-1.0-sources.jar - artifact-name-1.0-javadoc.jar -+---+ - - The sources jar contains the Java sources, and the javadoc jar contains the generated javadocs. - To include these files in your deployment, set the <<sources>> and <<javadoc>> parameters to - the paths to the sources and javadoc jar files. - -+---+ -mvn ${project.groupId}:${project.artifactId}:${project.version}:deploy-file -Durl=file:///home/me/m2-repo \ - -DrepositoryId=some.repo.id \ - -Dfile=./path/to/artifact-name-1.0.jar \ - -DpomFile=./path/to/pom.xml \ - -Dsources=./path/to/artifact-name-1.0-sources.jar \ - -Djavadoc=./path/to/artifact-name-1.0-javadoc.jar -+---+ - - <<Note>>: By using the fully qualified path of a goal, you're ensured to be using the preferred version of the maven-deploy-plugin. When using <<<mvn deploy:deploy-file>>> - its version depends on its specification in the pom or the version of Apache Maven. diff --git a/src/site/markdown/examples/deploying-sources-javadoc.md.vm b/src/site/markdown/examples/deploying-sources-javadoc.md.vm new file mode 100644 index 0000000..88f7f2b --- /dev/null +++ b/src/site/markdown/examples/deploying-sources-javadoc.md.vm @@ -0,0 +1,45 @@ +--- +title: Deploy sources and javadocs for an artifact +date: 20011-02-23 +--- + +<!-- 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.--> + +# Deploy sources and javadoc jars + +A project may include a main jar and associated sources and javadoc jars\. + +```unknown + artifact-name-1.0.jar + artifact-name-1.0-sources.jar + artifact-name-1.0-javadoc.jar +``` + +The sources jar contains the Java sources, and the javadoc jar contains the generated javadocs\. To include these files in your deployment, set the **sources** and **javadoc** parameters to the paths to the sources and javadoc jar files\. + +```unknown +mvn ${project.groupId}:${project.artifactId}:${project.version}:deploy-file -Durl=file:///home/me/m2-repo \ + -DrepositoryId=some.repo.id \ + -Dfile=./path/to/artifact-name-1.0.jar \ + -DpomFile=./path/to/pom.xml \ + -Dsources=./path/to/artifact-name-1.0-sources.jar \ + -Djavadoc=./path/to/artifact-name-1.0-javadoc.jar +``` + +**Note**: By using the fully qualified path of a goal, you're ensured to be using the preferred version of the maven\-deploy\-plugin\. When using `mvn deploy:deploy-file` its version depends on its specification in the pom or the version of Apache Maven\. + diff --git a/src/site/markdown/examples/deploying-with-classifiers.md b/src/site/markdown/examples/deploying-with-classifiers.md deleted file mode 100644 index ce3cb22..0000000 --- a/src/site/markdown/examples/deploying-with-classifiers.md +++ /dev/null @@ -1,66 +0,0 @@ - ---- - Deploy an artifact with classifier - ------ - Robert Scholte - ------ - 2013-09-01 - ------ - -~~ 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. - -~~ NOTE: For help with the syntax of this file, see: -~~ http://maven.apache.org/doxia/references/apt-format.html - -Deploy an artifact with classifier - - Beside the main artifact there can be additional files which are attached to the Maven project. Such attached files can be recognized and accessed by their classifier. - - For example: from the following artifact names, the classifier is located between the version and extension name of the artifact. - - * <<<artifact-name-1.0.jar>>> the main jar which contains classes compiled without {{{https://maven.apache.org/plugins/maven-compiler-plugin/compile-mojo.html#debug}debugging}} information (such as linenumbers) - - * <<<artifact-name-1.0-debug.jar>>> the classified jar which contains classes compiled with {{{https://maven.apache.org/plugins/maven-compiler-plugin/compile-mojo.html#debug}debugging}} information, so will be larger - - * <<<artifact-name-1.0-site.pdf>>> a pdf which contains an export of the site documentation. - - [] - - You can deploy the main artifact and the classified artifacts in a single run. Let's assume the original filename for the documentation is <<<site.pdf>>>: - -+---+ -mvn ${project.groupId}:${project.artifactId}:${project.version}:deploy-file -Durl=http://localhost:8081/repomanager/ \ - -DrepositoryId=some.id \ - -Dfile=path/to/artifact-name-1.0.jar \ - -DpomFile=path-to-your-pom.xml \ - -Dfiles=path/to/artifact-name-1.0-debug.jar,path/to/site.pdf \ - -Dclassifiers=debug,site \ - -Dtypes=jar,pdf -+---+ - - If you only want to deploy the <<<debug>>>-jar and want to keep the classifier, you can execute the <<<deploy-file>>> like - -+---+ -mvn ${project.groupId}:${project.artifactId}:${project.version}:deploy-file -Durl=http://localhost:8081/repomanager/ \ - -DrepositoryId=some.id \ - -Dfile=path-to-your-artifact-jar \ - -DpomFile=path-to-your-pom.xml \ - -Dclassifier=bin -+---+ - - <<Note>>: By using the fully qualified path of a goal, you're ensured to be using the preferred version of the maven-deploy-plugin. When using <<<mvn deploy:deploy-file>>> - its version depends on its specification in the pom or the version of Apache Maven. diff --git a/src/site/markdown/examples/deploying-with-classifiers.md.vm b/src/site/markdown/examples/deploying-with-classifiers.md.vm new file mode 100644 index 0000000..7b12b67 --- /dev/null +++ b/src/site/markdown/examples/deploying-with-classifiers.md.vm @@ -0,0 +1,58 @@ +--- +title: Deploy an artifact with classifier +author: + - Robert Scholte +date: 2013-09-01 +--- + +<!-- 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.--> + +# Deploy an artifact with classifier + +Beside the main artifact there can be additional files which are attached to the Maven project\. Such attached files can be recognized and accessed by their classifier\. + +For example: from the following artifact names, the classifier is located between the version and extension name of the artifact\. + +- `artifact-name-1.0.jar` the main jar which contains classes compiled without [debugging](https://maven.apache.org/plugins/maven-compiler-plugin/compile-mojo.html#debug) information \(such as linenumbers\) +- `artifact-name-1.0-debug.jar` the classified jar which contains classes compiled with [debugging](https://maven.apache.org/plugins/maven-compiler-plugin/compile-mojo.html#debug) information, so will be larger +- `artifact-name-1.0-site.pdf` a pdf which contains an export of the site documentation\. + +You can deploy the main artifact and the classified artifacts in a single run\. Let's assume the original filename for the documentation is `site.pdf`: + +```unknown +mvn ${project.groupId}:${project.artifactId}:${project.version}:deploy-file -Durl=http://localhost:8081/repomanager/ \ + -DrepositoryId=some.id \ + -Dfile=path/to/artifact-name-1.0.jar \ + -DpomFile=path-to-your-pom.xml \ + -Dfiles=path/to/artifact-name-1.0-debug.jar,path/to/site.pdf \ + -Dclassifiers=debug,site \ + -Dtypes=jar,pdf +``` + +If you only want to deploy the `debug`\-jar and want to keep the classifier, you can execute the `deploy-file` like + +```unknown +mvn ${project.groupId}:${project.artifactId}:${project.version}:deploy-file -Durl=http://localhost:8081/repomanager/ \ + -DrepositoryId=some.id \ + -Dfile=path-to-your-artifact-jar \ + -DpomFile=path-to-your-pom.xml \ + -Dclassifier=bin +``` + +**Note**: By using the fully qualified path of a goal, you're ensured to be using the preferred version of the maven\-deploy\-plugin\. When using `mvn deploy:deploy-file` its version depends on its specification in the pom or the version of Apache Maven\. + diff --git a/src/site/markdown/examples/deploying-with-customized-pom.md b/src/site/markdown/examples/deploying-with-customized-pom.md deleted file mode 100644 index 9e6654a..0000000 --- a/src/site/markdown/examples/deploying-with-customized-pom.md +++ /dev/null @@ -1,46 +0,0 @@ - ---- - Deploy an artifact with a customized pom - ------ - Allan Ramirez - ------ - 2006-06-21 - ------ - -~~ 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. - -~~ NOTE: For help with the syntax of this file, see: -~~ http://maven.apache.org/doxia/references/apt-format.html - -Deploy an artifact with a customized pom - - If there is already an existing pom and want it to be deployed together with the 3rd party artifact, - set the <<pomFile>> parameter to the path of the pom.xml. - -+---+ -mvn ${project.groupId}:${project.artifactId}:${project.version}:deploy-file -Durl=file:///C:/m2-repo \ - -DrepositoryId=some.id \ - -Dfile=path-to-your-artifact-jar \ - -DpomFile=path-to-your-pom.xml -+---+ - - Note that the groupId, artifactId, version and packaging informations are automatically retrieved from the - given pom. - - <<Note>>: By using the fully qualified path of a goal, you're ensured to be using the preferred version of the maven-deploy-plugin. When using <<<mvn deploy:deploy-file>>> - its version depends on its specification in the pom or the version of Apache Maven. - diff --git a/src/site/markdown/examples/deploying-with-customized-pom.md.vm b/src/site/markdown/examples/deploying-with-customized-pom.md.vm new file mode 100644 index 0000000..33dce41 --- /dev/null +++ b/src/site/markdown/examples/deploying-with-customized-pom.md.vm @@ -0,0 +1,39 @@ +--- +title: Deploy an artifact with a customized pom +author: + - Allan Ramirez +date: 2006-06-21 +--- + +<!-- 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.--> + +# Deploy an artifact with a customized pom + +If there is already an existing pom and want it to be deployed together with the 3rd party artifact, set the **pomFile** parameter to the path of the pom\.xml\. + +```unknown +mvn ${project.groupId}:${project.artifactId}:${project.version}:deploy-file -Durl=file:///C:/m2-repo \ + -DrepositoryId=some.id \ + -Dfile=path-to-your-artifact-jar \ + -DpomFile=path-to-your-pom.xml +``` + +Note that the groupId, artifactId, version and packaging informations are automatically retrieved from the given pom\. + +**Note**: By using the fully qualified path of a goal, you're ensured to be using the preferred version of the maven\-deploy\-plugin\. When using `mvn deploy:deploy-file` its version depends on its specification in the pom or the version of Apache Maven\. + diff --git a/src/site/markdown/examples/disabling-generic-pom.md b/src/site/markdown/examples/disabling-generic-pom.md deleted file mode 100644 index 2d23e9f..0000000 --- a/src/site/markdown/examples/disabling-generic-pom.md +++ /dev/null @@ -1,47 +0,0 @@ - ---- - Disable the generation of pom - ------ - Allan Ramirez - ------ - 2006-06-21 - ------ - -~~ 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. - -~~ NOTE: For help with the syntax of this file, see: -~~ http://maven.apache.org/doxia/references/apt-format.html - -Disable the generation of pom - - By default, If no pom is specified during deployment of your 3rd party artifact, a generic pom will be generated - which contains the minimum required elements needed for the pom. In order to disable it, set the - <<generatePom>> parameter to <<<false>>>. - -+---+ -mvn ${project.groupId}:${project.artifactId}:${project.version}:deploy-file -Durl=file:///C:/m2-repo \ - -DrepositoryId=some.id \ - -Dfile=path-to-your-artifact-jar \ - -DgroupId=your.groupId \ - -DartifactId=your-artifactId \ - -Dversion=version \ - -Dpackaging=jar \ - -DgeneratePom=false -+---+ - - <<Note>>: By using the fully qualified path of a goal, you're ensured to be using the preferred version of the maven-deploy-plugin. When using <<<mvn deploy:deploy-file>>> - its version depends on its specification in the pom or the version of Apache Maven. diff --git a/src/site/markdown/examples/disabling-generic-pom.md.vm b/src/site/markdown/examples/disabling-generic-pom.md.vm new file mode 100644 index 0000000..863576a --- /dev/null +++ b/src/site/markdown/examples/disabling-generic-pom.md.vm @@ -0,0 +1,41 @@ +--- +title: Disable the generation of pom +author: + - Allan Ramirez +date: 2006-06-21 +--- + +<!-- 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.--> + +# Disable the generation of pom + +By default, If no pom is specified during deployment of your 3rd party artifact, a generic pom will be generated which contains the minimum required elements needed for the pom\. In order to disable it, set the **generatePom** parameter to `false`\. + +```unknown +mvn ${project.groupId}:${project.artifactId}:${project.version}:deploy-file -Durl=file:///C:/m2-repo \ + -DrepositoryId=some.id \ + -Dfile=path-to-your-artifact-jar \ + -DgroupId=your.groupId \ + -DartifactId=your-artifactId \ + -Dversion=version \ + -Dpackaging=jar \ + -DgeneratePom=false +``` + +**Note**: By using the fully qualified path of a goal, you're ensured to be using the preferred version of the maven\-deploy\-plugin\. When using `mvn deploy:deploy-file` its version depends on its specification in the pom or the version of Apache Maven\. + diff --git a/src/site/markdown/file-deployment.md b/src/site/markdown/file-deployment.md index ca21471..c234af6 100644 --- a/src/site/markdown/file-deployment.md +++ b/src/site/markdown/file-deployment.md @@ -1,43 +1,33 @@ - ---- - Project Deployment - ------ - Allan Ramirez - ------ - 2006-07-14 - ------ - -~~ 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. - -~~ NOTE: For help with the syntax of this file, see: -~~ http://maven.apache.org/doxia/references/apt-format.html - -File Deployment - - Here are examples of using the deploy plugin for file deployment: - - * {{{./examples/disabling-generic-pom.html}Disable the generation of pom}} - - * {{{./examples/deploying-with-customized-pom.html}Deploy an artifact with a customized pom}} - - * {{{./examples/deploying-with-classifiers.html}Deploy an artifact with classifier}} - - * {{{./examples/deploying-sources-javadoc.html}Deploy an artifact with sources and javadoc jars}} - - * {{{./examples/deploying-in-legacy-layout.html}Deploy an artifact in legacy layout}} - - [] +--- +title: Project Deployment +author: + - Allan Ramirez +date: 2006-07-14 +--- + +<!-- 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.--> + +# File Deployment + +Here are examples of using the deploy plugin for file deployment: + +- [Disable the generation of pom](./examples/disabling-generic-pom.html) +- [Deploy an artifact with a customized pom](./examples/deploying-with-customized-pom.html) +- [Deploy an artifact with classifier](./examples/deploying-with-classifiers.html) +- [Deploy an artifact with sources and javadoc jars](./examples/deploying-sources-javadoc.html) +- [Deploy an artifact in legacy layout](./examples/deploying-in-legacy-layout.html) diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md deleted file mode 100644 index a52dca9..0000000 --- a/src/site/markdown/index.md +++ /dev/null @@ -1,121 +0,0 @@ - ------ - Introduction - ------ - Jerome Lacoste - ------ - 2013-07-22 - ------ - -~~ 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. - -~~ NOTE: For help with the syntax of this file, see: -~~ http://maven.apache.org/doxia/references/apt-format.html - -${project.name} - - The deploy plugin is primarily used during the deploy phase, to add your - artifact(s) to a remote repository for sharing with other developers and - projects. This is usually done in an integration or release environment. It can - also be used to deploy a particular artifact (e.g. a third party jar like - Sun's non redistributable reference implementations). - - As a repository contains more than JAR files (POMs, the metadata, MD5 and - SHA1 hash files...), deploying means not only uploading a single file, but - making sure all associated artifacts are correctly updated as well. - This is the reponsibility of the deploy plugin. - - To work, the deployment will require: - - * information about the repository: its location, the transport method used to - access it (FTP, SCP, SFTP...) and the optional user specific required - account information - - * information about the artifact(s): the group, artifact, version, packaging, - classifier... - - * a deployer: a method to actually perform the deployment. This can be - implemented as a wagon transport (making it cross-platform), or use a system - specific method. - - [] - - The information will be taken from the implied (or specified) pom and from the - command line. The settings.xml file may also be parsed to retrieve user - credentials. - - -* Goals Overview - - The deploy plugin has 2 goals: - - * {{{./deploy-mojo.html}deploy:deploy}} is used to automatically install the - artifact, its pom, and the attached artifacts produced by a particular - project. Most if not all of the information related to the deployment is stored - in the project's pom. - - * {{{./deploy-file-mojo.html}deploy:deploy-file}} is used to install a single artifact - along with its pom. In that case, the artifact information can be taken from - an optionally specified pomFile, but can be completed/overridden using the - command line. - - [] - -* Usage - - General instructions on how to use the Deploy Plugin can be found on the {{{./usage.html}usage page}}. Some more - specific use cases are described in the examples given below. - - If you have questions about the plugin's usage, please read the {{{./faq.html}FAQ}} and feel - free to contact the {{{./mailing-lists.html}user mailing list}}. Posts to the mailing list are archived and could - already contain the answer to your question as part of an older thread. Hence, it is also worth browsing/searching - the {{{./mailing-lists.html}mail archive}}. - - If you think the plugin is missing a feature or has a defect, you can file a feature request or bug report in our - {{{./issue-management.html}issue tracker}}. When creating a new issue, please provide a comprehensive description of your - concern. Especially for fixing bugs, it is crucial that the developers can reproduce your problem. For this reason, - entire debug logs, POMs, or most preferably little demo projects attached to the issue are very much appreciated. - Of course, patches are welcome, too. Contributors can check out the project from our - {{{./scm.html}source repository}} and will find supplementary information in the - {{{https://maven.apache.org/guides/development/guide-helping.html}guide to helping with Maven}}. - -* Examples - - To provide you with better understanding on some usages of the deploy plugin, - you can see the following examples: - - <Project Deployment:> - - * {{{./examples/deploy-ftp.html}Deployment with FTP}} - - * {{{./examples/deploy-ssh-external.html}Deployment with external SSH}} - - * {{{./examples/deploy-network-issues.html}Workarounds when there are network issues}} - - [] - - <File Deployment:> - - * {{{./examples/disabling-generic-pom.html}Disable the generation of pom}} - - * {{{./examples/deploying-with-customized-pom.html}Deploy an artifact with a customized pom}} - - * {{{./examples/deploying-with-classifiers.html}Deploy an artifact with classifier}} - - * {{{./examples/deploying-in-legacy-layout.html}Deploy an artifact in legacy layout}} - - [] diff --git a/src/site/markdown/index.md.vm b/src/site/markdown/index.md.vm new file mode 100644 index 0000000..17d2cbb --- /dev/null +++ b/src/site/markdown/index.md.vm @@ -0,0 +1,72 @@ +--- +title: Introduction +author: + - Jerome Lacoste +date: 2013-07-22 +--- + +<!-- 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.--> + +# ${project.name} + +The deploy plugin is primarily used during the deploy phase, to add your artifact\(s\) to a remote repository for sharing with other developers and projects\. This is usually done in an integration or release environment\. It can also be used to deploy a particular artifact \(e\.g\. a third party jar like Sun's non redistributable reference implementations\)\. + +As a repository contains more than JAR files \(POMs, the metadata, MD5 and SHA1 hash files\.\.\.\), deploying means not only uploading a single file, but making sure all associated artifacts are correctly updated as well\. This is the reponsibility of the deploy plugin\. + +To work, the deployment will require: + +- information about the repository: its location, the transport method used to access it \(FTP, SCP, SFTP\.\.\.\) and the optional user specific required account information +- information about the artifact\(s\): the group, artifact, version, packaging, classifier\.\.\. +- a deployer: a method to actually perform the deployment\. This can be implemented as a wagon transport \(making it cross\-platform\), or use a system specific method\. + +The information will be taken from the implied \(or specified\) pom and from the command line\. The settings\.xml file may also be parsed to retrieve user credentials\. + +Goals Overview +------- + +The deploy plugin has 2 goals: + +- [deploy:deploy](./deploy-mojo.html) is used to automatically install the artifact, its pom, and the attached artifacts produced by a particular project\. Most if not all of the information related to the deployment is stored in the project's pom\. +- [deploy:deploy\-file](./deploy-file-mojo.html) is used to install a single artifact along with its pom\. In that case, the artifact information can be taken from an optionally specified pomFile, but can be completed/overridden using the command line\. + +Usage +------- + +General instructions on how to use the Deploy Plugin can be found on the [usage page](./usage.html)\. Some more specific use cases are described in the examples given below\. + +If you have questions about the plugin's usage, please read the [FAQ](./faq.html) and feel free to contact the [user mailing list](./mailing-lists.html)\. Posts to the mailing list are archived and could already contain the answer to your question as part of an older thread\. Hence, it is also worth browsing/searching the [mail archive](./mailing-lists.html)\. + +If you think the plugin is missing a feature or has a defect, you can file a feature request or bug report in our [issue tracker](./issue-management.html)\. When creating a new issue, please provide a comprehensive description of your concern\. Especially for fixing bugs, it is crucial that the developers can reproduce your problem\. For this reason, entire debug logs, POMs, or most preferably little demo projects attached to the issue are very much appreciated\. Of course, patches are w [...] + +Examples +-------- + +To provide you with better understanding on some usages of the deploy plugin, you can see the following examples: + +_Project Deployment:_ + +- [Deployment with FTP](./examples/deploy-ftp.html) +- [Deployment with external SSH](./examples/deploy-ssh-external.html) +- [Workarounds when there are network issues](./examples/deploy-network-issues.html) + +_File Deployment:_ + +- [Disable the generation of pom](./examples/disabling-generic-pom.html) +- [Deploy an artifact with a customized pom](./examples/deploying-with-customized-pom.html) +- [Deploy an artifact with classifier](./examples/deploying-with-classifiers.html) +- [Deploy an artifact in legacy layout](./examples/deploying-in-legacy-layout.html) diff --git a/src/site/markdown/project-deployment.md b/src/site/markdown/project-deployment.md index c462e70..b9860cb 100644 --- a/src/site/markdown/project-deployment.md +++ b/src/site/markdown/project-deployment.md @@ -1,39 +1,31 @@ - ---- - Project Deployment - ------ - Allan Ramirez - ------ - 2006-07-14 - ------ - -~~ 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. - -~~ NOTE: For help with the syntax of this file, see: -~~ http://maven.apache.org/doxia/references/apt-format.html - -Project Deployment - - Here are examples of using the deploy plugin for project deployment: - - * {{{./examples/deploy-ftp.html}Deployment with FTP}} - - * {{{./examples/deploy-ssh-external.html}Deployment with external SSH}} - - * {{{./examples/deploy-network-issues.html}Workarounds when there are network issues}} - - [] \ No newline at end of file +--- +title: Project Deployment +author: + - Allan Ramirez +date: 2006-07-14 +--- + +<!-- 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.--> + +# Project Deployment + +Here are examples of using the deploy plugin for project deployment: + +- [Deployment with FTP](./examples/deploy-ftp.html) +- [Deployment with external SSH](./examples/deploy-ssh-external.html) +- [Workarounds when there are network issues](./examples/deploy-network-issues.html) diff --git a/src/site/markdown/usage.md b/src/site/markdown/usage.md index baaf7a9..ed8cad6 100644 --- a/src/site/markdown/usage.md +++ b/src/site/markdown/usage.md @@ -1,63 +1,43 @@ - ------ - Usage - ------ - Jerome Lacoste - John Casey - ------ - 2006-01-29 - ------ - -~~ 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. - -~~ NOTE: For help with the syntax of this file, see: -~~ http://maven.apache.org/doxia/references/apt-format.html - -Usage - -* Introduction - - The Deploy Plugin has two basic functions. In most project builds, the - <<<deploy>>> phase of the build lifecycle is implemented using the - <<<deploy:deploy>>> mojo. Also, artifacts which are not built using Maven can - be added to any remote repository using the <<<deploy:deploy-file>>> mojo. - -* The <<<deploy:deploy>>> Mojo - - In most cases, this mojo is invoked when you call the <<<deploy>>> phase of - the default build lifecycle. - - To enable this mojo to function, you must include a valid - <<<\<distributionManagement/\>>>> section POM, which at the minimum provides a - <<<\<repository/\>>>> defining the remote repository location for your - artifact. To separate snapshot artifacts from release artifacts, you can also - specify a <<<\<snapshotRepository/\>>>> location. Finally, to deploy a project - website, you must specify a <<<\<site/\>>>> section here as well. It's also - important to note that this section can be inherited, allowing you to specify - the deployment location one time for a set of related projects. - - If your repository is secured, you may also want to configure your - <<<settings.xml>>> file to define corresponding <<<\<server/\>>>> entries - which provides authentication information. Server entries are matched to the - different parts of the distributionManagement using their <<<\<id/\>>>> - elements. For example, your project may have a distributionManagement section - similar to the following: - -+---+ +--- +title: Usage +author: + - Jerome Lacoste + - John Casey +date: 2006-01-29 +--- + +<!-- 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.--> + +# Usage + +## Introduction + +The Deploy Plugin has two basic functions\. In most project builds, the `deploy` phase of the build lifecycle is implemented using the `deploy:deploy` mojo\. Also, artifacts which are not built using Maven can be added to any remote repository using the `deploy:deploy-file` mojo\. + +## The `deploy:deploy` Mojo + +In most cases, this mojo is invoked when you call the `deploy` phase of the default build lifecycle\. + +To enable this mojo to function, you must include a valid `<distributionManagement/>` section POM, which at the minimum provides a `<repository/>` defining the remote repository location for your artifact\. To separate snapshot artifacts from release artifacts, you can also specify a `<snapshotRepository/>` location\. Finally, to deploy a project website, you must specify a `<site/>` section here as well\. It's also important to note that this section can be inherited, allowing you [...] + +If your repository is secured, you may also want to configure your `settings.xml` file to define corresponding `<server/>` entries which provides authentication information\. Server entries are matched to the different parts of the distributionManagement using their `<id/>` elements\. For example, your project may have a distributionManagement section similar to the following: + +```unknown [...] <distributionManagement> <repository> @@ -67,13 +47,11 @@ Usage </repository> </distributionManagement> [...] -+---+ +``` - In this case, you can specify a server definition in your <<<settings.xml>>> - to provide authentication information for both of these repositories at once. - Your server section might look like this: +In this case, you can specify a server definition in your `settings.xml` to provide authentication information for both of these repositories at once\. Your server section might look like this: -+---+ +```unknown [...] <server> <id>internal.repo</id> @@ -81,33 +59,21 @@ Usage <password>foobar</password> </server> [...] -+---+ +``` - Please see the article about - {{{https://maven.apache.org/guides/mini/guide-encryption.html}Password Encryption}} - for instructions on how to avoid clear text passwords in the <<<settings.xml>>>. +Please see the article about [Password Encryption](https://maven.apache.org/guides/mini/guide-encryption.html) for instructions on how to avoid clear text passwords in the `settings.xml`\. - Once you've configured your repository deployment information correctly - deploying your project's artifact will only require invocation of the - <<<deploy>>> phase of the build: +Once you've configured your repository deployment information correctly deploying your project's artifact will only require invocation of the `deploy` phase of the build: -+---+ +```unknown mvn deploy -+---+ +``` +## The `deploy:deploy-file` Mojo -* The <<<deploy:deploy-file>>> Mojo +The `deploy:deploy-file` mojo is used primarily for deploying artifacts, which were not built by Maven\. The project's development team may or may not provide a POM for the artifact, and in some cases you may want to deploy the artifact to an internal remote repository\. The deploy\-file mojo provides functionality covering all of these use cases, and offers a wide range of configurability for generating a POM on\-the\-fly\. Additionally, you can specify what layout your repository [...] - The <<<deploy:deploy-file>>> mojo is used primarily for deploying artifacts, - which were not built by Maven. The project's development team may or may not - provide a POM for the artifact, and in some cases you may want to deploy the - artifact to an internal remote repository. The deploy-file mojo provides - functionality covering all of these use cases, and offers a wide range of - configurability for generating a POM on-the-fly. Additionally, you can specify - what layout your repository uses. The full usage statement of the deploy-file - mojo can be described as: - -+---+ +```unknown mvn deploy:deploy-file -Durl=file://C:\m2-repo \ -DrepositoryId=some.id \ -Dfile=your-artifact-1.0.jar \ @@ -120,23 +86,10 @@ mvn deploy:deploy-file -Durl=file://C:\m2-repo \ [-DgeneratePom=true] \ [-DgeneratePom.description="My Project Description"] \ [-DrepositoryLayout=legacy] -+---+ - - If the following required information is not specified in some way, the goal - will fail: - - * the artifact file to deploy - - * the group, artifact, version and packaging of the file to deploy. These can - be taken from the specified pomFile, and overriden or specified using the - command line. When the pomFile contains a <parent> section, the parent's - groupId can be considered if the groupId is not specified further for the - current project or on the command line. - - * the repository information: the url to deploy to and the repositoryId - mapping to a server section in the settings.xml file. If you don't specify a - repositoryId, Maven will try to extract authentication information using the - id <<<'remote-repository'>>>. +``` - [] +If the following required information is not specified in some way, the goal will fail: +- the artifact file to deploy +- the group, artifact, version and packaging of the file to deploy\. These can be taken from the specified pomFile, and overriden or specified using the command line\. When the pomFile contains a _parent_ section, the parent's groupId can be considered if the groupId is not specified further for the current project or on the command line\. +- the repository information: the url to deploy to and the repositoryId mapping to a server section in the settings\.xml file\. If you don't specify a repositoryId, Maven will try to extract authentication information using the id `'remote-repository'`\. diff --git a/src/site/site.xml b/src/site/site.xml index d580087..42f093a 100644 --- a/src/site/site.xml +++ b/src/site/site.xml @@ -19,24 +19,8 @@ specific language governing permissions and limitations under the License. --> -<project xmlns="http://maven.apache.org/DECORATION/1.0.0"; - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; - xsi:schemaLocation="http://maven.apache.org/DECORATION/1.0.0 http://maven.apache.org/xsd/decoration-1.0.0.xsd";> - <bannerLeft> - <src>https://maven.apache.org/images/apache-maven-project.png</src> - <href>https://www.apache.org/</href> - </bannerLeft> - - <bannerRight> - <src>https://maven.apache.org/images/maven-logo-black-on-white.png</src> - <href>https://maven.apache.org/</href> - </bannerRight> - <skin> - <groupId>org.apache.maven.skins</groupId> - <artifactId>maven-fluido-skin</artifactId> - <version>1.10.0</version> - </skin> - +<site xmlns="http://maven.apache.org/SITE/2.0.0"; xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xsi:schemaLocation="http://maven.apache.org/SITE/2.0.0 https://maven.apache.org/xsd/site-2.0.0.xsd";> <custom> <fluidoSkin> <sourceLineNumbersEnabled>true</sourceLineNumbersEnabled> @@ -71,4 +55,4 @@ under the License. </item> </menu> </body> -</project> +</site>
