Hello community, here is the log from the commit of package yast2-core checked in at Fri Sep 26 15:15:57 CEST 2008. -------- --- yast2-core/yast2-core.changes 2008-09-25 12:27:33.000000000 +0200 +++ /mounts/work_src_done/STABLE/yast2-core/yast2-core.changes 2008-09-26 12:54:20.896445000 +0200 @@ -1,0 +2,7 @@ +Fri Sep 26 12:17:35 CEST 2008 - visnov@suse.cz + +- allow clients to return exit code (bnc #350740) +- clean up documentation in liby2 +- 2.17.14 + +------------------------------------------------------------------- Old: ---- yast2-core-2.17.13.tar.bz2 New: ---- yast2-core-2.17.14.tar.bz2 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Other differences: ------------------ ++++++ yast2-core.spec ++++++ --- /var/tmp/diff_new_pack.OA6442/_old 2008-09-26 15:15:18.000000000 +0200 +++ /var/tmp/diff_new_pack.OA6442/_new 2008-09-26 15:15:18.000000000 +0200 @@ -1,5 +1,5 @@ # -# spec file for package yast2-core (Version 2.17.13) +# spec file for package yast2-core (Version 2.17.14) # # Copyright (c) 2008 SUSE LINUX Products GmbH, Nuernberg, Germany. # @@ -19,12 +19,12 @@ Name: yast2-core -Version: 2.17.13 +Version: 2.17.14 Release: 1 License: GPL v2 or later Group: System/YaST BuildRoot: %{_tmppath}/%{name}-%{version}-build -Source0: yast2-core-2.17.13.tar.bz2 +Source0: yast2-core-2.17.14.tar.bz2 Prefix: /usr # obviously BuildRequires: gcc-c++ @@ -95,7 +95,7 @@ Stanislav Visnovsky <visnov@suse.cz> %prep -%setup -n yast2-core-2.17.13 +%setup -n yast2-core-2.17.14 %build %{prefix}/bin/y2tool y2autoconf @@ -178,6 +178,10 @@ %doc %{_datadir}/doc/yastdoc /usr/share/YaST2/data/devtools/bin/generateYCPWrappers %changelog +* Fri Sep 26 2008 visnov@suse.cz +- allow clients to return exit code (bnc #350740) +- clean up documentation in liby2 +- 2.17.14 * Thu Sep 25 2008 visnov@suse.cz - support SCR::RegisterAgent and SCR::UnregisterAgent in chroot (bnc #425472) ++++++ yast2-core-2.17.13.tar.bz2 -> yast2-core-2.17.14.tar.bz2 ++++++ ++++ 1873 lines of diff (skipped) ++++ retrying with extended exclude list diff -urN --exclude=CVS --exclude=.cvsignore --exclude=.svn --exclude=.svnignore --exclude Makefile.in --exclude configure --exclude config.guess --exclude '*.pot' --exclude mkinstalldirs --exclude aclocal.m4 --exclude config.sub --exclude depcomp --exclude install-sh --exclude ltmain.sh old/yast2-core-2.17.13/autodocs/Makefile.am new/yast2-core-2.17.14/autodocs/Makefile.am --- old/yast2-core-2.17.13/autodocs/Makefile.am 2007-11-26 12:48:41.000000000 +0100 +++ new/yast2-core-2.17.14/autodocs/Makefile.am 2008-09-26 10:31:02.000000000 +0200 @@ -13,5 +13,6 @@ index.html: $(wildcard $(top_srcdir)/*/*.cc $(top_srcdir)/*/*/*.cc) ${YDOXYGEN} PROJECT_NAME=@RPMNAME@ \ - INPUT=.. + INPUT=.. \ + EXCLUDE=../liby2util-r/testsuite # TODO: create libzypp.tag and use it (elsewhere) diff -urN --exclude=CVS --exclude=.cvsignore --exclude=.svn --exclude=.svnignore --exclude Makefile.in --exclude configure --exclude config.guess --exclude '*.pot' --exclude mkinstalldirs --exclude aclocal.m4 --exclude config.sub --exclude depcomp --exclude install-sh --exclude ltmain.sh old/yast2-core-2.17.13/configure.in new/yast2-core-2.17.14/configure.in --- old/yast2-core-2.17.13/configure.in 2008-09-17 15:50:58.000000000 +0200 +++ new/yast2-core-2.17.14/configure.in 2008-09-26 09:17:05.000000000 +0200 @@ -3,7 +3,7 @@ dnl -- This file is generated by y2autoconf 2.17.6 - DO NOT EDIT! -- dnl (edit configure.in.in instead) -AC_INIT(yast2-core, 2.17.12, http://bugs.opensuse.org/, yast2-core) +AC_INIT(yast2-core, 2.17.13, http://bugs.opensuse.org/, yast2-core) dnl Check for presence of file 'RPMNAME' AC_CONFIG_SRCDIR([RPMNAME]) @@ -18,7 +18,7 @@ AM_INIT_AUTOMAKE(tar-ustar -Wno-portability) dnl Important YaST2 variables -VERSION="2.17.12" +VERSION="2.17.13" RPMNAME="yast2-core" MAINTAINER="Martin Vidner <mvidner@suse.cz>" diff -urN --exclude=CVS --exclude=.cvsignore --exclude=.svn --exclude=.svnignore --exclude Makefile.in --exclude configure --exclude config.guess --exclude '*.pot' --exclude mkinstalldirs --exclude aclocal.m4 --exclude config.sub --exclude depcomp --exclude install-sh --exclude ltmain.sh old/yast2-core-2.17.13/configure.in.in new/yast2-core-2.17.14/configure.in.in --- old/yast2-core-2.17.13/configure.in.in 2008-08-19 13:20:25.000000000 +0200 +++ new/yast2-core-2.17.14/configure.in.in 2008-09-26 11:57:46.000000000 +0200 @@ -130,8 +130,6 @@ ## and generate the output AC_CONFIG_FILES([ - liby2/doc/Y2-access.html - liby2/doc/Y2-components.html scr/doc/SCR.html scr/doc/intro_to_scr.html ]) diff -urN --exclude=CVS --exclude=.cvsignore --exclude=.svn --exclude=.svnignore --exclude Makefile.in --exclude configure --exclude config.guess --exclude '*.pot' --exclude mkinstalldirs --exclude aclocal.m4 --exclude config.sub --exclude depcomp --exclude install-sh --exclude ltmain.sh old/yast2-core-2.17.13/liby2/doc/componentbroker.txt new/yast2-core-2.17.14/liby2/doc/componentbroker.txt --- old/yast2-core-2.17.13/liby2/doc/componentbroker.txt 2007-06-25 11:19:13.000000000 +0200 +++ new/yast2-core-2.17.14/liby2/doc/componentbroker.txt 1970-01-01 01:00:00.000000000 +0100 @@ -1,38 +0,0 @@ -How the component broker works - - -liby2 is the library which does all the stuff - -in Y2ProgramComponent.cc the server/client is started -(launchExternalProgram) by connecting pipes for stdin/stdout -and starting the program via fork/execve. - -The program is searched via pathsearch.cc and must reside -in a sub-directory "clients" or "servers". -The $HOME directory is a special case, as a sub-dir $HOME/.yast2 -must exists. - -Every program starts via main() genericfrontend.cc - -The main() function parses argv and starts -the client (Y2ComponentBroker::createClient) and the -server (Y2ComponentBroker::createServer) for the component - - -Expressions are 'commands' to the server and sent via -"...Component::evaluate (const YCPValue& command)" - -evaluate() starts the 'real' component if it is not already -running. - -For the serial and remote components, evaluate() -passes the command via "sendToExternal(command)". - -The it waits for the answer via "receiveFromExternal()" - --> the protocol between WFM and the component is synchronous. - For every sendToExternal there is a corresponding receiveFromExternal. - --> doActualWork() is used for client components - --> result() is used to finish server components diff -urN --exclude=CVS --exclude=.cvsignore --exclude=.svn --exclude=.svnignore --exclude Makefile.in --exclude configure --exclude config.guess --exclude '*.pot' --exclude mkinstalldirs --exclude aclocal.m4 --exclude config.sub --exclude depcomp --exclude install-sh --exclude ltmain.sh old/yast2-core-2.17.13/liby2/doc/Makefile.am new/yast2-core-2.17.14/liby2/doc/Makefile.am --- old/yast2-core-2.17.13/liby2/doc/Makefile.am 2007-06-25 11:19:13.000000000 +0200 +++ new/yast2-core-2.17.14/liby2/doc/Makefile.am 1970-01-01 01:00:00.000000000 +0100 @@ -1,15 +0,0 @@ -# -# Makefile.am for core/liby2/doc -# - - - -htmldir = $(docdir)/liby2 - -html_DATA = \ - Y2-access.html Y2-components.html \ - Y2-overview.html \ - componentbroker.txt \ - README.componentsearch - -EXTRA_DIST = $(html_DATA) diff -urN --exclude=CVS --exclude=.cvsignore --exclude=.svn --exclude=.svnignore --exclude Makefile.in --exclude configure --exclude config.guess --exclude '*.pot' --exclude mkinstalldirs --exclude aclocal.m4 --exclude config.sub --exclude depcomp --exclude install-sh --exclude ltmain.sh old/yast2-core-2.17.13/liby2/doc/README.componentsearch new/yast2-core-2.17.14/liby2/doc/README.componentsearch --- old/yast2-core-2.17.13/liby2/doc/README.componentsearch 2007-06-25 11:19:13.000000000 +0200 +++ new/yast2-core-2.17.14/liby2/doc/README.componentsearch 1970-01-01 01:00:00.000000000 +0100 @@ -1,32 +0,0 @@ -I implemented and checked in a new strategy Y2 looks for its components . -It scans in a sequential manner in - -level path - 0 /floppy - 1 /y2update - 2 HOME --> means: $HOME/.yast2/ - 3 /usr/local/lib/YaST2 - 4 /usr/lib/YaST2 - 5 /lib/YaST2 - 6 /var/lib/YaST2 - 7 YASTHOME - -Lower leves are preferred. The search applies for scripts, config files -and binaries. - -Now you can put an updated component on a floppy disk and that component -will be used preferrably. - -You can update _each_ component, even cat, stdio and logger. - -Only the generic frontend main function, the ComponentBroker and the -ComponentCreators contained in bignfat can't be replaced. They -must at least be able to find the first component on floppy. - -Executable components are searched for in the above mentioned manner, -the paths being extended with one of the following directories: - -.../servers/: Y2 servers like compiled programs using liby2 -.../servers_non_y2: NonY2 servers like shell scripts and such like -.../clients: Y2 clients like compiled programs using liby2 -.../clients_non_y2: NonY2 clients like shell scripts and such like diff -urN --exclude=CVS --exclude=.cvsignore --exclude=.svn --exclude=.svnignore --exclude Makefile.in --exclude configure --exclude config.guess --exclude '*.pot' --exclude mkinstalldirs --exclude aclocal.m4 --exclude config.sub --exclude depcomp --exclude install-sh --exclude ltmain.sh old/yast2-core-2.17.13/liby2/doc/Y2-access.html new/yast2-core-2.17.14/liby2/doc/Y2-access.html --- old/yast2-core-2.17.13/liby2/doc/Y2-access.html 2008-09-17 15:52:00.000000000 +0200 +++ new/yast2-core-2.17.14/liby2/doc/Y2-access.html 1970-01-01 01:00:00.000000000 +0100 @@ -1,29 +0,0 @@ -YaST2: How to access hardware and configuration files - -There are a number of different ways to access configuration files, -the output of external programms and the hardware from within YCP -scripts. - -<ul> - <li>Write an <b>SCR agent</b> in YCP using the <b>anyagent</b> component. - <li>Write an <b>SCR agent</b>, either in C++ or in shell</li> - <li>Use the WFM builtin <b><tt>Shell()</tt></b> to call a shell - script</li> - <li>Use the WFM builtins <b><tt>ReadString()</tt> and <tt>WriteString()</tt></b> - to read and write Ascii files directly</li> - <li>Write a </b>client component</b> in C++ that calls an external program and - parses its output. Use the liby2 class <tt>ExternalProgramm</tt> for - this. - </li> - <li>Write a arbitrary <b>server component</b> in C++ and implement there the functionality - you need.</li> -</ul> - - -All methods have advantages and disadvantages. The upper list is -ordered in the direction in which you have to decide. For example if -something can be done with the <tt>anyagent</tt>, you should do it -this way. If not, try to write an agent in C++ or in shell. The -advantage of agents is, that they are very independent of the -configuration module(s) that use them. It is much more easy to reuse -an agent than a code sequence of a module. diff -urN --exclude=CVS --exclude=.cvsignore --exclude=.svn --exclude=.svnignore --exclude Makefile.in --exclude configure --exclude config.guess --exclude '*.pot' --exclude mkinstalldirs --exclude aclocal.m4 --exclude config.sub --exclude depcomp --exclude install-sh --exclude ltmain.sh old/yast2-core-2.17.13/liby2/doc/Y2-access.html.in new/yast2-core-2.17.14/liby2/doc/Y2-access.html.in --- old/yast2-core-2.17.13/liby2/doc/Y2-access.html.in 2007-06-25 11:19:13.000000000 +0200 +++ new/yast2-core-2.17.14/liby2/doc/Y2-access.html.in 1970-01-01 01:00:00.000000000 +0100 @@ -1,29 +0,0 @@ -YaST2: How to access hardware and configuration files - -There are a number of different ways to access configuration files, -the output of external programms and the hardware from within YCP -scripts. - -<ul> - <li>Write an <b>SCR agent</b> in YCP using the <b>anyagent</b> component. - <li>Write an <b>SCR agent</b>, either in C++ or in shell</li> - <li>Use the WFM builtin <b><tt>Shell()</tt></b> to call a shell - script</li> - <li>Use the WFM builtins <b><tt>ReadString()</tt> and <tt>WriteString()</tt></b> - to read and write Ascii files directly</li> - <li>Write a </b>client component</b> in C++ that calls an external program and - parses its output. Use the liby2 class <tt>ExternalProgramm</tt> for - this. - </li> - <li>Write a arbitrary <b>server component</b> in C++ and implement there the functionality - you need.</li> -</ul> - - -All methods have advantages and disadvantages. The upper list is -ordered in the direction in which you have to decide. For example if -something can be done with the <tt>anyagent</tt>, you should do it -this way. If not, try to write an agent in C++ or in shell. The -advantage of agents is, that they are very independent of the -configuration module(s) that use them. It is much more easy to reuse -an agent than a code sequence of a module. diff -urN --exclude=CVS --exclude=.cvsignore --exclude=.svn --exclude=.svnignore --exclude Makefile.in --exclude configure --exclude config.guess --exclude '*.pot' --exclude mkinstalldirs --exclude aclocal.m4 --exclude config.sub --exclude depcomp --exclude install-sh --exclude ltmain.sh old/yast2-core-2.17.13/liby2/doc/Y2-components.html new/yast2-core-2.17.14/liby2/doc/Y2-components.html --- old/yast2-core-2.17.13/liby2/doc/Y2-components.html 2008-09-17 15:52:00.000000000 +0200 +++ new/yast2-core-2.17.14/liby2/doc/Y2-components.html 1970-01-01 01:00:00.000000000 +0100 @@ -1,184 +0,0 @@ -Y2 reference: The YaST2 Component Architecture - -Author: Mathias Kettner <a href="mailto:kettner@suse.de">kettner@suse.de</a> - -<h2>Design principles</h2> - -<p>The YaST2 component model is the foundation of the -YaST2 architecture. It is important to understand at least -the basic ideas in order to be able to write new Y2 components. -It's based upon the following design principles: - -<p><table cellspacing=0 BGCOLOR="#f96500" width="100%"><tr><td> -<table width="100%" bgcolor="#ffc080" cellpadding=10><TR><TD> -<ul> - -<p><li><i>YaST2 should be easily extensable. One should be able -to exchange or add functionality independent -of all other parts.</i>This leads to a modular architecture. -The interchangable parts are called 'components'.</li> - -<p><li><i>It should be possible, that a component can be added -or exchanged merely through the fact, that a file has been -added or exchanged.</i> This allows you to put configuration -modules for a software into the same package as that software. -For example you could write a configuration module for -sendmail and put it into the sendmail package. As long as -the sendmail package is installed, its YaST2 configuration -module is available.</li> - -<p><li><i>Despite the need for Y2 to be modular in concept, -during execution time this should not lead to high communication -overhead or large need in memory usage or the number of -concurrently running processes.</i></li> - -<p><li><i>The inter-component communication should be human -readable, at least in debugging situations.</i></li> - -<p><li><i>The inter-component communication should be network -transparent.</i></li> - -<p><li><i>It should be easy to write a component. Component implementing -should not be restricted to a certain programming language.</i> - -</ul> -</td></tr></table> -</td></tr></table> - -<h2>Communication</h2> - -<p>All components speak a common language and act according to -defined protocol. Both the language and the protocol are -called <i>YCP (YaST2 communication protocol)</i>. One protocol -step consists of one of the partners sending exactly one -<a href="../libycp/YCP-datatypes.html">YCP value</a> - to the other and the other receiving that value. In the -next step, the component that just was receiving, is now sending and -vice versa. The only exception is, that one of that partners -may terminate the session and send a last <i>result</i> message -after which - of course - the partner won't send another value. - -<h2>Clients and Servers</h2> - -<p>There are two different kinds of components: server components and -client components, which differ in how the control flows. - -<p>A <i>server</i> component is one that - once it's initialized - -just waits for jobs to do. Another component can send a <i>request</i> -and thus pass the control to the server. That does what is neccessary -in order to do handle the request and returns an -<i>answer</i>. Prominent examples for server components are the user -interfaces. In YaST2 they play a <i>passive</i> role. They just wait -for a command like "Show me this dialog, wait for the next user -input and return me that input". A server component can also use -the service of another server component. For example the <i>SCR -(System configuration repository)</i> makes use of servers called -<i>agents</i>, which realize subtrees of the SCR tree. - -<p>A <i>client</i> component is one that controls the flow. It may -contain something like an "event loop". In order to do its -work, it can use the services of other server components. Client -components are sometimes called <i>modules</i>. Examples for -modules are the single steps of the YaST2 "Installation -Wizard" or the program that calls <tt>rpm</tt> to install -packages. Other examples could be a module that configures the network -setup of a workstation or one, that just sets the IP-number and the -hostname of that workstation. - -<p>Modules can be hiearchically structured -and hand over control to other modules that acomplish sub tasks and -are called <i>submodules</i> in this context. An example is the -structure of the YaST2 installer. The installation itself is -a module. For each of the wizard window steps, it calls a submodule. - -<h2>How components are realized</h2> -<p>There are quite a number of ways how you can implement a component. -A component can be: -<p><table cellspacing=0 BGCOLOR="#f96500" width="100%"><tr><td> -<table width="100%" bgcolor="#ffc080" cellpadding=10><TR><TD> -<ul> - -<li>An executable program (ELF, /bin/sh, or whatsoever)</li> -<li>A C++ class using <tt><a href="../libycp/autodocs/intro.html">libycp</a></tt> -and <tt><a href="../liby2/autodocs/intro.html">liby2</a></tt></li> -<li>A YCP script executed by the <i>Workflowmanager</i></li> -<li>Youself typing some YCP code at a terminal</li> - -</ul> -</td></tr></table> -</td></tr></table> - -<p>Don't laugh over the last possibility! For debugging this is sometimes -very helpful. You can simulate <i>any</i> component by typing to a terminal. - -<h3>Executable programs</h3> - -<p>A component that exists as <i>executable program</i> is realized by -a process that is created when the component is needed. If a component -needs the services of an external program component, it launches a -seperate process and starts a communication via two unix pipes, one in -each direction. - -<p>The data flowing through these pipes is YCP Ascii -representation. Each communication side needs a parser to analyse the -data and a YCP syntax generater to write data to the pipe. Both can be -found in the <tt><a href="../libycp/autodocs/intro.html">libycp</a></tt>, -which can only used from C++ programs. - -<p>But the production of YCP code -can in many cases very easily be done be printing to stdout, for -example with <tt>echo</tt> (shell) or <tt>printf</tt> (C). - -<p>The parsing of YCP code is as bit more tricky. But in many cases you -don't need a full featured parser, because you know beforehand what structure -the value have that you get. This especially holds for client components, -because they can decide, how the output from the server should look like. - -<h3>C++ class using libycp and liby2</h3> -<p>If you anyway decide to write your component in C++, -it's by far the most conveniant way to use the functionality -of libycp and liby2, whose only purpose is excactly to support -component implementation. - -<p>What you have to do is to subclass at least two classes: -<tt><a href="../liby2/autodocs/Y2ComponentCreator.html">Y2ComponentCreator</a></tt> and -<tt><a href="../liby2/autodocs/Y2Component.html">Y2Component</a></tt> and - -<p>Depending on whether you want to implement a server or a client component -you have to override different methods. Many examples can be found within the liby2 -itself. - -<p>One big advantage of writing a component in C++ is, that -you can very easily create three external appearances of the component: -<ul> -<li>A selfcontained executable program</li> -<li>A shared library plugin to load during runtime</li> -<li>A static library that can be linked together with other components</li> -</ul> - -<p>The YaST2 installer makes usage of the third variant only. All required components -are linked together to <tt>y2base</tt>, which is statically linked against liby2 and -libycp. The memory usage is reduced as well as the required disk space. Furthermore -no creating and parsing of Ascii streams between the components is required. Protocol -steps are simple function calls. Even for very large data structures, only one pointer -has to be passed. - -<h3>A YCP script executed by the <i>Workflowmanager</i></h3> -<p>If you have installed YaST2, you will find some files ending in <tt>.ycp</tt> -lying around in <tt>/lib/YaST2/clients</tt>. These are YCP scripts implementing -client components (modules). YCP is not only a protocol, it is also a full features -programming language, which is in this case used to implement components. This is -very conveniant as the language can directly operate on the protocol values and -has some other nice features. - -<p>The client scripts are executed by the <i>Workflowmanager</i>, which is an -extension to the core YCP language. It implements a couple of builtin functions -that allow communication the the system and with other -components. Here is a -<a href="../y2wfm/YCP-builtins-wfm.html">of builtins.</a>. - -<h3>Youself typing YCP code at a terminal</h3> -<p>You can be a component yourself :-). Just tell another component to communicate -via stdio and speak with it. For example you can launch the component <tt>ycp</tt> by -typing <tt>y2ycp stdio</tt>. Now you can enter YCP expressions and get the evaluation -as answer. diff -urN --exclude=CVS --exclude=.cvsignore --exclude=.svn --exclude=.svnignore --exclude Makefile.in --exclude configure --exclude config.guess --exclude '*.pot' --exclude mkinstalldirs --exclude aclocal.m4 --exclude config.sub --exclude depcomp --exclude install-sh --exclude ltmain.sh old/yast2-core-2.17.13/liby2/doc/Y2-components.html.in new/yast2-core-2.17.14/liby2/doc/Y2-components.html.in --- old/yast2-core-2.17.13/liby2/doc/Y2-components.html.in 2007-06-25 11:19:13.000000000 +0200 +++ new/yast2-core-2.17.14/liby2/doc/Y2-components.html.in 1970-01-01 01:00:00.000000000 +0100 @@ -1,184 +0,0 @@ -Y2 reference: The YaST2 Component Architecture - -Author: Mathias Kettner <a href="mailto:kettner@suse.de">kettner@suse.de</a> - -<h2>Design principles</h2> - -<p>The YaST2 component model is the foundation of the -YaST2 architecture. It is important to understand at least -the basic ideas in order to be able to write new Y2 components. -It's based upon the following design principles: - -<p><table cellspacing=0 BGCOLOR="#f96500" width="100%"><tr><td> -<table width="100%" bgcolor="#ffc080" cellpadding=10><TR><TD> -<ul> - -<p><li><i>YaST2 should be easily extensable. One should be able -to exchange or add functionality independent -of all other parts.</i>This leads to a modular architecture. -The interchangable parts are called 'components'.</li> - -<p><li><i>It should be possible, that a component can be added -or exchanged merely through the fact, that a file has been -added or exchanged.</i> This allows you to put configuration -modules for a software into the same package as that software. -For example you could write a configuration module for -sendmail and put it into the sendmail package. As long as -the sendmail package is installed, its YaST2 configuration -module is available.</li> - -<p><li><i>Despite the need for Y2 to be modular in concept, -during execution time this should not lead to high communication -overhead or large need in memory usage or the number of -concurrently running processes.</i></li> - -<p><li><i>The inter-component communication should be human -readable, at least in debugging situations.</i></li> - -<p><li><i>The inter-component communication should be network -transparent.</i></li> - -<p><li><i>It should be easy to write a component. Component implementing -should not be restricted to a certain programming language.</i> - -</ul> -</td></tr></table> -</td></tr></table> - -<h2>Communication</h2> - -<p>All components speak a common language and act according to -defined protocol. Both the language and the protocol are -called <i>YCP (YaST2 communication protocol)</i>. One protocol -step consists of one of the partners sending exactly one -<a href="../libycp/YCP-datatypes.html">YCP value</a> - to the other and the other receiving that value. In the -next step, the component that just was receiving, is now sending and -vice versa. The only exception is, that one of that partners -may terminate the session and send a last <i>result</i> message -after which - of course - the partner won't send another value. - -<h2>Clients and Servers</h2> - -<p>There are two different kinds of components: server components and -client components, which differ in how the control flows. - -<p>A <i>server</i> component is one that - once it's initialized - -just waits for jobs to do. Another component can send a <i>request</i> -and thus pass the control to the server. That does what is neccessary -in order to do handle the request and returns an -<i>answer</i>. Prominent examples for server components are the user -interfaces. In YaST2 they play a <i>passive</i> role. They just wait -for a command like "Show me this dialog, wait for the next user -input and return me that input". A server component can also use -the service of another server component. For example the <i>SCR -(System configuration repository)</i> makes use of servers called -<i>agents</i>, which realize subtrees of the SCR tree. - -<p>A <i>client</i> component is one that controls the flow. It may -contain something like an "event loop". In order to do its -work, it can use the services of other server components. Client -components are sometimes called <i>modules</i>. Examples for -modules are the single steps of the YaST2 "Installation -Wizard" or the program that calls <tt>rpm</tt> to install -packages. Other examples could be a module that configures the network -setup of a workstation or one, that just sets the IP-number and the -hostname of that workstation. - -<p>Modules can be hiearchically structured -and hand over control to other modules that acomplish sub tasks and -are called <i>submodules</i> in this context. An example is the -structure of the YaST2 installer. The installation itself is -a module. For each of the wizard window steps, it calls a submodule. - -<h2>How components are realized</h2> -<p>There are quite a number of ways how you can implement a component. -A component can be: -<p><table cellspacing=0 BGCOLOR="#f96500" width="100%"><tr><td> -<table width="100%" bgcolor="#ffc080" cellpadding=10><TR><TD> -<ul> - -<li>An executable program (ELF, /bin/sh, or whatsoever)</li> -<li>A C++ class using <tt><a href="../libycp/autodocs/intro.html">libycp</a></tt> -and <tt><a href="../liby2/autodocs/intro.html">liby2</a></tt></li> -<li>A YCP script executed by the <i>Workflowmanager</i></li> -<li>Youself typing some YCP code at a terminal</li> - -</ul> -</td></tr></table> -</td></tr></table> - -<p>Don't laugh over the last possibility! For debugging this is sometimes -very helpful. You can simulate <i>any</i> component by typing to a terminal. - -<h3>Executable programs</h3> - -<p>A component that exists as <i>executable program</i> is realized by -a process that is created when the component is needed. If a component -needs the services of an external program component, it launches a -seperate process and starts a communication via two unix pipes, one in -each direction. - -<p>The data flowing through these pipes is YCP Ascii -representation. Each communication side needs a parser to analyse the -data and a YCP syntax generater to write data to the pipe. Both can be -found in the <tt><a href="../libycp/autodocs/intro.html">libycp</a></tt>, -which can only used from C++ programs. - -<p>But the production of YCP code -can in many cases very easily be done be printing to stdout, for -example with <tt>echo</tt> (shell) or <tt>printf</tt> (C). - -<p>The parsing of YCP code is as bit more tricky. But in many cases you -don't need a full featured parser, because you know beforehand what structure -the value have that you get. This especially holds for client components, -because they can decide, how the output from the server should look like. - -<h3>C++ class using libycp and liby2</h3> -<p>If you anyway decide to write your component in C++, -it's by far the most conveniant way to use the functionality -of libycp and liby2, whose only purpose is excactly to support -component implementation. - -<p>What you have to do is to subclass at least two classes: -<tt><a href="../liby2/autodocs/Y2ComponentCreator.html">Y2ComponentCreator</a></tt> and -<tt><a href="../liby2/autodocs/Y2Component.html">Y2Component</a></tt> and - -<p>Depending on whether you want to implement a server or a client component -you have to override different methods. Many examples can be found within the liby2 -itself. - -<p>One big advantage of writing a component in C++ is, that -you can very easily create three external appearances of the component: -<ul> -<li>A selfcontained executable program</li> -<li>A shared library plugin to load during runtime</li> -<li>A static library that can be linked together with other components</li> -</ul> - -<p>The YaST2 installer makes usage of the third variant only. All required components -are linked together to <tt>y2base</tt>, which is statically linked against liby2 and -libycp. The memory usage is reduced as well as the required disk space. Furthermore -no creating and parsing of Ascii streams between the components is required. Protocol -steps are simple function calls. Even for very large data structures, only one pointer -has to be passed. - -<h3>A YCP script executed by the <i>Workflowmanager</i></h3> -<p>If you have installed YaST2, you will find some files ending in <tt>.ycp</tt> -lying around in <tt>/lib/YaST2/clients</tt>. These are YCP scripts implementing -client components (modules). YCP is not only a protocol, it is also a full features -programming language, which is in this case used to implement components. This is -very conveniant as the language can directly operate on the protocol values and -has some other nice features. - -<p>The client scripts are executed by the <i>Workflowmanager</i>, which is an -extension to the core YCP language. It implements a couple of builtin functions -that allow communication the the system and with other -components. Here is a -<a href="../y2wfm/YCP-builtins-wfm.html">of builtins.</a>. - -<h3>Youself typing YCP code at a terminal</h3> -<p>You can be a component yourself :-). Just tell another component to communicate -via stdio and speak with it. For example you can launch the component <tt>ycp</tt> by -typing <tt>y2ycp stdio</tt>. Now you can enter YCP expressions and get the evaluation -as answer. diff -urN --exclude=CVS --exclude=.cvsignore --exclude=.svn --exclude=.svnignore --exclude Makefile.in --exclude configure --exclude config.guess --exclude '*.pot' --exclude mkinstalldirs --exclude aclocal.m4 --exclude config.sub --exclude depcomp --exclude install-sh --exclude ltmain.sh old/yast2-core-2.17.13/liby2/doc/Y2-overview.html new/yast2-core-2.17.14/liby2/doc/Y2-overview.html --- old/yast2-core-2.17.13/liby2/doc/Y2-overview.html 2007-06-25 11:19:13.000000000 +0200 +++ new/yast2-core-2.17.14/liby2/doc/Y2-overview.html 1970-01-01 01:00:00.000000000 +0100 @@ -1,197 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> -<html> -<head> -<meta http-equiv="Content-Type" -content="text/html; charset=ISO-8859-1"> - <title>YCP inside</title> - <style type="text/css"><!-- h3.fn,span.fn { margin-left: 1cm; text-indent: -1cm; } - a:link { color: #004faf; text-decoration: none } - a:visited { color: #004fb4; text-decoration: none }body { background: - white; color: black; } --> - </style></head> - -<!--body bgcolor="#ffffff" text=#4c9900 --> -<body bgcolor="#ffffff" text=#3b7700 > - -<h1 align=center>YCP Inside</h1> - -<table text=#FFCC99 align=center cellpadding=2 cellspacing=2 width=95% > -<tr>Have a look at these links if you want to code YCP C++ agent or you -want to improve the ycp groundwork.</tr> -</table> -<p> -<font color="#418200"> -<table align=center cellpadding=2 cellspacing=2 width=95% > - - - <tr aaa=center> - <th bgcolor=#62af30 width=33%> - <font color="White">The Language</font> - </th> - </tr> - - <tr aaa=center> - <td bgcolor=#f0f0f0 ><b> - <a href="../libycp/YCP-quoting.html"> Quoting </a></b></td> - <td width=0></td> - <td bgcolor=#f0f0f0 >Explains the usage of backquotes in YCP</td> - </tr> - - <tr><td height=10></td> </tr> - - <tr aaa=center> - <td bgcolor=#f0f0f0 ><b> - <a href="../libycp/changes.html"> YCP Grammer Changes </a></b></td> - <td width=0></td> - <td bgcolor=#f0f0f0 >Recently (12/2000) implemented changes in the YCP grammer</td> - </tr> - - <tr><td height=10></td> </tr> - - <!-- ************************************************************** --> - <tr aaa=center> - <th bgcolor=#62af30 width=33%> - <font color="White">Components</font> - </th> - </tr> - - <tr aaa=center> - <td bgcolor=#f0f0f0 ><b> - <a href="Y2-components.html"> Component Architecture </a></b></td> - <td width=0></td> - <td bgcolor=#f0f0f0 >Learn about the design principles, the communication and client - and server architecture</td> - </tr> - - <tr><td height=10></td> </tr> - - <!-- ************************************************************** --> - - <tr aaa=center> - <td bgcolor=#f0f0f0 ><b> - <a href="componentbroker.txt"> Component Broker </a></b></td> - <td width=0></td> - <td bgcolor=#f0f0f0 >How does the Component broker work </td> - </tr> - - <tr><td height=10></td> </tr> - - <!-- ************************************************************** --> - - <tr aaa=center> - <td bgcolor=#f0f0f0 ><b> - <a href="README.componentsearch"> Component Search </a></b></td> - <td width=0></td> - <td bgcolor=#f0f0f0 >Where YaST2 looks for Components </td> - </tr> - - <tr><td height=10></td> </tr> - - <!-- ************************************************************** --> - <tr aaa=center> - <th bgcolor=#62af30 width=33%> - <font color="White">Serial</font> - </th> - </tr> - - <tr aaa=center> - <td bgcolor=#f0f0f0 ><b> - <a href="README.serial"> Serial Communication </a></b></td> - <td width=0></td> - <td bgcolor=#f0f0f0 >A README how to communicate with YaST2 - components via serial line </td> - </tr> - - <tr><td height=10></td> </tr> - - <!-- ************************************************************** --> - <tr aaa=center> - <th bgcolor=#62af30 width=33%> - <font color="White">liby2</font> - </th> - </tr> - - <tr aaa=center> - <td bgcolor=#f0f0f0 ><b> - <a href="autodocs/intro.html"> Liby2 Introduction </a></b></td> - <td width=0></td> - <td bgcolor=#f0f0f0 >An Introduction of the YaST2 component architecture</td> - </tr> - - <tr><td height=10></td> </tr> - - <!-- ************************************************************** --> - - <tr aaa=center> - <td bgcolor=#f0f0f0 > - <a href="autodocs/heir.html"> Liby2 Class Hierarchy </a></td> - <td width=0></td> - <td bgcolor=#f0f0f0 >The class hierarchy of liby2 - components via serial line </td> - </tr> - - <tr><td height=10></td> </tr> - - <!-- ************************************************************** --> - - <tr aaa=center> - <td bgcolor=#f0f0f0 > - <a href="autodocs/index.html"> Liby2 Class Index </a></td> - <td width=0></td> - <td bgcolor=#f0f0f0 >The class index of liby2</td> - </tr> - - <tr><td height=10></td> </tr> - - <!-- ************************************************************** --> - <tr aaa=center> - <th bgcolor=#62af30 width=33%> - <font color="White">libycp</font> - </th> - </tr> - - <tr aaa=center> - <td bgcolor=#f0f0f0 ><b> - <a href="../libycp/autodocs/intro.html"> Libycp Introduction </a></b></td> - <td width=0></td> - <td bgcolor=#f0f0f0 >An Introduction of the YaST2 component architecture</td> - </tr> - - <tr><td height=10></td> </tr> - - <!-- ************************************************************** --> - - <tr aaa=center> - <td bgcolor=#f0f0f0 > - <a href="../libycp/autodocs/heir.html"> Libycp Class Hierarchy </a></td> - <td width=0></td> - <td bgcolor=#f0f0f0 >The class hierarchy of liby2 - components via serial line </td> - </tr> - - <tr><td height=10></td> </tr> - - <!-- ************************************************************** --> - - <tr aaa=center> - <td bgcolor=#f0f0f0 > - <a href="../libycp/autodocs/index.html"> Libycp Class </a></td> - <td width=0></td> - <td bgcolor=#f0f0f0 >The class index of liby2</td> - </tr> - - <tr><td height=10></td> </tr> - - -</table> -</font> -<p> - - -<p><address><hr><div align="center"> -<table width="100%" cellspacing="0" border="0"><tr> -<td><a href="http://www.suse.de">www.suse.de</a><td> -<td align="right"><div align="right">YaST2 Version 7.1</div> -</table></div></address></body></html> - - diff -urN --exclude=CVS --exclude=.cvsignore --exclude=.svn --exclude=.svnignore --exclude Makefile.in --exclude configure --exclude config.guess --exclude '*.pot' --exclude mkinstalldirs --exclude aclocal.m4 --exclude config.sub --exclude depcomp --exclude install-sh --exclude ltmain.sh old/yast2-core-2.17.13/liby2/Makefile.am new/yast2-core-2.17.14/liby2/Makefile.am --- old/yast2-core-2.17.13/liby2/Makefile.am 2007-06-25 11:19:13.000000000 +0200 +++ new/yast2-core-2.17.14/liby2/Makefile.am 2008-09-26 11:47:34.000000000 +0200 @@ -2,4 +2,4 @@ # Makefile.am for core/liby2 # -SUBDIRS = src doc +SUBDIRS = src diff -urN --exclude=CVS --exclude=.cvsignore --exclude=.svn --exclude=.svnignore --exclude Makefile.in --exclude configure --exclude config.guess --exclude '*.pot' --exclude mkinstalldirs --exclude aclocal.m4 --exclude config.sub --exclude depcomp --exclude install-sh --exclude ltmain.sh old/yast2-core-2.17.13/liby2/src/genericfrontend.cc new/yast2-core-2.17.14/liby2/src/genericfrontend.cc --- old/yast2-core-2.17.13/liby2/src/genericfrontend.cc 2008-06-13 15:52:11.000000000 +0200 +++ new/yast2-core-2.17.14/liby2/src/genericfrontend.cc 2008-09-26 11:00:11.000000000 +0200 @@ -14,17 +14,45 @@ Authors: Mathias Kettner <kettner@suse.de> Arvin Schnell <arvin@suse.de> + Stanislav Visnovsky <visnov@suse.cz> Maintainer: Arvin Schnell <arvin@suse.de> /-*/ -/* - * main function common to all Y2 components - */ - #ifndef _GNU_SOURCE #define _GNU_SOURCE // needed for vasprintf below #endif +/** + * \file + * Generic \ref main function handler for all YaST2 appliations. + */ + +/** + * \mainpage YaST2 Core System Documentation + * + * This is the main page of the YaST2 Core documentation. Some of the general topics are covered by the + * following pages: + * + * - Component architecture + * - \ref components + * - \ref componentbroker + * - \ref componentsearch + * - Handling of error codes: \ref exitcodes + */ + +/** + * \page exitcodes YaST2 Exit Codes + * + * All applications using liby2 library share a common \ref main function. The function handles the exit codes in the following way. + * + * The exit codes are described in \ref exitcodes.h header file. A special handling is applied to the value returned from the client. + * - If a value is \ref YCPNull or \ref YCPVoid, exitcode \ref YAST_OK will be used. + * - If the value is \ref YCPBoolean, \ref YAST_OK will be returned for true, \ref YAST_CLIENTRESULT for false. + * - If the value is \ref YCPInteger, the value will be added to \ref YAST_CLIENTRESULT and the resulting + * integer will be the process exitcode. + * - If the value is \ref YCPSymbol, for names defined by \ref ycp_error_exit_symbols \ref YAST_CLIENTRESULT + * will be returned, otherwise \ref YAST_OK. + */ #include <stdarg.h> #include <unistd.h> #include <signal.h> @@ -44,12 +72,21 @@ #include <YCP.h> #include <ycp/Parser.h> #include <ycp/pathsearch.h> +#include "exitcodes.h" + +/// number of symbols that are handled as error codes +#define MAX_YCP_ERROR_EXIT_SYMBOLS 2 + +/// symbol names that are handled as error codes when returned by the client +const char* ycp_error_exit_symbols[MAX_YCP_ERROR_EXIT_SYMBOLS] = { + "abort", + "cancel" +}; using std::string; ExecutionEnvironment ee; -static const int YCP_ERROR = 16; - +/// fallback name of the program static const char *progname = "genericfrontend"; static void print_usage (); @@ -262,7 +299,7 @@ if (!argv[arg]) { print_usage (); - exit (1); + exit (YAST_FEWARGUMENTS); } client_name = argv[arg]; @@ -299,13 +336,13 @@ if (option.isNull()) { print_error ("Client option -s: Couldn't parse valid YCP value from stdin"); - exit (5); + exit (YAST_OPTIONERROR); } if (!option->isList()) { print_error ("Client option -s: Parsed YCP value is NOT a YCPList"); - exit (5); + exit (YAST_OPTIONERROR); } arglist = option->asList(); // the option read _IS_ arglist @@ -387,13 +424,13 @@ { fprintf(stderr, "No server module given\n"); print_usage (); - exit (5); + exit (YAST_OPTIONERROR); } // now create server if (!argv[arg]) { print_usage (); - exit (1); + exit (YAST_FEWARGUMENTS); } server_name = argv[arg]; @@ -477,7 +514,7 @@ if (!argv[0]) { fprintf (stderr, "Missing argv[0]. It is a NULL pointer."); - exit (5); + exit (YAST_OPTIONERROR); } progname = basename (argv[0]); // get program name @@ -501,12 +538,12 @@ if (argc < 2) { fprintf (stderr, "\nToo few arguments"); print_usage(); - exit (1); + exit (YAST_FEWARGUMENTS); } if (!strcmp (argv[1], "-h") || !strcmp (argv[1], "--help")) { print_help (); - exit (0); + exit (YAST_OK); } // client _AND_ server must be given @@ -591,7 +628,7 @@ if (pos == NULL) { print_error ("Option %s argument must be in format namespace=component", argv[arg-1]); - exit (5); + exit (YAST_OPTIONERROR); } *pos = 0; Y2ComponentBroker::registerNamespaceException (argv[arg], pos+1); @@ -689,12 +726,12 @@ fprintf (stderr, " %s\n", i->c_str()); print_usage (); - exit (5); + exit (YAST_OPTIONERROR); } if (dynamic_cast<Y2ErrorComponent *>(client)) { print_error ("Error while creating client module %s", client_name); - exit (5); + exit (YAST_OPTIONERROR); } @@ -729,10 +766,30 @@ // might be useful in tracking segmentation faults y2milestone ("Finished YaST2 component '%s'", progname); - if( !result.isNull () && result->isBoolean() ) - exit( result->asBoolean()->value() ? 0 : YCP_ERROR ); + if( result.isNull () ) + exit (YAST_OK); - exit (EXIT_SUCCESS); + y2milestone( "Exiting with client return value '%s'", result->toString ().c_str ()); + + if( result->isBoolean () ) + { + exit( result->asBoolean()->value() ? YAST_OK : YAST_CLIENTRESULT ); + } + + if( result->isInteger () ) + exit( YAST_CLIENTRESULT + result->asInteger ()->value () ); + + // if it is one of error symbols, return it as error + if( result->isSymbol () ) + { + string symbol = result->asSymbol()->symbol(); + for( int i = 0 ; i < MAX_YCP_ERROR_EXIT_SYMBOLS; i++ ) + if( symbol == ycp_error_exit_symbols[i] ) + exit( YAST_CLIENTRESULT ); + } + + // all other values + exit (YAST_OK); } diff -urN --exclude=CVS --exclude=.cvsignore --exclude=.svn --exclude=.svnignore --exclude Makefile.in --exclude configure --exclude config.guess --exclude '*.pot' --exclude mkinstalldirs --exclude aclocal.m4 --exclude config.sub --exclude depcomp --exclude install-sh --exclude ltmain.sh old/yast2-core-2.17.13/liby2/src/include/y2/exitcodes.h new/yast2-core-2.17.14/liby2/src/include/y2/exitcodes.h --- old/yast2-core-2.17.13/liby2/src/include/y2/exitcodes.h 1970-01-01 01:00:00.000000000 +0100 +++ new/yast2-core-2.17.14/liby2/src/include/y2/exitcodes.h 2008-09-26 08:48:16.000000000 +0200 @@ -0,0 +1,31 @@ +/*---------------------------------------------------------------------\ +| | +| __ __ ____ _____ ____ | +| \ \ / /_ _/ ___|_ _|___ \ | +| \ V / _` ___ \ | | __) | | +| | | (_| |___) || | / __/ | +| |_|__,_|____/ |_| |_____| | +| | +| core system | +| (C) SuSE GmbH | +----------------------------------------------------------------------/ + + File: exitcodes.h + + Author: Stanislav Visnovsky <visnov@suse.cz> + Maintainer: Stanislav Visnovsky <visnov@suse.cz> + +/-*/ +// -*- c++ -*- + +#ifndef exitcodes_h +#define exitcodes_h + +enum error_codes { + YAST_OK = 0, // process finished without errors + YAST_FEWARGUMENTS = 1, // too few arguments for the commandline + YAST_OPTIONERROR = 5, // error in provided arguments + YAST_CLIENTRESULT = 16 // client (YCP) returned special result, this is used as offset (or as generic error) +}; + +#endif // exitcodes_h diff -urN --exclude=CVS --exclude=.cvsignore --exclude=.svn --exclude=.svnignore --exclude Makefile.in --exclude configure --exclude config.guess --exclude '*.pot' --exclude mkinstalldirs --exclude aclocal.m4 --exclude config.sub --exclude depcomp --exclude install-sh --exclude ltmain.sh old/yast2-core-2.17.13/liby2/src/include/y2/Makefile.am new/yast2-core-2.17.14/liby2/src/include/y2/Makefile.am --- old/yast2-core-2.17.13/liby2/src/include/y2/Makefile.am 2007-10-23 15:50:05.000000000 +0200 +++ new/yast2-core-2.17.14/liby2/src/include/y2/Makefile.am 2008-09-26 12:09:32.000000000 +0200 @@ -14,7 +14,8 @@ Y2SerialComponent.h Y2StdioComponent.h \ Y2PluginComponent.h Y2CCPlugin.h \ Y2Namespace.h \ - Y2Function.h SymbolEntry.h + Y2Function.h SymbolEntry.h \ + exitcodes.h #<INSTALL-HEADER-TARGET> diff -urN --exclude=CVS --exclude=.cvsignore --exclude=.svn --exclude=.svnignore --exclude Makefile.in --exclude configure --exclude config.guess --exclude '*.pot' --exclude mkinstalldirs --exclude aclocal.m4 --exclude config.sub --exclude depcomp --exclude install-sh --exclude ltmain.sh old/yast2-core-2.17.13/liby2/src/include/y2/Y2ComponentBroker.h new/yast2-core-2.17.14/liby2/src/include/y2/Y2ComponentBroker.h --- old/yast2-core-2.17.13/liby2/src/include/y2/Y2ComponentBroker.h 2008-05-05 20:43:38.000000000 +0200 +++ new/yast2-core-2.17.14/liby2/src/include/y2/Y2ComponentBroker.h 2008-09-26 10:52:41.000000000 +0200 @@ -34,6 +34,41 @@ class Y2Component; /** + * \page componentbroker YaST2 Component Broker + * \author Matthias Kettner + * \todo clean up and update + * + * <h2>How the component broker works</h2> + * + * liby2 is the library which does all the stuff + * + * in \ref Y2ProgramComponent.cc the server/client is started + * (\ref launchExternalProgram) by connecting pipes for stdin/stdout + * and starting the program via fork/execve. + * + * The program is searched via \ref pathsearch.cc and must reside + * in a sub-directory "clients" or "servers". + * The $HOME directory is a special case, as a sub-dir $HOME/.yast2 + * must exists. + * + * Every program starts via \ref main() \ref genericfrontend.cc + * + * The \ref main() function parses argv and starts + * the client (\ref Y2ComponentBroker::createClient) and the + * server (\ref Y2ComponentBroker::createServer) for the component + * + * Expressions are 'commands' to the server and sent via + * "...Component::evaluate (const YCPValue& command)" + * + * evaluate() starts the 'real' component if it is not already + * running. + * + * \ref doActualWork() is used for client components + * + * \ref result() is used to finish server components + */ + +/** * @short Looks for and creates YaST2 components * This class has no instances and only static methods. * There are two reasons for this: @@ -50,6 +85,8 @@ * exist. During global constructor call time (before main), the * constructors of the @ref ComponentCreator classes <i>register</i> * themselves to the component broker. + * + * For more details, see \page componentbroker */ class Y2ComponentBroker { diff -urN --exclude=CVS --exclude=.cvsignore --exclude=.svn --exclude=.svnignore --exclude Makefile.in --exclude configure --exclude config.guess --exclude '*.pot' --exclude mkinstalldirs --exclude aclocal.m4 --exclude config.sub --exclude depcomp --exclude install-sh --exclude ltmain.sh old/yast2-core-2.17.13/liby2/src/include/y2/Y2Component.h new/yast2-core-2.17.14/liby2/src/include/y2/Y2Component.h --- old/yast2-core-2.17.13/liby2/src/include/y2/Y2Component.h 2007-06-25 11:19:13.000000000 +0200 +++ new/yast2-core-2.17.14/liby2/src/include/y2/Y2Component.h 2008-09-26 10:54:37.000000000 +0200 @@ -33,8 +33,199 @@ class YCPList; /** + * \page components YaST2 Component Architecture + * + * \author Mathias Kettner + * + * \todo This is partially obsolete! + * + * <h2>Design principles</h2> + * + * <p>The YaST2 component model is the foundation of the + * YaST2 architecture. It is important to understand at least + * the basic ideas in order to be able to write new Y2 components. + * It's based upon the following design principles: + * + * <p><table cellspacing=0 BGCOLOR="#f96500" width="100%"><tr><td> + * <table width="100%" bgcolor="#ffc080" cellpadding=10><TR><TD> + * <ul> + * + * <p><li><i>YaST2 should be easily extensable. One should be able + * to exchange or add functionality independent + * of all other parts.</i>This leads to a modular architecture. + * The interchangable parts are called 'components'.</li> + * + * <p><li><i>It should be possible, that a component can be added + * or exchanged merely through the fact, that a file has been + * added or exchanged.</i> This allows you to put configuration + * modules for a software into the same package as that software. + * For example you could write a configuration module for + * sendmail and put it into the sendmail package. As long as + * the sendmail package is installed, its YaST2 configuration + * module is available.</li> + * + * <p><li><i>Despite the need for Y2 to be modular in concept, + * during execution time this should not lead to high communication + * overhead or large need in memory usage or the number of + * concurrently running processes.</i></li> + * + * <p><li><i>The inter-component communication should be human + * readable, at least in debugging situations.</i></li> + * + * <p><li><i>The inter-component communication should be network + * transparent.</i></li> + * + * <p><li><i>It should be easy to write a component. Component implementing + * should not be restricted to a certain programming language.</i> + * + * </ul> + * </td></tr></table> + * </td></tr></table> + * + * <h2>Communication</h2> + * + * <p>All components speak a common language and act according to + * defined protocol. Both the language and the protocol are + * called <i>YCP (YaST2 communication protocol)</i>. One protocol + * step consists of one of the partners sending exactly one + * <a href="../libycp/YCP-datatypes.html">YCP value</a> + * to the other and the other receiving that value. In the + * next step, the component that just was receiving, is now sending and + * vice versa. The only exception is, that one of that partners + * may terminate the session and send a last <i>result</i> message + * after which - of course - the partner won't send another value. + * + * <h2>Clients and Servers</h2> + * + * <p>There are two different kinds of components: server components and + * client components, which differ in how the control flows. + * + * <p>A <i>server</i> component is one that - once it's initialized - + * just waits for jobs to do. Another component can send a <i>request</i> + * and thus pass the control to the server. That does what is neccessary + * in order to do handle the request and returns an + * <i>answer</i>. Prominent examples for server components are the user + * interfaces. In YaST2 they play a <i>passive</i> role. They just wait + * for a command like "Show me this dialog, wait for the next user + * input and return me that input". A server component can also use + * the service of another server component. For example the <i>SCR + * (System configuration repository)</i> makes use of servers called + * <i>agents</i>, which realize subtrees of the SCR tree. + * + * <p>A <i>client</i> component is one that controls the flow. It may + * contain something like an "event loop". In order to do its + * work, it can use the services of other server components. Client + * components are sometimes called <i>modules</i>. Examples for + * modules are the single steps of the YaST2 "Installation + * Wizard" or the program that calls <tt>rpm</tt> to install + * packages. Other examples could be a module that configures the network + * setup of a workstation or one, that just sets the IP-number and the + * hostname of that workstation. + * + * <p>Modules can be hiearchically structured + * and hand over control to other modules that acomplish sub tasks and + * are called <i>submodules</i> in this context. An example is the + * structure of the YaST2 installer. The installation itself is + * a module. For each of the wizard window steps, it calls a submodule. + * + * <h2>How components are realized</h2> + * <p>There are quite a number of ways how you can implement a component. + * A component can be: + * <p><table cellspacing=0 BGCOLOR="#f96500" width="100%"><tr><td> + * <table width="100%" bgcolor="#ffc080" cellpadding=10><TR><TD> + * <ul> + * + * <li>An executable program (ELF, /bin/sh, or whatsoever)</li> + * <li>A C++ class using <tt><a href="../libycp/autodocs/intro.html">libycp</a></tt> + * and <tt><a href="../liby2/autodocs/intro.html">liby2</a></tt></li> + * <li>A YCP script executed by the <i>Workflowmanager</i></li> + * <li>Youself typing some YCP code at a terminal</li> + * + * </ul> + * </td></tr></table> + * </td></tr></table> + * + * <p>Don't laugh over the last possibility! For debugging this is sometimes + * very helpful. You can simulate <i>any</i> component by typing to a terminal. + * + * <h3>Executable programs</h3> + * + * <p>A component that exists as <i>executable program</i> is realized by + * a process that is created when the component is needed. If a component + * needs the services of an external program component, it launches a + * seperate process and starts a communication via two unix pipes, one in + * each direction. + * + * <p>The data flowing through these pipes is YCP Ascii + * representation. Each communication side needs a parser to analyse the + * data and a YCP syntax generater to write data to the pipe. Both can be + * found in the <tt><a href="../libycp/autodocs/intro.html">libycp</a></tt>, + * which can only used from C++ programs. + * + * <p>But the production of YCP code + * can in many cases very easily be done be printing to stdout, for + * example with <tt>echo</tt> (shell) or <tt>printf</tt> (C). + * + * <p>The parsing of YCP code is as bit more tricky. But in many cases you + * don't need a full featured parser, because you know beforehand what structure + * the value have that you get. This especially holds for client components, + * because they can decide, how the output from the server should look like. + * + * <h3>C++ class using libycp and liby2</h3> + * <p>If you anyway decide to write your component in C++, + * it's by far the most conveniant way to use the functionality + * of libycp and liby2, whose only purpose is excactly to support + * component implementation. + * + * <p>What you have to do is to subclass at least two classes: + * <tt><a href="../liby2/autodocs/Y2ComponentCreator.html">Y2ComponentCreator</a></tt> and + * <tt><a href="../liby2/autodocs/Y2Component.html">Y2Component</a></tt> and + * + * <p>Depending on whether you want to implement a server or a client component + * you have to override different methods. Many examples can be found within the liby2 + * itself. + * + * <p>One big advantage of writing a component in C++ is, that + * you can very easily create three external appearances of the component: + * <ul> + * <li>A selfcontained executable program</li> + * <li>A shared library plugin to load during runtime</li> + * <li>A static library that can be linked together with other components</li> + * </ul> + * + * <p>The YaST2 installer makes usage of the third variant only. All required components + * are linked together to <tt>y2base</tt>, which is statically linked against liby2 and + * libycp. The memory usage is reduced as well as the required disk space. Furthermore + * no creating and parsing of Ascii streams between the components is required. Protocol + * steps are simple function calls. Even for very large data structures, only one pointer + * has to be passed. + * + * <h3>A YCP script executed by the <i>Workflowmanager</i></h3> + * <p>If you have installed YaST2, you will find some files ending in <tt>.ycp</tt> + * lying around in <tt>/lib/YaST2/clients</tt>. These are YCP scripts implementing + * client components (modules). YCP is not only a protocol, it is also a full features + * programming language, which is in this case used to implement components. This is + * very conveniant as the language can directly operate on the protocol values and + * has some other nice features. + * + * <p>The client scripts are executed by the <i>Workflowmanager</i>, which is an + * extension to the core YCP language. It implements a couple of builtin functions + * that allow communication the the system and with other + * components. Here is a + * <a href="../y2wfm/YCP-builtins-wfm.html">of builtins.</a>. + * + * <h3>Youself typing YCP code at a terminal</h3> + * <p>You can be a component yourself :-). Just tell another component to communicate + * via stdio and speak with it. For example you can launch the component <tt>ycp</tt> by + * typing <tt>y2ycp stdio</tt>. Now you can enter YCP expressions and get the evaluation + * as answer. + */ + +/** * @short Communication handle to a YaST2 component. - * @see Y2ComponentBroker. + * @see componentbroker + * @see Y2ComponentBroker + * * YaST2 is a network oriented client/server architecture. * Currently there exist five differnt types of components: * userinterfaces, modules, the workflowmanagers, the diff -urN --exclude=CVS --exclude=.cvsignore --exclude=.svn --exclude=.svnignore --exclude Makefile.in --exclude configure --exclude config.guess --exclude '*.pot' --exclude mkinstalldirs --exclude aclocal.m4 --exclude config.sub --exclude depcomp --exclude install-sh --exclude ltmain.sh old/yast2-core-2.17.13/VERSION new/yast2-core-2.17.14/VERSION --- old/yast2-core-2.17.13/VERSION 2008-09-25 12:21:33.000000000 +0200 +++ new/yast2-core-2.17.14/VERSION 2008-09-26 12:19:00.000000000 +0200 @@ -1 +1 @@ -2.17.13 +2.17.14 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Remember to have fun... -- To unsubscribe, e-mail: opensuse-commit+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-commit+help@opensuse.org