How to comment functions and variables This section describes how to comment functions for other YaST tools to let them generate documentation automatically. Documentation is generated by script /usr/lib/YaST2/bin/ycpdoc which can be found in the yast2-devtools package. See more detailed information by typing perldoc /usr/lib/YaST2/bin/ycpdoc. More examples can be found in the yast2-devtools package or in the /usr/share/doc/packages/yast2-devtools/ycpdoc/example/ directory. This is the exemplary file header ycpdoc recognizes comments when they are marked with special syntax /** * some description * can be multiline */ Exemplary function comment Exemplary variable descriptions How to read and write text files in YaST? Use .target.string path of 'system agent' to manipulate with the text files. The Read function returns the whole contents as a one string, with the write variant you can rewrite the file. Documentation of system agent can be found at /usr/share/doc/packages/yast2-core/agent-system Check for existing SCR agents for various configuration files. If you want to read/edit/write known config file, it is very likely that SCR agent for this file already exists. The easy way to find this out is grep the files under /usr/share/YaST2/scrconf/ directory for the file name. If you want to manipulate with a file contents (e.g. delete or rewrite some line) it is possible to use AsciiFile module, which describes the file by the map. map file = $[]; AsciiFile::ReadFile (file, "/tmp/myfile"); // now you can check the 'file' map manually // or using AsciiFile interface ... AsciiFile::RewriteFile (new_map, "/tmp/myfile"); For more, look directly into /usr/share/YaST2/modules/AsciiFile.ycp. How to read and write sysconfig values? First, you need the scr file which actually calls an agent that handles this type of files. In this case it is done using the so called ini agent which can handle multiple types of config files, not only ini files. The following listing is an example scr script which calls the ini agent special handling for sysconfig files: Now, this file has to be installed in /usr/share/YaST2/scrconf/ directory. In you ycp code, you can access the variable TESTING the following way: string test = (string) SCR::Read(.sysconfig.novell-apache.TESTING); and you can write it: SCR::Write(.sysconfig.novell-apache.TESTING, "a value"); For most sysconfig files, there already exist the agents - you can grep in /usr/share/YaST2/scrconf/ directory for the file name you are looking for. // read the BASE_CONFIG_DN variable from /etc/sysconfig/ldap string base_config_dn = SCR::Read (.sysconfig.ldap.BASE_CONFIG_DN); // ... and save the new value SCR::Write (.sysconfig.ldap.BASE_CONFIG_DN, new_dn); For documentation, see /usr/share/doc/packages/yast2-core/agent-ini/ini.html How to run external programs? Use 'system agent' documented in /usr/share/doc/packages/yast2-core/agent-system/. Using .target.bash path you can run bash command, defined by the string parameter. The last parameter can be used to give initial environment definitions to the target. The keys have to be strings, the values can be of any type. The return value is an integer with the exitcode. If you use .target.bash_output path, the return value will be the map: $[ "exit" : <integer>, //exitcode from shell script "stdout" : <string>, //stdout of the command "stderr" : <string> //stderr of the command ] Where are proposal screens handled during 2nd stage of installation? For each proposal the control file /var/lib/YaST2/control.xml contains a list of clients to be called. The tag <proposal> describes the name of the client. Then, the name is suffixed by _proposal, for instance proxy_proposal.ycp, and such client is started via WFM::Call. The required action is done by a command line argument. Each proposal client has to implement the following arguments: MakeProposal - prepare a proposal, return its summary AskUser - start the GUI for user to manually modify the proposal Description - return a map for title, entry in the menu button and your id Write - user accepted the proposal, write it down For more details see *_proposal.ycp clients in /usr/share/YaST2/clients/ directory and documentation in /usr/share/doc/packages/yast2-installation/. Where the YaST2 logs can be found? Logs are situated in the /var/log/YaST2/ directory. They are named y2log and from y2log-1 to y2log-9, rotated in the size at about 1.1 MB. How is YaST2 logging done? YaST2 loggings are done using y2* built-in functions. This is a simple program, which should help us with the logging. y2debug is used only for the debugging information, only for testing because it is not logged during the normal run of the YaST2. It is usable only for the developer. y2milestone is used for logging some important information. For instance Configuration has been changed, saving into the '/etc/any.conf'. y2milestone("Configuration has been changed, saving into the '%1'", "/etc/any.conf"); y2warning is used to announce that something would go wrong. For instance when any configured card has been lost after the reboot. y2error is used for major problems. For instance if YaST2 didn't find what it expected and needed. y2security is not used. y2internal is not used. And this is the part of the log found in the logfile /var/log/YaST2/y2log after we have runned Y2DEBUG=1 yast2 y2logs.ycp, we would not see any debug information if we would run yast2 y2logs.ycp only. 2004-09-21 10:04:13 <0> wizard(5964) [YCP] y2logs.ycp:2 debug 2004-09-21 10:04:13 <1> wizard(5964) [YCP] y2logs.ycp:3 milestone 2004-09-21 10:04:13 <2> wizard(5964) [YCP] y2logs.ycp:4 warning 2004-09-21 10:04:13 <3> wizard(5964) [YCP] y2logs.ycp:5 error 2004-09-21 10:04:13 <4> wizard(5964) [YCP] y2logs.ycp:6 security 2004-09-21 10:04:13 <5> wizard(5964) [YCP] y2logs.ycp:7 internal Format of the log is [year]-[month]-[day] [time] [log-weight] [process-name](PID) [library] [filename]:[line-number] [message]. y2* built-in functions accepts maximally 9 parameters of variables: y2milestone("This is the example for %3, %4, %1 and %2", "1st parameter", "2nd parameter", "3rd parameter", "4th parameter"); Each %[number] is replaced by the corresponding variable. Parameters can be all types (function, boolean, integer, map ...). How to mark any text for the translation? There are two internal functions for marking the text for the translation. They are _(string text) (single underscore) in YCP and __(string text) (double underscore) in Perl. It is needed to place every single calling of the function on the separate line because of making .pot file. Every text marked for translation should be commented above for the translators. What kinds of VALIDATION code has been implemented in modules? For simple syntax validation there is a lot of it, but only the basic ones are grouped together in the yast2.rpm. Those are: IP::Check(), IP::Check4(), IP::Check6() for IP addresses checking Hostname::Check(), Hostname::CheckDomain(), Hostname::CheckFQ() for Hostnames (DNS) Address::Check(), Address::Check4(), Address::Check6() for addresses (IP or a hostname) Netmask::Check(), Netmask::Check4(), Netmask::Check6() for netmasks URL::Check() for URL syntax For the rest you need to lookup in the corresponding YaST modules. Are there some good examples of the use of Wizard? Any documentation? See /usr/share/doc/packages/yast2/wizard/examples/ and /usr/share/doc/packages/yast2-core/libyui/examples/Wizard... The wizard is controlled by the Wizard YCP module (import "Wizard"). It's documentation is in /usr/share/YaST2/modules/Wizard.ycp. What is the semantics of Wizard::SetDesktopIcon ("proxy") ? This sets the icon at the left side of the dialog title label to the one used by the yast2-proxy desktop file. It is the same as appears in the yast2 control center. What is the semantics of Wizard::CreateDialog() ? This creates a Wizard Dialog. This is the basic framework used in YaST screens with help on the left and the YaST graphics on top. At the bottom there are usually three buttons, Back, Abort and Next. This is how a workflow is implemented. However, in the last step of a workflow, naming the rightmost button "next" isn't appropriate. Wizard::SetNextButton (`next, Label::FinishButton); replaces the button caption with "Finish". In some dialogs you need to hide some default buttons or to restorem them again. Wizard::HideBackButton (); hides the Back button. Wizard::RestoreAbortButton (); restores hidden Abort button. What is the meaning of YCP files generated by y2tool? TODO ... more about templates, and devtools Has anyone created a YaST mode for EMACS? TODO Syntax file for VIM is part of SUSE's vim package. How to add a user using a script? For documentation of whole Users module API, look at /usr/share/YaST2/modules/YaPI/USERS.pm Could be any map seen as a tree? Maps which you can find in y2log are not human-readable. You can use the tree view in UI which is the one you can find in yast2-testsuite package. As you can see, this is very ugly map. Run yast2 debug_map.ycp to open the UI tree and browse the map. How to create a new YaST module Use the /usr/bin/y2tool create-new-package. y2tool is included in the yast2-devtools package. /usr/bin/y2tool create-new-package -s returns a list of available skeletons. They are: agent - SCR agent skeleton config - YaST configuration module skeleton trans - YaST translation To create a new YaST module run: /usr/bin/y2tool create-new-package -v config module-name "Maintainer Name" maintainer@email.com How to test the YCP code? Use simple command ycpc -E source.ycp. It would report errors it it would find any. Attention: files imported and included in the source are got from the default YaST2 directory /usr/share/YaST2/ first of all other locations. How to test the SCR agent? Use the /usr/lib/YaST2/bin/y2base stdio scr command which allows you to send commands directly to the SCR. Commands are `Dir(path), `Read(path) and `Write(path). How to start and stop services? Service Manipulation Service Enabling Service Information Documentation can be found in /usr/share/doc/packages/yast2/runlevel/ How to test the first stage installation (before reboot)? ... How to test the second stage installation (after reboot)? ... How to test the installation proposals? You can use this code to test the `network installation proposal: Run yast2 network_proposal.ycp to open the UI with the appropriate installation proposal. There are more proposals with in more stages. You should find it in the control.xml file. Proposal: `initial, Stage initial for the first stage installation Proposal: `dirinstall, Stage normal for the installation into the directory Proposal: `network, Stage continue for the second stage network configuration Proposal: `hardware, Stage continue for the second stage hardware configuration How to test YaPI and PerlAPI functions? There more methods of testing YaPI and PerlAPI functions. Let me show you one of them - simple YCP script. Run this simple script using the yast2 samba.ycp command and see the log for the result. Here are the interesting parts of the log: "shares":[ $["options":[ $["key":"public", "value":"yes"]], "share":"NEW1_SHARE" ] ] at the "Export_B". "shares":[ $["options":[ $["key":"public", "value":"yes"]], "share":"NEW1_SHARE" ], $["options":[ $["key":"public", "value":"no"]], "share":"NEW2_SHARE" ] ] at the "Export_C". This is the PerlAPI implementation of the same functionality: This is another example of the YaPI testing. It will open the popup window with an error message. How to test the AutoYaST? ... How to test the AutoInstallation? ...