You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@maven.apache.org by br...@apache.org on 2005/01/31 12:29:55 UTC
svn commit: r149240 - maven/maven-1/core/trunk/xdocs/using/repositories.xml
Author: brett
Date: Mon Jan 31 03:29:53 2005
New Revision: 149240
URL: http://svn.apache.org/viewcvs?view=rev&rev=149240
Log:
repository doco
Modified:
maven/maven-1/core/trunk/xdocs/using/repositories.xml
Modified: maven/maven-1/core/trunk/xdocs/using/repositories.xml
URL: http://svn.apache.org/viewcvs/maven/maven-1/core/trunk/xdocs/using/repositories.xml?view=diff&r1=149239&r2=149240
==============================================================================
--- maven/maven-1/core/trunk/xdocs/using/repositories.xml (original)
+++ maven/maven-1/core/trunk/xdocs/using/repositories.xml Mon Jan 31 03:29:53 2005
@@ -26,92 +26,99 @@
</properties>
<body>
-
-<!-- TODO
- <section name="Remote Repository Layout">
+ <section name="Artifact Repositories">
<p>
- This document outlines the layout of Maven's remote repositories.
- Currently, the primary repository is housed at
- <a href="http://www.ibiblio.org/maven/">here</a> at Ibiblio, but you
- may create an use your own remote repositories provided they adhere
- to the structure outlined in this document.
+ A repository (<A href="../reference/glossary.html#Repository">definition</a>) in Maven is used to
+ hold build artifacts and dependencies of varying types.
</p>
-
<p>
- Every separate project has its own directory in the repository where
- artifacts for that project can be stored. Each project has a unique
- project id and directory where a project stores its artifacts is named
- after the project id.
+ There are strictly only two types of repositories: local and remote. The local repository refers to a copy
+ on your own installation that is a cache of the remote downloads, and also contains the temporary
+ build artifacts that you have not yet released.
</p>
-
<p>
- Within a project's directory various types of artifacts may be stored.
- Currently, the two most common types are JARs and distributions.
- Below is a little snapshot of what the remote repository looks like:
+ Remote repositories refer to any other type of repository, accessed by a variety of protocols such as
+ <code>file://</code> and <code>http://</code>. These repositories might be a truely remote repository
+ set up by a third party to provide their artifacts for downloading (for example,
+ <a href="http://www.ibiblio.org/maven/">Ibiblio</a> houses Maven's central repository).
+ Other "remote" repositories may be <a href="../reference/internal-repositories.html">internal repositories</a>
+ set up on a file or HTTP server within your company, used to share private artifacts between development teams
+ and for releases.
+ </p>
+ <p>
+ The local and remote repositories are structured the same way so that scripts can easily be run on either
+ side, or they can be synced for offline used. In general use, the layout of the repositories is completely
+ transparent to the Maven user, however.
</p>
-
-<source><![CDATA[
-repository
- |
- |- ant
- | |- distribution
- | `- jars
- | |- ant-1.4.1.jar
- | `- ant-optional-1.4.1.jar
- +- jsse
- |- distribution
- `- jars
- |- jsse.jar
- |- jcert.jar
- `- jnet.jar
-]]></source>
-
</section>
- <section name="Local Repository Layout">
+ <section name="Why not Store JARs in CVS?">
+ <p>
+ It is not recommended that you store your JARs in CVS. Maven tries to
+ promote the notion of a user local repository where JARs, or any
+ project artifacts, can be stored and used for any number of builds.
+ Many projects have dependencies such as XML parsers and standard utilities that
+ are often replicated in typical builds. With Maven these standard utilities
+ can be stored in your local repository and shared by any number of builds.
+ </p>
<p>
- There is a very minimally implemented set of interfaces that allow the
- structuring of the local repository in an arbitrary fashion. This has
- barely been fleshed and I am only using one class in the package
- directly at the moment. I still think the local and remote repositories
- should be structured the same, but in an attempt to make users happy I
- started a set of interfaces that will allow someone to layout their
- local side anyway they like and still interface with the remote repos in
- a consistent way. Though currently it is still required to have your
- local repository structured in the same way as the remote repository.
- I'm hoping that more user feedback will drive the completion of the
- interfaces or allow them to be dropped all together.
+ This has the following advantages:
</p>
+ <ul>
+ <li><b>It uses less storage</b> - while a repository is typically quite large, because each JAR is only kept
+ in the one place it is actually saving space, even though it may not seem that way</li>
+ <li><b>It makes checking out a project quicker</b> - initial checkout, and to a small degree updating, a
+ project will be faster if there are no large binary files in CVS. While they may need to be downloaded
+ again afterwards anyway, this only happens once and may not be necessary for some common JARs already in
+ place.</li>
+ <li><b>No need for versioning</b> - CVS and other source control systems are designed for versioning files,
+ but external dependencies typically don't change, or if they do their filename changes anyway to indicate the
+ new version. Storing these in CVS doesn't have any added benefit over keeping them in a local artifact
+ cache.</li>
+ </ul>
</section>
- <section name="Building">
+ <section name="Using Repositories">
<p>
- Maven works using the notion of a central repository. All artifacts
- required for building are drawn from the central repository. Currently
- our central repository is housed
- <a href="http://www.ibiblio.org/maven">here</a> at
- <a href="http://www.ibiblio.org">Ibiblio</a>. In a typical Maven project,
- the JARs required to build a project are pulled from the central
- repository. Maven will only retrieve dependencies which are not
- satisfied. If you are using Maven to build several projects it is
- likely that those projects share a few dependencies: Maven will let
- you share one JAR file between any number of projects that require
- that JAR to build. No multiple copies of the same JAR on your
- system!
+ In general, you should not need to do anything with the local repository on a regular basis, except clean
+ it out if you are short on disk space (or erase it completely if you are willing to download everything again).
</p>
-
- <subsection name="Storing JARs in CVS">
+ <p>
+ For the remote repositories, they are used for both downloading and uploading (if you have the permission to
+ do so).
+ </p>
+ <subsection name="Downloading from a Remote Repository">
<p>
- It is not recommended that you store your JARs in CVS. Maven tries to
- promote the notion of a user local repository where JARs, or any
- project artifacts, can be stored and used for any number of builds.
- Many projects have dependencies such as XML parsers and standard utilities that
- are often replicated in typical Ant builds. With Maven these standard utilities
- can be stored in your local repository and shared by any number of builds.
+ Downloading in Maven is triggered by a project declaring a dependency that is not present in the local
+ repository (or for a <code>SNAPSHOT</code>, when the remote repository contains one that is newer).
+ By default, Maven will download from Ibiblio.
+ </p>
+ <p>
+ To override this, you need to set the property <code>maven.repo.remote</code> as follows:
+ </p>
+ <source>maven.repo.remote=http://planetmirror.com/maven/,http://www.ibiblio.org/maven/</source>
+ <p>
+ You can set this in your <code>~/build.properties</code> file to globally use a certain mirror, however
+ note that it is common for a project to customise the repository in their <code>project.properties</code>
+ and that your setting will take precedence. If you find that dependencies are not being found, check you
+ have not overridden the remote repository.
+ </p>
+ <p>
+ (Future versions should allow you to use a setting of
+ <code>${maven.repo.remote},http://planetmirror.com/maven</code>, but currently this causes an infinite
+ recursion).
</p>
</subsection>
+ <subsection name="Uploading to a Remote Repository">
+ <p>
+ While this is possible for any type of remote repository, you must have the permission to do so. Usually,
+ you will only be attempting to upload a release of your own application to an internal repository.
+ See <a href="../reference/internal-repositories.html">internal repositories</a> for more information.
+ </p>
+ </subsection>
+ </section>
-
+<!-- TODO: not net used, but belongs elsewhere
<subsection name="Overriding Stated Dependencies">
<p>
You may find it convenient, or necessary, at times to override the
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@maven.apache.org
For additional commands, e-mail: dev-help@maven.apache.org