laeubi
commented
4 months ago Thanks for the feedback, the documentation is located here:
if you want to improve that it would be great, just open a PR with suggested changes!
Open thahnen opened 4 months ago
laeubi
commented
4 months ago Thanks for the feedback, the documentation is located here:
if you want to improve that it would be great, just open a PR with suggested changes!
merks
commented
4 months ago We'll both be happy to review changes and to help answer questions.
Please note this comment:
That "generator" is here commented out:
The following automated setup is quite handy to ensure you have a correctly setup workspace with the appropriate clones:
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
commented
3 months ago 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 :smile:
Summary
The documentation regarding the
org.eclipse.equinox.p2.directorapplication is lacking information on the-followReferencesargument. 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 -hanymore. 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)
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
-followReferencesargument, 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.