Overhaul documentation on p2 director application

[thahnen]

Summary

The documentation regarding the org.eclipse.equinox.p2.director application is lacking information on the -followReferences argument. I'm not sure if the documentation is located in this repository as well, but the root cause - the application - is.

I'm using the application heavily for quite some time to install plug-ins and features from command line, mostly for provisioning Eclipse installations to developers. I consult the official documentation quite often in order to understand what everything does and more often I find myself slowly understanding arguments. As an example the one mentioned above, I think I finally understood. I hope.

The point is, the documentation lacks a lot of examples or clarification and seems to be not on par with running eclipse -application org.eclipse.equinox.p2.director -h anymore. The latter might be due to recent changes, but I honestly can't tell.

It would be nice if the documentation would feature examples on how to install from a local archive (here an older example from one of my scripts)

eclipse.exe -application org.eclipse.equinox.p2.director -repository jar:file:%~dp0org.sonarlint.eclipse.site-3.3.0.201711211047.zip!/ ...

Googling stuff like this is rarely helpful and it was a bliss when I stumbled upon this snippet a while ago.

Additionally, again mentioning the -followReferences argument, some need clarification or their own example and the statement what using this argument implies and what happens if it is not used. From my perspective: Installing without the argument led to installation errors when dependencies / requirements were not found, using it made it happen. Honestly no clue if that is actually the behaviour or if I'm just in the dark, but the documentation is blurry and every clue I found indicates something like this.

Improvements are not limited to the examples given, these are just the ones I collided the most with.

How can this be achieved

Speaking from the perspective of a Eclipse user and developer of plug-ins with limited experience of a few years who doesn't take everything for granted or isn't involved so heavily in the development around the Eclipse IDE for years to be able to know everything about it, I'd like to give some input on possible improvements and also take action myself on helping to improve and the documentation if that is desired.
Feel free to challenge any of the statements and assumptions taken by me and let me know what you think. I'm always open for a discussion (hopefully with following actions) around this.

[laeubi]

Thanks for the feedback, the documentation is located here:

https://github.com/eclipse-platform/eclipse.platform.releng.aggregator/blob/master/eclipse.platform.common/bundles/org.eclipse.platform.doc.isv/guide/p2_director.html

if you want to improve that it would be great, just open a PR with suggested changes!

[merks]

We'll both be happy to review changes and to help answer questions.

Please note this comment:

followReference

That "generator" is here commented out:

p2/bundles/org.eclipse.equinox.p2.director.app/src/org/eclipse/equinox/internal/p2/director/app/DirectorApplication.java

Lines 1806 to 1819 in ef2ce2f

	// @SuppressWarnings("nls")
	// public static void main(String[] args) {
	// System.out.println(
	// "<!-- This is generated from org.eclipse.equinox.internal.p2.director.app.DirectorApplication.main(String[]) -->");
	// System.out.println("<dl>");
	// System.out.println("<dt>");
	// System.out.println("-application org.eclipse.equinox.p2.director");
	// System.out.println("</dt>");
	// System.out.println("<dd>");
	// System.out.println("The application ID.");
	// System.out.println("</dd>");
	// performHelpInfo(true);
	// System.out.println("</dl>");
	// }

The following automated setup is quite handy to ensure you have a correctly setup workspace with the appropriate clones:

https://github.com/eclipse-platform/.github/blob/main/CONTRIBUTING.md#creating-an-eclipse-development-environment

This is way more clones than you actually need, but it's all automated so that does not harm.

In terms of -followReferences, generally repositories are composed as seen by org.eclipse.equinox.p2.repository.ICompositeRepository.getChildren() but a repository can also have references as seen by org.eclipse.equinox.p2.repository.metadata.IMetadataRepository.getReferences(). The option effectively just specifies whether those references are used or ignored. And of course one can imagine that folks building a repository with references will generally expect those to be visible/used when someone is using the repository to install something. If I'd designed this myself, I would have made follow references the default and supported a -noFollowReferences option for what seems like the more rare case. But I suppose initially even having references was the rare case...

[thahnen]

Thank you for the quick responses and for the links and clarification! I will make a plan for improvements and tackle that as quckly as possible once I have time to spare 😄