Re: AW: [PATCH] setup - help and local dir command line optionswas"Re: Setup Command Line Options"

[Robert Collins <rbcollins at cygwin dot com>]

On Sat, 2003-10-25 at 22:23, Ralf Habacker wrote:
> > This is in the wrong place: LocalDirSetting::load is the right method to
> > query the option from.
> >
> While thinking about this a while more, I recognized that there is some more
> basic work necessary how to design the command line interface.
> Are there any other requests or hints about the design ?

I've roughed stuff out here before, I think. Anywhere, here goes a quick
brain dump.

> For me there is currently one major question. Is it possible to print
> message on stdout/stderr from a gui application ?

No. To show the help to the user, setup needs to show a dialog with the
help content in it. To do that, either:
1) provide a ostringstream to the ParameterUsage() call.
or
2) iterate through optionsInSet() and do your own formatting. (see the
source for OptionSet::ParameterUsage for an example of how to do it).

Then put whatever you've generated into a dialog. 

> If not than the first step seems to me really to split the gui from the
> core, so that a console application could be build. Has anyone done some
> analysis, where the cut could be done ?

Yes. This is a much bigger project than that needed to show the help to
the user. 

> A personal note: I will take some time for this because this is a need for
> further kde releases, so I probably will be able to help with the design,
> implementing some functions and making an initial design document about the
> command line design works, but there is much more work to do. At all I see
> the following tasks:
> 
> 1. analyse how to seperate the gui from the engine (the core) and the helper
> classes/code

I'm pretty simple on this: we need an engine that has no UI, provides
* A single thread interface.
    having the UI needing to be aware of engine thread status would be
seriously complex. Instead, the engine will be communicated with via a
single thread, and may create it's on worker threads for async activity.
No engine calls will block - they must return immediately.
* Provides callbacks to the UI on progress.
  calls that haven't completed when the engine returns, will signal
completion via a later callback. We can use one of:
  - async completion tokens.
  - callback wrappers (i.e. via a signals and slots library)
  - standard windows messages

  I don't have a particular preference, but I've listed those in likely
order of difficulty (for migration from the current code base) - and we
should only use one approach. If we want to use windows messages, I
suspect we want to wrap the engine in an adapter - as the command line
tool won't have a message loop.
* never throws exceptions: all errors must be handled in the engine, and
propogated to the UI via the callback mechanism. (We need a callback for
engine termination.)

The UI needs to be able to:
* query the engine for the available options
* hand user details into the engine
* retrieve structured data (ie. the list of sites) 
* attempt to action a given stage of the engine.
* display progress of long running tasks.

in terms of code separation, I wouldn't rush to put everything in
different dirs - see inilintmain.cc for the beginning of a command line
tool (one just to lint the ini file). A solid, minimal waste of time
approach would be to:
1 - define the engine API. in doing this, the -core- is:
    initialise (returns an instance of something)
    get option help
    terminate
  and
    initialise
    get instance for the first stage.
    perform an action on that stage
     ... repeat
    terminate

 note that the details for the actions can wait - it's only the outline
that is needed initially. callback actions like moving to the
download/download&install/install from the chooser will have an api
dependent on the choice of callback mechanism. Also note that the engine
cannot include -any- GUI headers.
    
2 - once the engine api is defined, work on the callback mechanism.
minimally it needs to support:
 * polling for events (i.e. from the windows idle event in the main
thread)
 * waiting for events (i.e. from a timer-less event loop in a command
line app)
 * notification of events (i.e. a % point completed, a change in
download time/expected completion time, package installation progress
etc).
 
  a small worked example:
    during downloading, the download thread should store status detail
in the engine. When the window idle thread comes around, it polls for
events. The engine then notifies if something has changed. The
notification might be a status change in an async completion token (in
which case we'd check those after the poll), a callback to a slot (in
which case it'd take effect immediately). 

3 - introduce the engine to main.cc. Move the loggin calls into the
engine. Other than that, all it needs to do is be initialised and
terminated.

4 - with the engine and callback interfaces in place, start a
setup-cmdline project within the current framework (see the inilint
target in Makefile.am).
 - start with what main.cc does. assign each task to either GUI or
engine.
 - for the GUI tasks, leave them intact. 
 - for the engine tasks, move them into the engine. If moving the task
into the engine would require moving a non-converted source file or
header into the engine, stop main.cc and switch to that other source
file / header.
 - give the commandline project code to use the new functionality in the
engine. This tests the api as it evolves.
 - rinse and repeat until the commandline has the desired functionality.

> 2. make a design about (a) the engine api and (b) the command line design
> 3. build up the engine
> 4. change the gui stuff to use the new engine
> 5. build a command line front end using the new engine

You cannot sensibly separate 4 and 3 - unless you duplicate code which
is a hard approach to take. I hope my comments here help. If you want to
start working on this, you're more than welcome to create a branch in
CVS on sources.redhat.com - I can give you CVS write access. Whether you
use a branch or not, be sure to work up a series of small patches for
inclusion as you progress. I'll happily review patches heading along an
agreed path, such as I've sketched above. If the patch looks good, it
can go in - even if we end up reversing it later. 

FWIW, I use eclipse's (www.eclipse.org) CDT view, it works quite well.

Rob


-- 
GPG key available at: <http://members.aardvark.net.au/lifeless/keys.txt>.

Attachment: signature.asc
Description: This is a digitally signed message part