Using it from Eclipse

Arca hosts and proxies Eclipse p2 update sites, so Eclipse, PDE and Tycho resolve bundles and features through your own server: a proxy caches the public sites, and a hosted repository holds the sites your own builds publish.

Proxying a public site

Create a repository with a format of p2, a type of proxy, and a remote URL that is a host root, with no path:

https://download.eclipse.org

A path is rejected, and the reason matters. Composite update sites routinely point at children above their own directory. The 2024-12 release train lists this as a child of /releases/2024-12/:

<child location='../../technology/epp/packages/2024-12/'/>

Eclipse resolves that against the URL it loaded the site from. Pinning the remote to one update site puts those children outside the repository, where they cannot be served. Proxying the host root keeps them resolvable.

Pointing Eclipse at it

Append the path of the site you want to the repository URL. So a proxy named eclipse mirroring download.eclipse.org serves the 2024-12 release train at:

https://repo.example.com/repository/eclipse/releases/2024-12

Paste that into Help, Install New Software. A public repository needs no credentials. A private one prompts for your email and an API token.

Target platforms and Tycho

In a PDE target definition:

<location includeMode="planner" type="InstallableUnit">
  <repository location="https://repo.example.com/repository/eclipse/releases/2024-12"/>
  <unit id="org.eclipse.jgit.feature.group" version="0.0.0"/>
</location>

In a Tycho build, the p2 layout marks the repository as an update site rather than a Maven one:

<repositories>
  <repository>
    <id>eclipse</id>
    <url>https://repo.example.com/repository/eclipse/releases/2024-12</url>
    <layout>p2</layout>
  </repository>
</repositories>

What gets cached in a proxy

Bundles, features and binaries carry their version in the filename, so they are cached until the retention sweep evicts them. Metadata is republished in place, which is how a site like releases/latest moves, so p2.index, content.*, artifacts.* and the composite documents are revalidated once their metadata TTL expires.

What a proxy changes on the way through

A hosted site is served byte for byte as it was published. A proxy strips two properties from every artifact document it caches:

  • p2.mirrorsURL, which tells Eclipse to fetch bundles from a public mirror. Left in place it walks straight past this cache, and only the metadata would ever be cached.
  • p2.statsURI, which reports what your network installs back to eclipse.org.

The .xz form of an artifact document is answered with a 404 rather than served unstripped, and the artifact.repository.factory.order line of p2.index has that candidate removed so clients do not ask for it. Nothing is added in its place: those entries name repository factories rather than files, and the factory artifacts.xml already looks for artifacts.jar first. An order left naming nothing serveable is dropped entirely, so the client falls back on its own defaults.

Metadata documents, composite documents and the bundles themselves are passed through byte for byte.

One URL over several sites

A target platform that lists a dozen locations is a nuisance to keep in step across a team. Create a repository with a format of p2 and a type of group, and give it an ordered list of members:

eclipse/releases/2024-12
eclipse/technology/babel/update-site/R0.20.0/2022-12
p2-releases/commons/25.2.5

Each member is a p2 repository, optionally narrowed to a path inside it, because an update site is usually one directory of a repository rather than the whole of one. Point Eclipse at the group and it resolves all of them.

A group stores nothing. It serves a generated compositeContent.xml and compositeArtifacts.xml naming its members as children, and p2 merges them on the client. That is why a group needs no metadata merging here, and why only p2 has groups: a Maven or npm group would have to merge maven-metadata.xml or packuments server side, which is a different job.

Two consequences worth knowing:

  • Members enforce their own permissions. The client reads each child from its own URL, so nothing is served on a member’s behalf. A member the caller cannot read is left out of the composite rather than failing the whole site, because a composite loads atomically and one unreadable child would otherwise break the group for that user.
  • Order is preserved but is not precedence. p2 sees every version in every child, so a member does not hide another the way a Nexus group member can. Order only influences which child p2 prefers when two of them offer the identical artifact.

Groups are read-only, and cannot contain other groups.

Publishing your own sites

Create a repository with a format of p2 and a type of hosted. It needs no remote URL.

A Tycho project with eclipse-repository packaging writes a complete update site to target/repository: artifacts.jar, content.jar and the plugins/, features/ and binary/ directories. Publish that directory as it stands. Arca stores no metadata of its own for a p2 site, so what you upload is exactly what Eclipse reads back.

wagon-maven-plugin walks the directory and uploads a file at a time:

<plugin>
  <groupId>org.codehaus.mojo</groupId>
  <artifactId>wagon-maven-plugin</artifactId>
  <executions>
    <execution>
      <phase>package</phase>
      <goals><goal>upload</goal></goals>
      <configuration>
        <serverId>p2-releases</serverId>
        <fromDir>${project.build.directory}/repository</fromDir>
        <includes>**</includes>
        <url>https://repo.example.com/repository/p2-releases</url>
        <toDir>commons/25.2.5</toDir>
      </configuration>
    </execution>
  </executions>
</plugin>

With the credentials in settings.xml, keyed on the same serverId:

<servers>
  <server>
    <id>p2-releases</id>
    <username>YOUR_EMAIL</username>
    <password>YOUR_API_TOKEN</password>
  </server>
</servers>

Publishing over a path that already exists is allowed. A rebuild rewrites artifacts.jar and content.jar under the same names, so a repository that refused to overwrite would break the format.

Replacing a snapshot

To clear a site before republishing it, delete the tree:

curl -u YOUR_EMAIL:YOUR_API_TOKEN -X DELETE \
  https://repo.example.com/repository/p2-snapshots/commons/25.2.5/

The trailing slash matters. Without it only that exact file is removed.

Consuming it from Maven coordinates instead

If you would rather not publish a full site, Tycho’s assemble-maven-repository produces a metadata-only site attached as a zip with the classifier p2site, whose artifacts are referenced by Maven coordinate. Deploy it to a hosted maven2 repository alongside your bundle jars and consume it with mvn:your.group:your-artifact:1.0.0:zip:p2site. That path needs m2e installed in the IDE. Consuming it from a Tycho build does not.