Community
Participate
Working Groups
Launching Eclipse like so: "./eclipse --help" should print information to the command line about what options Eclipse supports. For an example of what the --help output should look like, evoke almost any Linux program from the command line and pass it --help. This would be particularly helpful on Linux where users expect --help to be supported, but it would be nice to have this on all platforms.
KC to investigate and advise.
To output the proper information when the "-help" or "-?" switch is given, the real help text must be output by Eclipse, since it interprets the vast majority of the switches. Also, since Eclipse knows the locale, it can output that help information in the proper language. It would be a big job to support internationalization in the launcher, especially since it has to support multiple OS's and the JVM already does this (why reinvent the wheel). There are a few switches that are recognized only by the launcher: -nosplash, - vm and –vmargs. Eclipse could contain information on these switches since they are really quite static and have not changed since 1.0. The remaining switches (-os, -arch, -ws, -consoleLog, -debug) are really switches for Eclipse to interpret. By having the info output by Eclipse (not the launcher), if an older version of the launcher happened to be used, the help information would still reflect the version of Eclipse being run. The "-showsplash" switch should not be documented because it is strictly used for communication between the launcher and Eclipse. If Eclipse interprets the "-help" switch and outputs the information, the launcher does not really need to do anything special. Here is how I think it might work (just a suggestion): 1. The user specifies "-help" on the command line along with other switches (e.g., -vm, -vmargs). 2. The launcher does not interpret the "-help" switch but merely passes it on to Eclipse when it starts the desired JVM. The launcher then waits for the JVM to exit as usual. 3. Eclipse interprets the –os, -arch, -ws and –help switches and displays a dialog with the corresponding help information. It would probably not display the workbench and may not interpret the –showsplash (don't show the splash screen). 4. When the user terminates the help info dialog (hits OK), Eclipse could then exit with a normal exit code (0) and the launcher would quietly exit too. I do not know how difficult step 3 would be since it has to load some plugins (SWT) in order to display a dialog but would probably not load the workbench plugins. If in the future, features wanted to append to the help (since they too can interpret switches), this should be possible. Given the info above, this bug really belongs to the "core" group.
*** Bug 21770 has been marked as a duplicate of this bug. ***
The launcher will pass the -help argument on to core (no change required). It is up to core to provide the info. Moving to the core team.
Here's a suggestion: - org.eclipse.core.runtime defines an extension point for command line help - extensions can provide text to show (statically, no classes involved) - org.eclipse.ui, org.eclipse.core.runtime and anyone else interested would provide the needed extensions The extension could have more structure than just a chunk of text, e.g. organized by command line arg.
*** Bug 32110 has been marked as a duplicate of this bug. ***
The command line args for Eclipse are processed in at least 5 places. 1) eclipse.exe 2) Main (startup.jar) 3) EclipseStarter (OSGi) 4) InternalPlatform (Runtime) 5) Resources (somewhere for -refresh) 6) UI (for -perspective, ...) The commandline depends on what application you are running. It also seems to depend on what plugins are started. I think this latter use of the command line (what resources is doing) is less than optimal and should be discontinued. The point here is that the help is really a product thing. RCP app writers likely to not want to expose to their uesrs that they can run with -vm or some such. I suggest we leave this up to doc and to the applications. I'm going to close. Someone can reopen if they feel strongly.
The per-application argument sounds right to me. But then shouldn't this just be moved to the SDK?
I would still like to see --help implemented. I opened bug 56268.
*** Bug 56268 has been marked as a duplicate of this bug. ***
*** Bug 64465 has been marked as a duplicate of this bug. ***
*** Bug 88024 has been marked as a duplicate of this bug. ***
Why not moving this to the UI team?
*** Bug 158021 has been marked as a duplicate of this bug. ***
Let this comment formally lodge my disgust at this sighted design choice, in relation to the WONTFIX resolution awarded. The way to document command line options on all platforms is through the use of rejecting invalid arguments given, this is the only feedback mechanism provided by an application to ensure a command line option was understood and valid. All other documentation is supplemenary to that behavor. At this moment in time it is impossible to tell the difference between a correct command line argument and an ignored command line argument by using error code and message reporting mechanisms that all other system applications use. The ever increasing bug duplicate list is indicative of a problem that is affecting the userbase. So I cast my vote on this bug entry to show support in the bug creators concept.
i second #16. the assumption of #7 regarding what rcp-developers might want or not are imo unsound -- nobody will know for sure what rcp-programmers want (i, f ex, like the idea to give informations by --help). the best way would be to implement #5's suggestion, an extension-point. as the launcher hardly will be devoloped w/o communication w/ the other parts of eclipse, informations to include launcher-opts would be accessible -- and every rcp-developer might decide on it's own whether to overwrite, amend or remove the informations filled in per default.
This certainly was not intended to generate disgust! The point I was trying to make is that the set of args to expose to the user is completely in the eye of the application writer. Your application as access to all of the command line arguments supplied when Eclipse was launched. It is your application that has the power and responsibility to decide which args are acceptable and which are invalid. Your application also has the right point of view to determine whether or not, and how, --help (or any other option) is handled. It is not clear how the platform can/should help here. The extension point idea is interesting but there will be a great many such extensions in any given configuration. The rutnime then needs to determine which of these contributions would be needed and possibly process some dynamic state or filtering. All of this is, IMHO, rightfully and very easily implemented in your application.
I agree with Jeff's observation that the checking of command-line arguments is application-specific, however, in an open-ended integration platform it would be wrong for the application extension to abort if it doesn't recognize one of the arguments, since this would prevent plug-ins added after-the-fact to add their own command-line arguments (and associated processing). I suspect what most people are complaining about here, though, is that there's no easy way to find out what the main command line arguments are for the Eclipse IDE (they're not looking for a general solution). Moving to the IDE team for consideration.
Also note that on Windows the convention is /help or /?, not -help or -? We should probably support all 4.
(In reply to comment #18) > This certainly was not intended to generate disgust! The point I was trying to > make is that the set of args to expose to the user is completely in the eye of > the application writer. Just to be clear from my PoV here. The only application I am referring to is the Eclipse development platform, as in the application that covers JDT and Callisto. Maybe my original bug should be addressed at "the" application writer of whatever that application Callisto is called ? But from what I can see of the problem is a lack of infrastructure to implement the feature that takes into account convention. > It is not clear how the platform can/should help here. Can you write up a technical description of why it is not the platform team's problem but it is the JDT team's problem and the WTP team's problem, etc... Then maybe I can approach those team's with a bug report to fix their application(s). RCP application are an important point, if anything the example the development platform sets would probably end up copied into any high quality RCP application. But alas no example is set and it seems no mechamism exists to achieve complete correctness with respect to command line argument handling. (In reply to comment #19) > I agree with Jeff's observation that the checking of command-line arguments is > application-specific, however, in an open-ended integration platform it would > be wrong for the application extension to abort if it doesn't recognize one of > the arguments, since this would prevent plug-ins added after-the-fact to add > their own command-line arguments (and associated processing). But this is how it works and you can't change that. When an option is invalid the application does not startup. So with that in mind the specification of any system which deals with command line options should be able to parse the options and offer them to all interested parties (listeners for command line options via way of extension point or other simple API) if there are any options left over or the listener generates an error, all the the errors are put in a list and the application exits with a non-zero exit status. Off the top of my head an outline specification of the necessary infrastrucure (to throw ideas in the air to be picked at): * Support fixed error code reports (certain errors might want to return a specific exit status, instead of the default value 1, so there are two classes of error a generic and a fixed, one doesn't care what the exact exit status is so long as it indicates an error, so non-zero. The other enforces what the exact value of the non-zero exit status is and would generally halt further option processing in order to convey that fixed exit status value) * Support listing multiple error problems in on go (we dont bail out at the first generic error but try to complete all options processing and dump multiple errors out in one go at the end) * Support for emitting warnings (non-fatal messages that doesn't inhibit startup but provides feedback to the user) * Support querying of available options --help -? /help /? * Support variable arguments, done on a 2nd pass and only makes sense if the listener has variable argument support. Variable argument would be like "./eclise_rcp_the_text_editor myfile.txt foobar.txt" * Support disabiling of further options processing the "--" option, remaining options are treated as a list of variable arguments. * Option processing code not to use stdout/stderr directly for error reporting, but to place formatted strings in the error list. This is to allow the method of informing the user of error would be with stdout/stderr with command line tools, a dialog box for GUI based startup or possible logfile for JUnit testing. * _If_ multiple cmdline option listeners are present there need to be defined order of execution and checking/automatic warnings to ensure two plugins dont try and grab the same option. * Overridable/plugable (by RCP users) default option handling, by default any error is fatal and Eclipse does not startup and emits feedback. This aspect would be possible to override which allow existing users who rely on current behaviour to get it back and specialised applications to provide their own mechanism to emit errors/warnings. * Support for debugging the option processing scheme, if we have multiple listener support then maybe it would dump listeners and which options were acted on by which listener. * The default is to fail on unexpected variable arguments or unknown option. (In reply to comment #20) > Also note that on Windows the convention is /help or /? Agreed, see my duped bug #158021. To be pedantic, it is convention on Linux that: -a -b -c convention is used for single character options so that concatention is valid -abc to mean the same thing. --long-option --configuration --data is used for long options with the leading double dash. The option "--" has a special meaning that the rest of the command line should be treated as literal values, even if those values start with a '-' character. This switched off option processing. But I'm not requesting Eclipse following the full convention in this bug report just useful to inform those that may not know such a convention exists.
Removing bogus milestone. Bug is still open.
Putting it in my bucket for the time being.
I will investigate a rudimentary solution for 3.4.
Sorry, there was no time in 3.4.
Removing 3.5 target milestone. We are in the end-game now. Please have a look and decide if this should be targeted at 3.6.
(In reply to comment #26) > Removing 3.5 target milestone. We are in the end-game now. Please have a look > and decide if this should be targeted at 3.6. > Boris why did you move this back to Framework? There has been lots of discussion in this bug about why we cannot implement this in the framework. This bug has been scoped down to the Eclipse IDE application and is specific to the options it supports.
Sorry, I was processing a whole pile of bugs and only looked at the last few comments. My suggestion would be to support --help at the launcher level, by writing out information about its arguments (-vm and -vmargs), and providing a way to "brand" the launcher with additional messages. Should I file a separate enhancement request for this?
(In reply to comment #28) > Sorry, I was processing a whole pile of bugs and only looked at the last few > comments. > > My suggestion would be to support --help at the launcher level, by writing out > information about its arguments (-vm and -vmargs), and providing a way to > "brand" the launcher with additional messages. Should I file a separate > enhancement request for this? > I would not suggest a separate request if we think such a solution will satisfy the requirements of this bug. But I think such a solution has a number of limitations. 1) Not sure we can translate such messages from the native launcher. 2) The same launcher can be used to launch many different applications (with -application option) each which would likely have different options available. Others?
(In reply to comment #29) > I think such a solution has a number of > limitations. 1) Not sure we can translate such messages from the native > launcher. 2) The same launcher can be used to launch many different > applications (with -application option) each which would likely have different > options available. Sure it has limitations, but it would be a pragmatic way to add that capability. 1) Do other Linux apps really give you translated messages when you pass "--help"? 2) Typical usage seems to be to launch a particular application, which is why there is support to brand the launcher (different name, icon). The pragmatic solution for the Eclipse SDK would be to "brand" the --help message to say e.g. "For further help, see http://help.eclipse.org/galileo/index.jsp".
Trying to read up on this request, I think it may be beneficial to consider the usage scenarios in which commandline help may be expected or beneficial. There won't be a "one size fits all" solution, given the extreme positions of Jeff on the one hand (comment 7: commandline help is a product thing) and some of the other more pragmatic proposals on the other hand. So here's a prioritized list of cases where _I_ would find commandline help beneficial: 1.) List available Launcher vmargs which allow me to configure startup itself. eclipsec --help --> Options like -vm, -vmargs, --launcher.ini etc --> Also output a hint that --help applications gives more info 2.) List available (registered) applications with a 1-line summary what they do. --help applications --> List apps like o.e.e.p2.director, ... --> Also output a hint that -application foobar --help gives more info 3.) Commandline help for a particular application that I choose. -application foobar --help 4.) Pervasive commonly used OSGi options -data, -configuration, ... I acknowledge that there are *tons* of other options which allow configuring / tweaking an application in a multitude of ways. But quite frankly, such configuration is rarely applicable in the context of a commandline use-case. I'm operating a product / RCP that I might want to tweak, so it is acceptable to read normal HTML documentation that tells me how to tweak the product. And we do have great existing documentation: (a) for end users: http://help.eclipse.org/galileo/topic/org.eclipse.platform.doc.user/tasks/running_eclipse.htm (b) for product builders: http://help.eclipse.org/galileo/topic/org.eclipse.platform.doc.isv/reference/misc/runtime-options.html You'll need to run the launcher from commandline in order to even see any console output. So, in order to provide real value to commandline users, I suggest focusing on commandline use-cases. Even if that means not providing a generic way for exposing each and every possible option.
I also just now stumbled upon the absence of a --help (or -?) when trying to find a parameter for debug options.
This bug hasn't had any activity in quite some time. Maybe the problem got resolved, was a duplicate of something else, or became less pressing for some reason - or maybe it's still relevant but just hasn't been looked at yet. If you have further information on the current state of the bug, please add it. The information can be, for example, that the problem still occurs, that you still want the feature, that more information is needed, or that the bug is (for whatever reason) no longer relevant. -- The automated Eclipse Genie.
