diff options
558 files changed, 54688 insertions, 0 deletions
diff --git a/AccountMaintenance.mdwn b/AccountMaintenance.mdwn new file mode 100644 index 00000000..61fe4627 --- /dev/null +++ b/AccountMaintenance.mdwn @@ -0,0 +1,40 @@ + +This page is not about getting new accounts. If you do not currently have a fd.o account, see [[AccountRequests]]. + + +# Account Maintenance + +freedesktop.org uses a user management system entitled userdir-ldap. More information on ud-l can be found at [[Debian's information page|http://db.debian.org/doc-mail.html]]. + +This page describes the mail interface, which assumes you have a GPG key attached to your account. If this is not the case, please file a bug on [[the Account Changes component|https://bugs.freedesktop.org/enter_bug.cgi?product=freedesktop.org]] in Bugzilla first, with your GPG key attached as a text/plain file, and noting the account which the key should be attached to. Please also make sure it's visible on the subkeys.pgp.net keyserver. + +The web interface is not operational at this time. + + +## Adding/removing SSH keys + +The mail gateway maintains SSH keys by _replacing_ all keys with the contents of the mail. Send the mail, GPG-signed, each key on a new line: + + cat ~/.ssh/key1.pub ~/.ssh/key2.pub ~/.ssh/key3.pub | gpg --clearsign | mail change@db.freedesktop.org + +You will receive a mail back within a few minutes confirming your changes. Note again that this replaces the entire list of keys: following the example above, if you previously had key1 and key4 active, the new set would be key1, key2, and key3: key4 would be excluded. Note that this is important as password logins are not available on freedesktop.org. + +**Only RSA keys are accepted!** Due to security reasons relating to an OpenSSL vulnerability, DSA keys (as well as legacy RSA1 keys) will not be accepted. + +**Note: Your total key length must be <=1024 characters in ascii, hence anything longer than a 4096bit key will not work** + +**Note2: If you get the error: "Message Error: Verification of signature failed" your email is probably being line wrapped, try a different client** + +**Note3: If you never get a reply back, make sure your return address is actually valid.** +## Changing email address + + echo 'emailforward: new@address.com' | gpg --clearsign | mail change@db.freedesktop.org + +## Getting a copy of your current details + + + echo 'show' | gpg --clearsign | mail change@db.freedesktop.org + +Your LDAP record will be mailed back to you, GPG-encrypted. Most of these details can be changed by sending the same string back to [[change@db.freedesktop.org|mailto:change@db.freedesktop.org]], e.g.: + + echo 'gecos: Full Name' | gpg --clearsign | mail change@db.freedesktop.org diff --git a/AccountRequests.mdwn b/AccountRequests.mdwn new file mode 100644 index 00000000..53b4fbb3 --- /dev/null +++ b/AccountRequests.mdwn @@ -0,0 +1,53 @@ +# How to request a freedesktop.org account + +To obtain an account for a project hosted by freedesktop.org, you must follow these rules. Failure to do so will probably result in your request getting dropped on the floor. Don't take it personally if it does, the rules are there to make sure it doesn't happen, so if they aren't followed ... + + +## What you need + +Passwords are not used for the accounts at freedesktop.org. Instead, SSH keys are used. Therefore, you will need to have you SSH key at hand when requesting an account. Also, you must have a GPG key available so that you can identify yourself for future account maintainance requests. + +If you already have an account, and these key are already in place, then you don't need to supply them with your request. + + +## Requesting a New Account + + +### What you do + +* go to <http://bugs.freedesktop.org> +* Create a bug asking for an account. Select the Product that corresponds to the Project for which you are requesting access. If there's no product in bugzilla for the project in question, file it against the freedesktop.org product, in the New Accounts component. +* You MUST include your real name, email address, and a preferred account name. +* You MUST attach both your SSH (RSA only -- no DSA!) and GPG public keys to this bug. Please attach them as text/plain. Please make sure you add them as attachments, not inline in the bug. +* Verify that your GPG key is visible via subkeys.pgp.net: `gpg --keyserver subkeys.pgp.net --send-keys 0xdeadbeef` + +(replace `0xdeadbeef` with your key id; note also that the server is subkeys.**pgp**.net, not subkeys.gpg.net) + +To generate a GPG key, run `gpg --gen-key`, and `gpg --export -a <your email address>` to export the public key in a format suitable for attaching. You MUST keep your private key secure; anyone with your private key can now get access to fd.o machines, and potentially compromise source code! A strong passphrase is recommended, as is not keeping it on any public machines. If a private key is found on a freedesktop.org machine, it will be removed from the keyring, and a new one will have to be created. + +To generate an SSH key, run `ssh-keygen -t rsa -f ~/.ssh/mykey-fdo`. Key type **must** be 'rsa': neither DSA nor RSA1 keys will be accepted. This will put your new public key in `~/.ssh/mykey-fdo.pub`; to use it, add `-i ~/.ssh/mykey-fdo` to your SSH command line (e.g. `ssh -i ~/.ssh/mykey-fdo annarchy.freedesktop.org`), or create a stanza in `~/.ssh/config` like so: + + Host *.freedesktop.org + User myusername + IdentityFile ~/.ssh/mykey-fdo + +Mac users should see [[MacGPG|http://macgpg.sourceforge.net/]] for information about running GPG on Mac. Windows users should see [[PuTTY|http://www.chiark.greenend.org.uk/~sgtatham/putty/]] for information on using SSH clients in Windows, including key generation. + +_DO NOT ATTACH YOUR PRIVATE SSH KEY. DOUBLE CHECK THAT IT IS A ONE-LINE PUBLIC KEY, AND NOT A PRIVATE KEY._ + + +### What the Project Leader does + +* Review and approve the request for an account & access to your project. +* Reassign the bug to the **freedesktop.org** Product with the Component set to **New Accounts**, Make sure the owner is changed to ** [[sitewranglers@lists.freedesktop.org|mailto:sitewranglers@lists.freedesktop.org]] **. +If everything is in order, and all of the data is provided, then the account will be created, usually within a few days, with possible exceptions around holidays and major conferences. Don't freak out if it ends up taking longer than this: we're all humans, sometimes we're busy humans. Your request isn't being ignored or forgotten, it's just that no-one has the time to get to it right now. + + +## Requesting Modifications + +If you want to add a GPG key to your account or get added to another project, this requires manual intervention. Go to [[Bugzilla|https://bugs.freedesktop.org/enter_bug.cgi]] and file a new bug. If you need to add a GPG key, assign it to freedesktop.org, component Account Changes; if you need to be added to a new project, assign it to that project (not freedesktop.org) for approval by the project maintainer. Project leaders will follow the same procedure as above to approve an addition request. + + +# Account Maintenance + +For details on how to change your SSH keys, email address, etc, see [[AccountMaintenance]]. diff --git a/ApplicationPackageSpec.mdwn b/ApplicationPackageSpec.mdwn new file mode 100644 index 00000000..d7d7a4e6 --- /dev/null +++ b/ApplicationPackageSpec.mdwn @@ -0,0 +1,163 @@ +# Application Package Specification (Idea) + + +## Introduction + +This specification is designed to provide a desktop neutral way to package one application. + +Dependencies can be installed on first start of the application. The necessary runtime environment should be installed (may use of packagekit) and the runtime environment should install the necessary modules. + + +## Package Structure + +A application-package is an archive containing the application and a file describing all the contents. The archive should be a gzip-compressed tarball with an .app extension. + + + / + /info + /app/ + + +### Package Description + +The info file should be formatted as followed: + + +#### Package Name + + [Application] + Name=Example application + +The Name of the application, it is required for identification-purposes. + + +#### ApplicationPackage-file version + + Version=1.0 + +The Desktop-file syntax version, this field must be present. + + +#### Mime-type + + Type=X-ApplicationPackage + +The mime-type, this field must be present and have the value _X-Application``Package_. + + +#### Executable file + + Exec=example.bin + +This field represents the main executable file of the application. It must be present. + + +#### Mime-type of executable file + + ExecType=application/x-executable + +This field represents the mime-type of the main executable file of the application. It must be present. + + +#### Maintainer + + Maintainer=John Doe <john DOT doe AT freedesktop DOT org> + +The Theme``Package maintainer, this field should be present and formatted as followed + + _Name < email >_ + +If for some reason this field is not available, implementations may choose to warn a user about this fact. + + +#### Application version + + Application-Version=1.0 + +The Application``Package version-number (increases with every update), this field should be present and formatted as followed + + _a[.b[.c[.d[.e]]]]_ + +Where a, b, c, d and e are numbers between 0 and 4294967296 (32 bits unsigned integers). + + +##### Author(s) / Artist(s) name(s) + + Authors=Jane Doe <jane AT freedesktop DOT org>; John Doe <john AT freedesktop DOT org> + +The author(s) of the application, this field may be present. + + _Name < email >[; Name < email >[; etc...]]_ + + +##### Package Description + + Description=This example application is a great multiplayer game for the whole family. You can use your keyboard and your mouse. For more information see our website: www.greatgame.example. + +This field provides a description about the application. + + +##### Application License Information + + License=GPL;Creative-Commons + +The License under which the application is distributed. + + +##### Icon + + Icon=http://example.com/example_app_icon.svg + +Icon to display in the software center, menus, etc. The name of the file should be either an web address or a name according to the [[Icon Theme Specification|Specifications/icon-theme-spec]]. + + +##### Web address for download + + DownloadURL=http://example.com/example.app + +The web address which allows to download the application again. + + +##### Update information + + UpdateInfo=http://example.com/example.info + +An info file according to this spec. This file must content an DownloadURL field. It should provide a never version if available. This specification allows to put information about several versions in one info file. + + +### info Example + + [Application] + Name=Example application + Version=1.0 + Type=X-ApplicationPackage + Exec=example.bin + ExecType=application/x-executable + Maintainer=John Doe <john AT freedesktop DOT org> + Application-Version=1.0 + Authors=Jane Doe <jane AT freedesktop DOT org>; John Doe <john AT freedesktop DOT org> + Description=This example application is a great multiplayer game for the whole family. You can use your keyboard and your mouse. For more information see our website: www.greatgame.example. + License=GPL;Creative-Commons + Icon=http://example.com/example_app_icon.svg + DownloadURL=http://example.com/example.app + UpdateInfo=http://example.com/example.info + + +### app directory + +This directory contains the application files. This directory will be used to look for the exec file which is stated in the info file. + + +### Installation + +The user should be able to copy the application to applications:// to register the application. At all you don't need to install the application, just execute the app-file to use the application. The system will may share the application for multiple users. + + +### Security considerations + +Software according to this specification should run in a sandbox. The application is not allowed to read any personal information from the home directory. Therefore each [[ApplicationPackage]] gets his own home directory with write access. A special file selector widget should allow applications to read and write to specific files chosen by the user. + + +### Internationalization + +The package server should be able to provide descriptions of packages in the user's language. diff --git a/Arphic_Public_License.mdwn b/Arphic_Public_License.mdwn new file mode 100644 index 00000000..8cd227d2 --- /dev/null +++ b/Arphic_Public_License.mdwn @@ -0,0 +1,70 @@ + +ARPHIC PUBLIC LICENSE + +Copyright (C) 1999 Arphic Technology Co., Ltd. + +11Fl. No.168, Yung Chi Rd., Taipei, 110 Taiwan + +All rights reserved except as specified below. + +Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is forbidden. + +Preamble + +The licenses for most software are designed to take away your freedom to share and change it. By contrast, the ARPHIC PUBLIC LICENSE specifically permits and encourages you to use this software, provided that you give the recipients allthe rights that we gave you and make sure they can get the modifications of this software. + +Legal Terms + +0. Definitions: + +Throughout this License, "Font" means the [[TrueType|TrueType]] fonts "AR PL Mingti2L Big5", "AR PL KaitiM Big5" (BIG-5 character set) and "AR PL SungtiL GB", "AR PL KaitiM GB" (GB character set) which are originally distributed by Arphic, and the derivatives of those fonts created through any modification including modifying glyph, reordering glyph, converting format, changing font name, or adding/deleting some characters in/from glyph table. + +"PL" means "Public License". + +"Copyright Holder" means whoever is named in the copyright or copyrights forthe Font. + +"You" means the licensee, or person copying, redistributing or modifying theFont. + +"Freely Available" means that you have the freedom to copy or modify the Font as well as redistribute copies of the Font under the same conditions you received, not price. If you wish, you can charge for this service. + +1. Copying & Distribution + +You may copy and distribute verbatim copies of this Font in any medium, without restriction, provided that you retain this license file (ARPHICPL.TXT) unaltered in all copies. + +2. Modification + +You may otherwise modify your copy of this Font in any way, including modifying glyph, reordering glyph, converting format, changing font name, or adding/deleting some characters in/from glyph table, and copy and distribute such modifications under the terms of Section 1 above, provided that the following conditions are met: + +a) You must insert a prominent notice in each modified file stating how and when you changed that file. + +b) You must make such modifications Freely Available as a whole to all thirdparties under the terms of this License, such as by offering access to copy themodifications from a designated place, or distributing the modifications on a medium customarily used for software interchange. + +c) If the modified fonts normally reads commands interactively when run, youmust cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide awarranty) and that users may redistribute the Font under these conditions, and telling the user how to view a copy of this License. + +These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Font, and can be reasonably considered independent and separate works in themselves, then this License and its terms, do not apply to those sections when you distribute them as separate works. Therefore, mere aggregation of another work not based on the Font with the Font ona volume of a storage or distribution medium does not bring the other work under the scope of this License. + +3. Condition Subsequent + +You may not copy, modify, sublicense, or distribute the Font except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Font will automatically retroactively void your rights under this License. However, parties who have received copies or rights from you under this License will keep their licenses valid so long as such parties remain in full compliance. + +4. Acceptance + +You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to copy, modify, sublicense or distribute the Font. These actions are prohibited by law if you do not accept this License. Therefore, by copying, modifying, sublicensing or distributing the Font, you indicate your acceptance of this License and all its terms and conditions. + +5. Automatic Receipt + +Each time you redistribute the Font, the recipient automatically receives a license from the original licensor to copy, distribute or modify the Font subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License. + +6. Contradiction + +If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposedon you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence youmay not distribute the Font at all. For example, if a patent license would not permit royalty-free redistribution of the Font by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Font. + +If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances. + +7. NO WARRANTY + +BECAUSE THE FONT IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE FONT, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS OR OTHER PARTIES PROVIDE THE FONT "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE FONT IS WITH YOU. SHOULDTHE FONT PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. + +8. DAMAGES WAIVER + +UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING, IN NO EVENT WILL ANY COPYRIGHTT HOLDERS, OR OTHER PARTIES WHO MAY COPY, MODIFY OR REDISTRIBUTE THE FONT AS PERMITTED ABOVE, BE LIABLE TO YOU FOR ANY DIRECT, INDIRECT, CONSEQUENTIAL, INCIDENTAL, SPECIAL OR EXEMPLARY DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE FONT (INCLUDING BUT NOT LIMITED TO PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA OR PROFITS; OR BUSINESS INTERRUPTION), EVEN IF SUCH HOLDERS OR OTHER PARTIES HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. diff --git a/Bango.mdwn b/Bango.mdwn new file mode 100644 index 00000000..3519eaa8 --- /dev/null +++ b/Bango.mdwn @@ -0,0 +1,89 @@ + + +# The Bango Project + +Original forum post [[http://www.ubuntuforums.org/showthread.php?p=919723#post919723|http://www.ubuntuforums.org/showthread.php?p=919723#post919723]] + +Also this can be found on the ubuntu wiki here [[https://wiki.ubuntu.com/Bango|https://wiki.ubuntu.com/Bango]] + +I was changing the sounds on my computer today, and realized what a drag is was. I m often not at my computer 100% of the time, even though it is on, and so i need alerts to tell me when i have a new email or IM message, or for other reasons. + +Anyway, I got thinking about why there is no gnome sound theme available, you can change the individual files for notifications etc in preferences > sounds, but this isn't great, I really don't want to go through and select each file. What i really want is to download a theme of gnome-look.org or something similar, and just drag it onto the theme manager, and let it install all the files for me. + +The big trouble with this right now is there is no specification that I know of for desktop sounds. I may be wrong here. + +Then I got thinking a little more, about the tango project. This has been great, it not only creating a detailed specification allowing applications to share common icons, i want the same play button on all my media applications!, but it also provides guidance on the design of icons, how to use shadows or colours for instance. + +So what had this got to do with sounds files? Well I had a thought that it would be really cool if a similar effort sound be set up for sounds on computers. For computer newbies, sounds can be a great way to provide feedback on their actions, making the gulf between a real world action action and its results on screen seem smaller from a user perspective. + +So I am proposing the bango project, why bango? well, sounds like tango for one thing, and bango - kinda like making a noise with the bang part. Mind you, i am open to suggestions for the name + +What would this project do? Well for one thing provide useful guidance on how to match events on the screen to sounds. How should someone create a sound event for an email arriving, or for when an application crashes, or when a user logs in. + +The project should also be responsible for carrying our usability testing on a range of users. Making sure these sounds themes enhance the users computing experience. + +Most importantly however, the group should work with freedesktop.org to produce a specification for sounds themes, similar to the tango project. This will allow the project to span multiple desktop environments like tango. If a developer wanted a sound for a particular event for their app, say the email arriving again, just use the notification-email.flac file. + +The group should also be responsible for promoting the use of open codecs for the sounds files, ogg or flac for example. + +So why all the bother? Well because I feel it would make the life of people migrating to open source software like Linux that little bit easier. Having common consequences for actions can allow the user to bridge semantically similar actions, which may be syntactically different. + +Anyway, this is really just me putting this idea out there, maybe there's similar projects right now, i dunno, but i guess let the community decide if this is important enough to be considered. + + +# Naming Specification + +This is a first draft of the sound naming spec for bango. There are lots of similarites between tango, this is deliberate. + +Ok, so i have identified three broad categories i think the sounds should fall under: + + +## Alerts + +_This is to notify the user of an action or event which may have a major imact on the system or their current use case_ +[[!table header="no" class="mointable" data=""" + network-error | The sound used when an error occurs trying to intialize the network connection of the computing device. + dialog-error | The sound used when a dialog is opened to explain an error condition to the user. + battery-low | The sound used when the battery is below 20%. + software-update-urgent | The sound used when an urgent update is available through the system software update program. +"""]] + + +## Notifications + +_This is to alert the user that the system, or their current use case has changed state in some way - mew email arriving, new non-critical update to an application available_ +[[!table header="no" class="mointable" data=""" + search-results | The sound used when one or more search results are returned + search-results-empty | the sound used when no search results are returned + system-lock-screen | The sound used when the user locks their current session + system-log-out | The sound used when a user logs into the system or a service (i.e. desktop login) + system-log-in | The sound used when a user logs out of the system or a service (i.e. Gaim logout) + battery-caution | The sound used when the battery is below 40%. + dialog-information | The sound used when a dialog is opened to give information to the user that may be pertinent to the requested action. + software-update-available | The sound used when an update is available for software installed on the computing device, through the system software update program. +"""]] + + +## Support + +_This is to give the user feedback on their actions. These are not used to alter the use of errors, but rather reassure the user that their action was successful, sound on window opening / closing for example_ +[[!table header="no" class="mointable" data=""" + message-new | The sound used when a new IM or email is recieved + message-sent | The sound used when a new IM or email is sent + window-new | The sound used when a new window or dialog is opened + window-close | The sound used when an existing window is closed + dialog-ok | The sound used for the âOKâ button that might appear in dialog windows. + dialog-cancel | The sound used for the âCancelâ button that might appear in dialog windows. + drag-accept | The sound used when a file is accepted by a window, such as a folder or IM conversation + trash-empty | The sound used when the user emptys the trash + file-sendto-trash | The sound used when a file or folder is sent to the trash +"""]] + + +# Idea Pool + +By having the categories above, the user could now select whether they want all sounds, only alert sounds so they only get notified on critical events + +--- + + [[CategorySpec|CategorySpec]] diff --git a/CategoryCategory.mdwn b/CategoryCategory.mdwn new file mode 100644 index 00000000..6c9cd631 --- /dev/null +++ b/CategoryCategory.mdwn @@ -0,0 +1,10 @@ + +A category is a [[WikiName|WikiName]] that exploits [[!c2 WikiWiki desc="WikiWiki"]]'s reverse linking. If you click on the title of a category page, you'll get a list of pages belonging to that category. To get a list of all categories, click above on the Category****Category title. + +Here is a list of all categories known to this wiki: [[!map pages="^Category.*"]] + +Here is a list of all pages containing the CategoryCategory wiki tag: <span style="display:none">was , but that doesn't work</span> + +[[!inline pages="link(CategoryCategory)" quick feeds="no" archive="yes"]] + +To be consistent with the C2 category scheme, all categories start with the word "Category". For more information, see [[!c2 AboutCategoriesAndTopics desc="AboutCategoriesAndTopics"]]****. diff --git a/CategoryExtension.mdwn b/CategoryExtension.mdwn new file mode 100644 index 00000000..b27585c4 --- /dev/null +++ b/CategoryExtension.mdwn @@ -0,0 +1,12 @@ + +A category for X protocol extensions. + +To add a page to this category, add a link to this page on the last line of the page. You can add multiple categories to a page. + +**List of pages in this category:** + +[[!inline pages="link(CategoryExtension)" quick feeds="no" archive="yes"]] + +--- + + [[CategoryCategory|CategoryCategory]] diff --git a/CategoryHalReplacement.mdwn b/CategoryHalReplacement.mdwn new file mode 100644 index 00000000..4624cb27 --- /dev/null +++ b/CategoryHalReplacement.mdwn @@ -0,0 +1,12 @@ + +Pages related to the eventual replacement of the functionality of [[HAL|Software/hal]]: + +To add a page to this category, add a link to this page on the last line of the page. You can add multiple categories to a page. + +**List of pages in this category:** + +[[!inline pages="link(CategoryHalReplacement)" quick feeds="no" archive="yes"]] + +--- + + [[CategoryCategory|CategoryCategory]] diff --git a/CategoryHardware.mdwn b/CategoryHardware.mdwn new file mode 100644 index 00000000..96e3092c --- /dev/null +++ b/CategoryHardware.mdwn @@ -0,0 +1,10 @@ + +To add a page to this category, add a link to this page on the last line of the page. You can add multiple categories to a page. + +**List of pages in this category:** + +[[!inline pages="link(CategoryHardware)" quick feeds="no" archive="yes"]] + +--- + + [[CategoryCategory|CategoryCategory]] diff --git a/CategoryHomepage.mdwn b/CategoryHomepage.mdwn new file mode 100644 index 00000000..e141ee31 --- /dev/null +++ b/CategoryHomepage.mdwn @@ -0,0 +1,14 @@ + +A category for [[WikiHomePage]]****s. + +Note that such pages are "owned" by the respective person, and should not be edited by others, except to leave a message to that person. To do so, just append your message to the page, after four dashes like so: + +**List of pages in this category:** + +[[!inline pages="link(CategoryHomepage)" quick feeds="no" archive="yes"]] + + + +--- + + [[CategoryCategory]] diff --git a/ClipboardManager.mdwn b/ClipboardManager.mdwn new file mode 100644 index 00000000..602027fc --- /dev/null +++ b/ClipboardManager.mdwn @@ -0,0 +1,33 @@ + + +# Clipboard Manager Specification + + +## Responsibilities of clipboard managers + +Clipboard managers will acquire ownership of a selection named CLIPBOARD_MANAGER, as described in section 1.2.6 of the ICCCM. Clipboard managers should comply with the conventions for "Manager Selections" described in section 2.8 of the ICCCM. The intent is for clients to be able to request a variety of information or services by issuing conversion requests on this selection. + +Clipboard managers should support conversion of the SAVE_TARGETS target on their manager selection. This is a side-effect target, as described in ICCCM section 2.6.3. + +When a clipboard manager receives a request to convert the manager selection to the target SAVE_TARGETS, the named property specifies a list of targets to convert the CLIPBOARD selection to. If the named property exists, it must be of type ATOM and contain the list of targets. If the named property does not exist, the list of targets should be obtained by converting the CLIPBOARD to the TARGETS target, excluding side effect targets like DELETE, INSERT_PROPERTY and INSERT_SELECTION and possibly reducing the list of targets further. + +If the clipboard owner supports the TARGET_SIZES target, the clipboard manager may use that to determine how to handle the SAVE_TARGETS request, possibly refusing to save large amounts of data, or asking the user before doing so. + +When handling SAVE_TARGETS, the clipboard manager should convert the CLIPBOARD selection to the selected targets. Then it should take over ownership of the CLIPBOARD selection and offer the saved conversion results under the same targets they were requested with. Note: It is important to not send the [[SelectionNotify|SelectionNotify]] finishing the SAVE_TARGETS conversion until all target transfers are complete, since the clipboard owner will quit upon receiving the [[SelectionNotify|SelectionNotify]] and may not wait for the incremental transfers (using the INCR mechanism) to complete. + +Clipboard owners which support SAVE_TARGETS should include SAVE_TARGETS in their list of supported targets to indicate this. Clipboard managers are encouraged to use this information to support legacy clients. + + +## Responsibilities of clipboard owners + +If a client needs to exit while owning the CLIPBOARD selection, it should request the clipboard manager to take over the ownership of the clipboard, using the SAVE_TARGETS mechanism. If there is no clipboard manager, or if the SAVE_TARGETS conversion fails, the application should simply exit. + +Clients which support the SAVE_TARGETS mechanism should announce this by listing SAVE_TARGETS as a target for the CLIPBOARD. In this context, SAVE_TARGETS is used purely as a "marker target". If another client tries to convert the CLIPBOARD to SAVE_TARGETS, the clipboard owner should treat it like a side effect target without any actual side effect. + +In order to support peers who use the XFIXES extension to watch clipboard ownership changes, clipboard owners should reacquire the clipboard whenever the content or metadata (e.g the list of supported targets) changes. + +In order to support clipboard managers who want to avoid storing large amounts of data, clipboard owners should support a target named TARGET_SIZES. When asked to convert the clipboard to TARGET_SIZES, the clipboard owner must set the named property to format 32, type ATOM, and fill it with a list of pairs of target atoms and integers. There should be exactly one list entry for each supported target, and the integer should be + +* a. -1 for side effect targets, or +* b. an estimate of the size in bytes of the result of converting the current CLIPBOARD contents to the target, or +* c. 0 if it is too hard or impossible to determine the size, e.g. for MULTIPLE.
\ No newline at end of file diff --git a/CommonExtendedAttributes.mdwn b/CommonExtendedAttributes.mdwn new file mode 100644 index 00000000..62a43331 --- /dev/null +++ b/CommonExtendedAttributes.mdwn @@ -0,0 +1,78 @@ + + +# Guidelines for extended attributes + +Extended attributes (xattrs) can be set in different namespaces. Linux uses "security", "system", "trusted", and "user". This document only describes and proposes attributes in the "user" namespace. + +To avoid future conflicts between attributes, it is recommended that application-specific attributes are namespaced using reverse-DNS naming style. Standard DNS mapping places a subdomain (**WWW**) before a domain (**EXAMPLE**) before the top-level (**COM**), all separated by periods. In Common Extended Attributes, this is done backwards, in which the top level (**user**) appears first, followed (optionally) by one or more application-specific namespaces, followed by the attribute name, all separated by periods. + +For example, if you have written a book, your document might include information about it such as number of words, number of characters, number of chapters, and so on. These attributes might be added by your word processor or you might insert them manually using an attribute editor. Since they would change every time you edited the document, you wouldn't want to include them as a part of your document unless the information was specifically marked as being information about the document ("metadata") in which case either it's kept in the document as a special marked internal value (e.g. an attribute) or is stored outside the document as an attribute. The difference being, at least in theory, one could examine the attribute data about a file without changing the last access date/time of that file. Thus information not directly related to the file itself could be stored externally to the file, such as comments, lists of contributors, and so on. + +To prevent one program from misreading attributes written by another - and becoming confused or crashing if what it expects for an attribute is not the same as what was written by the other program - it is recommended that at least one application-specific namespace be used before the attribute, to avoid conflicting use of attributes, unless the attribute is such that it is unique to the file, is unambiguous, and would not be used for any other purpose, e.g. an attribute like "creation-date" or "last-modified-date" might be acceptable as an attribute without a name space, but an attribute such as "Status" might not be as what status represents is probably ambiguous. On the other hand, an attribute such as "document-status" or "document.status" would be a better choice (it would also allow other forms of a "status" value to be associated with the file.) + +Then there is the issue of the value for the attribute, if it is not in an application-specific namespace like _user.mywordprocessor.lasteditdate_ as opposed to _user.lasteditdate_, which value for "lasteditdate" is going to be used? There are probably a half-dozen ways to store dates on computers, many conflicting with each other. For example, is the date 04/05/06 the value April 4, 2006, May 4, 2006, or May 6, 2004? (All three of these interpretations have been validly used for ambiguous date values). And does the date include the time? And is it local time or UTC? + +Any attribute for a specific application using the file must be in an application-specific namespace in order to prevent conflicts such as the one given above. The application-specific namespace should probably either be the name of the company producing the application, a general identifier which indicates the application, or both. So, as in the example above, the company making the product "mywordprocessor" would put all of the extended attributes in the form user.mywordprocessor._attribute_ where "attribute" is whatever extended attribute used by that program. This would prevent some other program accidentally changing or contaminating an attribute it is using. + +This recommendation also applies on Mac OS X, where for example the resource fork is stored as an extended attribute with the key "com.apple.[[ResourceFork|ResourceFork]]". Attributes specified by freedesktop.org are prefixed with "xdg". + +Attribute strings should be in UTF-8 encoding. + + +## General attributes in current use + +* user.mime_type: Sets the MIME type of a file explicitly. This attribute is documented by the "Shared MIME-info Database Specification"([[http://standards.freedesktop.org/shared-mime-info-spec|http://standards.freedesktop.org/shared-mime-info-spec]]). It says: + * "An implementation MAY also get a file's MIME type from the user.mime_type extended attribute. The type given here should normally be used in preference to any guessed type, since the user is able to set it explicitly. Applications MAY choose to set the type when saving files. Since many applications and filesystems do not support extended attributes, implementations MUST NOT rely on this method being available." +* user.charset: The character encoding of a file. This attribute can be useful if the encoding is different than the platform default. It is used by the Apache httpd module mod_mime_xattr ([[http://0pointer.de/lennart/projects/mod_mime_xattr|http://0pointer.de/lennart/projects/mod_mime_xattr]]). +* user.creator: The name of the application that created the file. The ROX Contact Manager "Contact" sets this value to "Contact" ([[http://roxos.sunsite.dk/dev-contrib/guido/Contacts/|http://roxos.sunsite.dk/dev-contrib/guido/Contacts/]]). This meaning of the creator string is different from the meaning in Dublin core + +## Proposed metadata attributes + +Extended attributes are especially useful when they add information that is not present in the in the actual file. Depending on the file origin, an application can add metadata that is not present and/or can not be specified by the file or its format. For example file downloaded from a web server can be tagged with the url, which can be convenient if its source has to be determined in the future. Likewise, an email attachment can when saved be tagged with the message-id of the email. This will make it possible to trace the original message. + +These attributes are currently _proposed_ + +* user.xdg.comment: A comment specified by the _user_. This comment could be displayed by file managers +* user.xdg.origin.url: Set on a file downloaded from a url. Its value should equal the url it was downloaded from. +* user.xdg.origin.email.subject: Set on an email attachment when saved to disk. It should get its value from the originating message's "Subject" header +* user.xdg.origin.email.from: Set on an email attachment when saved to disk. It should get its value from the originating messsage's "From" header. For example '"John Doe" <[[jdoe@example.com|mailto:jdoe@example.com]]>', or '[[jdoe@example.com|mailto:jdoe@example.com]]' +* user.xdg.origin.email.message-id: Set on an email attachment when saved to disk. It should get its value from the originating message's "Message-Id" header. +* user.xdg.language: Language of the intellectual content of the resource. The value should follow the syntax described in RFC 3066 in conjunction with ISO 639 language codes. When a file is downloaded using HTTP, the value of the Content-Language HTTP header can if present be copied into this attribute. See also the Language element in Dublin core. +* user.xdg.creator: Reserved but not yet defined. The string "user" has a different meaning in ROX Contact Manager (creating application) compared with Dublin core (creating person/entity). +* user.xdg.publisher: Name of the creating application. See also the Publisher element in Dublin core. + +## Relation to Dublin Core + +Dublin Core is a standard for cross-domain information resource description. The Simple Dublin Core Metadata Element Set defines 15 elements. Applications that have knowledge of Dublin Core metadata may choose to set this metadata as extended attributes on a file when it saves it. Some of these elements have counterparts in the xdg name space, but then with more strict or detailed syntax or meaning. Attributes in the Dublin core namespace are currently not further specified. + +* user.dublincore.title +* user.dublincore.creator See also user.xdg.creator +* user.dublincore.subject +* user.dublincore.description +* user.dublincore.publisher +* user.dublincore.contributor +* user.dublincore.date +* user.dublincore.type +* user.dublincore.format +* user.dublincore.identifier +* user.dublincore.source +* user.dublincore.language See also user.xdg.language +* user.dublincore.relation +* user.dublincore.coverage +* user.dublincore.rights + +## Application-specific attributes in current use + +* user.mime_encoding: This attribute defines the MIME encoding to use when serving a file with Apache httpd. It is used by mod_mime_xattr. (Is this attribute useful in general?) +* user.apache_handler: This attribute is used by mod_mime_xattr to define the Apache handler for a file. +* user.Beagle.[[AttrTime|AttrTime]]: Used by Beagle +* user.Beagle.Fingerprint: Used by Beagle +* user.Beagle.MTime: Used by Beagle +* user.Beagle.Uid: Used by Beagle + +## Proposed control attributes + +Extended attributes could also act as flags for backup programs, indexing programs and similar, to control their behaviour. Below is an initial proposal for start of discussion, to alter the default behaviour. They are inspired by html attributes to control web crawling. + +* user.xdg.robots.index: On a file: "true" to index, "false" to not index. On a directory: "true" to traverse the into the directory for indexing, "false" for not traversing into it. +* user.xdg.robots.backup: On a file: "true" to index, "false" to not backup. On a directory: "true" to traverse the into the directory for backup, "false" for not traversing into it.
\ No newline at end of file diff --git a/DBusGLibRoadmap.mdwn b/DBusGLibRoadmap.mdwn new file mode 100644 index 00000000..2c5fc6fe --- /dev/null +++ b/DBusGLibRoadmap.mdwn @@ -0,0 +1,9 @@ + + +# dbus-glib Roadmap + +[[http://farm5.staticflickr.com/4133/5051068725_a204360b65.jpg|http://farm5.staticflickr.com/4133/5051068725_a204360b65.jpg]] + +There is no longer a road map for dbus-glib. Use GDBus. + +(Image CC-BY-2.0 <[[https://secure.flickr.com/photos/thelocalpeople/>|https://secure.flickr.com/photos/thelocalpeople/>]]) diff --git a/DavidReveman.mdwn b/DavidReveman.mdwn new file mode 100644 index 00000000..545db51f --- /dev/null +++ b/DavidReveman.mdwn @@ -0,0 +1,5 @@ + + +## David Reveman + +Email: davidr AT novell DOT com diff --git a/DejaVu.mdwn b/DejaVu.mdwn new file mode 100644 index 00000000..92310f80 --- /dev/null +++ b/DejaVu.mdwn @@ -0,0 +1,6 @@ + +The DejaVu font family is one of the key FLOSS font families for the free desktop. + +It is based on the Bitstream Vera Fonts release 1.10. + +The website of the project is [[http://dejavu.sourceforge.net|http://dejavu.sourceforge.net]] diff --git a/Desktops.mdwn b/Desktops.mdwn new file mode 100644 index 00000000..7d02c343 --- /dev/null +++ b/Desktops.mdwn @@ -0,0 +1,49 @@ + +In general there are two flavors of X desktop. The two most famous "heavyweight" desktop projects are GNOME and KDE; these include both a _desktop environment_ and an _application development framework_. A desktop environment includes a window manager, help browser, file manager, task bar, and so on. A development framework includes any number of libraries to ease application development, perhaps most importantly a GUI toolkit. GNOME and KDE are the desktops with the most support from Linux distribution vendors. + +The second flavor of X desktop includes a desktop environment only; no development framework is included. The line between this flavor of desktop and a plain old window manager is a bit blurry; many people would describe Xfce, [[WindowMaker|WindowMaker]], and Enlightenment as desktops in this category. + +Desktops can be mixed-and-matched; for example, you can run Enlightenment together with GNOME or KDE components; you can run applications developed with the GNOME or KDE development framework under any of the X desktops. One purpose of freedesktop.org is to ensure that this mixing-and-matching remains possible, and promote more of it. Read our [[Mission Statement|MissionStatement]] for details. The executive summary is that people or organizations developing applications do not need to worry about which desktop their users will select. _Applications_ which work with any desktop are easy to write. + +One way to think about the mission of freedesktop.org is this: to ensure that the different development frameworks aren't user-visible. + + +### X Desktops with a Development Framework + +* [[Backbone|http://www.nongnu.org/backbone/]]: A GNUstep-based desktop environment +* [[Étoilé|http://www.etoile-project.org/]]: another GNUstep-based Desktop Environment +* [[GNOME|http://www.gnome.org]] [[(developer site)|http://developer.gnome.org]]: The GNU Network Object Model Environment +* [[GNUstep|http://www.gnustep.org/]]: The GNU [[OpenStep|http://www.gnustep.org/resources/OpenStepSpec/OpenStepSpec.html]] Implementation +* [[KDE|http://www.kde.org]] [[(developer site)|http://techbase.kde.org]]: The K Desktop Environment +* [[Unity|http://unity.ubuntu.com/]]: A desktop environment built on GNOME + +### Plain Desktop Environments + +* [[AfterStep|http://www.afterstep.org/]]: Window manager that combines flexibility with elegant look +* [[AntiRight|http://www.nongnu.org/antiright]]: Lightweight scripted environment that uses the GTK+ toolkit +* [[awesome|http://awesome.naquadah.org]]: Highly configurable, next generation framework window manager +* [[EDE|http://equinox-project.org/]]: small desktop environment, built to be simple and fast +* [[Enlightenment|http://www.enlightenment.org/]]: The Enlightenment Window Manager +* [[fluxbox|http://fluxbox.org/]]: Lightweight WM with support for tabs +* [[FVWM|http://fvwm.org/]]: An extremely customizable window manager and some desktop applications +* [[GoFun|http://gofun.berlios.de/]]: Lightweight Desktop Entry Specification based desktop +* [[IceWM|http://icewm.org/]]: Window manager designed to be small, fast and lightweight +* [[LxDE|http://lxde.sourceforge.net]]: provide a new desktop environment which is lightweight and fast +* [[Matchbox|http://matchbox.handhelds.org/]]: Environment for non-desktop systems, such as handheld computers +* [[MATE|http://www.mate-desktop.org]]: MATE Desktop Environment is the fork of GNOME2 +* [[ROX|http://rox.sourceforge.net/]]: ROX is a free, GTK+-based, fully drag-and-drop desktop +* [[UDE|http://udeproject.sourceforge.net/]]: attempt to create new WM with original Look'n'Feel +* [[WindowMaker|http://www.windowmaker.org/]]: Window manager intended to work with GNUstep +* [[Xfce|http://www.xfce.org/]]: Lightweight GTK+-based environment +* [[XPde|http://www.xpde.com/]]: A Windows XP-like desktop environment designed for Windows users migrating to Linux + +### 3D Desktop Environments + +* [[Compiz|http://www.compiz.org/]]: OpenGL-based 3D window manager to extend existing desktop environments like Gnome and KDE +* [[Metisse|http://insitu.lri.fr/~chapuis/metisse/index.html]]: Metisse 3D Desktop project +* [[True3D*Shell|http://www.sixtyfourbit.org/3dshell.htm]]: open source 3D desktop environment + +### Classic Desktop Environments + +* [[CDE|http://www.opengroup.org/cde/]]: Common Desktop Environment, the traditional proprietary environment based on Motif +* [[TkDesk|http://tkdesk.sourceforge.net/]]: TkDesk predates most of the environments on this page
\ No newline at end of file diff --git a/DisplayLink.mdwn b/DisplayLink.mdwn new file mode 100644 index 00000000..e69de29b --- /dev/null +++ b/DisplayLink.mdwn diff --git a/Distributions.mdwn b/Distributions.mdwn new file mode 100644 index 00000000..b1ed3ae0 --- /dev/null +++ b/Distributions.mdwn @@ -0,0 +1,36 @@ + + +# Distributions Wiki + +This is a collaboration space for distributions to share ideas and discuss common issues. + + +## Communicating + +Email: [[Mailing List|http://lists.freedesktop.org/mailman/listinfo/distributions]] + +IRC: irc.freenode.net ##distros + + +## Contents + +Right now, there's only a little content in this wiki. So we can link it all to the front page. As we generate more content, we'll have to organize things better. + +* [[ConflictingFiles|Distributions/ConflictingFiles]] is a page to coordinate distribution renames of files upstream provides. These renames are caused because the file exists in more than one package at a time. Coordinating these renames reduces end-user confusion by making the renames the same across distributions where possible. +* [[ContactingPackagers|Distributions/ContactingPackagers]] documents ways to contact specific packagers in other distributions. +* [[WhyUpstream|Distributions/Packaging/WhyUpstream]] documents why we should encourage all our packagers to upstream their changes. +* [[DistributionLocations|Distributions/DistributionLocations]] where to find BTSs, VCSs, patches amongst other things. +* [[Meetings|Distributions/Meetings]] lists cross-distro meetings, and links to their conclusions. + +## Projects + +* [[AppStream|Distributions/AppStream]]: cross-distro umbrella project for a great user experience when finding and installing applications + +## Related external resources + +* [[Per-vendor information on how to locate patches|http://oss-security.openwall.org/wiki/distro-patches]] +* [[Per-vendor security contacts, advisories, bug trackers|http://oss-security.openwall.org/wiki/vendors]] +* [[Open Source Software Security (oss-security) Wiki|http://oss-security.openwall.org]] +* [[oss-security mailing list|http://oss-security.openwall.org/wiki/mailinglists/oss-security-charter]] +* [[oCERT (Open Source Computer Emergency Response Team)|http://ocert.org]] +* [[xvendor (cross-vendor) mailing list - currently on hold in favor of the Distributions list|http://www.openwall.com/community/xvendor]]
\ No newline at end of file diff --git a/Distributions/AppStream.mdwn b/Distributions/AppStream.mdwn new file mode 100644 index 00000000..024b53d6 --- /dev/null +++ b/Distributions/AppStream.mdwn @@ -0,0 +1,35 @@ + + +# Project AppStream + +The [[app installer meeting|Distributions/Meetings/AppInstaller2011]] produced some great results. + +[[[[!img appstream_meeting.jpg]|appstream_meeting.jpg]] + + +## Resources + +* [[How this stuff is going to work|Distributions/AppStream/Implementation]] +* General discussion is happening on the [[distribution mailing list|http://lists.freedesktop.org/mailman/listinfo/distributions]] at freedesktop +* General collaboration point for random stuff: [[http://gitorious.org/appstream/|http://gitorious.org/appstream/]] + +## Notes + +* [[Xapian Index Howto|Distributions/AppStream/XapianIndexHOWTO]] + +## AppStream-Core + +AppStream-Core provides basic tools to build an AppStream database. It also provides libappstream, a library which makes it easy to create Software-Center-like applications. See more on [[the project page|Distributions/AppStream/ASCore]]. + + +## Documents that were edited on pad + +Please note that most of those documents lack context for people who didn't attend the meeting. It's our intention to properly document the results, and the current notes are, at the moment, kept here mostly as reference for the meeting attendees. + +* [[Action Items|Distributions/AppStream/ActionItems]] +* [[Agenda|Distributions/AppStream/Agenda]] +* [[Notes on Architecture|Distributions/AppStream/ArchitectureNotes]] +* [[Notes on metadata|Distributions/AppStream/MetadataNotes]] +* [[General Notes|Distributions/AppStream/Notes]] +* [[Notes on OCS|Distributions/AppStream/OCSNotes]] +* [[Notes on UI|Distributions/AppStream/UINotes]]
\ No newline at end of file diff --git a/Distributions/AppStream/ASCore.mdwn b/Distributions/AppStream/ASCore.mdwn new file mode 100644 index 00000000..b5bd93dc --- /dev/null +++ b/Distributions/AppStream/ASCore.mdwn @@ -0,0 +1,17 @@ + + +# AppStream Core + +Utilities to generate, maintain and access the [[AppStream|Distributions/AppStream]] Xapian database. + + +## What is AppStream-Core? + +AppStream-Core makes it easy to access application information from the AppStream database over a nice GObject interface. It also contains a small DBus daemon to update the application cache automatically and can be used by a wide variety of programming languages (via GObject-Introspection). In combination with [[PackageKit|http://packagekit.org]] in can be used to build Software Centers. + +The AppStream Core utilities are **alpha software** at time, and the API might change a lot during the development process. Please keep that in mind when using it! + + +## Get it! + +You can download the latest release [[here|http://www.freedesktop.org/software/appstream/]] diff --git a/Distributions/AppStream/ActionItems.mdwn b/Distributions/AppStream/ActionItems.mdwn new file mode 100644 index 00000000..f3ceeed2 --- /dev/null +++ b/Distributions/AppStream/ActionItems.mdwn @@ -0,0 +1,159 @@ + + +# Action Items + + +## Next steps / Timeline + +* **[DONE]** (step -1 : save the piratepads somewhere :)) +* Step 0 (next week) + * Get infrastructure for development (wiki, mailing list, git) => fd.o + * subscribe to mailing list: [[http://lists.freedesktop.org/mailman/listinfo/distributions|http://lists.freedesktop.org/mailman/listinfo/distributions]] + * **[DONE]** wiki: [[http://distributions.freedesktop.org/|http://distributions.freedesktop.org/]] + * bugzilla: product on [[http://bugs.freedesktop.org|http://bugs.freedesktop.org]] [vuntz to create it if needed] + * **[DONE]** git repo: gitorious.org + * **[DONE]** Draw the big picture [hughsie] + * **[DONE]** xml schema for the metadata format (hughsie) +* First step: end-of-march + * Update desktop entry spec for new fields [vuntz] + * Push new fields in .desktop upstream [all] + * Getting the metadata published by distros [Debian: ?, Fedora: ?, Mageia: misc+samuel?, openSUSE: ?, Ubuntu: ? Can do it on [[http://distrib-coffee.ipsl.jussieu.fr/|http://distrib-coffee.ipsl.jussieu.fr/]] for testing (Nanar)] + * Create desktop-xml-to-xapian musher (mvo :-) + * Get up to date xapian in all distros + * Implement the OCS changes described below (Frank) + * Move USC to using PackageKit rather than leaking apt stuff (mvo,vuntz) + * CLA topic clarified + * How to validate: + * USC works on openSUSE + * USC works on Fedora (hughsie) + * 10% of desktop files have extra metadata + * distros are adding metadata back upstream (packagers) + * USC can display the metadata + * resolution on CLA (mvo) +* Second step: end-of-june + * Publish specification for the metadata format + * Setup distros OCS servers + * Use OCS in USC + * Put test data in OCS servers + * Getting screenshots.debian.net to have symlinks for appid + * How to validate: + * screenshots working on other distros in USC + * test data from OCS visible in USC +* End Goal: november + * Distros releasing at the end of 2011 have all that + * Hopefully with OCS data + * Hopefully with suggestions + +## Big untriaged list of action items + +This is a list of action items organized by topics. Most of them have been integrated in the timeline above. + +**List, for each metadata item** + +* is it available offline / online ? (essential vs nice to have) +* where it comes from (desktop file, user-provided...) +* if it's translated, and how +* if it's the same for all distributions or has to be tagged by origin +**Communication** + +* share meeting results + * FOSDEM talk (vuntz) + * wiki + * write a short "why this project is for your distribution" text ? +* "sell" the project to our distributions/managers (hughsie, vuntz) +* "sell" it to other distributions +* "sell" it upstream +**Desktop Files (vuntz,hughsie)** + +* Add extra items to .desktop item specification +* Add Homepage + * a package can contain more than one application, e.g. openoffice-writer and presenter +* Add Keywords + * So gimp.desktop can contain "photoshop" +* Add !OnlyShowIn/![[NotShowIn|NotShowIn]] item for !AppStore/![[SoftwareCenter|SoftwareCenter]] +* Enhances=firefox.desktop [comma seporated list] for firefox plugins (AddonTo, Extends,... pick one) +* Fix categories to be sane, so they could be used as tags too + * Add new categories + * Deprecate old useless ones + * Fix the issue with secondary categories requiring a main category, and you end up with two main categories because you're too explicit when listing secondary ones + * etc. + * We'll use Categories by default, and if an override is needed, use AppCategory? +**Software Center** + +* Write PackageKit backend [vuntz/mvo] +* improve distro abstractions (pkginfo provider instead of apt cache) including strings like *Ubuntu* Software Center [mvo] +* ask people to review ubuntu cla [mvo,vuntz] +* write OCS ratings/reviews backend +* add support for appdata.xml in update-softare-center.py [mvo] +**OCS** + +* {spam} for comments/inappropriate comments (Frank) +* Merge the new requirements into an OCS version 1.7 draft (Frank) +* Do a tagging module (Frank) +* Discuss and agree on OCS 1.7 on [[ocs@freedesktop.org|mailto:ocs@freedesktop.org]] (Frank) +* Provide a testing Server for development (Frank) +* Do an OCS 2.0 meeting (Frank) +**Screenshot** + +* screenshot.debian.net should use application id as a key, even if it's a symlink +**Translations** + +* Define translations workflow for applications descriptions +**Packaging (misc,Nanar)** + +* rpmlint/lintian: have some checks to make sure the .desktop metadata (Url, Enhances, etc.) is also in the package metadata +* automatically add a Provides for each .desktop file +**Metadata format** + +* Create a spec on xdg (can help: vuntz) +* Create a reference implementation + * create a fedora implementation in icky python (hughsie) +**Matching package data (enrico)** + +* source<->source (via upstream URLs -- or something else ;-)) +* binary<->binary (via .desktop files, regexps on package names) +* work at [[http://git.debian.org/?p=users/enrico/distromatch.git|http://git.debian.org/?p=users/enrico/distromatch.git]] +* datasets at [[http://people.debian.org/~enrico/dist-info.tar.gz|http://people.debian.org/~enrico/dist-info.tar.gz]] +* Other attempts: + * [[http://lists.freedesktop.org/mailman/listinfo/packagemap|http://lists.freedesktop.org/mailman/listinfo/packagemap]] + * [[http://blog.hartwork.org/?p=373|http://blog.hartwork.org/?p=373]] + * [[https://github.com/silviocesare/Equivalent-Packages/blob/master/NearestNeighbour/Debian5_Fedora13_Matches|https://github.com/silviocesare/Equivalent-Packages/blob/master/NearestNeighbour/Debian5_Fedora13_Matches]] + * [[http://packages.debian.org/sid/whohas|http://packages.debian.org/sid/whohas]] +* Use cases + * falling back to other distros for missing data like categories and screenshots + * accessing ratings and comments + * finding patches from other distros + * linking BTSes + * cross-distro, googlable application index +**Building a Xapian index for non-debian distros (enrico)** + +* bringing debtags across after a rough binary package matching [prototype done: [[http://www.enricozini.org/2011/debian/distromatch/|http://www.enricozini.org/2011/debian/distromatch/]] now it needs to be deployed with regular updates] +* [[Build a Xapian index on your distro|Distributions/AppStream/XapianIndexHOWTO]] +* run Enrico's faceted prototype ([[http://www.enricozini.org/2011/debian/pkgshelf/|http://www.enricozini.org/2011/debian/pkgshelf/]]) on other distro data +**Klik (vuntz)** + +* talk to alexl about klik + * see [[http://blogs.gnome.org/alexl/2007/08/07/experiments-with-runtime-less-app-bundles/|http://blogs.gnome.org/alexl/2007/08/07/experiments-with-runtime-less-app-bundles/]] +**(side things) (enrico)** + +* Deploying apt-file fast server-side index for other distros [[http://dde.debian.net/dde/q/aptfile/all/bin/mc|http://dde.debian.net/dde/q/aptfile/all/bin/mc]] +* web-based application browsing (mageia-app-db project) (Samuel) + * [[http://mageia-app-db.tuxette.fr/projects/mageia-app-db/wiki|http://mageia-app-db.tuxette.fr/projects/mageia-app-db/wiki]] + * are there other distributions than Mageia and Mandriva interested in this app ? + * deploy one test instance per RPM distribution + * fedora + * opensuse + * make it usable with DEB repos too (currently only RPM) : depending on debian/ubuntu interest in it. + * use xapian index to speed things up + * flag packages as applications based on .desktop files and provide "application-only" views + * use "strong" and "weak" suggests dependencies to group applications and add-ons together + * map from distributions package names to names in screenshots.debian.net, until we have the screenshots provided by OCS servers + * one click install + * tags support (read-only to begin with) + * use OCS servers as soon as they are available (read-only to begin with) +**Debtags links** + +* Pointers to the data: [[http://debtags.alioth.debian.org/tags/|http://debtags.alioth.debian.org/tags/]] +**Misc** + +* [[http://git.debian.org/?p=users/enrico/pkgshelf.git|http://git.debian.org/?p=users/enrico/pkgshelf.git]] (the prototype xapian based appstoreything put together in 2 hours that I demoed the first day [enrico])
\ No newline at end of file diff --git a/Distributions/AppStream/Agenda.mdwn b/Distributions/AppStream/Agenda.mdwn new file mode 100644 index 00000000..735e72db --- /dev/null +++ b/Distributions/AppStream/Agenda.mdwn @@ -0,0 +1,48 @@ + + +# Agenda + +**Definitions:** target user, what's an application, etc. [vuntz,hughsie,prusnak,mls,Samuel] + +* Bash? Firefox? Apache? MySQL? +* Use .desktop file as app id? +**Quick showcase** [enrico, vuntz,frank,hughsie,ffesti,Samuel?,Nanar,mvo] + +**Metadata** + +* What metadata [frank, Samuel,hughsie, mvo] + * Grouping apps (Games, Action Games, etc.) [enrico,hughsie,mvo, prusnak, Samuel,david,ffesti] + * Delta metadata? +* How to access (API/format) [enrico,frank,hughsie,mvo,misc,mls,Samuel,prusnak,david,Nanar,ffesti] +* Where (server? local?) [enrico,frank,hughsie,mvo,misc,mls,Samuel,prusnak,david,ffesti] +* Relating apps and their add-ons (Recommends/Suggests/addons) [wstephenson,hughsie] +* How do we identify uniquely an application. From what information ? Do we need to define a unique identifier ? Where, who ? +* Moderation [hughsie,mvo,wstephenson] +**Localization** [vuntz,mvo(?),misc,Samuel,david,hughsie] + +* of metadata +** Find & install apps** [vuntz,hughsie,mvo,prusnak,mls,david,ffesti,Samuel?] + +* UI [enrico,hughsie,mvo,prusnak,ffesti] +* Suggests [enrico,frank,hughsie,mvo,prusnak,david,ffesti] +* Addons (think browser or app plugins) [mvo,prusnak,Samuel] +* Grouping of packages as one application [Samuel,prusnak,Nanar,ffesti] => based on dependancies (strong or weak dependencies), with a special treatment for localization packages. +**UI to display installed apps** [enrico,hughsie,mvo(?),ffestiy] + +**UI for updates** [vuntz,hughsie,mvo,mls,wstephenson] + +**Use cases? Target users? Anti-users?** + +**Restrictions** [enrico,misc,Nanar] + +* legal issues/restrictions depending on your location? +* children vs adult content [Samuel] + * [[http://www.miriamruiz.es/weblog/?p=69|http://www.miriamruiz.es/weblog/?p=69]] + * [[http://www.miriamruiz.es/weblog/?p=155|http://www.miriamruiz.es/weblog/?p=155]] + * [[http://wiki.debian.org/OpenRating/Categories|http://wiki.debian.org/OpenRating/Categories]] +* should we care/can we do something? Maybe just use distro blends/flavors +**What to tell upstream?** [vuntz,hughsie,misc,prusnak,wstephenson] + +* require .desktop files to appear in app store? [hughsie] +* push package description in .desktop files upstream? [hughsie,Samuel] +**official repos vs "third-party-provided" ones** [misc,Nanar,Samuel?,hughsie] diff --git a/Distributions/AppStream/ArchitectureNotes.mdwn b/Distributions/AppStream/ArchitectureNotes.mdwn new file mode 100644 index 00000000..b9bbe60b --- /dev/null +++ b/Distributions/AppStream/ArchitectureNotes.mdwn @@ -0,0 +1,33 @@ + +[[!img Architecture plan] + +using OCS -> rest, easy to replicate + +different clients connect to different servers + +server under the control of distribution + +how to share ? + +if we use a central server, who will maintain ? + +Garett : applications distributers should not have their own server -> a way to have 3rd party to plug in the system + +content identifier on the server + +* desktopfilename +* version of soft +* repository ( distro, repo for each distribution ) -> url to metadata +* distro/version +no need to filter on server, as the client only show applications that exist + +how to play well with 3rd party ? ( OBS, livna ) -> just add another server + +need to solve these 2 problem : + +* discover applications +* discover repositories +Frank proposal ( for solving discover repositories ) : + +* add a shared linux ecosystem repositories +* several client connecting to their server, and also to the shared one
\ No newline at end of file diff --git a/Distributions/AppStream/Implementation.mdwn b/Distributions/AppStream/Implementation.mdwn new file mode 100644 index 00000000..41e109df --- /dev/null +++ b/Distributions/AppStream/Implementation.mdwn @@ -0,0 +1,67 @@ + + +# AppStream Architecture + +[[!img Architecture plan] + +Appstream is split into four logical blocks, on three principal levels. + +[[!toc 2]] + + +## Client + + +### Software Center + +* The existing Ubuntu Application Center fits the perceived need and is an established and stable project + * Has CLA we might need to work around / fork. + * Have to convert away from using custom social server to OCS, non-issue + * Have to port to [[PackageKit|PackageKit]] 100%, non-issue +* Talks to zeitgeist for usage stats +* Has recommendations and featured applications +* Need the ability to tag applications and moderate comments + +### PackageKit + +* [[http://www.packagekit.org|http://www.packagekit.org]] +* Use the assumption that packages are an uninteresting implementation detail. +* Need to be able to search whilst we are installing, perhaps limited to existing xapian results. + +### xapian + +* [[http://xapian.org/|http://xapian.org/]] +* Established project used for many years to enable free text search using important things like priority and stemming that can return results in 10's of milliseconds. +* We discussed a relational database, but not suitable for our needs +* Need to rebuild every time we add/enable or disabled. + +### OCS + +* [[http://www.freedesktop.org/wiki/Specifications/open-collaboration-services|http://www.freedesktop.org/wiki/Specifications/open-collaboration-services]] +* Provides a shared API we can add social media to an application installer +* Growing userbase and stable and approachable upstream +* Can have single server for all or private instance on own infrastructure with possible federation between distros + +## Mirror + + +### Metadata + +* Just another file on the mirror server: app-data.xml +* Contains data derived from the upstream desktop files and extracted at repo-compose time. +* Means we have different metadata for each repo +* Just another blob of data that can be downloaded by apt-get, yum, etc + * See [[http://gitorious.org/appstream/resources/blobs/master/appdata.xml|http://gitorious.org/appstream/resources/blobs/master/appdata.xml]] for an example, or schema here [[http://gitorious.org/appstream/resources/blobs/raw/master/appdata.xsd|http://gitorious.org/appstream/resources/blobs/raw/master/appdata.xsd]] + +### Icons + +* super-critical in search results +* app-data-32x32.tar.gz +* icons/32x32/foo.png +* Can encode location and type of icons in the appdata.xml + +## Compose server + +* We explode the package files which contain a desktop file and extract the data from the desktop files +* All gets added to the app-data.xml and icons get (resized/converted?) and copied +* Probably a per-distro tool outputting shared format XML
\ No newline at end of file diff --git a/Distributions/AppStream/MetadataNotes.mdwn b/Distributions/AppStream/MetadataNotes.mdwn new file mode 100644 index 00000000..ade09ba9 --- /dev/null +++ b/Distributions/AppStream/MetadataNotes.mdwn @@ -0,0 +1,122 @@ + + +# App-installer Metadata Meeting Notes + +**what we want/need** + + * desktop file with annotations like pkgname, repository, component + * description + * icon(s) + * categories (.desktop) (for relating to menus) + * categories (distribution) (with distro QA process, used to implement specific use cases) + * categories (user folksonomy) (community tags) + * upstream URL - TODO put it into the .desktop file + * keywords - TODO put it into the .desktop file (or just use tags?) + * screenshots - screenshots.debian.net with locales + * videos (?) + * long description including markup (markdown?) + * (didn't we mention that upstream URLs can do as well, at least as a tradeoff? I think we said we need a "medium size" description, + upstream URL for more information (moving to chat in bottom right)) + * suggestions (based on zeitgeist usage, based on what other people use, static list, app of the day) + * addons + * repository information + * upstream activity ([[http://www.ohloh.net/|http://www.ohloh.net/]]) + * latest upstream version(?) : stable version, dev version (if such a distinction exists) + * latest upstream release date(?) + * pluggable extra tagsets + * child ratings + * [[http://www.miriamruiz.es/weblog/?p=69|http://www.miriamruiz.es/weblog/?p=69]] [[http://www.miriamruiz.es/weblog/?p=155|http://www.miriamruiz.es/weblog/?p=155]] [[http://wiki.debian.org/OpenRating/Categories|http://wiki.debian.org/OpenRating/Categories]] + * QA tags + * ?more urls to more things (debian-administration articles, ask.debian.net questions, howtos) (possibly built as backlink searches, microformats style?) + * mime types + * comments, ratings, moderation (including version, origin) +**where to store it** + +* an rfc822/xml (or other lighter format) file containing mapping between packages and applications (build by scanning the packages for desktop files), on mirrors + * this can include all the useful data from desktop files (categories, long description, short description, translations ? (would make it way bigger)) + * (yet to define) server(s) for other metadata (screenshots, ratings, comments, ...) + * one master server and slave servers for each distribution (so that they can "control" it ?) + * screenshots should have a additional api that includes origin +**How to access (API/format)** + +**Moderation** + +**Localization** + +**How do we identify uniquely an application.** From what information ? Do we need to define a unique identifier ? Where, who ? + +**appdata.xml (one file per repository)** + +_What we need :_ + +* application_id (paths ?) +* package name (distribution-dependant) +* app-name (+ translations) +* app-summary (+ translations) +* keywords[] (+ translations) +* icon (stock:games) relative to mirror URL / absolute URL (?) +* [[AppCategories|AppCategories]][] +* [[MimeTypes|MimeTypes]] [] +* Enhances[] +* URL[] +_Issues :_ application id : + +* /usr/share/applications/foo.desktop ? +* /usr/share/kde4/foo.desktop ? +* just foo.desktop ? +* kde4/foo.desktop ? +_Example file :_ +[[!format txt """ +<applications version="0.1"> + <application> + <id type="desktop">firefox.desktop</id> + <pkgname>firefox-bin</pkgname> + <name>Firefox upstream</name> + <name lang="en_GB">Firefox</name> + ... + <summary>...</summary> + <summary lang="en_GB">...</summary> + ... + <keywords> + <keyword lang="en_GB">colour</keyword> + <keyword>color</keyword> + <keyword>agent</keyword> + ... + </keywords> + <icon type="stock">application-games</icon> + <appcategories> + <appcategory></appcategory> + <appcategory></appcategory> + ... + </appcategories> + <mimetypes> + <mimetype>...</mimetype> + <mimetype>...</mimetype> + ... + </mimetypes> + <url type="homepage">http://example.com</url> + </application> + <application> + ... + </application> + ... +</applications> +"""]] +_Layout :_ + +* /appdata.xml +* /icons/64x64 +**Notes:** + + * Leave the compression to the distro + * when appdata.xml changes in any repo (including adding and removing ppas/repos) we need to rebuild xapian index + * xdg application id for /usr/share/applications/kde4/kwrite.desktop is "kde4/kwrite.desktop" so we can open the actual desktop file once installed just from using the application_id. + * Perhaps not include applications if they don't have [[AppCategories|AppCategories]] (maybe a useful feature for plugins that you don't want to show in the "by groups" or "by tags" views, but still have available for searching and in also in relation to the application(s) they enhance. +**Action Items:** + +* Add extra items to .desktop item specification +* use '/' as separator for GIO application id, not '-' +* Need to do reference implementation to extract .rpm/.deb to xml file + * ./append-metadata --output output.xml --input ./packages/dave.rpm --package-name=dave-bin +* Need to merge the metadata into a shared xapian instance +* Talk about compressed mmappable file for icons. Lots of small files doesn't sit well with the mirrors, and means we have to download the icons through the package manager one at a time, rather than being able to load these in one lump. + * Use appdata-icons-32x32.tar.gz if we don't want to ship thousands of icons on the mirrors -- allows the package manager to download this in one go, explode to the filesystem and then use the <icon type="local">/usr/cache/icons/foo.png</icons>
\ No newline at end of file diff --git a/Distributions/AppStream/Notes.mdwn b/Distributions/AppStream/Notes.mdwn new file mode 100644 index 00000000..dc0db88f --- /dev/null +++ b/Distributions/AppStream/Notes.mdwn @@ -0,0 +1,37 @@ + + +# List topics for Agenda + +Quote of the conference: Garrett: "Nobody in this room is normal." (not even Garrett) + +**Showcase** + +* software center (mvo) +* debtags (enrico) +* packagekit (hughsie) +* ocs (frank) +* sophie (olivier) +**Define application** + +30 minutes. We shouldn't have any "?" left at the end :-) + +* "an application is a .desktop file" ? +* Applications have to appear in the application menu? +* Add extra fields to the upstream desktop files? UseInAppStore=true AppStoreGroups=Games,System,etc AppId=1123457 <- or is the desktop filename the appid? sometimes it is not (MozillaFirefox.desktop vs firefox.desktop) A unique ID (or name, easier to remember) included in the .desktop file is more sure. +* Can ship .desktop files for stuff that isn't really a GUI program for something to be included in the appstore -- e.g. emacs, mutt, lynx..., but of course, not show it in the application menu (eg. OnlyShowIn=AppStore) +* Still, it would be interesting to have the same metadata for eg apache, mysql, postgresql... than for other "applications" (comments, ratings, translations...). Does it mean they need .desktop files ? +* we strongly agreed on the fact that size of the dependencies should be counted to the size of the application (even when the deps are shared among more applications) +* We agreed that when the original application is removed, the deps installed with the application should be removed if no other application requires it +* if there is a dekstop file that shouldn't be displayed we add SoftwareFooIgnore=True (NotShowIn=AppStore) +* if there is a desktop file that should be there but is missing, we need to add it +* plugins installation/deinstallation should be accessed relative to the software they are related to Agreed, but don't they sometime enhance several applications ? (maybe not a problem) -- desktop file extension AppStoreRelatesTo=firefox +**Bretzn presentation (Frank)** + +* Looks promising, but QA process - updates-testing first, then updates? +**Installing multiple versions of same app** + +* using Klik? +* enable fast & easy testing of new version of an app (or something that had no QA) +* web developers can have firefox 2/3/4 +* the install is local to the user, so doesn't affect the system. Trivial to "revert". +* But the new version could alter your configuration or data, there's no coming back then
\ No newline at end of file diff --git a/Distributions/AppStream/OCSNotes.mdwn b/Distributions/AppStream/OCSNotes.mdwn new file mode 100644 index 00000000..a5159977 --- /dev/null +++ b/Distributions/AppStream/OCSNotes.mdwn @@ -0,0 +1,39 @@ + +Agenda: + +* Introduction +* [[http://www.freedesktop.org/wiki/Specifications/idixdeoxopen-collaboration-services|http://www.freedesktop.org/wiki/Specifications/idixdeoxopen-collaboration-services]] +Notes: + +* Can write a server with only support for applications, comments but not for friends +* Provider files [server side] to control sources of data (freedesktop?, internal for RHEL) +* application can currently only belong to one category (artificial server limitation) +* Can only query server without auth certain number of times without being locked out. +* Still need to call download even if we don't need the package name for package popularity and suggestions +* Need to vote up and down, (0--100, although can map to 1-5 stars) +* Map applications to content items, if they are installable in parallel. Else the same. +Content item: + +* desktopFilename +* VersionApp? +* repo? +* distro-version? +Questions: + +* server control +* How save data persistently? What if I restart the service? (in a mysql database) +Action items: + +* mvo to send the OCS team an idea of what extra stuff needs to be in 1.7 +* need to chase the OSC guys on tagging +* {spam} for comments/inappropriate comments +* screenshot.debian.net should use application id as a key, even if it's a symlink +Missing: + +* authentication with oauth +* language for comments, description and knowledgebase articles +* COMMENTS for applications need to carry version info for a package +* moderation request API call for a comment +* search for repository in CONTENT list +* a comment can be in the state NEEDS-MODERATION +* moderation API? or moderation Webui?
\ No newline at end of file diff --git a/Distributions/AppStream/UINotes.mdwn b/Distributions/AppStream/UINotes.mdwn new file mode 100644 index 00000000..b4c1f511 --- /dev/null +++ b/Distributions/AppStream/UINotes.mdwn @@ -0,0 +1,65 @@ + +Issue: How do you find the application you're looking for? + +What do we need: title, icon, screenshot, comments, ratings, description. + +Access rights (privileges needed for the app to run)? There's no technical solution for now anyway, so ignore it. + +Categories for apps: + +* use the ones from .desktop files? +* should we have same categorization in app menu and app store? => probably different +* tree structure doesn't scale +* [[http://www.appbrain.com/|http://www.appbrain.com/]] +* [[http://instantwatcher.com|http://instantwatcher.com]] +* amazon + * good thing here is the tags that are proposed after a search: they're used to split results in equal groups (and not all tags are proposed) + * no huge list of results, but pages of results +* tags: a defined set of common tags. No free-form. +find apps per mime-types + +One-level of navigation. We don't want to have deep navigation. => toplevel categories. And then, inside of this, you can filter it down: keywords. There's no real way to display all tags in a reasonable to the user anyway. + +default order of apps should make sense: top 5 apps should be the 5 apps people want. + +Native app vs website? + +* website enables easy sharing with other people +Use software center as a basis + +* finding an app is not good at the moment +* once you're on the page of one app, it's quite okay (not perfect) +How to find apps: + +* front-page: + * first level of categories (5-10) + * featured apps +* second level: + * something at the top (featured/recommend apps) + * then, below, list of results + * display a small set of tags (most-used in the list of results) to help user filter? +* search interface should not really be different from browse interface +* the way people find apps has to be "web-like" +we need a web version of the app to have it indexed by google (people look on google) is there a good reason we need a native version of the app? + +Conclusion: + +* no tree view +* get results immediately +* 1 or 2 steps only +* keywords +* filtering on the result page +* indexed by google, a link to share the app +* web page and native client need to work together/interop +* we can use debian tags +* packages enhancing package X should be displayed on the page of package X (like Software Center does). Useful for plugins, addons. +* top results are important. We want recommendations there (popular apps, related to what user has already installed, etc.) +* add "Launch" button to app pages +* maybe just get rid of "install button", and merge with "Launch" (ie, automatically install if needed) +web site: should be shared between distros? Or per distro? + +Main question: use Ubuntu Software Center + build a web site OR just build web site + +share code between web interface & native interface to avoid too much duplication of efforts + +keep in mind tablets. Also possibly make use of multitouch where it makes sense. diff --git a/Distributions/AppStream/XapianIndexHOWTO.mdwn b/Distributions/AppStream/XapianIndexHOWTO.mdwn new file mode 100644 index 00000000..86873cf6 --- /dev/null +++ b/Distributions/AppStream/XapianIndexHOWTO.mdwn @@ -0,0 +1,71 @@ + + +# Build yourself a Xapian index of package info + + +## Run the Debian indexer on your distro + +The Debian Xapian indexer is called update-apt-xapian-index and normally it reads data from the Apt database. Luckily it also has an option (--pkgfile=_file_) for reading data from a plain file, which is used to build server-side indices and to build a test environment for its test suite. If you can generate a suitable input file, update-apt-xapian-index will build an index for you. + +The input file has the same format as the Debian Packages file, which is similar to email or HTTP headers: +[[!format txt """ +Package: 2vcard +Priority: optional +Section: utils +Installed-Size: 108 +Maintainer: Martin Albisetti <argentina@gmail.com> +Architecture: all +Version: 0.5-3 +Filename: pool/main/2/2vcard/2vcard_0.5-3_all.deb +Size: 14300 +MD5sum: d831fd82a8605e9258b2314a7d703abe +SHA1: e903a05f168a825ff84c87326898a182635f8175 +SHA256: 2be9a86f0ec99b1299880c6bf0f4da8257c74a61341c14c103b70c9ec04b10ec +Description: perl script to convert an addressbook to VCARD file format + 2vcard is a little perl script that you can use to convert the + popular vcard file format. Currently 2vcard can only convert addressbooks + and alias files from the following formats: abook,eudora,juno,ldif,mutt, + mh and pine. + . + The VCARD format is used by gnomecard, for example, which is used by the + balsa email client. +Tag: implemented-in::perl, role::program, use::converting + +Package: 3dchess +[...] +"""]] +Records are separated with an empty line, and long fields like 'Description' use continuation lines that start with spaces. The first line of the description is the short description, the rest is the long description; an empty line in the Description is represented with a dot. + +For update-apt-xapian-index you only need the fields **Package**, **Version**, **Description**, **Tag**, Section, Installed-Size and Size. Tag, Section, Installed-Size and Size are all optional, although you probably want Tag for Debtags categories. + +If you want to start playing with the indexer without building your own input file, you can run `apt-cache dumpavail` on any Debian or Ubuntu system to extract the whole system dataset. Alternatively, you can use any [[Packages|http://ftp.debian.org/debian/dists/sid/main/binary-amd64/Packages.gz]] file from a Debian mirror. + +**Dependencies**: + +* python-xapian (Python bindings for Xapian) +* [[python-debian|http://packages.debian.org/sid/python-debian]] (used to read some Debian-style files, source is straightforward to build) +* python-chardet, dependency of python-debian, available in Fedora, Mandriva/Mageia and Suse with the same name +**Building the index**: +[[!format txt """ +git clone git://git.debian.org/git/collab-maint/apt-xapian-index.git +cd apt-xapian-index + +# Testrun is just a simple wrapper that exports the variables needed +# to run the indexer in the current directory +./testrun --pkgfile=inputfile --force --verbose # Creates an index in testdb/ + +# Try querying it with Xapian's low-level "delve" tool, to see if it worked: +delve -1 -d -t edit testdb/index +"""]] +The Xapian index itself is in testdb/index; testdb/ will contain other information about the index, including an autogenerated README file documenting its contents, especially the [[term prefixes|http://xapian.org/docs/omega/termprefixes.html]] used by the index. + +Congratulations: you can now try querying the index. The Xapian website has documentation and examples for [[C++|http://xapian.org/docs/quickstart.html]] and [[Python, Perl, PHP, Ruby, C#, Java and more bindings|http://xapian.org/docs/bindings/]]. + +Patches welcome for alternative input file formats and extra plugins to index extra info you may need. Please update this page with your experience if you try it. + +**Possible things to try**: + +* Change DEBTAGSDB in plugins/debtags.py to make it read Debtags information from one of the [[distromatch exports|http://www.enricozini.org/2011/debian/distromatch/]] so you don't need to add them as Tag: fields +* Get [[pkgshelf|http://www.enricozini.org/2011/debian/pkgshelf/]] to work (it should only need `export AXI_DB_PATH=testdb` and editing `pkgshelf/__init__.py` to change `/var/lib/debtags/package-tags` with the location of your distromatch Debtags export. +* If you need to index some extra information, take a look at plugins/template.py for a plugin template: you only need to redefine the method indexDeb822. +* Build an indexer that reads the native package database for your own distribution, then get in touch with Enrico to see if it can all fit in the same codebase.
\ No newline at end of file diff --git a/Distributions/AppStream/appstream_meeting.jpg b/Distributions/AppStream/appstream_meeting.jpg Binary files differnew file mode 100644 index 00000000..1e1f16fc --- /dev/null +++ b/Distributions/AppStream/appstream_meeting.jpg diff --git a/Distributions/ConflictingFiles.mdwn b/Distributions/ConflictingFiles.mdwn new file mode 100644 index 00000000..319c855a --- /dev/null +++ b/Distributions/ConflictingFiles.mdwn @@ -0,0 +1,36 @@ + + +# Conflicting Files + +Sometimes two upstream packages will have files that are named the same. When this happens, the two packages can't be installed without conflicts. The way to resolve this is to rename the files from one or both packages. Whenever possible these changes should occur upstream so everyone benefits from it. Sometimes, however, upstream is not responsive to requests to rename. When this happens distributions have to rename the files at their level. + +Renaming at the distribution level is less than ideal as end-users using multiple distributions may be confused when they have to use different names to invoke a program or compile against a library. This page exists to help distributions coordinate these renames to minimize this end user confusion. + + +## Policies + +Different distributions have slightly different policies about renaming conflicting files. Here are links to relevant policies in various distros. + +* Fedora: [[http://fedoraproject.org/wiki/Packaging/Conflicts#Conflicting_Files|http://fedoraproject.org/wiki/Packaging/Conflicts#Conflicting_Files]] +* Gentoo: [[http://lists.freedesktop.org/archives/distributions/2008-August/000205.html|http://lists.freedesktop.org/archives/distributions/2008-August/000205.html]] +* Debian: [[http://lists.freedesktop.org/archives/distributions/2008-August/000206.html|http://lists.freedesktop.org/archives/distributions/2008-August/000206.html]] + +## Renamed Files + +This table of renames is manually created by packagers in the various distributions therefore it is not complete. +[[!table header="no" class="mointable" data=""" +Upstream Package | Upstream File | Renamed To | Distributions Renamed In +[[sqlalchemy-migrate|http://code.google.com/p/sqlalchemy-migrate/]] | /usr/bin/migrate | /usr/bin/sqlalchemy-migrate | Fedora +[[Terminal|http://www.os-cillation.com/index.php?id=42&L=5]] | /usr/bin/Terminal | /usr/bin/xfce4-terminal | Debian +"""]] + + +### docbook2x + +* Homepage: [[http://docbook2x.sourceforge.net/|http://docbook2x.sourceforge.net/]] +* AltLinux: --program-transform-name='s/docbook2/db2x_docbook2/' +* Redhat EL, Fedore: --program-transform-name='s/docbook2/db2x_docbook2/' +* Debian: --program-transform-name="s/^docbook2/docbook2x-/" +* openSUSE: just moves files to docbook-to-man and docbook-to-texi +* Mandriva: does nothing +* Gentoo: --program-transform-name='s,\(docbook2.*\),\1.pl,'
\ No newline at end of file diff --git a/Distributions/ContactingPackagers.mdwn b/Distributions/ContactingPackagers.mdwn new file mode 100644 index 00000000..af2ffe7d --- /dev/null +++ b/Distributions/ContactingPackagers.mdwn @@ -0,0 +1,68 @@ + + +# Contacting Packagers in Other Distributions + +Sometimes you can work on a package and need to talk to a packager in other distributions. This might be because the package is non-trivial to package. It might be because you discover a security hole and want to make sure others are not affected. It might be because you want to share a beer at LinuxTAG with other packagers of the same software. In any case, this page exists to help you get in touch with your colleagues in other distributions. + +There are some caveats. Notably, you have to know what the package name is in all distributions. (Debian has `python-turbogears` and Fedora has `TurboGears` packages, for instance.) However, the information here is a good start. + + +## Debian + +Debian's main developer list is [[debian-devel@lists.debian.org|mailto:debian-devel@lists.debian.org]]. + +To reach individual developers responsible for a package use <package>@packages.debian.org, package names can be looked up at [[http://packages.debian.org|http://packages.debian.org]] or through the Packages.gz files on every Debian mirror. A list of people is available at [[http://www.debian.org/devel/people|http://www.debian.org/devel/people]] + + +## Exherbo + +Exherbos's main mailing list for development is [[exherbo-dev@lists.exherbo.org|mailto:exherbo-dev@lists.exherbo.org]]. + +The maintainer responsible for a particular package can be acquired by several means: + +* In the respective exheres, look for the BUGS_TO keyword, e. g. BUGS_TO="[[philantrop@exherbo.org|mailto:philantrop@exherbo.org]]". +* At [[http://git.exherbo.org/summer/|http://git.exherbo.org/summer/]] you can either look the package up by its repository or its category. On the package level, you'll find "Bugs to" again. +In both cases, the email address in BUGS_TO is the person or group you'll want to talk to. + +The `#exherbo` channel on the FreeNode IRC network is home to almost all Exherbo developers and contributors. + +A list of Exherbo's core developers is available at [[http://www.exherbo.org/developers.html|http://www.exherbo.org/developers.html]]. A complete list can be found at [[http://www.mailstation.de/egitstats/authors.html|http://www.mailstation.de/egitstats/authors.html]]. + + +## Fedora + +To contact all of the packagers in Fedora for discussion you can use the mailing list [[MailTo(fedora-devel-list AT redhat DOT com)|MailTo(fedora-devel-list AT redhat DOT com)]]. You need to be [[subscribed|https://www.redhat.com/mailman/listinfo/fedora-devel-list]] to post. + +Fedora has recently started providing email aliases that go to the owners of packages. At the current time, those aliases are [[MailTo(PACKAGENAME-owner AT fedoraproject DOT org)|MailTo(PACKAGENAME-owner AT fedoraproject DOT org)]]. It directs to the package owner and everyone who is watching the packages. More fine-grained aliases have been requested for the future. + +If you need to find just the owners or need to find out the name of a package in Fedora, you can use the search feature of the [[Fedora Package Database|https://admin.fedoraproject.org/pkgdb]]. Typing in keywords will let you search the packages and clicking into a packages record will show you exactly who owns a package in each release of Fedora. Every package maintainer can be reached via an e-mail alias using the displayed username as the local-part and fedoraproject.org as the domain. + +Primary Contact: [[Tom Callaway|http://fedoraproject.org/wiki/TomCallaway]]. Fedora Engineering Manager. + + +## Gentoo + +Gentoo's main mailing list for development is [[gentoo-dev@gentoo.org|mailto:gentoo-dev@gentoo.org]]. + +The maintainer or team responsible for a particular package can be gotten from [[http://sources.gentoo.org/viewcvs.py/gentoo-x86/<category>/<pkgname>/metadata.xml|http://sources.gentoo.org/viewcvs.py/gentoo-x86/]] (<maintainer>@gentoo.org or <herd>@gentoo.org). Package names can be looked up through [[http://packages.larrythecow.org/|http://packages.larrythecow.org/]] (the official package page is unsearchable for some odd reason). + +A full list of developers is available at [[http://www.gentoo.org/proj/en/devrel/roll-call/userinfo.xml|http://www.gentoo.org/proj/en/devrel/roll-call/userinfo.xml]]. + + +## Mandriva + +Mandriva maintainers' mailing list: [[maintainers@mandrivalinux.com|mailto:maintainers@mandrivalinux.com]] + + +## openSUSE + +openSUSE's main packager list is [[opensuse-packaging@opensuse.org|mailto:opensuse-packaging@opensuse.org]]. The development list is [[opensuse-factory@opensuse.org|mailto:opensuse-factory@opensuse.org]]. Archives are at [[http://lists.opensuse.org|http://lists.opensuse.org]]. + +A packager can be contacted by the Bug Report link in the openSUSE Build Service by following the link from a package's entry in the openSUSE:Factory project back to its development project - alternatively look in an RPM changelog. + + +## Ubuntu + +Email discussion among Ubuntu developers takes place on the [[ubuntu-devel mailing list|http://lists.ubuntu.com/mailman/listinfo/ubuntu-devel]], which is moderated (excepting registered Ubuntu developers). The [[ubuntu-devel-discuss mailing list|http://lists.ubuntu.com/mailman/listinfo/ubuntu-devel-discuss]] is available for open discussion about Ubuntu development. [[Various other mailing lists|https://lists.ubuntu.com/mailman/listinfo/]] are available, some of which focus on specific areas of development. The charter of the [[ubuntu-devel mailing list|http://lists.ubuntu.com/mailman/listinfo/ubuntu-devel]] includes "Point of contact for upstream developers to reach Ubuntu developers", and while it is moderated that moderation is usually swift. + +The `#ubuntu-devel` channel on the FreeNode IRC network is home to many Ubuntu developers for real-time communication. diff --git a/Distributions/DistributionLocations.mdwn b/Distributions/DistributionLocations.mdwn new file mode 100644 index 00000000..02f8a583 --- /dev/null +++ b/Distributions/DistributionLocations.mdwn @@ -0,0 +1,161 @@ + +Locations of bug-trackers, packaging repositories and files such as patches and changes to the upstream source. + + +## Debian + +* Package format: deb +* Package: + * [[http://packages.debian.org/$PACKAGE|http://packages.debian.org/$PACKAGE]] (binary packages, user-oriented) + * [[http://packages.qa.debian.org/$PACKAGE|http://packages.qa.debian.org/$PACKAGE]] (source packages, developer-oriented) +* BTS: + * [[http://bugs.debian.org|http://bugs.debian.org]] + * [[http://bugs.debian.org/$PACKAGE|http://bugs.debian.org/$PACKAGE]] + * [[http://bugs.debian.org/src:$PACKAGE|http://bugs.debian.org/src:$PACKAGE]] +* Changes: integrated in the package format in the .diff.gz +* Patches: + * [[http://patch-tracker.debian.org|http://patch-tracker.debian.org]] (per source package listing of which patches have been applied by Debian) + * there are several patch systems like quilt, dpatch, ... to store separated patches +* VCS: several used, go on [[http://packages.qa.debian.org/$PACKAGE|http://packages.qa.debian.org/$PACKAGE]] and check the Vcs-* link at the top-left of the page + * VCS-indexes can be found at [[http://git.debian.org|http://git.debian.org]] , [[http://svn.debian.org|http://svn.debian.org]], etc. +* Homepage: location stored in the Homepage-field [[*|http://www.debian.org/doc/developers-reference/ch-best-pkging-practices.en.html#s-bpp-upstream-info]] +* Wiki: [[http://wiki.debian.org|http://wiki.debian.org]] +* CVE: [[http://security-tracker.debian.org/tracker/$CVE|http://security-tracker.debian.org/tracker/$CVE]] + +## Exherbo + +* Package format: exheres (source-based build recipe) +* Packages: [[http://git.exherbo.org/summer/|http://git.exherbo.org/summer/]] +* BTS: [[https://bugs.exherbo.org/|https://bugs.exherbo.org/]] +* VCS: [[http://git.exherbo.org/|http://git.exherbo.org/]] +* Homepage: [[http://www.exherbo.org/|http://www.exherbo.org/]] + +## Fedora + +* Package format: .rpm +* Packages: [[https://admin.fedoraproject.org/pkgdb|https://admin.fedoraproject.org/pkgdb]] +* Updates & QA: [[http://admin.fedoraproject.org/updates|http://admin.fedoraproject.org/updates]] +* BTS: + * [[https://bugzilla.redhat.com|https://bugzilla.redhat.com]] + * [[http://bugz.fedoraproject.org/$PACKAGE|http://bugz.fedoraproject.org/$PACKAGE]] +* VCS: [[http://pkgs.fedoraproject.org/gitweb/?p=$PACKAGE.git|http://pkgs.fedoraproject.org/gitweb/?p=$PACKAGE.git]] +* Translations: [[https://translate.fedoraproject.org|https://translate.fedoraproject.org]] +* Wiki: [[https://fedoraproject.org/wiki/|https://fedoraproject.org/wiki/]] +* CVE: [[https://bugzilla.redhat.com/show_bug.cgi?id=$CVE|https://bugzilla.redhat.com/show_bug.cgi?id=$CVE]] + +## Foresight + +* Package format: conary +* Packages: [[http://www.rpath.com/rbuilder/repos/foresight/browse|http://www.rpath.com/rbuilder/repos/foresight/browse]] +* BTS: [[https://issues.foresightlinux.org|https://issues.foresightlinux.org]] +* VCS: [[http://www.foresightlinux.org/hg|http://www.foresightlinux.org/hg]] +* Wiki: [[https://wiki.foresightlinux.org/dashboard.action|https://wiki.foresightlinux.org/dashboard.action]] + +## FreeBSD + +* Packages: [[http://www.freshports.org/|http://www.freshports.org/]] (what I use to take a look) +* BTS: [[http://www.freebsd.org/support/bugreports.html|http://www.freebsd.org/support/bugreports.html]] +* VCS: [[http://www.freebsd.org/cgi/cvsweb.cgi/ports/|http://www.freebsd.org/cgi/cvsweb.cgi/ports/]] + +## Gentoo + +* Packages (QA): [[http://packages.gentoo.org/|http://packages.gentoo.org/]] +* BTS: [[http://bugs.gentoo.org/|http://bugs.gentoo.org/]] +* VCS: [[http://sources.gentoo.org/viewcvs.py/gentoo-x86/|http://sources.gentoo.org/viewcvs.py/gentoo-x86/]] +* CVE: [[http://bugs.gentoo.org/show_bug.cgi?id=$CVE|http://bugs.gentoo.org/show_bug.cgi?id=$CVE]] + +## gNewSense + +* Package format: .deb +* Packages page: n/a, we usually use [[http://packages.ubuntu.com/|http://packages.ubuntu.com/]] and search 'hardy' +* BTS: [[http://bugs.gnewsense.org/|http://bugs.gnewsense.org/]] +* VCS: [[http://svn.gnewsense.svnhopper.net/gnewsense/builder/trunk/|http://svn.gnewsense.svnhopper.net/gnewsense/builder/trunk/]] +* Changes: applied by scripts found in VCS + +## GoboLinux + +* Packages: [[http://gobolinux.org/?page=packages|http://gobolinux.org/?page=packages]] +* BTS: [[http://bugs.gobolinux.org/|http://bugs.gobolinux.org/]] +* VCS: [[http://svn.gobolinux.org|http://svn.gobolinux.org]] +* Recipes: [[http://recipes.gobolinux.org/|http://recipes.gobolinux.org/]] + +## Mageia + +* Package format: .rpm +* Package/maintainer lists: [[http://pkgsubmit.mageia.org/data/maintdb.txt|http://pkgsubmit.mageia.org/data/maintdb.txt]] +* Packages: [[http://sophie.zarb.org/|http://sophie.zarb.org/]] (unofficial) +* Bugs: [[http://bugs.mageia.org/|http://bugs.mageia.org/]] +* VCS: [[http://svnweb.mageia.org/packages/cauldron/|http://svnweb.mageia.org/packages/cauldron/]] or svn://svn.mageia.org/svn/packages/cauldron/ (development tree), contains specs and all sources/patches +* Wiki: [[http://wiki.mageia.org/|http://wiki.mageia.org/]] + +## Mandriva + +* Package format: .rpm +* Package/maintainer lists: [[http://maintainers.mandriva.com/|http://maintainers.mandriva.com/]] +* Packages: [[http://sophie.zarb.org/|http://sophie.zarb.org/]] (unofficial) +* Bugs: [[http://qa.mandriva.com/|http://qa.mandriva.com/]] +* VCS: [[http://svn.mandriva.com/cgi-bin/viewvc.cgi/packages/cooker/|http://svn.mandriva.com/cgi-bin/viewvc.cgi/packages/cooker/]] (development tree), contains specs and all sources/patches +* Wiki: [[http://wiki.mandriva.com|http://wiki.mandriva.com]] + +## openSUSE + +* Package format: rpm +* Packages: [[http://en.opensuse.org/Package_repositories|http://en.opensuse.org/Package_repositories]] +* Package QA: [[http://en.opensuse.org/Portal:How_to_participate|http://en.opensuse.org/Portal:How_to_participate]] +* BTS: [[https://bugzilla.novell.com|https://bugzilla.novell.com]] +* Changes: integrated in the package format and through build server history checkins +* Source packages and Patches: browsable at [[https://build.opensuse.org/project/show?project=openSUSE%3AFactory|https://build.opensuse.org/project/show?project=openSUSE%3AFactory]] +* VCSes: [[http://gitorious.org/opensuse|http://gitorious.org/opensuse]] +* Homepage: [[http://www.opensuse.org/|http://www.opensuse.org/]] +* Wiki: [[http://en.opensuse.org/|http://en.opensuse.org/]] +* CVE: [[http://support.novell.com/security/cve/$CVE.html|http://support.novell.com/security/cve/$CVE.html]] + +## Openwall GNU/*/Linux (Owl) + +* Package format: rpm +* Packages: /pub/Owl/current/*/RPMS/ on the FTP mirrors +* Changes: [[http://www.openwall.com/Owl/CHANGES-current.shtml|http://www.openwall.com/Owl/CHANGES-current.shtml]] for major changes (minor ones are documented in CVS commits and package %changelogs only) +* VCS: [[http://cvsweb.openwall.com|http://cvsweb.openwall.com]] +* Wiki: [[http://openwall.info/wiki/Owl|http://openwall.info/wiki/Owl]] +* Homepage: [[http://www.openwall.com/Owl/|http://www.openwall.com/Owl/]] + +## Pardus + +* Package format: .pisi +* Packages: [[http://packages.pardus.org.tr/|http://packages.pardus.org.tr/]] +* BTS: [[http://bugs.pardus.org.tr/|http://bugs.pardus.org.tr/]] +* VCS: + * Packages - [[http://svn.pardus.org.tr/pardus/|http://svn.pardus.org.tr/pardus/]] + * Projects - [[http://svn.pardus.org.tr/uludag/|http://svn.pardus.org.tr/uludag/]] +* Changes & Patches: Included in source packages [[*|http://en.pardus-wiki.org/Pisi_Package]] +* Translations: [[http://translate.pardus.org.tr|http://translate.pardus.org.tr]] + +## Ubuntu + +* Package format: .deb +* Packages: + * [[http://packages.ubuntu.com/|http://packages.ubuntu.com/]] + * [[https://launchpad.net/ubuntu/+source/$PACKAGE|https://launchpad.net/ubuntu/+source/$PACKAGE]] for source packages +* BTS: [[http://bugs.launchpad.net/ubuntu|http://bugs.launchpad.net/ubuntu]] +* VCS: sometimes you have to consider the VCS used by the Debian developer and a VCS used by a MOTU (usually [[http://code.launchpad.net/ubuntu|http://code.launchpad.net/ubuntu]] ) +* Changes: same format as Debian +* Wiki: [[http://wiki.ubuntu.com|http://wiki.ubuntu.com]] +* Translations: [[http://translations.launchpad.net/ubuntu|http://translations.launchpad.net/ubuntu]] +* Feature requests: [[http://brainstorm.ubuntu.com/|http://brainstorm.ubuntu.com/]] +* Blueprints (feature specifications tracker): [[http://blueprints.launchpad.net/ubuntu|http://blueprints.launchpad.net/ubuntu]] +* CVE: [[https://launchpad.net/bugs/cve/$CVE|https://launchpad.net/bugs/cve/$CVE]] +* CVE: [[http://people.canonical.com/~ubuntu-security/cve/$CVE|http://people.canonical.com/~ubuntu-security/cve/$CVE]] + +## Yoper + +* Package format: rpm +* Packages: [[http://development.yoper.com/pub/devel/source-cache/|http://development.yoper.com/pub/devel/source-cache/]] +* Package QA: + * [[http://www.yoper.com/wiki|http://www.yoper.com/wiki]] + * [[http://www.yoper.com/forum/|http://www.yoper.com/forum/]] +* BTS: [[http://www.yoper.com/bugtracker|http://www.yoper.com/bugtracker]] +* Changes: Automatic, through build server history checkins +* patches: Hardly any patches, one of he principles of Yoper. Back to the source and optimised for the purpose. +* VCSes: svn+[[ssh://development.yoper.com/thinktank|ssh://development.yoper.com/thinktank]] +* Homepage: [[http:/www.yoper.com|http:/www.yoper.com]] +There's a similar wiki page at [[http://oss-security.openwall.org/wiki/distro-patches|http://oss-security.openwall.org/wiki/distro-patches]] diff --git a/Distributions/Fosdem2010.mdwn b/Distributions/Fosdem2010.mdwn new file mode 100644 index 00000000..5a97208c --- /dev/null +++ b/Distributions/Fosdem2010.mdwn @@ -0,0 +1,59 @@ + +This page is to coordinate the cross-distribution devroom at FOSDEM 2010. For more information, see [[http://www.fosdem.org/2010/distrominiconf|http://www.fosdem.org/2010/distrominiconf]]. + + +## Proposed talks + +This list contains each and every talk proposal made on the list, just so that we don't lose track of them. + +Note that some of these were "what about..." type proposals that weren't very much fleshed out; others were by people who are not related to any distribution and may therefore be somewhat out of scope for the devroom. I could have excluded both of these groups, but that would have left us with little if any proposals, and I didn't want to be the judge just yet. + +Note that the deadline for talk submissions was January 5th; i.e., talks should be submitted no later than the 4th. This deadline has now passed. + +* Gabor Szabo: packaging perl and CPAN modules. [[mail|http://lists.fosdem.org/pipermail/dist2010/2009-November/000030.html]]. +* Jeff Johnson: Transactionally Protected Package Management. [[mail|http://lists.fosdem.org/pipermail/dist2010/2009-November/000036.html]]. +* Vincent Untz: Working with GNOME upstream. [[mail|http://lists.fosdem.org/pipermail/dist2010/2009-November/000039.html]]. +* John Thomson: Transactional Roll-backs and Upgrades. [[mail|http://lists.fosdem.org/pipermail/dist2010/2009-November/000041.html]]/[[link|http://wiki.mancoosi.org/bin/view/public/events/FOSDEM2010]]. +* Dominique Dumont: Config::Model and configuration upgrades during package upgrade. [[mail|http://lists.fosdem.org/pipermail/dist2010/2009-December/000054.html]], [[second mail|http://lists.fosdem.org/pipermail/dist2010/2009-December/000075.html]]. +* Nicolas Pierron: the configuration system of NixOS. [[mail|http://lists.fosdem.org/pipermail/dist2010/2009-December/000055.html]]. +* Guillaume Rousse: the youri project. [[mail|http://lists.fosdem.org/pipermail/dist2010/2009-December/000064.html]]. +* Anne NICOLAS: translations of package descriptions. [[mail|http://lists.fosdem.org/pipermail/dist2010/2009-December/000065.html]]. +* Ralf Treinen and Stefano Zacchiroli: Cross-distro dependency resolution. [[mail|http://lists.fosdem.org/pipermail/dist2010/2009-December/000056.html]]. +* Max Spevack: Fedora Governance [[mail|http://lists.fosdem.org/pipermail/dist2010/2009-December/000087.html]]. +* Sandro Mathys and Marcus Moeller : Spacewalk [[mail|http://lists.fosdem.org/pipermail/dist2010/2009-December/000088.html]]. +* Ralph Angenendt : Infrastructure Management [[mail|http://lists.fosdem.org/pipermail/dist2010/2009-December/000084.html]] +* Ralph Angenendt : Mirror Management [[mail|http://lists.fosdem.org/pipermail/dist2010/2009-December/000085.html]] +* Thomas Koch: Packaging with topgit [[mail|http://lists.fosdem.org/pipermail/dist2010/2009-December/000090.html]] +* Sune Vuorela: Shared libraries in Debian [[mail|http://lists.fosdem.org/pipermail/dist2010/2009-December/000094.html]] +* Thomas Canniot and Armel Kermorvant: Fedora-fr and upstream French communities [[mail|http://lists.fosdem.org/pipermail/dist2010/2009-December/000094.html]] +* Petteri Räty: Distribution HR management [[mail|http://lists.fosdem.org/pipermail/dist2010/2009-November/000008.html]] +* Petteri Räty: How to be a good upstream [[mail|http://lists.fosdem.org/pipermail/dist2010/2009-November/000008.html]] +* Wouter Verhelst: Debian Secrets: power tools for power users. [[mail|http://lists.fosdem.org/pipermail/dist2010/2009-December/000099.html]] +* Adrian Schröter: Cross-distro packaging experience with the openSUSE Buildservice [[mail|http://lists.fosdem.org/pipermail/dist2010/2010-January/000108.html]] +* Christopher Hofmann: Distribution Image building with KIWI [[mail|http://lists.fosdem.org/pipermail/dist2010/2010-January/000109.html]] +* Klaas Freitag: Hermes message dispatching [[mail|http://lists.fosdem.org/pipermail/dist2010/2010-January/000110.html]] +* Stephan Kulow: Clicfs as perfect live cd file system [[mail|http://lists.fosdem.org/pipermail/dist2010/2010-January/000111.html]] +* NN: SUSE Studio [[mail|http://lists.fosdem.org/pipermail/dist2010/2010-January/000113.html]] +* NN: [[MirrorBrain|MirrorBrain]] [[mail|http://lists.fosdem.org/pipermail/dist2010/2010-January/000113.html]] +* Dave Neary: The Maemo Community Council: a case-study in governance. [[mail|http://lists.fosdem.org/pipermail/dist2010/2010-January/000116.html]] +* Bruno Cornec: Continuous Packaging with Project-Builder.org. [[mail|http://lists.fosdem.org/pipermail/dist2010/2010-January/000107.html]] +* Peter Eisentraut: Linux distribution for the cloud. [[mail|http://lists.fosdem.org/pipermail/dist2010/2010-January/000119.html]] +* Pavol Rusnak: RPM packaging collaboration. [[mail|http://lists.fosdem.org/pipermail/dist2010/2010-January/000120.html]] +* Harald Hoyer: Dracut - a generic, modular initramfs generation tool. [[mail|http://lists.fosdem.org/pipermail/dist2010/2010-January/000121.html]] + +## Coordination + +General coordinator is Wouter Verhelst <[[wouter@debian.org|mailto:wouter@debian.org]]> + +Coordinators for individual distributions are: + +* Debian: Wouter Verhelst <[[wouter@debian.org|mailto:wouter@debian.org]]> +* Gentoo: Petteri Räty <[[betelgeuse@gentoo.org|mailto:betelgeuse@gentoo.org]]> +* Mandriva: Anne Nicolas <[[anne.nicolas@mandriva.com|mailto:anne.nicolas@mandriva.com]]> +* CentOS: Fabian Arrotin <[[arrfab@centos.org|mailto:arrfab@centos.org]]> +* Fedora: Frederic Hornain <[[fhornain@gmail.com|mailto:fhornain@gmail.com]]> +* openSUSE: Henne Vogelsang <[[hvogel@opensuse.org|mailto:hvogel@opensuse.org]]>, Pascal Bleser <[[pascal.bleser@opensuse.org|mailto:pascal.bleser@opensuse.org]]> +* Foresight: Mark Trompell <[[mark@foresightlinux.org|mailto:mark@foresightlinux.org]]> +* Arch: Dieter Plaetinck <[[dieter@plaetinck.be|mailto:dieter@plaetinck.be]]> +* Maemo: Dave Neary <[[dneary@maemo.org|mailto:dneary@maemo.org]]> +* Caixa Mágica: Paulo Trezentos <[[paulo.trezentos@caixamagica.pt|mailto:paulo.trezentos@caixamagica.pt]]>
\ No newline at end of file diff --git a/Distributions/Meetings.mdwn b/Distributions/Meetings.mdwn new file mode 100644 index 00000000..49eba2a5 --- /dev/null +++ b/Distributions/Meetings.mdwn @@ -0,0 +1,20 @@ + + +# Cross-distribution Meetings/Hackfests + +The goal of this page is to track all meetings/hackfests that cover cross-distribution topics, and to keep some links to reports and conclusions of each event. + +See [[http://live.gnome.org/Hackfests|http://live.gnome.org/Hackfests]] as an example of how to use this page :-) + + +## 2011 + +**[[Application Installer Meeting|Distributions/Meetings/AppInstaller2011]]**, Nürnberg (Germany), January 19-21 + +* [[http://www.enricozini.org/2011/debian/appinstaller2011/|http://www.enricozini.org/2011/debian/appinstaller2011/]] +* [[http://www.enricozini.org/2011/debian/pkgshelf/|http://www.enricozini.org/2011/debian/pkgshelf/]] +* [[http://www.enricozini.org/2011/debian/distromatch/|http://www.enricozini.org/2011/debian/distromatch/]] +* [[http://blogs.gnome.org/hughsie/2011/01/24/application-installer-miniconf-trip-report/|http://blogs.gnome.org/hughsie/2011/01/24/application-installer-miniconf-trip-report/]] +* [[http://stick.gk2.sk/blog/2011/01/gnome-python-hackfest-appinstaller-meeting-and-bretzn-hackfest/|http://stick.gk2.sk/blog/2011/01/gnome-python-hackfest-appinstaller-meeting-and-bretzn-hackfest/]] +* [[http://www.vuntz.net/journal/post/2011/01/25/Results-of-the-App-Installer-meeting%2C-and-some-thoughts-on-cross-distro-collaboration|http://www.vuntz.net/journal/post/2011/01/25/Results-of-the-App-Installer-meeting%2C-and-some-thoughts-on-cross-distro-collaboration]] +* _link to blog post_
\ No newline at end of file diff --git a/Distributions/Meetings/AppInstaller2011.mdwn b/Distributions/Meetings/AppInstaller2011.mdwn new file mode 100644 index 00000000..3c44e5a2 --- /dev/null +++ b/Distributions/Meetings/AppInstaller2011.mdwn @@ -0,0 +1,86 @@ + + +# Cross-distro Meeting on Application Installer + +(application installer, or app store, market place, software center, etc. -- many names for one thing ;-)) + + +## Goals + +Blue-sky goals: + +* agree on a common UI to install applications +* agree on what metadata to use, how to generate it, where to host it +* agree on a protocol to use to provide non-static metadata (featured apps, ratings, comments, etc.) +* decide what metadata can be shared between distros, and what should stay distro-specific (eg: do we want user comments to be shared?) +In reality, if it turns out we can't all agree on one item, it's still fine: it doesn't mean we can't collaborate on the other items. And some distros might still work together. + +It's worth mentioning here that what matters to us is the end-user experience. It matters more than the technical implementation. + + +## Background + +Nearly all distributions are slowly moving towards making it easier to deal with applications, and get information about those. The Ubuntu Software Center is a good example of work being done here. + +At the moment, many of us are working in our own corners, while we could certainly all move much faster if we worked together, especially since we're all targetting mostly the same result. + +We do want content to be provided not just by us, distributors, but also by the users: their experience with an application can inspire other users to install it too. + + +## Sponsors + +The events is sponsored by Novell (hosting, sponsorship of three attendees) and Debian (sponsorship of one attendee). + +Many thanks also to Canonical and Red Hat for sending people to this event! + + +## Who/Where/When + +January 19th-21st, in Nürnberg, Germany. + +The goal is to have the event around the same time as the [[Bretzn meeting|http://en.opensuse.org/openSUSE:2011_Bretzn_Meeting]], which covers related topics, but from a different perspective. + +We want key people from various distributions (10-15 people max). + + +### Interested people +[[!table header="no" class="mointable" data=""" +**Name** | **Distro** | **Need sponsorship?** | **Staying at Azimut Hotel** | **Hotel booked** +_John Doe_ | _Tux Distro_ | _Yes (~150€)_ | _Yes, 18-22_ | _Yes_ +Richard Hughes | Fedora | No (thanks Red Hat!) | Yes, 18-22 | Yes +Michael Vogt | Ubuntu | No (thanks Canonical!) | Yes, 18-21 | Yes +Vincent Untz | openSUSE | No (thanks Novell!) | Yes, 18-23 | Yes +Alexander Naumov | openSUSE | No (local) | No | Not needed +Frank Karlitschek | KDE/openDesktop.org | Yes, sponsored by Novell | ? | ? +Pavol Rusnak | openSUSE | No (thanks Novell!) | Yes, 18-23 | Yes +Enrico Zini | Debian | Yes, sponsored by Novell | Yes, 18-21 | Yes +David Kalnischkies | Debian | Yes, sponsored by Debian! | Yes, 18-21 | Yes +Samuel Verschelde | Mageia | Yes, sponsored by Novell | Yes, 18-22 | Yes +Olivier Thauvin | Mageia | No (thanks to you!) | Yes, 18-22 | Yes +Michael Scherer | Mageia | No (thanks to you!) | Yes, 18-22 | Yes +Duncan Mac-Vicar (?) | openSUSE | No (local) | No | Not needed +Florian Festi | Fedora | No (thanks Red Hat!) | Yes, 18-21 | Yes +Michael Schroeder | openSUSE | No (local) | No | Not needed +Sebastian Heinlein | Ubuntu | No | Yes (19-20) | ? +"""]] + + +## Results + +* [[Video Recording 53m:06s|http://www.youtube.com/watch?v=BHeP2ZBwS_U]]: Presenting the Summary of Cross-Distro Application Installer Meeting January 19th-21st, in Nürnberg, Germany. + +## Some related work + +* [[Listaller Project|http://listaller.nlinux.org/]]: a cross-distro AppStore +* [[Software Center|https://wiki.ubuntu.com/SoftwareCenter]]: UI focused on applications +* [[app-install|http://blogs.gnome.org/hughsie/2010/09/07/linux-and-application-installing/]]: UI focused on applications + code to generate metadata +* [[screenshots.debian.net|http://screenshots.debian.net/]]: web service providing app screenshot +* [[Open Collaboration Services|Specifications/open-collaboration-services]]: specification that can help provide social features (rating, comments, etc.) +* [[http://launchpad.net/rnr-server|http://launchpad.net/rnr-server]]: django based server for ratings&reviews webservice (not following the open-collaboration-spec yet, but there is interesst about this from the devs) +* [[mageia-app-db|http://mageia-app-db.tuxette.fr/projects/mageia-app-db/wiki]]: Mageia's application database (work in progress, there's a link to a nightly updated instance on the wiki) +* [[Sophie|http://sophie.zarb.org/]]: Search and analyze rpms from various distribution. +* [[openSUSE Software Portal|http://software.opensuse-community.org/web/]]: a web app focused on applications + +## Source + +* [[Gitorious|http://gitorious.org/+opensuse-appstore]]: openSUSE-appstore
\ No newline at end of file diff --git a/Distributions/Packaging.mdwn b/Distributions/Packaging.mdwn new file mode 100644 index 00000000..8272fe5d --- /dev/null +++ b/Distributions/Packaging.mdwn @@ -0,0 +1,2 @@ + +Distribution neutral packaging guidelines are described here. diff --git a/Distributions/Packaging/WhyUpstream.mdwn b/Distributions/Packaging/WhyUpstream.mdwn new file mode 100644 index 00000000..eeb43942 --- /dev/null +++ b/Distributions/Packaging/WhyUpstream.mdwn @@ -0,0 +1,72 @@ + + +# Upstream Guidelines + +Distributions should have a strong focus on not deviating from upstream as much as possible in all the different software it includes in the repository. The following is a general set of best practice guidelines on why this is a good idea, tips for sending your patches upstream, and the potential exceptions any distribution might make. The primary goal is to share the benefits of a common codebase for end users and developers while simultaneously reducing unnecessary maintenance efforts. + +**upstream** (noun) In free and open source projectas, the _upstream_ of a program or set of programs is the project that develops those programs. Any Linux distribution is _downstream_ of those projects. This term comes from the idea that water and the goods it carries float downstream and benefit those who are there to receive it. + +**to upstream** (verb) A short-hand way of saying "push changes to the upstream project". + + +## Credit + +These guidelines are a more generalized version of the original Fedora Project guidelines at [[http://fedoraproject.org/wiki/PackageMaintainers/WhyUpstream|http://fedoraproject.org/wiki/PackageMaintainers/WhyUpstream]] + + +## Why Upstream + +* **Common Benefit And Reduced Maintenance Burden** - When a distribution carries patches that are specific to one or deviations from upstream projects, those patches are not shared by every distribution. This puts the burden of maintaining those patches on that distribution, which includes keeping those patches in a functional state by rewriting or forward-porting them for every upstream release. This effort can quickly add up to be overwhelming, while not being in the spirit of sharing the benefits (as well as the effort in maintaining) free and open source software. + +* **Documentation** - Upstream projects are documented formally (in the form of man/info pages and longer guides) and informally in many user forums or mailing lists as answers to user questions. Deviations from upstream projects can thus confuse end users when those patches cause changes in behavior that are distribution specific and not documented properly, even where the formal documentation (such as man pages) are also patched to describe the changes. + +* **Translations** - Maintaining translations upstream gains the advantage of established translation communities, which are most likely more experienced with the project terms. Downstream projects benefit when using those translations. In addition, it lifts the burden of hosting, and of the need to merge often from upstream to downstream and back again. To make sure translation work continues upstream, Fedora developed [[Transifex|https://fedorahosted.org/transifex/]] , which helps translators contribute directly to upstream projects. Any string changes that were introduced by patches should be maintained by the downstream community. + +* **Upstream Acceptance** - A Linux distribution is typically downstream of many thousands of software projects. Much of this software is packaged by maintainers who are not programmers or lack expertise in the language(s) the software is written in. In some cases the software has a large and complex codebase (such as the kernel or openoffice.org) and the package maintainers might not have the level of understanding in all areas compared to subsystem maintainers or upstream developers. For this and other reasons, any linux distribution needs the acceptance of upstream software developers. These developers may view any significant patches as a fork or refuse to take bug reports from particular users due to the differences in the codebase. Any Linux distribution as a project must strive to be welcoming and cooperative with upstream developers as much as possible. We must avoid Linux distribution specific patches and any patches that are useful should be sent upstream to these developers via mailing lists, bug trackers, or direct email. + +* **Quality Assurance** - Patches that are accepted upstream are usually reviewed or tested by many people including developers and testers. This includes testing by other GNU/Linux distributions. A deviation from the common codebase used by many is a potential chance of introducing a regression that is specific to a distribution. + +* **Security** - A special case of the "Quality Assurance" issue is that changes that have surprising security implications are more likely to be detected by upstream (who often have deeper knowledge of the program). + +* **Fast incremental improvements** - Staying close to upstream versions is helpful when doing version bumps for updates that bring in new features. This prevents tedious backporting of only security and bug fixes. Deviations from upstream can significantly hamper the speed of delivering improvements from new versions to end users. + +* **ABI or API Deviations** - Patches that introduce a new application binary interface (ABI) or application program interface (API) must be especially avoided, even if the ABI/API changes are planned to land upstream. When these patches get upstream (if ever), upstream developers might introduce changes in the ABI/API during the code review process before merging the code. This could break other software in the repository that makes use of the distribution-patched ABI/API. + +* **Direct End User Feedback** - When users run into problems with any software that is in a Linux distribution, they can report the problems directly upstream. By not deviating from upstream, it remains a central location for all bug reports on that software, leaving package maintainers to concentrate on good packaging instead of acting in between users and upstream issues. + + +## Tips On Upstreaming Patches + +* Talk to upstream: Maintaining a regular flow of communication with the upstream project is helpful in understanding the upstream developers well, and encourages them to be more responsive to your requests. It also helps in understanding technical issues, such as how they prefer patches to be submitted. + +* Make the patches generic enough to be maintained by upstream developers. Explain the need for your patches, that is, what bugs they fix or what features they add. Any references to bugzilla reports or user requests can be quite useful for the developers who receive your patches. + +* Divide patches into small and independent chunks that remain functional, so they can be understood, reviewed, and accepted or rejected individually. + +* If the patch introduces new strings or changes existing ones, make the changes as generic as possible. + +* Fix your coding style to match the upstream project's guidelines. This might seem trivial but many upstream projects insist on following their guidelines so that their codebase looks internally self consistent and is more maintainable. + +* Test your changes as throughly as you can before you send them upstream. Broken patches leave a long-lasting bad impression. + +* Be patient and cooperative. If feedback is offered, discuss changes, answer questions, and provide revisions that fix any problems. Don't flame or argue unnecessarily with upstream developers. The goal is to get your patches committed upstream and not to demonstrate "who is better." + + +## Some Examples Of Exceptions + +* **Severe Security Issues Or Major Bug Fixes** - For any major issues, waiting on a new release from upstream for a fix can be too much of a delay. In these instances, it may be better to backport those fixes from upstream and do an update. If you are writing a new patch, send it upstream so that all Linux distributions shares the benefits and avoid deviations in new releases that follow. Due to differences in release schedules between upstream projects and distribution releases, maintainers would have to keep in mind feature and development freezes in distributions and fix problems accordingly. + +* ** Non-free or patent encumbered software** - If upstream projects include software that is non-free or has known patent issues, such software might not meet the distribution licensing guidelines. In many instances, such code is optional in the form of plugins that simply does not need to included in its software repository. In other cases, it might be possible to work with upstream on making it optional or patch specific portions. + +* **Dead Or Unresponsive Upstream Projects** - In cases where upstream projects are either dead or unresponsive, it might be acceptable to patch the software. If upstream is dead, you might want to consider sharing patches with other distributions or taking over maintenance if you have the time, skills, and interest. Be wary of maintaining software with no upstream since all the burden of maintaining the codebase as well as packaging issues are with you. If upstream is unresponsive and many distributions are deviating significantly, it might be a opportunity for a cross distribution fork (Similar to XFree86 and Xorg). + +* **Patches Heading Upstream** - Any patches that are known to be headed upstream _might_ be patched temporarily in a Linux distribution for a high benefit addition of new features to end users. If this is done, maintenance effort of the patches should be low impact for the small amount of time until upstream merges the patches and does a new release. + +* **Distribution Integration** - There are features that are critical or very good to have for a particular distribution but not been significant enough for various upstream projects to accept related enhancements just yet. Use your discretion carefully when choosing to integrate any such patches since there is a trade off between upstream acceptance and distribution integration and associated costs/benefits. + + +## References + +* [[https://fedoraproject.org/wiki/Packaging/Guidelines#All_patches_should_have_an_upstream_bug_link_or_comment|https://fedoraproject.org/wiki/Packaging/Guidelines#All_patches_should_have_an_upstream_bug_link_or_comment]] +* [[http://fedoraproject.org/wiki/PackageMaintainers/TrackingUpstream|http://fedoraproject.org/wiki/PackageMaintainers/TrackingUpstream]] +* [[http://fedoraproject.org/wiki/PackageMaintainers/TrackingDownstream|http://fedoraproject.org/wiki/PackageMaintainers/TrackingDownstream]]
\ No newline at end of file diff --git a/EricAnholt.mdwn b/EricAnholt.mdwn new file mode 100644 index 00000000..ba53e364 --- /dev/null +++ b/EricAnholt.mdwn @@ -0,0 +1,6 @@ + + * Name: Eric Anholt + * Email: [[eta@lclark.edu|mailto:eta@lclark.edu]], [[anholt@FreeBSD.org|mailto:anholt@FreeBSD.org]] + * Homepage: [[http://people.freebsd.org/~anholt/|http://people.freebsd.org/~anholt/]] + * advogato: [[http://advogato.org/person/anholt/|http://advogato.org/person/anholt/]] +-- Main.EricAnholt - 27 Oct 2003 diff --git a/FreedesktopProjects.mdwn b/FreedesktopProjects.mdwn new file mode 100644 index 00000000..1681775c --- /dev/null +++ b/FreedesktopProjects.mdwn @@ -0,0 +1,146 @@ + + +## Freedesktop.org Possible Projects Page + +It is often difficult to see if there are projects that you might be interested in contributing to. This page attempts to help this problem for you. + + * Project - a name for a project + * Type - type of project: design, code, web or documentation + * Difficulty - rough guess at the difficulty of the project - easy, moderate, difficult + * Size - how much work is involved to complete the project - small, medium, large + * Comp. - how far along the (sub)project is estimatated to be + * Contact - who to contact to get guidance on how to proceed. That person would like to get the project completed, but needs help in some form. +Please make appropriate changes here yourself. General comments should go to appropriate mailing lists. For projects that are not underway, discussions are vital, as rough consensus is vital for community acceptance, and for discussion of technical alternatives. + + +## Freedesktop.org X Window System Related Projects + +New people interested in working on the X Window System or related desktop technologies have often found it difficult to find a manageable size project to undertake, or even understand where to go to get guidance. The X distribution in particular when seen from outside has been very intimidating due to its size, even though it is highly modular, and often/usually well designed. The recent work to modularize the distribution is helping. + +The list below breaks down some of the larger projects underway (or contemplated) into more manageable pieces among which you may find something that sparks your interests, matches your talents, or possibly that your organization or company feels it can't live without. I hope this list will also help you better understand where work is now. You are encouraged to choose one or more of these projects and wade in; you can help X to make much more rapid progress by your contribution. + +These are projects that various people are considering; please feel free to send along your suggestions of additions to this list. + +Please do not presume there is any ordering of importance to the tasks below; this is just a first cut at possible projects. + + +## Projects Underway + + +### Render Extension + +Render brings anti-aliased alpha blended text and graphics to the X Window System. + +The Render extension, already implemented and deployed, needs completion in a number of areas. This was held up by the urgency of getting AA text deployed, and a difficult numerical problem with the formulation of trapezoids that would have required very high precision arithmetic to implement (which would have been big and slow). + +The Render extension is discussed on the [[xorg@lists.freedesktop.org mailing list|http://lists.freedesktop.org/mailman/listinfo/xorg]]. It is nearly complete, with the major remaining issues being documentation and test suite. If interested in any of these projects, contact [[KeithPackard|KeithPackard]]. +[[!table header="no" class="mointable" data=""" + **Project** | **Type** | **Description** | **Diff / Size** | **Comp.** + Gamma | design / code | Render needs design and implementation of gamma correction functionality | Mod. / Small | 0% + Render Library Spec | doc | Write specification of the Render Extension C library binding | Easy / Small | 0% + Render Wire Encoding Spec | doc | Write wire encoding specification from the C implementation | Easy / Small | 0% + DDX work | code | Implement Render acceleration in various drivers (DDX's). In fact, while we are doing prototyping in the kdrive framework, we expect much of this will come out in the wash in a OpenGL based ddx. | Mod. / Mod. | 20% + Test Suite | code | Implement test suite for Render. This is important both for testing and performance. x11perf also needs tests for each new primitive. The real problem implementing render acceleration is the lack of a performance and compliance test suite. Driver writers find it difficult to implement things that they don't have easy tests for. As for compliance, there is a problem. Pretty much no hardware is going to be able to do the "precise" rendering, so correctness tests may be more or less visual when render is used in imprecise mode. That is, compare a rendered image with a reference to make sure they are subjectively the same, or within the specification's tolerances (if we succeed in quantifying imprecise mode) | Mod. / Mod | 0% +"""]] + + +### Fontconfig + +Fontconfig is a (non-X dependent) library used for font discovery, name substitution, etc. + +While mostly complete, there are a few remaining projects left on its [[Fontconfig To Do List|Software/fontconfig/ToDo]]. + + +### Xft + +Xft is a library used for anti-aliased font rendering that does not use the old X core fonts, using the [[Freetype|Software/FreeType]] font rendering library. + +While mostly complete, there are a few remaining projects left on its [[Xft To Do List|Software/XftToDo]]. + + +### RandR + +The X Resize, Rotate and Refresh Rate extension has a few details left. RandR provides facilities for resize, rotation, and refresh rate changing of X screens. This is needed for good support on laptops, for migration of applications, and for dynamic changes of depths. A version without rotation support is in XFree86; kdrive has full support. We hope/expect that only upward compatible changes, if any, will be needed from here on out, but there is insufficient implementation experience to claim that incompatible change would never occur. + +In particular: +[[!table header="no" class="mointable" data=""" + **Project** | **Type** | **Description** | **Diff / Size** | **Contact** | **Comp.** + RandR doc | doc | The RandR wire encoding spec needs to be derived from the C implementation. | easy / small | Main.[[JimGettys|JimGettys]] | 0% + RandR ddx | code | RandR rotation is not implemented in some DDX's. The difficulty will depend on which DDX. | mod.? / small | Main.[[JimGettys|JimGettys]] | 30% + RandR speed | code | Some DDX implementations could be made much faster if need be, so that shadow frame buffers aren't necessarily always in use or in the graphics fast path. | mod.? / mod.? | Main.[[KeithPackard|KeithPackard]] | 0% +"""]] + + +### Cairo + +Cairo is a vector graphics library with cross-device output support. It targets a number of back ends, including the X Window System, Microsoft Windows, Postscript and others are planned. It is well underway and usable for many purposes already. There are many [[fun projects left to do|http://cairographics.org/todo]] for those with the interest and talents. + + +### DRI - Direct Rendering Infrastructure and Mesa + +If working on display hardware, or working on a free OpenGL 3D graphics library is your cup of tea, there is always fun work to be done on [[DRI and Mesa|Software/dri]]. + + +### vaAPI - Video Acceleration API + +Proposal for a hardware agnostic interface specification that allows video codec developers to write to a standard set of APIs and supports any common video compression format. The API does not constrain how the actual decode is implemented... decode may be done by CPU, by specialized video decode engines, or by 3D engines. Currently looking for feedback on the specification; see the [[vaAPI|Software/vaapi]] page for the full spec. + + +### X Protocol Libraries + +Since the inception of the X Window System, Xlib was the production X Window System protocol and utility library. An older list of Xlib [[projects|Software/XlibToDoList]] is here. However, a newer project known as [[XCB|http://xcb.freedesktop.org]] is well on the way to replacing Xlib, and most Xlib development is currently being done in the context of XCB. There's a great deal of interesting work remaining with XCB, and folks are encouraged to join the effort. + + +### Convert Documentation + +Most of the base documentation for the X Window System is written in troff, and occasionally other text formatting systems. Most open source systems are moving to [[Docbook|http://freshmeat.net/projects/docbook/]] as a modern unifying representation from which to generate manual pages, manuals, books and other documentation in whatever presentation form is most convenient, from man, to postscript, to html. + +The [[doclifter|http://www.catb.org/~esr/doclifter/]] program makes it feasible to convert most troff documents with little or no manual editing required for most documents. Other formats may require other tools. This is probably done best in collaboration with the maintainer of the particular module; the effort is not much on a per document basis for the mechanical part of the translation, but proofreading is a significant effort, and there is a lot of documentation to convert over all. + + +### Translation + +Both program strings and documentation need translation into your favorite language. + + +### Modularization and Autotooling + +The X Window System has been split into modular components and converted from Imake to autoconf. The first release under this new system was done in 2005 as [[X11R7|X11R7]].0 but more work is needed to finish the conversion. Documentation for each module such as AUTHORS, [[ChangeLog|ChangeLog]], and COPYING files need to be created and pre-7.0 information incorporated. Linux and Solaris on x86/x64 were fully ported for the 7.0 release, and BSD & Darwin mostly ported, but work needs to be done to ensure the modules build and run on other OS'es/platforms. [[The X.Org Modular Developers Guide|http://wiki.x.org/wiki/ModularDevelopersGuide]] has more info. + + +### Synchronization + +The X Window System has had for years facilities for very tight synchronization of multimedia or other X clients using the XSync extension; but the Linux and *BSD implementations have only had real-time counters defined. Linux device driver work, in concert with small amounts of glue in the X implementation would extend this to audio devices and vertical retrace. Alan Cox started on driver framework for Linux during the summer of 2003, and Robert Love is planning to continue this work. [[JimGettys|JimGettys]] was one of the original designers of XSync and is happy to consult on this project. The driver framework should not be difficult for an experienced kernel driver person, and minor changes in appropriate drivers will need to be made. + + +### Color + +Free desktops need good end to end color management, from input devices, to calibration of screens, to printing. [[JimGettys|JimGettys]] is trying to coalesce work in this area. The facilities in Xlib for color management are at best inadequate, and at worse, completely useless. We know the existing CMS is essentially unused by applications, as it was broken for many months in CVS without anyone noticing. [[[OpenIcc|OpenIcc]]] is a list dedicated to discussing specs and configuration issues. + + +### Oyranos + +[[Oyranos|http://www.oyranos.org]] is a Colour Management System (CMS) on operating system level. It allows applications and users to match predictably input device colours to output device colours. To do so in a consistent manner, applications and workflows need to support the Oyranos CMS. Oyranos is based one the well established ICC standard and various other specifications. System wide settings in Oyranos shall enshure consistency in a portable fashion. Oyranos will provide in the future a advanced Colour Matching Module (CMM) framework. Users can then transparently select a desired colour engine. + +Development plans and open tasks can be found [[here|http://www.oyranos.org/wiki/index.php?title=Oyranos#Development]]. contact: [[KaiUweBehrmann|KaiUweBehrmann]] + + +### Cut and Paste + +The [[http://www.x.org/wiki/CutAndPaste|http://www.x.org/wiki/CutAndPaste]] project is intended to tackle and resolve the 20-year-old issues inherent in X Cut and Paste. It is not yet particularly underway, but hopes to be soon. The email list at [[cut-and-paste@lists.freedesktop.org|mailto:cut-and-paste@lists.freedesktop.org]] is one venue for this work. This is a [[BartMassey|BartMassey]] inspiration, but he hasn't had much time to work on it since announcing it some time ago. + + +## Projects Not Yet Underway + + +## Infrastructure Projects + +Additions to the Freedesktop.org infrastructure to enhance collaboration are always welcome, so long as you intend to maintain the facilities. The sitewranglers at freedesktop.org mailing list is used for discussions. +[[!table header="no" class="mointable" data=""" + **Project** | **Type** | **Description** | **Diff / Size** | **Comp.** + Tinderbox | web | Freedesktop.org has a very similar problem to Mozilla: our software is very cross platform, and it is not uncommon that people check in code that can break a build on a system they do not have access to. The [[tinderbox|Software/TinderboxWiki]] allows continuous testing of builds on various platforms. At this point we need more machines on different platforms running the tinderbox script.. | easy / easy | 80% + News | web | Freedesktop needs an easy way to post news, and that should probably be gatewayed to a mailing list. | easy / easy | 0% + CIA | web | Installing a IRC spy bot watching appropriate CVS repositories and reporting the check ins to appropriate IRC channels. | easy / easy | 100% +"""]] + +-- Main.[[JimGettys|JimGettys]] - 12 Feb 2004 diff --git a/FriscoRose.mdwn b/FriscoRose.mdwn new file mode 100644 index 00000000..ee77571f --- /dev/null +++ b/FriscoRose.mdwn @@ -0,0 +1,17 @@ + + +## Your Name + +Frisco Rose + +My site is [[http://butsuri.homelinux.net|http://butsuri.homelinux.net]] + +Email: FriscoRose AT SPAMFREE GMail DOT com + +... + + + +--- + + [[CategoryHomepage|CategoryHomepage]] diff --git a/GettingInvolved.mdwn b/GettingInvolved.mdwn new file mode 100644 index 00000000..99a216a8 --- /dev/null +++ b/GettingInvolved.mdwn @@ -0,0 +1,64 @@ +## Getting Involved in freedesktop.org + +freedesktop.org is always looking for more involvement. Remember that freedesktop.org is a project for developers interested in working on shared desktop code, specifications, or documentation. + +<a name="MailingLists"></a> +### Mailing Lists + +If you're interested in working on specifications, the best way to get started is to join our mailing list; mail [[xdg-request@lists.freedesktop.org|mailto:xdg-request@lists.freedesktop.org]] with the word "subscribe" in the subject of your email. xdg-list has archives and on-the-web subscription [[here|http://lists.freedesktop.org/mailman/listinfo/xdg]]. + +For other mailing lists and archives, go [[here|http://lists.freedesktop.org/mailman/listinfo]]. + +Again, because this is important: XDG is not a diplomacy project, we want to actually work on specifications rather than discussing what the specifications could contain. Whenever possible, discussion on xdg should focus on a concrete _draft specification_ or _existing code_. It's best to post a draft of a document, or go ahead and code something up, rather than asking for comments on an abstract topic. + +For general freedesktop.org discussion, please mail [[freedesktop@lists.freedesktop.org|mailto:freedesktop@lists.freedesktop.org]]. + + +### Source Code: Subversion + +A few FD.o projects use Subversion as their revision control system. Developer access is possible using <svn+ssh://<user>@svn.freedesktop.org/svn/<project>>. And then there's WebSVN, too at <http://websvn.freedesktop.org/>. TODO: is there anonsvn available at all? + +<a name="GIT"></a> +### Source Code: Git + +Several X.org projects have been moved to the git revision control system. See [[UsingGit|UsingGit]] for more information on using git. + +Read-only [[Git|http://git.or.cz/]] repositories are hosted at <git://git.freedesktop.org> Each project may create a repository on git.freedesktop.org in `/srv/git.freedesktop.org` using `GIT_DIR=/srv/git.freedesktop.org/{project}.git git-init-db` and then they can push commits to that tree with git-push. + +<a name="CVS"></a> +### Source Code: CVS + +Anonymous CVS is available from: + + cvs -d:pserver:anoncvs@anoncvs.freedesktop.org:/cvs/<project> login + cvs -d:pserver:anoncvs@anoncvs.freedesktop.org:/cvs/<project> co <module> + +You can browse the modules via web at [[http://webcvs.freedesktop.org|http://webcvs.freedesktop.org]]. + +**Beware**: for projects that have moved to git, the source code in CVS is out of date. + +CVS commits can be monitored on a per-project basis. See the project's page for more info. + +See [[UsingCvs]] for help with developer CVS access. Check out the [[MAINTAINERS|http://webcvs.freedesktop.org/xorg/doc/xorg-docs/MAINTAINERS?view=markup]] list for information about which lists or which people to contact about a given piece of software. + +If you have some code that may be of cross-desktop interest, we're happy to host it on our CVS server, and you may want to bring it up for discussion on xdg-list. Mail [[the fd.o admins|mailto:sitewranglers@lists.freedesktop.org]] with requests for CVS access; be sure to include a pointer to the work you want to put in CVS. + +<a name="Bugzilla"></a> +### Bugzilla + +The freedesktop.org bugzilla can be found on <http://bugs.freedesktop.org>. + +<a name="Translations"></a> +### Translations + +See the [[Translations]] page to find out where you can contribute translations for some freedesktop.org packages. + +<a name="IRC"></a> +### IRC + +Join us on #freedesktop on [[freenode|http://freenode.net/]]. + +<a name="Wiki"></a> +### Wiki + +Active work on this website is found at [[RecentChanges]]. Work to be done on the website can be found in [[WantedPages]] and [[OrphanedPages]]. diff --git a/HarfBuzz.mdwn b/HarfBuzz.mdwn new file mode 100644 index 00000000..b3f374f0 --- /dev/null +++ b/HarfBuzz.mdwn @@ -0,0 +1,6 @@ + +[[HarfBuzz|Software/HarfBuzz]] (حرفباز) is _my_ Persian translation of "[[OpenType|http://www.microsoft.com/typography/otspec/]]", transliterated using the Latin script. It sports a second meaning, but that ain't translatable. + +Background: Originally there was this font format called TrueType. People and companies started calling their type engines all things ending in Type: FreeType, CoolType, ClearType, etc. And then came OpenType, which is the successor of TrueType. So, for my OpenType implementation, I decided to stick with the concept but use the Persian translation. Which is fitting given that Persian is written in the Arabic script, and OpenType is an extension of TrueType that adds support for complex script rendering, and HarfBuzz is an implementation of OpenType complex text shaping. + +Not to be confused with [[HarzBuff|HarzBuff]]! diff --git a/HarfBuzz/HarfBuzz b/HarfBuzz/HarfBuzz Binary files differnew file mode 100644 index 00000000..052f6cae --- /dev/null +++ b/HarfBuzz/HarfBuzz diff --git a/HarzBuff.mdwn b/HarzBuff.mdwn new file mode 100644 index 00000000..1c3365b1 --- /dev/null +++ b/HarzBuff.mdwn @@ -0,0 +1,2 @@ + +spam diff --git a/HdrRenderingDescription.mdwn b/HdrRenderingDescription.mdwn new file mode 100644 index 00000000..3e9c9d0f --- /dev/null +++ b/HdrRenderingDescription.mdwn @@ -0,0 +1,39 @@ + +High Dynamic Range (HDR) images must be converted to Low Dynamic Range (LDR) to display properly on print media and traditional TV's and Monitors. For better prediction of the colour appearance, a way to describe the algorithm used on the authors side seems desirable. With such a description a viewer can display the HDR content accordingly to the remote media capabilities. + +[[!toc 2]] + + +# Links + + +## Algorithms + +* [[Reinhard|http://www.cs.utah.edu/~reinhard/cdrom/source.html]] C +* [[iCAM|http://www.cis.rit.edu/mcsl/icam/hdr/]] +* [[Fast Bilateral Filtering|http://people.csail.mit.edu/fredo/PUBLI/Siggraph2002/]] +* [[A Visibility Matching Tone Reproduction Operator for High Dynamic Range Scenes|http://www.anyhere.com/gward/pixformat/Larsonetal.html]] G.W.Larson + * [[Radiance package|http://www.radiance-online.org/]] +* some more can be found on the wikipedia tonemapping link below + +## Articles + +* [[Tonemapping|http://en.wikipedia.org/wiki/Tone_mapping]] +* [[HDRI|http://en.wikipedia.org/wiki/High_dynamic_range_imaging]] +* [[HDRR|http://en.wikipedia.org/wiki/High_dynamic_range_rendering]] +* [[Shaders|http://en.wikipedia.org/wiki/Shading_language]] +* HDSL/Cg ... +* [[Greg Ward's site|http://www.anyhere.com/gward/]] not to forget +* [[Tonemapping operator overview|http://dativ.at/logmap/]] +* [[Evaluation of tone mapping operators|http://moon.felk.cvut.cz/~cadikm/tmo/]] at CTU in Prague + +## Related Projects + +* [[OpenIccForGoogleSoC2007|OpenIccForGoogleSoC2007]] +* [[exrtools|http://scanline.ca/exrtools/]] C++ +* [[OpenEXR|http://www.openexr.com]] C++ +* [[pfstmo|http://www.mpii.mpg.de/resources/tmo/]] C++ +* [[Qtpfsgui|http://qtpfsgui.sourceforge.net/]] C++ +* [[Programming links|http://people.csail.mit.edu/sparis/#code]] + +-> back to [[OpenIcc|OpenIcc]] diff --git a/HomepageTemplate.mdwn b/HomepageTemplate.mdwn new file mode 100644 index 00000000..a4d3e378 --- /dev/null +++ b/HomepageTemplate.mdwn @@ -0,0 +1,13 @@ + + +## Your Name + +Email: you AT SPAMFREE example DOT com + +... + + + +--- + + [[CategoryHomepage|CategoryHomepage]] diff --git a/IccGreyObjects.mdwn b/IccGreyObjects.mdwn new file mode 100644 index 00000000..40b80ece --- /dev/null +++ b/IccGreyObjects.mdwn @@ -0,0 +1,46 @@ + + +# Better handling of grey objects in ICC workflows for the graphic arts + + +## Which realworld usecases are adressed + +Problems concerning grey objcts in ICC workflows are especially connected with colormanagement of images or complete documents targeting CMYK printing processes. In most cases grey objects are either ignored in the colormanagement workflow or they are converted through the PCS to CMYK. In the very most cases, users are expecting grey objects to be converted to the black channel only of the CMYK printing process. + + +## which kind of applications are targeted + +* layout applications +* vectorgraphic applications +* imaging applications +* pdf workflow applications +* digital asset management +* content management systems with output for printing + +## how should it be implemented technically + +If data from different sources is converted trough the source-profile to the PCS (mostly CIE L*a*b*), the CMM doesn´t know if the source colorspace was e.g. RGB, CMYK or Grey. Firstly, we need a mechanism, which tells the CMM, that the actual data converted to the PCS was original a Grey file. Second, we need a mechanism, that the CMM is able to calculate temporarly a greyscale-profile from the blackplate of the destination CMYK-profile. If the data in the PCS colorspace is tagged as Grey, the conversion to the destination-colorspace should be done with the temporarly calculated greyscale-profile instead of the CMYK-destination profile. + + +## how should it be implemented in the user interface + +In most cases, such options could be implemented in the menue specifying the destination colorspace for a colortransformation. Good naming would be: + +* convert grey objects only to the black channel +In many cases, grey objects have no embbeded profiles. If such objects are placed in a CMYK-document, the user expects grey objects to handled like the black channel of the CMYK document-space. In this case it would be helpful, if the colorsettings for the document have a menue with two options concerning grey objects: + +* preserve embedded greyscale profiles +* keep grey objects without embedded profiles like the black channel of the CMYK documentspace. +If greyscale objects without embedded profiles are converted to the destinationspace, following things should happen: - a greyscale profile is temporarly calculated from the document CMYK-colorspace - The greyscale object is tagged with the temporarly grey document colorspace - After been transformed to the PCS the object has an tag to be original a greyscale object - Being transformed to the destination colorspace, the temporarly calculated destination-greyscale profile is used. + + +## comments from ICC members + +The statement that in most cases users are expecting grey objects to be converted to the black channel of the CMYK printing process is certainly correct. The method proposed is one possible approach. Enhancements to this basic method can be considered for certain types of grey objects. For example, the tonescale contrast of greyscale raster images may need to perform differently than the black channel of a particular CMYK profile. Ann [[McCarthy|McCarthy]], ICC Workflow WG Chair [note that these comments do not represent a statement of the ICC] + + +## implementations in Open Source solutions + +not yet available + +Back to [[OpenIcc|OpenIcc]] diff --git a/Infrastructure/git.mdwn b/Infrastructure/git.mdwn new file mode 100644 index 00000000..13e74cd7 --- /dev/null +++ b/Infrastructure/git.mdwn @@ -0,0 +1,41 @@ + + +## Users + +Information for users who want to check out repositories and use them to build code and isolate bugs can find more information on [[the users page|Infrastructure/git/Users]]. + + +## Developers + +Information for developers who want to commit code and push and/or send patches can be found on [[the developers page|Infrastructure/git/Developers]]. + +Owen Taylor has created a tool for integrating git and bugzilla updates. Documentation is [[provided with the tool|http://git.fishsoup.net/cgit/git-bz/tree/git-bz.txt]] and it has been further described in Owen's blog: [[git-bz: Bugzilla subcommand for Git|http://blog.fishsoup.net/2008/11/16/git-bz-bugzilla-subcommand-for-git/]], [[git bz push|http://blog.fishsoup.net/2009/09/05/git-bz-push/]]. + + +## Creating your own repository + +Please see the [[repository admin page|Infrastructure/git/RepositoryAdmin]]. + + +## cia.vc integration + +If you want your notifications on IRC, we support integration with CIA.vc. File a ticket to have your hook scripts updated, and make sure to tell us what the cia.vc project name is. + + +## Migration from CVS + +Instructions on [[migrating from CVS|Infrastructure/git/Migration]] are available. + + +## Wishlist + +We are also maintaining a rough wishlist of what we'd like to see [[changed in git|Infrastructure/git/UIFlaws]]. + + +## More Resources + +More documentation for both users and developers can be found at these sites: + +* [[GitWiki: Git Documentation|http://git.or.cz/gitwiki/GitDocumentation]] +* [[The Git Community Book|http://book.git-scm.com/]] +* [[The Git Parable|http://tom.preston-werner.com/2009/05/19/the-git-parable.html]]
\ No newline at end of file diff --git a/Infrastructure/git/Developers.mdwn b/Infrastructure/git/Developers.mdwn new file mode 100644 index 00000000..29d9f240 --- /dev/null +++ b/Infrastructure/git/Developers.mdwn @@ -0,0 +1,152 @@ +Several projects have been moved to the git revision control system. While there exist tutorials out there for using git, one of git's features is that it allows people to use many different workflows, so many of those tutorials won't apply to git as it's used in X.Org projects. We might call what we usually do "shared central repository" mode. + +Things which are within the scope of this document: + +* Checking out code +* Committing code +* Resolving conflicts +* Working on branches +Things which are not within the scope of this document: + +* Using the index for selective committing +First note about git: there are many commands. Each command exists as an argument to the git command (`git clone`) and also as a hyphenated version to aid in tab-completion ("git-clone"). + +The next thing to understand is that when you check out code from a remote git repository, you end up with a full-fledged git repository yourself. When you diff, commit, etc. code, you are doing it against your local repository. Clone, pull, and push are used to move changes between repositories. Your local repository is stored in the .git directory at the top of the tree. + + +## Checking out + +If you have an anonymously-checked out repository which you now wish to use to push, you can edit `.git/remotes/origin` and replace the contents of the `URL: ` line (change `git://` to `ssh://`, and `anongit.freedesktop.org` to `git.freedesktop.org`). + +If your username at freedesktop.org is different from local, the refspec becomes `ssh://myusername@git.freedesktop.org/git/xorg/lib/libX11`, or you can just add the following to `~/.ssh/config` to tell ssh your default username for all of freedesktop.org: + + Host *.freedesktop.org + User myusername + +## Viewing diffs + +Now, you have a copy of the master branch of the tree. Go ahead and build it and whatever else. If you make some changes, you can see what files you would commit with `git status -a` or get a diff of the local tree against the repository with ` git status -a -v` + +The `-a` flag means all local updates. The git system actually has this concept of an "index", managed using `git-update-index`, which lets you selectively commit changes. However, because this adds to confusion, I will leave learning about the index up to you to do later. + + +## Getting the latest upstream code + +There are two ways to update your local repository. Which one to use depends on whether you have committed changes in the meantime. + + +### No changes: pull + +The command to update your local repository is: + + git pull + +It will pull down the latest repository information from the `origin` remote file (which points at where you initially cloned the repository from), then merge. If the new changes don't conflict with anything locally, the merge will "fast-forward" your branch reference to the new head. If new changes do conflict, it will try to do an automatic merge using a couple of different schemes, and then automatically commits the merge if it's satisfied. If you notice that your pull resulted in a merge (in the output of pull), you might want to use `gitk` to see if the merge did what you expected it to. If it isn't satisfied, then you have to resolve the conflict manually. + + +### You've made changes: fetch and rebase + +If you have committed local changes, then `git-pull` will create a spurious "Merge" commit, which will pollute the change list when you later push upstream. To avoid this, do these two commands: + + git fetch + git rebase origin + +Instead of merging, this attempts to insert the changes you pull from the origin repository before your local changes, avoiding the merge message. + + +## Dealing with conflicts + +If you get a serious conflict that can't be merged automatically, git will leave familiar conflict markers in the files, and `git status` should say that you've got unmerged files. Go edit them and fix your conflicts, and test. After you do so, `git status` will still be noisy about unmerged files (since you haven't updated the index to say you've merged them), but you can still do + + git commit -a + +and commit your merge. It hands you a default log message for the merge, and it will retain the information on the parents of the commit you did, so that branch history is maintained. + + +## Reverting commits + +It may happen that you commit something you really didn't want to go into the repository. This is not referring to broken changes, but things like mis-merges or getting branches confused. If you haven't pushed the code upstream, then it's really easy to make it look like the commit didn't happen. To reset to the immediate previous revision, you would run: + + git reset --hard HEAD^ + + +## Reverting code prior to commit + +git doesn't have a revert command like svn. Instead, just run `git checkout -- <yourfile>` to revert it to the last committed version. The `--` isn't necessary in most cases, but does provide extra insurance. + + +## Committing code + +If you're satisfied with your diff, you could commit it with: `git commit -a` + +The commit message should have a one-line summary ('Add support for FooBazzle 700'), and then a longer explanatory paragraph, separated by a blank line, e.g.: + + Add support for FooBazzle 700 + + Add support for the FooBazzle 700, which is an interesting device in + that it does not actually exist. This is our first driver for an + entirely ficticious device, and as such, it performs no rendering. + +Your subject line should include the subsystem name (for example, 'KDrive: Fix keymap memory leak', not just 'Fix leak'), unless it's entirely redundant. + +After you enter your log message, it will quickly terminate. You've now committed your diff to your local repository. You could run: + + gitk + +to see your diff in the history now. Note that the `gitk` output actually shows two branches: master and origin. The `master` branch is the head of development in the local tree. The `origin` branch is the last version from upstream. + + +## Pushing your code upstream + +Now that you've resolved the conflicts (if any) with others upstream, you're ready to push your changes. To do this, type + + git push origin + +This tells git to push every branch in a `Push:` line in the `origin` remote upstream (more on the Push: lines later). Unlike `git pull`, `git push` does require you to specify the remote and doesn't have a default. + + +## Emailing your code upstream + +If you do not have direct commit access or wish to get patch review, type: `git format-patch origin` (assuming you're on master) + +This will generate a few sequentially-numbered text files, one per patch (e.g. `0001-Add-support-for-FooBazzle-700.txt`, `0002-Fix-memory-leak.txt`), in mbox format. These can be sent individually. If part of a series, use the `-n` argument to `git format-patch`, so their subjects will be '[PATCH 1/7] Add support for FooBazzle 700', and so on, and so forth. + +Traditionally, a '[PATCH 0/7] FooBazzle-related enhancements' mail would be sent to the list first, giving a relatively long explanation of the patchset, as well as a very brief rundown of the individual patches. You should then edit your patches before you send them, to include an `In-Reply-To` and `References` header listing the `Message-Id` of the 0th message, so it doesn't break threading. + + +## Working on branches + +Now you've learned how to check out HEAD code, diff, update, commit, and push code back upstream. The next thing to talk about is branching. + +You can see what branch you're on using `git branch` -- it should show `master` initially. To switch branches in your current repository, do: + + git checkout <branch> + +If you've got local changes, there are flags to either throw out your local changes, or try to merge them across to the new branch. By default it will just refuse to change. + +If you want to make a new branch, you can do: + + git checkout -b <new-branch> + +Now you've got a new branch. However, git checkout doesn't set up the branch: branch-origin mapping that we want. There's a rule in using git, which is: **Never commit to the right side of a Pull line**. This is referring to the contents of `.git/remotes/<remotename>`. The `.git/remotes/origin` (what you're using currently) file should currently have: + + URL: git://anongit.freedesktop.org/git/whatever + Pull: master:origin + +This means that the current remote master is mapped to the local origin. When working on a branch where you'll be committing code, add a few more lines: + + Push: master:master + Pull: new-branch:new-branch-origin + Push: new-branch:new-branch + +The first says "map the remote new-branch to new-branch-origin in the local repository". The second says "when pushing code, push from new-branch locally into new-branch remotely". If you haven't set any `Push:` lines, then git implies a `master:master` mapping for pushes. Once we add our new-branch push line, we also have to add `master:master` if you intend to ever commit to master. + +Now, you're set up for committing and pushing the branch. There's one more trick to know about. When you do `git pull`, it is now pulling the remote branches into what they're mapped to locally. So, the latest new-branch upstream code is in new-branch-origin. To merge it to your local new-branch code, do: + + git pull . new-branch-origin + +This means "merge the new-branch-origin code into the current working directory". Like the other `git pull` command we mentioned, it will by default commit the merge, unless it runs into conflicts which aren't automatically resolvable. + +And, to push, you do it just like when you were working on master. + + git push origin diff --git a/Infrastructure/git/Migration.mdwn b/Infrastructure/git/Migration.mdwn new file mode 100644 index 00000000..891b0e73 --- /dev/null +++ b/Infrastructure/git/Migration.mdwn @@ -0,0 +1,53 @@ +## Migrating a CVS module to Git. + +This page provides some instructions on how to migrate a module from CVS to git using the parsecvs utility (which desperately needs UI work). + + +### Prepare the community + +The first thing to do is pick a reasonable time to make the transition. A week before a major release of either X.org or the module itself is probably not the best plan. With a timeframe in mind, coordinate with other major maintainers of the module and select a target date. Send mail to your mailing list announcing your intention and include the proposed schedule. You should also remind developers of the expected sequence of events so no-one is surprised (or at least the surprise will be their fault for skipping over your carefully delivered email). Here's the usual sequence of events: + +1. Send migration warning email (this mail) +1. Wait for selected date +1. Make the CVS tree read-only +1. Convert the tree using parsecvs +1. Stick warning signs in CVS +1. Push exported tree to kemper + +### Make CVS tree read-only + +Ask an admin to make the CVS tree read-only on kemper, and make you a tarball of the repository. + + +### Convert tree using parsecvs + +OK, this tool is primitive, but handles our broken CVS bits better than git-cvsimport. + +1. Ensure edit-change-log (from parsecvs) is in your path. This script takes [[ChangeLog|ChangeLog]]-style commit messages and converts them to plain text. +1. Create a directory for the module, cd to it. +1. Create an Authors file, similar to xorg-Authors in the parsecvs tree. +1. Run the import process: + * find cvsrepodir/ -name '*,v' | parsecvs +1. Verify the results + * gitk --all + * git-checkout master + * diff -r . <checkout of CVS head> +1. Prepare the git tree for publication + * chmod +x .git/hooks/post-update + * fix up the update hook, chmod +x .git/hooks/update + +### Stick warning signs in CVS + +1. Edit configure.ac in the CVS version, adding this just before the final AC_OUTPUT call: + + AC_MSG_ERROR([The $module is now maintained at:] + [ git://git.freedesktop.org/git/reponame] + [Please use that repository.] + +1. Temporarily make CVS writeable +1. Commit change + +### Export git tree + +1. Get the admins to create a [[new git repository|Infrastructure/git/RepositoryAdmin]] for you. +1. `git push --force --all ssh://git.freedesktop.org/git/reponame` diff --git a/Infrastructure/git/RepositoryAdmin.mdwn b/Infrastructure/git/RepositoryAdmin.mdwn new file mode 100644 index 00000000..845be76e --- /dev/null +++ b/Infrastructure/git/RepositoryAdmin.mdwn @@ -0,0 +1,28 @@ +Repositories on fd.o take two forms: project repositories (e.g. dbus, cairo), and personal user repositories, which may contain anything. Project repositories are only available to projects already hosted on freedesktop.org. + + +## Projects + +If you want a 'project' repository on fd.o, file a bug with [[Bugzilla|http://bugs.freedesktop.org/enter_bug.cgi?product=freedesktop.org]] requesting a new repository and including the information described in [[NewProject|http://www.freedesktop.org/wiki/NewProject]]. If you want commit notifications, please also state that, and let us know where they should go to. + +Conversion using the parsecvs tool is also available: this has converted the X.Org, Cairo and XCB repositories, among others, mostly without incident. + +Your repository will be available as `ssh://git.freedesktop.org/git/projectname` for commit access, and `git://anongit.freedesktop.org/git/projectname` for anonymous access. + + +## Personal repositories + +For personal repositories, SSH to people.freedesktop.org and execute: + + git --git-dir=repo-name.git init + cd repo-name.git + touch git-daemon-export-ok + vim description + mv hooks/post-update.sample hooks/post-update + chmod +x hooks/post-update + +You can now push into it from your local repository with: `git push --force --all ssh://people.freedesktop.org/~username/repo-name` + +and it will be available from `git://people.freedesktop.org/~username/repo-name`; it will take up to one hour to be visible on cgit. + +To add the new repository as a remote, on your local machine run `git remote add fdo ssh://people.freedesktop.org/~username/repo-name`. You can then push to it with `git push fdo branchname`. diff --git a/Infrastructure/git/UIFlaws.mdwn b/Infrastructure/git/UIFlaws.mdwn new file mode 100644 index 00000000..2a53c9d7 --- /dev/null +++ b/Infrastructure/git/UIFlaws.mdwn @@ -0,0 +1,20 @@ + +This page attempts to document the most egregious git UI offenses, in the hope that they'll get fixed someday. + +Update: Since this page was created Git has come a long way. All of the issues listed have been addressed and this page should probably be retired. + +* There is no way to tell `git-fetch` (or therefore `git-pull`) to grab all newly available branches. You have to ask for them by two names (as above), and then there's no way to get those names automatically into your remotes list (also as above). _Solved: git remote update_ +* `git pull`'s default behaviour on a branch is unhelpful: even when there is an explicit Pull: branch1:branch1 line, a `git pull` with branch1 checked out will still pull in master. _Solved: the "merge" variable in the config holds which branch to merge by default_ +* `git-fetch` requires that the branch be named on both sides of the :. It should treat `foo` as an alias for `foo:foo`. _Solved: the config now holds the associated remote to fetch by default_ +* `git-revert` will refuse to back out multi-parent commits, ie, merges. The obvious behaviour is to do basically what `git-show [commit] | patch -p1 -R` would do, ie, roll back the tree state to the branch you came from. _Solved: git revert -m1_ +* The command to merge branch B onto branch A is not `git-merge A B`. Instead it's `git-checkout A && git-pull . B`. _Solved: The documentation now makes it clear that you can only merge with checked out branch, eg. git checkout A && git merge B_ +* branch:branch-origin (or something) should be the default pull. _Solved: config holds which branch to fetch and merge for each local branch_ +* `git-rebase` claims you should `git-rebase --continue` after you fix up the merges; it really means you should `git-update-index` followed by `git-rebase --continue`. _Solved: User is informed of proper steps (git add, etc)_ +* branch:branch should be the default push for all branches, but only push the current branch unless a flag is added. _Solved: the config holds a mapping of local branch name to remote branch name so there is no need to give it on command line_ +* `git-rebase foo` is a noop, when foo is the name of local branch. You would expect it to fetch the branch named foo from upstream, and rebase your foo branch on top of it. _Solved: Documentation makes it clear that Git is designed to work offline; users should not expect network activity for local operations_ +* An update command should be created that: _Solved: git pull --no-commit performs the operations as outlined below_ + * fetches the current branch's upstream to its -origin locally (or all branches, perhaps); + * merges the current branch origin to the branch locally; + * commits if it was a fast-forward, and leaves uncommitted diffs otherwise. +* Fundamentally, the entire approach of making the UI painful to deal with and forcing the user to deal with all the warts (instead of just making the hairy low-level commands available), because people will write nice wrappers around it, is the same reason people laughed at tla, and still do. _Solved: Fundamentally this wasn't ever a problem, but Git is now just a single command "git" with sub-commands_ +* The index should be second-class, i.e. no -a flags to avoid the index. _Solved: Documentation is more clear now. Users can choose one of many GUI's and avoid command line altogether if they find -a hard to type_
\ No newline at end of file diff --git a/Infrastructure/git/Users.mdwn b/Infrastructure/git/Users.mdwn new file mode 100644 index 00000000..0ea0a5cd --- /dev/null +++ b/Infrastructure/git/Users.mdwn @@ -0,0 +1,50 @@ + +This is about one-way use of git. For information on committing, merging, and pushing, please see [[the developers page|Infrastructure/git/Developers]]. + +Also note the [[documentation on the git wiki|http://git.or.cz/gitwiki/GitDocumentation]]. + + +## Checking out a repository + +To check out any project repository on fd.o, run: `git clone git://anongit.freedesktop.org/git/name`, e.g. `git://anongit.freedesktop.org/git/cairo`. A full list of projects is available on [[cgit|http://cgit.freedesktop.org]]. + +To switch to a particular branch, use `git checkout branchname`; a list of branches is available with `git branch`. If you want to use a particular tag, use `git checkout -b temp tagname`, e.g. `git checkout -b temp xorg-server-1.1.99.3`. A list of tags is available with `git tag -l`. + +`git checkout master` will return to the main development branch ('trunk'). + + +## Keeping up to date + +`git pull` will download the latest changes. Note that if you are on a branch, then you should type `git pull origin branchname:branchname`, otherwise you will merge the master branch, instead of simply keeping your current branch up to date. + + +## Basic repository information + +`git log` will give you a list of all changes. To see changes since a particular version, or between a particular version, use `version1..version2` as an argument; if version1 is unspecified (i.e. `..version2`), it is assumed as the first revision. Conversely, if version2 is unspecified (i.e. `version1..`), it is assumed as the current revision (not necessarily the most recent in the repository, but the one you currently have checked out). Examples: + +* `git log xorg-server-1.2.0..` â changes since xorg-server 1.2.0 +* `git log ..xorg-server-1.2.0` â changes up until xorg-server 1.2.0 +* `git log xorg-server-1.2.0..xorg-server-1.2.1` â changes between xorg-server 1.2.0 and 1.2.1 +To examine a particular revision, including the diff, run `git show commitid`. The commit ID does not have to be the full SHA1 sum, but only enough to be unambiguous; the first 6 characters are usually sufficient. + + +## CVS cheat sheet + +* cvs checkout: `git clone` +* cvs status: `git status` +* cvs diff: `git diff -a` +* cvs update: `git pull` (with caveats) + +## Bisecting + +Bisecting allows you to determine which commit introduced breakage, by iterative testing. As an example, assume that the code worked one month ago, and now segfaults. + +First, run git log, to determine where you want to roll back to. If it worked one month ago, say five weeks to be safe. Find the sha1 sum of the commit where you think things last worked. Take note of this (say it's 123456...). + +`git bisect start` â start the process `git bisect bad` â the current revision is broken `git bisect good 123456` â the revision starting with 123456 works + +You will get output something like: `Bisecting: 297 revisions left to test after this` + +Run make, and check if it works. If it works, type `git bisect good`, else `git bisect bad`. This will give you a new revision to try: run make, check if it works, and type bad/good, accordingly. + +If you are unable to compile a particular revision (say it's picked one that introduced a compile breakage), type `git bisect god/bad`, and then continue as usual. The manpage for git-bisect has some more in-depth details, as does [[kernel.org|http://www.kernel.org/pub/software/scm/git/docs/howto/isolate-bugs-with-bisect.txt]]. diff --git a/InternetPrintingProtocol.mdwn b/InternetPrintingProtocol.mdwn new file mode 100644 index 00000000..9d98181c --- /dev/null +++ b/InternetPrintingProtocol.mdwn @@ -0,0 +1,54 @@ + +The Internet Printing Protocol is maintained by IEEE Print Working Group [[http://www.pwg.org|PWG]] + + +## Statements from the PWG Website + + +### About the PWG + +The Printer Working Group (or PWG) is a Program of the IEEE Industry Standards and Technology Organization (ISTO) with member organizations including printer and multi-function device manufacturers, print server developers, operating system providers and print management application developers. The group is chartered to make printers, multi-function devices, and the applications and operating systems supporting them work together better. + + +### The Internet Printing Protocol IPP + +The IPP working group has developed a modern, full featured network printing protocol which is now the industry standard. IPP allows a print client to query a printer for its supported capabilities, features, and parameters to allow the selection of an appropriate printer for each print job. IPP also provides job information prior to, during, and at the end of job processing. + +The IPP working group remains active for the maintenance of IANA registrations and PWG/ISTO standards, and to support current and future work items. + + +## Color Management and IPP + +The IPP specs are targeted to use cases both with invisible color management in the background or alternatively the option to specify complex color management printing actions. + +Members of the PWG are active at the OpenICC mailing-list for dicussion color management related topics of IPP. + + +### Open ICC E-mail posting from from Paul Tykodi Co-Chair - PWG IPP Working Group + +PWG has only recently had to consider how to describe ICC Profiles within a workflow. The document that explicitly mentions them is the current working draft of the IPP: Job and Printer Extensions - Set 3 specification: [[ftp://ftp.pwg.org/pub/pwg/ipp/wd/wd-ippjobprinterext3v10-20110330.pdf|ftp://ftp.pwg.org/pub/pwg/ipp/wd/wd-ippjobprinterext3v10-20110330.pdf]] + +All of the color information contained within the document is probably somewhat relevant to the discussions currently taking place here on the OpenICC list, however the particular section to review is titled 5.5.16 printer-icc-profiles (1setOf collection). + +Generally PWG best practices advocate keeping the user intent separate from the actual document or data stream that contains the information to be processed or rendered. At this time, the place where I believe the PWG specifications could turn out to be helpful in supporting work on color management is with our core semantic model, which is maintained by the MFD Working Group. The Semantic Model describes an abstracted view of the different functions performed by either a multi-function device or single-function device using standardized terms. The benefit to the standardization of the terms is that both the senders and the receivers within a workflow can declare their intents with a minimum of confusion. + +As an open standards body, the PWG welcomes comments and suggestions. Please feel free to contact us directly or participate in PWG working group mailing lists should you want to provide input on how best to describe ICC Profile usage within PWG specifications. + +Thanks for your interest in our work. + + +### Open ICC E-mail posting from from Mike Sweet, PWG-Chair + +For IPP Everywhere (which is one project of the Printer Working Group), we have a specific goal to define a baseline IPP implementation that supports "driverless" printing from any platform. In support of that goal we have a minimal raster format (PWG Raster, a subset of CUPS Raster), JPEG (since most cameras produce it), and full PDF (which is the only standard format likely to provide full engine speed on high-end laser printers). + +PWG Raster includes standard color spaces - sRGB, sGray (a grayscale version of sRGB), and AdobeRGB - as well as device color spaces such as DeviceRGB, DeviceK, DeviceCMYK, and the full set of DeviceN spaces (1 to 15 components). Printers advertise the color spaces and bit depths they support via IPP attributes. + +JPEG includes support for standard color spaces (sRGB and AdobeRGB) as well as embedded ICC profiles. I suspect we we require support for sRGB and AdobeRGB and recommend support for embedded ICC profiles. + +PDF includes support for standard and arbitrary color spaces, and a printer that supports PDF must also support PDF color spaces and embedded profiles. + +It would be accurate to say that we want to support a common standard color space for basic printing, but we also want to support a fully-color-managed workflow including color proofing. Right now the answer for a standard color space is sRGB, although for photo printing we are seeing a lot more AdobeRGB as well these days. + +For client-side color management, all of the formats under consideration support pass-through of device color, and the "printer-icc-profiles" attribute in the JPS3 specification supports color proofing and client use of vendor (device) color profiles. + +Rendering intent, regardless of profile or format, is handled using the "print-rendering-intent" set of attributes. Right now this is a simple list of values (keywords), but we definitely want to capture any relevant information needed for a color-managed workflow. diff --git a/IntroductionToDBus.mdwn b/IntroductionToDBus.mdwn new file mode 100644 index 00000000..cdaa7510 --- /dev/null +++ b/IntroductionToDBus.mdwn @@ -0,0 +1,183 @@ +# This document + +The following text is _not_ a tutorial or a reference. It will not show you how to use D-Bus (yet). It won't tell you how to install D-Bus or how to program for it. + +What you will find here is an explanation what D-Bus really _is,_ what the concepts behind it are and how they fit together, and what jargon you'll need to know to understand it all. There will be no unnecessary technical detail, and no assumptions about what language you like to program in. The idea is that you can read this before you move on to tutorials or how-to guides for whatever it is you want to use D-Bus for. + +Reading all this first can be useful even if you have a good tutorial to work with. There's a long list of words that have special meanings in the D-Bus world, and not all of them are completely standardized. In this document we try to explain them from the ground up so you won't run into unexplained terms that will only become clear later. We'll also try to give an overview of how different people's views of D-Bus overlap and differ. A perfectly good explanation written from the perspective of one particular programming language can sometimes mislead a new user, or even an experienced user, when using another language. + + +# Introduction to D-Bus + +D-Bus is an inter-process communication mechanism—a medium for local communication between processes running on the same host. (Inter-host connects may be added in the future, but that is not what D-Bus is meant for). D-Bus is meant to be fast and lightweight, and is designed for use as a unified middleware layer underneath the main free desktop environments. + +If you're familiar with many communication mechanisms, here's a quick rundown of this one. Unlike more heavyweight conventional messaging middleware, D-Bus is non-transactional. It is stateful and connection-based, however, making it "smarter" than low-level message-passing protocols such as UDP. On the other hand, it does carry _messages_ as discrete items—not continuous streams of data as is the case with TCP. Both one-to-one messaging and publish/subscribe communication are supported. + +D-Bus has a structured view of the data it carries, and deals with data in binary form: integral numbers of various widths, floating-point numbers, strings, compound types, and so on. Because data is not just "raw bytes" to D-Bus, messages can be validated and ill-formed messages rejected. In technical terms, D-Bus behaves as an RPC mechanism and provides its own marshaling. + + +## Language Bindings + +Application Programming Interfaces for D-Bus, or _bindings,_ are available in several languages—typically one per language, but not necessarily. Each presents its own API as suits the language, hiding the details of working with D-Bus from the programmer to different extents. The ideal is to fit the D-Bus API into the native language and libraries as naturally as possible. + +Using D-Bus should feel more like object-oriented programming than like communication. In some bindings, a programmer may hardly notice that D-Bus is there at all. When that happens, a program that uses D-Bus to communicate will for the most part look as if the counterparts it communicates with were regular components (libraries, modules, packages, objects, functions—whatever the language uses) of the program itself. This is also why some aspects of D-Bus that may seem very basic can differ greatly depending on programming language. + +D-Bus bindings are available for [[an increasing number of languages|http://www.freedesktop.org/wiki/Software/DBusBindings]]. There is a [[low-level C binding|http://dbus.freedesktop.org/doc/dbus/libdbus-tutorial.html]], but that is probably too detailed and cumbersome for anything but writing other bindings. A more practical C binding is based on [[GLib|http://www.gtk.org/]]. There are also [[Java|http://dbus.freedesktop.org/doc/dbus-java/]], [[Perl|http://search.cpan.org/~danberr/Net-DBus-0.33.3/lib/Net/DBus.pm]] and [[Python|http://dbus.freedesktop.org/doc/dbus-python/doc/tutorial.html]] bindings. There are also dbus [[notes and examples|DbusNotes]], and so on. + + +## Buses + +There are two major components to D-Bus: a point-to-point communication _`dbus` library,_ which in theory could be used by any two processes in order to exchange messages among themselves; and a _`dbus` daemon._ The daemon runs an actual _bus,_ a kind of "street" that messages are transported over, and to which any number of processes may be connected at any given time. Those processes connect to the daemon using the library, and it probably wouldn't make much sense to use the library for anything else. We'll be looking mostly at the situation where applications (or more generally, _clients_) connect to a full-blown bus. + +Multiple buses may be active simultaneously on a single system. D-Bus was first built to replace the CORBA-like component model underlying the GNOME desktop environment. Similar to DCOP (which is used by KDE), D-Bus is set to become a standard component of the major free desktop environments for GNU/Linux and other platforms. A GNOME environment normally runs two kinds of buses: a single _system bus_ for miscellaneous system-wide communication, e.g. notifications when a new piece of hardware is hooked up; and a _session bus_ used by a single user's ongoing GNOME session. A session bus normally carries traffic under only a single user identity, but D-Bus is aware of user identities and does support flexible authentication mechanisms and access controls. The system bus may see traffic from and to any number of user identities. + + +### Addresses + +Every bus has an _address_ describing how to connect to it. A bus address will typically be the filename of a Unix-domain socket such as "`/tmp/.hiddensocket`," but it may also be a TCP port where a bus daemon is listening on an IP-domain socket, or conceivably a descriptor for some other low-level communications scheme. The details of how to hook up to the bus daemon are, of course, completely hidden from the client process by the dbus library. We'll just say that a client process opens and uses a _connection_ to the bus. + + +### Configuration and Startup + +Bus daemons are started using the `dbus-launch` command, which in turn runs `dbus-daemon`. Both take an option `--config-file` option to indicate a _configuration file_ describing the bus being started. The standard buses have `/etc/dbus-1/system.conf` and `/etc/dbus-1/session.conf` as their respective configuration files. + +Configuration files are in a simple XML-based format called _busconfig._ + + +### Connections + +Every connection to a bus can be addressed on that bus under one or more names. These names are known as the connection's _bus names._ (Note that bus names are the names of connections on the bus, not names of buses.) Bus names consist of a series of identifiers separated by dots, e.g. "`com.acme.Foo`" and the identifiers themselves may contain letters, digits, dashes, and underscores. The connection is said to _own_ its bus names. + +When a connection is set up, the bus immediately assigns it an immutable bus name that it will retain for as long as the bus exists. This bus name is called a _unique connection name,_ because no other connection will ever have that same name on the same bus--even if the connection is closed down and other ones are created. It can be recognized by the fact that it starts with a colon, which is otherwise not possible: "`:34-907`" (the other parts of the name have no particular meaning). + +A connection may also request additional names, e.g. to offer services under _well-known names_ that are agreed upon by convention. These names must consist of two or more dot-separated elements: "`com.acme.PortableHole`". Only one connection can hold a given name on the bus at any time, but except for unique connection names, bus names can be relinquished and grabbed by other clients. (Whether a client currently holding it is willing to give it up is, of course, another question, but there are ways of arbitrating this.) + + +## Object Model + +Message exchange on protocols like TCP or UDP is symmetric; in those examples, data is always transferred from one "port" to another. D-Bus presents a more sophisticated model where the sending and the receiving side of a message are never quite of the same type. + +In the following we'll borrow from object-oriented terminology. Many terms such as "object" and "method" have more specific meanings in the context of D-Bus, and may have nothing to do with whatever else is going on in client applications. We'll write these terms _in italics_ when they are introduced. All of them are used here only in their D-Bus specific sense, never for their general meanings. + + +### Objects + +One end of any exchange on a bus will always be a communications endpoint that in D-Bus parlance is called an _object._ An object is created by a client process and exists within the context of that client's connection to the bus. The object is a way for the client process to offer its services on the bus--but one client may create any number of objects. + +The bus imposes an object-centric view of communications, where any message carried by the bus is of one of three kinds: + +1. Requests sent to objects by client processes. +1. Replies to requests, going from an object back to a requesting process. +1. One-way messages emanating from objects, broadcast to any connected clients that have registered an interest in them. +Thus at a higher level of abstraction, the bus supports two forms of communication that we could call "_1:1_ request-reply" going to an object, and "_1:n_ publish-subscribe" coming from an object. + +Every bus has at least one object, representing the bus itself. Clients can obtain information about the status of the bus by sending requests to this object. As you'll see later on, it represents the bus in other useful ways as well. + + +### Proxies + +Objects on the bus can be accessed through references that we call _proxies._ We call them that because a proxy is a local representation inside your own program of an object that is really accessed through the bus, and typically lives outside your program: you literally access the object "by proxy." Whether you need to know the difference between an object and a proxy depends on how you talk to D-Bus. The Java binding hides the difference, making it look like you're dealing with the objects directly, but the GLib binding makes the existence of proxies very visible and even offers two kinds of proxies. A proxy exists only inside your client, and the details of how it works depend entirely on the binding you use. + +Objects have names, also called _paths_ because they look like Unix-style, slash-separated filesystem paths. An object that represents a particular cell in a particular spreadsheet might be called "`/org/kde/kspread/sheets/3/cells/4/5`", for instance. An object's name needs to be unique only within the context of its connection to the bus. To obtain a proxy to that spreadsheet cell, you would ask the bus to look up object `/org/kde/kspread/sheets/3/cells/4/5` for you, to be found in the context of the spreadsheet's connection. + +Since any object "lives within" the context of a connection, it takes a combination of that connection's bus name and the object's own name to find it. Once you have found the object you want, if you'll be using it again soon, you'll usually want to keep a proxy to that object around as a variable in your program. That will save you having to look up the object time and again. + +Some bindings' proxies may support _failover._ If you have a proxy to an object exported by some client connected to the bus under a well-known bus name, and that client disconnects (removing the object), reconnects under the same well-known name, and revivies the object, your own program may continue to use the proxy without ever noticing that the object went away for a while. Not all bindings support this, and of the two kinds of proxy in the GLib binding, only one does. It is also not always desirable, e.g. when subsequent operations on an object are meant to be a whole, and it's not acceptable for the object to be disbanded and later reinstituted without your noticing. In those cases, you may need to use a unique connection name in obtaining the proxy rather than a well-known one. + + +### Methods + +When a client sends a request to an object, it sees this request as invoking a _method_ on the object: the object is asked to perform a specific, named action. Normally, if a client tries to invoke a method on an object that the object does not provide, this will raise an error. + +The method's definition may require certain information to be passed with the request as arguments (_input parameters_). For every request, a reply message carries the result back to the requester, along with either result data (_output parameters_) or, if the action could not be performed, _exception_ information. Exceptions will contain at least an exception name and an error message. + +Most D-Bus bindings make all this fit in with their environment's native mechanisms, hiding the finicky details of encapsulating parameters in messages and translating exception messages into exceptions (or whatever the native error-handling mechanism is). For example, passing a string argument to a method of some remote object will look to your program just like passing a string argument to a function in your own program. There is no need for tedious conversions and copying of the data into messages, and there is usually no need to concern yourself with the sending of the underlying message. The binding takes care of all that; the work of encapsulating your data into the messages is called _marshalling._ + +There is one interesting difference with conventional function calls: when sending a request to an object, you don't necessarily have to sit around and wait for a reply. In more complex programs you'll usually find other useful things to do until the method completes. You may want to be ready to handle user interaction, for example, or availability of data from a file or a network connection; you may even have multiple method invocations "in flight" and want to handle the results as they come in, rather than in some pre-defined order. This style of invocation, where you go on to do other things while waiting for an answer, is called _asynchronous_ method invocation. If you use the simple call-and-wait style (_synchronous_ invocation), any other messages that come in while you wait will be queued up and delivered to your program when it's ready for them. + + +### Signals + +The other form of communication also follows the object-oriented mould. Called _signals,_ these one-way communications come from an object and go nowhere in particular. Client processes can register an interest in signals of a particular name coming from a particular object. Whenever an object emits a signal, all interested clients will receive a copy of the signal. There may be one client receiving it, or there may be many--or nobody may be listening. There are no replies to signals: the object emitting the signal would not know how many replies to expect, or where to expect them from. + +Signals can carry parameters, just like method invocations. Of course, since signals are a strictly one-way form of communication, signals do not have input and output parameters like methods do. More recent versions of D-Bus also allow clients to restrict their interest to cases where certain of the signal's parameters match given values; they will only receive instances of the signal that match those expectations. + +Signals are used to publish the occurrence of events that clients may be interested in, such as the closing of some other client's connection to the bus. That particular kind of signal is sent by the object representing the bus itself. Because of this, the event can be announced properly regardless of whether the departing client closed its connection in an orderly fashion, or was killed, or crashed spectacularly. + + +### Interfaces + +So every object supports particular methods and may emit particular signals. These are known collectively as the object's _members._ + +All of an object's members are specified in _interfaces._ Like their namesakes in the Java language, interfaces are sets of declarations. "Implementing" an interface is tantamount to promising to provide all methods specified in the interface, and announcing the availability of its signals for listeners. Each of these members must accept and/or provide parameters exactly as specified in the interface. + +Any object may implement a given interface, just as in Java any number of classes may implement the same interface. Conversely, a single object may implement any number of interfaces. (With D-Bus it probably wouldn't make much sense to have an object that implemented no interfaces at all, though, which is perfectly normal with Java classes.) The combination of all interfaces supported by the object is called the object's _type._ + +When a client invokes a method or listens for a signal, it must indicate the object and the member it is referring to. In addition to object and member, the client may also name the interface in which that member was specified. This can be necessary in some cases. If an object implements two interfaces, for example, that both specify a method named `foo`, then the object may have separate implementations for `foo` in the two interfaces. When a client tries to invoke `foo` on the object without specifying which interface it had in mind, there is <ins>no guarantee</ins> as to which of the two `foo` methods will be invoked. The D-Bus implementation may even refuse to carry the request message in the first place. Similarly, you wouldn't want to receive signals that looked like what you're listening for but are really different ones that happened to have the same name. Older versions of D-Bus also had a bug where request or signal messages could be lost if they failed to specify an interface. + +Whether there is "overloading" of members within interfaces, i.e. whether multiple members of the same interface may have the same name, depends on the binding. + + +# Addressing + +Let's just recap how your program gets all the way from not even being connected to a bus, to finding a method it wants to call or a signal it wants to listen for. Apart from the interface, which as we've seen can usually be omitted, each of these steps is a matter of identifying something that will be needed in the next step: +[[!table header="no" class="mointable" data=""" + **A...** | **is identified by a(n)...** | **which looks like...** | **and is chosen by...** + Bus | address | `unix:path=/var/run/dbus/system_bus_socket` | system configuration + Connection | bus name | `:34-907` (_unique_) or `com.mycompany.TextEditor` (_well-known_) | D-Bus (_unique_) or the owning program (_well-known_) + Object | path | `/com/mycompany/TextFileManager` | the owning program + _Interface_ | _interface name_ | `org.freedesktop.Hal.Manager` | _the owning program_ + Member | member name | `ListNames` | the owning program +"""]] + +Most of these identifiers are also structured as paths themselves: parts of addresses may be; well-known bus names are; object paths are; and interface names are, too. This gets confusing sometimes, especially since related names are often chosen to look very similar--a connection `org.freedesktop.Hal` may provide an object `/org/freedesktop/Hal/Manager` that implements an interface `org.freedesktop.Hal.Manager`. The use of slashes in some identifiers and dots in others also takes some getting used to. + + +# Message Ordering + +Requests from one connection to the same object are delivered in the same order in which they were sent. The same goes for multiple replies from one object to the same client. + +This does not mean that all messages are always delivered in sending order. For example, if two client processes send requests to the same object around the same time, there is no documented guarantee that the object will receive them in the same order. Even when one client sends two subsequent requests to the same object, then waits for both replies, it is possible that the reply to the second request comes in before the reply to the first request. The "object" may really be a multithreaded server process with multiple requests being handled in parallel, or it may prioritize requests internally. + +**TODO: Threading** + + +# Activation + +So far we've assumed that objects are created by active clients. There is another way of offering services on the bus: the bus daemon can be instructed to start (or _activate_) clients automatically when needed. Activation of a client can be triggered in two ways, both keyed by a well-known bus name that the activated client must obtain: + +1. Through an explicit request to the object representing the bus itself. +1. By invoking a method on an object in the context of the client's well-known bus name. +The latter can be inhibited through an option in the method invocation message. Some bindings may try to activate an appropriate client when you create a proxy on a well-known bus name that is not currently in use; others may defer this until you use the proxy to invoke the method. The difference can matter if you listen for a signal coming from an object: if the client that should provide the object is not actually running, you could wait in vain! + +To create a client that can be activated, describe it in a _service file._ A service file looks like a human-readable ".ini" file, line-based and encoded in UTF-8. Its name must always end in "`.service`". + +For example, you might want to register the fact that client program `/usr/local/bin/bankcounter` can be run to provide well-known bus names `com.bigmoneybank.Deposits` and `com.bigmoneybank.Withdrawals`. To do that, you'd write a service file "`bankcounter.service`" (the name is arbitrary, so long as it ends with `.service`) looking like: + + # (Lines starting with hash marks are comments) + + # Fixed section header (do not change): + [D-BUS Service] + Names=com.bigmoneybank.Deposits;com.bigmoneybank.Withdrawals + Exec=/usr/local/bin/bankcounter + +The `Names` line lists the well-known connection names that the client will provide, separated by semicolons (there may also be an extra semicolon at the end). The `Exec` line gives the name of the program to execute in order to activate the client. + +The service files go into a directory indicated in a `<servicedir>` block in the bus' configuration file; the default location is `/usr/share/dbus-1/services/`. If you add service files while the bus is running, the bus daemon will notice and read them without any further prodding. + +More detailed information about activation can be found in Raphaël Slinckx's [[DBus Activation Tutorial|http://raphael.slinckx.net/blog/documents/dbus-tutorial/]]. + + +# Future Work + +This document is still far from complete. Some subjects still need to be covered: + +* Implementing objects +* The special role of `org.freedesktop.DBus` (methods on a bus name, without objects!) +* Authentication ([[see here|http://www.redhat.com/magazine/003jan05/features/dbus/]] for a brief explanation) +* Introspection + +# Other documentation + +* DBusGLibRoadmap +* Software/dbus diff --git a/JamesHenstridge.mdwn b/JamesHenstridge.mdwn new file mode 100644 index 00000000..e98e9448 --- /dev/null +++ b/JamesHenstridge.mdwn @@ -0,0 +1,13 @@ + + +## James Henstridge + +Email: james jamesh id au + +[[http://www.jamesh.id.au|http://www.jamesh.id.au]] + + + +--- + + [[CategoryHomepage|CategoryHomepage]] diff --git a/JamesRichardTyrer.mdwn b/JamesRichardTyrer.mdwn new file mode 100644 index 00000000..96602e6d --- /dev/null +++ b/JamesRichardTyrer.mdwn @@ -0,0 +1,13 @@ + + +## James Richard Tyrer + +Email: tyrerj AT SPAMFREE_acm DOT org + +... + + + +--- + + [[CategoryHomepage|CategoryHomepage]] diff --git a/KaiUweBehrmann.mdwn b/KaiUweBehrmann.mdwn new file mode 100644 index 00000000..9314c5d8 --- /dev/null +++ b/KaiUweBehrmann.mdwn @@ -0,0 +1,15 @@ + + +## Kai-Uwe Behrmann + +Email: ku.b AT NONSENSE gmx DOT de + +www: [[http://www.behrmann.name|http://www.behrmann.name]] + +With the work on the open source CinePaint project, ICC Examin and some non open ones I gathered experience around the colour management field. My goal is to build a flexible open source [[ColourManagementSystem|http://www.oyranos.org]] for many kinds of applications and the desktop. I am very often at freenode on the #openicc channel and discuss regulary on the [[OpenIcc|OpenIcc]] email list. + + + +--- + + [[CategoryHomepage|CategoryHomepage]] diff --git a/KeithPackard.mdwn b/KeithPackard.mdwn new file mode 100644 index 00000000..69a42d10 --- /dev/null +++ b/KeithPackard.mdwn @@ -0,0 +1,6 @@ + + +# Relevant links + +* [[Home Page|http://keithp.com]] +* [[Blog|http://keithp.com/blog]]
\ No newline at end of file diff --git a/LuisMatos.mdwn b/LuisMatos.mdwn new file mode 100644 index 00000000..9ae4c99e --- /dev/null +++ b/LuisMatos.mdwn @@ -0,0 +1,14 @@ + +We run [[http://pvbrowser.org|http://pvbrowser.org]] According to our opinion data acquisition must be portable. + +We use a shared memory and a mailbox. see: [[http://pvbrowser.de/pvbrowser/pic/prinzip.png|http://pvbrowser.de/pvbrowser/pic/prinzip.png]] + +An alternative to a shared memory might be a database table which is memory mapped E.g. [[http://dev.mysql.com/doc/refman/5.0/en/memory-storage-engine.html|http://dev.mysql.com/doc/refman/5.0/en/memory-storage-engine.html]] + +We support Modbus (Serial Line and TCP) Siemens TCP Siemens PPI Ethernet_IP EIBnet/KNX OPC XML-DA PROFIBUS CAN DCON protocol + +Which protocols do you support ? + +Are you interested in cooperation ? For contact see: [[http://tech.groups.yahoo.com/group/pvbrowser/|http://tech.groups.yahoo.com/group/pvbrowser/]] + +This site seems to be down. Right ? There has been no response for over 1/2 an year. You can contact me as written above. diff --git a/MissionStatement.mdwn b/MissionStatement.mdwn new file mode 100644 index 00000000..6b680fd0 --- /dev/null +++ b/MissionStatement.mdwn @@ -0,0 +1,29 @@ + + +## freedesktop.org Mission Statement + +freedesktop.org was formed in March 2000 to encourage cooperation among open source desktops for the X Window System. + +An X desktop is a graphical environment designed to give a technologically advanced, user-friendly face to the X Window System running on UNIX-like operating systems. Most X desktops also provide a development infrastructure for writing applications that integrate well with the desktop. + +freedesktop.org has the following **concrete goals**: + + * Collect existing specifications, standards, and documents related to X desktop interoperability and make them available in a central location; + * Promote the development of new specifications and standards to be shared among multiple X desktops; + * Integrate desktop-specific standards into broader standards efforts, such as Linux Standard Base and the ICCCM; + * Work on the implementation of these standards in specific X desktops; + * Serve as a neutral forum for sharing ideas about X desktop technology; + * Implement technologies that further X desktop interoperability and free X desktops in general; + * Promote X desktops and X desktop standards to application authors, both commercial and volunteer; + * Communicate with the developers of free operating system kernels, the X Window System itself, free OS distributions, and so on to address desktop-related problems; + * Provide source code hosting, web hosting, mailing lists, and other resources to free software projects that work toward the above goals. +The concrete goals of freedesktop.org stem from the following **general principles**: + + * _Developers_ should be able to use the development environment of their choice without limiting their potential userbase to users of a particular desktop environment + * _Users_ should have a maximum amount of choice in selecting the applications they wish to run. Users should not be limited to a certain subset of applications; ideally, even the components of the desktop environment (window manager, panel, file manager, etc.) would be interchangeable. + * _Code sharing_ and _modularity_ are a good thing. When possible, a common implementation not dependent on a specific desktop increases stability, increases interoperability, reduces system footprint, and optimizes the use of free software development resources. + * _Concept sharing_ is a good thing. Users do not benefit from the existence of multiple desktops if those desktops do not share their good ideas and work together toward common goals. + * freedesktop.org is first and foremost a _work project_; we intend to develop specifications, and then write code where needed. Work is the only currency that matters in the free software world. + * freedesktop.org is an organization made up of developers, designed to help developers do development. XDG does not intend to provide user resources. + * freedesktop.org's code will be placed under free licenses that encourage wide use; most commonly, the LGPL for libraries, or an X-style license when appropriate. **Most importantly**: the goal of an X desktop is to provide a service to users (including not only the users of the desktop environment, but also the developers who use the development infrastructure). freedesktop.org should be judged by how well it serves the interests of X desktop users. +The goals of freedesktop.org specifically _exclude_ "blessing" or legislating formal standards, because freedesktop.org does not have the formal infrastructure for that. This site is about catching interoperability issues much earlier in the development process, ideally before code has been written, and providing a forum to work on specifications. Some of these specifications may be standardized by other bodies, but only after "de facto" acceptance most likely. You can look at freedesktop.org as a way to oil the wheels of "de facto" shared specifications. diff --git a/MoinMoin.mdwn b/MoinMoin.mdwn new file mode 100644 index 00000000..eaedd187 --- /dev/null +++ b/MoinMoin.mdwn @@ -0,0 +1,39 @@ + +The following pages are about the development of MoinMoin: + +* [[!MoinMoin MoinMoinQuestions desc="MoinMoinQuestions"]] - Questions about MoinMoin (installing, etc.) +* [[!MoinMoin MoinMoinTips desc="MoinMoinTips"]] - Tips & tricks for MoinMoin +* [[!MoinMoin MoinMoinTranslation desc="MoinMoinTranslation"]] - discussion about translating MoinMoin +* [[!MoinMoin MoinMoinBugs desc="MoinMoinBugs"]] - bugs in the software (see also [[The Sourceforge Bug Tracker|http://sourceforge.net/tracker/?group_id=8482&atid=108482]]) +* [[!MoinMoin MoinMoinDiscussion desc="MoinMoinDiscussion"]] - discussion about new features +* [[!MoinMoin MoinMoinIdeas desc="MoinMoinIdeas"]] - you are encouraged to _add_ wishes and ideas to this page +* [[!MoinMoin MoinMoinMailingLists desc="MoinMoinMailingLists"]] - discussion about MoinMoin via email +* [[!MoinMoin MoinMoinWinCvs desc="MoinMoinWinCvs"]] - instructions on using WinCVS to obtain the latest source of MoinMoin +* [[HelpForDevelopers|HelpForDevelopers]] - the rules that govern MoinMoin development +These pages provide information about using and installing MoinMoin: + +* [[/TextFormatting|MoinMoin/TextFormatting]] - a page containing samples of all the markup options +* [[!MoinMoin MoinMoinSuccessStories desc="MoinMoinSuccessStories"]] - what do other people use MoinMoin for? +* [[HelpContents|HelpContents]] - The main page of the help system +* [[HelpMiscellaneous/FrequentlyAskedQuestions|HelpMiscellaneous/FrequentlyAskedQuestions]] - Frequently Asked Questions (ask your own on [[!MoinMoin MoinMoinQuestions desc="MoinMoinQuestions"]]) +* [[!MoinMoin MoinMoinMailingLists desc="MoinMoinMailingLists"]] - discussion about MoinMoin via email +* [[!MoinMoin MoinMoinWikis desc="MoinMoinWikis"]] - list of wiki sites using MoinMoin +* [[/InstallDocs|MoinMoin/InstallDocs]] - all the help pages about installation rolled into one +* [[/InstallationsAnleitung|MoinMoin/InstallationsAnleitung]] - installation docs in German +* [[!MoinMoin SecurityPolicy desc="SecurityPolicy"]] - explains how to restrict access to your wiki, or parts of it +* [[!MoinMoin MoinMoinSyndication desc="MoinMoinSyndication"]] - Support for RSS feeds and other collaboration features across systems +Other pages about MoinMoin: + +* [[!MoinMoin MoinMoinEtymology desc="MoinMoinEtymology"]] +External links: + +* [[SourceForge Project Info|http://sourceforge.net/projects/moin/]] +* [[Project Homepage|http://moin.sourceforge.net/]] +* [[FreshMeat Entry|http://freshmeat.net/projects/moin]] +* [[PythonNews article on wikis|http://www.oreillynet.com/pub/a/python/2000/11/29/pythonnews.html]] +Connect to [[!Foldoc IRC desc="IRC"]] for meeting the author and other MoinMoin users and developers: + +* channel `#moin` on [[!MoinMoin FreeNode desc="FreeNode"]] server `irc.freenode.net` +* see also [[freenode home page|http://freenode.net/]] and esp. [[freenode IRC servers|http://freenode.net/irc_servers.shtml]] for more information +[[!img http://www.opensource.org/trademarks/opensource/web/opensource-110x95.png] +[[Open Source|http://www.opensource.org/docs/definition.php]] diff --git a/MoinMoin/InstallDocs.mdwn b/MoinMoin/InstallDocs.mdwn new file mode 100644 index 00000000..562ae1f5 --- /dev/null +++ b/MoinMoin/InstallDocs.mdwn @@ -0,0 +1,104 @@ + +This HTML page contains the basic install docs that can be found on [[http://moinmaster.wikiwikiweb.de/MoinMoin/InstallDocs|http://moinmaster.wikiwikiweb.de/MoinMoin/InstallDocs]]. It contains all necessary information to get your wiki up and running, even without being online. If you have a permanent internet connection, you might want to browse the docs on the Help``On``Installing page, which might contain more up-to-date information. + +After following the procedures on this page, you should have a working wiki and can browse the rest of the online docs there. + + +## How to install your own MoinMoin Wiki + +This page describes the installation procedure applying to [[!MoinMaster MoinMoin desc="MoinMoin"]] version 1.1 and up. In the next section, there is a list of real-world [[Installation Scenarios|MoinMoin/InstallDocs]] that help you to understand how to apply the instructions in different environments. + +[[Basic Installation|MoinMoin/InstallDocs]] explains the "`setup.py`" step of the installation in more detail. This applies equally to all scenarios, and you should read it before trying a live installation. + +[[Trouble-shooting|MoinMoin/InstallDocs]] helps with fixing any general problems you might encounter, which apply to any installation platform. + +After a successful installation, you might want to read more about configuration and other options that you, as the wiki administrator, can set up. [[!MoinMaster HelpOnAdministration desc="HelpOnAdministration"]] contains links to pages that cover these topics. Especially, the [[!MoinMaster HelpOnConfiguration desc="HelpOnConfiguration"]] and [[!MoinMaster HelpOnUpdating desc="HelpOnUpdating"]] pages provide additional information regarding wiki setup and maintenance. [[!MoinMoin MoinMoinWinCvs desc="MoinMoinWinCvs"]] and [[!MoinMoin MoinMoinUnixCvs desc="MoinMoinUnixCvs"]] describe how to run your wiki using the current development version from the [[!MoinMoin SourceForge desc="SourceForge"]] CVS repository. +[[!table header="no" class="mointable" data=""" + Please **make sure** that you do **not** accidently put your wiki's **`data/`** directory under a directory directly accessible by your web server (like below document root). Or at least forbid your web server serving anything below `data/` to a user - this is neither needed nor wanted! Your web server needs to serve moin.cgi and the stuff below htdocs **only**. +"""]] + +<a name="installscenarios"></a> +### Sample Installation Scenarios + +The following links lead you to concrete examples of installation sessions, showing the commands used and explaining what they do. It is highly recommended that you _first_ read the general information on installing (especially the next section of this page) before choosing an installation scenario that best fits your intended use of [[!MoinMaster MoinMoin desc="MoinMoin"]]. + +UNIX: + +* [[UNIX Installation|MoinMoin/InstallDocs]] +Windows: + +* [[Windows Installation using Apache|MoinMoin/InstallDocs]] +* [[Windows Installation using IIS|MoinMoin/InstallDocs]] +Mac OS X: + +* [[Mac OS X Installation|MoinMoin/InstallDocs]] +Long-Running-Process Setup: + +* [[FastCGI Setup using Apache|MoinMoin/InstallDocs]] +* [[mod_python Setup using Apache|MoinMoin/InstallDocs]] +* [[Setup using twisted|MoinMoin/InstallDocs]] +<a name="basic-install"></a> [[!inline pages="HelpOnInstalling/BasicInstallation" quick="yes" raw="yes"]] + +--- + + <a name="trouble-shooting"></a> + +--- + + [[!inline pages="HelpOnInstalling/TroubleShooting" quick="yes" raw="yes"]] + +--- + + <a name="unix-install"></a> + +--- + + [[!inline pages="HelpOnInstalling/ApacheOnUnix" quick="yes" raw="yes"]] + +--- + + <a name="win32apache-install"></a> + +--- + + [[!inline pages="HelpOnInstalling/ApacheOnWin32" quick="yes" raw="yes"]] + +--- + + <a name="win32iis-install"></a> + +--- + + [[!inline pages="HelpOnInstalling/InternetInformationServer" quick="yes" raw="yes"]] + +--- + + <a name="macosx-install"></a> + +--- + + [[!inline pages="HelpOnInstalling/ApacheOnMacOsx" quick="yes" raw="yes"]] + +--- + + <a name="fastcgi-install"></a> + +--- + + [[!inline pages="HelpOnInstalling/ApacheWithFastCgi" quick="yes" raw="yes"]] + +--- + + <a name="modpy-install"></a> + +--- + + [[!inline pages="HelpOnInstalling/ApacheWithModPython" quick="yes" raw="yes"]] + +--- + + <a name="twisted-install"></a> + +--- + + [[!inline pages="HelpOnInstalling/TwistedWeb" quick="yes" raw="yes"]] diff --git a/MortenSvantesson.mdwn b/MortenSvantesson.mdwn new file mode 100644 index 00000000..41b76c58 --- /dev/null +++ b/MortenSvantesson.mdwn @@ -0,0 +1,13 @@ + + +## Mårten Svantesson + +My name is Mårten, but since [[MoinMoin|MoinMoin]] doesn't support å in [[WikiNames|WikiNames]] I use the alternate spelling Morten here. I don't use Marten, because that isn't my name. Now you know. + +... + + + +--- + + [[CategoryHomepage|CategoryHomepage]] diff --git a/NetworkManager.mdwn b/NetworkManager.mdwn new file mode 100644 index 00000000..5bb7463e --- /dev/null +++ b/NetworkManager.mdwn @@ -0,0 +1,8 @@ + +NetworkManager (NM) a network management daemon to make your networking Just Work. For more information, see the [[NetworkManager|http://projects.gnome.org/NetworkManager]] web site. + + + +--- + + [[CategoryHardware|CategoryHardware]] diff --git a/NewProject.mdwn b/NewProject.mdwn new file mode 100644 index 00000000..33a27fc3 --- /dev/null +++ b/NewProject.mdwn @@ -0,0 +1,22 @@ + + +# THIS IS A DRAFT + + +# How to request a new freedesktop.org project + +First, please make sure your project fits within the [[MissionStatement|MissionStatement]], if it doesn't, it will be rejected. We prefer hosted projects to be using our infrastructure, so if you plan to use Freedesktop.org just for bug tracking for instance, your project will be rejected. Not using all Freedesktop.org services is acceptable, but just using a single one will probably cause your project to be rejected. + +If you are in doubt about whether your project is appropriate for freedesktop.org, please start a discussion about it on the freedesktop mailing list. + + +# Requesting a new project + +* go to [[http://bugs.freedesktop.org|http://bugs.freedesktop.org]] +* file a bug on the freedesktop.org product with the component set to "Project Creation Requests". Make sure the bug includes the following information: + * project name (if there are any ambiguities about what the unix group name should be, please suggest one as well, else we'll use our best judgement) + * who should be able to approve new members into your project + * if you need git hosting: which git repositories you want, each with a short description (to go into .git/description) + * if you need bugzilla, we need a short product description and a list of components (each with a short description and default assignee) + * if you need mailing lists, we need the names of all of them and who should be the list administrator. + * if you need file upload space
\ No newline at end of file diff --git a/OpenIcc.mdwn b/OpenIcc.mdwn new file mode 100644 index 00000000..2e62ec8d --- /dev/null +++ b/OpenIcc.mdwn @@ -0,0 +1,189 @@ + + +# OpenICC project + +OpenICC has two main goals. The first goal is to work out a common set of settings for color savvy applications to share profiles and settings. The second goal is to bring together those developers in areas like printing, display and desktop applications to work together to make color management end to end work for open source applications. + +A draft specification is planned at a later stage. + +[[!toc 3]] + + +# Getting involved + +If you are planning to add color management to your software project or you are hardware manufacturer who wishes to extend his clients base by dipping your toes into opensource water, we encourage you to join our mailing list. Subscription page is [[just round the corner|http://lists.freedesktop.org/mailman/listinfo/openicc]]. + +* Email: [[OpenICC email list at freedesktop.org|http://lists.freedesktop.org/mailman/listinfo/openicc]] +* [[IRC|http://webchat.freenode.net?channels=openicc&uio=MT11bmRlZmluZWQb1]]: the channel is called [[#openicc @ irc.freenode.net|irc://irc.freenode.net/openicc]] + +# Who's taking part + +Currently, OpenICC is an informal group of developers exchanging ideas and concepts on integrating ICC color management. Here is a mostly complete list of project developers involved in this discussion: + +* [[ArgyllCMS|http://www.argyllcms.com]], an experimental, open source, ICC compatible color management system. +* [[CinePaint|http://cinepaint.sourceforge.net]], a 16-bit photo retouching application, best suited for video. +* [[colord|http://colord.hughsie.com/index.html]], a system service to manage, install and generate color profiles +* [[CUPS|http://cups.org]], printing software. +* [[GraphicsMagick|http://www.graphicsmagick.org/]], is the swiss army knife of image processing. +* [[GIMP|http://www.gimp.org]], popular pixel manipulation application +* [[GhostScript|http://www.ghostscript.com/]], an interpreter for the [[PostScript|PostScript]] language and for PDF +* [[Gutenprint|http://gutenprint.org]], a set of very high quality drivers for printers, with particular emphasis on inkjets. +* [[ImageMagick|http://www.imagemagick.net]], image editing collection. +* [[Inkscape|http://www.inkscape.org]], a vector graphics editor. +* [[Krita|http://www.krita.org]], and [[Karbon|http://www.calligra.org]], the raster and vector image manipulation applications of the Calligra suite. +* [[LittleCMS|http://www.littlecms.com]], a widely used open source color management system. +* [[Poppler|http://poppler.freedesktop.org/]], a PDF rendering library based on the xpdf-3.0 code base. +* [[LPROF|http://lprof.sourceforge.net]], an open source profiler that uses LCMS. +* [[Scribus|http://www.scribus.net]], an open source page layout application. +* [[Oyranos|http://www.oyranos.org]], a colour management system for configuration, user interfaces and much more. + +# Profiles for standard print condition and their licenses + +For the creation and exchange of images, vector graphics and documents (e.g. PDF) it makes sense, when applications can use a standard set of ICC-profiles which are preinstalled in an known directoty like eg. share/color/profile on every computer. Currently, different organisations, projects and vendors are offering such standard profile packages with different licenses. Not all licenses are compatible to integrate these profile packages into LINUX distributions. + +Furthermore in the graphic arts, there are so called "reference printing conditions" which represent color measurement-data (also called characterization-data) representing a printing standard. Such characterization-data are a basis for calculating ICC-profiles representing a printing standard. + +Several packages for standard ICC profiles are containing CMYK-profiles with different names and calculated with different profiling packages but representing the same reference printing condition. The International Color Consortium ICC hosts a [[registry|http://www.color.org/registry2.xalter]] for worldwide used reference printing conditions. + +Future new ICC profiles for OpenICC should use the same [[reviewed|http://www.crynwr.com/cgi-bin/ezmlm-cgi?3:mss:16756:201007:jgkgmfkbkeglodlhbmnc]] [[license as the ICC|http://www.color.org/registry/profileregistration.xalter]]. + +An overview about available packages is here [[OpenIcc/ProfilePackages|OpenIcc/ProfilePackages]] + + +# ICC is going open source + +The ICC itself has began an open source project: + +* [[http://sourceforge.net/projects/sampleicc/|http://sourceforge.net/projects/sampleicc/]] +SampleICC provides an open source platform independent C++ library for reading, writing, manipulating, and applying ICC profiles along with applications that make use of this library. + + +# Legal issues + +In the middle of the 90's, there were some patent wars concerning color management. Specifically the company EFI sued a lot of other companies that had implemented an RGB to CMYK conversion in their applications. Actually, it is important to be aware of which color management features are part of the ICC specs, and which are going beyond the ICC specs. + +Implementing color management according to ICC specs is very safe. Implementing extended functions that are not part of the ICC specification could may be dangerous. This concerns especially LittleCMS, which is the standard CMM for more or less all open source applications dealing with color management. (Of course, ArgyllCMS also contains a CMM...) + +Some of this extended functionality can be very helpful for some use cases. So from the point of view of the user, it makes a lot of sense to implement and use them. One example is enhanced options for CMYK to CMYK conversions. Such functions are useful for the colormanagement of documents for the graphic arts. + +It can be implemented as special function for the CMM, or it can be solved by precalculating a devicelink-profile, which is used with a ICC-conforming CMM. If it is, for example, implemented as special function in LittleCMS, a legal issue concerning littleCMS could touch all applications which make use of LittleCMS. + +If it is implemented in a standalone software, which generates and delivers a devicelink-profile, the legal issue covers only the standalone software. The use of devicelink-profiles in other software is a standard feature of the ICC specs. + + +# Specifications + +* [[Standards|http://www.oyranos.org/wiki/index.php?title=Standards]] overview on [[ColourWiki|http://www.oyranos.org/wiki/]] +* [[ICC Profiles in X Specification|http://www.freedesktop.org/wiki/Specifications/icc_profiles_in_x_spec]] +* [[ICC meta Tag for Monitor Profiles|http://www.freedesktop.org/wiki/Specifications/icc_meta_tag_for_monitor_profiles]] +* [[Oyranos X11 Requirements|http://www.oyranos.org/wiki/index.php?title=Oyranos_X11_Requirements]] + +# Proposals + + +## White papers for enhancing the ICC-specs + +Observing real world colormanagement-workflows with ICC-profiles, it is clear that some problems should be solved with better and more clear defined ICC-specs. Actually, some of such enhancements can be done through "white papers". Such a white paper could e.g. describe extended functions of the CMM. One example of such enhancement is the description of Blackpoint Compensation in Adobe Products at *[[http://www.color.org/Adobe1bpc.pdf|http://www.color.org/Adobe1bpc.pdf]] + +If developers or color management consultants think, that the ICC-specs need some enhancements, the OpenICC wiki could be used as collaborative platform to produce such whitepapers. + +Every proposal for an ICC Whitepaper should be a Subpage in the OpenICC wiki and should be structured as following: + +* Which real world use cases are addressed +* which kind of applications are targeted +* how should it be implemented technically +* how should it be implemented in the user interface. + +### Actual proposals for ICC whitepapers + + +#### Better handling of ICC Grey Objects + +[[IccGreyObjects|IccGreyObjects]] + + +#### Device Settings in ICC + +[[ICC meta data tag|http://www.color.org/ICCSpecRevision_25-02-10_dictType.pdf]] - the base specification to store a meta data key/value list in ICC profiles. + +[[ICC meta Tag for Monitor Profiles|http://www.freedesktop.org/wiki/Specifications/icc_meta_tag_for_monitor_profiles]] stores device infos from EDID + + +#### HDR Rendering Description + +The goal of the [[HdrRenderingDescription|HdrRenderingDescription]] is to provide a way of, how to render an LDR representation from a certain HDR image in different applications to appear similar. Such a description should be included into a ICC style colour profile. As one step a [[OpenIccForGoogleSoC2007|OpenIccForGoogleSoC2007]] project was underway. + + +## General Topics + + +### Directory scheme for Colour Management + +[[OpenICC Directory Proposal|http://www.oyranos.com/wiki/index.php?title=OpenIccDirectoryProposal]] + + +### X Color Management spec + +[[Version 0.4 Draft 1|http://oyranos.org/scm?p=xcolor.git;a=blob;f=docs/X_Color_Management.txt]] is public. The goal is to communicate ICC colour regions between server and clients. The implementation is available in libXcm-0.2.x. Some tools and plugin in the Oyranos examples directory support the draft by using libXcm. + + +## Requirements of Applications and Services + + +### Link Collection + +* [[Applications at ColourWiki|https://www.oyranos.org/wiki/index.php?title=Applications]] +* [[Cairo|http://www.freedesktop.org/wiki/OpenIcc/Cairo]] + +### PPD colouring + +End user applications want to assign ICC profiles to a combination of printer device, a driver and a set of colour related driver options. Thus for PPD to support this scheme, it is necessary to know, which PPD option is colour related. The proposal suggests a enumerated list of PPD key words named ColorKeyWords, containing a semicolon ';' separated list of PPD key words. The listed keys relate to colour and thus with their values to the ICC profile selection at application level. + + +# LINUX color management a proposal for implementation + +[[OpenIcc/LinuxCmProposal|OpenIcc/LinuxCmProposal]] describes a roadmap for color management under LINUX with the interaction of + +* A profile repository connecting devices, documents and profiles +* Engine for ICC color transformations of Image maps +* Cairo +* Ghostscript +* monitor output +* printer driver (e.g. Gutenprint or Turboprint) +* CUPS / PPDs +* File export +* application interface +[[ColourWiki|http://www.oyranos.org/wiki]] contains [[schemes for colour managed printing|http://www.oyranos.org/wiki/index.php?title=Device_Settings#Printing]]. They are graphical and in some parts more technical. + + +# Color managed Printing Path + +[[OpenIcc/ColorMangedPrintingPath|OpenIcc/ColorMangedPrintingPath]] is a proposal for coordinating developments of Gutenprint, CPD and pdftoraster moduls like e.g. [[GhostScript|GhostScript]] to create a reliable color managed printing path both for standard users, color enthusiasts and color professionals. + + +# Internet Printing Protocol + +The page [[InternetPrintingProtocol|InternetPrintingProtocol]] collects informations about color managed printing according the Internet Printing Protocol IPP. + + +# Google SoC + +Suggestions for Googles Summer of Code 2012 are here [[OpenIcc/GoogleSoC2012|OpenIcc/GoogleSoC2012]]. Students will find our project goals and ideas, contact persons, requirements and other hints there. + +Students who successfully complete their projects will receive a significant stipend from Google for their work. Not our application is not agreed upon. For the older projects and ideas see here [[OpenIcc/GoogleSoC2011|OpenIcc/GoogleSoC2011]], [[OpenIcc/GoogleSoC2010|OpenIcc/GoogleSoC2010]], [[OpenIcc/GoogleSoC2009|OpenIcc/GoogleSoC2009]], [[OpenIccForGoogleSoC2008|OpenIccForGoogleSoC2008]] and here [[OpenIccForGoogleSoC2007|OpenIccForGoogleSoC2007]]. + + +# Events + +[[Linux Color Management Hackfest Brno 9th till 12th November 2012|http://www.freedesktop.org/wiki/OpenIcc/Events/Hackfest/2012]] + +[[Elder OpenICC Events|OpenIcc/Events]] + + + +--- + + +# Help for editors + +Here is the editing manual [[http://www.freedesktop.org/wiki/HelpContents|http://www.freedesktop.org/wiki/HelpContents]] diff --git a/OpenIcc/ColorMangedPrintingPath.mdwn b/OpenIcc/ColorMangedPrintingPath.mdwn new file mode 100644 index 00000000..777c6f2b --- /dev/null +++ b/OpenIcc/ColorMangedPrintingPath.mdwn @@ -0,0 +1,161 @@ + + +# The Colormanaged Printing Path + +This page is intended to coordinate the developments and the usage of ICC profiles in following applications / tools. The first version should act as a starting point for the community active for the colormanaged printing path. + + +### Print Spool file generation + +* QT printing API + +* print spool files created directly from applications + + +### PDFtoRaster modules + +* [[GhostScript|GhostScript]] + +* Poppler + + +### CUPS + + +### CPD - Common Printing Dialogue + + +### Raster Printer driver + +* Gutenprint + + +# Overall description of project goals and use cases + + +## 1) Invisible print colormanagement for standard users + +The standard print spool format under LINUX are currently DeviceRGB PDF-files. For colormanagegd print path, such spool files will be treated as being sRGB. If the standard user changes media settings in the CPD, the proper canned printer profile should be configured automatically in the CUPS PDFtoRaster module. + + +## 2) Robust color management Opt-out process for printing testcharts + +A "bullet proof" printing mode for testcharts must be avaliable with disabled color management in the printing path. This is reached through and advanced option in CPD for Opt Out ICC based color conversion in the pdftoRaster module for DeviceRGB and DeviceCMYK print spool files. + + +## 3) Linking of printer ICC-profiles and raster driver settings through ICC dictType metadata + +An automatic linking between raster driver settings and ICC-profiles is extremly helpful for automated and colormanaged print workflows. The ICC dictType metadata allows to register a vendor specific ICC tag, which e.g. can contain driver settings. CUPS PDFtoRaster could uses such prepared printer profile as a target profile and embed this profile in the raster file for e.g. [[RastertoGutenprint|RastertoGutenprint]]. [[RastertoGutenprints|RastertoGutenprints]] will parse the Rasterfile, extract the driver settings and setups Gutenprint automatically. This concept could be used both for CUPS based printing workflows and also for colormanaged imaging applications, which are bypassing CUPS and driving Gutenprint directly. A combination of ICC-profile and driver setting is named "ICC-driversetting" in the following paragraphs. + + +## 4) Importing ICC-driversettings into CPD + +Normally, available driver options are represented through static PPD files in the CUPS / CPD workflow. There are several use cases, where it makes a lot of sense, that the user can import ICC-driversettings into CPD without the need to change the PPD for the printer. These are e.g. + +- The driver vendor / community publishes new ICC-driver settings for a given printer + +- A media vendor publishes new ICC-driver settings for a given printer + +- A remote profiling service delivers ICC-driver settings to the enduser + +- The enduser itself creates new ICC-driver settings + +The choosable options for the standard user in CPD concerning media and print quality / speed will be generated only from the available ICC-driver settings. For creating a simple CPD-user interface, the ICC-driversettings should contain hierarchical selectors for e.g. printertype, mediatype and resolution If for a printer type two profile for plain paper with 360 DpI / Fast and 720 / High Quality are available, the CPD dialogue will show for the media selector one entry for plain paper and two entries in the resolution / quality selector. If there is only one profile for Glossy paper, the CPD selector for resolution / quality will only show one entry, glossy paper is choosed in the media selector.. The workflow for printing testcharts will discussed later. + + +## 5) The role of PDFtoRaster and CPD + +PDFtoRaster must be able rasterize a DeviceXXX PDF without any color conversion (testchart printing) and also with a colorconversion from a default source profile to a target profile. CPD must be able to setup the target profile (ICC-driversetting) in PDFtoRaster. PDFtoRaster must also be able to embedd the ICC-driversetting into the rasterfile, to allow an automatic setup of e.g. [[RastertoGutenprint|RastertoGutenprint]] or RastertoXXXdriver. + + +## 6) Printing Testcharts, creating new stand alone driver settings and ICC-driversettings + +Printing Testcharts can be simple with predefined driver settings for a given media type, or can be a science if new driver settings have to be optimized for a special ink-media combination. Working with predefined driver settings is necessary for user who don´t want to know the details about printer profiling, but wants to have an individual ICC-profile for his media through an remote profiling service. The advanced options are needed for power users which want to adapt the driver settings to an optimum for the ink-media combination before the testchart is printed. + +Doing high-quality printer profiling with control for black generation needs the possibility for sending CMYK testcharts to the printer. This is not possible if the sending application supports only RGB based print spool files. + + +## 7) Disclosure of complexity through CPD + +The following concept describes three layers in a CPD dialogues: + + +## 7a) Daily usage + +The top CPD dialogues presents: - media type selector (extracted from installed ICC-driversettings) + +- resolution / quality (extracted from ICC driversettings of the same media type, Standard rendering is set to relative colorimetric with blackpoint compensation and hidden from the user) - papersize + +- number of copies + +- scaling of print job + +- import new media / quality setting (simply import an ICC-driversetting for the printertype) + +- advanced settings (open the second layer) + + +## 7b) Advanced settings + +- media / quality selector (available from different sources: + + * - extracted from ICC-driver settings, - direct import of settings indpendent fromICC-profile, - creation of own media / quality settings in expert mode) +- Choose color rendering options (changes the rendering intent in pdftoraster, or disables colormanagement in pdftoraster for deviceXXX files) + +- Create additional quality setting (adds for a given media media setting an additional quality entry, to print with a different rendering intent or disabled colormanagement. Will be choosable in the top dialogue as additional entry. This allows e.g. daily printing with disabled colormanagement, or e.g. with absolute colorimetric rendering intent for proofing) + +- import media/quality settings (import of settings independent from an ICC-profile, which than will be available through the media / quality selector + +- merge ICC with media/quality setting (import of an ICC-profile, integrate current media/quality setting as ICC dictType and make it available in the the CPD top layer + +- export ICC-driversetting (export available ICC-driversettings for exchange with other users) + +- activate control slug (prints a control slug with name of media quality setting, active ICC-profiles and rendering intent. This is needed for proofing, helpful for troubleshooting and a must for testcharts to know which media quality settings has been used to print the testchart. + +- activate control bar (prints an additional control bar, which is e.g. mandatory for proofing. + +- expert settings (open the third layer) + + +## 7c) Expert settings + +All available low level options for the expert to create individual media driver settings - media quality selector (the same selector as in advanced settings. Selecting a media / quality setting here, will show all the entries for the low level driver settings and makes them available for editing. Also additional media quality settings are available for: + +7c-1) printing testcharts for judging and setting inklimits per channel and total ink-limit + +7c-2) printing testcharts for judging and optimizing per channel linearization curves + + +## 7d Different versions / installing options of CPD ? + +For users, which are only using software with standard RGB print spool path and not interested in printing testcharts, it may makes sense to offer two versions of CPD. One containing only the top layer and another all three layers. It may also makes sense to develop a solution to print CMYK-testcharts directly from CtP to rastertogutenprint (bypassing the normal deviceRGB print spool path and pdftoraster) + + +## 8) CPD and pdftoraster + +The color transformtion of the print spool file happens in pdftoraster. pdftoraster must be able to be remotely configured through CPD, if e.g. the user changes a media / quality setting. Controlled by CPD are at least the target profile for the color transformation of the print spool file, the rendering intent and disabling of the usage of ICC profiles in pdftoraster. The source profile for the color transformtion of the print spool file is either: + +- defined from the sending application through its document colorspace + +- defined through a colormanagement framework like e.g. Oyranos or g-c-m + +- default profile of pdftoraster (sRGB.icc for standard pdf printspool files) + +If a user imports an ICC-driversetting in CPD, it must be available instantly for pdftoraster without any user intervention. pdftoraster must also be able to embedd the target profile of the transformtiion into the rasterfile for rastertodriver (e.g. rastertogutenprint). So far as I know, only [[GhostScript|GhostScript]] is currently able to convert DeviceRGB and DeviceCMYK PDF-files with ICC-profiles and free choosable rendering intents. poppler applies ICC-based transformations only to ICCbased PDF-objects. + + +## 9) Crowd profiling and registry for Gutenprint ICC-driversettings + +If we are talking about ICC-driver settings representing different printers, different media types and quality modes, we are talking about 1000+ Gutenprint ICC-driver settings. To organize such Gutenprint ICC-driversettings, it would be helpful, to have a registry which allows upload of ICC-driversettings and download for endusers selectable by printertype. 1000+ ICC driver settings seems to be a lot of work for a relatively small project like the Gutenprint team. But if we look, which parties could participate in the project, 1000+ Gutenprint ICC-driversettings could be realized between 6 and 12 months. Potential creators of Gutenprint ICC-driversettings are e.g. + +- Members of the Gutenprint team + +- vendors and resellers for inkjet-media + +- open source color enthusiasts, which sponsoring their own made Gutenprint ICC-driversettings + +- open source color enthusiasts which are sponsoring the project with monthly measuring some testcharts + +- remote profiling services, where the buyer of an individual made Gutenprint ICC-driversetting gets a lower price, if he agrees that a copy of his Gutenprint ICC-driversetting will be uploaded to the registry. + +To organize the registry and the crowd-profiling process, it is very important, that printertypes, general mediatypes and resolution/quulity settings are unambiguous defined. This could be solved, where the Gutenprint delivers predefined settings, where e.g. the printertypes, general mediatypes and resolution / quality settings are already named. The contributor will ad e.g. additional informations like the precise commercial media name of the setting, before he merges ICC-profile and Gutenprint settings to an Gutenprint ICC-setting, which he than uploads to the registry. diff --git a/OpenIcc/Events.mdwn b/OpenIcc/Events.mdwn new file mode 100644 index 00000000..c468c8d3 --- /dev/null +++ b/OpenIcc/Events.mdwn @@ -0,0 +1,4 @@ + +* [[OpenIcc @ FOSDEM 4 + 5 February 2012 in Brussels, Belgium|OpenIcc/Events/Fosdem/2012]] +* [[OpenICC @ LGM in Vienna from 2th till 5th of May 2012|http://libregraphicsmeeting.org/2012]] +* [[Linux Color Management Hackfest Brno 9th till 12th November 2012|OpenIcc/Events/Hackfest/2012]]
\ No newline at end of file diff --git a/OpenIcc/Events/Fosdem/2012.mdwn b/OpenIcc/Events/Fosdem/2012.mdwn new file mode 100644 index 00000000..d11877d3 --- /dev/null +++ b/OpenIcc/Events/Fosdem/2012.mdwn @@ -0,0 +1,60 @@ + + +# OpenIcc @ FOSDEM 4 + 5 February 2012 in Brussels, Belgium + +* _What:_ OpenICC @ [[Fosdem|http://www.fosdem.org]], a big open source community event +* _Where:_ Brussels, Belgium, Europe +* _When:_ 4 + 5 February 2012 +* _Why:_ Colour Management in the Open Source field +* _Who:_ Kai-Uwe Behrmann (ku.b at gmx.de] is organiser. Get in contact about all issues with him. +[[OpenIcc|OpenIcc]] is provided with a 85 seat developer room at Fosdem together with [[Xorg|http://wiki.x.org/wiki/fosdem2012]] for two days. Our talks will be scheduled for Sunday the 5th February starting at 12:00 o'clock till 17:00 o'clock. + + +## Talks + + +### Kai-Uwe Behrmann: Colour Management in Compositors + + * type: ca. 45 minutes full length presentation and discussion (will run in the Xorg time frame) +Xorg allows compositors to run on efficient GPU hardware. It is possibly to deploy GPUs for low power consumption colour correction of the whole desktop. The talk will introduce in the topic by the [[CompICC|http://www.oyranos.org/compicc/]] colour server implementation and give a overview about used techniques and concepts. It will try to outline next generation desktop colour management and what is needed, from my point of view, to get colour management well supported in graphics servers and deployed by toolkits and applications. + + * [[Slides|http://www.oyranos.org/FOSDEM2012/ColourManagementInCompositors2012.pdf]] [[Audio|http://www.oyranos.org/FOSDEM2012/ColourManagementInCompositors.ogg]] + +### Kai-Uwe Behrmann and Peter Linnell: OpenICC - Colour Standards for Linux + + * type: ca. 45 minutes full length presentation and discussion +Who are the people behind [[OpenIcc|OpenIcc]] and what do they do for open source colour management? What are standards exist and are primarily maintained by [[OpenIcc|OpenIcc]] and what work is in progress? + + * [[Audio|http://www.oyranos.org/FOSDEM2012/OpenICC.ogg]] + +### Peter Linnell: Scribus + + * type: ca. 45 minutes full length presentation + * abstract: + * [[Audio|http://www.oyranos.org/FOSDEM2012/Scribus.ogg]] + +### Sirko Kemter: Call a Cab to bring the Colors - Taxi DB + + * type: ca. 25 minutes half length presentation and discussion + * abstract: Taxi DB is designed to store ICC device profiles and meta data online. What technology is used and how it works will be in the talk. + * [[Slides|http://www.oyranos.org/FOSDEM2012/taxidb.svg]] [[Audio|http://www.oyranos.org/FOSDEM2012/TaxiDB.ogg]] + +### Kai-Uwe Behrmann: Cross Platform Colour Management with Oyranos + + * type: ca. 25 minutes half length presentation and discussion +The Colour Management System exists since 2004 with a long history of new ideas for Linux ICC style Colour Management. Oyranos is well integrated in KDE and shipped with openSUSE. Find out what it does and what is hot. + + * [[Slides|http://www.oyranos.org/FOSDEM2012/Oyranos2012.pdf]] [[Audio|http://www.oyranos.org/FOSDEM2012/Oyranos.ogg]] + +### Chris Lilley: Color Management in SVG2 + + * type: ca. 45 minutes full length presentation and discussion + * abstract: SVG 1.1 is now widely implemented, and has some (minimal, optional) support for ICC colours. In the main though it is an sRGB system. SVG2 adds a conformance class for full ICC support (v2 and v4) including named colours, direct specification in LAB or LCHab, and interpolation in LAB or LCHab. Unmanaged device-specific colour is also supported. + * bio: Chris Lilley is Technical Director for the Interaction Domain at W3C. He is involved in SVG, CSS, and Web Fonts. + * [[Slides|http://www.oyranos.org/FOSDEM2012/ChrisLilley/cover-basic.svg]] [[Audio|http://www.oyranos.org/FOSDEM2012/SVG2.ogg]] + +## Contact + +* Personal email: ku dot b at gmx dot de +* Email: [[OpenICC email list at freedesktop.org|http://lists.freedesktop.org/mailman/listinfo/openicc]] +* IRC: oy on the OpenICC channel [[#openicc @ irc.freenode.net|irc://irc.freenode.net/openicc]]
\ No newline at end of file diff --git a/OpenIcc/Events/Hackfest/2012.mdwn b/OpenIcc/Events/Hackfest/2012.mdwn new file mode 100644 index 00000000..790e4dbf --- /dev/null +++ b/OpenIcc/Events/Hackfest/2012.mdwn @@ -0,0 +1,37 @@ + + +# Linux Color Management Hackfest 2012 + +* **What**: Linux Color Management Hackfest +* **Where**: Brno, Czech Republic, Europe @ [[Red Hat Czech office|http://maps.google.de/maps?q=RedHat+Brno&ie=UTF8&oe=utf-8&client=firefox-a&fb=1&gl=de&hq=RedHat&hnear=0x4712943ac03f5111:0x400af0f6614b1b0,Brünn,+Tschechische+Republik&cid=0,0,1379083089485248315&t=m&z=16&iwloc=A]] (the "old" building) +* **When**: 9th until 12th November 2012 +* **Why**: Get different applications from various free desktops together and move color management on them forward +* **Who**: S.Kemter [[gnokii@fedoraproject.org|mailto:gnokii@fedoraproject.org]] , [[ku.b@gmx.de|mailto:ku.b@gmx.de]] contact them for questions, [[jreznik@redhat.com|mailto:jreznik@redhat.com]] as local contact (place, travelling etc.) +* **Agenda**: Our main focuses are + * desktop applications, including window managers, + * web browsers and + * printing. +* These topics are already worked on, but in a scattered way. By meeting in person in one place, we want to get something done and build a good understanding of the role of each participating group for a working end to end color management. +* **Travel**: Brno has his own [[airport|http://www.airport-brno.cz]], but there are not many flights to it. There are direct flights from London/Stansted and Rome/Fiumicino and also Moscow. Another possibility to go to Brno would be the [[airport in Prague|http://www.prg.aero/en/]] and then to Brno with train or [[bus|http://jizdenky.studentagency.cz/?wicket:interface=:0:1:::]]. Another possibility is the [[airport in Vienna|http://www.viennaairport.com/]] and also with bus or train to Brno. +* A ticket for train costs from Prague arround 13€ and from Vienna arround 9€. Consider the bus, they are really comfortable and they have WLAN ;) +* **Public Transport**: for using the public transport buy a ticket for 100+101 zones, consider to buy a 5day ticket for CZK 250 (~9€). To get to the Red Hat office and A-Sport Hotel from Main Railway station or Grand Hotel Student Agency bus station, take a tram 12 or 13, direction to "Technologicky park". The tram stop is "Cervinkova", Red Hat office is on the left side, A-Sport Hotel close on the right. See the [[http://rezza.hofyland.cz/plan.png|http://rezza.hofyland.cz/plan.png]] . +* **Accomodation**: The main hackfest hotels are [[http://www.a-sporthotel.cz/hotel-brno-ubytovani/|http://www.a-sporthotel.cz/hotel-brno-ubytovani/]] and [[http://www.brno-hotel-avanti.eu/|http://www.brno-hotel-avanti.eu/]] . A-Sport Hotel booking is on "CM Hackfest" group. +* **Sponsoring**: OpenICC has as organization no budget, we try to win some sponsors, to re-imburse the travel costs. We can not guarantee that we can reimburse all travel costs! If you can be sponsored from another organization or your company, we would appreciate that. [[!table header="no" class="mointable" data=""" +**Participants** ||||||| +name | project | like to work on | need sponsoring | travel costs | need hotel | room share +Kai-Uwe Behrmann | Oyranos / OpenICC | display+toolkit+print CM | yes | 100 € | yes | yes +Sirko Kemter | OpenICC /taxiDB | colord and taxi | yes | 100 € | yes | yes +Jaroslav Reznik | Red Hat | local contact and some KDE | no | - | - | - +Richard Hughes | GNOME / colord | integration points | yes | 250 € | yes | Yes, if required +Till Kamppeter | OpenPrinting/Canonical | Color management in printing workflow | no | 200 € | yes | Yes, if required +Daniel Nicoletti | KDE / colord-kde | Color management for applications | yes | 1000 € | yes | Yes, if required +Casian Andrei | KDE / kwin | Color management and KDE | yes | 210 € | yes | yes +Øyvind Kolås | GIMP/GEGL/babl | the future | yes | 200 € | yes | Yes, if required +Chris Murphy | Color Remedies / OpenICC | CM in Linux | yes | ~1120 € | yes | no +John Layt | Qt/KDE | Printing | If available | €200 | yes | no +Daniel Jahre | taxiDB | taxi | no | €80 | yes | yes +Lukas Tinkl | KDE | KDE | no | no | no | no +Dan Vratil | KDE | KDE | no | no | no | no +David Tardon | [[LibreOffice|http://libreoffice.org]] | LO CM | no | no | no | no +Jan Grulich | Fedora | KDE | no | no | no | no +"""]] diff --git a/OpenIcc/GoogleSoC2009.mdwn b/OpenIcc/GoogleSoC2009.mdwn new file mode 100644 index 00000000..3228fcb5 --- /dev/null +++ b/OpenIcc/GoogleSoC2009.mdwn @@ -0,0 +1,342 @@ + +OpenIcc/GoogleSoC2009 Wiki is intended to collect ideas for possible projects participating in [[Googles Summer of Code program|http://code.google.com/soc/]]. They are mentored by members of [[OpenIcc|OpenIcc]] projects. + +OpenICC is a group of people dedicated to organise how applications, libraries, toolkits and colour devices talk each to the other about colours. The center of this work is the ICC specification, which is surounded be several general and operating system specific conventions to create a open sourced colour management system. + +Oyranos is a example implementation of mentioned conventions to cover ICC profile handling and colour conversions. The newBSD licensed code base is plain C with very few dependencies, namely libxml2 and Elektra. Goal is to use existing standard technology like XML, XFORMS and GLSL. Oyranos features a (almost) data independent framework to plug-in data manipulators, for colour conversions, tonemapping, image I/O and other operators into a data processing graph. + + +# About the Group + +[[OpenIcc|OpenIcc]] consist of the partipicants of the OpenICC email list. It was started by Scribus members to better support introduction of colour management into applications and discuss general issues. List contributors are application and CMS developers as well as colour management specialists and users, no matter whether commercial, open source and both. The main focus of this group is to expand the level of support for color management on open source software systems. + +[[!toc 2]] + + +# Project Suggestions + + +## Simple Toolkit Abstraction + +* The Oyranos colour management system is in parts only a thin layer between imaging applications and advanced moduls or plug-ins. To deploy these plug-ins flexible and maintain toolkit independency the plug-ins must present their UI in a own language. Goal is to create a simple and highly flexible GUI system, which allows easy creation of dialogs including callback meachanisms. This project lets you explore concepts like W3C XForms/DOM, and how to adapt it to traditional event driven programming. The result should be something simple and powerful enough to use for a wide range of applications not limited to Oyranos. Possibly this will result in a stand alone project. + +### Expectations + +* design and implement a minimalistic widget set, which allows easy implementation, exchange and processing (create a XForms profile, interact with DOM) +* write a interpreter for console applications as proof of concept +* write a HTML backend for documentation +* simple examples showing what is intented to work + +### Skills + +* clear and highly modular API design +* design of interactive applications +* good abstraction +* C, (C++), XML, DOM +* good communication + +### Contact + +* Mentor: , Advisor: Jon A. Cruz + +### Optional + +* allow some basic events and C callbacks +* write one or more toolkit dependent interpreter(s) (Gtk, Qt, Fltk ...) +* script bindings to Java/Python/? +* build a colour chooser based on the above widgets and callbacks + +## Sane configuration backend for Oyranos + +* Scanner devices can be described by ICC profiles. These profiles should be communicated alongside the normal communication pipeline. A module abstracting Sane details for ICC profile communication would make remote ICC profiles available for applications and configuration tools. + +### Expectations + +* work with SANE API's +* extend SANE to transport remote scanner informations to the Oyranos modul +* inline documentation + +### Skills + +* good communication skills (work with different parties) +* portable C + +### Contact + +* Student: Yiannis Belias <[[...@hol.gr|mailto:...@hol.gr]]> +* blog: [[http://orion.freehost.gr|http://orion.freehost.gr]] +* sources via: git clone git://github.com/yiannis/gsoc2009 +* Mentor: Kai-Uwe Behrmann < [[ku.b@gmx.de|mailto:ku.b@gmx.de]] > + +## GPhoto configuration backend for Oyranos + +* Camera devices can be described by ICC profiles. These profiles should be communicated alongside the normal communication pipeline. A module abstracting GPhoto and/or HAL details for ICC profile communication would make ICC profiles easily available for applications and configuration tools. + +### Expectations + +* work with GPhoto/Hal and Oyranos API's +* inline documentation + +### Skills + +* good communication skills (work with different parties) +* portable C + +### Contact + +* Student: Yiannis Belias <[[...@hol.gr|mailto:...@hol.gr]]> +* blog and sources as above +* Mentor: Kai-Uwe Behrmann < [[ku.b@gmx.de|mailto:ku.b@gmx.de]] > + +## Printer configuration backend for Oyranos + +* Print devices can be described by ICC profiles. These profiles should be communicated alongside the normal print pipeline. A module abstracting CUPS and other print spooler details for ICC profile communication would open the door of print previews for applications and configuration tools. + +### Expectations + +* work with CUPS API's +* extend CUPS to transport remote printer informations to the Oyranos modul +* inline documentation + +### Skills + +* good communication skills (work with different parties) +* portable C + +### Contact + +* Student: Joe Simon < [[j.sim...@astound.net|mailto:j.sim...@astound.net]] > +* Oyranos device backend sources via: git clone git://gitorious.org/oyranos_printer/oyranos_printer +* Kolor-Manager sources via: svn checkout svn://anonsvn.kde.org/home/kde/trunk/playground/graphics/kolor-manager +* Mentor: Kai-Uwe Behrmann < [[ku.b@gmx.de|mailto:ku.b@gmx.de]] > + +## GLSL meta backend for Oyranos + +* In order to build fast filters in Oyranos a meta backend is to be programmed. It should allow for fast manipulation of image data like colour conversions, tonemapping, blending or geometric transformations. + +### Expectations + +* study basic concepts of OpenGL shaders, their implementation in Mesa and the Oyranos CMM framework +* decide for a implementation concept +* work on existing code and integrate your implementation using most of the already available functionality, extent where needed +* documentation for users - should be very few + +### Skills + +* basic communication +* basic mathematical skills like matrix operations +* portable C and OpenGL shader programming + +### Contact + +* Mentor: Kai-Uwe Behrmann < [[ku.b@gmx.de|mailto:ku.b@gmx.de]] > +* [[OpenIcc|OpenIcc]] email list + +### Optional + +* convert the available small ICC colour transformation application for demonstration with colour table lookup into a shader plug-in + +## CMM's for Oyranos + +* SampleICC is the official implementation of the ICC colour profile standard from members of the [[ICC|http://www.color.org]]. A module of this engine to plug into Oyranos would be cool. + +### Expectations + + * wrap the [[SampleICC|http://sourceforge.net/projects/sampleicc/]] API into the Oyranos Colour Matching Module (CMM) API + * create a catalog of plug-in options to support by the CMM + * optimise SampleICC, allow unbound HDR conversions + +### Skills + +* good communication +* basic mathematical skills +* portable C++ and C + +### Contact + +* Mentor: Kai-Uwe Behrmann < [[ku.b@gmx.de|mailto:ku.b@gmx.de]] > + +## Oyranos Device Settings to ICC profile layer + +* Devices need to be introduced to a colour management system, in order to control the colour behaviour of a device. For instance different drivers may produce different colour on a otherwise identical device. A CMS needs some mechanism to connect colour influental device settings and driver informations and a particular colour profile reflecting these settings. ICC profiles containing such information would allow for automating many user decissions. +* Overview and informations: [[http://www.oyranos.org/wiki/index.php?title=Device_Settings|http://www.oyranos.org/wiki/index.php?title=Device_Settings]] +* Draft for new ICC colour profile tag: [[http://www.oyranos.org/wiki/index.php?title=Device_Settings_in_ICC_0.2|http://www.oyranos.org/wiki/index.php?title=Device_Settings_in_ICC_0.2]] (reading is implemented in Oyranos) + +### Expectations + +* create and implement a API for inclusion of driver specific data into ICC profiles in a generic way +* filter profiles according to theire included gerneric driver informations +* apply your API's to one device driver API, for instance Gutenprint, libopenraw or Sane to study their effects +* document the API usage + +### Skills + +* portable C +* be fit in compiling various libraries and applications + +### Contact + +* Mentor: Kai-Uwe Behrmann < [[ku.b@gmx.de|mailto:ku.b@gmx.de]] > + Robert Krawitz, ... + +## ICC Examin Library + +* ICC Examin is a profile analysing tool and colour visualiser. Many widgets are interesting to other applications. But they are written in FLTK and would be needed in an other toolkit in a modular fashion. This project instroduces in the process of effectively presenting various data. + +### Expectations + +* reorganise, modularise and rewrite parts of the existing project +* create an easy to use API and build a example application with it +* user documentation inline + +### Skills + +* portable C, C++, +* OpenGL would be helpful +* (Java/Python/?) + +### Contact + +* Mentor: possibly Kai-Uwe Behrmann < [[ku.b@gmx.de|mailto:ku.b@gmx.de]] > + +### Optional + +* create one wrapper in a scripting language for basic widgets, Python +* support profile editing +* support plug-ins, to display reports and various graphs +* support spectral data + +## Extending the Oyranos Colour Conversion Framework + +* The colour management system Oyranos provides high level means to render colours in a generic way. The advantage is, application developers can rely on Oyranos services without understanding the often complicated details. This project lets you create and optimise verious underpinnings of sytem level to advanced graphic tools. This project is a collection of many small and very versatile tasks. You can freely create a own plan what to do or will be guided according to your level of expertise. + +### Expectations + +* Possible targets: +* implement efficient pixel conversion between arbitrary buffer types (low level C) +* implement object observation to automatically update to data changes (object oriented C) +* adapt Oyranos devices to catch outside events (X, dbus, ...) +* add [[Create NamedColour|http://create.freedesktop.org/wiki/Swatches_-_colour_file_format]] format support +* implement OS specific CMS connectors to [[ColorSync|ColorSync]] and WCS (cross platform) +* analyse the concepts behind the Oyranos graphs and suggest means for complete data type abstraction (conceptual work) +* extent the Oyranos command line tools set (build upon Unix/Posix) +* build a small shiny graphical sample application (didactical GUI) +* agreed upon parts shall be finalised, substitution is possible + +### Skills + +* depends on what we agree to work on +* code organisation +* conceptual fitness +* good communication +* work under different OSes (possibly) +* basic to good C +* understanding object oriented designs is helpful + +### Contact + +* Mentor: Kai-Uwe Behrmann < [[ku.b@gmx.de|mailto:ku.b@gmx.de]] > + +## LProf - Finalize Qt4 port + +* LProf is an open source ICC profiler. It has recently been ported to Qt4 from Qt3. Although the port is working it still needs to have Qt3 support library calls removed. + +### Expectations + +* Systematically remove [[Qt3Support|Qt3Support]] calls from the LProf code base and replace these with pure Qt4 code. This is a significant undertaking and involves changes to just about every part of the UI code base for LProf. + +### Skills + +* General C++ programming skills +* Experience with C++ object oriented programming +* Experience with Qt a plus but not required (OJT) + +### Contact + +* Student: amit kumar < [[amit...@gmail.com|mailto:amit...@gmail.com]] > +* Get sources: cvs -d:pserver:[[anonymous@lprof.cvs.sourceforge.net|mailto:anonymous@lprof.cvs.sourceforge.net]]:/cvsroot/lprof login + * cvs -z3 -d:pserver:[[anonymous@lprof.cvs.sourceforge.net|mailto:anonymous@lprof.cvs.sourceforge.net]]:/cvsroot/lprof co -r GSoC-2009 -P lprof +* Mentor: Hal V. Engel < [[hvengel@astound.net|mailto:hvengel@astound.net]] > + +## LProf - Add DDC/CI and USB HID Monitor Controls for Monitor Calibration + +* LProf is an open source ICC profiler. This project will add DDC/CI and HID USB monitor controls support to the current monitor calibration functionality. This will allow the software to automatically make monitor adjustments during calibration so that users do not have to make manual adjustments to their monitors. + +### Expectations + +Implement DDC/CI and/or USB HID Monitor Control support in LProf. This will need to work in a broad range of platforms including *nix/X11, Windows (2000 and later) and OS/X. +### Skills + +* General C/C++ programming skills +* Some background in EDID and/or DDC +* Ability to work in a cross platform environment. This will need to work for *nix/ Windows and OS/X machines. + +### Contact + +* Mentor: Hal V. Engel < [[hvengel@astound.net|mailto:hvengel@astound.net]] > + +## LProf - Add a Regression Analysis Based Monitor Profiling. + +* LProf is an open source ICC profiler. LProf now has the ability to use various measurement instruments to take measurements for profiling monitors of various types. Currently the profiling algorithms are very simple ones and this needs to be corrected. + +### Expectations + +This project will implement a regression analysis algorithm for monitor profiling. +### Skills + +* General C/C++ programming skills +* An understanding of 3D regression anaysis +* An understanding of ICC profiles + +### Contact + +* Mentor: Hal V. Engel < [[hvengel@astound.net|mailto:hvengel@astound.net]] > + +## LProf - Create a Robust Interative Video Card LUT Creation Algorithm. + +* LProf is an open source ICC profiler. LProf now has the ability to use various measurement instruments to take measurements for profiling monitors of various types. Currently the video card LUT creation algorithms are very simple ones and this needs to be corrected. + +### Expectations + +This project will implement a robust interative video card LUT calibration algorithm and will be integrated into the LProf UI. +### Skills + +* General C/C++ programming skills +* An understanding of 3D regression anaysis +* An understanding of ICC profiles + +### Contact + +* Mentor: Hal V. Engel < [[hvengel@astound.net|mailto:hvengel@astound.net]] > + +# Alternative Ideas + +Feel free to propose and discuss your ideas. + + +# Requirements + + +## License + +BSD, LGPL extended by allowing for static linking are preferred licenses for libraries. GPL and other open source licenses are acceptable for other projects but in most cases the project mentor will specify the license to be used for the project. + + +## Skills + +Both good project and coding skills are expected, in order to set up our complex open source projects. We know it is sometimes difficult to talk to people you do not know, especially when they are not visible like over the internet. Nevertheless the mentors of these OpenICC projects want an open dialog with anyone interested in working on these projects. This is an important part of open software development and it is even more important for these Google Summer of Code Projects. Please feel free to contact any of the mentors listed above at any time. The earlier a candidate contacts us the more time remains for getting a feeling of the projects in advance. + + +## Developers Environment + +You are free to select whatever build environment you like as long as the project is targeted at that platform. Many of the above projects are targeted at Unix like systems and a few are fully cross platform. Our experience for cross platform projects is that some build environments are more difficult to setup than others. You will also likely find that these projects are significantly more complex than your school projects. For example, the LProf code base is now almost 100,000 lines of C and C++ code. + +In order to help candidates be successful in completing their projects it is important that anyone selected is prepared to start actual project work at the project startup date. Please be prepared to have your development environment ready long before the project starts. This means that project mentors will want you to be to able to build and run the base system you are working on well before the project start date. For example, if you are working on one of the LProf projects you should be able to build and run LProf on your development machine at least a month before the project startup date. Windows build environments, in particular, have proven to be particularly difficult to setup and it is common for GSoC mentors to comment about how often the single biggest difficultly for students working on Wndows machines is getting a fully functional build environment setup. + +Many open source developers use a unix like environment (IE. Linux, BSD ...) in part because setting up a working build environments is much simpler. This also means that there is a high likely hood that your mentor will not have much experience working in Windows or OS/X and may not be able to provide much assistance to help you get your builds working in those environments. So take this very seriously. On the other hand using a Unix like system like BSD/Linux/osX/Solaris can be a great learning experience for any student who has not worked on one of these in the past. Many big projects run on *nix systems deploying unix concepts and some of the projects listed above are *nix only projects that can not be worked on using a Windows machine. On request we simply expect the programmer to switch to BSD, Linux or osX. The installation should be no issue. + + +# Communication + +The [[OpenIcc|OpenIcc]] list and the mentors for the above projects are all open for having contact with any prospective candidate. We will use a additional public list dedicated to the GSoC projects communication. IRC: freenode#openicc + +For any uncovered toppics related to the GSoC project please contact Kai-Uwe Behrmann < [[ku.b@gmx.de|mailto:ku.b@gmx.de]] >. diff --git a/OpenIcc/GoogleSoC2010.mdwn b/OpenIcc/GoogleSoC2010.mdwn new file mode 100644 index 00000000..91c43acb --- /dev/null +++ b/OpenIcc/GoogleSoC2010.mdwn @@ -0,0 +1,314 @@ + +OpenIcc/GoogleSoC2010 Wiki is intended to collect ideas for possible projects participating in [[Googles Summer of Code program|http://code.google.com/soc/]]. They are mentored by members of [[OpenIcc|OpenIcc]] projects. + +OpenICC is a group of people dedicated to organise how applications, libraries, toolkits and colour devices talk each to the other about colours. The center of this work is the ICC specification, which is surounded be several general and operating system specific conventions to create a open sourced colour management system. + +Oyranos is a example implementation of mentioned conventions to cover ICC profile handling and colour conversions. The newBSD licensed code base is plain C. Its core requires very few dependencies, namely libxml2. Device support and colour conversions involve according APIs. Goal is to use existing standard technology like XML, XFORMS and GLSL. Oyranos features a (almost) data independent framework to plug-in data manipulators, for colour conversions, tonemapping, image I/O and other operators into a data processing graph. + + +# About the Group + +[[OpenIcc|OpenIcc]] consist of the participants of the OpenICC email list. It was started by Scribus members to better support introduction of colour management into applications and discuss general issues. List contributors are application and CMS developers as well as colour management specialists and users, no matter whether commercial, open source and both. The main focus of this group is to expand the level of support for color management on open source software systems. + +[[!toc 2]] + + +# Project Suggestions + + +## Simple Toolkit Abstraction + +* The Oyranos colour management system is in parts only a thin layer between imaging applications and advanced moduls or plug-ins. To deploy these plug-ins flexible and maintain toolkit independency the plug-ins must present their UI in a own language. Goal is to create a simple and highly flexible GUI system, which allows easy creation of dialogs including callback meachanisms. This project lets you explore concepts like W3C XForms/DOM, and how to adapt it to traditional event driven programming. The result should be something simple and powerful enough to use for a wide range of applications not limited to Oyranos. Possibly this will result in a stand alone project. + +### Expectations + +* design and implement a minimalistic widget set, which allows easy implementation, exchange and processing (create a XForms profile, interact with DOM) +* write a interpreter for console applications as proof of concept +* write a HTML backend for documentation +* simple examples showing what is intented to work + +### Skills + +* clear and highly modular API design +* design of interactive applications +* good abstraction +* C, (C++), XML, DOM +* good communication + +### Contact + +* Mentor: , Advisor: Jon A. Cruz + +### Optional + +* allow some basic events and C callbacks +* write one or more toolkit dependent interpreter(s) (Gtk, Qt, Fltk ...) +* script bindings to Java/Python/? +* build a colour chooser based on the above widgets and callbacks + +## Oyranos Device Settings to ICC profile layer + +* Devices need to be introduced to a colour management system, in order to control the colour behaviour of a device. For instance different drivers may produce different colour on a otherwise identical device. A CMS needs some mechanism to connect colour influental device settings and driver informations and a particular colour profile reflecting these settings. ICC profiles containing such information would allow for automating many user decissions. +* Overview and informations: [[http://www.oyranos.org/wiki/index.php?title=Device_Settings|http://www.oyranos.org/wiki/index.php?title=Device_Settings]] +* implement based on a ICC confirmed proposal +* Draft for new ICC colour profile tag: [[http://www.oyranos.org/wiki/index.php?title=Device_Settings_in_ICC_0.2|http://www.oyranos.org/wiki/index.php?title=Device_Settings_in_ICC_0.2]] (reading is implemented in Oyranos) + +### Expectations + +* create and implement a API for inclusion of driver specific data into ICC profiles in a generic way +* filter profiles according to theire included gerneric driver informations +* apply your API's to one device driver API, for instance Gutenprint, libopenraw or Sane to study their effects +* write a command line tool for use by end users including a manual page +* document the API usage + +### Skills + +* portable C +* be fit in compiling various libraries and applications + +### Contact + +* Mentor: Kai-Uwe Behrmann < [[ku.b@gmx.de|mailto:ku.b@gmx.de]] > + Robert Krawitz, ... + +## GLSL-/+OpenCL meta backend for Oyranos + +* In order to build fast filters in Oyranos a meta backend is to be programmed. It should allow for fast manipulation of image data like colour conversions, tonemapping, blending or geometric transformations.. + +### Expectations + +* study basic concepts of OpenGL shaders, their implementation in Mesa and the Oyranos CMM framework +* decide for a implementation concept (GLSL/OpenCL) +* work on existing code and integrate your implementation using most of the already available functionality, extent where needed +* documentation for users - should be very few + +### Skills + +* basic communication +* basic mathematical skills like matrix operations +* portable C and OpenGL shader programming + +### Contact + +* Mentor: Kai-Uwe Behrmann < [[ku.b@gmx.de|mailto:ku.b@gmx.de]] > +* [[OpenIcc|OpenIcc]] email list + +### Optional + +* convert the available small ICC colour transformation application for demonstration with colour table lookup into a shader plug-in + +## CMM's for Oyranos + +* SampleICC is the official implementation of the ICC colour profile standard from members of the [[ICC|http://www.color.org]]. A module of this engine to plug into Oyranos would be cool. Lcms2 will be soon released and replace the work horse lcms. Oyranos needs a updated module to continue to provide a actual CMM. + +### Expectations + + * wrap the [[SampleICC|http://sourceforge.net/projects/sampleicc/]] API into the Oyranos Colour Matching Module (CMM) API + * create a lcms2 module based on the already existing one + * create a catalog of plug-in options to support by the CMM + * optimise SampleICC, allow unbound HDR conversions + * work out test and quality assurance strategies + +### Skills + +* good communication +* basic mathematical skills +* portable C++ and C + +### Contact + +* Mentor: Kai-Uwe Behrmann < [[ku.b@gmx.de|mailto:ku.b@gmx.de]] > + +## ICC Examin Library + +* ICC Examin is a profile analysing tool and colour visualiser. Many widgets are interesting to other applications. But they are written in FLTK and would be needed in an other toolkit in a modular fashion. This project instroduces in the process of effectively presenting various data. + +### Expectations + +* reorganise, modularise and rewrite parts of the existing project +* create an easy to use API and build a example application with it +* user documentation inline + +### Skills + +* portable C, C++, +* OpenGL would be helpful +* (Java/Python/?) + +### Contact + +* Student: Joe Simon < [[j.sim...@astound.net|mailto:j.sim...@astound.net]] > +* email list: [[https://lists.sourceforge.net/lists/listinfo/oyranos-devel|https://lists.sourceforge.net/lists/listinfo/oyranos-devel]] +* www: [[http://jsimon3.wordpress.com/|http://jsimon3.wordpress.com/]] + * [[http://twitter.com/jsimonGSoC|http://twitter.com/jsimonGSoC]] +* Mentor: Kai-Uwe Behrmann < [[ku.b@gmx.de|mailto:ku.b@gmx.de]] > + +### Optional + +* create one wrapper in a scripting language for basic widgets, Python +* support profile editing +* support plug-ins, to display reports and various graphs +* support spectral data + +## Extending the Oyranos Colour Conversion Framework + +* The colour management system Oyranos provides high level means to render colours in a generic way. The advantage is, application developers can rely on Oyranos services without understanding the often complicated details. This project lets you create and optimise verious underpinnings of sytem level to advanced graphic tools. This project is a collection of many small and very versatile tasks. You can freely create a own plan what to do or will be guided according to your level of expertise. + +### Expectations + +* Possible targets: +* implement efficient pixel conversion between arbitrary buffer types (low level C) +* implement object observation to automatically update to data changes (object oriented C) +* adapt Oyranos devices to catch outside events (X, dbus, ...) +* add [[Create NamedColour|http://create.freedesktop.org/wiki/Swatches_-_colour_file_format]] format support +* implement OS specific CMS connectors to [[ColorSync|ColorSync]] and WCS (cross platform) +* analyse the concepts behind the Oyranos graphs and suggest means for complete data type abstraction (conceptual work) +* extent the Oyranos command line tools set (build upon Unix/Posix) +* build a small shiny graphical sample application (didactical GUI) +* agreed upon parts shall be finalised, substitution is possible + +### Skills + +* depends on what we agree to work on +* code organisation +* conceptual fitness +* good communication +* work under different OSes (possibly) +* basic to good C +* understanding object oriented designs is helpful + +### Contact + +* Mentor: Kai-Uwe Behrmann < [[ku.b@gmx.de|mailto:ku.b@gmx.de]] > + +## API stabilization for Oyranos Colour Management System + +* Currently, Oyranos has a big part of it's API in an alpha state. That includes the object oriented part, modules and devices API. The objective of this project is to work on the necessary parts of oyranos, so that by the end of summer, at least the most wanted functionalities will have a stable API/ABI and be ready for wider use. Following APIs are a good target: +* Miscellaneous->Generic Objects +* Miscellaneous->Values Handling +* Module APIs +* Device API +* Profile API +* Named Colour API + +### Expectations + +* an object oriented C API with compile time safety (API and ABI wise) +* enough transparency for common debuggers as it is provided now and for new +* flexibility for further development + +### Contact + +* Student: Yiannis Belias <[[...@hol.gr|mailto:...@hol.gr]]> +* sources via: git clone git://github.com/yiannis/gsoc2010 +* email list: [[https://lists.sourceforge.net/lists/listinfo/oyranos-devel|https://lists.sourceforge.net/lists/listinfo/oyranos-devel]] +* Mentor: Kai-Uwe Behrmann < [[ku.b@gmx.de|mailto:ku.b@gmx.de]] > + +## Kwin colour correction plugin + +* The compiz colour correction plugin is very useful for instant colour corrections including movies with minimal overhead. Port this idea to KDE's kwin. It will be almost a write from scratch. Due to a controversial discussion on the OpenICC email list the project is unlikely to be chosen until a reasonable consense is found. + +### Expectations + +* create a scheme before you implement and discuss it +* write a OpenGL shader based plugin +* work with kwin, Oyranos, OpenGL/Shaders +* inline documentation + +### Skills + +* C++ +* good communication +* Shader language + +### Contact + +* Mentor: Kai-Uwe Behrmann < [[ku.b@gmx.de|mailto:ku.b@gmx.de]] > + +### Optional + +* port the compiz plugin to v0.9 from C to C++ +* add grid and image based correction textures + +## LProf - Add DDC/CI and USB HID Monitor Controls for Monitor Calibration + +* LProf is an open source ICC profiler. This project will add DDC/CI and HID USB monitor controls support to the current monitor calibration functionality. This will allow the software to automatically make monitor adjustments during calibration so that users do not have to make manual adjustments to their monitors. + +### Expectations + +Implement DDC/CI and/or USB HID Monitor Control support in LProf. This will need to work in a broad range of platforms including *nix/X11, Windows (2000 and later) and OS/X. +### Skills + +* General C/C++ programming skills +* Some background in EDID and/or DDC +* Ability to work in a cross platform environment. This will need to work for *nix/ Windows and OS/X machines. + +### Contact + +* Mentor: Hal V. Engel < [[hvengel@astound.net|mailto:hvengel@astound.net]] > + +## LProf - Add a Regression Analysis Based Monitor Profiling. + +* LProf is an open source ICC profiler. LProf now has the ability to use various measurement instruments to take measurements for profiling monitors of various types. Currently the profiling algorithms are very simple ones and this needs to be corrected. + +### Expectations + +This project will implement a regression analysis algorithm for monitor profiling. +### Skills + +* General C/C++ programming skills +* An understanding of 3D regression anaysis +* An understanding of ICC profiles + +### Contact + +* Mentor: Hal V. Engel < [[hvengel@astound.net|mailto:hvengel@astound.net]] > + +## LProf - Create a Robust Interative Video Card LUT Creation Algorithm. + +* LProf is an open source ICC profiler. LProf now has the ability to use various measurement instruments to take measurements for profiling monitors of various types. Currently the video card LUT creation algorithms are very simple ones and this needs to be corrected. + +### Expectations + +This project will implement a robust interative video card LUT calibration algorithm and will be integrated into the LProf UI. +### Skills + +* General C/C++ programming skills +* An understanding of 3D regression anaysis +* An understanding of ICC profiles + +### Contact + +* Mentor: Hal V. Engel < [[hvengel@astound.net|mailto:hvengel@astound.net]] > + +# Alternative Ideas + +Feel free to propose and discuss your ideas. + + +# Requirements + + +## License + +BSD, LGPL extended by allowing for static linking are preferred licenses for libraries. GPL and other open source licenses are acceptable for other projects but in most cases the project mentor will specify the license to be used for the project. + + +## Skills + +Both good project and coding skills are expected, in order to set up our complex open source projects. We know it is sometimes difficult to talk to people you do not know, especially when they are not visible like over the internet. Nevertheless the mentors of these OpenICC projects want an open dialog with anyone interested in working on these projects. This is an important part of open software development and it is even more important for these Google Summer of Code Projects. Please feel free to contact any of the mentors listed above at any time. The earlier a candidate contacts us the more time remains for getting a feeling of the projects in advance. + + +## Developers Environment + +You are free to select whatever build environment you like as long as the project is targeted at that platform. Many of the above projects are targeted at Unix like systems and a few are fully cross platform. Our experience for cross platform projects is that some build environments are more difficult to setup than others. You will also likely find that these projects are significantly more complex than your school projects. For example, the LProf code base is now almost 100,000 lines of C and C++ code. + +In order to help candidates be successful in completing their projects it is important that anyone selected is prepared to start actual project work at the project startup date. Please be prepared to have your development environment ready long before the project starts. This means that project mentors will want you to be to able to build and run the base system you are working on well before the project start date. For example, if you are working on one of the LProf projects you should be able to build and run LProf on your development machine at least a month before the project startup date. Windows build environments, in particular, have proven to be particularly difficult to setup and it is common for GSoC mentors to comment about how often the single biggest difficultly for students working on Wndows machines is getting a fully functional build environment setup. + +Many open source developers use a unix like environment (IE. Linux, BSD ...) in part because setting up a working build environments is much simpler. This also means that there is a high likely hood that your mentor will not have much experience working in Windows or OS/X and may not be able to provide much assistance to help you get your builds working in those environments. So take this very seriously. On the other hand using a Unix like system like BSD/Linux/osX/Solaris can be a great learning experience for any student who has not worked on one of these in the past. Many big projects run on *nix systems deploying unix concepts and some of the projects listed above are *nix only projects that can not be worked on using a Windows machine. On request we simply expect the programmer to switch to BSD, Linux or osX. The installation should be no issue. + + +# Communication + +The [[OpenIcc|OpenIcc]] list and the mentors for the above projects are all open for having contact with any prospective candidate. We will use a additional public list dedicated to the GSoC projects communication. IRC: freenode#openicc + +For any uncovered toppics related to the GSoC project please contact Kai-Uwe Behrmann < [[ku.b@gmx.de|mailto:ku.b@gmx.de]] >. diff --git a/OpenIcc/GoogleSoC2011.mdwn b/OpenIcc/GoogleSoC2011.mdwn new file mode 100644 index 00000000..83ec6b28 --- /dev/null +++ b/OpenIcc/GoogleSoC2011.mdwn @@ -0,0 +1,354 @@ + +OpenIcc/GoogleSoC2011 Wiki is intended to collect ideas for possible projects participating in [[Googles Summer of Code program|http://code.google.com/soc/]]. [[Google Summer of Code|http://www.google-melange.com/document/show/gsoc_program/google/gsoc2011/timeline]] timeline is online. + +OpenICC wants to bring colour management programming themes to the audience of students. Goal is to understand open source programming and learn how to effectively interact with and contribute to a project in an intercultural environment. + +OpenICC is a group of people dedicated to organise how applications, libraries, toolkits and colour devices talk each to the other about colours. The center of this work is the ICC specification, which is surrounded by several general and operating system specific conventions to create a easy to use open sourced colour management system for naive and experienced users. + +Oyranos is a example implementation of mentioned conventions to cover ICC profile handling and colour conversions. The newBSD licensed code base is plain C. Its core requires very few dependencies, namely libxml2. Device support and colour conversions involve according APIs. Goal is to use existing standard technology like XML, XFORMS and GLSL. Oyranos features a (almost) data independent framework to plug-in data manipulators, for colour conversions, tonemapping, image I/O and other operators into a data processing graph. + +GNOME Color Manager is another CMS framework, similar to oyranos. The heavy use of GTK, GLib and DBus means that GCM can integrate deeplying into the GNOME desktop. GCM provides a user-accessable interface to the low level colord system daemon, and also provides a application-accessable DBusi interface for user preferences and session policy. GNOME Color Manager is included by default on the GNOME desktop and is already installed on several millions of computers worldwide. + + +# About the Group + +[[OpenIcc|OpenIcc]] consist of the participants of the OpenICC email list. It was started by Scribus members to better support introduction of colour management into applications and discuss general issues. List contributors are application and CMS developers as well as colour management specialists and users, no matter whether commercial, open source and both. The main focus of this group is to expand the level of support for color management on open source software systems. + +[[!toc 2]] + + +# Project Suggestions + + +## Colour Management for Common Printing Dialog + +* Artists and Pro Users want to configure custom ICC profiles. This should be simple and easy. The CPD is the ideal place to let user interact in a intuitive way. Oyranos will ensure a very robust configuration of ICC device profiles. OpenUsability, OpenPrinting and OpenICC outlined a concept on how to best integrate colour management into the Common Printing Dialog (CPD). + +### Expectations + +* add profile selector to CPD +* use Oyranos device APIs to assign a ICC profile +* add few user visible options +* use Poppler/Ghostscript renderers for ICC profile in PDF +* add robust checking for correct functionality +* careful coding and comments +* end user documentation + +### Skills + +* rather simple programming task +* good communication +* C++, C, shell +* git + +### Contact + +* Student: Joseph Simon <jsimon383 at gmail dot com> +* blog: [[http://jsimon3.wordpress.com|http://jsimon3.wordpress.com]] +* twitter: [[http://twitter.com/#!/joe_devel|http://twitter.com/#!/joe_devel]] +* code: [[https://www.gitorious.org/google-summer-of-code-2011/xcpd|https://www.gitorious.org/google-summer-of-code-2011/xcpd]] +* Mentor: Kai-Uwe Behrmann + +## Colour Configuration Data Base + +* Users, who configure their colour management system (CMS) behaviour and devices, want to share these settings on one host without any intervention among installed CMSes. The project will provide the basic design and a implementation to access and manipulate the data base. CMSes like ArgyllCMS, Oyranos and colord want to use the common format and in parts the provided tools. + +### Expectations + +* POSIX C +* basic settings like rendering intent, default profiles as in Oyranos and GCM +* device + driver settings to ICC profile association +* DB layout +* a in close relation to existing work +* b together with the community +* c designed to be a easily accessible through DBus +* d scalable +* careful API design, coding and comments +* search optimisation +* end user documentation +* MIT license + +### Skills + +* rather simple programming task +* good communication +* C, JSON, make +* git + +### Contact + +* Mentor: Kai-Uwe Behrmann +* Further Advisors: OpenICC email list + +## Simple Toolkit Abstraction + +* The Oyranos colour management system is in parts only a thin layer between imaging applications and advanced moduls or plug-ins. To deploy these plug-ins flexible and maintain toolkit independency the plug-ins must present their UI in a own language. Goal is to create a simple and highly flexible GUI system, which allows easy creation of dialogs including callback meachanisms. This project lets you explore concepts like W3C XForms/DOM, and how to adapt it to traditional event driven programming. The result should be something simple and powerful enough to use for a wide range of applications not limited to Oyranos. Possibly this will result in a stand alone project. + +### Expectations + +* design and implement a minimalistic widget set, which allows easy implementation, exchange and processing (create a XForms profile, interact with DOM) +* write a interpreter for console applications as proof of concept +* write a HTML backend for documentation +* simple examples showing what is intented to work + +### Skills + +* clear and highly modular API design +* design of interactive applications +* good abstraction +* C, (C++), XML, DOM +* good communication + +### Contact + +* Mentor: Kai-Uwe Behrmann , Advisor: Jon A. Cruz + +### Optional + +* allow some basic events and C callbacks +* write one or more toolkit dependent interpreter(s) (Gtk, Qt, Fltk ...) +* script bindings to Java/Python/? +* build a colour chooser based on the above widgets and callbacks + +## OpenGTL-/+OpenCL meta backend for Oyranos + +* In order to build fast filters in Oyranos a meta backend is to be programmed. It should allow for fast manipulation of image data like colour conversions, tonemapping, blending or geometric transformations. + +### Expectations + +* study basic concepts of OpenCL shaders, their implementation in Mesa and the Oyranos CMM framework +* decide for a implementation concept (OpenGTL/OpenCL) +* work on existing code and integrate your implementation using most of the already available functionality, extent where needed +* documentation for users - should be very few + +### Skills + +* basic communication +* portable C and C++ programming + +### Contact + +* Mentor: Kai-Uwe Behrmann < [[ku.b@gmx.de|mailto:ku.b@gmx.de]] > +* [[OpenIcc|OpenIcc]] email list + +### Optional + +* convert the available small ICC colour transformation application for demonstration with colour table lookup into a shader plug-in + +## CMM's for Oyranos + +* SampleICC is the official implementation of the ICC colour profile standard from members of the [[ICC|http://www.color.org]]. A module of this engine to plug into Oyranos would be cool. An other candidate is ArgyllCMS, which features very sophisticated colour transformations. + +### Expectations + + * wrap the [[SampleICC|http://sourceforge.net/projects/sampleicc/]] API into the Oyranos Colour Matching Module (CMM) API + * wrap the [[http://www.argyllcms.com|http://www.argyllcms.com]] into the Oyranos Colour Matching Module (CMM) API + * create a catalog of plug-in options supported by the CMM + * work out test and quality assurance strategies + +### Skills + +* good communication +* basic mathematical skills +* portable C++ and C + +### Contact + +* Mentor: Kai-Uwe Behrmann < [[ku.b@gmx.de|mailto:ku.b@gmx.de]] > + +## AICC Library + +* ICC Examin is a profile analysing tool and colour visualiser. Many widgets are interesting to other applications and would be needed in other toolkits in a modular fashion. The AICC project started to implement parts of ICC Examin in C. This project aims at effectively presenting various data as text, graphics and in part in 3D. + +### Expectations + +* continue the AICC project [[http://gitorious.org/gsoc10_openicc|http://gitorious.org/gsoc10_openicc]] +* create a 3D view of gamut +* support 2D output of ICC tag informations +* example application +* user documentation inline + +### Skills + +* POSIX C +* OpenGL +* (Java/Python/?) + +### Contact + +* Mentor: Kai-Uwe Behrmann + +### Optional + +* create one wrapper in a scripting language for basic widgets, Python +* support profile editing +* support plug-ins, to display reports and various graphs +* support spectral data + +## Extending the Oyranos Colour Conversion Framework + +* The colour management system Oyranos provides high level means to render colours in a generic way. The advantage is, application developers can rely on Oyranos services without understanding the often complicated details. This project lets you create and optimise various underpinnings of system level to advanced graphic tools. This project is a collection of many small and very versatile tasks. You can freely create a own plan what to do or will be guided according to your level of expertise. + +### Expectations + +* Possible targets: +* implement efficient pixel conversion between arbitrary buffer types (low level C) +* implement object observation to automatically update to data changes (object oriented C) +* adapt Oyranos devices to catch outside events (X, dbus, ...) +* add [[Create NamedColour|http://create.freedesktop.org/wiki/Swatches_-_colour_file_format]] format support +* implement OS specific CMS connectors to [[ColorSync|ColorSync]] and WCS (cross platform) +* analyse the concepts behind the Oyranos graphs and suggest means for complete data type abstraction (conceptual work) +* extent the Oyranos command line tools set to access device and other settings (build upon Unix/Posix) +* build a small shiny graphical sample application (didactical GUI) +* agreed upon parts shall be finalised, substitution is possible + +### Skills + +* depends on what we agree to work on +* code organisation +* conceptual fitness +* good communication +* work under different OSes (possibly) +* basic to good C +* understanding object oriented designs is helpful + +### Contact + +* Mentor: Kai-Uwe Behrmann < [[ku.b@gmx.de|mailto:ku.b@gmx.de]] > + +## API stabilization for Oyranos Colour Management System II + +* Currently, Oyranos has a big part of it's API in an alpha state. That includes the object oriented part, modules and devices API. The objective of this project is to work on the necessary parts of Oyranos, so that by the end of summer, at least the most wanted functionalities will have a stable API/ABI and be ready for wider use. Following APIs are good targets: +* Module APIs +* Device API +* Profile API +* Named Colour API + +### Expectations + +* an object oriented C API with compile time safety (API and ABI wise) +* enough transparency for common debuggers as it is provided now and for new +* flexibility for further development +* add test cases along the transition process +* adapt the inline documentation to changes + +### Skills + +* C +* good communication + +### Contact + +* Student: Yiannis Belias <jonnyb at hol dot gr> +* email list: [[https://lists.sourceforge.net/lists/listinfo/oyranos-devel|https://lists.sourceforge.net/lists/listinfo/oyranos-devel]] +* code: [[https://github.com/yiannis/Oyranos|https://github.com/yiannis/Oyranos]] +* Mentor: Kai-Uwe Behrmann < [[ku.b@gmx.de|mailto:ku.b@gmx.de]] > + +## Kwin colour correction plugin + +* The compiz colour correction plugin is very useful for instant colour corrections including movies with minimal overhead. Port this idea to KDE's kwin. It will be almost a write from scratch. Due to a controversial discussion on the OpenICC email list the project is unlikely to be chosen until a reasonable consense is found. + +### Expectations + +* create a scheme before you implement and discuss it +* write a OpenGL shader based plugin +* work with kwin, Oyranos, OpenGL/Shaders +* inline documentation + +### Skills + +* C++ +* good communication +* Shader language + +### Contact + +* Mentor: Kai-Uwe Behrmann < [[ku.b@gmx.de|mailto:ku.b@gmx.de]] >, Advisors: KWin project + +### Optional + +* port the compiz plugin to v0.9 from C to C++ +* add grid and image based correction textures + +## Native display profiling + +* GNOME Color Manager provides a easy to use front-end to the colord management layer. As such it is responsible for creating and applying ICC profiles in the running user session. GNOME Color Manager is part of GNOME, and such is shipped by default in several large distros and is already installed on millions of computers all over the world. At the moment GCM is using argyllcms to control the colorimeter devices and again using argyllcms to create the display profile from the gathered results. +* Users want a quicker and more streamlined profiling experience, with things like ambient light adjustment and a profile that takes 30 seconds to generate, not 5 minutes. Users don't want to be dealing with constant popups and odd questioms just to profile the screen. +* By using the GCM native colorimeter drivers (only pantone huey supported at the moment) we can provide a GNOME-specific integrated experience that can create good profiles in tens of seconds. In doing so, we can also remove the various VTE windows, pop-up dialogs and the twisted and complicated argyll spawned interface code. This also means we can ship a calibration solution in enterprise-class distros without legal worries. + +### Expectations + +* Use the existing native driver to create some native data interchange format (IT8?). Use the native data format to create a simple ICC profile containing elements such as VCGT to change the display temperature. There is some proof of concept code based on lprof in existance, but nothing that's even comparable in quality to the argyll generated profiles. +* The code should be tested and merged to git master before the project is complete. + +### Skills + +* C coding, hopefully with GTK and GLib knowledge. +* Good solid mathematic grounding. +* Knowledge of the internal structure of ICC profiles, and in particular understanding of elements like AtoB tables and VCGT data. +* Access to IRC and being able to speak good English. + +### Contact + +* Mentor: Richard Hughes + +### Optional + +* Improve the design and workflow of the calibration process for other devices, such as printers, scanners and cameras. +* Device driver work on other colorimeters. + +## A Color Managed Mutter + +* Mutter is the new window manager for GNOME3. Mutter is a fully composting manager, which means it has access to the GPU 3D engine. This allows us to do full screen color managed correction using a hardware GLSL shader to do the correction in near-real time for selected widgets. +* I have already written proof of concept code adding this functionality into mutter, but it requires bug fixing, interfacing with the DBUS interface of GNOME Color Manager and also with the lower parts of the stack like GTK. + +### Expectations + +* A patch suitable for upstream for mutter than can color manage displays similar to compiz colour correction plugin designed by Kai-Uwe Behrmann, but letting applications opt-in, rather than declare regions to be opted out. + +### Skills + +* C coding, hopefully with GL, GTK, GLib and DBus knowledge. +* Access to IRC and being able to speak good English. +* Experience filing bugs with patches for upstream projects. + +### Contact + +* Mentor: Richard Hughes + +### Optional + +* Integration with GTK, to be able to turn on color management for specific widgets in a window. This would require some kind of marshalling between GTK and mutter, possibly using the net-color-spec. + +# Alternative Ideas + +Feel free to propose and discuss your ideas. We highly appreciate your initiative. It is possible to give multiple proposals. Be warned each proposal needs typical time to prepare. The quality of the proposals counts for us to become able to decide. + + +# Requirements + + +## License + +BSD, LGPL extended by allowing for static linking are preferred licenses for libraries. GPL and other open source licenses are acceptable for other projects but in most cases the project mentor will specify the license to be used for the project. + + +## Skills + +Both good project and coding skills are expected, in order to set up our complex open source projects. We know it is sometimes difficult to talk to people you do not know, especially when they are not visible like over the internet. Nevertheless the mentors of these OpenICC projects want an open dialog with anyone interested in working on these projects. This is an important part of open software development and it is even more important for these Google Summer of Code Projects. Please feel free to contact any of the mentors listed above at any time. The earlier a candidate contacts us the more time remains for getting a feeling of the projects in advance. + + +## Developers Environment + +You are free to select whatever build environment you like as long as the project is targeted at that platform. Many of the above projects are targeted at Unix like systems and a few are fully cross platform. Our experience for cross platform projects is that some build environments are more difficult to setup than others. You will also likely find that these projects are significantly more complex than your school projects. For example, the LProf code base is now almost 100,000 lines of C and C++ code. + +In order to help candidates be successful in completing their projects it is important that anyone selected is prepared to start actual project work at the project startup date. Please be prepared to have your development environment ready long before the project starts. This means that project mentors will want you to be to able to build and run the base system you are working on well before the project start date. For example, if you are working on one of the LProf projects you should be able to build and run LProf on your development machine at least a month before the project startup date. Windows build environments, in particular, have proven to be particularly difficult to setup and it is common for GSoC mentors to comment about how often the single biggest difficultly for students working on Wndows machines is getting a fully functional build environment setup. + +Many open source developers use a unix like environment (IE. Linux, BSD ...) in part because setting up a working build environments is much simpler. This also means that there is a high likely hood that your mentor will not have much experience working in Windows or OS/X and may not be able to provide much assistance to help you get your builds working in those environments. So take this very seriously. On the other hand using a Unix like system like BSD/Linux/osX/Solaris can be a great learning experience for any student who has not worked on one of these in the past. Many big projects run on *nix systems deploying unix concepts and some of the projects listed above are *nix only projects that can not be worked on using a Windows machine. On request we simply expect the programmer to switch to BSD, Linux or osX. The installation should be no issue. + + +# Communication + +The [[OpenIcc|OpenIcc]] list and the mentors for the above projects are all open for having contact with any prospective candidate. We will use a additional public list dedicated to the GSoC projects communication. IRC: freenode#openicc We require frequent direct communication for at least one time per week over email. More is usual better for us to address issues early. Blogging and public discussions are encouraged to interact with the wider community and give them feedback around whats happening. + +For any uncovered toppics related to the GSoC project please contact Kai-Uwe Behrmann < [[ku.b@gmx.de|mailto:ku.b@gmx.de]] >. diff --git a/OpenIcc/GoogleSoC2012.mdwn b/OpenIcc/GoogleSoC2012.mdwn new file mode 100644 index 00000000..25b1083f --- /dev/null +++ b/OpenIcc/GoogleSoC2012.mdwn @@ -0,0 +1,380 @@ + +OpenIcc/GoogleSoC2012 Wiki is intended to collect ideas for possible projects participating in [[Googles Summer of Code program|http://code.google.com/soc/]]. [[Google Summer of Code|http://www.google-melange.com/gsoc/events/google/gsoc2012]] timeline is online. + +OpenICC wants to bring colour management programming themes to the audience of students. Goal is to understand open source programming and learn how to effectively interact with and contribute to a project in an intercultural environment. + +OpenICC is a group of people dedicated to organise how applications, libraries, toolkits and colour devices talk each to the other about colours. The center of this work is the ICC specification, which is surrounded by several general and operating system specific conventions to create a easy to use open sourced colour management system for naive and experienced users. + +Oyranos is a implementation of mentioned conventions to cover ICC profile handling and colour conversions. The newBSD licensed code base is plain C. Its core requires very few dependencies, namely libxml2. Device support and colour conversions involve according APIs. Goal is to use existing standard technology like XML, XFORMS and GLSL. Oyranos features a (almost) data independent framework to plug-in data manipulators, for colour conversions, tonemapping, image I/O and other operators into a data processing graph. + + +# About the Group + +[[OpenIcc|OpenIcc]] consist of the participants of the OpenICC email list. It was started by Scribus members to better support introduction of colour management into applications and discuss general issues. List contributors are application and CMS developers as well as colour management specialists and users, no matter whether commercial, open source and both. The main focus of this group is to expand the level of support for color management on open source software systems. + +[[!toc 2]] + + +# Project Suggestions + + +## Colour Managed Window + +* 3D games, graphics applications and web browsers want their content to utilise the whole monitor colour space. With colour managed compositing managers under Linux the requirement comes to colour convert the whole window inclusive GUI at once. A colour management widget can help clients to improve their appearance, provide fallbacks on non colour managed platforms and bundle some common code into one powerful widget per toolkit. Most code for GPU computing, multi monitor colour correction and related stuff exists. This projects shall create very easy to use widgets for easy and wide spread integration into applications. + +### Expectations + +* create a root widget for offscreen rendering of windows +* integrate existing code demo snippets for colour correction on GPU +* expose Oyranos API for colour transform options +* render to GL texture using a widely available and portable API or library +* detect OpenGL support and allow for fallbacks +* detect and communicate window colour space to colour servers +* add configurable fallbacks to CPU colour correction using Oyranos +* detect sub widgets and their colour space for normalisation prior blending +* support three toolkits +* small demo application + +### Skills + +* OpenGL knowledge +* good API design +* readable, extendable and clean code +* inline documentation + +### Contact + +* Mentor: Kai-Uwe Behrmann + +### Optional + +* support multiple monitor colour correction + +## Advanced GPU Colour Management + +* 3D and advanced graphics applications want to deploy fast colour correction in several corner cases. The project will help them to use effective stored HDR texture buffers and do blending in linear space for multiple monitors. The goal is to provide working code, which runs fast even on low level devices to increase portability. The project results target at integration into applications, toolkits, compositing window managers and CMM's. + +### Expectations + +* create a root widget for offscreen rendering of windows (preferred Qt) +* integrate existing code demo snippets for colour correction on GPU using 3Dtexture lookups +* integrate shaders for LogLuv compression and decompression (shader snippets exist) +* integrate post linearisation LUT's to convert from linear space to monitor gamma +* render to GL texture using a widely available and portable API or library +* support multi monitor output (e,g, glScissor) +* provide sensible clipping of HDR values as optional shader (algorithm exists) +* demonstrate blending in linear space and final conversion to monitor spaces + +### Skills + +* good OpenGL knowledge +* good API design +* readable, extendable and clean code +* inline documentation + +### Contact + +* Mentor: Kai-Uwe Behrmann + +## Colour Management for Krita Printing + +* Artists and Pro Users want to configure custom ICC profiles. This should be simple and easy. Print dialogs are the ideal place to let user interact in a intuitive way. Oyranos will ensure a very robust configuration of ICC device profiles. OpenUsability, OpenPrinting and OpenICC outlined a concept on how to best integrate colour management into the Common Printing Dialog (CPD). Use the code resulting from last year and enable colour management inside the print dialog of the Krita painting application. + +### Expectations + +* work on Krita +* use libCmpx/Oyranos inside a print dialog +* allow for custom input colour spaces +* work with PDF/X print streams +* test the whole print stack and +* provide necessary patches upstream +* end user documentation + +### Skills + +* medium difficult +* good communication +* Qt, C++, C +* git + +### Contact + +* Mentor: Kai-Uwe Behrmann +* Student: Joseph Simon < [[jsimon383@gmail.com|mailto:jsimon383@gmail.com]] > + +### Links + +* www: [[http://www.oyranos.org/wiki/index.php?title=Device_Settings#Solutions_for_Color-Managed_Printing|http://www.oyranos.org/wiki/index.php?title=Device_Settings#Solutions_for_Color-Managed_Printing]] +* Wiki: [[http://www.oyranos.org/wiki/index.php?title=LibCmpx|http://www.oyranos.org/wiki/index.php?title=LibCmpx]] +* Repository: [[http://gitorious.org/libcmpx|http://gitorious.org/libcmpx]] +* Blog: [[http://jsimon3.wordpress.com|http://jsimon3.wordpress.com]] + +## Print Queue Setup in KolorManager + +* Users and administrators want to configure device ICC profiles for print queues to improve colour output. This should be simple and easy. The project aims at making that reachable wit ha few mouse clicks from inside KDE's Color Management configuration panel. Most components are already present and need just to be combined in a user friendly way. + +### Expectations + +* integrate into KolorManager/Synnefo +* use Oyranos API's +* configure PPD print queues +* modify CUPS print filter(s) as needed to pass through calibration data +* provide well commented patches to upstream CUPS +* end user documentation + +### Skills + +* medium difficult +* good communication +* C++, Qt, C, shell +* git + +### Contact + +* Mentor: Kai-Uwe Behrmann +* Adviser: Edmund Ronald + +## KWin Colour Correction + +* GPUs allow economic and fast colour correction including movies with minimal overhead. A consistent colour corrected desktop increases it's usability. + +### Expectations + +* implement the baseline [[X Color Management|http://www.freedesktop.org/wiki/OpenIcc#XColor_Management_spec]] spec + [[XcolorOutput|XcolorOutput]] +* modify KWin's OpenGL shader +* support multi monitor setups +* create colour transforms with Oyranos +* inline documentation + +### Skills + +* medium difficult +* C++ +* good communication +* shader language + +### Contact + +* Mentor: Kai-Uwe Behrmann < [[ku.b@gmx.de|mailto:ku.b@gmx.de]] >, Advisors: KWin project +* Student: Casian-Valentin Andrei < [[skelet.k13@gmail.com|mailto:skelet.k13@gmail.com]] >, IRC - skelet + +### Optional + +* update the Compiz plugin(s) to support the same standard +* add grid and image based correction textures +* add CM to Wayland's demo compositor Weston and create the needed protocol + +### Project Info + +* blog: [[http://skeletdev.wordpress.com|http://skeletdev.wordpress.com]] +* wiki: [[http://community.kde.org/KWin/GSoC/Color_Correction|http://community.kde.org/KWin/GSoC/Color_Correction]] +* repo: none, at the current stage (will use KWin reviewboard at first) + +## OpenICC Colour Configuration Data Base + +* Users, who configure their colour management system (CMS) behaviour and devices, want to share these settings on one host without any intervention among installed CMSes. The project will introduce the OpenICC data base into CMSes like ArgyllCMS, Oyranos and colord and replaces existing own DB access code. + +### Expectations + +* small, readable and clean code +* existing code might be reused +* use yajl library +* decide about file locations (/etc and in ~/.config) +* add path if any new is needed to [[http://www.oyranos.com/wiki/index.php?title=OpenIccDirectoryProposal|http://www.oyranos.com/wiki/index.php?title=OpenIccDirectoryProposal]] +* add DBus interface +* provide patches for existing CMM'es like ArgyllCMS, Oyranos, colord +* add end user documentation (inline API docu and man pages) +* MIT license + +### Skills + +* rather simple programming tasks +* good communication +* C, JSON, make +* git + +### Contact + +* Mentor: Kai-Uwe Behrmann +* Further Advisors: OpenICC email list + +### Links + +* device DB example: [[http://www.freedesktop.org/wiki/Specifications/icc_meta_tag_for_monitor_profiles|http://www.freedesktop.org/wiki/Specifications/icc_meta_tag_for_monitor_profiles]] +* existing code: [[http://openicc.git.sourceforge.net/git/gitweb.cgi?p=openicc/openicc;a=tree|http://openicc.git.sourceforge.net/git/gitweb.cgi?p=openicc/openicc;a=tree]] + +## Simple Toolkit Abstraction + +* The Oyranos colour management system is in parts only a thin layer between imaging applications and advanced modules or plug-ins. To deploy these plug-ins flexible and maintain toolkit independency, the plug-ins must present their UI in a own language. Goal is to create a simple and highly flexible GUI system, which allows easy creation of dialogs including callback mechanisms. This project lets you explore concepts like W3C XForms, and how to adapt it to traditional event driven programming. The result should be something simple and powerful enough to use for a wide range of applications not limited to Oyranos. Possibly this will result in a stand alone project. + +### Expectations + +* design and implement a small widget set, which allows easy implementation, exchange and processing (create a XForms profile, interact with DOM) +* extend the existing drop down list about slider and other useful widgets +* work on the existing command line and FLTK backends +* add new Gtk and Qt backends +* simple examples showing what is intented to work + +### Skills + +* clear and highly modular API design +* design of interactive applications +* good abstraction +* C, (C++), XML, DOM +* good communication + +### Contact + +* Mentor: Kai-Uwe Behrmann , Advisor: Jon A. Cruz + +### Optional + +* allow some basic events (XEvent) and C callbacks +* write one or more toolkit dependent interpreter(s) (ncurses, ... ) +* script bindings to Java/Python/? +* build a colour chooser based on the above widgets and callbacks for demoing interactive usage + +### Links + +* Repo : [[https://github.com/upcomingnewton/SimpleUI|https://github.com/upcomingnewton/SimpleUI]] +* blog : [[http://upcomingnewton.blogspot.in/|http://upcomingnewton.blogspot.in/]] + +## OpenGTL-/+OpenCL meta backend for Oyranos + +* In order to build fast filters in Oyranos a meta backend is to be programmed. It should allow for fast manipulation of image data like colour conversions, tonemapping, blending or geometric transformations. + +### Expectations + +* study basic concepts of OpenCL shaders, their implementation in Mesa and the Oyranos CMM framework +* decide for a implementation concept (OpenGTL/OpenCL) +* work on existing code and integrate your implementation using most of the already available functionality, extent where needed +* documentation for users - should be very few + +### Skills + +* basic communication +* portable C and C++ programming + +### Contact + +* Mentor: Kai-Uwe Behrmann < [[ku.b@gmx.de|mailto:ku.b@gmx.de]] > +* [[OpenIcc|OpenIcc]] email list + +### Optional + +* convert the available small ICC colour transformation application for demonstration with colour table lookup into a shader plug-in + +## CMM's for Oyranos + +* SampleICC is the official implementation of the ICC colour profile standard from members of the [[ICC|http://www.color.org]]. A module of this engine to plug into Oyranos would be cool. An other candidate is ArgyllCMS, which features very sophisticated colour transformations. + +### Expectations + +* wrap the [[SampleICC|http://sourceforge.net/projects/sampleicc/]] API into the Oyranos Colour Matching Module (CMM) API +* wrap the [[http://www.argyllcms.com|http://www.argyllcms.com]] into the Oyranos Colour Matching Module (CMM) API +* create a catalog of plug-in options supported by the CMM +* work out test and quality assurance strategies + +### Skills + +* good communication +* basic mathematical skills +* portable C++ and C + +### Contact + +* Mentor: Kai-Uwe Behrmann < [[ku.b@gmx.de|mailto:ku.b@gmx.de]] > + +## AICC Library + +* ICC Examin is a profile analysing tool and colour visualiser. Many widgets are interesting to other applications and would be needed in other toolkits in a modular fashion. The AICC project started to implement parts of ICC Examin in C. This project aims at effectively presenting various data as text, graphics and in part in 3D. + +### Expectations + +* continue the AICC project [[http://gitorious.org/gsoc10_openicc|http://gitorious.org/gsoc10_openicc]] +* create a 3D view of gamut +* support 2D output of ICC tag informations +* example application +* user documentation inline + +### Skills + +* POSIX C +* OpenGL +* (Java/Python/?) + +### Contact + +* Mentor: Kai-Uwe Behrmann + +### Optional + +* create one wrapper in a scripting language for basic widgets, Python +* support profile editing +* support plug-ins, to display reports and various graphs +* support spectral data + +## Extending the Oyranos Colour Conversion Framework + +* The colour management system Oyranos provides high level means to render colours in a generic way. The advantage is, application developers can rely on Oyranos services without understanding the often complicated details. This project lets you create and optimise various underpinnings of system level to advanced graphic tools. This project is a collection of many small and very versatile tasks. You can freely create a own plan what to do or will be guided according to your level of expertise. + +### Expectations + +* Possible targets: +* implement efficient pixel conversion between arbitrary buffer types (low level C) +* implement object observation to automatically update to data changes (object oriented C) +* adapt Oyranos devices to catch outside events (X, dbus, ...) +* add [[Create NamedColour|http://create.freedesktop.org/wiki/Swatches_-_colour_file_format]] format support +* implement OS specific CMS connectors to [[ColorSync|ColorSync]] and WCS (cross platform) +* port to Android +* analyse the concepts behind the Oyranos graphs and suggest means for complete data type abstraction (conceptual work) +* extent the Oyranos command line tools set to access device and other settings (build upon Unix/Posix) +* build a small shiny graphical sample application (didactical GUI) +* agreed upon parts shall be finalised, substitution is possible + +### Skills + +* depends on what we agree to work on +* code organisation +* conceptual fitness +* good communication +* work under different OSes (possibly) +* basic to good C +* understanding object oriented designs is helpful + +### Contact + +* Mentor: Kai-Uwe Behrmann < [[ku.b@gmx.de|mailto:ku.b@gmx.de]] > + +# Alternative Ideas + +Feel free to propose and discuss your ideas. We highly appreciate your initiative. It is possible to give multiple proposals. Be warned each proposal needs typical time to prepare. The quality of the proposals counts for us to become able to decide. + + +# Requirements + + +## License + +BSD, LGPL extended by allowing for static linking are preferred licenses for libraries. GPL and other open source licenses are acceptable for other projects but in most cases the project mentor will specify the license to be used for the project. + + +## Skills + +Both good project and coding skills are expected, in order to set up our complex open source projects. We know it is sometimes difficult to talk to people you do not know, especially when they are not visible like over the internet. Nevertheless the mentors of these OpenICC projects want an open dialog with anyone interested in working on these projects. This is an important part of open software development and it is even more important for these Google Summer of Code Projects. Please feel free to contact any of the mentors listed above at any time. The earlier a candidate contacts us the more time remains for getting a feeling of the projects in advance. + + +## Developers Environment + +You are free to select whatever build environment you like as long as the project is targeted at that platform. Many of the above projects are targeted at Unix like systems and a few are fully cross platform. Our experience for cross platform projects is that some build environments are more difficult to setup than others. You will also likely find that these projects are significantly more complex than your school projects. For example, the LProf code base is now almost 100,000 lines of C and C++ code. + +In order to help candidates be successful in completing their projects it is important that anyone selected is prepared to start actual project work at the project startup date. Please be prepared to have your development environment ready long before the project starts. This means that project mentors will want you to be to able to build and run the base system you are working on well before the project start date. For example, if you are working on one of the LProf projects you should be able to build and run LProf on your development machine at least a month before the project startup date. Windows build environments, in particular, have proven to be particularly difficult to setup and it is common for GSoC mentors to comment about how often the single biggest difficultly for students working on Wndows machines is getting a fully functional build environment setup. + +Many open source developers use a unix like environment (IE. Linux, BSD ...) in part because setting up a working build environments is much simpler. This also means that there is a high likely hood that your mentor will not have much experience working in Windows or OS/X and may not be able to provide much assistance to help you get your builds working in those environments. So take this very seriously. On the other hand using a Unix like system like BSD/Linux/osX/Solaris can be a great learning experience for any student who has not worked on one of these in the past. Many big projects run on *nix systems deploying unix concepts and some of the projects listed above are *nix only projects that can not be worked on using a Windows machine. On request we simply expect the programmer to switch to BSD, Linux or osX. The installation should be no issue. + + +# Communication + +The [[OpenIcc|OpenIcc]] list and the mentors for the above projects are all open for having contact with any prospective candidate. We will use a additional public list dedicated to the GSoC projects communication. IRC: freenode#openicc We require frequent direct communication for at least one time per week over email. More is usual better for us to address issues early. Blogging and public discussions are encouraged to interact with the wider community and give them feedback around whats happening. + +For any uncovered topics related to the GSoC project please contact Kai-Uwe Behrmann < [[ku.b@gmx.de|mailto:ku.b@gmx.de]] >. diff --git a/OpenIcc/LinuxCmProposal.mdwn b/OpenIcc/LinuxCmProposal.mdwn new file mode 100644 index 00000000..2d71442c --- /dev/null +++ b/OpenIcc/LinuxCmProposal.mdwn @@ -0,0 +1,89 @@ + + +# LINUX color management a proposal for implementation + +This proposal describes a roadmap for color management under LINUX with the interaction of + +- A profile repository connecting devices, documents and profiles - Engine for ICC color transformations of Image maps - Cairo - Ghostscript - monitor output - printer driver (e.g. Gutenprint or Turboprint) - CUPS / PPDs - File export - application interface + + +## 1) The role of a profile repository + +The profile repository connects ICC profiles to input and output devices and documents. t is the central point for applications, libraries and services to get the information which profiles are valid for transforming an document for output on the monitor, on a printer with a specific printer driver setting and media or a file export. Available profile repositories for windows are - Oyranos - Gnome Color Manager + + +## 2) Engine for ICC color transformation of Image maps + +A Image map is a pixel array with 8 or 16 bit colordepth per channel. Monitors are displaying RGB Image maps. Colorprinter drivers a mainly out putting CMYK Image maps, which are may converted inside the printerdriver in CMYK+X Image maps. An well known engine for ICC based colortransformations of Image maps is littleCMS. If a e.g. littleCMS is combined with the profile repository, the color transformation of Image maps for output on monitor and printerdriver can be made systemwide available for applications, graphic libraries and printer drivers. + + +## 3) Printer driver and ICC profiles + +If the printerdriver is should be integrated into an ICC based colormanagement workflow, an ICC profile for printing always represent a combination of printerdriver settings, inks / toner and the media. There are several advantages, if ICC-profiles for printer setups are configured inside the printerdriver and the printer driver communicates with the "ICC profile repository, which ICC-profile is valid for a printer setup. Furthermore, it would also be helpful, if the printerdriver has the possibility for export and import of color relevant setups with an attached ICC-profile for the setup. This allows e.g. following workflows: - Driver vendor providing setups for different media / print-modes with attached ICC-profiles - Media vendor providing setups for different printers / media with attached ICC profiles - profiling service delivers driver setups incl. the profile In all this variants, the user imports the setups for the media he is using, and the correct ICC-profile is automatically configured. If the printerdriver communicates with "ICC profile repository" all applications and graphic libraries creating print data can detect (if necessary), which ICC-profile is valid for an active printer setup. + +Another option for connecting ICC-profiles and printer setups is the integration of all color relevant print setup data (screening parameters, per channel ink limits, per channel LUT, etc..) as metadata into the ICC-profile. If the printing data is already converted to the printer profile, the driver extracts the metadata from the ICC-profile and setups the driver automatically. + + +## 4) Document types and ICC-Profiles for devices, objects and documents + +For implementing colormanagement on system level, it makes sense to differentiate between following types of documents: + + +### 4a) images + +with embedded ICC-profiles or EXIF-data referencing to standard-profile like sRGB or Adobe RGB + + +### 4b) flat color documents + +containing text, vectorgraphics and images with one valid document ICC profile for all objects Typical standard profiles and document types are e.g. sRGB for Office documents or FOGRA39_coated for documents prepared for commercial printing. The PDF equivalent for such document types is PDF/X-1a where (in general) all PDF objects are either DeviceRGB with outputIntent sRGB or DeviceCMYK with Output Intent e.g. FOGRA39_coated. Flat color document can be easily rendered to a Image map. For displaying such document on the monitor or the printout, the color transformation can be applied after rendering the document to a Image map. + + +### 4c) Mixed color documents, + +* where every object (texts, images, vectorgraphics can have their own ICC-embedded profiles and rendering intents. These objects can also interact through transparencies and blending color spaces. +Rendering for such kind of elements is quite complex. The only available engine to deliver such functionality in the OpenSource Environment is currently GhostScript, which is currently too slow for realtime rendering to the monitor. + + +## 5) Step by step colormanagement implementation in the LINUX environment + +A lot of developers think, that colormanagement must be implemented in one step with the approach to handle mixed color documents. This is a very complex beast, with a lot of traps, which e.g. also APPLE is still learning. In this concept the colormanagement implementation under LINUX concentrates first only of images and flat color documents. The goal for this implementation step is to reach a robust workflow both for output on monitor and printers with shared libraries and services between applications, graphic libraries and printer drivers. The steps could be e.g. + + +### 5a) Adding Colormanagement of Image maps to Oyranos and Gnome Color Manager (g-c-m) + +Oraynos and g-c-m get added functionality to colormanage Image maps with currently active profiles and send the Image maps to the display or a printerdriver with the associated setting + + +### 5b) Adding "per document profile" to Oyranos and g-c-m + +If documents are exchanged between computers, it is necessary, that the document colorspace from the creator of the document is remembered at the receivers side. This makes it necessary to specify a mechanism, ho the document colorspace can be embedded into an document and communicated from an application to Oyranos or g-c-m + + +### 5c) Adding CMYK colorspace and Oyranos g-c-m support for cairo + +In the first implementation, it is not needed, that ICC based color transformations are part of Cairo. Cairo gets the following added functionalities: - assigned Cairo document/window colorspace (This ICC profile describes all colors of an actual Cairo document / window - embed Cairo document during file export (The Cairo document profile is embedded as PDF output Intent during text export or during TIFF / JPEG export - communicate Cairo document profile to Oyranos / g-c-m image map color processing ((Cairo renders output to an Image map and Oyranos / g-c-m transform the image map from the embedded Cairo document profile to either the monitor or print setting profile - introduce CMYK elements in Cairo (they will rendered through described mechanism to the monitor or printer setting + + +### 5d) Handling of ICC-profiles in the print pipeline + +In the first implementation, the printerdriver do NOT needs an internal engine for doing color transformations. It needs only the possibility to assign an ICC profile to named setting and communicate the the setting to oyranos or g-c-m. The colortransformation from document colorspace to the ICC-profile of the driver print setting will be done in the Image map color engine from Oyranos / g-c-m. The driver should also have the possibility to export and import a complete setting incl. the assigned ICC-profile. In the LINUX environment CUPS is the leading service to manage printing queues. The options of a printer driver are described in PPDs, from which the User Interface is generated. + +Handling of driver settings, ICC-profiles, CUPD queues and PPDs could be e.g. organized as follows: + + +### 5d-1) Virtual printers with static PPD + +The PPD for a printer is reduced from all color relevant option like e.g. quality modes, media-presets, color corrections... The user first creates in the printer driver all the necessary settings incl. an ICC profile for each setting. For every setting, a virtual CUPS printer is created and the assigned ICC profile for the setting is communicated to Oyranos / g-c-m. If the user prints through the virtual printer, the CUPS output is converted from the document profile to the printer setting profile in the Oyranos / g-c-m Image map engine. This solution has the advantage to work with static PPDs. But the number of virtual printers is increasing. + + +### 5d-2) Dynamic PPD creation + +The user creates in the printer driver all necessary setting with assigned ICC-profiles for every setting. If he has finished the setup the PPD of the printer will be automatically updated, including all the named settings, the user has created. Only one CUPS queue is needed for the printer. In the printing UI - concerning color - the user only sees, the settings created in the driver. Depending on the setting choosed in the print UI, the Oyranos / g-c-m Image map engine will configure the correct profile for the color transformation to the printer setting. + + +## 6) Entering the area of mixed color documents + +If we have robust workflow for images and flat color documents, the implemented workflows can be migrated to workflows for mixed color documents. Here we have currently two OpenSource engines: GhostScript and Poppler. GhostScript is standard for rendering complex document for print output, but is currently too slow for doing realtime rendering to the monitor. Poppler as a PDF renderer is not such a "big beast" like GhostScript, but probably will have difficulties with very complex documents. If somebody expects for complex documents the same rendering on the monitor and the print out, he should use the same rendering engine for both ways. + +Back to Mainpage [[OpenIcc|OpenIcc]] diff --git a/OpenIcc/ProfilePackages.mdwn b/OpenIcc/ProfilePackages.mdwn new file mode 100644 index 00000000..209852f2 --- /dev/null +++ b/OpenIcc/ProfilePackages.mdwn @@ -0,0 +1,75 @@ + +free license + +[[OpenICC peer reviewed icc-profile packages|http://sourceforge.net/projects/openicc/files/]] OpenICC has prepared different profile packages. icc-profiles-printing-basiccolor2009 and icc-profiles-openicc are suggested as default packages. Both cover a wide range of colour space and are already included in several Linux distributions. Their content is described below. + +[[Colormanagment.org Offset profiles 2009|http://www.colormanagement.org/download_files/basICColor_Offset_2009.zip]] Karl Koch, owner of the Company [[Basiccolor|http://www.basiccolor.de]] hosts at [[colormanagement.org|http://www.colormanagement.org]] packages of ICC profiles and test images under a creatice commons licence. The offset 2009 package is based on the same FOGRA characterization-data like the ECI profiles, but they are calculated with a profiling package from Basiccolor. basICColor [[released|http://lists.freedesktop.org/archives/openicc/2010q3/002218.html]] its www.colormanagement.org profiles under a free license. The content is nearly identical to icc-profiles-printing-basiccolor2009 except a added ICC checksum. + +* ISOcoated_v2_bas.ICC (FOGRA39L based) +* ISOcoated_v2_300_bas.ICC +* ISOnewspaper_v4_26_bas.ICC +* ISOuncoatedyellowish_bas.ICC +* PSO_Coated_300_NPscreen_ISO12647_bas.ICC +* PSO_Coated_NPscreen_ISO12647_bas.ICC +* PSO_LWC_Improved_bas.ICC +* PSO_LWC_Standard_bas.ICC +* PSO_MFC_Paper_bas.ICC +* PSO_SNP_Paper_bas.ICC +* PSO_Uncoated_ISO12647_bas.ICC +* PSO_Uncoated_NPscreen_ISO12647_bas.ICC +* SC_paper_bas.ICC +* ISOcoated_v2_grey1c_bas.ICC +(17/07/2009) + +[[OpenICC profile collection 1.3|http://sourceforge.net/projects/openicc/files/OpenICC-Profiles/]] + +* sRGB +* LStar-RGB.icc +* compatibleWithAdobeRGB1998.icc +* PhotoGamutRGB_avg6c.icc +* XYZ.icc +* Lab.icc +* Gray.icc +* Gray-CIE_L.icc +* ITULab.icc +(18/08/2011 Version 1.3) + +non free license + +[[Adobe Profiles for Bundlers|http://www.adobe.com/support/downloads/detail.jsp?ftpID=3682]] containing following profiles: + +3 RGB profiles + +* Adobe RGB (1998) +* Apple RGB +* [[ColorMatch|ColorMatch]] RGB +12 CMYK profiles + +* US Web Coated (SWOP) v2 +* US Web Uncoated v2 +* US Sheetfed Coated v2 +* US Sheetfed Uncoated v2 +* Coated FOGRA27 (ISO 12647-2:2004) +* Web Coated FOGRA28 (ISO 12647-2:2004) +* Uncoated FOGRA29 (ISO 12647-2:2004) +* Coated FOGRA39 (ISO 12647-2:2004) +* Japan Web Coated (Ad) +* Japan Color 2001 Coated +* Japan Color 2001 Uncoated +* Japan Color 2002 Newspaper +[[ECI Offset-profiles 2009|http://www.eci.org/lib/exe/fetch.php?id=en%3Adownloads&cache=cache&media=downloads:icc_profiles_from_eci:eci_offset_2009.zip]] The ECI is a european hub for colormanagement workflows for the graphic arts. The published profiles are based on characterization-data from [[FOGRA|http://www.fogra.org]]. The profiles are calculated with profiling tools from the company [[Heidelberg|http://www.heidelberg.com]]. ECI allows to bundle the profiles into installers, but this needs and individual permission from ECI. ECI uses a non free license. + +* The ECI Offset 2009 package contains. +* ISO Coated v2 (ECI) +* ISO Coated v2 300% (ECI) +* PSO LWC Improved (ECI) +* PSO LWC Standard (ECI) +* PSO Uncoated ISO12647 (ECI) +* ISO Uncoated Yellowish +* SC Paper (ECI) +* PSO MFC Paper (ECI) +* PSO SNP Paper (ECI) +* PSO Coated NPscreen ISO12647 (ECI) +* PSO Coated 300% NPscreen ISO12647 (ECI) +* PSO Uncoated NPscreen ISO12647 (ECI) +[[SWOP and GRACoL Profiles|http://files.idealliance.org/color_characterization/icc_profiles/swop2006%20and%20gracol2006%20icc%20profiles.zip]] SWOP and GRACoL are specifications for standardized printing in the US maintained by [[IDEAlliance|http://www.ideallinace.org]]. Profiles for printing according SWOP and GRACoL are based on characterization-data hosted from [[CGATS|http://www.npes.org/standards/tools.html]] Profiles are calculated with Profiling Tools from [[X-Rite|http://www.xrite.com]]. Integration of the profiles into installers is may possible but needs the allowance from IDEAlliance. diff --git a/OpenIccForGoogleSoC2007.mdwn b/OpenIccForGoogleSoC2007.mdwn new file mode 100644 index 00000000..263e49a4 --- /dev/null +++ b/OpenIccForGoogleSoC2007.mdwn @@ -0,0 +1,266 @@ + +OpenIccForGoogleSoC2007 Wiki is intended to collect ideas for possible projects participating in Googles Summer of Code. The are mentored by members of [[OpenIcc|OpenIcc]] projects. + + +# About the Group + +[[OpenIcc|OpenIcc]] consist of the members of the so named email list. It was started by Scribus members to better support introduction of colour management into applications and discuss general issues. List contributors are application and CMS developers as well as colour management specialists and users, no matter whether commercial, open source and both together. + +[[!toc 2]] + + +# Project Suggestions + + +## ICC support for HDR Images + +* Available open source colour management libraries like the popular lcms do not support HDR imaging. The work would be a great benefit for existing applications like Krita, CinePaint, Pixel, future Gimp/GEGL and others to support [[ICC|http://www.color.org]] style colour conversions of HDR images. + +### Expectations + + * study basic colour management concepts, [[ILM/OpenEXR's|http://www.openexr.org]] GPU based [[CTL|http://www.openexr.com/documentation.html]] + * decide for a implementation concept + * extent littleCMS (lcms), or alternatively + * create an ICC profile -> CTL converter and build an simple API for later inclusion in the Oyranos framework + * work on existing code and integrate your implementation using most of the already available functionality, extent where needed + * basic documentation for users - should be very few + +### Skills + + * basic communication + * basic mathematical skills like matrix operations + * portable C (lcms) or C++ and probably OpenGL shader programming (CTL) + +### Contact + + * Mentor: Kai-Uwe Behrmann <ku.b @ gmx.de> + * [[OpenIcc|OpenIcc]] / [[OpenEXR|http://www.openexr.com/mailinglist.html]] email lists + +### Optional + + * combine with the HDR Tonemapping project + +## HDR Tonemapping + +* Tonemapping is needed to represent HDR images on monitors and print media. HDR images often easily exceed traditional monitor and printer capabilities. Colours need to be compressed into the medias gamut depending on the intensities of the neighbor pixels. A simple logarithmic approach often yields non satisfactory results. Many algorithms where suggested but often lack a natural look or robustness for various content. + +### Expectations + + * enhance and work on algorithms to create pleasing and highly natural representations of HDR content + * work on a concept to include parameters into ICC or CTL colour profiles for later universal reproduction and standardisation + +### Skills + + * good communication + * basic to good mathematical skills, evaluate, combine and possibly modify existing tonemapping algorithms + * portable C + * OpenGL shader implementation (possibly make suggestion how to integrate into CTL) + +### Contact + + * Mentor: Cyrille Berger <cberger @ cberger.net> + +### Results + + * Shaine Joseph site: [[http://www.umsl.edu/~sj550/myweb/downloads.htm|http://www.umsl.edu/~sj550/myweb/downloads.htm]] You need P7ZIP from [[http://p7zip.sourceforge.net|http://p7zip.sourceforge.net]] to decompress some of the files on unix. + +## ICC Examin Library + +* ICC Examin is a profile and colour visualiser. Many widgets are interesting to other applications. But they are written in FLTK and would be needed in an other toolkit in a modular fashion. + +### Expectations + + * reorganise, modularise and rewrite parts of the existing project + * create an easy to use API and build an example application from it + * create at least one wrapper in a scripting language for basic widgets, Python + * user documentation inline + +### Skills + + * good code (re)organisation + * portable C, C++, Java/Python/? + * OpenGL, threads + +### Contact + + * Mentor: Kai-Uwe Behrmann <ku.b @ gmx.de> + +### Optional + + * support profile editing + * support plug-ins, to display reports and various graphs + * support spectral data + +## Cross Toolkit Colour Chooser for Linux/BSD + +* Linux/BSD operating systems need a standard colour chooser. Imaging applications would benefit from a common advanced colour chooser with extended capabilities and easy data exchange. + +### Expectations + + * colour selection C API to ask for colours from applications and sharing among them + * representation of native colour spaces and standard sRGB/CIE*Lab + * support for HDR values, not plain monitor representation + * plug-ins for third party colour selectors + * unified toolkit independent C API + * basic inline documentation + +### Skills + + * writing highly modular code + * handling of various native toolkits, including Qt, Gtk, FLTK, MFC, Carbon + * portable C, C++ + +### Contact + + * Mentor: Kai-Uwe Behrmann <ku.b @ gmx.de> + +### Optional + + * C API for various basic widgets (window, tab, group, pack layout, list chooser, message box, buttons, drawing area, slider with value input) + * allow some basic events and C callbacks + * layout representable in XML including a parser + * dump layout out to XML/Html for documentation + * scriptability, Java/Python/? + +## Control Panel for Colour Management + +* The KDE desktop needs integration of colour management settings in desktop configuration UI's. + +### Expectations + + * create and integrate a settings panel for the KDE desktop + * inline documentation + * user documentation + +### Skills + + * good communication skills + * portable C, C++ + +### Contact + + * Mentor: Boudewijn Rempt + +### Optional + + * combine with parts of the Colour Chooser project to create a basic toolkit independent layer + * a web interface with proper authentication would be a great plus [07/03/27] + +## LProf - Add checking for and user feedback for clipped patches + +* Right now LProf does not do much checking for issues related to the quality of the profiling target image. + +### Expectations + + * add checks to the profiler to look for and flag clipped patches + * if clipped patches are found display a message to the message console indicating how significant the problem is + * inline documentation + * user documentation + +### Skills + + * good communication skills + * portable C, C++ + +### Contact + + * Mentor: Hal Engel + +## LProf - Add DDC support + +* Use DDC to get monitor chromaticity values (monitor primaries). + +### Expectations + + * implement DDC to get monitor chromaticity values for the rough monitor profiler to set the monitor primaries. + * inline documentation + * user documentation + +### Skills + + * good communication skills + * portable C, C++ + +### Contact + + * Mentor: Hal Engel + +## LProf - Add DDC/CI support + +* Use DDC/CI to set monitor hardware controls to allow for automated adjustment of white point, black level, black offset, gain and other monitor controls during calibration. + +### Expectations + + * implement DDC/CI to set monitor controls. + * create a library for this functionality + * inline documentation + * user documentation + +### Skills + + * good communication skills + * portable C, C++ + +### Contact + + * Mentor: Hal Engel + +## LProf - Add support for the HTC profiling target + +* Support for the HTC profiling target would be a useful addition to LProf. + +### Expectations + + * implement reference file installer functionality to handle HTC target reference files. + * implement reference file installer functionality to create HTC pick template files based on information in the reference file + * inline documentation + * user documentation + +### Skills + + * good communication skills + * portable C, C++ + +### Contact + + * Mentor: Hal Engel + +### Results + + * LProf [[SourceForge|SourceForge]] News: [[http://sourceforge.net/forum/forum.php?forum_id=740238|http://sourceforge.net/forum/forum.php?forum_id=740238]] + +## LProf - Add support for vcgt tags + +* Add support for vcgt tags to the LProf monitor profiler and the UI. + +### Expectations + + * implement support for vcgt tags in the monitor profiler. + * add needed widgets to the UI for users to specify a CGATS file for the vcgt data. + * inline documentation + * user documentation + +### Skills + + * good communication skills + * portable C, C++ + +### Contact + + * Mentor: Hal Engel + +# Alternative Ideas + +Feel free to propose and discuss your ideas. + + +# Required License + +BSD and LGPL extended by allowing for static linking are preferred licenses. + + +# Communication + +The [[OpenIcc|OpenIcc]] list and the according mentors are all open for getting in contact. We may create a additional public list dedicated to the SoC projects communication. + +If in doubt, which way is right, write to Kai-Uwe Behrmann <ku.b @ gmx.de>. diff --git a/OpenIccForGoogleSoC2008.mdwn b/OpenIccForGoogleSoC2008.mdwn new file mode 100644 index 00000000..df0bf633 --- /dev/null +++ b/OpenIccForGoogleSoC2008.mdwn @@ -0,0 +1,372 @@ + +OpenIccForGoogleSoC2008 Wiki is intended to collect ideas for possible projects participating in [[Googles Summer of Code program|http://code.google.com/soc/2008/]]. They are mentored by members of [[OpenIcc|OpenIcc]] projects. + + +# About the Group + +[[OpenIcc|OpenIcc]] consist of the members of the OpenICC email list. It was started by Scribus members to better support introduction of colour management into applications and discuss general issues. List contributors are application and CMS developers as well as colour management specialists and users, no matter whether commercial, open source and both. The main focus of this group is to expand the level of support for color management on open source software systems. + +[[!toc 2]] + + +# Project Suggestions + + +## ICC support for HDR Images + +* Available open source colour management libraries like the popular lcms do not support HDR imaging. The work would be a great benefit for existing applications like Krita, CinePaint, Pixel, future Gimp/GEGL and others to support [[ICC|http://www.color.org]] style colour conversions of HDR images. + +### Expectations + +* study basic colour management concepts, [[ILM/OpenEXR's|http://www.openexr.org]] GPU based [[CTL|http://www.openexr.com/documentation.html]] +* decide for a implementation concept + * create a ICC profile <-> CTL converter and build an simple API for later inclusion in the Oyranos framework, build a Oyranos plugable Colour Matching Module (CMM) around it + * wrap the [[SampleICC|http://sourceforge.net/projects/sampleicc/]] CMM API into the Oyranos CMM API, optimise SampleICC, allow unbound HDR conversions +* work on existing code and integrate your implementation using most of the already available functionality, extent where needed +* basic documentation for users - should be very few + +### Skills + +* basic communication +* basic mathematical skills like matrix operations +* portable C (lcms) or C++ and probably OpenGL shader programming + +### Contact + +* Mentor: Kai-Uwe Behrmann < [[ku.b@gmx.de|mailto:ku.b@gmx.de]] > +* [[OpenIcc|OpenIcc]] / [[OpenEXR|http://www.openexr.com/mailinglist.html]] email lists + +### Optional + +* build a small sample application for demonstration + +## HDR Tonemapping + +* Tonemapping is needed to represent HDR images on monitors and print media. HDR images often easily exceed traditional monitor and printer capabilities. Colours need to be compressed into the medias gamut depending on the intensities of the neighbor pixels. A simple logarithmic approach often yields non satisfactory results. Many algorithms where suggested but often lack a natural look or robustness for various content. +The project would continue the last years work. +### Expectations + +* enhance and work on algorithms to create pleasing and highly natural representations of HDR content +* work on a concept to include parameters into ICC or CTL colour profiles for later universal reproduction and standardisation + +### Skills + +* good communication +* basic to good mathematical skills, evaluate, combine and possibly modify existing tonemapping algorithms +* portable C +* OpenGL shader implementation (possibly make suggestion how to integrate into CTL) + +### Contact + +* Mentor: Cyrille Berger < [[cberger@cberger.net|mailto:cberger@cberger.net]] > + +## ICC Examin Library + +* ICC Examin is a profile analysing tool and colour visualiser. Many widgets are interesting to other applications. But they are written in FLTK and would be needed in an other toolkit in a modular fashion. This project instroduces in the process of effectively presenting various data in easy understandable form. + +### Expectations + +* reorganise, modularise and rewrite parts of the existing project +* create an easy to use API and build an example application from it +* create at least one wrapper in a scripting language for basic widgets, Python +* user documentation inline + +### Skills + +* good code (re)organisation +* portable C, C++, Java/Python/? +* OpenGL, threads + +### Contact + +* Mentor: Kai-Uwe Behrmann < [[ku.b@gmx.de|mailto:ku.b@gmx.de]] > + +### Optional + +* support profile editing +* support plug-ins, to display reports and various graphs +* support spectral data + +## Simple Toolkit Abstraction + +* The Oyranos colour management system is in parts only a thin layer between imaging applications and advanced moduls or plug-ins. To deploy these plug-ins flexible and maintain toolkit independency the plug-ins must present their data in a own language. Goal is to create a simple and highly flexible GUI system, which allows easy creation of dialogs including callback meachanisms. This project lets you explore concepts like W3C XForms/DOM, and how to adapt it to traditional event driven programming. The result should be something simple and powerful enough to use for a wide range of applications not limited to Oyranos. Possibly this will result in a stand alone project. + +### Expectations + +* design and implement a minimalistic widget set, which allows easy implementation, exchange and processing (create a XForms profile, interact with DOM) +* C API for various basic widgets (groups, lists, sliders, buttons, text box, drawing area) +* allow some basic events and C callbacks +* serialise and deserialise with XML +* write interpreter for console applications +* write one or more toolkit dependent interpreter(s) (Gtk, Qt, Fltk ...) +* write a backend for Html output for documentation +* good documentation +* simple examples + +### Skills + +* clear and highly modular API design +* design of interactive applications +* good abstraction +* C, (C++), XML, DOM +* good communication + +### Contact + +* Mentor: Kai-Uwe Behrmann < [[ku.b@gmx.de|mailto:ku.b@gmx.de]] >, Advisor: Jon A. Cruz + +### Optional + +* script bindings to Java/Python/? +* build a colour chooser based on the above widgets and callbacks + +## Control Panel for Colour Management + +* The KDE desktop needs integration of colour management settings in desktop configuration UI's. + +### Expectations + +* create and integrate a settings panel for the KDE desktop +* inline documentation +* user documentation + +### Skills + +* good communication skills +* portable C, C++ + +### Contact + +* Mentor: Jon A. Cruz + +### Optional + +* combine with parts of the Colour Chooser project to create a basic toolkit independent layer +* a web interface with proper authentication would be a great plus [07/03/27] +Joseph Simon works on [[this|http://code.google.com/p/google-summer-of-code-2008-openicc/downloads/list]] project. + + +## Oyranos Device Settings to ICC profile layer + +* Devices need to be introduced to a colour management system, in order to control the devices colour behaviour. For instance different drivers may produce different colour on a otherwise identical device. A CMS needs some mechanism to connect colur influental device settings a particular profile reflecting this behaviour. The ICC and the Oyranos maintainer provide several data blobs to integrate the device information into a ICC profile. + +### Expectations + +* extent the evolving Oyranos colour management system +* implement the provided data formats for embedding into ICC profiles +* design and discuss an API to access the above ICC profile data and map it to existing device driver API's +* apply your API's to different device driver API's, for instance in Gutenprint, libopenraw, Sane to study +* document the API usage + +### Skills + +* portable C +* be fit in compiling various libraries and applications + +### Contact + +* Mentor: Kai-Uwe Behrmann < [[ku.b@gmx.de|mailto:ku.b@gmx.de]] > + Robert Krawitz, ... + +## Color Management near X + +* The Linux/BSD desktop needs some form of colour management to give it a consitent colour feel. A concern are multi monitor systems, with obviously different colorimetry. A laptop with an external monitor is a good example. Both monitor devices can display colours to some degree satisfactory. But a precondition is clear placing the colour transformation onto the right monitor plane. A layer near X will best know about such geometric details. Be prepared, we have no Xorg team member to help with special knowledge. + +### Expectations + +* implement a colour management layer on top of Xorg to colour match window regions, possibly inside a composite manager +* use Oyranos API's to do the colour transformations +* discuss the best way to route color informations from the application to reach your implementation +* document design concept with pros and cons, API, usage +* hint to further optimisation paths inside and outside your implamentation +* document inline and externals, create schema graphics +* optimise the colour transformation path, possibly in a Oyranos OpenGL module + +### Skills + +* flexible API usage +* Xorg code insights +* conceptual strength +* able to work for the Xorg part alone, or get help yourself +* portable and effective C, OpenGL, Shader, threads +* profiling + +### Contact + +* Mentor: Kai-Uwe Behrmann < [[ku.b@gmx.de|mailto:ku.b@gmx.de]] > +Tomas Carnecy works on [[this|http://www.freedesktop.org/wiki/OpenIcc/ColorManagementNearX]] project. + + +## Oyranos Tonemapping Integration + +HDR images needs to be displayed as consitently as any other colour content. There are few expeciences how to do this on a system level. This is a project to design and work on the behaviour of future imaging. With a sensible eye for natural colours and artistic effects you might have fun with this project. +### Expectations + +* discuss, port and optimise existing algorithms to the Oyranos colour management system +* create and optimise GUI layouts for the plug-in options +* serialise and deserialise the options +* document option effects and usage of the various tonemapping plug-ins +* create a simple sample application using Oyranos deploying the new capabilities + +### Skills + +* code organisation talent +* basic C and C++ +* adapting code to different API's +* basic artistic sensibility + +### Contact + +* Mentor: Kai-Uwe Behrmann < [[ku.b@gmx.de|mailto:ku.b@gmx.de]] > + +### Optional + +* create plug-ins to external libraries + +## Oyranos ICC spec Basics Implementation + +* The Oyranos colour management system provides parsing and writing profile capabilities. The data and structures handled in this project are the important base for many higher level stuff. This projects helps in understanding basic and nested data structures and their serialisation and deserialisation. + +### Expectations + +* parse and write profile tags inside the Oyranos CMS +* document the usage +* write a test application to verify robustness and speed of the implementation + +### Skills + +* code organisation and porting +* basic C and C++/STL + +### Contact + +* Mentor: Kai-Uwe Behrmann <ku.b @ gmx.de> + +## Extending the Oyranos Colour Conversion Framework + +* The colour management system Oyranos provides high level means to render colours in a generic way. The advantage is, application developers can rely on Oyranos services without understanding the often complicated details. This project lets you create and optimise verious underpinnings of sytem level to advanced graphic tools. This project is a collection of many small and very versatile tasks. You can freely create a own plan what to do or will be guided according to your level of expertise. + +### Expectations + +* implement efficient pixel conversion between arbitrary buffer types (low level C) +* implement object observation to automatically update to data changes (object oriented C) +* adapt Oyranos to catch outside events (X, dbus, ...) +* implement OS specific CMS connectors to [[ColorSync|ColorSync]] and WCS (cross platform) +* extent the Oyranos command line tools set (build upon Unix/Posix) +* build a small shiny graphical sample application (didactical GUI) +* agreed upon parts shall be finalised, substitution is possible + +### Skills + +* dependent on what we agree to cover +* code organisation +* conceptual fitness +* good communication +* work under different OSes +* basic to good C +* understanding object oriented designs is helpful + +### Contact + +* Mentor: Kai-Uwe Behrmann < [[ku.b@gmx.de|mailto:ku.b@gmx.de]] > + +## LProf - Finalize Qt4 port + +* LProf is an open source ICC profiler. It has recently been ported to Qt4 from Qt3. Although the port is working it still needs to have Qt3 support library calls removed. + +### Expectations + +* Systematically remove [[Qt3Support|Qt3Support]] calls from the LProf code base and replace these with pure Qt4 code. This is a significant undertaking and involves changes to just about every part of the UI code base for LProf. + +### Skills + +* General C++ programming skills +* Experience with C++ object oriented programming +* Experience with Qt a plus but not required (OJT) + +### Contact + +* Mentor: Hal V. Engel < [[hvengel@astound.net|mailto:hvengel@astound.net]] > + +## LProf - Add DDC/CI and USB HID Monitor Controls for Monitor Calibration + +* LProf is an open source ICC profiler. This project will add DDC/CI and HID USB monitor controls support to the current monitor calibration functionality. This will allow the software to automatically make monitor adjustments during calibration so that users do not have to make manual adjustments to their monitors. + +### Expectations + +Implement DDC/CI and/or USB HID Monitor Control support in LProf. This will need to work in a broad range of platforms including *nix/X11, Windows (2000 and later) and OS/X. +### Skills + +* General C/C++ programming skills +* Some background in EDID and/or DDC +* Ability to work in a cross platform environment. This will need to work for *nix/ Windows and OS/X machines. + +### Contact + +* Mentor: Hal V. Engel < [[hvengel@astound.net|mailto:hvengel@astound.net]] > + +## LProf - Add a Regression Analysis Based Monitor Profiling. + +* LProf is an open source ICC profiler. LProf now has the ability to use various measurement instruments to take measurements for profiling monitors of various types. Currently the profiling algorithms are very simple ones and this needs to be corrected. + +### Expectations + +This project will implement a regression analysis algorithm for monitor profiling. +### Skills + +* General C/C++ programming skills +* An understanding of 3D regression anaysis +* An understanding of ICC profiles + +### Contact + +* Mentor: Hal V. Engel < [[hvengel@astound.net|mailto:hvengel@astound.net]] > + +## LProf - Create a Robust Interative Video Card LUT Creation Algorithm. + +* LProf is an open source ICC profiler. LProf now has the ability to use various measurement instruments to take measurements for profiling monitors of various types. Currently the video card LUT creation algorithms are very simple ones and this needs to be corrected. + +### Expectations + +This project will implement a robust interative video card LUT calibration algorithm and will be integrated into the LProf UI. +### Skills + +* General C/C++ programming skills +* An understanding of 3D regression anaysis +* An understanding of ICC profiles + +### Contact + +* Mentor: Hal V. Engel < [[hvengel@astound.net|mailto:hvengel@astound.net]] > + +# Alternative Ideas + +Feel free to propose and discuss your ideas. + + +# Requirements + + +## License + +BSD, LGPL extended by allowing for static linking are preferred licenses for libraries. GPL and other open source licenses are acceptable for other projects but in most cases the project mentor will specify the license to be used for the project. + + +## Skills + +Both good project and coding skills are expected, in order to set up our complex open source projects. We know it is sometimes difficult to talk to people you do not know, especially when they are not visible like over the internet. Never the less the mentors of these OpenICC projects want an open dialog with anyone interested in working on these projects. This is an important part of open software development and it is even more important for these Google Summer of Code Projects. Please feel free to contact any of the mentors listed above at any time. The earlier a candidate contacts us the better. + + +## Developers Environment + +You are free to select whatever build environment you like as long as the project is targeted at that platform. Many of the above projects are targeted at Unix like systems and a few are fully cross platform. Our experience for cross platform projects is that some build environments are more difficult to setup than others. You will also likely find that these projects are significantly more complex than your school projects. For example, the LProf code base is now almost 100,000 lines of C and C++ code. + +In order to help candidates be successful in completing their projects it is important that anyone selected is prepared to start actual project work at the project startup date. Please be prepared to have your development environment ready long before the project starts. This means that project mentors will want you to be to able to build and run the base system you are working on well before the project start date. For example, if you are working on one of the LProf projects you should be able to build and run LProf on your development machine at least a month before the project startup date. Windows build environments, in particular, have proven to be particularly difficult to setup and it is common for GSoC mentors to comment about how often the single biggest difficultly for students working on Wndows machines is getting a fully functional build environment setup. + +Many open source developers use a unix like environment (IE. Linux, BSD ...) in part because setting up a working build environments is much simpler. This also means that there is a high likely hood that your mentor will not have much experience working in Windows or OS/X and may not be able to provide much assistance to help you get your builds working in those environments. So take this very seriously. On the other hand using a Unix like system like BSD/Linux/osX/Solaris can be a great learning experience for any student who has not worked on one of these in the past. Many big projects run on *nix systems deploying unix concepts and some of the projects listed above are *nix only projects that can not be worked on using a Windows machine. On request we simply expect the programmer to switch to BSD, Linux or osX. The installation should be no issue. + + +# Communication + +The [[OpenIcc|OpenIcc]] list and the mentors for the above projects are all open for having contact with any prospective candidate. We will create a additional public list dedicated to the GSoC projects communication. IRC: freenode#openicc + +If in doubt about how to proceed please contact Kai-Uwe Behrmann < [[ku.b@gmx.de|mailto:ku.b@gmx.de]] >. diff --git a/Openchrome.mdwn b/Openchrome.mdwn new file mode 100644 index 00000000..397383d1 --- /dev/null +++ b/Openchrome.mdwn @@ -0,0 +1,16 @@ + +[[!img openchrome.gif] +# About Openchrome + +The Openchrome project is committed to providing and supporting fully free and Open Source drivers that take full advantage of the hardware acceleration of [[VIA|http://en.wikipedia.org/wiki/VIA_Technologies]] chipsets featuring the VIA UniChrome, UniChrome Pro and Chrome9 integrated graphics processors. + + +## Documentation + +* [[Supported hardware|Openchrome/SupportedHardware]] +* [[Components|Openchrome/Components]] +* [[Installation|Openchrome/Installation]] +* [[Configuration|Openchrome/Configuration]] +* [[Troubleshooting|Openchrome/Troubleshooting]] +* [[Development|Openchrome/Development]] +* [[Contact|Openchrome/Contact]]
\ No newline at end of file diff --git a/Openchrome/openchrome.gif b/Openchrome/openchrome.gif Binary files differnew file mode 100644 index 00000000..e4dba151 --- /dev/null +++ b/Openchrome/openchrome.gif diff --git a/OrphanedPages.mdwn b/OrphanedPages.mdwn new file mode 100644 index 00000000..9b60b737 --- /dev/null +++ b/OrphanedPages.mdwn @@ -0,0 +1,2 @@ + +A list of pages no other page links to: [[!orphans ]] diff --git a/SeanMiddleditch.mdwn b/SeanMiddleditch.mdwn new file mode 100644 index 00000000..938b04f5 --- /dev/null +++ b/SeanMiddleditch.mdwn @@ -0,0 +1,13 @@ + + +## Sean Middleditch + +I'm a 21-year-old computer programmer working for the government in a top secret location. Well, OK, it's not top secret, but it _is_ the government. + +My interests in the desktop area lie mostly in system libraries and tools. I'm currently interested in a better API for file access and management ([[Software/dvfs|Software/dvfs]]), better identity management in both the desktop and system, and single sign-on support through Kerberos. + +I'm big into game design, especially MUDs, MMORPGs, LARPs, and table-top RPGs. I've contracted to one game development house and worked (briefly) for Angry Pixels, a Linux-oriented game development company, in addition to open source game development and tons of volunteer work elsewhere. + +Professionally, I work mostly on web applications and websites, focusing on security. I don't particularly enjoy doing this, but it makes the monies. + +[[My Weblog|http://blogs.awemud.net/elanthis/]] diff --git a/Software.mdwn b/Software.mdwn new file mode 100644 index 00000000..7d629e09 --- /dev/null +++ b/Software.mdwn @@ -0,0 +1,101 @@ + + +## Software hosted on or related to freedesktop.org + +Some software has made its way here to live. None of this is "endorsed" by anyone or implied to be standard software, remember that freedesktop.org is a collaboration forum, so anyone is encouraged to host stuff here if it's on-topic. + +You can view the source code in our git repository using [[cgit|http://cgit.freedesktop.org/]]. For more about these repositories, see [[UsingGit|UsingGit]]. + +Some of these modules keep track of their bugs in the local [[bugzilla|http://bugs.freedesktop.org]]. + +* [[AccountsService|Software/AccountsService]] is a dbus service for accessing user accounts +* [[Avahi|http://www.avahi.org]] is a multicast dns network service discovery library +* [[cairo|http://cairographics.org]] is a vector graphics library with cross-device output support. +* [[CJK-Unifonts|Software/CJKUnifonts]] open source CJK unicode truetype fonts with additional support for Minnan and Hakka languages. +* [[Clipart|http://www.openclipart.org/]] is an open source clipart repository. +* [[CppUnit|Software/cppunit]] is the C++ port of the famous JUnit framework for unit testing. +* [[cups-pk-helper|Software/cups-pk-helper]] is a PolicyKit helper to configure cups with fine-grained privileges. +* [[D-Bus|Software/dbus]] is a message bus system. +* [[dbus-cpp|Software/dbus-cpp]] aims to provide a C++ API for D-Bus. +* [[Desktop VFS|Software/dvfs]] is a Virtual File System aimed at message loop (gui) applications. +* [[desktop-file-utils|Software/desktop-file-utils]] contains command line utilities for working with desktop entries and .menu files +* [[DRI|Software/dri]] is a framework for allowing direct access to graphics hardware in a safe and efficient manner. +* [[Enchant|http://www.abiword.org/enchant/]] is a new cross-platform abstract layer to spellchecking. +* [[Elektra|Software/Elektra]] is an configuration storage. +* [[Enlightenment|http://enlightenment.org]] is a desktop environment and application toolkit suite with lots of pretty pixels. +* [[Eventuality|Software/eventuality]] is an "application automation meets cron" type DBUS based framework for creating a means to schedule arbitrary "actions" performed by conforming apps. +* [[Fontconfig|Software/fontconfig]] is a library for configuring and customizing font access. +* [[fprint|Software/fprint]] offers hardware support for a variety of fingerprint readers +* [[GNU FriBidi|http://fribidi.org/]] is a library implementing the Unicode Bidirectional Algorithm and Arabic Joining/Shaping. +* [[Galago|http://galago.sourceforge.net/]] is a desktop-neutral presence system. +* [[Gallium3D|Software/gallium]] is the new 3D driver infrastructure used by [[Mesa|http://www.mesa3d.org]] +* [[Glamor|Software/Glamor]] is an Open source X.org graphics common driver based on GL library. +* [[glitz|Software/glitz]] is an OpenGL 2D graphics library and a backend for gl output in cairo. +* [[GStreamer|http://gstreamer.freedesktop.org/]] is a streaming media framework. +* [[GTK-Qt Theme Engine|Software/gtk-qt]] is a project to unify the GTK and Qt theming engines. +* [[HAL|Software/hal]] is a specification and an implementation of a hardware abstraction layer. +* [[HarfBuzz|Software/HarfBuzz]] is the common [[OpenType|OpenType]] Layout engine shared by Pango, Qt, and possibly others. +* [[Hieroglyph|http://hieroglyph.freedesktop.org/]] is a PostScript rendering library. +* [[icon-slicer|Software/icon-slicer]] is a utility for generating icon themes and libXcursor cursor themes. +* [[icon-theme|Software/icon-theme]] contains the standard and also references the default icon theme called hicolor. +* [[IMBUS|Software/imbus]] is a common tier-1 architecture of IM frameworks for connecting input method engine containers and client application libraries. +* [[immodule for Qt|Software/immodule-qt]] is a modular, extensible input method subsystem for Qt. +* [[IPCF|Software/ipcf]] is an inter-personal communication framework. +* [[jhbuild|Software/jhbuild]] is a program that makes it easy to build software from CVS. It includes support for a number of packages hosted on freedesktop.org. +* [[kmscon|Software/kmscon]] is a KMS/DRM based system console +* [[LDTP|http://ldtp.freedesktop.org]] - Linux Desktop Testing Project +* [[libbsd|http://libbsd.freedesktop.org/]] is a library providing utility functions from BSD systems +* [[libburn|Software/burn]] is an open source library suite for reading, mastering and writing optical discs. +* [[libdlo|Software/libdlo]] is an LGPL library for talking to [[DisplayLink|DisplayLink]] USB graphics adapters. +* [[libexttextcat|Software/libexttextcat]] is an N-Gram-Based Text Categorization library primarily intended for language guessing. +* [[liblazy|Software/liblazy]] D-Bus methods provided for convenience. +* [[libmimetype|http://pcmanfm.svn.sourceforge.net/viewvc/pcmanfm/trunk/src/mime-type/]] is a simple implementation accessing the shared-mime-database included in [[PCManFM|http://pcmanfm.sourceforge.net/]], a lightweight graphical file manager featuring speed, low resource usage, and tabbed-browsing. This small GPL'd lib can be used for mime-type handling as a lightweight replacement of xdgmime. +* [[liboil|http://liboil.freedesktop.org/]] is a library that makes it easier to develop and maintain code written for MMX/SSE/Altivec extensions. +* [[libopenraw|Software/libopenraw]] is an open source library for Camera RAW file decoding and processing. +* [[libspectre|Software/libspectre]] is a small library for rendering Postscript documents. +* [[libvisio|Software/libvisio]] is library providing ability to interpret and import visio diagrams into various applications. +* [[libxklavier|Software/LibXklavier]] is an utility library for X keyboard-related projects. +* [[LightDM|Software/LightDM]] is a cross-desktop display manager. +* [[Mesa|http://www.mesa3d.org]] The Mesa 3D Graphics Library, an implementation of OpenGL. +* [[Nouveau|http://nouveau.freedesktop.org/]] is a project to build an open source driver for nVidia cards. +* [[OpenSync|http://www.opensync.org]] is a project to create a standardized synchronization framework. +* [[Oyranos|http://www.oyranos.org]] is a cross platform colour management system. +* [[pkg-config|Software/pkg-config]] is a system for managing library compile/link flags that works with automake and autoconf. It replaces the once ubiquitous *-config scripts you may have seen with a single tool. There's nothing desktop-specific or desktop-related about pkg-config, despite it being on freedesktop.org. +* [[Plymouth|Software/Plymouth]] is a daemon that runs during startup and shutdown that handles showing a splash screen animation and boot logging. +* [[pm-utils|http://pm-utils.freedesktop.org]] is a collection of scripts that manage suspend/resume in a distro-agnostic fashion. +* [[PolicyKit|Software/PolicyKit]] is an application-level toolkit for defining and handling the policy that allows unprivileged processes to speak to privileged processes. +* [[poppler|http://poppler.freedesktop.org]] is a PDF rendering library, forked from xpdf. +* [[Portland|http://portland.freedesktop.org]] provides a set of high level desktop-integration APIs +* [[pyxdg|Software/pyxdg]] is a python library to access freedesktop.org standards. +* [[SCIM|http://www.scim-im.org]] Smart Common Input Method platform, is a platform to develop input method services. +* [[Scratchbox2|Software/sbox2]] is a cross-compilation tool. +* [[shared-mime-info|Software/shared-mime-info]] is a package containing a large number of common MIME types, created by converting the existing KDE and GNOME databases to the new format and merging them together, and software for updating the database based on the share-mime-info specification. +* [[startup-notification|Software/startup-notification]] is a sample implementation of startup notification (telling the desktop environment when an app is done starting up). +* [[sysconfig|Software/sysconfig]] contains scripts used for managing freedesktop.org; right now this just contains the tinderclient and tinderserver. +* [[Tracker|Software/Tracker]] is a highly memory efficient file indexer and metadata harvester. +* [[uim|http://uim.freedesktop.org/]] is a library to support input many languages. +* [[UTF-8|Software/utf-8]] is a project to document and evangelize the use of UTF-8 encodings for open source projects. +* [[unicode-translation|Software/unicode-translation]] aims to translate Unicode character names and other data into many languages. +* [[vaAPI|Software/vaapi]] provides a decode only video acceleration API for all video formats. Currently in proposal stage. +* [[VDPAU|Software/VDPAU]] provides video decode acceleration and high-quality video presentation. +* [[waimea|Software/waimea]] aims to be a standards compliant window manager for the X Window System making use of the [[cairo|http://cairographics.org]] graphics library for all rendering. +* [[wmctrl|Software/wmctrl]] is a command-line tool to interact with a [[EWMH|Specifications/wm-spec]]-compatible window manager. +* [[XCB/XCL|http://xcb.freedesktop.org]] together are an attempt to re-architect Xlib for resource-constrained environments and different application design techniques. +* [[xdg-utils|http://portland.freedesktop.org/wiki/XdgUtils]] is a set of command line utilities to simplify integration with a Free Desktop. It has simple functions for creating menus, opening files, setting mime types, and so on. It is part of the [[Portland|http://portland.freedesktop.org]] project. +* [[xdg-user-dirs|Software/xdg-user-dirs]] is a tool to handle well known directories in the users homedir +* [[Xephyr|Software/Xephyr]] is a kdrive X Server which uses a window on a host X Server as its framebuffer. +* [[Xft|Software/Xft]] is a library for client-side rendering of fonts. +* [[xfullscreen|Software/xfullscreen]] is a useful module for applications or window managers supporting fullscreen modes. +* [[Xorg|http://xorg.freedesktop.org]] is the XOrg Foundation's Public Implementation of the X Window System™. +* [[xkeyboard-config|Software/XKeyboardConfig]] is a central project for keyboard configuration. +* [[Xoo|Software/xoo]] is a wrapper around a nested X server. +* [[xprint|Software/xprint]] is the X11 printing system. +* [[xresponse|Software/xresponse]] is a tool to measure response times to a mouse click event. +* [[xrestop|Software/xrestop]] is a 'top' like X Server resource usage monitor that uses the XRes extension. +* [[xsettings|Software/xsettings]] is a reference implementation. +* [[X Testing|Software/XTesting]] provides information on various software for testing X Servers and Clients. +* [[X Window Information|Software/wininfo]] is a window information utility for developers of applications, toolkits, and window managers. +* [[Zeitgeist|Software/Zeitgeist]] is a desktop event logging framework. +For more X related projects see the [[list of startup projects|FreedesktopProjects]]. There you will find even a few yet not started projects. + +For a list of third party desktop projects see the [[list of desktop projects|Desktops]]. diff --git a/Software/AccountsService.mdwn b/Software/AccountsService.mdwn new file mode 100644 index 00000000..b855b638 --- /dev/null +++ b/Software/AccountsService.mdwn @@ -0,0 +1,27 @@ + + +# AccountsService + +AccountsService is a D-Bus service for accessing the list of user accounts and information attached to those accounts. + +AccountsService has been developed in and is used by the GNOME project but should be usable in other desktops. It is a young project and is being kept pliable to update to requirements as they arise. See also [[SSSD|https://fedorahosted.org/sssd/]] which may replace / absorb AccountsService in the future. + + +## Documentation + +Documentation for the D-Bus interfaces is included in the source tarball. See the [[GNOME3 proposal|http://mail.gnome.org/archives/desktop-devel-list/2010-October/msg00132.html]] for more information. + + +## Source Code + +* [[Browse source code|http://cgit.freedesktop.org/accountsservice/]] +* [[Download releases|http://www.freedesktop.org/software/accountsservice]] + +## Bugs + +* [[Open bugs|https://bugs.freedesktop.org/buglist.cgi?query_format=specific&order=relevance+desc&bug_status=__open__&product=accountsservice&content=]] +* [[Enter a new bug|https://bugs.freedesktop.org/enter_bug.cgi?product=accountsservice]] + +## Communicate + +* There is no official channel for communication at this time. Please file bugs for feature requests/problems.
\ No newline at end of file diff --git a/Software/BMP-Only.mdwn b/Software/BMP-Only.mdwn new file mode 100644 index 00000000..f0ba011d --- /dev/null +++ b/Software/BMP-Only.mdwn @@ -0,0 +1,8 @@ + +This is a list of software that doesn�t support non-[[BMP|Software/BMP]] Unicode characters. These characters include less-used Han characters, musical notation, historical scripts like Old Persian, and modern artificial scripts like Shavian. + + * [[Emacs|http://www.gnu.org/software/emacs/emacs.html]]: Supplementary characters are displayed as occurrences of U+FFFD. Attempting to delete them [[leaves corruption|http://mail.gnu.org/archive/html/emacs-pretest-bug/2004-04/msg00164.html]]. + * [[VIM|http://www.vim.org/]]: Supplementary characters are handled cleanly, but displayed as question marks. + * [[ANTLR|http://www.antlr.org/]]: Does not accept supplementary characters in input files. +<br> -- Main.[[HendrikMaryns|HendrikMaryns]] - 25 Nov 2008 <br> -- Main.[[AlexanderWinston|AlexanderWinston]] - 22 Jun 2004 <br> -- Main.[[AlexanderWinston|AlexanderWinston]] - 17 Apr 2004 <br> -- Main.[[NoahLevitt|NoahLevitt]] - 17 Mar 2004 + diff --git a/Software/BMP.mdwn b/Software/BMP.mdwn new file mode 100644 index 00000000..8183f7e0 --- /dev/null +++ b/Software/BMP.mdwn @@ -0,0 +1,8 @@ + +Since Unicode 2.0, the authors of the Unicode Standard noticed that the original 65,536 characters are not adequate for the modern needs of information processing ([[Han|http://en.wikipedia.org/wiki/Han_Chinese]] characters were proving to be too many, if one considered the rarely-used characters). + +To handle this, they extended the upper limit of Unicode from U+FFFF to U+10FFFF, thereby introducing more than a million new character slots. The authors of the Unicode Standard, guessing many people will take a little time to change the architecture of their software to support the full repertoire of Unicode, only encoded characters of less frequent use (like rarely-used Han characters, older scripts, or musical notation) in that area. + +The range U+0000 to U+FFFF, where more important characters are stored, is called the Basic Multilingual Plane, while the range U+10000 to U+10FFFF is divided into 16 planes, only three of which have so far been used to encode characters. + +-- Main.[[MarianoSuarezAlvarez|MarianoSuarezAlvarez]] - 21 Feb 200 -- Main.[[RoozbehPournader|RoozbehPournader]] - 19 Nov 2003 diff --git a/Software/BadSoftware.mdwn b/Software/BadSoftware.mdwn new file mode 100644 index 00000000..ecee4f14 --- /dev/null +++ b/Software/BadSoftware.mdwn @@ -0,0 +1,28 @@ + +This is a list of software that doesn't support [[Unicode|http://en.wikipedia.org/wiki/Unicode]] properly, or at all. Please note that we do not consider [[UTF-16|http://en.wikipedia.org/wiki/UTF-16]] or [[UTF-32|http://en.wikipedia.org/wiki/UTF-32]] support adequate (or [[CESU-8|http://www.unicode.org/reports/tr26/]], for that matter). There is also [[another page|Software/BMP-Only]] for software that doesn't support characters outside the [[Basic Multilingual Plane|Software/BMP]]. [[Please file bug reports|http://www.jacksonh.net/jackson/images/godkills_bugs.jpg]] whenever possible, and be sure to let us know about them. + +<!-- Note to editors: Please keep this list in alphabetical order. Thank you. --> + + * [[Aterm|http://aterm.sourceforge.net/]]: Appears to [[fail unfortunately|http://web.archive.org/web/20040519000109/http://home.comcast.net/~alexander.winston/aterm.png]] when attempting to read [[Markus Kuhn's|http://www.cl.cam.ac.uk/~mgk25/]] [[UTF-8 demonstration document|http://www.cl.cam.ac.uk/~mgk25/ucs/examples/UTF-8-demo.txt]]. + * [[Emacs|http://www.gnu.org/software/emacs/emacs.html]]: The [[CVS version|http://savannah.gnu.org/cvs/?group=emacs]] is [[unable to uppercase|http://lists.gnu.org/archive/html/emacs-pretest-bug/2004-06/msg00020.html]] lowercase characters that map to multiple uppercase characters. + * [[Evolution|http://www.ximian.com/products/evolution/]]: [[Pango|http://www.pango.org/]] is used improperly in GtkHtml, so [[right-to-left text is displayed incorrectly|http://bugzilla.ximian.com/show_bug.cgi?id=41763]]. + * [[Flex|http://www.gnu.org/software/flex/]]: Unicode support is very basic. There is no support for dealing with `wchar_t` strings, and the regular expression matching is limited to [[US-ASCII|http://en.wikipedia.org/wiki/ASCII]]. + * [[gnome-print|http://www.gnome.org/projects/gnome-print/]]: [[Pango|http://www.pango.org/]] is [[not used for printing|http://bugzilla.gnome.org/show_bug.cgi?id=125762]]. + * [[GNU Arch|http://www.gnu.org/software/gnu-arch/]]: `tla` does not accept anything other than simple letters, numbers, and basic punctuation in `my-id`. It encounters problems with [[umlauts|http://savannah.gnu.org/bugs/index.php?func=detailitem&item_id=7078]], [[underscores|http://savannah.gnu.org/bugs/index.php?func=detailitem&item_id=7862]], and other [[âfunky charactersâ|http://savannah.gnu.org/bugs/index.php?func=detailitem&item_id=5555]]. + * [[GPG|http://www.gnupg.org/]]: Configuration files contain a setting that communicates the character set that is wanted. There is a notice near this setting claiming that UTF-8 will be the default in the next version. However, in !CVS revision HEAD, the default remains ISO-8859-1. + * [[grep|http://www.gnu.org/software/grep]]: [[Markus Kuhn|http://www.cl.cam.ac.uk/~mgk25/]] [[noticed|http://mail.nl.linux.org/linux-utf8/2003-11/msg00027.html]] that grep 2.5 is very slow in UTF-8 locales; [[Mika Fischer posted a patch|http://mail.nl.linux.org/linux-utf8/2003-11/msg00168.html]] that you may want to try. + * [[Grip|http://nostatic.org/grip/]] has problems with UTF-8 in [[ID3|http://www.id3.org/]] tags. See [[#854558|http://sourceforge.net/tracker/index.php?func=detail&aid=854558&group_id=3714&atid=103714]] and [[#852783|http://sourceforge.net/tracker/index.php?func=detail&aid=852783&group_id=3714&atid=103714]] + * [[ID3v2|http://id3v2.sourceforge.net/]] (an MP3 tagging tool) doesn't set the encoding flag of the text fields in the ID3v2 tags to UTF-8, which thus are not shown correctly in most players/music organizers. See [[this|http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=232307]] bug report for details. + * [[joe|http://sourceforge.net/projects/joe-editor/]]: [[Lon Hohberger|mailto:lhh@redhat.com]] said, âI looked at it briefly, but I didn't get too far before more important things came up. On a side note, it's probably much easier to write a `joe.elisp` or `joe.vim` :)â + * [[Linux kernel|http://www.kernel.org/]]: Console: Can display UTF-8 characters after configured using [[kbd|ftp://ftp.win.tue.nl/pub/linux-local/utils/kbd/]] package. Console can show 256 or 512 different characters at same time. Supported already in distributions such as Fedora, Mandrake, etc. Unicode input is problematic for composing (using a dead key to add accents to characters) as diacritics [[must be 8-bits|http://bugzilla.kernel.org/show_bug.cgi?id=3922]], allowing ISO 8859, but not UTF-8. You can input UTF-8 characters by assigning one key to one Unicode character. The issue of diacritics looks difficult to solve in an easy way. + * man-pages: Manual pages for character sets like ISO-8859-1 [[are not encoded in UTF-8|http://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=108991]]. + * newt: Has problems with multibyte characters, entering UTF-8 characters. + * [[mc|http://www.ibiblio.org/mc/]]: The Red Hat/[[Fedora|http://fedora.redhat.com/]] Linux packages contain patches that fix the main interface, but not the viewer or editor. [[Grab the source RPM|http://download.fedora.redhat.com/pub/fedora/linux/core/development/SRPMS/mc-4.6.0-6.src.rpm]] for the patches. There are also patches from Suse available: [[Suse Patches|http://www.suse.de/~nadvornik/mc.html]] + * strings, part of [[binutils|http://sources.redhat.com/binutils/]], does not support UTF-8. + * [[tcsh|http://tcsh.org]]: This shell has issues: âUnicode (UTF-8) doesn't seem to workâ. This is on their [[wish list|http://www.tcsh.org/WishList]], though. Setting the variable dspmbyte to utf8 seems to solve the problem, however [[you have to set it explicitely|https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=89549]]. There are bugs when editing a command line with UTF-8 characters. + * [[TWiki|http://twiki.org/]]: See [[http://twiki.org/cgi-bin/view/Codev/ProposedUTF8SupportForI18N|http://twiki.org/cgi-bin/view/Codev/ProposedUTF8SupportForI18N]] for the latest information. + * [[WordPress|http://wordpress.org]]: There's no current plan to support UTF-8, and there were no responses to a [[request|http://wordpress.org/support/4/1098]] to use anything other than ISO-8859-1. *Update* (2004-03): This appears to be mostly resolved in their CVS. + * [[Zsh|http://www.zsh.org]]: The Z Shell has partial support for UTF-8. For example, pasted UTF-8-encoded Latin characters display OK, but other characters such as the 3-byte UTF-8 single quote (â) or many Asian characters do not. Zsh also has trouble moving the cursor around multi-byte characters (such as using backspace). Tab completion will match files but probably not display them correctly. A \u escape for generating Unicode characters is supported. In the current unstable (4.3) branch a lot of progress has been made in adding support for unicode from the line editor and help in testing this would be much appreciated by the developers. It is a big job, in part because zsh's useful feature of being able to handle null characters is being preserved. +<!-- Note to editors: Please leave only three change log entries here. Thank you. --> + +<br>-- Main.[[NickLamb|NickLamb]] - 26 Jul 2006 <br>-- Main.[[AlexanderWinston|AlexanderWinston]] - 09 Jul 2004 <br>-- Main.[[AlexanderWinston|AlexanderWinston]] - 14 Jun 2004 diff --git a/Software/CFG.mdwn b/Software/CFG.mdwn new file mode 100644 index 00000000..cdd88dc5 --- /dev/null +++ b/Software/CFG.mdwn @@ -0,0 +1,102 @@ + +[[!toc ]] + + +## CFG (Config4GNU) + +CFG is a three layered unifying configuration framework. It can represent and modify hierarchies of settings in arbitrary config files/databases. + +Its modular framework is based on config (file) descriptions for particular packages, called meta-config definition files. These files can be maintained and installed together with the applications themselves. + +Once a meta-config definition for an application is in place the whole CFG framework can be used on the referenced configuration. + +The CFG framework features: + + * Simple access to all settings of a package + * Different Interfaces (API, comand line, www, GUI, LDAP ...) + * Higher level meta-logic beyond "keys and values" (general Forms and Wizard logic available for frontends) + * Help texts and comments from the config files along with the settings. + * Lossless config file updates/transformations + * and more... +In addition to the info below you might want to read the [[CfgFAQ|Software/CfgFAQ]], and look at the [[screenshots|http://config4gnu.sourceforge.net/screenshots/old.html]] of the GTK-- client prototype. In particular look for the usage of "forms". Don't get too caught up in the tree and key/value view. An end-users frontend could choose to render an icon view and only forms and wizards to alter configurations from the provided meta-data. + +Here is the short version of how it works: + +CFG's middlelayer adds the configurations it reads from the various back-end's syntax parsers to a unified XML representation according to the meta-config definitions it finds. The top-layer then provides utilities and different methods for frontends to querry and access the whole representation. CFG itself saves configuration state only in the original config files. The parsers know the syntax and the meta-config definitions are the source of the semantics. So CFG won't interfere with any hand-editing or other means of config manipulation. In case of an option, type or value error, wether real or due to a not up to date meta-config-definition, CFG can fall back to treat the option it does not know about as a string. Therefore CFG based config tools do not have to completly refuse working on modified files. + +(* means not yet implemented) +[[!table header="no" class="mointable" data=""" +**Front-Ends**: | Line Utilities | GUI | Web | LDAP* | Specialized Tools* (e.g. "go back" utility) +**Top-Layer**: | Provides API, logging*, caching, and any other shared functionality, as appropriate.||||| +**Middlelayer**: | According to found meta-config definitions: Invokes other back-end parsers, generates XML representation and activates changes after writes.||||| +"""]] +[[!table header="no" class="mointable" data=""" +**Bottom-Layer**: | conf-style parser | INI-style parser | XML parser | Specialized/derived parsers (e.g. Apache, samba, XF86``Config, Sendmail*,...) +**Back-Ends**: | Plain text config files | INI Files | XML config files/meta-config files | apache.conf, crontab*, system.dat*, LDAP server*, ... +"""]] + +The original authors have working code out now, but pracically no time to work on it anymore. We need your help packaging it and documenting how to define additional meta-config definitions. Also we'd like to see some of the dependencies (re)moved. (Some more specific things can be found on the [[development|Software/CfgDevel]] page and in the sourceforge's trackers). + +Frequently asked questions (and answers) are available and maintained on the [[CfgFAQ|Software/CfgFAQ]] page, and may help to quickly grasp the concept. + + +## Intended uses for CFG + + +### Shared foundation for universal Config Tools/Frontends + +This one is obvious. Instead of keeping each config tool around up-to-date with changes in config file options and formats only one meta-config definition per package and a appropriate general syntax parser has to be maintained. Config tools can be relatively light weight and easy to maintain yet be universal tools that make use of all their UI/Toolkit features. CFG provides a XML "configuration tree" with available settings, descriptions, available choices and defaults for all packages for which a meta-config definition is available. The frontend can present the tree, or parts of it, if and how desired, and can use the information in forms and wizard definitions to generate user interfaces beyond keys and values even for things the frontend has not been specialized for. Forms and wizards defined in the meta-config only provide the basic logic necessary, the actual appearance can vary widely depending on the frontend used. + + +### Config File Upgrades + +Config file upgrades can simply be done by querying the existing settings from CFG, and writing the settings back after the package upgrade. With the new meta-config definition in place CFG will now generate a new style config file when told to save all previous settings (and comments etc.) that have been read out before. In cases of first time installs or without previous non-default settings the defaults defined in the meta-config would be written out to the new config file. + + +### Installers + +With CFG a package itself should not need to contain a config file that gets copied into /etc, if the pre-inst script finds that the required configuration settings allready exist they will be kept, if no file exists, a new file with the defaults from the meta-config will be created. But sometimes reasonable defaults don't exist for all settings. In this case the installer script/program can call the appropriate/default CFG frontend to prompt the user with the "init" form or wizard. This wizard is defined in the packages' meta-config. Filling out this init form or wizard will complete a valid configuration. The init form or wizard is for setting up things that don't have reasonable defaults but are needed to use the package. + + +### Preconfigureing Packages + +Applications default options are marked in the meta-config definitions as such (i.e. application-defaults that are assumed by the described application if they are not set and therefore do not need to be written to the config file). + +CFG-defaults are different from application-defaults, they serve as suggestions/defaults for frontends. There could be even group specific defaults. For example the frontend might only offer to a user to change the options that have defined user-defaults and the other options will remain to be app, distribution and admin defaults (in that order) if they haven't been explicitly set before. (multi-level configuration) + +Two ways for preconfigureing or customization are: Modifying the defaults in a special packages' meta-config as desired. Or simply pre-seeding the /etc tree with initial config files which contain the desired options during a customized installation. When the package gets installed later those settings will be picked up. If values for all required settings are available the init wizard doesn't need to be invoked anymore. + + +## General package maintainer script tasks + +pre-install: + + * Query CFG for configuration of package that is to be installed. + * If result is positive save the result (XML representation) and rename the old config file. +post-install: + + * If a saved XML-representation from preinst is found write it back with the now updated meta-config. + * If package is installed in noninteractive mode, query CFG now again (meta-data in place, /etc still empty) and save with defaults to create a valid configuration, otherwise call frontend appropriately. + * If some required settings are still missing call the default CFG frontend to "init" the package. + +## Debconf and CFG: + +They extend each other. + +Existing debconf options provided by maintainer scripts can be tied into the configuration system even before explicit CFG meta-config definitions may be available for them. The idea is to make a CFG backend that functions as a frontend to debconf. This way all existing debconf settings could be readily available in the CFG configuration system. It opens a smooth transition path for packages to be updated to provide or depend on CFG meta-config files. + +Maintainers can gradualy make use of CFG functions in their package scripts to easily and safely set up and update their configfiles. Debconf will remain working as before. With the difference that the maintainer scripts debconf depends on to take care of the configuration will be easier to write and maintain due to the shared functionality. Not only the functionality between packages in debian is shared. Much of the config-management and config-description can be maintained in a collaborative way per application rather than per package or per distribution. + +Due to the meta-config definitions and the configuration system, any frontend, tool or script will now have access to the same settings and configuration possibilities. + + +## Downloads + +If you want to see for yourself what this is all about you can download and install Config4GNU. Be aware that the features mentioned here refer to the original Config4GNU concept which differs from the cut-down and hardcoded experimental config4gnu-wbem version. + +Download Information is available [[here|http://config4gnu.sourceforge.net/downloads/config4gnu.html]], you should prefer the cvs version over the outdated tarball. + +For more documentation look also on our first Hompage: [[http://config4gnu.sourceforge.net|http://config4gnu.sourceforge.net]] Note that not all parts there are up to date though. + +This [[news/web-mail interface|http://news.gmane.org/gmane.comp.sysutils.cfg.devel]] to our mailing list has also the later messages archived that somehow did not make it into sourceforge's [[mailing list|http://sourceforge.net/mail/?group_id=62306]] archive. + diff --git a/Software/CJKUnifonts.mdwn b/Software/CJKUnifonts.mdwn new file mode 100644 index 00000000..aca03cc7 --- /dev/null +++ b/Software/CJKUnifonts.mdwn @@ -0,0 +1,69 @@ + + +## Sections + +* Detailed project description [[Software/CJKUnifonts/Description|Software/CJKUnifonts/Description]] +* Download area [[Software/CJKUnifonts/Download|Software/CJKUnifonts/Download]] +* **OBSOLETE**: _Info about Xdelta_ [[Software/CJKUnifonts/Xdelta|Software/CJKUnifonts/Xdelta]] +* Support & Resources [[Software/CJKUnifonts/Resources|Software/CJKUnifonts/Resources]] +* Changelogs: [[AR PL UMing|http://people.ubuntu.com/~arne/cjk-unifonts/uming/FONTLOG]] [[AR PL UKai|http://people.ubuntu.com/~arne/cjk-unifonts/ukai/FONTLOG]] + +## Introduction + +This project aims to provide a full-sized CJK unicode truetype font set, supporting all CJK characters in Unicode plane 0 (BMP) and plane 2. These fonts are under heavy development, new releases containing more glyphs every time are released on a flexible base. + + +## Subprojects + +* Minnan IM (台式閩南語輸入法) [[Software/CJKUnifonts/Minnan_IM|Software/CJKUnifonts/Minnan_IM]] +Input module for Openvanilla to type Taiwan style Minnan ("Taiwanese") +* Hakka IM (台式客家話輸入法) [[Software/CJKUnifonts/Hakka_IM|Software/CJKUnifonts/Hakka_IM]] +Input module for Openvanilla to type Taiwan style Hakka. +* CID font development [[Software/CJKUnifonts/CID|Software/CJKUnifonts/CID]] +Developer Section to produce CID fonts + +## News + +* **2008/02/16** Version 0.2.20080216.1 has been released. This release contains major changes, please consult the Changelog files before installing them. +* **2006/09/28** Version 0.1.20060928 has been released. +* **2006/09/03** Version 0.1.20060903 has been released. +* **2006/06/06** Registered IRC channels on irc.debian.org (The channels on irc.freenode.net are still available). +* **2006/05/13** Version 0.1.20060513 has been released. +* **2006/04/21** Two mailing lists have been registered: [[CJKUnifonts-devel|http://lists.alioth.debian.org/mailman/listinfo/cjkunifonts-devel]] and [[CJKUnifonts-MinnanIM|http://lists.alioth.debian.org/mailman/listinfo/cjkunifonts-minnanim]]. Please use UTF-8 for posting! Only subscribers are allowed to post to the lists, so please subscribe first. +* **2006/02/13** Version 0.1.20060108-1 has been released. +* **2005/11/14** Version 0.1-1 has been released. +* **2005/08/23** New project domain: +This site is now also reachable under [[http://www.cjkunifonts.info|http://www.cjkunifonts.info]]. In fact the domain points to this page. :) +* **2005/08/23** Registered IRC channels on [[freenode|http://www.freenode.net/]]. +Join #cjkunifonts and ask your questions or join the discussion. Please use UTF-8 for posting! + +## Contributors + +* Aaron Cheung +* Akar Chen +* Alex Ho +* 高盛華 Arne Götje (Project leader) +* Chow Lok Yuen +* CP Tung +* Eric(EC-graphic) +* Eric Chan Chi Shing +* Firefly +* Ga Ming +* Jack Tse +* John Knightley +* John Ma +* Kevin Tse +* K.M. Lau +* Kong +* Kwok Wun Yung +* Lam Wai Tung +* Maurizio M. Gavioli +* Munkwui Ho +* Qianqian Fang +* Simon Wong +* Shiu Kau Wong +* Wily Yuen + +## News Coverage + +* [[http://udn.com/NEWS/NATIONAL/NAT5/4168423.shtml|http://udn.com/NEWS/NATIONAL/NAT5/4168423.shtml]]
\ No newline at end of file diff --git a/Software/CJKUnifonts/CID.mdwn b/Software/CJKUnifonts/CID.mdwn new file mode 100644 index 00000000..35fbfdac --- /dev/null +++ b/Software/CJKUnifonts/CID.mdwn @@ -0,0 +1,23 @@ + + +## Introduction + +This page contains links and developers experience about creating CID fonts from the current project. The key questions we'd like to have answered are: + +* How to install CID fonts on different platforms? +* Which applications support / don't support CID fonts? +* Test reports: Did you test these fonts and what is your comment? + +## What does this mean for the CJK-Unifonts? + +The goal is to provide a CID font for CJK users which not only includes all CJK glyphs, but also the popular used variants of those glyphs which share the same Unicode codepoint, but have different shapes in different countries / regions. + The included Cmap files then provide "virtual fonts", where each font contains a subset of glyphs from the whole OTF font. + + +## Links + +* [[Adobe CID Font Technical Documents|http://partners.adobe.com/public/developer/font/index.html#ckf]] +* [[CID Opentype font information on freefonts.oaka.org|http://freefonts.oaka.org/index.php/CID_OpenType_font]] +* [[X.org CID fonts installation guide|http://ftp.x.org/pub/X11R7.0/doc/html/fonts2.html#sec:cid-fonts]] + +## Developers' Comments diff --git a/Software/CJKUnifonts/Description.mdwn b/Software/CJKUnifonts/Description.mdwn new file mode 100644 index 00000000..572b91c2 --- /dev/null +++ b/Software/CJKUnifonts/Description.mdwn @@ -0,0 +1,37 @@ + +While nowadays the main languages (Mandarin, Japanese, Korean) in East Asia are quite well supported on computers, some peoples native languages were left behind. This is true for Taiwanese Minnan and Hakka, two languages spoken by 70 and 30 percent of the population in Taiwan respectively, as well as for many other minority languages throughout East Asia. + +Until now, people who want to use Taiwanese Minnan or Hakka on their computers, have to buy commercial software solutions to solve this problem. But these commercial solutions introduce another problem: incompatibility. Each software vendor promotes his own solution, but documents typed with one program cannot be displayed properly with other applications, let alone by users who don't have one of these special programs installed. + +This problem has a reason: up to now there exists no standard in Taiwan or elsewhere, which covers this issue and provides input tables or character sets, which contain all necessary characters and their input sequences. + +While most Hanzi used in Taiwanese Minnan or Hakka are already in the Big5 standard, many characters are still missing. Even the CNS11643 standard does not contain all characters necessary to type or display Taiwanese Minnan or Hakka properly. + +In the past years another international standard has emerged: Unicode. Unicode has been designed to support all languages and their characters in the world. But even there many characters necessary for Taiwanese Minnan and Hakka are still missing. + +Consequently, there does not exist any "free" font, which covers all those characters, nor does there exist any input method to type those characters. + +The commercial applications I mentioned, solve this problem by inventing their own standards. This however leads to the problem, that users who don't use one of these programs, can neither display nor type Taiwanese Minnan or Hakka properly and document exchange is highly complicated if not impossible. + +This is one of the reasons, why I started the CJK-Unifonts project. + +This project has the following goals: + +* create a "free" set of Truetype fonts, which contain all characters necessary to display Taiwanese and Hakka. +* for those characters, which are not yet included in the Unicode standard: + * identify the missing characters and + * submit them to Unicode for inclusion into the standard. + * until those characters are included in the Unicode standard, use Ideographic Description Sequences (IDS) to describe the glyphs. +* create an input method for typing Taiwanese Minnan and Hakka. This input method: + * can be used on Windows, Linux, Mac OS and many other systems + * can take input in Zhuyin, Tongyong Pinyin, POJ and maybe other methods + * can output Hanzi, Zhuyin, Tongyong Pinyin, POJ and maybe more forms (e.g. Hanzi with Zhuyin attached) + * can lookup a dictionary to make autocompletion or auto selection of words possible. +* both, fonts and input method can be used on any Unicode supporting system (i.e. Windows 2000, XP, Vista , Linux, Mac OS and others) +Especially for Taiwanese Minnan and Hakka Hanzi, there is a lot of confusion among students and users, because publishers often use wrong characters as they currently cannot type or display the correct ones. + +In this project we work closely together with respected dictionary authors and researchers to assure that the dictionary and input table entries contain correct Hanzi. + +This is especially important for teachers and students, because if every school uses different teaching material, different romanization systems and different Hanzi to teach Taiwanese or Hakka, written communication among students, as well as future publications will suffer from the same problem we have currently: that not everyone can read and understand them, but only those people who have learned the same characters or romanization systems. + +This project aims to create a foundation for better written communication and teaching material, through standardized characters, vocabulary and input methods. diff --git a/Software/CJKUnifonts/Download.mdwn b/Software/CJKUnifonts/Download.mdwn new file mode 100644 index 00000000..031cb805 --- /dev/null +++ b/Software/CJKUnifonts/Download.mdwn @@ -0,0 +1,51 @@ + +Latest Release: 0.2.20080216.1 + License: [[Arphic_Public_License|Arphic_Public_License]] + + +### Changelogs + +* [[AR PL UMing|http://people.ubuntu.com/~arne/cjk-unifonts/uming/FONTLOG]] +* [[AR PL UKai|http://people.ubuntu.com/~arne/cjk-unifonts/ukai/FONTLOG]] + +### Comparison Documents + +* Glyph shapes for the different font flavors + * [[AR PL UMing|http://people.ubuntu.com/~arne/cjk-unifonts/uming/Glyph_shapes_uming_0.2.20080216.pdf]] + * [[AR PL UKai|http://people.ubuntu.com/~arne/cjk-unifonts/ukai/Glyph_shapes_ukai_0.2.20080216.pdf]] +* Comparison between old (0.1.x) and new (0.2.x) font versions + * [[AR PL ShanHeiSun -> AR PL UMing|http://people.ubuntu.com/~arne/cjk-unifonts/uming/Font_Comparison_ShanHeiSun_UMing.pdf]] + * [[AR PL ZenKai -> AR PL UKai|http://people.ubuntu.com/~arne/cjk-unifonts/ukai/Font_Comparison_ZenKai_UKai.pdf]] + +### Font Statistics +[[!table header="no" class="mointable" data=""" + | **AR PL UMing** | **AR PL UKai ** + File Size | 116 MB (sfd) / 21 MB (ttc) | 96 MB (sfd) / 17 MB (ttc) + Total Number Of Glyphs | 27,120 | 26,769 + Total Number Of Codepoints | 24,128 | 23,768 +"""]] + + +### Notes + +* Starting from version 0.0.20050501-1 the _Mingti_ font contains Firefly's bitmap characters for pixelsizes 11, 12, 13, 14, 15 and 16. Currently only Big5 and GB2312 are covered by those. +* Starting from version 0.2.20080216 the fonts are distributed as Truetype Collections, which makes the use of xdelta obsolete. For details, please see the Changelog. +* Starting from version 0.2.20080216 the fonts come in 4 flavors (CN, HK, TW and TW MBE), with different glyph shapes according to the preferred shapes in each region. The JP, KR and VM flavors will follow later. Currently this feature is intended for testing only and is limited to only very few glyphs. Please see the Comparison Documents above for details. **Please do not file bug reports for missing glyph shapes! I am aware of them and just don't have enough time to implement them in a timely manner.** + +### Known Issues + +* Starting from version 0.2.20080216 the fonts are provided as Truetype Collections. However, not all software can deal with this correctly, in most cases it is not possible to choose the desired font face from the .ttc. Here is a list of software which is known to have this problem. If you discover more software having this problem, please add it here and notify the upstream developers of that software project. + * imlib2 (patch available) + +### Download +[[!table header="no" class="mointable" data=""" + **0.2.20080216.1** | **AR PL UMing** | **AR PL UKai** + **Tarball** | [[DE|http://de.archive.ubuntu.com/ubuntu/pool/main/t/ttf-arphic-uming/ttf-arphic-uming_0.2.20080216.1.orig.tar.gz]] [[TW|http://tw.archive.ubuntu.com/ubuntu/pool/main/t/ttf-arphic-uming/ttf-arphic-uming_0.2.20080216.1.orig.tar.gz]] [[UK|http://archive.ubuntu.com/ubuntu/pool/main/t/ttf-arphic-uming/ttf-arphic-uming_0.2.20080216.1.orig.tar.gz]] [[US|http://us.archive.ubuntu.com/ubuntu/pool/main/t/ttf-arphic-uming/ttf-arphic-uming_0.2.20080216.1.orig.tar.gz]] | [[DE|http://de.archive.ubuntu.com/ubuntu/pool/main/t/ttf-arphic-ukai/ttf-arphic-ukai_0.2.20080216.1.orig.tar.gz]] [[TW|http://tw.archive.ubuntu.com/ubuntu/pool/main/t/ttf-arphic-ukai/ttf-arphic-ukai_0.2.20080216.1.orig.tar.gz]] [[UK|http://archive.ubuntu.com/ubuntu/pool/main/t/ttf-arphic-ukai/ttf-arphic-ukai_0.2.20080216.1.orig.tar.gz]] [[US|http://us.archive.ubuntu.com/ubuntu/pool/main/t/ttf-arphic-ukai/ttf-arphic-ukai_0.2.20080216.1.orig.tar.gz]] + **deb** | [[DE|http://de.archive.ubuntu.com/ubuntu/pool/main/t/ttf-arphic-uming/ttf-arphic-uming_0.2.20080216.1-0ubuntu1_all.deb]] [[TW|http://tw.archive.ubuntu.com/ubuntu/pool/main/t/ttf-arphic-uming/ttf-arphic-uming_0.2.20080216.1-0ubuntu1_all.deb]] [[UK|http://archive.ubuntu.com/ubuntu/pool/main/t/ttf-arphic-uming/ttf-arphic-uming_0.2.20080216.1-0ubuntu1_all.deb]] [[US|http://us.archive.ubuntu.com/ubuntu/pool/main/t/ttf-arphic-uming/ttf-arphic-uming_0.2.20080216.1-0ubuntu1_all.deb]] | [[DE|http://de.archive.ubuntu.com/ubuntu/pool/main/t/ttf-arphic-ukai/ttf-arphic-ukai_0.2.20080216.1-0ubuntu1_all.deb]] [[TW|http://tw.archive.ubuntu.com/ubuntu/pool/main/t/ttf-arphic-ukai/ttf-arphic-ukai_0.2.20080216.1-0ubuntu1_all.deb]] [[UK|http://archive.ubuntu.com/ubuntu/pool/main/t/ttf-arphic-ukai/ttf-arphic-ukai_0.2.20080216.1-0ubuntu1_all.deb]] [[US|http://us.archive.ubuntu.com/ubuntu/pool/main/t/ttf-arphic-ukai/ttf-arphic-ukai_0.2.20080216.1-0ubuntu1_all.deb]] +"""]] +[[!table header="no" class="mointable" data=""" + **0.1.20060928** | **AR PL [[ShanHeiSun|ShanHeiSun]]** | **AR PL [[ZenKai|ZenKai]]** + **Tarball** | [[TW|http://tw.archive.ubuntu.com/ubuntu/pool/main/t/ttf-arphic-uming/ttf-arphic-uming_0.1.20060928.orig.tar.gz]] | [[TW|http://tw.archive.ubuntu.com/ubuntu/pool/main/t/ttf-arphic-ukai/ttf-arphic-ukai_0.1.20060928.orig.tar.gz]] + **deb** (Debian) | [[TW|ftp://ftp.tw.debian.org/debian/pool/main/t/ttf-arphic-uming/ttf-arphic-uming_0.1.20060928-2_all.deb]] | [[TW|ftp://ftp.tw.debian.org/debian/pool/main/t/ttf-arphic-ukai/ttf-arphic-ukai_0.1.20060928-2.2_all.deb]] + **deb** (Ubuntu) | [[TW|http://tw.archive.ubuntu.com/ubuntu/pool/main/t/ttf-arphic-uming/ttf-arphic-uming_0.1.20060928-2ubuntu3_all.deb]] | [[TW|http://tw.archive.ubuntu.com/ubuntu/pool/main/t/ttf-arphic-ukai/ttf-arphic-ukai_0.1.20060928-2_all.deb]] +"""]] diff --git a/Software/CJKUnifonts/Hakka_IM.mdwn b/Software/CJKUnifonts/Hakka_IM.mdwn new file mode 100644 index 00000000..012c5d33 --- /dev/null +++ b/Software/CJKUnifonts/Hakka_IM.mdwn @@ -0,0 +1,21 @@ + + +## Subproject "Hakka IM (台式客家話輸入法)" + +The aim of this subproject is, to create an input module for Openvanilla (can be used on Windows, Linux, *BSD, MAC, etc.) to type Taiwan style Hakka. + +We have regular meetings on Tuesday nights after the [[TOSSUG|http://wiki.tossug.org]] meetings, usually from 22:00 to 24:00. If you want to attend, just come to the TOSSUG meeting. + +* Mailing list: [[http://lists.alioth.debian.org/mailman/listinfo/cjkunifonts-hakkaim|http://lists.alioth.debian.org/mailman/listinfo/cjkunifonts-hakkaim]] +* IRC channel on freenode: #hakkaIM + +### News + + +### Work Progress + + +### Contributors + +* 李健秋 Andrew Lee +* 高盛華 Arne Götje (Project leader)
\ No newline at end of file diff --git a/Software/CJKUnifonts/Minnan_IM.mdwn b/Software/CJKUnifonts/Minnan_IM.mdwn new file mode 100644 index 00000000..a1f2bd17 --- /dev/null +++ b/Software/CJKUnifonts/Minnan_IM.mdwn @@ -0,0 +1,61 @@ + + +## Subproject "Minnan IM (台式閩南語輸入法)" + +The aim of this subproject is, to create an input module for Openvanilla (can be used on Windows, Linux, *BSD, MAC, etc.) to type Taiwan style Minnan ("Taiwanese"). + +這個子計畫的目的為製作一個香草輸入法（可在 Linux, *BSD, Windows, Mac..上運作）的模組，讓使用者可以用輸入台式閩南語("台語")。 + +Dictionaries for this purpose are provided by Mr. Yang Qing-Chu (楊青矗). I have created [[tasks|https://alioth.debian.org/pm/task.php?group_project_id=61&group_id=30649&func=browse]] for easier development. Each task contains about 25 pages and will take approximately 1 hour to finish. + +台語文學作家 - 楊青矗先生提供字典作為本計畫所需資料。為了開發方便，我已經切分好[[工作單位|https://alioth.debian.org/pm/task.php?group_project_id=61&group_id=30649&func=browse]] 。每個工作單位包含大約 25 頁，工作時間約需要一小時。 + +**Phase 1** will be to create a .cin file with a simple (Zhuyin) keystroke to Hanzi mapping and a mapping table between Zhuyin, Tongyong Pinyin and POJ input methods. + +**第一階段**：將字典上每個單字所有可能的按鍵組合，人工輸入成 .cin 表格，並且製作注音、通用拼音及 POJ 輸入法轉換表格。 + +**Phase 2** will be to create a sentence pattern database to make typing easier. + +**第二階段**：將字典內的詞條轉為資料庫，讓輸入更為方便。 + +Help is still needed. If you are located in Taipei have some time to burn and want to help with this project, you can join us by sending a mail to ` arne at linux dot org dot tw `. + +我們很需要您的幫助，假如您在台北且有時間可以打發的話，請寄一封信到: ` arne 小老鼠 linux 點 org 點 tw `，我們竭誠歡迎任何人的加入。 + +A copy of the 台華雙語辭典 is needed and will be provided by Mr. Yang. + +工作所需的每一本「台華雙語辭典」將由楊先生提供。 + +* Mailing list: [[http://lists.alioth.debian.org/mailman/listinfo/cjkunifonts-minnanim|http://lists.alioth.debian.org/mailman/listinfo/cjkunifonts-minnanim]] +* IRC channel on freenode: #minnanIM + +### News/新聞 + +* **2006/06/06** IRC channel #minnanIM registered on irc.debian.org. (The channel on irc.freenode.net is still available). Please use UTF-8 for posting! +* **2005/08/23** IRC channel on [[freenode|http://www.freenode.net]]: #minnanIM (Please use UTF-8 for posting!) + +### Working Progress/工作進度 + +* 14 Aug 2005 台大迴廊咖啡 工作內容：人工輸入字典上的單字及注音詞鍵。 參與工作者：樓庭岑、李健秋、高盛華、阿里巴巴、朱文君、蔡政崇、黃敬群、陳貴成、蕭志鴻、陳美鳳和王堯坡共 11 位，大約完成約 300 頁。 +* 28 Aug 2005 "QK" 台北車站附近 參與工作者：樓庭岑和高盛華共 2 位，大約完成約 20 頁。 +* 4 Sep 2005 "QK" 羅斯福路三段 參與工作者：李健秋、高盛華、朱文君和蔡政崇共 4 位，大約完成約 80 頁。 +* 13 Nov 2005 "QK" 羅斯福路三段 參與工作者：李健秋、高盛華和朱文君共 3 位，大約完成約 75 頁。 + +### Contributors/義工群 + +感謝每一位義工的幫助： + +* 樓庭岑 Amily Lou +* 李健秋 Andrew Lee +* 高盛華 Arne Götje (Project leader) +* 阿里巴巴 BV1AL +* Chia-I Wu +* 朱文君 Irene Chu +* 蔡政崇 Jeng-Chung Tsai +* 黃敬群 Jim Huang +* 陳貴成 KC Chen +* 蕭志鴻 Linus Hsao +* 陳美鳳 Meifeng Chen +* Penny Huang +* 王堯坡 Wang Yao-Po +* 朱昱任 Yuren Ju
\ No newline at end of file diff --git a/Software/CJKUnifonts/Resources.mdwn b/Software/CJKUnifonts/Resources.mdwn new file mode 100644 index 00000000..8961716e --- /dev/null +++ b/Software/CJKUnifonts/Resources.mdwn @@ -0,0 +1,27 @@ + + +## User Resources + +* [[Bug reports and feature requests|https://alioth.debian.org/tracker/?group_id=30649]] +* [[Discussion forums|https://alioth.debian.org/forum/?group_id=30649]] +* Mailing lists: + * [[cjkunifonts-devel|http://lists.alioth.debian.org/mailman/listinfo/cjkunifonts-devel]] + * [[cjkunifonts-minnanim|http://lists.alioth.debian.org/mailman/listinfo/cjkunifonts-minnanim]] + * [[cjkunifonts-hakkaim|http://lists.alioth.debian.org/mailman/listinfo/cjkunifonts-hakkaim]] +* [[Project overview|https://alioth.debian.org/projects/cjkunifonts/]] +* IRC channels on [[freenode|http://www.freenode.net]]: + * #cjkunifonts + * #minnanIM + * #hakkaIM +**Please use UTF-8 for posting!** + + +## How to help + +If you have some spare time and want to contribute to this project, please mail me at ` arne at ubuntu dot com ` + + +## Additional Developer Resources + +* Tutorial: [[Software/CJKUnifonts/Resources/Tutorial|Software/CJKUnifonts/Resources/Tutorial]] +* Glyph Counter (out of date): [[http://www.linux-stuff.de/index.php|http://www.linux-stuff.de/index.php]]
\ No newline at end of file diff --git a/Software/CJKUnifonts/Resources/Tutorial.mdwn b/Software/CJKUnifonts/Resources/Tutorial.mdwn new file mode 100644 index 00000000..8c15aee2 --- /dev/null +++ b/Software/CJKUnifonts/Resources/Tutorial.mdwn @@ -0,0 +1,202 @@ + +This is a short tutorial about how to contribute to the fonts. + + +## 0. Get ready + +1. I really recommend to do the development on a native Linux system, because all necessary tools come already with most distributions. It doesn't really matter which distribution you use (I personally use Debian Etch and Ubuntu 8.04 Hardy Heron), as long as it is fairly recent. +1. The fonts are produced using [[Fontforge|http://fontforge.sf.net]] a superb open source font editor. Get a recent copy of it (from 2008-03-30 or later) and install it on your development machine. As the fonts we work on are fairly large in size and therefor use a lot of memory when opened in Fontforge, I recommend to have at least 1GB of RAM. +The following screenshots show my recommended Fontforge preferences: [[Screenshot 01|http://people.ubuntu.com/~arne/cjk-unifonts/png/ff_preferences_01.png]] [[Screenshot 02|http://people.ubuntu.com/~arne/cjk-unifonts/png/ff_preferences_02.png]] [[Screenshot 03|http://people.ubuntu.com/~arne/cjk-unifonts/png/ff_preferences_03.png]] [[Screenshot 04|http://people.ubuntu.com/~arne/cjk-unifonts/png/ff_preferences_04.png]] [[Screenshot 05|http://people.ubuntu.com/~arne/cjk-unifonts/png/ff_preferences_05.png]] [[Screenshot 06|http://people.ubuntu.com/~arne/cjk-unifonts/png/ff_preferences_06.png]] +1. Get the development tarball of the fonts (they are already in fontforge's native sfd format): [[http://people.ubuntu.com/~arne/cjk-unifonts/uming_ukai_sfd.tar.bz2|http://people.ubuntu.com/~arne/cjk-unifonts/uming_ukai_sfd.tar.bz2]] (55MB) +1. Untar them into your working directory: _tar xvfj uming_ukai_sfd.tar.bz2_ +1. Never modify the original sfd files in place! Use the templates instead: [[http://people.ubuntu.com/~arne/cjk-unifonts/uming/umingTPL.sfd|http://people.ubuntu.com/~arne/cjk-unifonts/uming/umingTPL.sfd]] and [[http://people.ubuntu.com/~arne/cjk-unifonts/ukai/ukaiTPL.sfd|http://people.ubuntu.com/~arne/cjk-unifonts/ukai/ukaiTPL.sfd]] +1. As the UMing and Ukai fonts are based on the original free Arphic fonts, it's a good idea to have them on the system, too. (On Debian / Ubuntu use _apt-get install ttf-arphic-bsmi00lp ttf-arphic-gbsn00lp_ (for the Ming/Song style fonts) and _apt-get install ttf-arphic-bkai00mp ttf-arphic-gkai00mp_ (for the Kai style fonts). You will find the ttf files in _/usr/share/fonts/truetype/arphic/_. With other distributions the font packages might have different names.) +1. Get agrep. It allows you to grep a text file with an AND search. (On Debian / Ubuntu: _apt-get install agrep_) +1. One very handy text file, which lists all unique Han characters in Unicode 5.0, their radicals, radical index and remaining strokes and components they are built of in IDS (Ideographic Description Sequence) format: [[ids_rs.tar.gz|http://people.ubuntu.com/~arne/cjk-unifonts/ids_rs.tar.gz]] (tarball) or [[ids_rs.zip|http://people.ubuntu.com/~arne/cjk-unifonts/ids_rs.zip]] (zipfile) **Caveat:** This ids_rs.txt file is not final, nor is it official or error free. It is not intended to be redistributed. If you want to have better data, use the [[CHISE|http://www.kanji.zinbun.kyoto-u.ac.jp/projects/chise/]] project and the Unihan.txt file provided by Unicode. +1. Untar the text file in your working directory: _tar xvfz ids_rs.tar.gz_ +1. Han characters can have different glyph shapes, depending on the region they are used in. Glyphs usually look different in China, Hong Kong, Taiwan, Japan, Korea and Vietnam, even if they share the same codepoint. PDF files, which show these different shapes for each codepoint in the Unicode **CJK Unified Ideographs** and **CJK Unified Ideographs Extension A** blocks are available here: [[http://standards.iso.org/ittf/PubliclyAvailableStandards/c039921_ISO_IEC_10646_2003(E).zip|http://standards.iso.org/ittf/PubliclyAvailableStandards/c039921_ISO_IEC_10646_2003(E).zip]] (Please note that the glyph shapes have been submitted to Unicode some time ago. Japan has revised some glyph shapes in its latest JIS X0213-2004 standard.) + In this PDF, the glyphs for Hong Kong are missing. Therefor I produced a similar PDF for Hong Kong glyphs by myself, using the Ming font which is provided by the HKSAR government: [[http://people.ubuntu.com/~arne/cjk-unifonts/CJK_Glyphs_HK.tar.bz2|http://people.ubuntu.com/~arne/cjk-unifonts/CJK_Glyphs_HK.tar.bz2]] (Untar them with: _tar xvfj CJK_Glyphs_HK.tar.bz2_) + +## 1. Basics + +Now that you've downloaded all this stuff, we are ready to begin. + + +### 1.1. ids_rs.txt + +If you have downloaded the ids_rs.txt file, now it's the time to take a look at it. You can open it with any text editor. However, as this text file contains all Han characters from Unicode 5.0, including those of Extension B, you would need to have a font installed to actually display the characters. I found the [[Hannom|http://vietunicode.sourceforge.net/fonts/fonts_hannom.html]] fonts (they are free to download and use, but not free to modify or redistribute) to be perfect for this task. Install them on your system, on Linux, just copy them to your ~/.fonts/ directory and call _fc-cache ~/.fonts/_ to update the cache. + +The text file has multiple columns: + +* Codepoint +* Character +* Radical +* Radical Index / Additional Strokes +* IDS Sequences (can be more than one column) +* Remarks (optional) + +### 1.2. IDS (Ideographic Description Sequence) + +The IDS describes how a Han character looks like. That is, if a specific Han character is not encoded in Unicode yet, you could use IDS to describe how the character looks like. To do this, IDS consists of description characters and Han characters. The description characters are: + +* U+2FF0 [[!img http://people.ubuntu.com/~arne/cjk-unifonts/png/2FF0.png] IDEOGRAPHIC DESCRIPTION CHARACTER LEFT TO RIGHT +* U+2FF1 [[!img http://people.ubuntu.com/~arne/cjk-unifonts/png/2FF1.png] IDEOGRAPHIC DESCRIPTION CHARACTER ABOVE TO BELOW +* U+2FF2 [[!img http://people.ubuntu.com/~arne/cjk-unifonts/png/2FF2.png] IDEOGRAPHIC DESCRIPTION CHARACTER LEFT TO MIDDLE AND RIGHT +* U+2FF3 [[!img http://people.ubuntu.com/~arne/cjk-unifonts/png/2FF3.png] IDEOGRAPHIC DESCRIPTION CHARACTER ABOVE TO MIDDLE AND BELOW +* U+2FF4 [[!img http://people.ubuntu.com/~arne/cjk-unifonts/png/2FF4.png] IDEOGRAPHIC DESCRIPTION CHARACTER FULL SURROUND +* U+2FF5 [[!img http://people.ubuntu.com/~arne/cjk-unifonts/png/2FF5.png] IDEOGRAPHIC DESCRIPTION CHARACTER SURROUND FROM ABOVE +* U+2FF6 [[!img http://people.ubuntu.com/~arne/cjk-unifonts/png/2FF6.png] IDEOGRAPHIC DESCRIPTION CHARACTER SURROUND FROM BELOW +* U+2FF7 [[!img http://people.ubuntu.com/~arne/cjk-unifonts/png/2FF7.png] IDEOGRAPHIC DESCRIPTION CHARACTER SURROUND FROM LEFT +* U+2FF8 [[!img http://people.ubuntu.com/~arne/cjk-unifonts/png/2FF8.png] IDEOGRAPHIC DESCRIPTION CHARACTER SURROUND FROM UPPER LEFT +* U+2FF9 [[!img http://people.ubuntu.com/~arne/cjk-unifonts/png/2FF9.png] IDEOGRAPHIC DESCRIPTION CHARACTER SURROUND FROM UPPER RIGHT +* U+2FFA [[!img http://people.ubuntu.com/~arne/cjk-unifonts/png/2FFA.png] IDEOGRAPHIC DESCRIPTION CHARACTER SURROUND FROM LOWER LEFT +* U+2FFB [[!img http://people.ubuntu.com/~arne/cjk-unifonts/png/2FFB.png] IDEOGRAPHIC DESCRIPTION CHARACTER OVERLAID +The Han characters are the components the desired character is made of. The syntax is: First the IDC followed by the components (from outside to inside, from left to right, from top to bottom). + +Examples: + +* U+4E69 乩 -> [[!img http://people.ubuntu.com/~arne/cjk-unifonts/png/2FF0.png]占乚 +* U+4E6A 乪 -> [[!img http://people.ubuntu.com/~arne/cjk-unifonts/png/2FFA.png]乙田 +* U+4E6B 乫 -> [[!img http://people.ubuntu.com/~arne/cjk-unifonts/png/2FF1.png]加乙 +* U+55C0 嗀 -> [[!img http://people.ubuntu.com/~arne/cjk-unifonts/png/2FF0.png][[!img http://people.ubuntu.com/~arne/cjk-unifonts/png/2FF1.png][[!img http://people.ubuntu.com/~arne/cjk-unifonts/png/2FF3.png]士冖一口殳 +The description for U+55C0 嗀 reads like: ([[!img http://people.ubuntu.com/~arne/cjk-unifonts/png/2FF0.png]([[!img http://people.ubuntu.com/~arne/cjk-unifonts/png/2FF1.png]([[!img http://people.ubuntu.com/~arne/cjk-unifonts/png/2FF3.png]士冖一)口)殳 ). + + +### 1.3. How to use this? + +Most of the Han characters in Unicode can be composed out of other Han characters. By far the most cases use a LEFT TO RIGHT composition ([[!img http://people.ubuntu.com/~arne/cjk-unifonts/png/2FF0.png]), the second most common is ABOVE TO BOTTOM ([[!img http://people.ubuntu.com/~arne/cjk-unifonts/png/2FF1.png]). Almost all of these use a radical in either the LEFT, RIGHT, TOP or BOTTOM position (e.g. LEFT: 亻 冫 口 土 女 山 彳 忄 扌 日 月 氵 ..., RIGHT: 刂 支 攵 阝 ..., TOP: 入 八 冖 宀 艹 ..., BOTTOM: 乙 灬 ...). + + + +--- + + + +* **Example:** We want to add a new glyph to the font. Let's take **U+8281 芁**. + This character is composed of 几 and the 艹 radical component. The 艹 radical component sits on TOP of 几, so the IDS for this character would be [[http://people.ubuntu.com/~arne/cjk-unifonts/png/2FF1.png|http://people.ubuntu.com/~arne/cjk-unifonts/png/2FF1.png]]艹几. The 艹 component in this case does not take much space in the glyph, that means the BOTTOM part 几 has to use more space in the resulting glyph than the radical component. +Our goal is now to find an existing glyph in the font with a similar arrangement (radical on top, 几 on bottom, the radical does not use much space). Therefor, we can use agrep to filter our ids_rs.txt file: _agrep '⿱;几' ids_rs.txt | less_ . This means we search all lines which have [[!img http://people.ubuntu.com/~arne/cjk-unifonts/png/2FF1.png] AND 几 and display them with the pager _less_. + +The result in this case is quite long, so we can filter some more... as we are looking for a 几 with a radical component on TOP, we know that the **additional strokes** (means in addition to the radical component) is 2. Let's put this into our agrep search string: _agrep '\.2;⿱;几' ids_rs.txt_ . Et voilà: the list is much shorter now. ([[Screenshot|http://people.ubuntu.com/~arne/cjk-unifonts/png/ff_example01_00.png]]) + +From this search result the character U+5197 冗 冖 014.2 ⿱冖几 jumps right into sight and seems to be a perfect candidate. Now, assume we have already loaded the font (e.g. UKai) and the matching template (e.g. ukaiTPL) in Fontforge, we can take a look if U+5197 already exists in our font. View -> Goto -> U+5197 reveals that we are lucky ([[Screenshot|http://people.ubuntu.com/~arne/cjk-unifonts/png/ff_example01_01.png]]). Now we open the glyph with a double click and select the 几 part by carefully double clicking on the spline ([[Screenshot|http://people.ubuntu.com/~arne/cjk-unifonts/png/ff_example01_02.png]]). Then we copy the selection into the clipboard by pressing CRTL+C. In the template file window we go to U+8281, our missing character: View -> Goto -> U+8281 ([[Screenshot|http://people.ubuntu.com/~arne/cjk-unifonts/png/ff_example01_03.png]]). + +Double click on the empty character and paste the 几 component into it (CRTL+V) ([[Screenshot|http://people.ubuntu.com/~arne/cjk-unifonts/png/ff_example01_04.png]]). You can see that we have 3 layers available in the editing mode: Front, Back and Guide. Now we have to find a suitable radical component, which fits in size and slant to the 几 we already pasted. For this, we can now switch back to our main font window (e.g. UKai) and go to the same codepoint like in the template: View -> Goto -> U+8281 (which is empty of course) ([[Screenshot|http://people.ubuntu.com/~arne/cjk-unifonts/png/ff_example01_05.png]]). Now we look around this position if any of the surrounding glyphs has a promising radical components, which we could borrow. In this case U+8293 芓 looks like a good candidate ([[Screenshot|http://people.ubuntu.com/~arne/cjk-unifonts/png/ff_example01_06.png]]). + +Double click on that character, select the radical component by double clicking on it and copy it to the clipboard (CRTL+C) ([[Screenshot|http://people.ubuntu.com/~arne/cjk-unifonts/png/ff_example01_07.png]]). Now switch back to the template file, double click on the character we want to edit (if you have closed that window before), select the Back layer and paste the radical component into it (CRTL+V) ([[Screenshot|http://people.ubuntu.com/~arne/cjk-unifonts/png/ff_example01_08.png]]). We can now see if the radical component matches our BOTTOM component. As we used two layers, they won't conflict with each other. Means moving one of the parts around won't disturb the other. In this case it's a perfect match and we don't need to do any further modification. Let's move the radical component onto the Front layer into it's final position: select the radical component, CRTL+X, switch to the Front layer and paste with CRTL+V ([[Screenshot|http://people.ubuntu.com/~arne/cjk-unifonts/png/ff_example01_09.png]]). If the result looks good, we can take care of the next glyph ([[Screenshot|http://people.ubuntu.com/~arne/cjk-unifonts/png/ff_example01_10.png]]). + +Now, what if we would need to move a component around to make it fit? For this, I found it to be a good idea **not** to use the mouse to drag the component around, but the **arrow keys** on the keyboard. Pressing the arrow keys will move the selection one decimal point, holding down the ALT key while pressing the arrow keys will move the selection 10 decimal points. + + + +--- + + + + +## 2. More advanced stuff + +For an exhaustive tutorial about how to use Fontforge, please see the [[Fontforge|http://fontforge.sf.net]] website. + + +### 2.1. Resizing + +In this example, we create the character U+2A6A5 𪚥, which simply consists of 4 "dragons" (龍) using the UMing font.[[BR|BR]] This glyph could be divided into two horizontal parts ([[!img http://people.ubuntu.com/~arne/cjk-unifonts/png/2FF0.png]龍龍 stacked on top) or two vertical parts ([[!img http://people.ubuntu.com/~arne/cjk-unifonts/png/2FF1.png]龍龍 side by side). If we scan through our ids_rs.txt file (_grep 龍 ids_rs.txt_), we will find the perfect candidate: U+9F98 龘, which consists of 3 "dragons", one on top and two side by side below. This constellation ensures, that the height of the upper and lower parts are about the same, the ideal situation for our target glyph. + +1. We open our source font (UMing in this case) and find our candidate glyph: View -> Goto -> U+9F98 +1. We open the editing window by double clicking on that character ([[Screenshot 1|http://people.ubuntu.com/~arne/cjk-unifonts/png/ff_example03_01.png]]) +1. As we only want to copy the lower half of the glyph, we select the parts we want to copy. The bottom right "dragon" is conjoined with the "dragon" on top: select a rectangle around the area we want to copy. Then press CRTL+C. ([[Screenshot 2|http://people.ubuntu.com/~arne/cjk-unifonts/png/ff_example03_02.png]]) +1. In our template file, we find our target character: View -> Goto -> U+2A6A5 +1. We open the editing window of that character by double clicking on it. +1. Now, we can paste our selection into it. CTRL+V ([[Screenshot 3|http://people.ubuntu.com/~arne/cjk-unifonts/png/ff_example03_03.png]]) +1. With the pasted stuff still selected, we zoom in a bit to get a better look on the splines and points involved. Press CRTL+ALT+SHIFT+= . +1. Now we can remove those points and splines we don't need. Select them and press Delete. ([[Screenshot 4|http://people.ubuntu.com/~arne/cjk-unifonts/png/ff_example03_04.png]]) +1. If you compare the right "dragon" with the left one, you will notice that at those points, where the bottom right "dragon" was conjoined with the top "dragon", the splines are not closed now ([[Screenshot 5|http://people.ubuntu.com/~arne/cjk-unifonts/png/ff_example03_05.png]]). We need to fix this: + 1. Copy the missing parts from the left "dragon" one by one: CRTL+C. ([[Screenshot 6|http://people.ubuntu.com/~arne/cjk-unifonts/png/ff_example03_06.png]]) + 1. Paste the selection at the same position: CRTL+V + 1. Move the pasted part across to the right dragon by using the arrow keys. The arrow keys on your keyboard move the selection **exactly** one point at the time into the desired direction. Using the mouse to drag would probably distort the glyph when you connect the parts. So, be careful! Holding the ALT key pressed while using the arrow keys, will move the selection 10 points at a time into the desired direction. ([[Screenshot 7|http://people.ubuntu.com/~arne/cjk-unifonts/png/ff_example03_07.png]]) + 1. Connect the pasted selection with the right "dragon" by using the arrow keys on your keyboard. ([[Screenshot 8|http://people.ubuntu.com/~arne/cjk-unifonts/png/ff_example03_08.png]]) + 1. Do the same for the other missing part. ([[Screenshot 9|http://people.ubuntu.com/~arne/cjk-unifonts/png/ff_example03_09.png]]) ([[Screenshot 10|http://people.ubuntu.com/~arne/cjk-unifonts/png/ff_example03_10.png]]) ([[Screenshot 11|http://people.ubuntu.com/~arne/cjk-unifonts/png/ff_example03_11.png]]) +1. Now, the bottom part of our target glyph is complete. We can try to duplicate it and stack it on top: select the whole thing by drawing a rectangle around the glyph with your mouse, press CRTL+C and CRTL+V to paste it at the same position ([[Screenshot 12|http://people.ubuntu.com/~arne/cjk-unifonts/png/ff_example03_12.png]]). Use ALT+ Arrow Up to move the whole thing on top ([[Screenshot 13|http://people.ubuntu.com/~arne/cjk-unifonts/png/ff_example03_13.png]]). Zoom out to get a better overview how the result looks like. (View -> Fit). +1. You will notice, that our result is now too high and sticks out of our bounding box ([[Screenshot 14|http://people.ubuntu.com/~arne/cjk-unifonts/png/ff_example03_14.png]]). We need to fix this. The best way to do this is to "resize" the bottom part and then duplicate it again. + 1. remove the upper half of the glyph by selecting the upper part and press the Delete key. If that part is still selected from our moving step, just press the Delete key. + 1. Zoom in to get a better view: CRTL+ALT+SHIFT+= + 1. Now we need to skew the two "dragons" vertically. **Don't use any of fontforge's builtin Transformation functions, we want to keep the stem widths intact!** Instead find a good position to do the resizing manually. I suggest to make the space between the horizontal strokes of the "meat" part ⺼ and the corresponding horizontal strokes of the right part of the "dragon" smaller. + 1. Select the upper part of the two "dragons" carefully, then press the Arrow Down key 5 times ([[Screenshot 15|http://people.ubuntu.com/~arne/cjk-unifonts/png/ff_example03_15.png]]). + 1. You'll see that the "meat" part has two points on the spline we want to resize. As they have no function here, we can delete them. Select the two points in each "meat" part and press Delete ([[Screenshot 16|http://people.ubuntu.com/~arne/cjk-unifonts/png/ff_example03_16.png]]). Now the spline is open ([[Screenshot 17|http://people.ubuntu.com/~arne/cjk-unifonts/png/ff_example03_17.png]]). Select the lower point of the spline, select the "Add corner point" tool [[!img http://people.ubuntu.com/~arne/cjk-unifonts/png/ff_corner_point.png] from the toolbar and click on the upper point to close the spline ([[Screenshot 18|http://people.ubuntu.com/~arne/cjk-unifonts/png/ff_example03_18.png]]). Select the "Pointer" tool [[!img http://people.ubuntu.com/~arne/cjk-unifonts/png/ff_pointer.png] to finish the task. Repeat for the other "meat" part on the right side. + 1. Now include one more horizontal stroke in each part and repeat. Also 5 points down ([[Screenshot 19|http://people.ubuntu.com/~arne/cjk-unifonts/png/ff_example03_19.png]]). + 1. In total, we skewed our bottom half of the character by 10 points now. Let's see if it fits now. +1. Select the whole thing, press CRTL+C followed by CRTL+V, move the pasted selection up by using ALT+ Arrow Up a few times. Et Voilà, it fits ([[Screenshot 20|http://people.ubuntu.com/~arne/cjk-unifonts/png/ff_example03_20.png]]). +**Now, why not just use the single "dragon" U+9F8D 龍, scale it by 50% and duplicate it three times and move the parts into their correct position? Would be a lot easier, wouldn't it?** + +Well, let's compare the result: ([[Screenshot 21|http://people.ubuntu.com/~arne/cjk-unifonts/png/ff_example03_21.png]]) + +On the left hand side the proper glyph, on the right hand side the "scaled" one: as we can easily see, the "scaled" glyph is much thinner than the rest of the glyphs in the font. When reading a text containing this character, this glyph will stick out as being too thin compared to the other ones and will probably look blurry because of that. **In other words: it looks ugly!** + + +### 2.2. Editing splines + + +### 2.3. Glyph variants + +CJK characters are used in different regions and can look different in each region, although the share the same codepoint. If you have downloaded the PDFs I mentioned in Section 0, item 10, you can see which glyph has been submitted to Unicode by each national body for each codepoint used in that region. + +The regions are: +[[!table header="no" class="mointable" data=""" + **Region** | **Internal abbrevation** | **UMing font flavor** | **UKai font flavor** + China | C | AR PL UMing CN | AR PL UKai CN + Taiwan | T | AR PL UMing TW | AR PL UKai TW + Japan | J | AR PL UMing JP | AR PL UKai JP + Korea | K | AR PL UMing KR | AR PL UKai KR + Vietnam | V | AR PL UMing VN | AR PL UKai VN + Hong Kong | H | AR PL UMing HK | AR PL UKai HK +"""]] + +To produce these font flavors, we collect all regional flavored glyphs in the same font file and assign tags to them, depending on for which region they should be used. For example: **U+4EE4 令** has 3 different glyph shapes: C, TVH and JK. Therefor, we have three glyphs: **uni4EE4.C**, **uni4EE4.TVH** and **uni4EE4.JK** ([[Screenshot|http://people.ubuntu.com/~arne/cjk-unifonts/png/ukai_4EE4.png]]). + + + +--- + + + +* **Short Excursion: Codepoints, Encodings, Slots, Glyphs and more** + +* **Codepoints and Encodings:** In an application (e.g. a text editor) you type some bytes. The <ins>encoding</ins> maps these bytes to internal index numbers, the <ins>codepoints</ins>. In recent years ISO 10646-1, commonly known as "Unicode", has become the de-facto standard to represent texts. For example the <ins>codepoint</ins> 4EE4 in ISO 10646-1 has been assigned the character 令. To use this character on the computer, we need to use a byte sequence which maps to this ISO 10646-1 codepoint. The most common <ins>encoding</ins> for this on to-date Linux systems is "UTF-8". In UTF-8 the byte sequence, which represents the ISO 10646-1 codepoint 4EE4 is: 0xE4 0xBB 0xA4. +* **Slots and Glyphs:** To be able to read an "encoded" text (e.g. with the UTF-8 encoding), we need some graphical representation to map the byte sequence to something human readable. (_You can open a non-Latin UTF-8 encoded text file in a hex editor and try to read the text. You will see what I mean._ ;-) ) To do this mapping, we use <ins>fonts</ins>. A font is a collection of drawings (<ins>glyphs</ins>), which can map to one or more ISO 10646-1 codepoints. These <ins>glyphs</ins> are organized into <ins>slots</ins>. A TrueType font can have a maximum of 65536 slots and therefor 65536 glyphs. The glyphs in a font **can** have a mapping to one or more codepoints, but **don't need** to have one. Glyphs, which don't have a mapping to a codepoint are usually invisible to the user. Now why would we want to have invisible (<ins>unassigned</ins>) glyphs? + Well, in most cases the reason is, that we don't want them to be visible for the general public all the time, but only in some specific situations. In TrueType fonts this is done by using "_features_". The probably most common case for this is "_contextual shaping_" used in many writing systems, or "_ligatures_". Here, having a specific codepoint combination in a text would result in a different (<ins>unencoded</ins>) glyph than they would normally map to individually. +* **Variation Selectors:** Unicode has assigned a codeblock to contain "Variation Selectors". That is: if a Han character gets followed by a Variation Selector, a different glyph (_the variant shape_) is selected from the font instead of the usual one. The details are described here: [[http://www.unicode.org/ivd/|http://www.unicode.org/ivd/]]. There is currently one set of Variants registered. This comes from Adobe and is for Japanese Kanji. Certain Kanji can have a different shape, depending on the context as used in the text. Nevertheless, it's still the same codepoint. To display the desired shapes, one can use the registered Variation Selector sequences with a font capable of displaying the differences. +It is my aim to include as many of these variants as possible. +* **Stylistic TrueType Features:** TrueType knows several "_features_" which can be used to select a different glyph from a font than the one assigned with that codepoint. These can be combined with a language (zh, ja, ko, ...) and scripting (Hans, Hant, Hani, ...) tag to make a specific variant be selected automatically in a given language environment. However, since this relies heavily on the applications the user uses and the vast majority of available applications don't support this, it is usually not used in fonts either. +* **TrueType Collections:** TrueType Collections are basically multiple TrueType fonts bundled in a single .ttc file. If we have multiple single .ttf fonts, which share a large amount of glyphs and they are assigned to the same codepoints (like in this project), we can combine them into a single .ttc file. The advantage is that the glyphs which are shared between these fonts are only stored once. This saves a lot of space. +Technically, each single unique glyph is stored only once in the .ttc file. It then has multiple font headers and cmap tables. Each cmap table contains the mapping between glyph and codepoint. This way the font **AR PL UKai CN** can have a mapping to glyph **uni4EE4.C** for the codepoint **U+4EE4**, while the fonts **AR PL UKai HK**, **AR PL UKai TW** and **AR PL UKai VN** have a mapping to glyph **uni4EE4.TVH** instead. +This technology requires: + 1. a specific naming scheme throughout all variant glyph, + 1. all glyphs (including all variants) to be stored in the same font + 1. only one of the variants can be assigned to a codepoint at any time. The others are "_unassigned_". + 1. some magic behind the scenes when building the fonts, so that the appropriate glyphs get assigned the codepoint they should be used with, while all other variants for the same codepoint must be "_unassigned_". + + +--- + + + +* **Example:** + We want to add a new glyph, which is a variant of **U+8281 芁** we have created earlier in this tutorial. In this case the radical component 艹 has different shapes in China and Japan on the one hand and in Taiwan on the other hand. When we created the first glyph of this character, I chose to pick the Traditional Chinese form of the 艹 radical. Now, we are going to add the variant with the Simplified Chinese version of the 艹 radical. +* If you haven't done so already at the end of the first example, save the file to a new filename. +* Change the font encoding to be "Glyph Order" (Encoding -> Reencode -> Glyph Order). Now it only displays one glyph in Slot 1. +* Open the glyph (double click), select the 几 part and copy it into the clipboard (CRTL+C). +* Close the glyph editing window. +* Add another encoding slot: Encoding -> Add Encoding Slots -> 1 ([[Screenshot|http://people.ubuntu.com/~arne/cjk-unifonts/png/ff_example02_04.png]]) +* Open the new empty slot by double clicking on it. +* Paste the 几 part into the editing window ([[Screenshot|http://people.ubuntu.com/~arne/cjk-unifonts/png/ff_example02_05.png]]). +* Now we need the simplified radical version. If you have the original Arphic fonts lying around, it's a good idea to open the gkai00mp.ttf font file and look for a matching radical component there. +* I found the character U+82AC 芬 to have a suitable radical component ([[Screenshot|http://people.ubuntu.com/~arne/cjk-unifonts/png/ff_example02_06.png]]). Copy that one and paste it into the glyph editing window in the Back layer ([[Screenshot|http://people.ubuntu.com/~arne/cjk-unifonts/png/ff_example02_07.png]]). If it fits, move it over to the Front layer. +* Close the editing window ([[Screenshot|http://people.ubuntu.com/~arne/cjk-unifonts/png/ff_example02_08.png]]). +* Now we need to rename the traditional variant. Right mouse click on the glyph and choose "Glyph Info" ([[Screenshot|http://people.ubuntu.com/~arne/cjk-unifonts/png/ff_example02_02.png]]). +* In the "Unicode Name" field, we append **.T**, since this form is used only in Taiwan ([[Screenshot|http://people.ubuntu.com/~arne/cjk-unifonts/png/ff_example02_03.png]]). Then click OK. +* Now the same game for the simplified variant. Right mouse click on the glyph and choose "Glyph Info". +* In the "Unicode Name" field type **uni8281.CJ**, since this variant is used both in China and Japan ([[Screenshot|http://people.ubuntu.com/~arne/cjk-unifonts/png/ff_example02_09.png]]). +* Make sure that the "Unicode Value" field is **-1**, this glyph is _unassigned_, because the traditional form has already the codepoint assigned and only one of them can have the codepoint at any time. +* Now we are done with the font part, we should have two glyphs now, **uni8281.T** and **uni8281.CJ** ([[Screenshot|http://people.ubuntu.com/~arne/cjk-unifonts/png/ff_example02_10.png]]). Save your work! :) +* In order for the build script to do the right thing, we need to create a small text file for each font flavor. Just name them "vars_cn.txt", "vars_jp.txt" and "vars_tw.txt" in this case. In each of these text files type the Unicode codepoint, followed by a tab space and the glyph name which should be used in each font flavor. In this case, "vars_cn.txt" and "vars_jp.txt" would each get the line **8281<tab>uni8281.CJ** and "vars_tw.txt" would get a line **8281<tab>uni8281.T**. When you add more glyphs, just append the entries to these files ([[Screenshot|http://people.ubuntu.com/~arne/cjk-unifonts/png/ff_example02_11.png]]). +* Later, when you are done, zip or tar the .sfd and .txt files up and send them to me for inclusion into the main fonts. Currently it's best to send me this stuff via e-mail. I'm working on setting up a revision control system for this project, but because of the sheer size of the fonts, I'm currently hitting the wall. But I hope that over time this issue will get solved.
\ No newline at end of file diff --git a/Software/CJKUnifonts/Xdelta.mdwn b/Software/CJKUnifonts/Xdelta.mdwn new file mode 100644 index 00000000..406d3f9e --- /dev/null +++ b/Software/CJKUnifonts/Xdelta.mdwn @@ -0,0 +1,16 @@ + +**THIS PAGE IS OBSOLETE AS OF RELEASE 0.2.20080216** + +If you have already downloaded a tarball version of the fonts and only want to upgrade to a newer release, you can use xdelta to apply binary patches. + +For converting a uming font into umingmbe or ukai into ukaimbe find the xdelta file included in the tarball or debian package. + +You need to have xdelta version 1.1.3 installed. Debian users can simply get it via apt-get, others might want to visit [[http://www.xdelta.org|http://www.xdelta.org]]. Be sure to get version 1.1.3 and not any newer one, the newer ones are not compatible and have different purposes. + +Windows users can visit [[http://www.eng.uwaterloo.ca/~ejones/software/xdelta-win32.html|http://www.eng.uwaterloo.ca/~ejones/software/xdelta-win32.html]] + +Then put your tar.gz package of the old font and the downloaded xdelta file into a temporary directory and use: + +` xdelta patch xdelta_file font_file ` + +**THIS PAGE IS OBSOLETE AS OF RELEASE 0.2.20080216** diff --git a/Software/CfgDevel.mdwn b/Software/CfgDevel.mdwn new file mode 100644 index 00000000..54058f29 --- /dev/null +++ b/Software/CfgDevel.mdwn @@ -0,0 +1,12 @@ + +Things that have been discussed on the mailing list: + + * We don't want to depend on Xerces anymore. + * Implementation of remote administration that goes on top[1] or under[2] the Software.CFG framework in contrast to put dependencies right into Software.CFG. + * (problem may be overcome) Possibly reimplementing entirely in perl to avoid C++ <-> perl communication as only very recent gcc compilers don't have a bug that causes issues w/ it. [1] +[1] remote access (WBEM) top-layer [[http://article.gmane.org/gmane.comp.sysutils.cfg.devel/37|http://article.gmane.org/gmane.comp.sysutils.cfg.devel/37]] + +[2] remote access (ssh) backend [[http://article.gmane.org/gmane.comp.sysutils.cfg.devel/33|http://article.gmane.org/gmane.comp.sysutils.cfg.devel/33]] + +Back to Software.CFG + diff --git a/Software/CfgFAQ.mdwn b/Software/CfgFAQ.mdwn new file mode 100644 index 00000000..68792b49 --- /dev/null +++ b/Software/CfgFAQ.mdwn @@ -0,0 +1,134 @@ + + +# The Software.CFG Frequenty Asked Questions + + +## First to clear up some common misconceptions: + +Our system is an abstraction layer, *just like other config tools*. It is not a replacement for native config files, it does not require apps to use it, and it certainly does not intend to force a single way of doing things. It is just a tool that people can use to edit existing, plain text files one day, and the next day to edit them by hand if you wish. The system will provide an XML-based representation of the configuration which you can use for various purposes. This XML cache will be kept up to date with the native config files, and NOT the other way around. The beauty of our system is that you get an XML-based, structured interface to the native config files. Its just an interface, not necessarily a replacement. + +Our system currently allows application developers to read their configuration easily using our API, though it does not require it. It is not a registry, it is an interface. If you want to write your own parser or your own file format, go ahead. We'll try to handle your special formats, but we'd like to keep the number of config file formats to a minimum if possible. + +We intend the our base system to be for people who more or less know what they're doing or for foolproof frontends. Someone made a good point that even if you have been a sysadmin for 20 years, there are just some apps that you don't configure often enough to remember all the details needed to hand edit a config file without consulting a fair amount of documentation. + +Of course there are reasons why someone who doesn't know squat about unix should not be able to configure an important server in a production environment. Thats up to the boss. If they want to depend on someone being able to use our tool for their business to stay alive, they've got bigger problems. + +More importantly*, what if someone wants to mess with configuration on a *testing* machine? Why should it be so hard for them to learn? + + +## General Questions: + + +### Don't you guys know about [SOME CONFIG PROJECT]? + +* We've looked at various config editing projects, such as Webmin, Linuxconf, Ximian Setup Tools, and Debconf to name a few. In short, they aren't as flexible or modular as we think they should be. We've spent a lot of time fiddling with the design, and we think that our system is unique and that it provides significant benefits over existing tools. If we didn't think that, we wouldn't be wasting our time. :) + +### Isn't Software.CFG doomed to fail because the formats and options change so fast? + +In contrast to all other config tools around, the Software.CFG framework has the key advantage of external meta-configuration files. + +Well, first off the project will create meta-config-data files for current versions of popular software (apache, samba, php, qmail, etc.) Once these initial files are made, it is our hope (and we will work hard on making this happen) that the software maintainers or distro maintainers will include these files in the package with the software. This way, when user installs version x.y.z of software A on distro 34, the installer (whether its a tarball w/, an rpm, a .deb, an ebuild, whatever) will put the necessary files in the right place. If this were to happen, the headache would be gone. It is also important to know that these files consist of XML which is read by our system, and the XML would just define the configuration options and how they should be displayed, so that any reasonably up-to-date version of our software is able to handle it. If we can't get software maintainers to include the file, we'll make a web-based database which the system can automatically check and get the necessary files from. + +All the configuration will be in XML. If a particular configuration directive isn't recognized, it will be marked as such and will likely be displayed as a generic text entry field (although we're open to better suggestions). Since neither using our system or editing the config files by hand will exclude doing the other, extremely special situations won't be a problem as you can resort to doing it by hand. Keep in mind that both of us use a text editor to edit 99% of our config files and are more or less happy with that. We just think that there could (and should) be more options. + +To help people understand the configuration, we would like to provide context-sensitive documentation inside the config interfaces where possible. For example, I plan to write a parser that will take things like samba's man page (which is *excellent*) and create an XML representation of it to allow our middle layer to associate the documentation with each directive. This, of course, needs to be mostly automatic, since I know that I definitely don't want to write lots of XML documentation by hand for every release of every project if I can help it. + + +### This is bloat! + +As for the problem of bloat, we're hoping that will be avoided by the fact that no information about specific software is going to be included in our actual code. That way, when someone is editing samba's configuration, only the general core, the specific backend, the users's chosen frontend, and the XML meta-config-data files for samba will be needed. A user may or may not have the files on his/her system needed to allow him/her to configure apache with our system, but either way they won't be loaded. + +And after all, Software.CFG makes a lot of redundant code currently in different tools unneseccary. + + +### I think Software.CFG is a bad idea because [your opinion or experience with other config tools]. + +People like different things. There's nothing wrong with that. If you don't want to use our system, rest assured that even if you find yourself at a box which previously had only been configured by our system, you wouldn't even notice. And Software.CFG won't even change the layout or comments of your files if used intermittently, it will only change single values if asked to do so. This is because Software.CFG works with external meta-config-information and has been designed to be absolutely non-intrusive to other means of configuration handling. + + +### Wouldn't it be better to only use multiple diffs as entities to apply to config files? + +Software.CFG uses individual configuration settings and even comments as entities that can be individually validated and changed. As far as using only diffs of the new and current config files, we can currently completely reconstruct the config file *exactly* (byte for byte identical) as it was from our XML representation of the data. If we can do this, and we checked to make sure the file hadn't been changed by one user as another was editing it by hand, we should be ok. Either way, since we can re-create the exact (or slightly modified) config file, producing a diff of the two wouldn't be difficult either, and may be a good option (among others) for logging. + + +### Why don't you just concentrate on establishing a better standard for configuration storage like a virtual filesystem to access XML or some other nice thing? + +Again, this could be a possible alternate interface, which would certainly make configuration very accessibly at the command line and using already existing tools. This isn't a primary interface because it ties it to that specific OS, but it could easily be added later. Still, the native configuration needs to be parsed to and from XML in order to get into the XML-to-filesystem code, so this type of an extension would work nicely as an add-on interface. We hope to make libraries available so that such a thing could be done. I think it is a great idea, and would definitely work nicely over a network. + +Initially, our system will probably just rely on standard file permissions to determine whether a user can or can't update a configuration file, since that makes things simple. We want to make a durable core which allows these sorts of things to be easily added on, but we do agree that its important to keep things simple and not re-invent anything if we can help it. + + +### Re: GConf + +We did look at GConf among other projects, hoping that we could build on some existing code. One of GConf's main flaws is that the method for adding support for a new thing to configure involves writing a lot of C code and various other things, which we felt was too cumbersome. + +We want to make things simpler, and the architecture for GConf and most of the other tools wasn't flexible enough to accomplish what we're looking to do. Unfortunately (depending on how you look at it), it looks like we ended up writing lots of new code in order to accomplish this. The upside is that since we've putting tons of effort into planning, soliciting comments, and really thinking this through, the release should turn out pretty close to what we're going for. + + +### Re: Webmin + +There are some tools that are good at a lot of things. Webmin is one of them. Webmin has some flaws which detract from its usefulness to some extent. First, it is only web-based, which although that is probably the best interface to pick if you're going to focus on a single one, picking only one can also be bad. + +Second, webmin requires a module be written for each new software, and that this module be added by the user. Our system will (ideally) handle this automatically as version-appropriate files will be included with each software package. + +Third, webmin doesn't make it terribly easy to allow people to write new modules. There are some things built in, but not nearly enough. There's little reason why someone should have to write more than a basic text file to explain how a piece of software (or part of the system) is configured. We want our system to be easy and straightforward to use for everyone involved, without keeping people too far from the details. For example, we may want to display someplace in most of our interfaces a note explaining what actual config file the user is editing should they want to edit it by hand. + +Our system is specific to the task of configuration, but it will be general enough so that it won't need to be re-written to add support for new things. The process will be very simple, and may even be mostly automatic. + + +## About the Implementation: + + +### Doesn't Software.CFG have too many dependencies? + + +### Why is this not in my favourite programming language? + +In the case you would actually need a new parser or frontend you can write it in the language you prefer due to Software.CFG's modularity. However chances are you won't need to. + +Perl is used because it is well suited for parsing and wide spread. + + +### Why C and glib not just C++ ? + + +### How is Software.CFG's config representation organized? + +The actual XML data is organized by nested <section> tags, which accomplishes the necessary grouping. The individual parameter/value pairs are inside one or more levels of <section> tags. Even with INI style files (like samba) for example the guest ok directive can be used to globally allow guest access to samba shares, and any sections inherit this default value unless it is explicitly over-ridden. + +Properly handling defaults & inheritance is very important for the project's success since otherwise it won't be very useful for a lot of situations. + + +### Ok, now I want to have support for my own application, what do I need to do? How do I define my own XML meta-config-data? + +Currently you'd have to look at our extending howto at [[http://config4gnu.sourceforge.net/docs/extending/|http://config4gnu.sourceforge.net/docs/extending/]] particularly the section on adding entities. Also in CVS take a look at config4gnu/data/classes/ to see our current meta-data files. + +Our meta-config XML actually does not have a DTD for a couple of reasons. While we never actually tried, I don't think our meta-data could be validated against a schema/dtd. + +All our XML nodes are defined in meta-data as basically sub-classes of other nodes. Because of this, there are 2 problems with using standard schema/dtd validation, I'm assuming you're referring to #1 but I'll include #2 anyway. + +1) each node defined in meta-data can have ANY child elements that it wants to. While they are restricted to certain classes of nodes, current XML libraries don't support this type of validation. So, we can't validate them in the traditional way. It would be possible to write our own validator to do a good amount of sanity-checking, but we have not done this yet. + +2) the actual config data that comes from one of our more generic parsers (i.e., the apache-*style* parser) could be validated against a DTD. However, in practice we primarily use more specific parsers, and by the time the XML reaches the front-ends, it may have additional nodes added to it as defined in the meta-data, which as mentioned in #1 can't be validated using traditional XML libs. + + +### Finally, here is a working example of how you could edit your Samba configuration with a perl script: + +#!/usr/bin/perl use config4gnu; + +my $samba = config4gnu::get_configuration_root->resolve_path("/Daemons/Samba Configuration"); + +my $global_section = $samba->resolve_path(".samba-global"); + +my $wins_setting = $global_section->resolve_path(".wins_server"); + +print "Your samba's wins server is " . $wins_setting->get_string_value; + +This example script asks the config4gnu library to load the samba configuration file (i.e., /etc/samba/smb.conf) into XML, locate specific nodes in it, and retrieve the output. Modifying it is just as easy, and the change is saved back in the native config file without changing ANYTHING else (whitespace, comments, blank lines, etc.). + + +### Hacking on a frontend: emit clashes with the QT emit !!! + +Simply put the include to sigc++ BEFORE the includes for QT + +See: [[http://mail.gnome.org/archives/gnome-kde-list/1999-July/msg00012.html|http://mail.gnome.org/archives/gnome-kde-list/1999-July/msg00012.html]]
\ No newline at end of file diff --git a/Software/CompositeExt.mdwn b/Software/CompositeExt.mdwn new file mode 100644 index 00000000..9f6e9a6d --- /dev/null +++ b/Software/CompositeExt.mdwn @@ -0,0 +1,16 @@ + + +## X Composite Extension + +This extension causes a entire sub-tree of the window hierarchy to be rendered to an off-screen buffer. Applications can then take the contents of that buffer and do whatever they like. The off-screen buffer can be automatically merged into the parent window or merged by external programs, called compositing managers. Compositing managers enable [[lots of fun effects|http://freedesktop.org/~keithp/screenshots/]]. + + +## See Also + +* [[Composite Extension protocol specification|http://cgit.freedesktop.org/xorg/proto/compositeproto/tree/compositeproto.txt]] from git repository. + +* [[Composite Extension client library sources|http://cgit.freedesktop.org/xorg/lib/libXcomposite/]] from git. + +--- + + [[CategoryExtension|CategoryExtension]] diff --git a/Software/ConsoleKit.mdwn b/Software/ConsoleKit.mdwn new file mode 100644 index 00000000..7a2a26f4 --- /dev/null +++ b/Software/ConsoleKit.mdwn @@ -0,0 +1,50 @@ + + +# ConsoleKit + +[[ConsoleKit|Software/ConsoleKit]] is a framework for defining and tracking users, login sessions, and seats. +[[!table header="no" class="mointable" data=""" + [[ConsoleKit|ConsoleKit]] is currently not actively maintained. The focus has shifted to the built-in seat/user/session management of [[Software/systemd|Software/systemd]] called [[systemd-loginctl|http://0pointer.de/public/systemd-man/systemd-loginctl.html]] +"""]] + + +## Documentation + +* [[Latest ConsoleKit documentation|http://www.freedesktop.org/software/ConsoleKit/doc/ConsoleKit.html]] +* [[Building a Modern Multi-User Desktop (GUADEC 2007) - PDF|http://people.gnome.org/~mccann/talks/guadec-multiuser.pdf]] +* [[Original Announcement|http://lists.freedesktop.org/archives/hal/2007-January/006996.html]] + +## Source Code + +* View latest code on-line: [[http://cgit.freedesktop.org/ConsoleKit/tree/|http://cgit.freedesktop.org/ConsoleKit/tree/]] +* View latest changelog/commitlog online: [[http://cgit.freedesktop.org/ConsoleKit/log/|http://cgit.freedesktop.org/ConsoleKit/log/]] +* Tarballs are available at [[http://www.freedesktop.org/software/ConsoleKit/dist|http://www.freedesktop.org/software/ConsoleKit/dist]] + +### GIT + +There are [[guides for using git with freedesktop.org projects|http://freedesktop.org/wiki/Infrastructure/git]]. There is also another tutorial at [[IBM Developerworks site|http://www-128.ibm.com/developerworks/linux/library/l-git/]]. You can also take a look at [[http://cgit.freedesktop.org/ConsoleKit/tree/HACKING|http://cgit.freedesktop.org/ConsoleKit/tree/HACKING]]. + + +### Dependencies + + * Linux / Solaris 11+ / FreeBSD + * dbus 0.61 (or later) + * glib + gobject 2.6.0 (or later) + * Xlib + +#### Optional Dependencies + + * PAM + * inotify + +## Bugs + +* [[Open bugs|https://bugs.freedesktop.org/buglist.cgi?query_format=specific&order=relevance+desc&bug_status=__open__&product=ConsoleKit&content=]] +* [[Enter a new bug|https://bugs.freedesktop.org/enter_bug.cgi?product=ConsoleKit]] + +## Communicate + +* Mailing lists: + * [[!table header="no" class="mointable" data=""" +[[ConsoleKit|ConsoleKit]] Discussion | [[ConsoleKit@lists.freedesktop.org|http://lists.freedesktop.org/mailman/listinfo/ConsoleKit]] +"""]] diff --git a/Software/DBusAnalogy.mdwn b/Software/DBusAnalogy.mdwn new file mode 100644 index 00000000..8640693f --- /dev/null +++ b/Software/DBusAnalogy.mdwn @@ -0,0 +1,33 @@ + +Many people are confused about the concepts in DBus. This page gives an analogy to the web which should help to explain things. + + +## Concepts + +* unique bus name +* well-known bus name +* object path +* interface +* method name +* in parameters +* out parameters + +## Web Server Analogy + +* unique bus name is like an IP address. In particular it is dynamic. +* well-known bus name is like a hostname. It can be held by different programs at different times, but they should all implement the same API +* object path is like the path on the server +* interface/method name is like GET or POST +* in parameters are like like GET/POST variables +* out parameters are like the page which is returned. + +## Object-Oriented Language Analogy + +* an object path refers to an object, such as a java.lang.Object +* an interface is exactly like a Java interface +* in parameters are method arguments +* out parameters are method return values +* unique bus name identifies the running process or application uniquely (these bus names are never re-used by a different process) +* well-known bus name is a "symlink" that points to the process providing a particular API +* an API is made up of objects that are expected to exist, which are expected to implement certain interfaces +* see also [[http://log.ometer.com/2007-05.html#17|http://log.ometer.com/2007-05.html#17]]
\ No newline at end of file diff --git a/Software/DBusBindingErrors.mdwn b/Software/DBusBindingErrors.mdwn new file mode 100644 index 00000000..148ef13b --- /dev/null +++ b/Software/DBusBindingErrors.mdwn @@ -0,0 +1,60 @@ + +This page is for bindings authors to discuss what generic errors should be sent by the binding: +[[!table header="no" class="mointable" data=""" +**Name** | **Description** | **Comments** +[[ServiceUnknown|ServiceUnknown]] | The recipient bus name is not taken | In Core +[[UnknownObject|UnknownObject]] | The sender has called a method on an object not exported on this connection (the service name is valid) | Used by Java +[[UnknownInterface|UnknownInterface]] | The sender has specified an interface this object does not implement (but the object is valid) | Requested by Thiago +[[UnknownMethod|UnknownMethod]] | The specified method is not implemented on this object (but the object and the interface names are valid) | In core +[[InvalidParameters|InvalidParameters]] | Method was called with an invalid number or type of parameters. (Comment: org.freedesktop.DBus.Error.[[InvalidArgs|InvalidArgs]] seems more suitable for this use, especially considering there is no "parameter" in D-Bus terminology -- alp) | Suggested by Matt +"""]] + +Please add other errors you think should, or could possibly, be useful + +Other comments: + +* What about errors in executing the method within the binding? There could be problems with marshalling and so on? At the moment I send an internal error with a specific message, should there be a generic error type? - Matt +* About [[InvalidParameters|InvalidParameters]]: some bindings could not implement it and use only [[UnknownMethod|UnknownMethod]]. Methods in those bindings are recognised by both the method name and signature. The bindings that support overloading through parameters are the case (C++ and Java especially). +* Objects that have children must never reply with [[UnknownObject|UnknownObject]]. + +## The format of error messages + +The spec suggests that error messages can contain different arguments and aren't restricted to a single string. Do any core errors or binding errors make use of this? Would this be useful when mapping exceptions thrown by an object binding, say for the stack trace etc.? + +The spec should specifically say whether the string is mandatory as the first parameter or not. It should also make it clear if more parameters are permitted or not. + + +## Well-known core errors + +This is a list of core errors for reference. They are usually kept in order because it seems the glib binding puts them in an enumeration. Are these documented anywhere? + +* org.freedesktop.DBus.Error.Failed +* org.freedesktop.DBus.Error.[[NoMemory|NoMemory]] +* org.freedesktop.DBus.Error.[[ServiceUnknown|ServiceUnknown]] +* org.freedesktop.DBus.Error.[[NameHasNoOwner|NameHasNoOwner]] +* org.freedesktop.DBus.Error.[[NoReply|NoReply]] +* org.freedesktop.DBus.Error.IOError +* org.freedesktop.DBus.Error.[[BadAddress|BadAddress]] +* org.freedesktop.DBus.Error.[[NotSupported|NotSupported]] +* org.freedesktop.DBus.Error.[[LimitsExceeded|LimitsExceeded]] +* org.freedesktop.DBus.Error.[[AccessDenied|AccessDenied]] +* org.freedesktop.DBus.Error.[[AuthFailed|AuthFailed]] +* org.freedesktop.DBus.Error.[[NoServer|NoServer]] +* org.freedesktop.DBus.Error.Timeout +* org.freedesktop.DBus.Error.[[NoNetwork|NoNetwork]] +* org.freedesktop.DBus.Error.[[AddressInUse|AddressInUse]] +* org.freedesktop.DBus.Error.Disconnected +* org.freedesktop.DBus.Error.[[InvalidArgs|InvalidArgs]] +* org.freedesktop.DBus.Error.[[FileNotFound|FileNotFound]] +* org.freedesktop.DBus.Error.[[UnknownMethod|UnknownMethod]] +* org.freedesktop.DBus.Error.[[TimedOut|TimedOut]] +* org.freedesktop.DBus.Error.[[MatchRuleNotFound|MatchRuleNotFound]] +* org.freedesktop.DBus.Error.[[MatchRuleInvalid|MatchRuleInvalid]] +* org.freedesktop.DBus.Error.Spawn.[[ExecFailed|ExecFailed]] +* org.freedesktop.DBus.Error.Spawn.[[ForkFailed|ForkFailed]] +* org.freedesktop.DBus.Error.Spawn.[[ChildExited|ChildExited]] +* org.freedesktop.DBus.Error.Spawn.[[ChildSignaled|ChildSignaled]] +* org.freedesktop.DBus.Error.Spawn.Failed +* org.freedesktop.DBus.Error.[[UnixProcessIdUnknown|UnixProcessIdUnknown]] +* org.freedesktop.DBus.Error.[[InvalidSignature|InvalidSignature]] +* org.freedesktop.DBus.Error.SELinuxSecurityContextUnknown
\ No newline at end of file diff --git a/Software/DBusBindings.mdwn b/Software/DBusBindings.mdwn new file mode 100644 index 00000000..ca873b1a --- /dev/null +++ b/Software/DBusBindings.mdwn @@ -0,0 +1,253 @@ + +This page lists the language bindings for D-Bus, their status and, if appropriate, links to download them. + + +## GDBus (D-Bus support in GLib) + +Since version 2.26, GLib includes a D-Bus binding. This is intended to replace the DBus-GLib bindings and many applications have started migrating their code. See the documentation for the [[high-level|http://library.gnome.org/devel/gio/2.26/gdbus-convenience.html]] and [[low-level|http://library.gnome.org/devel/gio/2.26/gdbus-lowlevel.html]] API for more details. + + +## DBus-GLib (obsolete) + +**New GLib applications should use the D-Bus support built into GLib. See above.** + +You can find the old dbus-glib binding in Freedesktop's [[git repo|http://cgit.freedesktop.org/dbus/dbus-glib/]]. To access with git: + +* users with commit access: git+[[ssh://git.freedesktop.org/git/dbus/dbus-glib|ssh://git.freedesktop.org/git/dbus/dbus-glib]] +* anonymous read only access: git://anongit.freedesktop.org/git/dbus/dbus-glib +* [[API documentation|http://dbus.freedesktop.org/doc/dbus-glib/index.html]] +* [[Training material for Glib wrappers from maemo|http://maemo.org/maemo_training_material/maemo4.x/html/maemo_Platform_Development_Chinook/Chapter_03_Using_the_GLib_wrappers_for_DBus.html]] +A page for working on a roadmap for dbus-glib's future can be found at [[DBusGLibRoadmap|DBusGLibRoadmap]]. + + +## e_dbus + +You can find latest EFL (Enlightenment) bindings in Enlightenment [[Subversion repo|http://trac.enlightenment.org/e/browser/trunk/e_dbus]]. To access with SVN: + +* anonymous read only access: svn co [[http://svn.enlightenment.org/svn/e/trunk/e_dbus|http://svn.enlightenment.org/svn/e/trunk/e_dbus]] svn co [[https://svn.enlightenment.org/svn/e/trunk/e_dbus|https://svn.enlightenment.org/svn/e/trunk/e_dbus]] +**The latest release is [[here|http://download.enlightenment.org/snapshots/LATEST/]].** + + +## edelib + +edelib is a base library for [[EDE|http://equinox-project.org]] and comes with own C++ D-Bus binding. Latest source can be obtained via anonymous SVN access: + +* svn co [[https://ede.svn.sourceforge.net/svnroot/ede/trunk/edelib|https://ede.svn.sourceforge.net/svnroot/ede/trunk/edelib]] + +## Python + + +### GDBus + +GDBus, the D-Bus implementation in GLib, can be used from Python 2 or 3 via GObject-Introspection and PyGI. + + +### QtDBus + +QtDBus, the D-Bus implementation in Qt, can be used from Python 2 or 3 via recent versions of [[PyQt|PyQt]]. + + +### txdbus + +[[txdbus|http://pypi.python.org/pypi/txdbus]] is a native Python implementation of the D-Bus protocol for the Twisted networking framework. + + +### dbus-python + +dbus-python is a binding for libdbus, the reference implementation of D-Bus. For compatibility reasons, its API involves a lot of type-guessing (despite "explicit is better than implicit" and "resist the temptation to guess"). + +Since version 1.0.0 it supports both Python 2 and 3. + +* [[Recent release history|http://dbus.freedesktop.org/doc/dbus-python/NEWS.html]] +* Releases are always available from [[http://dbus.freedesktop.org/releases/dbus-python/|http://dbus.freedesktop.org/releases/dbus-python/]] +* API and other documentation are at [[http://dbus.freedesktop.org/doc/dbus-python/|http://dbus.freedesktop.org/doc/dbus-python/]] +* dbus-python is maintained in git: [[dbus-python git web|http://cgit.freedesktop.org/dbus/dbus-python/]] +* For users with commit access: git clone git+[[ssh://git.freedesktop.org/git/dbus/dbus-python|ssh://git.freedesktop.org/git/dbus/dbus-python]] +* For anonymous read only access: git clone git://anongit.freedesktop.org/git/dbus/dbus-python +* Bugs are tracked in the freedesktop.org bugzilla: [[search for dbus-python bugs|https://bugs.freedesktop.org/buglist.cgi?product=dbus&component=python&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED]] or [[file a dbus-python bug|https://bugs.freedesktop.org/enter_bug.cgi?product=dbus&component=python]] + +## Java + +There are now three versions of Java D-Bus. Since version 2.0 it has been a complete native implementation of the protocol and not a wrapper around the reference implementation. 1.x versions are feature-complete bindings around the reference implementation, but only work with 1.5-compatible VMs (Currently only Sun). There are older 1.4-compatible bindings which are feature incomplete and have not had much optimization work. See below if you want to try these. + +Java D-Bus is hosted in freedesktop.org's [[git repository|http://cgit.freedesktop.org/dbus/dbus-java/]] and can be accessed: + +For users with commit access: git+[[ssh://git.freedesktop.org/git/dbus/dbus-java|ssh://git.freedesktop.org/git/dbus/dbus-java]] + +For anonymous read only access: git://anongit.freedesktop.org/git/dbus/dbus-java + +**The current release is [[dbus-java-2.7.tar.gz|http://dbus.freedesktop.org/releases/dbus-java/dbus-java-2.7.tar.gz]]. (2009-12-06)** + +Version 2.7: + +* Fix bug in disconnected signal/exception handling (Spotted by Serkan Kaba <serkan_kaba -at- yahoo -dot- com>) +* Fix bug in empty signals (Spotted by Daniel Wagner <Daniel -dot- Wagner -at- bmw-carit -dot- de>) +* Fix bug in maps containing complex types (Spotted by Tim Court <tim -dot- court -at- venture3systems -dot- com>) +* Fix signal handling bug in DBusDaemon (Spotted by Markus Gaebelein <Markus -dot- Gaebelein -at- fiducia -dot- de>) +* Make MessageReader/Writer use Buffered streams to try and improve performance +* Support reading session bus address from file in $HOME +* Fix TCP cookie timestamp problems (Report/fix from Johannes Felten <johannesfelten -at- googlemail -dot- com>) +* Add handleError() method to callbacks (breaks backwards source compatibility) +**The previous release was [[dbus-java-2.6.tar.gz|http://dbus.freedesktop.org/releases/dbus-java/dbus-java-2.6.tar.gz]]. (2009-04-05)** + +Version 2.6: + +* Add DBusConnection.releaseBusName API +* Add DBusConnection.[[PeerSet|PeerSet]] for tracking peer lifetimes +* Fix bug where DBusDaemon never sends [[NameOwnerChanged/NameLost|NameOwnerChanged/NameLost]] signals +* Patches from Omair Majid <omajid -at- redhat -dot- com> to fix DBusCall manpage and allow alternative docbook-to-man implementations. +* Fix dependency on unix.jar even in tcp mode +* Fix Path/ObjectPath cast issues (reported by Greg [[DeAngelis|DeAngelis]] <gdeangel -at- gmail -dot- com>) +* Fix behavior when disconnected (spotted by Christopher Armstrong <carmstrong -at- fastmail -dot- com -dot- au>) +The last release binding the reference implementation is [[libdbus-java-1.13.tar.gz|http://dbus.freedesktop.org/releases/dbus-java/libdbus-java-1.13.tar.gz]]. + +Documentation and API reference for the Java implementation of D-Bus is [[here|http://dbus.freedesktop.org/doc/dbus-java/]]. + +The older 1.4-compatible bindings are still available [[here|http://www.matthew.ath.cx/projects/java]]. + +The Maintainer is Matthew Johnson < [[dbus@matthew.ath.cx|mailto:dbus@matthew.ath.cx]] > + + +## Qt4 + +The D-Bus bindings for Qt4 are distributed alongside Qt itself, starting with version 4.2. + +The bindings are documented at [[http://doc.trolltech.com/qtdbus.html|http://doc.trolltech.com/qtdbus.html]]. + +The latest release can be found at [[http://www.trolltech.com/developer/downloads/qt/index|http://www.trolltech.com/developer/downloads/qt/index]]. More recent versions can be found in Qt's [[nightly snapshots|http://www.trolltech.com/developer/downloads/qt/snapshots]]. + + +## Perl + +The Perl bindings currently work on any Perl >= 5.8.x and any D-Bus version from 0.33.0 onwards. They can be downloaded from [[CPAN|http://search.cpan.org]] under the [[Net-DBus|http://search.cpan.org/~danberr/Net-DBus-1.0.0/]] module: + +* [[Net-DBus-1.0.0.tar.gz|http://search.cpan.org/CPAN/authors/id/D/DA/DANBERR/Net-DBus-1.0.0.tar.gz]] +* [[API documentation|http://search.cpan.org/~danberr/Net-DBus-1.0.0/lib/Net/DBus.pm]] +* [[Tutorials|http://search.cpan.org/~danberr/Net-DBus-1.0.0/lib/Net/DBus/Tutorial.pod]] +The maintainer is [[Daniel P. Berrange|http://search.cpan.org/~danberr/]], and the source code is managed in a Git repository at [[https://gitorious.org/net-dbus|https://gitorious.org/net-dbus]] + + +## C++ + +[[dbus-cpp|Software/dbus-cpp]] was started almost three years ago to provide a C++ API for D-Bus, but is unfortunately abandoned since then. For this reason [[PaoloDurante|PaoloDurante]] wrote a pure C++ binding ([[dbus-c++|Software/dbus-c++]]) while working on the [[OpenWengo|http://dev.openwengo.com/]] softphone. + + +### dbus-cxx + +[[dbus-cxx|http://dbus-cxx.sourceforge.net]] provides a C++ API for D-Bus, but explicitly exposes the C API as well. dbus-cxx-glibmm provides a way to integrate dbus-cxx with Glibmm/Gtkmm applications. + +* Project home: [[http://dbus-cxx.sourceforge.net|http://dbus-cxx.sourceforge.net]] +* _dbus-cxx-xml2cpp_ generates C++ proxy and adapter interfaces from extended D-Bus XML introspection documents +* Fedora packages are available in Fedora 9+ (dbus-cxx, dbus-cxx-devel, dbus-cxx-doc, dbus-cxx-glibmm, dbus-cxx-glibmm-devel, dbus-cxx-tools) +* Ubuntu packages are available from Launchpad's PPA +* [[Documentation|http://dbus-cxx.sourceforge.net/hierarchy.html]] +* [[News|http://sourceforge.net/news/?group_id=259994]] +* [[Subversion repository|http://dbus-cxx.svn.sourceforge.net/viewvc/dbus-cxx/trunk/dbus-cxx]] +* Mailing lists + * Users List (for those developing with dbus-cxx): + * [[Archives|http://sourceforge.net/mailarchive/forum.php?forum_name=dbus-cxx-users]] + * [[Subscribe/Unsubscribe|http://lists.sourceforge.net/mailman/listinfo/dbus-cxx-users]] + * Development List (for development of dbus-cxx itself): + * [[Archives|http://sourceforge.net/mailarchive/forum.php?forum_name=dbus-cxx-devel]] + * [[Subscribe/Unsubscribe|http://lists.sourceforge.net/mailman/listinfo/dbus-cxx-devel]] + +## PHP + +PHP bindings (PECL) are in progress and details can be found [[here|http://pecl.php.net/package/DBus]]. This extension allows you to talk to DBUS services on a system, and also act as a DBUS service. + +An additional PHP only binding with limited functionality is available [[on github|http://github.com/dNG-git/php_dbus]]. This one allows you to interact with DBUS services on a system as a client application. + + +## Pascal + +Free Pascal has bindings of version 1.2.16 included in release 2.6. + + +## Qt3 + +There is a Qt3 backport of the Qt4 bindings available under [[WebSVN@KDE|http://websvn.kde.org/branches/work/dbus-qt4-qt3backport/]] and [ [[http://people.freedesktop.org/~krake/dbus-1-qt3/libdbus-1-qt3-0.8.tar.gz|http://people.freedesktop.org/~krake/dbus-1-qt3/libdbus-1-qt3-0.8.tar.gz]] Sources ca. 600 KB] + +Check out through anonymous SVN is also avialable: _svn co svn://anonsvn.kde.org/home/kde/branches/work/dbus-qt4-qt3backport_ + +API documentation can be found here: [[API Docs|http://people.freedesktop.org/~krake/dbus-1-qt3/api-docs/]] + +The maintainer is Kevin Krammer < [[kevin.krammer@gmx.at|mailto:kevin.krammer@gmx.at]] > + + +## .NET + +The .NET bindings located in the D-Bus GIT server is unmaintained. They are scheduled to be removed unless a maintainer steps up. The have been split and placed in a [[git repo|http://cgit.freedesktop.org/dbus/dbus-mono/]] for anyone who would like to pick up maintainership. It can be accessed via git at: + +For users with commit access: git+[[ssh://git.freedesktop.org/git/dbus/dbus-mono|ssh://git.freedesktop.org/git/dbus/dbus-mono]] + +For anonymous read only access: git://anongit.freedesktop.org/git/dbus/dbus-mono + +For those interested in .NET support, the [[D-Bus Sharp|http://www.ndesk.org/DBusSharp]] implementation provides an alternative and is in active development. D-Bus Sharp is not a binding to the reference implementation, but an alternative implementation of the D-Bus protocol. + + +## Ruby + +The most active and complete ruby implementation at this point is the ruby-dbus project at [[https://trac.luon.net/ruby-dbus/|https://trac.luon.net/ruby-dbus/]]. This is a follow on from the original ruby-dbus project on rubyforge. + +Sven Herzberg was asked by a friend to develop dbus bindings for ruby. His git repository is located at: [[http://www.blaubeermuffin.de/rdbus.git|http://www.blaubeermuffin.de/rdbus.git]] + + +## Scheme + +[[Chicken Scheme|http://www.call-with-current-continuation.org]] binding can be found at chicken's _Egg Repository_ as [[dbus egg|http://chicken.wiki.br/dbus]]. The same place contains few short usage samples. + + +## Tcl + +The Tcl bindings are hosted under the [[dbus-tcl project at SourceForge|http://sourceforge.net/projects/dbus-tcl]]. At least Tcl version 8.5 is required to use the dbus-tcl package. + +* [[Release download page|http://sourceforge.net/project/showfiles.php?group_id=234589&package_id=284807]] +* [[API documentation|http://dbus-tcl.sourceforge.net/dbus-tcl.html]] + +## Squeak + +The Squeak Smalltalk bindings are available under the [[dbus project at Squeak Source site|http://squeaksource.com/dbus.html]]. + +* [[Releases, News and Description are available on this page.|http://squeaksource.com/dbus.html]] + +## Haskell + +The [[dbus-core|https://john-millikin.com/software/dbus-core/]] library is an implementation of the D-Bus protocol in Haskell. The current version is [[0.9|https://john-millikin.com/downloads/dbus-core_0.9.tar.gz]]. + + +## OCaml + +OCaml has an alternative implementation of D-BUS, it is called OBus. The current version is [[obus-1.0rc1|http://forge.ocamlcore.org/frs/download.php/280/obus-1.0rc1.tar.gz]]. + +* [[Home page|http://obus.forge.ocamlcore.org/]] +* [[Darcs repository|http://darcs.ocamlcore.org/cgi-bin/darcsweb.cgi?r=obus;a=summary]] + +## Gambas + +Gambas has a D-Bus component implementation in its development version. That component allows to: + +* Call any method and properties of any application connected to D-Bus. +* Catch any signal sent by any application connected to D-Bus. +* Automatically export application objects to D-Bus. +For more information: + +* [[Gambas home page|http://gambas.sourceforge.net]] +* [[D-Bus component documentation|http://gambasdoc.org/help/comp/gb.dbus?v3]] + +## Objective-C + +The GNUstep project provides Objective-C bindings for D-Bus with the DBusKit project. It can be obtained via SVN: + +* svn co svn://svn.gna.org/svn/gnustep/libs/dbuskit/trunk + +## Ada + + +### D_Bus/Ada + +The [[D_Bus/Ada|http://www.codelabs.ch/dbus-ada/]] project provides an Ada binding to D-Bus. + +* [[Download|http://www.codelabs.ch/download]] +* [[Git repository|http://git.codelabs.ch/?p=dbus-ada.git]] +* Packages are available in Debian (>= Wheezy) +* Packages are available in Ubuntu (>= Quantal Quetzal)
\ No newline at end of file diff --git a/Software/DBusRemote.mdwn b/Software/DBusRemote.mdwn new file mode 100644 index 00000000..53b46eae --- /dev/null +++ b/Software/DBusRemote.mdwn @@ -0,0 +1,26 @@ + +There are plans to get [[D-Bus|Software/dbus]] communication working also in situations where the two programs are not on the same computer and thus cannot use the default unix domain sockets. Possibilities include TCP/IP, SSH forwarding the bus daemon, a proxy daemon, or D-Bus over X. TCP/IP and SSH forwarding could in theory work without further programming. Most remote scenarios would require authentication of end points and encryption of messages on the wire though. + +A simple use case is running a remote application that wants to communicate with the local session bus. Another interesting setup is running an X session and the session bus remotely on a server machine, but allow the applications to contact the system bus running locally on a thin client. + + +## TCP/IP + +The TCP/IP transport isn't tested in use and it has the problems of access control, lack of encryption, and inability to go through firewalls and NAT. + + +## SSH forwarding + +SSH doesn't support forwarding of unix domain sockets. Even if it did, the methods that return unix user and unix process would return the local SSH process and not the remote information - perhaps that's not a problem, but needs documentation at least. + +A program called socat has been used before to adapt unix domain sockets to SSH forwarding. + + +## Proxy daemon + +Implementing a proxy daemon that poses as a bus daemon and also connects to the existing bus as a client has the problem of unix user and unix process too. + + +## D-Bus over X + +Transporting D-Bus messages over the X protocol does not work in the general case as X isn't always available. The advantages would be automatic support for SSH-forwarded X clients and NX etc. It's not known how much this approach would harm efficieny. diff --git a/Software/DbusProjects.mdwn b/Software/DbusProjects.mdwn new file mode 100644 index 00000000..0bd56fe7 --- /dev/null +++ b/Software/DbusProjects.mdwn @@ -0,0 +1,223 @@ + + +### D-Bus users + +Below is a list of projects using D-Bus. It is not complete so if you know of a project which should be added please just edit the wiki. (Or send mail to the [[mailing list|http://freedesktop.org/mailman/listinfo/dbus/]] and see if someone has time to do it for you.) + +The list also includes the bus names owned by the projects' software. This is to help avoid namespace clashes as it is important that no two projects use the same bus name. Not all D-Bus usages require owning a bus name, of course. + +Be sure to namespace your bus name in com.example.[[ReverseDomainStyle|ReverseDomainStyle]] as well as listing it here. + +Finally, the API column shows a code indicating which of the various D-Bus APIs has been used. These are defined as follows: + +* ** **D* - the raw D-BUS library ** **G* - the GLib bindings ** **Q* - the Qt bindings ** **P* - the Python bindings ** **M* - the Mono/.NET bindings [[!table header="no" class="mointable" data=""" + **Project** | **Description** | **Bus Name** | **API** + [[Avahi|http://www.freedesktop.org/Software/Avahi]] | mDNS Responder | org.freedesktop.Avahi | DGP + [[BMPx|http://bmpx.beep-media-player.org/]] | Music Player | org.beepmediaplayer.bmp | GP + [[Compiz-Fusion|http://compiz-fusion.org/]] | Compositing engine and effect plugins | org.freedesktop.compiz | D + [[CUPS|http://www.cups.org/]] (with patch) | The Common UNIX Printing System | com.redhat.[[PrinterSpooler|PrinterSpooler]] | D + [[eggcups|http://cyberelk.net/tim/data/eggcups/]] | eggtray printer icon | - | DG + [[EDE|http://equinox-project.org]] | Equinox Desktop | org.equinoxproject | D + [[freesmartphone.org|http://docs.freesmartphone.org]] | Mobile Device framework (GPS, GSM, ... | org.freesmartphone | D + [[Galago|http://galago.sourceforge.net/]] | desktop-neutral presence system | org.freedesktop.Galago | DG + [[Gajim|http://www.gajim.org/]] | Jabber client written in PyGTK | org.gajim.dbus | GP +[[Gossip|http://developer.imendio.com/projects/gossip]] | Jabber client | org.gnome.Gossip | G + [[GNOME Power Manager|http://gnome-power.sourceforge.net/]] | Power management daemon | org.gnome.[[GnomePowerManager|GnomePowerManager]] | G + [[Gnome Nautilus|http://live.gnome.org/Nautilus]] | File manager | In project | + GNOME Screen Saver | Screen Saver | org.gnome.[[ScreenSaver|ScreenSaver]] | G + [[Gnome Volume Manager|http://cvs.gnome.org/viewcvs/gnome-volume-manager/]] | Volume manager | In project + [[HAL|http://hal.freedesktop.org/]] | Hardware abstraction layer | org.freedesktop.Hal | PDG + [[HFP for Linux|http://nohands.sourceforge.net/]] | Bluetooth Hands-Free Profile Service | net.sf.nohands.hfpd | DP + [[Jamboree|http://www.imendio.com/projects/jamboree/]] | Music player | org.imendio.jamboree | DG + [[NavSys|http://www.navsys.org]] | Vehicle entertainment and navigation system | org.navsys | DG + [[NetworkManager|http://people.redhat.com/dcbw/NetworkManager/]] | Network link manager | org.freedesktop.[[NetworkManager|NetworkManager]] | PDG + [[oddjob|http://people.redhat.com/nalin/oddjob/]] | Privilege escalation service | com.redhat.oddjob | D + [[Pathfinder|http://www.carillon.ca/products/pathfinder.php]] | X.509 Path Discovery and Validation System | ca.carillon.pathfinder | D + [[Permovi|http://forge.novell.com/modules/xfmod/project/?permovi]] | Home Theatre PC application | org.permovi | M + [[Pidgin|http://developer.pidgin.im/wiki/DbusHowto]] | Instant Messaging client | im.pidgin.purple.PurpleInterface | ??? + [[Psi|http://psi-im.org]] | XMPP client | org.psi_im.Psi | Q + [[ROX-Session|http://rox.sourceforge.net/phpwiki/index.php/ROX-Session]] | Desktop session manager | net.sf.rox.Session, net.sf.rox.Session.Settings | GP + [[Skype|http://skype.com]] | Skype API | com.Skype.API | ? + [[Telepathy|http://telepathy.freedesktop.org/]] | Instant messaging framework | org.freedesktop.Telepathy.* (see API docs) | GMPQ (mainly G) + [[udev|http://www.kernel.org/pub/linux/utils/kernel/hotplug/udev-FAQ]] | Userspace implementation of devfs | org.kernel.uidev | D + [[Zero Install|http://0install.net]] | Software installation system | - | DG + [[UniConf|http://alumnit.ca/wiki/index.php?page=UniConf]] | Universal Configuration System | ca.nit.uniconfd | DG + [[XChat|http://www.xchat.org/]] | Multiplatform IRC Client | org.xchat.[[RemoteObject|RemoteObject]] | G + [[MyPlay|http://code.google.com/p/myplay/]] | Music playing service | org.nadako.myplay | GP + [[SwarmTv|http://www.swarmtv.nl/]] | Video downloading service | nl.swarmtv | GQ + KDE related applications | | | + [[Akregator|http://www.kde.org/applications/Internet/akregator/]] | Feed Reader | org.kde.akregator | Q + [[Amarok|http://www.kde.org/applications/Multimedia/amarok/]] | Audio Player | org.kde.amarok | Q + [[Ark|http://www.kde.org/applications/Utilities/ark/]] | Archiving Tool | org.kde.ark | Q + [[Blinken|http://www.kde.org/applications/Education/blinken/]] | Memory Enhancement Game | org.kde.blinken | Q + [[Blogilo|http://www.kde.org/applications/Internet/blogilo/]] | A KDE Blogging Client | org.kde.blogilo | Q + [[Bomber|http://www.kde.org/applications/Games/bomber/]] | Arcade Bombing Game | org.kde.bomber | Q + [[Bovo|http://www.kde.org/applications/Games/bovo/]] | Five-in-a-row Board Game | org.kde.bovo | Q + [[Cantor|http://www.kde.org/applications/Education/cantor/]] | KDE Frontend to Mathematical Software | org.kde.cantor | Q + [[Cervisia|http://www.kde.org/applications/Development/cervisia/]] | CVS Frontend | org.kde.cervisia | Q + [[Choqok|http://www.kde.org/applications/Internet/choqok/]] | KDE Micro-blogging Client | org.kde.choqok | Q + [[digiKam|http://www.kde.org/applications/Graphics/digikam/]] | Photo Management Program | org.kde.digikam | Q + [[Dolphin|http://www.kde.org/applications/System/dolphin/]] | File Manager | org.kde.dolphin | Q + [[Dragon Player|http://www.kde.org/applications/Multimedia/dragon player/]] | Video Player | org.kde.dragon player | Q + [[Granatier|http://www.kde.org/applications/Games/granatier/]] | Bomberman clone | org.kde.granatier | Q + [[Gwenview|http://www.kde.org/applications/Graphics/gwenview/]] | Image Viewer | org.kde.gwenview | Q + [[Jovie|http://www.kde.org/applications/Utilities/jovie/]] | KDE Text To Speech Daemon | org.kde.jovie | Q + [[JuK|http://www.kde.org/applications/Multimedia/juk/]] | Music Player | org.kde.juk | Q + [[K3b|http://www.kde.org/applications/Multimedia/k3b/]] | Disk Burning | org.kde.k3b | Q + [[KAddressBook|http://www.kde.org/applications/Office/kaddressbook/]] | Contact Manager | org.kde.kaddressbook | Q + [[Kaffeine|http://www.kde.org/applications/Multimedia/kaffeine/]] | Media Player | org.kde.kaffeine | Q + [[Kajongg|http://www.kde.org/applications/Games/kajongg/]] | Mah Jongg | org.kde.kajongg | Q + [[KAlarm|http://www.kde.org/applications/Utilities/kalarm/]] | Personal Alarm Scheduler | org.kde.kalarm | Q + [[KAlgebra|http://www.kde.org/applications/Education/kalgebra/]] | Graph Calculator | org.kde.kalgebra | Q + [[Kalzium|http://www.kde.org/applications/Education/kalzium/]] | Periodic Table of Elements | org.kde.kalzium | Q + [[Kanagram|http://www.kde.org/applications/Education/kanagram/]] | Letter Order Game | org.kde.kanagram | Q + [[Kapman|http://www.kde.org/applications/Games/kapman/]] | Pac-Man Clone | org.kde.kapman | Q + [[KAppfinder|http://www.kde.org/applications/System/kappfinder/]] | Menu Updating Tool | org.kde.kappfinder | Q + [[KAppTemplate|http://www.kde.org/applications/Development/kapptemplate/]] | KDE Template Generator | org.kde.kapptemplate | Q + [[Karbon14|http://www.kde.org/applications/Graphics/karbon14/]] | Scalable Graphics | org.kde.karbon14 | Q + [[Kate|http://www.kde.org/applications/Utilities/kate/]] | Advanced Text Editor | org.kde.kate | Q + [[katimon|http://www.kde.org/applications/System/katimon/]] | ATI Graphics Card monitor and overclocking GUI. | org.kde.katimon | Q + [[KAtomic|http://www.kde.org/applications/Games/katomic/]] | Sokoban-like Logic Game | org.kde.katomic | Q + [[KAudioCreator|http://www.kde.org/applications/Multimedia/kaudiocreator/]] | CD Ripper | org.kde.kaudiocreator | Q + [[KBattleship|http://www.kde.org/applications/Games/kbattleship/]] | Battleship Game | org.kde.kbattleship | Q + [[KBlackbox|http://www.kde.org/applications/Games/kblackbox/]] | Blackbox Logic Game | org.kde.kblackbox | Q + [[KBlocks|http://www.kde.org/applications/Games/kblocks/]] | Falling Blocks Game | org.kde.kblocks | Q + [[KBounce|http://www.kde.org/applications/Games/kbounce/]] | Ball Bouncing Game | org.kde.kbounce | Q + [[KBreakout|http://www.kde.org/applications/Games/kbreakout/]] | Breakout-like Game | org.kde.kbreakout | Q + [[KBruch|http://www.kde.org/applications/Education/kbruch/]] | Exercise Fractions | org.kde.kbruch | Q + [[KCachegrind|http://www.kde.org/applications/Development/kcachegrind/]] | Profiler Frontend | org.kde.kcachegrind | Q + [[KCalc|http://www.kde.org/applications/Utilities/kcalc/]] | Scientific Calculator | org.kde.kcalc | Q + [[KCharSelect|http://www.kde.org/applications/Utilities/kcharselect/]] | Character Selector | org.kde.kcharselect | Q + [[KColorChooser|http://www.kde.org/applications/Graphics/kcolorchooser/]] | Color Chooser | org.kde.kcolorchooser | Q + [[KColorEdit|http://www.kde.org/applications/Graphics/kcoloredit/]] | Color Palette Editor | org.kde.kcoloredit | Q + [[KDE Partition Manager|http://www.kde.org/applications/System/kde partition manager/]] | Partition Editor | org.kde.kde partition manager | Q + [[KDevelop|http://www.kde.org/applications/Development/kdevelop/]] | Integrated Development Environment | org.kde.kdevelop | Q + [[KDiamond|http://www.kde.org/applications/Games/kdiamond/]] | Three-in-a-row game | org.kde.kdiamond | Q + [[KDiff3|http://www.kde.org/applications/Development/kdiff3/]] | Diff/Patch Frontend | org.kde.kdiff3 | Q + [[KDiskFree|http://www.kde.org/applications/System/kdiskfree/]] | View Disk Usage | org.kde.kdiskfree | Q + [[Kerry|http://www.kde.org/applications/Utilities/kerry/]] | Desktop Search | org.kde.kerry | Q + [[KEuroCalc|http://www.kde.org/applications/Office/keurocalc/]] | A currency converter and calculator | org.kde.keurocalc | Q + [[Kexi|http://www.kde.org/applications/Office/kexi/]] | Database Creator | org.kde.kexi | Q + [[KFax|http://www.kde.org/applications/Graphics/kfax/]] | Fax Viewer | org.kde.kfax | Q + [[KFileReplace|http://www.kde.org/applications/Utilities/kfilereplace/]] | Search & Replace Tool | org.kde.kfilereplace | Q + [[KFind|http://www.kde.org/applications/Utilities/kfind/]] | Find Files/Folders | org.kde.kfind | Q + [[KFloppy|http://www.kde.org/applications/Utilities/kfloppy/]] | Floppy Formatter | org.kde.kfloppy | Q + [[KFourInLine|http://www.kde.org/applications/Games/kfourinline/]] | Four-in-a-row Board Game | org.kde.kfourinline | Q + [[KFTPgrabber|http://www.kde.org/applications/Internet/kftpgrabber/]] | FTP Client | org.kde.kftpgrabber | Q + [[KGeography|http://www.kde.org/applications/Education/kgeography/]] | Geography Trainer | org.kde.kgeography | Q + [[KGet|http://www.kde.org/applications/Internet/kget/]] | Download Manager | org.kde.kget | Q + [[KGoldrunner|http://www.kde.org/applications/Games/kgoldrunner/]] | Hunt Gold, Dodge Enemies and Solve Puzzles | org.kde.kgoldrunner | Q + [[KGpg|http://www.kde.org/applications/Utilities/kgpg/]] | Encryption Tool | org.kde.kgpg | Q + [[KGrab|http://www.kde.org/applications/Graphics/kgrab/]] | Screen Grabbing Program | org.kde.kgrab | Q + [[KGraphViewer|http://www.kde.org/applications/Graphics/kgraphviewer/]] | A Graphviz dot graph viewer for KDE | org.kde.kgraphviewer | Q + [[KHangMan|http://www.kde.org/applications/Education/khangman/]] | Hangman Game | org.kde.khangman | Q + [[KIconEdit|http://www.kde.org/applications/Graphics/kiconedit/]] | Icon Editor | org.kde.kiconedit | Q + [[Kig|http://www.kde.org/applications/Education/kig/]] | Interactive Geometry | org.kde.kig | Q + [[Kigo|http://www.kde.org/applications/Games/kigo/]] | Go Board Game | org.kde.kigo | Q + [[Kile|http://www.kde.org/applications/Office/kile/]] | LaTeX Frontend | org.kde.kile | Q + [[Killbots|http://www.kde.org/applications/Games/killbots/]] | | org.kde.killbots | Q + [[KImageMapEditor|http://www.kde.org/applications/Development/kimagemapeditor/]] | HTML Image Map Editor | org.kde.kimagemapeditor | Q + [[KInfoCenter|http://www.kde.org/applications/System/kinfocenter/]] | Info Center | org.kde.kinfocenter | Q + [[Kiosk Admin Tool|http://www.kde.org/applications/System/kiosk admin tool/]] | Kiosk Framework Administration | org.kde.kiosk admin tool | Q + [[Kiriki|http://www.kde.org/applications/Games/kiriki/]] | Yahtzee-like Dice Game | org.kde.kiriki | Q + [[Kiten|http://www.kde.org/applications/Education/kiten/]] | Japanese Reference/Study Tool | org.kde.kiten | Q + [[Kivio|http://www.kde.org/applications/Office/kivio/]] | Flowchart & Diagram Editing | org.kde.kivio | Q + [[KJots|http://www.kde.org/applications/Utilities/kjots/]] | Note Taker | org.kde.kjots | Q + [[KJumpingCube|http://www.kde.org/applications/Games/kjumpingcube/]] | Territory Capture Game | org.kde.kjumpingcube | Q + [[Kleopatra|http://www.kde.org/applications/Utilities/kleopatra/]] | Certificate Manager and Unified Crypto GUI | org.kde.kleopatra | Q + [[KLettres|http://www.kde.org/applications/Education/klettres/]] | Learn The Alphabet | org.kde.klettres | Q + [[KLines|http://www.kde.org/applications/Games/klines/]] | Tactical Game | org.kde.klines | Q + [[KLinkStatus|http://www.kde.org/applications/Development/klinkstatus/]] | Link Checker | org.kde.klinkstatus | Q + [[KMag|http://www.kde.org/applications/Utilities/kmag/]] | Screen Magnifier | org.kde.kmag | Q + [[KMahjongg|http://www.kde.org/applications/Games/kmahjongg/]] | Mahjongg Solitaire | org.kde.kmahjongg | Q + [[KMail|http://www.kde.org/applications/Internet/kmail/]] | Mail Client | org.kde.kmail | Q + [[KMid|http://www.kde.org/applications/Multimedia/kmid/]] | A KDE4 MIDI/Karaoke Player | org.kde.kmid | Q + [[KMines|http://www.kde.org/applications/Games/kmines/]] | Minesweeper-like Game | org.kde.kmines | Q + [[KMix|http://www.kde.org/applications/Multimedia/kmix/]] | Sound Mixer | org.kde.kmix | Q + [[KMLDonkey|http://www.kde.org/applications/Internet/kmldonkey/]] | MLDonkey Client | org.kde.kmldonkey | Q + [[KMouseTool|http://www.kde.org/applications/Utilities/kmousetool/]] | Automatic Mouse Click | org.kde.kmousetool | Q + [[KMouth|http://www.kde.org/applications/Utilities/kmouth/]] | Speech Synthesizer Frontend | org.kde.kmouth | Q + [[KMPlayer|http://www.kde.org/applications/Multimedia/kmplayer/]] | Media Player | org.kde.kmplayer | Q + [[KmPlot|http://www.kde.org/applications/Education/kmplot/]] | Mathematical Function Plotter | org.kde.kmplot | Q + [[KNemo|http://www.kde.org/applications/Internet/knemo/]] | Network Monitor | org.kde.knemo | Q + [[KNetWalk|http://www.kde.org/applications/Games/knetwalk/]] | Network Construction Game | org.kde.knetwalk | Q + [[KNode|http://www.kde.org/applications/Internet/knode/]] | News Reader | org.kde.knode | Q + [[KNotes|http://www.kde.org/applications/Utilities/knotes/]] | Popup Notes | org.kde.knotes | Q + [[Kolf|http://www.kde.org/applications/Games/kolf/]] | Miniature Golf | org.kde.kolf | Q + [[Kollision|http://www.kde.org/applications/Games/kollision/]] | A simple ball dodging game | org.kde.kollision | Q + [[KolourPaint|http://www.kde.org/applications/Graphics/kolourpaint/]] | Paint Program | org.kde.kolourpaint | Q + [[Kommander|http://www.kde.org/applications/Development/kommander/]] | Dynamic Dialog Editor | org.kde.kommander | Q + [[Kompare|http://www.kde.org/applications/Development/kompare/]] | Diff/Patch Frontend | org.kde.kompare | Q + [[Konqueror|http://www.kde.org/applications/Internet/konqueror/]] | KDE File Manager & Web Browser | org.kde.konqueror | Q + [[Konquest|http://www.kde.org/applications/Games/konquest/]] | Galactic Strategy Game | org.kde.konquest | Q + [[Konsole|http://www.kde.org/applications/System/konsole/]] | Terminal | org.kde.konsole | Q + [[Kontact|http://www.kde.org/applications/Office/kontact/]] | Personal Information Manager | org.kde.kontact | Q + [[Konversation|http://www.kde.org/applications/Internet/konversation/]] | IRC Client | org.kde.konversation | Q + [[Kopete|http://www.kde.org/applications/Internet/kopete/]] | Instant Messenger | org.kde.kopete | Q + [[KOrganizer|http://www.kde.org/applications/Office/korganizer/]] | Personal Organizer | org.kde.korganizer | Q + [[KPager|http://www.kde.org/applications/Utilities/kpager/]] | Desktop Pager | org.kde.kpager | Q + [[KPatience|http://www.kde.org/applications/Games/kpatience/]] | Patience Card Game | org.kde.kpatience | Q + [[KPhotoAlbum|http://www.kde.org/applications/Graphics/kphotoalbum/]] | Photo Album | org.kde.kphotoalbum | Q + [[KPlato|http://www.kde.org/applications/Office/kplato/]] | Project Management | org.kde.kplato | Q + [[KPlayer|http://www.kde.org/applications/Multimedia/kplayer/]] | Media Player | org.kde.kplayer | Q + [[KPovModeler|http://www.kde.org/applications/Graphics/kpovmodeler/]] | Povray Modeler | org.kde.kpovmodeler | Q + [[KPPP|http://www.kde.org/applications/Internet/kppp/]] | Internet Dial-Up Tool | org.kde.kppp | Q + [[KPresenter|http://www.kde.org/applications/Office/kpresenter/]] | Presentation | org.kde.kpresenter | Q + [[KRDC|http://www.kde.org/applications/Internet/krdc/]] | Remote Desktop Client | org.kde.krdc | Q + [[KRecipes|http://www.kde.org/applications/Utilities/krecipes/]] | Cooking Book | org.kde.krecipes | Q + [[KRemoteControl|http://www.kde.org/applications/Utilities/kremotecontrol/]] | Remote Controls | org.kde.kremotecontrol | Q + [[KReversi|http://www.kde.org/applications/Games/kreversi/]] | Reversi Board Game | org.kde.kreversi | Q + [[Krfb|http://www.kde.org/applications/System/krfb/]] | Desktop Sharing | org.kde.krfb | Q + [[Krita|http://www.kde.org/applications/Graphics/krita/]] | Painting and Image Editing | org.kde.krita | Q + [[KRuler|http://www.kde.org/applications/Graphics/kruler/]] | Screen Ruler | org.kde.kruler | Q + [[Krusader|http://www.kde.org/applications/Utilities/krusader/]] | File Manager | org.kde.krusader | Q + [[KSame|http://www.kde.org/applications/Games/ksame/]] | Board Game | org.kde.ksame | Q + [[KsCD|http://www.kde.org/applications/Multimedia/kscd/]] | CD Player | org.kde.kscd | Q + [[KShisen|http://www.kde.org/applications/Games/kshisen/]] | Shisen-Sho Mahjongg-like Tile Game | org.kde.kshisen | Q + [[KSig|http://www.kde.org/applications/Utilities/ksig/]] | Signature Editor | org.kde.ksig | Q + [[KsirK|http://www.kde.org/applications/Games/ksirk/]] | World Domination Strategy Game | org.kde.ksirk | Q + [[KSnapshot|http://www.kde.org/applications/Graphics/ksnapshot/]] | Screen Capture Program | org.kde.ksnapshot | Q + [[KSpaceDuel|http://www.kde.org/applications/Games/kspaceduel/]] | Space Arcade Game | org.kde.kspaceduel | Q + [[KSpread|http://www.kde.org/applications/Office/kspread/]] | Spreadsheet | org.kde.kspread | Q + [[KSquares|http://www.kde.org/applications/Games/ksquares/]] | Connect the dots to create squares | org.kde.ksquares | Q + [[KStars|http://www.kde.org/applications/Education/kstars/]] | Desktop Planetarium | org.kde.kstars | Q + [[KSudoku|http://www.kde.org/applications/Games/ksudoku/]] | Sudoku Game | org.kde.ksudoku | Q + [[KSystemLog|http://www.kde.org/applications/System/ksystemlog/]] | System Log Viewer | org.kde.ksystemlog | Q + [[KTeaTime|http://www.kde.org/applications/Games/kteatime/]] | Tea Cooker | org.kde.kteatime | Q + [[KTimer|http://www.kde.org/applications/Utilities/ktimer/]] | Countdown Launcher | org.kde.ktimer | Q + [[KTimeTracker|http://www.kde.org/applications/Utilities/ktimetracker/]] | Personal Time Tracker | org.kde.ktimetracker | Q + [[KTorrent|http://www.kde.org/applications/Internet/ktorrent/]] | [[BitTorrent|BitTorrent]] Client | org.kde.ktorrent | Q + [[KTouch|http://www.kde.org/applications/Education/ktouch/]] | Touch Typing Tutor | org.kde.ktouch | Q + [[KTron|http://www.kde.org/applications/Games/ktron/]] | Tron-like Game | org.kde.ktron | Q + [[KTuberling|http://www.kde.org/applications/Games/ktuberling/]] | Picture Game for Children | org.kde.ktuberling | Q + [[KTurtle|http://www.kde.org/applications/Education/kturtle/]] | Educational Programming Environment | org.kde.kturtle | Q + [[Kubrick|http://www.kde.org/applications/Games/kubrick/]] | 3-D Game based on Rubik's Cube | org.kde.kubrick | Q + [[KuickShow|http://www.kde.org/applications/Graphics/kuickshow/]] | Image Viewer | org.kde.kuickshow | Q + [[KUIViewer|http://www.kde.org/applications/Development/kuiviewer/]] | Qt Designer UI File Viewer | org.kde.kuiviewer | Q + [[KUser|http://www.kde.org/applications/System/kuser/]] | User Manager | org.kde.kuser | Q + [[KWalletManager|http://www.kde.org/applications/System/kwalletmanager/]] | Wallet Management Tool | org.kde.kwalletmanager | Q + [[Kwlan|http://www.kde.org/applications/Internet/kwlan/]] | Wireless Lan Manager | org.kde.kwlan | Q + [[KWord|http://www.kde.org/applications/Office/kword/]] | Word Processor | org.kde.kword | Q + [[KWordQuiz|http://www.kde.org/applications/Education/kwordquiz/]] | Flash Card Trainer | org.kde.kwordquiz | Q + [[KWrite|http://www.kde.org/applications/Utilities/kwrite/]] | Text Editor | org.kde.kwrite | Q + [[KXSLDbg|http://www.kde.org/applications/Development/kxsldbg/]] | XSLT Debugger | org.kde.kxsldbg | Q + [[Lokalize|http://www.kde.org/applications/Development/lokalize/]] | Computer-Aided Translation System | org.kde.lokalize | Q + [[LsKat|http://www.kde.org/applications/Games/lskat/]] | Card Game | org.kde.lskat | Q + [[Marble|http://www.kde.org/applications/Education/marble/]] | Desktop Globe | org.kde.marble | Q + [[Okteta|http://www.kde.org/applications/Utilities/okteta/]] | Hex Editor | org.kde.okteta | Q + [[Okular|http://www.kde.org/applications/Graphics/okular/]] | Document Viewer | org.kde.okular | Q + [[Palapeli|http://www.kde.org/applications/Games/palapeli/]] | Jigsaw puzzle game | org.kde.palapeli | Q + [[Parley|http://www.kde.org/applications/Education/parley/]] | Vocabulary Trainer | org.kde.parley | Q + [[Printer Applet|http://www.kde.org/applications/System/printer applet/]] | System tray icon for managing print jobs | org.kde.printer applet | Q + [[Rocs|http://www.kde.org/applications/Education/rocs/]] | Rocs Graph Theory | org.kde.rocs | Q + [[RSIBreak|http://www.kde.org/applications/Utilities/rsibreak/]] | Makes sure you rest now and then | org.kde.rsibreak | Q + [[Skanlite|http://www.kde.org/applications/Graphics/skanlite/]] | Image Scanning Application | org.kde.skanlite | Q + [[Skrooge|http://www.kde.org/applications/Office/skrooge/]] | Manage your money | org.kde.skrooge | Q + [[Step|http://www.kde.org/applications/Education/step/]] | Interactive Physical Simulator | org.kde.step | Q + [[SuperKaramba|http://www.kde.org/applications/Utilities/superkaramba/]] | Desktop Widgets | org.kde.superkaramba | Q + [[Sweeper|http://www.kde.org/applications/Utilities/sweeper/]] | System Cleaner | org.kde.sweeper | Q + [[Tellico|http://www.kde.org/applications/Office/tellico/]] | Collection Manager | org.kde.tellico | Q + [[Umbrello|http://www.kde.org/applications/Development/umbrello/]] | UML Modeller | org.kde.umbrello | Q + [[Yakuake|http://www.kde.org/applications/System/yakuake/]] | Drop-down Terminal | org.kde.yakuake | Q + [[Zanshin|http://www.kde.org/applications/Utilities/zanshin/]] | TODO Management Application | org.kde.zanshin | Q +"""]] diff --git a/Software/DbusTools.mdwn b/Software/DbusTools.mdwn new file mode 100644 index 00000000..bcd319f0 --- /dev/null +++ b/Software/DbusTools.mdwn @@ -0,0 +1,30 @@ + +If you find yourself developing or debugging D-Bus services or applications which use them, you might find some of these tools useful. + + +## Command-line + + +### Calling remote APIs + +`dbus-send`, distributed with D-Bus, allows you to invoke methods on services from the command line. `gdbus` and `qdbus`, shipped with GLib and Qt respectively, provide (arguably) nicer command-line syntax and output for essentially the same task. + + +### Monitoring bus traffic + +`dbus-monitor`, distributed with D-Bus, prints out traffic on the bus. You can filter the output by passing [[match rules|http://dbus.freedesktop.org/doc/dbus-specification.html#message-bus-routing-match-rules]] as arguments. + +The `gdbus monitor` subcommand lets you monitor a particular remote object. + + +## Graphical + + +### D-Feet + +Shows the object hierarchy exposed by running services, allowing you to call the methods you see. [[More information.|https://live.gnome.org/DFeet]] + + +### Bustle + +Records D-Bus traffic (like dbus-monitor) and shows it as a sequence diagram, with built-in filtering and statistics. [[More information.|http://www.willthompson.co.uk/bustle/]] diff --git a/Software/DeviceKit.mdwn b/Software/DeviceKit.mdwn new file mode 100644 index 00000000..32241d21 --- /dev/null +++ b/Software/DeviceKit.mdwn @@ -0,0 +1,30 @@ + +[[DeviceKit|DeviceKit]] was the original name of the projects that [[are to replace parts|http://lists.freedesktop.org/archives/hal/2008-May/011560.html]] of the functionality of [[HAL|Software/hal]]: + +* [[UPower|http://upower.freedesktop.org]], a D-Bus service for dealing with power management +* [[udisks|Software/udisks]], a D-Bus interface for dealing with storage devices +* [[media-player-info|Software/media-player-info]], information about portable media players +* [[urfkill|http://freedesktop.org/wiki/Software/urfkill]], a D-Bus service for dealing with [[RFKill|http://www.mjmwired.net/kernel/Documentation/rfkill.txt]] +Other parts of the stack should replace other things that HAL used to provide: + +* Network: + * [[NetworkManager|http://projects.gnome.org/NetworkManager]], [[Wicd|http://wicd.sourceforge.net/]], etc. for network information and control. + * [[NTrack|https://launchpad.net/ntrack]] should be sufficient for most applications' needs. +* Audio: hardware enumeration should generally be done through the same interface that is used to interact with audio devices, whether that is [[PulseAudio|http://freedesktop.org/wiki/PulseAudio]], [[ALSA|http://www.alsa-project.org/]], [[GStreamer|http://www.gstreamer.net/]] or other libraries or platform-specific interfaces. +* Input: use [[XI2|http://www.x.org/wiki/XI2]] (which uses udev itself on Linux). +* Display: use X: [[XRandR|http://www.x.org/wiki/Projects/XRandR]] provides control over LCD backlights, for example. +* Processors: + * Linux: Enumeration via udev. Most of the info HAL provided (and more) is available via [[cpufreq|http://www.kernel.org/pub/linux/utils/kernel/cpufreq/cpufrequtils.html]]. Some information can currently only be obtained from `/proc/cpuinfo`, such as the processor model name. + * FreeBSD: Use sysctl directly. +* Other: + * On Linux, other hardware enumeration should be done directly through [[udev|http://www.kernel.org/pub/linux/utils/kernel/hotplug/udev.html]], generally via [[libudev|http://www.kernel.org/pub/linux/utils/kernel/hotplug/libudev/]]. Work is under way to provide most of the "extra" information that HAL provided _(except quirks?)_ via udev rules; [[media-player-info|Software/media-player-info]] does this, and [[UPower|http://upower.freedesktop.org]] provides battery recall information via udev, for example. + * On other platforms, native hardware enumeration systems should be used. +* Qt/KDE applications can make use of the [[Solid|http://solid.kde.org/]] library, which aims to provide a unified API for hardware enumeration across platforms and backends (Solid is Qt-only, but is distributed as part of kdelibs). + +## Mailing List + +Announcements and discussion happen on the [[DevKit-devel mailing list|http://lists.freedesktop.org/mailman/listinfo/devkit-devel]]. + +--- + + [[CategoryHalReplacement|CategoryHalReplacement]] diff --git a/Software/Elektra.mdwn b/Software/Elektra.mdwn new file mode 100644 index 00000000..d57ac275 --- /dev/null +++ b/Software/Elektra.mdwn @@ -0,0 +1,67 @@ + + +# About + +Elektra provides a universal and secure framework to store configuration parameters in a global, hierarchical key database. The core is a small library implemented in C. The plugin-based framework fulfills many configuration-related tasks to avoid any unnecessary code duplication across applications while it still allows the core to stay without any external dependency. Elektra abstracts from cross-platform-related issues with an consistent API, and allows applications to be aware of other applications' configurations, leveraging easy application integration. + + +## Facts and Features + +* Elektra implements an API to fully access a global key database. +* Elektra supports mounting of existing configuration files into the global key database. +* Elektra is multi-process safe and can be used in multi-threaded programs. +* Elektra (except for some plugins) is portable and completely written in Ansi-C99. +* Elektra (except for some plugins) has no external dependency. +* Elektra uses the BSD licence. +* Elektra is suitable for embedded systems and early boot stage programs. +* Elektra supports comments and other non-configuration information by meta data. +* Elektra can import, export and convert supported configuration files. +* Elektra is able to log and notify other software on any configuration changes using [[dbus|Software/dbus]]. +* Elektra is able to avoid the problem that any invalid configuration is written into the permanent storage. +* Elektra is able to provide different mechanisms to locate configuration files. +* Elektra supports different ways to escape and encode content of configuration files. +* Standard key/value pair hierarchy and semantics are defined within freedesktop.org. + +## Further Information + +To get an introduction, it is best to take a look at the [[presentation|http://www.libelektra.org/ftp/elektra/presentations/2012/lgm.odp]], see the [[poster|http://www.libelektra.org/ftp/elektra/poster.pdf]] and read the [[abridgment|http://www.libelektra.org/ftp/elektra/abridgement.pdf]]. + +The currently best information about Elektra is [[this paper|http://www.libelektra.org/ftp/elektra/thesis.pdf]]. + +The API documentation can be found [[here|http://doc.libelektra.org/api/current/html]]. + + +## Contact + +Do not hesitate to ask any question on + +* [[https://lists.sourceforge.net/lists/listinfo/registry-list|https://lists.sourceforge.net/lists/listinfo/registry-list]] +or one of the [[AUTHORS|https://gitorious.org/elektra-initiative/libelektra/blobs/master/doc/AUTHORS]]. + + +# Get Started + + +## Download + +Elektra's uses a [[git repository at gitorious|http://gitorious.org/elektra-initiative/libelektra]]. + +The latest source code can be checked out with: + +* git-clone git://gitorious.org/elektra-initiative/libelektra.git +Releases can be downloaded from [[ftp|ftp://ftp.libelektra.org/elektra/releases/]] and [[http|http://www.libelektra.org/ftp/elektra/releases/]] + +Which are also [[mirrored at|http://gitorious.org/elektra-initiative/ftp]]: + +* git-clone git://gitorious.org/elektra-initiative/ftp.git + +## Compile + +See the [[COMPILE|https://gitorious.org/elektra-initiative/libelektra/blobs/master/doc/COMPILE]] document in the repository for informations how to compile the software. + + +## Install + +The preferred way to install Elektra is by using packages provided for your distribution. + +If there are no packages available, see the [[INSTALL|https://gitorious.org/elektra-initiative/libelektra/blobs/master/doc/INSTALL]] document. diff --git a/Software/Eventuality/FAQ.txt.mdwn b/Software/Eventuality/FAQ.txt.mdwn new file mode 100644 index 00000000..316d525a --- /dev/null +++ b/Software/Eventuality/FAQ.txt.mdwn @@ -0,0 +1,46 @@ + + +## FAQ + +1) What is Eventuality? + + * Eventuality is general framework, designed to replace and supersede traditional crond-like type apps for running pre-scheduled jobs. It is however much more flexible and powerful, and can achieve whole sort of things that were hard or impossible to do with cron, as well as things that simply never were meant to be done with cron. It is a bit of desktop- and system-wide scripting framework, that allows defining arbitrary actions and activating them on various conditions, as well as flexible control of actual execution. There are many possibilities just waiting to be explored. NOTE: There seems to be slightly similar thing in prerelease of MacOS X 10.4 "Tiger", called Automator. Eventuality however isn't in any way inspired, nor modelled after Automator, in fact it was first proposed and thought out before anyone has heard about Tiger. +2) How does Eventuality achieve all these cool things? + + * Eventuality is designed to fully leverage on latest-and-greatest technologies in F/LOSS world, particularly D-BUS, Evolution Data Server, and GNotify. We hope to be able to shift as much hard work as possible on others ;), thus avoiding reinventing the wheel and running into risk of creating yet-another-incompatible-framework. We want to do what wasn't done before, and once again show that F/LOSS world is truly innovative. +3) Is Eventuality GNOME-specific? Desktop-specific? Linux-specific? + + * No. The only hard dependency of Eventuality is D-BUS. Any other dependency is specific to given implementation, be it GNOME, KDE or console-based one for sysadmin's pleasure. Eventuality is framework, and defines mostly set of conventions, much less the actual implementation + +#### Architecture Overview + +0) D-BUS + + * All communication inside framework is done exclusively using D-BUS. It is primary way of all IPC, as well as mechanism that provides much of actual capabilities. Whenever there is appropriate D-BUS feature that can be exploited to achieve some goal, it will be preferred over any ad-hoc, proprietary way. Conceptually, D-BUS (usually in its bus mode of operation) sits in the center of star-shaped structure, and all of following items connect to it. +1) Registry + + * Registry is kind of DB-like storage, that stores all registered actions and provides access to them. It's possible to ask registry to store an action instance, and to activate it, given ID obtained on registration +2) Triggers + + * Triggers are what actually cause events to happen. One possible trigger is time-driven scheduler, like original crond, or E-D-S in current GNOME. Another one is panel, which can embed number of action buttons causing some of predefined actions to happen. This way you can have button that fires up RB with given song and volume, as well as you can do that from Evo alert, all using the same code. Note however, that contrary to initial design, and to what could be expected from crond replacement, scheduler (ie. time-driven trigger) is NOT part of framework, just a "well known" instance of trigger, and as such you cannot rely on it being available in all installations. Similarly, protocol defined for communication with such scheduler is fully up to it to define, and is of no interest whatsoever to framework itself. That said, you can of course expect it to be present on most systems, and require any particular trigger for proper operation, it's a dependency as any other that needs to be fulfilled. Triggers don't actually do much wrt to activation of actions, just ask registry to do it and pass it ID registered before. This is similar to calling g_signal_emit(registry, ID). Much more interesting in any given trigger is logic that decides when to trigger. Note: triggering may be actually implemented using D-BUS signals, depending on their exact capabilities. To be investigated +3) Event handlers + + * Or synonymously dispatchers, are analogous to GLib signal handlers (callbacks). Mechanism of dispatching is also similar, although not completely identical, due to slightly different nature of events and handlers registration. Basic idea is that handlers are called sequentially, from most specific ones to most generic ones, similarly to how exceptions are propagated in programming languages. Just as in GLib, event emission stops when one of handlers claims it's fully handled. One possible addition may be priority level, for example for logging facilities that want to be run for every event (and thus are very general), yet they need to make sure no other handler stops emission before they get to see it. Most of system flexibilty is achieved through use of different handlers, that can be plugged dynamically (so that for example, when watching fullscreen movie, all notifications are intercepted and held back until user is available, or depending on whether user is considered AFK (there is screensaver running) notification is either displayed onscreen or sent through SMS) +4) Actions + + * Actions are (like classes) general types of things that can be launched which are then turned into specific instances upon registration. Example action may be "Action.Totem.[[PlayMovie|PlayMovie]]", which has attributes such as "Movie name" (URI), "Volume" (Int<1,100>), "Fullscren" (Boolean). See UI discussion below. Also, if D-BUS services turn out to be suitable to do this, all actions may be actually purely D-BUS services, just gathered under common "Action" namespace. This would have advantage of using existing .service files mechanism for registration of available actions. + +#### Details + +1) UI + + * One particularly tricky area is UI for definig new actions. As we want to be independent from any particular GUI toolkit, or even GUI altogether, it's important to provide way to specify needed parameters in UI-agnostic way. This is valuable for example for sysadmins, who may want to schedule actions using console-only environment, or even through headless setup, like may be the case when initiating action based on received email. Past experiences show however, that it is very hard to achieve while not using least-common-denominator approach and providing decent UI in each case. In particular, while autogenerating layout based on set of values to obtain is relatively straightforward task, it is much harder to ensure that proper constraints are executed and data integrity is preserved (for example, percentage obviously cannot be more than 100, and it doesn't make much sense to ask if playlist should be shuffled on play, if only there's single file selected). For that, one possible solution is that each action, in addition to simple listing of needed values, also has associated code snippet in chosen language (like, say, Python), that is consulted on given input. This is however more advanced question, and won't be initially considered, for the time being, hard-coded, "client side" UI is good enough. +2) OAF + + * In order to be able to perform robust service activation and matching, we need framework similar to OAF (later known as Bonobo-Activation) sported by Bonobo component framework for GNOME. Although Bonobo in general didn't meet its goals, and was rather complex and poorly documented, OAF was one cool part of it (second one was monikers, unfortunately they never caught up enough to actually matter), providing very powerful query capabilities to service activation. OAF lets you do SQL-like queries, so you can for example ask for things like: + * "(repo_ids.has_all (['IDL:Bonobo/Control:1.0', + * 'IDL:Nautilus/ContentView:1.0']) OR + * repo_ids.has_one (['IDL:Bonobo/Control:1.0', + * 'IDL:Bonobo/Embeddable:1.0'])) AND +repo_ids.has('IDL:Bonobo/PersistFile:1.0') AND foo:bar.defined()" +This is extremely important for Eventuality, as main part of its working is matching and glueing various events together into working structure. Not to mention that query capabilities are useful to D-BUS in general.
\ No newline at end of file diff --git a/Software/Farstream.mdwn b/Software/Farstream.mdwn new file mode 100644 index 00000000..753550f4 --- /dev/null +++ b/Software/Farstream.mdwn @@ -0,0 +1,95 @@ + + +# Farstream - Audio/Video Communications Framework + +The Farstream (formerly Farsight) project is an effort to create a framework to deal with all known audio/video conferencing protocols. On one side it offers a generic API that makes it possible to write plugins for different streaming protocols, on the other side it offers an API for clients to use those plugins. + +The main target clients for Farstream are Instant Messaging applications. These applications should be able to use Farstream for all their Audio/Video conferencing needs without having to worry about any of the lower level streaming and NAT traversal issues. + +Farstream forms an integral part of the [[Telepathy|http://telepathy.freedesktop.org/]] framework. It is used by [[Empathy|http://live.gnome.org/Empathy]] through the Telepathy-Farstream library. The Telepathy-Farstream library binds it to the Connection Managers via [[D-Bus|http://dbus.freedesktop.org]] and the [[Telepathy Media Stream Spec|http://telepathy.freedesktop.org/spec.html]] and is used for all their streaming requirements. + +Telepathy and Farstream constitute the first implementation of the [[Jingle XMPP|http://www.xmpp.org/extensions/xep-0166.html]] protocol. + +Farstream deals with all the streaming specific parts of the protocol and leaves the signaling to the clients. The Farstream plugin API is heavily influenced by the ICE (Interactive Connectivity Establishment) RFC draft. This API allows for an easy interaction between the signaling and streaming parts of the sessions. + +Farstream uses [[GStreamer|http://gstreamer.freedesktop.org]] for all it's media streaming needs. A large part of the project is to provide the required elements and improvements to GStreamer in order to deal with streaming protocols such as RTP. + +Farstream will also be using the [[GstFilters|Software/GstFilters]] library to make it easier to build the GStreamer filter-like pipelines. + +Farstream is written in C using GLib and uses GObjects extensively. Versions before 0.2 provide python bindings, version 0.2 and later uses [[GObject Introspection|https://live.gnome.org/GObjectIntrospection]] to provides bindings, it is known to work with Python, but other GObject Introspection based bindings should also work. + +This project is sponsored by [[[[!img http://www.collabora.com/]|http://www.collabora.com/]] + + +## License + +Farstream is licensed under the [[GNU Lesser General Public License, version 2.1|http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html]] or later. + + +## Documentation + +The core API documentation is available for [[Farstream|http://www.freedesktop.org/software/farstream/apidoc/farstream/]] and its [[plugins|http://www.freedesktop.org/software/farstream/apidoc/farstream-plugins/]]. + +There is a [[Software/Farstream/FAQ|Software/Farstream/FAQ]] and some videos/slides from [[Software/Farstream/Talks|Software/Farstream/Talks]] about Farstream. + +The H263/H263+/H263++ RTP fiasco is explained in [[Software/Farstream/H263Jungle|Software/Farstream/H263Jungle]]. + +A almost up to date page documenting the RTP design for GStreamer : [[Software/Farstream/GstRtpDesign|Software/Farstream/GstRtpDesign]]. The Farstream API is being discussed [[Software/Farstream/Design|Software/Farstream/Design]] and the list of left todo [[Software/Farstream/Todo|Software/Farstream/Todo]] + +The old core API documentation is available for [[Farsight2|http://www.freedesktop.org/software/farstream/apidoc/farsight2/]] and its [[plugins|http://www.freedesktop.org/software/farstream/apidoc/farsight2-plugins/]]. + + +## Available Plugins + +* rtp : RTP +* msn webcam : MSN Webcam +* raw plugin: For protocols where the media processing is done in the application. Allows using Farstream solely for the networking part. + +## Available Transmitters + +Transmitters are plugins that are used by Farstream plugins in order to implement lower level connectivity establishment methods such as ICE or GTalk-P2P. + +* raw udp : This is a raw udp transmitter with external IP detection using STUN, and can also open up ports with UPnP +* multicast : Multicast UDP +* nice ([[libnice|http://nice.freedesktop.org/]]) : This is a transmitter that uses libnice to do ICE (as defined in the [[RFC 5245|http://tools.ietf.org/html/rfc5245]]), as well as Google Talk and MSN compatible ICE-like protocols +* shm: Shared memory plugin for IPC between processes using shmsrc/shmsink from GStreamer. + + +--- + + +## Git repositories + +[[Browse|http://cgit.collabora.com/git/farstream.git/]] the Farstream development tree. + Fetch it using: git clone git://git.collabora.co.uk/git/farstream.git + +--- + + +## Releases + +[[http://freedesktop.org/software/farstream/releases|http://freedesktop.org/software/farstream/releases]] + + + +--- + + +## Mailing list and IRC + +You can reach the developers and other users of Farstream at our [[mailing list|http://lists.freedesktop.org/mailman/listinfo/farstream-devel]] or in the #farstream channel on [[freenode|http://freenode.net/]]. + + + +--- + + +## Misc Pages and Links + +Please report bugs in the [[freedesktop.org bugzilla|https://bugs.freedesktop.org/enter_bug.cgi?product=Farstream]]. + + + +--- + + diff --git a/Software/Farstream/CodingStyle.mdwn b/Software/Farstream/CodingStyle.mdwn new file mode 100644 index 00000000..e8fad2c9 --- /dev/null +++ b/Software/Farstream/CodingStyle.mdwn @@ -0,0 +1,160 @@ + +This page describes the Farstream coding style. + +Loosely based on GNU style C. + +Max line width 80. + +All long lines wrapped with 4 space indentation. + +Spaces after all procedural calls (includes macros). + +Function names and variables names use underscore word separators. All GObject methods are prefixed with the appropriate prefix for the object. + +Typenames are in camelcase. + +Functions that must be called with a lock held end with _locked, those that will be called with the lock but will return without end with _unlock, the doc will specify which lock + +NO TABS! + +Base indent unit is 2 spaces. + + +#### Function prototypes + +The first parameter is on the same line as the function only if the function is a method. + + +[[!format txt """ +static void fs_rtp_stream_get_property (GObject *object, + guint prop_id, + GValue *value, + GParamSpec *pspec); +"""]] + +#### Function declarations + +The first parameter is on the same line as the function only if the function is a method. + + +[[!format txt """ +static void +fs_rtp_stream_get_property (GObject * object, + guint prop_id, + GValue * value, + GParamSpec * pspec) +{ +} +"""]] + +#### If/else/while/for/do/struct/switch/etc + + +[[!format txt """ +if (condition) +{ + die (); +} +else +{ + die (); +} +"""]] +For blocks that only contain one statement, the opening/closing brackets can be omitted. But this can only be done if all the blocks in a statement contain only one statement. This is an ILLEGAL example : +[[!format txt """ +if (condition) + die (); +else +{ + die (); + die_again (); +} +"""]] +In C, 0 is false, non-zero is true. No need to say it. + +BAD: +[[!format txt """ +if (aa == FALSE) {} +if (aa == TRUE) {} +if (aa == NULL) {} +if (aa != NULL) {} +"""]] +GOOD: +[[!format txt """ +if (aa) {} +if (!aa) {} +"""]] + +#### Breaks and boolean operators + + +[[!format txt """ +if (self->priv->main_pipeline && src_in_pipeline + || !self->priv->your_mama) +{ +} +"""]] + +#### Pointer declarations + + +[[!format txt """ +Type *var; +"""]] + +#### Switch + + +[[!format txt """ +switch (var) +{ + case 4: + die (); + break; + case 5: + die (); +} +"""]] + +#### Casting + + +[[!format txt """ +FsRtpStream *self = FS_RTP_STREAM (stream); +"""]] + +#### #includes + +If you're going to #include "config.h", do that first, in case it defines things like "inline". + +Next, #include the header in which this .c file's API is declared. This guarantees that all public headers are self-contained. + +Next, #define any libc feature-test macros you need (_GNU_SOURCE etc.) and #include any C/POSIX standard library headers you need, in alphabetical order. + +Next, #include any headers you need from non-standard libraries (GLib, Gtk, GStreamer, ...) in alphabetical order. + +Finally, #include any private (non-installed) headers from the library or program you're writing. + + +#### Emacs mode + + +[[!format txt """ +(defun farstream-c-mode () + "C mode with Farstream style" + (interactive) + (c-mode) + (c-set-style "GNU") + (setq tab-width 8) + (setq indent-tabs-mode nil) + (setq c-basic-offset 2) + (setq c-tab-always-indent nil) + (setq show-trailing-whitespace 't) + (c-set-offset 'case-label 2) + (c-set-offset 'arglist-intro 4) + (c-set-offset 'statement-cont 4) + (c-set-offset 'substatement-open 0) + (c-set-offset 'arglist-cont-nonempty 4) + (setq c-cleanup-list (quote (brace-else-brace brace-elseif-brace space-before-funcall))) +) +"""]]
\ No newline at end of file diff --git a/Software/Farstream/ComfortNoise.mdwn b/Software/Farstream/ComfortNoise.mdwn new file mode 100644 index 00000000..93f30fc8 --- /dev/null +++ b/Software/Farstream/ComfortNoise.mdwn @@ -0,0 +1,15 @@ + + +## Comfort Noise for codecs that don't have it in Farstream + +Regular encoding pipeline: + +[[!img original-diagram.png] + +Encoding pipeline with CN: + +[[!img separated.png] + +In the second case, we have a VAD element that generates CN. If there is voice, nothing is sent out on the CN src pad and the data goes on the regular src pad. If it detects silence, it stops sending data on the regular src pad and instead generates CN buffers onto the CN source pad. + +On the Farsight 2 side of things, that means having profiles for encoding/decoding pipelines that will supplement the autodetection so we can support more complex cases like this one. For the reception, we will have a CN depayloader/decoder combo that would generate events and then these would tell the mixer/sink/etc to generate CN until some other audio arrives. diff --git a/Software/Farstream/ComfortNoise/original-diagram.png b/Software/Farstream/ComfortNoise/original-diagram.png Binary files differnew file mode 100644 index 00000000..f4b66df5 --- /dev/null +++ b/Software/Farstream/ComfortNoise/original-diagram.png diff --git a/Software/Farstream/ComfortNoise/separated.png b/Software/Farstream/ComfortNoise/separated.png Binary files differnew file mode 100644 index 00000000..8d0f55c4 --- /dev/null +++ b/Software/Farstream/ComfortNoise/separated.png diff --git a/Software/Farstream/Design.mdwn b/Software/Farstream/Design.mdwn new file mode 100644 index 00000000..df980f36 --- /dev/null +++ b/Software/Farstream/Design.mdwn @@ -0,0 +1,135 @@ + + +## Goals + +The goals of Farstream (Farsight2) is to do everything that the current Farsight does and: + +* support multi-party conferences in all of the possible different modes supported by RTP +* support SRTP and other similar security mechanisms +* support the latest drafts of ICE as well as the older ones used by Google Talk and MSN +* support full lip-sync between different streams (rtp sessions) in the same conference +* make the api for audio and video sources identical as much as possible + +## Core design ideas + +The cores design ideas of Farstream are the following: + +* it will be a GLib/GStreamer base class [[FsConference|FsConference]]. The different protocols derive from this base to create protocol specific gstreamer elements (like an RTP element or an MSN webcam element) +* The RTP GStreamer element will be on the GStreamer rtpmanager element (currently in gst-plugins-bad and described by [[Software/Farstream/GstRtpDesign|Software/Farstream/GstRtpDesign]]) +There will be four core concepts: + + +#### Farstream Conference + +A conference represents one high-level conference which may include multiple synchronized audio/video/text RTP sessions. + +* It was a Session in Farsight 1. + +#### Farstream Session + +A Farstream session corresponds to one RTP session (and in Farsight 1 was a stream). It is defined by having one media ty pe and and one "sink pad" (one local microphone or camera for example). We can receive data from multiple sources (one p er participant). + + +#### Farstream Participant + +A Farstream participant represents one physical person (or something similar like a bot). + + +#### Farstream Stream + +This is the link between a session and a participant. It is linked to candidates and hold SRTP information and state. + + +## API + +The API documentation can be found at [[http://www.freedesktop.org/software/farstream/apidoc/farsight2/|http://www.freedesktop.org/software/farstream/apidoc/farsight2/]] + +The following graph shows are the different objects are to be linked together: + +[[!img farsight2-references.png] + + +### Transmitters + +In the previous diagram, we can see transmitter, they abstract the network layer. Different transmitter could be multicast UDP, unicast UDP, ICE UDP, HTTP tunnelling, etc. The transmitter is selected by the client when it creates the Stream (so different stream could use different transmitters). + +Transmitters implement two objects, the [[FsTransmitter|FsTransmitter]], which has one instance per [[FsSession|FsSession]] (there could be multiple [[FsTransmitter|FsTransmitter]] objects for a single [[FsSession|FsSession]], one per type). This object provides a GStreamer source and sink. From this object, the [[FsSession|FsSession]] function that creates the Stream will make a [[FsStreamTransmitter|FsStreamTransmitter]] object, this one is used by the Stream to communicate various per-stream data with the transmitter (mostly candidates). + + +### RTP Implementation + +The first implementation will be for RTP, as it is the most commonly used protocol and streaming. We will implement a FsRTPConference that is derived from [[FsConference|FsConference]] that is derived from [[GstBin|GstBin]]. + +Transmitters are really RTP specific, they will be implemented as RTP elements, probably implementing another GInterface which should probably resemble the current one, but will also need to be able to understand the concept of multiple participants (since one ICE transmitter may have to actually contain multiple sub-transmitters to initiate ICE sessions with each one). + +To do a mixer, you just have to add one adder to all sink ports of the same type, then a tee to that. On the tee, one branch goes to the audio sink and the other is added to the local input... which is sent back into the sink. + +The following drawing shows the proposed design for [[FsRtpConference|FsRtpConference]], This drawing shows only 2 [[FsSession|FsSession]] with 2 SSRCs, more can be added. All pads on the [[FsConference|FsConference]] element are sometimes pads that are created when either data arrives for sources or when they are requested through the Interface for sink pads. + +[[!img farsight2rtp.png] + + +## Different types of conferences + +There are many different types of conferences that we hope Farstream to support: + + +### Distributed media (unicast), focused signalling + +[[!img http://www.freedesktop.org/software/farstream/rtpdesign/conf-type-1.png] + +* n-1 duplex media streams per participant +* 1 duplex signalling stream per participant +* n duplex signalling streams at focus, n-1 if focus is a participant +* + Easy to implement +* - High bandwidth/CPU required at each participant for large conferences +* - Scalability limited by participant with lowest capacity + +### Distributed media (multicast), focused signalling + +[[!img http://www.freedesktop.org/software/farstream/rtpdesign/conf-type-3.png] + +* 1 duplex media stream per participant +* 1 duplex signalling stream per participant +* n duplex signalling streams at focus, n-1 if focus is a participant +* + Easy to implement +* + Minimal bandwith/CPU usage at each participant +* + Scalability limited by multicast network capacity +* - Multicast doesn't really work over the net, this would be suitable for local networks though + +### Centralized media (unicast), focused signalling + +[[!img http://www.freedesktop.org/software/farstream/rtpdesign/conf-type-2.png] + +* 1 duplex media stream per participant +* 1 duplex signalling stream per participant +* n duplex signalling streams at focus, n-1 if focus is a participant +* n duplex signalling streams at mixer, n-1 if mixer is a participant +* - Must implement mixer +* + Minimal bandwidth/CPU usage at each participant +* - High bandwidth/CPU usage at mixer +* - Scalability limited by capacity of mixer + +### Distributed media (unicast), distributed signalling + +[[!img http://www.freedesktop.org/software/farstream/rtpdesign/conf-type-4.png] + +* n-1 duplex media streams per participant +* n-1 duplex signalling streams per participant +* - Distributed signalling difficult to implement (each participant needs to keep a state of the conference) +* - High bandwidth/CPU usage at each participant +* - Scalability limited by participant with lowest capacity + +### Distributed-centralized media (unicast), distributed-focused signalling + +[[!img http://www.freedesktop.org/software/farstream/rtpdesign/conf-type-5.png] + +Multiple mixers and signalling focuses distributed along network. Basically mixers and focuses are supernodes in the network. + +* - Very difficult to implement on both media and signalling sides + * - Must absolutely avoid loops + * - How to deal with supernodes leaving the conferences +* - Potentially high media latency at participants +* + Scalability nearly unlimited if supernodes are well distributed +* + Low bandwidth/CPU required at leaves +* - High bandwidth/CPU required at supernodes
\ No newline at end of file diff --git a/Software/Farstream/Design/farsight2-references.png b/Software/Farstream/Design/farsight2-references.png Binary files differnew file mode 100644 index 00000000..8672a6d8 --- /dev/null +++ b/Software/Farstream/Design/farsight2-references.png diff --git a/Software/Farstream/Design/farsight2rtp.png b/Software/Farstream/Design/farsight2rtp.png Binary files differnew file mode 100644 index 00000000..df583f96 --- /dev/null +++ b/Software/Farstream/Design/farsight2rtp.png diff --git a/Software/Farstream/FAQ.mdwn b/Software/Farstream/FAQ.mdwn new file mode 100644 index 00000000..f01b7cb1 --- /dev/null +++ b/Software/Farstream/FAQ.mdwn @@ -0,0 +1,16 @@ + +**Will Farsight2 work with older versions of GStreamer than the ones mentionned in the README?** + +No, it won't. + +**When I run tests/gui/fs2-gui.py, I have a deadlock.** + +This is a known bug in pygobject, details are in [[gnome bug #530935|http://bugzilla.gnome.org/show_bug.cgi?id=530935]] which has a [[patch|http://bugzilla.gnome.org/attachment.cgi?id=110244]]. + +**I run Debian and when I try to start a video session, the "codecs-ready" property never turns to TRUE?** + +Debian maintainers think they're smarter then the upstream maintainers and use their own copy of ffmpeg instead of the one provided by gst-ffmpeg. They forgot to disable ffenc_libtheora (which is broken). They know about this problem, but have yet to fix it. Solution: use a better distribution or remove the gstreamer0.10-ffmpeg package. + +**I run Gentoo and my application crashes when I enable video?** + +Avoid gst-plugins-farsight 0.10.5, use 0.10.4 or 0.10.6 diff --git a/Software/Farstream/GstRtpDesign.mdwn b/Software/Farstream/GstRtpDesign.mdwn new file mode 100644 index 00000000..e1e04e55 --- /dev/null +++ b/Software/Farstream/GstRtpDesign.mdwn @@ -0,0 +1,50 @@ + +The goal of this page is to document the design of RTP in GStreamer as of our meeting at Fluendo on 30th March. + +The goal of the design was to allow us to cover the wide range of RTP usage, this includes : + +* Basic RTP receiving/sending +* RTSP support +* RTCP support +* Multi-user RTP sessions (This means talking to more than one participant in a conference) +* Multi-session RTP conferences (This means receiving A/V from one or more participants in a conference) +* A/V Lipsync +* Jitterbuffer +* Multicast RTP +Implementation can be found on : [[http://cgit.freedesktop.org/gstreamer/gst-plugins-good/tree/gst/rtpmanager|http://cgit.freedesktop.org/gstreamer/gst-plugins-good/tree/gst/rtpmanager]] + + +# rtpbin + +The idea is to have an element (rtpbin) that ensures all of the above features while offering a simple and flexible inte rface to the user. rtpbin is a dynamic element that is used for all RTP sessions. For each RTP session, the user needs t o connect to the following request pads : + +* recv_rtp_sink_%d : Incoming RTP stream +* recv_rtcp_sink_%d : Incoming RTCP stream (if available) +* send_rtp_sink_%d : Outgoing RTP stream (if transmitting an RTP stream) +rtpbin will ensure that all received streams from the different RTP sessions are synced (i.e. Audio/Video). It will also generate RTCP packets for each RTP Session if you link up to the send_rtcp_src_%d request pad. rtpbin will also eliminate network jitter using internal rtpjitterbuffer elements. The rtpbin element will create dynamic pads, one for each payload type from each participant. These pads are called recv_rtp_src_m_n_PT with : + +* m : The RTP session identifier +* n : The participant identifier +* PT : The payload type number +The user needs to provide the dynamic payload type information as a [[GstCaps|GstCaps]] when rtpbin requests it via the request_pt_caps() signal. rtpbin has a latency property that is used to set the latency on the jitterbuffer. + +Here is a [[diagram|http://www.freedesktop.org/software/farstream/rtpdesign/rtpbin.png]] showing the internals of rtpbin. This example has 2 RTP Sessions (A/V) and 2 sources (a 3 way A/V conference). + + +## rtpsession + +This is the rtp session manager element. We have 1 of these elements per RTP session. Inside this element resides the RTP session manager library that does all the RTP session management, such as RTCP packet generation, collision detection, etc. Considering that all RTP sources from a same session send to the same RTP/RTCP port, we only need 1 sink pad for RTP and 1 sink pad for RTCP. The third pad (send_rtp_sink) is a request pad used for outgoing streams (if we are transmitting). + +Here is a [[diagram|http://www.freedesktop.org/software/farstream/rtpdesign/rtpsession.png]] showing the internals of rtpsession. + + +## rtpssrcdemuxer + +This element is in charge of demuxing the RTP stream based on SSRC information. It does so for both RTP and RTCP separately. We have 1 rtpssrcdemuxer for each RTP session. The rtpbin is in charge of figuring out what different SSRCs (from different RTP session) are from the same physical host using the CNAME information in the RTCP packets. It can therefore connect the appropriate rtpssrcdemuxer src pads to the rtpsource elements. + + +## rtpsource + +This is just a logical grouping that represents a physical source host. We need one of these groupings each physical host participating in the RTP conference. It is used to synchronize the different incoming streams from the same host but from different RTP sessions. The common use-case is to synchronize the Audio and Video streams coming from the same source. This grouping also has a jitterbuffer and a ptdemuxer for each stream. The jitterbuffer reduces network jitter, reorders packets and drops old and duplicate packets. The ptdemuxer demuxes the streams into the multiple payload types (codecs) they can be transmitting. + +Here is a [[diagram|http://www.freedesktop.org/software/farstream/rtpdesign/rtpsource.png]] showing the internals of rtpsource. diff --git a/Software/Farstream/H263Jungle.mdwn b/Software/Farstream/H263Jungle.mdwn new file mode 100644 index 00000000..2919d8be --- /dev/null +++ b/Software/Farstream/H263Jungle.mdwn @@ -0,0 +1,30 @@ + +This page describes the RFC mess with H263/+/++ RTP payloading and how Farsight deals with it. + +We have 4 relevant RFCs :T + +- 2190 - a "historic" RFC for payloading H263 + +- 2429 - an obsolete one for payloading H263+ specifically + +- 4629 - a new one that obsoletes 2429. Used for payloading H263/+/++ (nearly identical to 2429) + +- 4628 - makes 2190 historic + +RFC2429 and RFC4629 are nearly identical. The difference is that RFC4629 says that plain H263 (1996) SHALL use it for payloading. It also defines some new SDP registrations for H263-1998 and H263-2000. + +This means that all new implementations of plain H263 must use RFC4629 for payloading. It also says that when using RFC4629 for plain H263, we have to use H263-1998 without any optional annexes defined. If doing H263+, we have to use H263-1998 as encoding name and add the optional annexes we support. If we are using H263 payloaded with RFC2190, we have to use H263 as the encoding name. + +The main problem with this is that UAs who don't understand RFC4629 will think that H263-1998 without annexes is actually H263+ as defined in RFC2429, but based on RFC4629 it is H263. So this means that UAs that implement RFC4629 could be incompatible with UAs that don't. + +So we have the following encoding names : + +H263 -> H263 with RFC2190 + +H263-1998 -> H263 with RFC4629 or H263+ with RFC2429 + +H263-1998 with annexes -> H263+ with RFC4629 + +H263-2000 -> H263++ with RFC2429 payloading or H263++ with RFC4629 + +Farsight deals with this by support RFC2190 for old implementations, and RFC4629. It will prioritize H263 over H263-1998 in order to maximize backwards compatibility with UAs that don't do RFC4629. diff --git a/Software/Farstream/LTE_Requirements.mdwn b/Software/Farstream/LTE_Requirements.mdwn new file mode 100644 index 00000000..7077496c --- /dev/null +++ b/Software/Farstream/LTE_Requirements.mdwn @@ -0,0 +1,37 @@ + +Here is a list of things that are missing in Farstream and required by LTE. As specified in TS 26.114 version 9.3.0 + +* Support for the text in RTP as per ITU T.140 + * Must support backspace + * Must support rate limiting (30 cps for LTE) +* Audio: + * ECN may be used for speech adaptation (optional) according to ecn-capable-rtp SDP attribute + * Full support for AMR-NB/WB negotiation +* Video + * AVPF nack + * TMMBR/TMMBN +* Dynamic jitterbuffer +Call interface requirement: + +* Synchronization of streams is optional and specified over SDP with 3gpp_sync_info including grouping (using group: LS) +* Streams need to have groupable sync (possibly modifiable with a renegotiation) using group: LS +* Support for b=RS/RR +GStreamer requirement: + +* Implement Codec Mode Request (CMR) handling in pay/depay (and also in Farsight2 or something) +* Reduced size RTCP with rtcp-rsize (RFC 5506) +Requirement for Telepathy Sofia-SIP: + +* SDPCapNeg +* AVPF only with SDPCapNeg +Codecs: + +* Must + * H.263 Profile 0 with Level 45, QCIF and sQCIF up to 128kbits/s and up to 15fps + * AMR-NB: redundancy, etc should be handled by the codec + * Should have packet loss concealement +* Should + * H.263 Profile 3 (Annexes D.1, F.2 (4MV), I, J, K, T) + * MPEG4 Part 2 Simple Profile Level 3: + * H.264 Baseline Level 1.1 with constraint_set1_flag=1 + * AMR-WB if 16khz is supported
\ No newline at end of file diff --git a/Software/Farstream/RFCs.mdwn b/Software/Farstream/RFCs.mdwn new file mode 100644 index 00000000..3844027f --- /dev/null +++ b/Software/Farstream/RFCs.mdwn @@ -0,0 +1,37 @@ + +This is an exhaustive list of the RFCs that are implemented. + +Generic RTP RFCs: + +* RFC 3550: RTP: A Transport Protocol for Real-Time Applications + * Replaces: RFC 1889 +* RFC 3551: RTP Profile for Audio and Video Conferences with Minimal Control + * Replaces: RFC 1890 +* RFC 4585: Extended RTP Profile for Real-time Transport Control Protocol (RTCP)-Based Feedback (RTP/AVPF) + * Only the generic mecanisms +* +* RFC 5285: A General Mechanism for RTP Header Extensions +SDP related (Farsight only implement the semantics, not the actual parsing): + +* RFC 3264: An Offer/Answer Model with SDP +* RFC 3605: RTCP attribute in SDP +Through libnice: + +* RFC 5245: Interactive Connectivity Establishment (ICE): A Protocol for Network Address Translator (NAT) Traversal for Offer/Answer Protocols +* draft-ietf-behave-turn: Traversal Using Relays around NAT (TURN): Relay Extensions to Session Traversal Utilities for NAT (STUN) +* RFC 5389: Session Traversal Utilities for NAT (STUN) + * Replaces: RFC 3489 +* RFC 2817: Upgrading to TLS Within HTTP/1.1 (Only a simple version of the HTTP Connect method) +* RFC 1928: SOCKS Protocol Version 5 +Codecs: + +* RFC 4733: RTP Payload for DTMF Digits, Telephony Tones, and Telephony Signals + * Only implement the telephone-event/DTMF part + * Replaces: RFC 2833 +* RFC 5574: RTP Payload Format for the Speex Codec +* RFC 4629: RTP Payload Format for ITU-T Rec. H.263 Video + * Replaces: RFC 2924: RTP Payload Format for the 1998 Version of ITU-T Rec. H.263 Video (H.263+) + * Replaces: RFC 2190: RTP Payload Format for H.263 Video Streams +* RFC 3984: RTP Payload Format for H.264 Video +* RFC 3267: Real-Time Transport Protocol (RTP) Payload Format and File Storage Format for the Adaptive Multi-Rate (AMR) and Adaptive Multi-Rate Wideband (AMR-WB) Audio Codecs (only the RTP part) +* RFC 3952: Real-time Transport Protocol (RTP) Payload Format for internet Low Bit Rate Codec (iLBC) Speech (only the RTP part)
\ No newline at end of file diff --git a/Software/Farstream/ReleaseChecklist.mdwn b/Software/Farstream/ReleaseChecklist.mdwn new file mode 100644 index 00000000..2a86782d --- /dev/null +++ b/Software/Farstream/ReleaseChecklist.mdwn @@ -0,0 +1,20 @@ + +Steps to make a new release of Farstream: + +* Fill in NEWS file +* Bump the libtool revision if the API/ABI has changed +* make check +* make distcheck +* Bump version in configure.ac (and remove nano) +* git commit -m "Version $VERSION" -a +* make check +* make distcheck +* gpg --detach-sign -a $TARBALL +* git tag -s -m "Farstream $VERSION" $VERSION +* Set the nano version to 1 +* git commit -m "Version $VERSION.1" -a +* git push --tags origin master +* scp $TARBALL* annarchy.freedesktop.org:/srv/www.freedesktop.org/www/software/farstream/releases/farstream +* scp -r docs/libs/html/* annarchy.freedesktop.org:/srv/www.freedesktop.org/www/software/farstream/apidoc/farstream +* scp -r docs/plugins/html/* annarchy.freedesktop.org:/srv/www.freedesktop.org/www/software/farstream/apidoc/farstream-plugins +* Write release announcement and email to farstream-devel and [[ftp-release@lists.freedesktop.org|mailto:ftp-release@lists.freedesktop.org]]
\ No newline at end of file diff --git a/Software/Farstream/RtcWeb_Requirements.mdwn b/Software/Farstream/RtcWeb_Requirements.mdwn new file mode 100644 index 00000000..02cb10ce --- /dev/null +++ b/Software/Farstream/RtcWeb_Requirements.mdwn @@ -0,0 +1,26 @@ + +Here is a list of missing features for the [[RtcWeb|RtcWeb]] requirements as of Nov 10, 2011. Note that none of this is set is stone, so this list may change in the future. + +* SRTP, so we can support the RTP/SAVPF profile) (RFC 5124 + RFC 3711) + * Including DTLS-SRTP (RFC 5764) +* RTCP session bandwidth modifiers (RFC 3556) +* rtcp multiplexing (RFC 5761) +* Reduced size RTCP (RFC 5506) +* Support for multiple stun/turn servers (in libnice) +Not required, but recommented: + +* RTP Header extension for rapid sync (RFC 6051) +* Mixer levels in RTP hdrext (currently in draft) +Not exactly in Farstream, but related: + +* RFC 6222: Guidelines for Choosing RTP Control Protocol (RTCP) Canonical Names (CNAMEs) +Not yet defined enough to implemenent: + +* RTP session multiplexing (multiple drafts are circulating) +* Better congestion control + * May include RTCP TMMBR/TMMBN +* Some kind of FEC... maybe +References: + +* [[IETF rtcweb workgroup|http://tools.ietf.org/wg/rtcweb/]] +* [[Web Real-Time Communication (WebRTC): Media Transport and Use of RTP|http://tools.ietf.org/html/draft-ietf-rtcweb-rtp-usage]]
\ No newline at end of file diff --git a/Software/Farstream/Talks.mdwn b/Software/Farstream/Talks.mdwn new file mode 100644 index 00000000..3e9bb6c5 --- /dev/null +++ b/Software/Farstream/Talks.mdwn @@ -0,0 +1,15 @@ + +Here is a list of some talks that I (Olivier Crête) has given about Farsight: + + +### 2008 + +* Linux.Conf.Au ([[Video|http://mirror.linux.org.au/pub/linux.conf.au/2008/Fri/mel8-163.ogg]],[[Audio only|http://mirror.linux.org.au/pub/linux.conf.au/2008/Fri/mel8-163.spx]], [[Slides|http://mirror.linux.org.au/pub/linux.conf.au/2008/slides/163-farsight2-lca2008-presentation.pdf]]) +* Fosdem ([[Slides|http://www.tester.ca/files/farsight2-fosdem2008-presentation.pdf]]) +* GUADEC ([[Slides|http://people.collabora.co.uk/~tester/farsight2-guadec2008-presentation.pdf]]) +* foss.in ([[Slides|http://foss.in/2008/register/slides/Farsight_2__Video_conferencing_made_easy_691.pdf]]) <== Best Slides! + +### 2009 + +* Linux.Conf.Au ([[Slides|http://people.collabora.co.uk/~tester/talks/fs2-integration-lca09.pdf]]) +* Bossa ([[Video|http://blip.tv/file/1884455]], [[Slides|http://people.collabora.co.uk/~tester/talks/farsight2-bossa2009-slides.pdf]])
\ No newline at end of file diff --git a/Software/Farstream/Todo.mdwn b/Software/Farstream/Todo.mdwn new file mode 100644 index 00000000..eddf4578 --- /dev/null +++ b/Software/Farstream/Todo.mdwn @@ -0,0 +1,66 @@ + +See also [[Farstream/ApiProblems|Farstream/ApiProblems]] + +I've also listed the missing requirements for [[Voice over LTE (VoLTE)|Software/Farstream/LTE Requirements]] and [[rtcweb|Software/Farstream/RtcWeb Requirements]]. + +Voice over LTE (VoLTE) has [[extra requirements|Software/Farstream/LTE Requirements]]. WebRTc + + +### RTP plugin + +* Add an "extra-send-codecs" property to [[FsSession|FsSession]] and add it to the "farsight-send-codec-changed" message +* RTP/RTCP multiplexing/demultiplexing (to send both on the same UDP port) +* Comfort noise (write Free software VAD and CN generator) +* Add REDundant audio data (RFC 2198) +* Support multiple stun servers in the rawudp plugin and possibly also libnice +* Document + * That you have to be playing for most stuff to happen (like getting stun replies) +* Re-write codec discovery + * Make it possible to use the missing-element message to ask the user to install extra codecs, so keep list of pay/depay without enc/dec + * Make it possible to specify input/output caps so we can send pre-encoded data, etc + * Make the codec cleaner and hopefully remove the h263/amr hacks +* SRTP: There is a branch of gst-plugins-bad that integrates libsrtp. The farstream integration needs to be done too + +#### Tests to write + +* Two sessions in the same conference +* Packets with invalid payload types +* Setting invalid payload types as local or remote codecs (in the 35-96 range). +* Errors: + * New stream with invalid participant (invalid... from another type or from + * another conf?) +* Change codec ids while its running... +* New codec with the same PT while its running +* H263-1998 (use h263 or h263+ encoder depending on the properties) +* 3 way negotiation + * success + * failed +* Test codec cache: + * empty + * save + * load +* Test non-rtcp case (drop rtcp, filter candidate, provide wrong candidate?) + * Test lack of rtcp with more than one participant (it should fail) +* Change the udp port of a stream while it's running (rawudp transmitter, multicast transmitter?) +* Generate DTMF + * Sound (write dtmf detector?) +* Receive DTMF + * Events (without dtmf detector? only check if [[GstMessages|GstMessages]] are received maybe?) +* Changing a running pipeline + * Add a session to a running pipeline + * Destroy a session in a running pipeline + * Re-add a destroying session in a running pipline +* Write automated tests for the live adder +* Set to playing more than once? + +### Other plugins + +Port msnav, yahoowebcam to the new api + + +### Generic GStreamer RTP enhancements + +* Make reverse propagation of SDP optional parameters to the encoders + * Speex + * H263 + * H264
\ No newline at end of file diff --git a/Software/FixesExt.mdwn b/Software/FixesExt.mdwn new file mode 100644 index 00000000..608ee242 --- /dev/null +++ b/Software/FixesExt.mdwn @@ -0,0 +1,31 @@ + + +## X Fixes Extension + + +### Changing the way X works since 2003 + +The X Fixes extension is designed to hold various vaguely related extension bits that change how the X server and clients interact with fundemental parts of the window system. The goal is for all of the changes to reside entirely within the device-independent portion of the X server and hence be relatively portable to any X server implementation. + +[[Keith's proposal for XFixes version 2 from CVS|http://cvs.freedesktop.org/xlibs/FixesExt/protocol?view=markup]] + + +### X Fixes Version 1 + +Version 1 of the extension included: + + * Save Set processing changes. Core save set processing breaks in the presence of nesting. This extension makes embedding applications more reliable + * Selection notification events. The core provides no way to be notified when a selection changes. This adds events sent when selection ownership is asserted. + * Cursor tracking. The core protocol provides no way to tell what cursor image is currently displayed. This adds requests that allow the image to be tracked reliably + +### X Fixes Version 2 + +Version 2 of the extension adds: + + * Region objects. X uses regions in both the server and client to represent sets of pixel addresses. Exposing these objects in the protocol will allow for improved performance as well as simplifying some other new extensions + * Cursor names. Applying a label to each cursor will improve cursor tracking from Version 1 and also permit re-theming of the system by replacing all existing cursors of a specified name with new images. +-- [[KeithPackard|KeithPackard]] - 15 Oct 2003 [[!img http:/png/glider.png] + +--- + + [[CategoryExtension|CategoryExtension]] diff --git a/Software/Fonts.mdwn b/Software/Fonts.mdwn new file mode 100644 index 00000000..892ef296 --- /dev/null +++ b/Software/Fonts.mdwn @@ -0,0 +1,233 @@ + + +## Fonts + + +### Lists of Free/Libre and Open Unicode fonts + + * [[Unicode Font Guide For Free/Libre Open Source Operating Systems|http://www.unifont.org/fontguide/]]. It is maintained by Ed Trager. + * [[http://scripts.sil.org/OFL_fonts|http://scripts.sil.org/OFL_fonts]]. OFL-ed font list maintained by SIL. + +### Draft Recommendations for Default Unicode Fonts By Script + +**Introduction** + +Free/Libre Open Source (FLOSS) desktop infrastructure has matured rapidly in the last few years. As part of this phenomenon, an increasing number of modern Unicode fonts for numerous human scripts have become available under FLOSS licenses such as the GPL, Vera Bitstream-style licenses, and, most recently, the Open Font License (OFL) [[http://scripts.sil.org/OFL|http://scripts.sil.org/OFL]]. An additional number of fonts are available for "free download" under licensing terms that are not yet as clear as many in the Free/Open Source and Free Desktop community would like. A number of these Free/Libre and otherwise open Unicode fonts are referenced in Ed Trager's _Unicode Font Guide For Free/Libre Open Source Operating Systems_ on **unifont.org**. Fonts specifically released under the OFL are referenced on SIL's _OFL Fonts_ page on **sil.org**. URLs to both sites are provided above. Links to additional font resources may be found toward the bottom of this document. + +As GNU/Linux and other Free Software / Open Source operating systems become mainstream all over the world, there is an increasing need for distributors of these operating systems to be able to build out font infrastructure from a common basis or set of standards. + +This draft document represents the beginnings of one part of that effort and follows from a recent discussion at the GNOME User and Developer European Conference (GUADEC, [[http://guadec.org/|http://guadec.org/]]) on figuring out the most appropriate FLOSS fonts that a distribution could choose for various Unicode script blocks. Earlier discussions at the Libre Graphics Meeting, the Ubuntu Summit and the LSB meetings also touched upon improving the situation with fonts on the free desktop at large. + +The task of choosing a set of default fonts has both _objective_ and _subjective_ aspects to it. + +On the objective side, it is obviously necessary to evaluate how well a given font covers a given script and the orthographies of human languages which use that script. It is also necessary to decide whether a font is easy to read on screen and on paper. In the case of Indic, Indic-derived and Middle Eastern scripts, it is often also necessary to evaluate the sets of ligatures and glyph substitutions that need to occur for proper orthographies. + +On the subjective side, it is necessary to decide whether a font sufficiently agrees with a language community or nation's _collective consciousness_ about how typeset letters and words should look. For example, by now most people who have been following the various debates on Unicode over the last few years are well aware that the Japanese have a slightly different standard from the Chinese on how many Kanji/Hanzi/漢字 should appear. A much less well-known example is that the Vietnamese, who use a Latin orthography in their modern writing, expect to see slightly greater vertical line spacing by default to accomodate the numerous diacritical marks that are required by their orthography. + +Given the complex interaction between the objective and subjective tests that a font must "pass" in order to be accepted as a good default, it should be evident that it will very likely be _impossible_ to please everyone in every language community. Limitations in current software, especially in how the Font****Config library can be configured, make it even more certain that pleasing everyone is an unrealistic goal. + +Nevertheless, we trust that the combined and constructive efforts of the Free/Open Source community will lead to the genesis of a set of very reasonable defaults that will meet the needs of the majority of users in most language communities especially when fonts can be modified or branched thanks to an appropriate license. + + +#### Testing + +For testing fonts, especially Open****Type ones, please read [[http://pravin-s.blogspot.com/2008/02/how-to-test-open-type-fonts.html|http://pravin-s.blogspot.com/2008/02/how-to-test-open-type-fonts.html]] + +Please collect test material on per-script pages and link them from the [[Software/Fonts/Tests|Software/Fonts/Tests]] page. + +**Notes About Terminology Used in Font Classification** + +The [[FontConfig|FontConfig]] library uses the terms _serif_, _sans_, and _monospace_ to describe three distinct categories of fonts. In modern Western typography, these terms have reasonable meanings. However, when applied in a more global script context, these terms are less adequate. In a global context, it would be much better to use the terms _modulated_ and _unmodulated_ instead of _serif_ and _sans_, respectively. A _modulated_ font is one in which the thickness of the stroke varies visibly whereas an _unmodulated_ font is one in which the thickness does not appear to vary appreciably when perceived by the human eye. + +In this global script context, _serif_ represents a _subset of mostly Western fonts in the larger global set of all modulated fonts_, while _sans_ likewise represents a different _subset of mostly Western fonts in the larger global set of unmodulated fonts_. + +Note also that _monospace_ fonts can only be created for a limited subset of scripts in the world. + +Finally, a number of vector and bitmap fonts have been carefully designed to maximize readability on computer screens. Font****Config does not currently distinguish a category of _screen_ fonts. However, it is worthwhile for us to do so nevertheless. + +Please put down the names of each font family along with the current license. + +**African Scripts** + +* Ethiopic: Abyssinica SIL (OFL) +* Tifinagh: Hapax Berber (Public Domain and GPL) + * 2nd choice: Dejavu Sans (Vera-style FLOSS licence) +* Latin (African Reference or Pan-Nigerian Alphabet): + * Unmodulated (Sans): Deja Vu Sans (Vera-style FLOSS licence) + * Modulated (Serif): Deja Vu Serif (Vera-style FLOSS license). Gentium (OFL) over Deja Vu Serif? + * Screen: Deja Vu Sans (Vera-style FLOSS license) + * Monospace: Deja Vu Sans Mono (Vera-style FLOSS license) +**American Scripts** + +* Unified Canadian Syllabics: +* Cherokee: MPH 2B Damase (Public Domain?) +**European Scripts** + +* Armenian: +* Cyrillic: + * Unmodulated (Sans): Deja Vu Sans (Vera-style FLOSS licence) + * Modulated (Serif): Deja Vu Serif (Vera-style FLOSS license). Anybody want to vote for Gentium (OFL) over Deja Vu Serif? + * Screen: Deja Vu Sans (Vera-style FLOSS license) + * Monospace: Deja Vu Sans Mono (Vera-style FLOSS license) +* Georgian: + * Unmodulated: BPG Glaho (GPL) + * Modulated: BPG Chveulebrivi (GPL) + * Monospace: BPG Courier (GPL) +* Greek: + * Unmodulated (Sans): [[MgOpen|MgOpen]] Moderna (Vera-style FLOSS license) + * Modulated (Serif): [[MgOpen|MgOpen]] Canonica (Vera-style FLOSS license) + * Monospace: [[DejaVu|DejaVu]] Sans Mono (Vera-style FLOSS license) +* Latin: + * Unmodulated (Sans): Deja Vu Sans (Vera-style FLOSS licence) + * 2nd choice : Andika (OFL) + * 3rd choice: Linux Libertine (GPL + OFL) + * Modulated (Serif): Deja Vu Serif (Vera-style FLOSS license). Would anyone like to submit votes for Gentium (OFL) over Deja Vu Serif? + * Screen: Deja Vu Sans (Vera-style FLOSS license) + * Monospace: Deja Vu Sans Mono (Vera-style FLOSS license) -- + * 2nd choice: Inconsolata (OFL) +**Middle East Fonts** + +* Arabic: + * Is the style of the [[FarsiWeb|FarsiWeb]] fonts for Farsi suitable to use them as the defaults for both Farsi and Arabic language locales? Need to verify licensing of [[FarsiWeb|FarsiWeb]] fonts: + * Unmodulated: Roya ? Scheherazade (OFL) + * Modulated: Nazli ? +* Hebrew: + * Unmodulated: Ezra SIL (OFL) +**East Asian Scripts** + +* Chinese: + * Unmodulated: Same as modulated one (see note below) + * Modulated: AR PL Shan Hei Sun Uni (APL). ( 宋 Song/Sung/Sun ) style. + * Screen: Currently probably must remain the same as the modulated one: In the near future, we expect Wen Quan Yi Bitmap Font 文泉驿 (GPL) + * will be preferred once the fontconfig bitmap-in-TTF issues on Linux are resolved. +_Nota bene_: + + * Recent Chinese Unicode font projects make the division into simplified (简体字) vs. traditional (繁體字/正體字) fonts obsolete. + * The chinese font style matching 'unmodulated' is Hei style (黑体). All publicly available Hei style fonts are commercial ones. "AR PL Zen****Kai Uni" is in "楷体" style (Kai style), which is used generally for artistic purposes, but rarely on screen. Nor is it an unmodulated one. + * As people in the Taiwan Area, HK/Macao, SE Asia, N America and the mainland appear to disagree on the preferable looks of traditional (Hant) glyphs, and as these design differences within the Sinosphere seem to be of more or less the same severity as differences between _hanzi_ and _hanja_ fonts (the latter of which apparently follow the Kangxi Dictionary, whose designs were also still palatable enough in parts of the Sinosphere to make it into Windows' MingLiU _hanzi_ font where they have only recently been [[replaced|http://zh.wikipedia.org/wiki/新細明體更新套件]] with other shapes/variants), perhaps somebody should find out how pronounced, systematic or even explicit those intra-Hant preferences are and whether they would justify splitting this section into different regions. (For examples of intra-Hant differences either in minor shape details or in preferred glyph variants, see [[1|http://commons.wikimedia.org/wiki/File:Vergleich_zh-Hant-CN_zh-Hant-TW_ja-Hani_ko-Hani.png]]·[[2|http://commons.wikimedia.org/wiki/File:Differences_of_Chinese_characters_between_places.png]]·[[3|http://en.wikipedia.org/wiki/Variant_Chinese_character#Example_Characters]]·[[4|http://www.unicode.org/cgi-bin/GetUnihanData.pl?codepoint=6EAB]]) + * There are a number of screenshots on the WWW showing Kai style in UIs, so it seems it is not quite that rare. + * Wen Quan Yi is a truetype font containing bitmap glyphs **only**, so it doesn't work very well with vanilla fontconfig. Patch for fontconfig is needed. Besides, it can't be used for high-quality printing. +* Japanese: + * Unmodulated: Sazanami Gothic (project-specific BSD-like DFSG compatible) + * Modulated: Sazanami Mincho (project-specific BSD-like DFSG compatible) + * Screen: Sazanami Gothic (project-specific BSD-like DFSG compatible) +* Korean: + * Unmodulated: Un Dotum (GPL) + * Modulated: Un Batang (GPL) + * Screen: Either of the above + * Monospace: + * 1st choice: Un Dotum + * 2nd choice: Eun Guseul Mono (GPL), combining with [[DejaVu|DejaVu]] Sans Mono (Vera-style FLOSS license) + * For Middle Korean, the only free Unicode font is Un Jamo****Batang (GPL). +* Mongolian: + * “FLOSS systems do not yet support Mongolian. There are a number of problems…” ([[EH Trager 2006|http://www.unifont.org/textlayout/TheBigPicture.pdf]]; the same goes for Xibe, Manchu, and pre-1930 Tuvan) +* Yi: + * SIL YI (OFL) +* Tai Le: +**South Asian Scripts** + +* 9 major scripts of official languages in India [[full font list|http://www.indlinux.org/wiki/index.php/IndicFontsList]] + * Bengali: + * Devanagari: + * Gujarati: + * Gurmukhi (Punjabi): + * Kannada: + * Malayalam: + * Oriya: + * Tamil: + * Telugu: +* Sinhala: + * LKLUG (GPL) +* Tibetan/ Dzonghka + * Modulated: THDL Tibetan Machine Unicode (GPL) + * Jomolhari (OFL) +**Southeast Asian Scripts** + +* Burmese: + * Unmodulated: Padauk (OFL) + * Myanmar1 (LGPL) + * Parabaik (OFL) +* Khmer: + * Fonts from [[http://khmeros.info|http://khmeros.info]]: + * Unmodulated: Khmer OS Freehand (LGPL) + * Modulated: Khmer OS (LGPL) + * Screen: Khmer OS System (LGPL) +* Lao: + * Phetsarath OT (LGPL) +* Thai: + * National Font Project fonts available from the Thai Linux Working Group (TLWG): + * Unmodulated: Garuda (GPL) + * Modulated: Norasi (GPL) + * Screen: Loma (GPL) +* Vietnamese: + * Unmodulated (Sans): Deja Vu Sans (Vera-style FLOSS licence) + * Modulated (Serif): Deja Vu Serif (Vera-style FLOSS license) + * From [[urwvn fonts|http://freshmeat.net/projects/urwvn/]] (all GPL-2): + * Unmodulated: Vn Nimbus Sans L, Vn URW Gothic L, Vn URW Grotesk T + * Modulated: Vn Bitstream Charter, Vn Century Schoolbook L, Vn [[GaramondNo|GaramondNo]], Vn Nimbus Roman No9 L, Vn URW Bookman L, Vn URW Chancery L, Vn URW Palladio L + * Monospace: Vn Nimbus Mono L + +### Generic fonts.conf configuration file + +A Linux distribution can fine tune the precise font that will be used to render a specific language/script using the configuration files found in /etc/fonts/ + +We made a list of such existing configuration files, at [[Software/Fonts/fonts.conf|Software/Fonts/fonts.conf]]. If your distribution is not listed, please add the corresponding configuration file. + + +### Free/libre/open fonts + + * [[Bitstream Vera|http://www.gnome.org/fonts/]]: Very high quality font which unfortunately only supports Western European languages. + * [[DejaVu fonts|http://dejavu.sourceforge.net/]]: Bitstream Vera fonts derivatives with added features, covering Latin/Greek/Cyrillic including Combining Diacritics and Symbols. Experimental Serif Oblique fonts, Sans ExtraLight and Arabic, Armenian in DejaVu Sans. + * [[Arev|http://tavmjong.free.fr/FONTS/]]: Bitstream Vera Sans derivative with Greek, Cyrillic, Latin-A, Latin-B, Latin-Extended, IPA, Combining Diacritical Marks, Dingbats, and Symbol. + * [[PakType|http://www.zaban.net/paktype/index.html]]: Pakistani typography. + * [[Sampige|http://brahmi.sourceforge.net/downloads.html]]: Kannada font. + * [[Junicode|http://www.engl.virginia.edu/OE/junicode/junicode.html]]: A serif font, for medievalists. + * [[FreeFont|http://www.nongnu.org/freefont/]]: Set of free fonts with the goal of covering all of Unicode. FreeFont has a reputation for sacrificing quality in favor of coverage. + * [[Computer Modern Unicode|http://canopus.iacp.dvo.ru/~panov/cm-unicode/]]: Set of fonts derived from Donald Knuth's Computer Modern family, usually gotten using automatic tracing of bitmaps generated by Metafont. Supports Latin, most Cyrillic and Greek glyphs. + * [[Saab|http://guca.sourceforge.net/typography/fonts/saab/]]: Saab is the first ever freely available, Unicode 4.0 compliant, OpenType, Gurmukhi font. + * [[FarsiFonts|http://www.farsiweb.info/font/farsifonts-0.4.zip]]: Set of high quality free fonts for Persian, developed by the [[FarsiWeb Project|http://farsiweb.info]]. + * [[Nafees Web Naskh|http://www.crulp.org/Downloads/NafeesWeb.ttf]]: The OTF font for Urdu web. The GPL release [[announcement|http://groups.yahoo.com/group/urdu_computing/message/1081]] from [[CRULP|http://crulp.org]]. + * [[Charis SIL|http://scripts.sil.org/CharisSILfont]] : Extended Roman/Latin, including phonetic transcription. Supports Unicode 4.1, includes smart font code for diacritic positioning. [Regular, Italic, Bold, Bold Italic] (large line height for special needs) + * [[Gentium|http://scripts.sil.org/Gentium]] : Extended Roman/Latin, including phonetic transcription. Supports Unicode 3. [Regular, Italic] (award-winning design) + * [[Doulos SIL|http://scripts.sil.org/DoulosSILfont]] : Extended Roman/Latin, including phonetic transcription. Supports Unicode 4.1, includes smart font code for diacritic positioning. [Regular] (large line height for special needs) + * [[Abyssinica SIL|http://scripts.sil.org/AbyssinicaSIL]] : Smart font for the Ethiopic script (Amharic). Based on Ethiopic calligraphic traditions. Supports all Ethiopic characters which are in Unicode including the Unicode 4.1 extensions. Some languages of Ethiopia represented in the Private Use Area. [Regular - no other weights planned] + * [[Padauk|http://scripts.sil.org/Padauk]] : Smart font for Myanmar + * [[John Stracke's fonts|http://www.thibault.org/fonts/]]: Several styled ASCII fonts + * [[URWVN fonts|http://freshmeat.net/projects/urwvn/]]: URW++ derived fonts with additional Vietnamese glyphs + * [[CJKUnifonts|http://www.freedesktop.org/wiki/Software_2fCJKUnifonts]]: AR PL [[ShanHeiSun|ShanHeiSun]] Uni and AR PL [[ZenKai|ZenKai]] Uni fonts, which currently support Big5, GB2312, HKSCS-2004 and Vietnamese (precomposed Latin glyphs). Additional support for Minnan and Hakka languages is work in progress. + * [[SIL Yi|http://scripts.sil.org/SILYI_home]] : font for the Yi script + * [[GFS Didot|http://www.greekfontsociety.org/pages/en_typefaces.html]] : Latin and Greek coverage. + * [[GFS Bodoni|http://www.greekfontsociety.org/pages/en_typefaces.html]] : Latin and Greek coverage. + * [[GFS Olga|http://www.greekfontsociety.org/pages/en_typefaces.html]] : Latin and Greek coverage. + * [[GFS Neohellenic|http://www.greekfontsociety.org/pages/en_typefaces.html]] : Latin and Greek coverage. + * [[GFS Porson|http://www.greekfontsociety.org/pages/en_typefaces.html]] : Latin and Greek coverage. + * [[GFS Elpis|http://www.greekfontsociety.org/pages/en_typefaces.html]] : Latin and Greek coverage. + * Many more open fonts from GFS: [[http://greekfontsociety.org/pages/en_typefaces1.html|http://greekfontsociety.org/pages/en_typefaces1.html]] + * [[Inconsolata|http://www.levien.com/type/myfonts/inconsolata.html]]: Latin Monospace. + * [[Jomolhari|http://chris.fynn.googlepages.com/jomolhari]] : Tibetan and Dzonghka coverage + * [[Ezra SIL|http://scripts.sil.org/EzraSIL_Home]] Hebrew coverage. + * [[Old Standard|http://www.thessalonica.org.ru/en/fonts.html]]: Latin, Greek Cyrillic coverage. + * [[Andika|http://script.sil.org/Andika]]: Extended Latin coverage. + * [[Linux Libertine|http://linuxlibertine.sourceforge.net]] Latin coverage. + * [[Arkpandis|http://perso.orange.fr/arkandis/ADF/fonts.html]]. + +## Possibly future free/libre/open fonts (currently freeware) + + * [[Lateef|http://scripts.sil.org/ArabicFonts]] : smart Arabic fonts + * [[Galatia SIL Greek Unicode Fonts|http://scripts.sil.org/SILgrkuni]] : smart font for ancient Greek + +## Non-free fonts + + * [[TITUS Cyberbit Basic|http://titus.fkidg1.uni-frankfurt.de/unicode/tituut.asp]] + * [[Code2000 and Code2001|http://home.att.net/%7Ejameskass/]]: Code2000 covers a wide range of the [[BMP|Software/BMP]] and includes opentype tables for some scripts; itâs a very good font to have for anyone interested in internationalization. Code2001 has characters beyond the BMP. (Code2000 is shareware, Code2001 is freeware) + * [[Microsoft's Core Web Fonts|http://corefonts.sourceforge.net/]]: Microsoft's TrueType Arial, Verdana, Times New Roman, and a couple of other fonts. These may legally be installed on a Linux computer, under the terms of the accompanying EULA. They cover most Western and Central European characters, and some other characters including Greek, Cyrillic, Arabic, and Hebrew. + * [[Porson|http://www.geocities.com/greekfonts/]]: A really nice font for greek, based on the famous typeface which was originally cut from a transcript of Euripides' Medea in the hand of the preeminent nineteenth century classical scholar Richard Porson, of Cambridge. + * [[STIX|http://www.stixfonts.org/]]: fonts for the scientific and engineering community. not yet released. + + + + + + + + diff --git a/Software/Fonts/Tests.mdwn b/Software/Fonts/Tests.mdwn new file mode 100644 index 00000000..80b67944 --- /dev/null +++ b/Software/Fonts/Tests.mdwn @@ -0,0 +1,4 @@ + +Please collect tests for specific scripts here. For large scripts, creating a sub-page would be a good idea. + +For more ideas on testing, please read [[http://pravin-s.blogspot.com/2008/02/how-to-test-open-type-fonts.html|http://pravin-s.blogspot.com/2008/02/how-to-test-open-type-fonts.html]] diff --git a/Software/Fonts/fonts.conf.mdwn b/Software/Fonts/fonts.conf.mdwn new file mode 100644 index 00000000..cfb9cb93 --- /dev/null +++ b/Software/Fonts/fonts.conf.mdwn @@ -0,0 +1,2719 @@ + +This is a collection of fonts.conf files as found in Linux distributions. Fontconfig allows the finetuning of the configuration by permitting individual configuration snippets in the conf.d subdirectory. In the files listed below, we note whether those configuration snippets affect the selection of the main fonts; generally they finetune issues such as hinting and AA. + + +### Fedora Core 6 Devel (8 July 2006) -- WITH DEJAVU EXPERIMENTAL INSTALLED --- VERIFIED + + + <?xml version="1.0"?> + <!DOCTYPE fontconfig SYSTEM "fonts.dtd"> + <!-- /etc/fonts/fonts.conf file to configure system font access --> + <fontconfig> + + <!-- + DO NOT EDIT THIS FILE. + IT WILL BE REPLACED WHEN FONTCONFIG IS UPDATED. + LOCAL CHANGES BELONG IN 'local.conf'. + + The intent of this standard configuration file is to be adequate for + most environments. If you have a reasonably normal environment and + have found problems with this configuration, they are probably + things that others will also want fixed. Please submit any + problems to the fontconfig bugzilla system located at fontconfig.org + + Note that the normal 'make install' procedure for fontconfig is to + replace any existing fonts.conf file with the new version. Place + any local customizations in local.conf which this file references. + + Keith Packard + --> + + <!-- Font directory list --> + + <dir>/usr/share/fonts</dir> + <dir>/usr/share/X11/fonts/Type1</dir> <dir>/usr/share/X11/fonts/OTF</dir> + <dir>~/.fonts</dir> + + <!-- + Accept deprecated 'mono' alias, replacing it with 'monospace' + --> + <match target="pattern"> + <test qual="any" name="family"> + <string>mono</string> + </test> + <edit name="family" mode="assign"> + <string>monospace</string> + </edit> + </match> + + <!-- + Accept alternate 'sans serif' spelling, replacing it with 'sans-serif' + --> + <match target="pattern"> + <test qual="any" name="family"> + <string>sans serif</string> + </test> + <edit name="family" mode="assign"> + <string>sans-serif</string> + </edit> + </match> + + <!-- + Accept deprecated 'sans' alias, replacing it with 'sans-serif' + --> + <match target="pattern"> + <test qual="any" name="family"> + <string>sans</string> + </test> + <edit name="family" mode="assign"> + <string>sans-serif</string> + </edit> + </match> + + <!-- + Mark common families with their generics so we'll get + something reasonable + --> + + <!-- + Serif faces + --> + <alias> + <family>DejaVu Serif</family> + <family>Bitstream Vera Serif</family> + <family>Times New Roman</family> + <family>Thorndale AMT</family> + <family>Times</family> + <family>Nimbus Roman No9 L</family> + <family>Luxi Serif</family> + <family>Kochi Mincho</family> + <family>Sazanami Mincho</family> + <family>AR PL ZenKai Uni</family> + <family>AR PL SungtiL GB</family> + <family>AR PL Mingti2L Big5</family> + <family>ï¼ï¼³ ææ</family> + <family>Baekmuk Batang</family> + <family>FreeSerif</family> + <family>MgOpen Canonica</family> + <default><family>serif</family></default> + </alias> + <!-- + Sans-serif faces + --> + <alias> + <family>DejaVu Sans</family> + <family>Bitstream Vera Sans</family> + <family>Helvetica</family> + <family>Arial</family> + <family>Verdana</family> + <family>Albany AMT</family> + <family>Nimbus Sans L</family> + <family>Luxi Sans</family> + <family>Sazanami Gothic</family> + <family>Kochi Gothic</family> + <family>AR PL ShanHeiSun Uni</family> + <family>AR PL KaitiM GB</family> + <family>AR PL KaitiM Big5</family> + <family>ï¼ï¼³ ã´ã·ãã¯</family> + <family>Baekmuk Dotum</family> + <family>SimSun</family> + <family>FreeSans</family> + <family>MgOpen Modata</family> + <default><family>sans-serif</family></default> + </alias> + <!-- + Monospace faces + --> + <alias> + <family>DejaVu Sans Mono</family> + <family>Courier</family> + <family>Courier New</family> + <family>Andale Mono</family> + <family>Luxi Mono</family> + <family>Cumberland AMT</family> + <family>Nimbus Mono L</family> + <family>NSimSun</family> + <family>FreeMono</family> + <default><family>monospace</family></default> + </alias> + <!-- + If the font still has no generic name, add sans-serif + --> + <match target="pattern"> + <test qual="all" name="family" compare="not_eq"> + <string>sans-serif</string> + </test> + <test qual="all" name="family" compare="not_eq"> + <string>serif</string> + </test> + <test qual="all" name="family" compare="not_eq"> + <string>monospace</string> + </test> + <edit name="family" mode="append_last"> + <string>sans-serif</string> + </edit> + </match> + + <!-- + URW provides metric and shape compatible fonts for these 10 Adobe families. + --> + <alias> + <family>Avant Garde</family> + <accept><family>URW Gothic L</family></accept> + </alias> + <alias> + <family>Bookman</family> + <accept><family>URW Bookman L</family></accept> + </alias> + <alias> + <family>Courier</family> + <accept> + <family>Cumberland AMT</family> + <family>Courier New</family> + <family>Nimbus Mono L</family> + </accept> + </alias> + <alias> + <family>Helvetica</family> + <accept> + <family>Nimbus Sans L</family> + <family>Albany AMT</family> + <family>Arial</family> + </accept> + </alias> + <alias> + <family>New Century Schoolbook</family> + <accept><family>Century Schoolbook L</family></accept> + </alias> + <alias> + <family>Palatino</family> + <accept><family>URW Palladio L</family></accept> + </alias> + <alias> + <family>Times</family> + <accept> + <family>Nimbus Roman No9 L</family> + <family>Thorndale AMT</family> + <family>Times New Roman</family> + </accept> + </alias> + <alias> + <family>Zapf Chancery</family> + <accept><family>URW Chancery L</family></accept> + </alias> + <alias> + <family>Zapf Dingbats</family> + <accept><family>Dingbats</family></accept> + </alias> + <alias> + <family>ZapfDingbats</family> + <accept><family>Dingbats</family></accept> + </alias> + <match target="pattern"> + <test name="family"> + <string>Symbol</string> + </test> + <edit name="family" mode="append" binding="strong"> + <string>Standard Symbols L</string> + </edit> + </match> + <!-- + AMT provides metric and shape compatible fonts for these three web font + families. + --> + <alias> + <family>Times New Roman</family> + <accept> + <family>Thorndale AMT</family> + <family>Nimbus Roman No9 L</family> + </accept> + </alias> + <alias> + <family>Arial</family> + <accept> + <family>Albany AMT</family> + <family>Nimbus Sans L</family> + <family>Arial</family> + </accept> + </alias> + <alias> + <family>Courier New</family> + <accept><family>Cumberland AMT</family></accept> + </alias> + + <!-- + Some Asian fonts misadvertise themselves as monospaced when + in fact they are dual-spaced (half and full). This makes + FreeType very confused as it forces all widths to match. + Undo this magic by disabling the width forcing code --> + <match target="font"> + <test name="family"><string>GulimChe</string></test> + <edit name="globaladvance"><bool>false</bool></edit> + </match> + + <match target="font"> + <test name="family"><string>DotumChe</string></test> + <edit name="globaladvance"><bool>false</bool></edit> + </match> + + <match target="font"> + <test name="family"><string>BatangChe</string></test> + <edit name="globaladvance"><bool>false</bool></edit> + </match> + + <match target="font"> + <test name="family"><string>GungsuhChe</string></test> + <edit name="globaladvance"><bool>false</bool></edit> + </match> + + <!-- + The Bitstream Vera fonts have GASP entries suggesting that hinting be + disabled below 8 ppem, but FreeType ignores those, preferring to use + the data found in the instructed hints. The initial Vera release + didn't include the right instructions in the 'prep' table. Fix this + by disabling hinting manually at smaller sizes (< 8ppem) + --> + + <match target="font"> + <test name="family"> + <string>Bitstream Vera Sans</string> + </test> + <test name="pixelsize" compare="less"> + <double>7.5</double> + </test> + <edit name="hinting"> + <bool>false</bool> + </edit> + </match> + + <match target="font"> + <test name="family"> + <string>Bitstream Vera Serif</string> + </test> + <test name="pixelsize" compare="less"> + <double>7.5</double> + </test> + <edit name="hinting"> + <bool>false</bool> + </edit> + </match> + + <match target="font"> + <test name="family"> + <string>Bitstream Vera Sans Mono</string> + </test> + <test name="pixelsize" compare="less"> + <double>7.5</double> + </test> + <edit name="hinting"> + <bool>false</bool> + </edit> + </match> + + <!-- + Load per-user customization file + --> + <include ignore_missing="yes">~/.fonts.conf</include> + + <!-- + Load local system customization file + --> + <include ignore_missing="yes">conf.d</include> + <include ignore_missing="yes">local.conf</include> + + <!-- + Provide required aliases for standard names + --> + <alias> + <family>serif</family> + <prefer> + <family>Nimbus Roman No9 L</family> + <family>Thorndale AMT</family> + <family>Bitstream Vera Serif</family> + <family>Times New Roman</family> + <family>Luxi Serif</family> + <family>Times</family> + <family>KacstQura</family> + <family>Frank Ruehl CLM</family> + <family>Lohit Bengali</family> + <family>Lohit Gujarati</family> + <family>Lohit Hindi</family> + <family>Lohit Punjabi</family> + <family>Lohit Tamil</family> + <family>Sazanami Mincho</family> + <family>Kochi Mincho</family> + <family>ZYSong18030</family> + <family>MgOpen Canonica</family> + <family>FreeSerif</family> + <family>AR PL Zenkai Uni</family> + <family>AR PL SungtiL GB</family> + <family>AR PL Mingti2L Big5</family> + <family>ï¼ï¼³ ææ</family> + <family>Baekmuk Batang</family> + </prefer> + </alias> + <alias> + <family>sans-serif</family> + <prefer> + <family>Luxi Sans</family> + <family>Albany AMT</family> + <family>Bitstream Vera Sans</family> + <family>Verdana</family> + <family>Arial</family> + <family>Nimbus Sans L</family> + <family>Helvetica</family> + <family>KacstQura</family> + <family>Nachlieli</family> + <family>Lohit Bengali</family> + <family>Lohit Gujarati</family> + <family>Lohit Hindi</family> + <family>Lohit Punjabi</family> + <family>Lohit Tamil</family> + <family>Sazanami Gothic</family> + <family>Kochi Gothic</family> + <family>ï¼ï¼³ ã´ã·ãã¯</family> + <family>MgOpen Modata</family> + <family>FreeSans</family> + <family>ZYSong18030</family> + <family>AR PL ShanHeiSun Uni</family> + <family>AR PL SungtiL GB</family> + <family>AR PL Mingti2L Big5</family> + <family>Baekmuk Gulim</family> + <family>SimSun</family> + </prefer> + </alias> + <alias> + <family>monospace</family> + <prefer> + <family>Luxi Mono</family> + <family>Bitstream Vera Sans Mono</family> + <family>Andale Mono</family> + <family>Courier New</family> + <family>Cumberland AMT</family> + <family>KacstQura</family> + <family>Miriam Mono CLM</family> + <family>Lohit Bengali</family> + <family>Lohit Gujarati</family> + <family>Lohit Hindi</family> + <family>Lohit Punjabi</family> + <family>Lohit Tamil</family> + <family>Nimbus Mono L</family> + <family>Courier</family> + <family>Sazanami Gothic</family> + <family>Kochi Gothic</family> + <family>ZYSong18030</family> + <family>AR PL ShanHeiSun Uni</family> + <family>AR PL SungtiL GB</family> + <family>AR PL Mingti2L Big5</family> + <family>Baekmuk Gulim</family> + <family>FreeMono</family> + </prefer> + </alias> + + <!-- + Artificial oblique for fonts without an italic or oblique version + --> + + <match target="font"> + <!-- check to see if the font is roman --> + <test name="slant"> + <const>roman</const> + </test> + <!-- check to see if the pattern requested non-roman --> + <test target="pattern" name="slant" compare="not_eq"> + <const>roman</const> + </test> + <!-- multiply the matrix to slant the font --> + <edit name="matrix" mode="assign"> + <times> + <name>matrix</name> + <matrix><double>1</double><double>0.2</double> + <double>0</double><double>1</double> + </matrix> + </times> + </edit> + <!-- pretend the font is oblique now --> + <edit name="slant" mode="assign"> + <const>oblique</const> + </edit> + <!-- and disable embedded bitmaps for artificial oblique --> + <edit name="embeddedbitmap" mode="assign"> + <bool>false</bool> + </edit> + </match> + + <!-- + Synthetic emboldening for fonts that do not have bold face available + --> + + <match target="font"> + <!-- check to see if the font is just regular --> + <test name="weight" compare="less_eq"> + <const>medium</const> + </test> + <!-- check to see if the pattern requests bold --> + <test target="pattern" name="weight" compare="more"> + <const>medium</const> + </test> + <!-- + set the embolden flag + needed for applications using cairo, e.g. gucharmap, gedit, ... + --> + <edit name="embolden" mode="assign"> + <bool>true</bool> + </edit> + <!-- + set weight to bold + needed for applications using Xft directly, e.g. Firefox, ... + --> + <edit name="weight" mode="assign"> + <const>bold</const> + </edit> + </match> + + + <config> + <!-- + These are the default Unicode chars that are expected to be blank + in fonts. All other blank chars are assumed to be broken and + won't appear in the resulting charsets + --> + <blank> + <int>0x0020</int> <!-- SPACE --> + <int>0x00A0</int> <!-- NO-BREAK SPACE --> + <int>0x00AD</int> <!-- SOFT HYPHEN --> + <int>0x034F</int> <!-- COMBINING GRAPHEME JOINER --> + <int>0x0600</int> <!-- ARABIC NUMBER SIGN --> + <int>0x0601</int> <!-- ARABIC SIGN SANAH --> + <int>0x0602</int> <!-- ARABIC FOOTNOTE MARKER --> + <int>0x0603</int> <!-- ARABIC SIGN SAFHA --> + <int>0x06DD</int> <!-- ARABIC END OF AYAH --> + <int>0x070F</int> <!-- SYRIAC ABBREVIATION MARK --> + <int>0x115F</int> <!-- HANGUL CHOSEONG FILLER --> + <int>0x1160</int> <!-- HANGUL JUNGSEONG FILLER --> + <int>0x1680</int> <!-- OGHAM SPACE MARK --> + <int>0x17B4</int> <!-- KHMER VOWEL INHERENT AQ --> + <int>0x17B5</int> <!-- KHMER VOWEL INHERENT AA --> + <int>0x180E</int> <!-- MONGOLIAN VOWEL SEPARATOR --> + <int>0x2000</int> <!-- EN QUAD --> + <int>0x2001</int> <!-- EM QUAD --> + <int>0x2002</int> <!-- EN SPACE --> + <int>0x2003</int> <!-- EM SPACE --> + <int>0x2004</int> <!-- THREE-PER-EM SPACE --> + <int>0x2005</int> <!-- FOUR-PER-EM SPACE --> + <int>0x2006</int> <!-- SIX-PER-EM SPACE --> + <int>0x2007</int> <!-- FIGURE SPACE --> + <int>0x2008</int> <!-- PUNCTUATION SPACE --> + <int>0x2009</int> <!-- THIN SPACE --> + <int>0x200A</int> <!-- HAIR SPACE --> + <int>0x200B</int> <!-- ZERO WIDTH SPACE --> + <int>0x200C</int> <!-- ZERO WIDTH NON-JOINER --> + <int>0x200D</int> <!-- ZERO WIDTH JOINER --> + <int>0x200E</int> <!-- LEFT-TO-RIGHT MARK --> + <int>0x200F</int> <!-- RIGHT-TO-LEFT MARK --> + <int>0x2028</int> <!-- LINE SEPARATOR --> + <int>0x2029</int> <!-- PARAGRAPH SEPARATOR --> + <int>0x202A</int> <!-- LEFT-TO-RIGHT EMBEDDING --> + <int>0x202B</int> <!-- RIGHT-TO-LEFT EMBEDDING --> + <int>0x202C</int> <!-- POP DIRECTIONAL FORMATTING --> + <int>0x202D</int> <!-- LEFT-TO-RIGHT OVERRIDE --> + <int>0x202E</int> <!-- RIGHT-TO-LEFT OVERRIDE --> + <int>0x202F</int> <!-- NARROW NO-BREAK SPACE --> + <int>0x205F</int> <!-- MEDIUM MATHEMATICAL SPACE --> + <int>0x2060</int> <!-- WORD JOINER --> + <int>0x2061</int> <!-- FUNCTION APPLICATION --> + <int>0x2062</int> <!-- INVISIBLE TIMES --> + <int>0x2063</int> <!-- INVISIBLE SEPARATOR --> + <int>0x206A</int> <!-- INHIBIT SYMMETRIC SWAPPING --> + <int>0x206B</int> <!-- ACTIVATE SYMMETRIC SWAPPING --> + <int>0x206C</int> <!-- INHIBIT ARABIC FORM SHAPING --> + <int>0x206D</int> <!-- ACTIVATE ARABIC FORM SHAPING --> + <int>0x206E</int> <!-- NATIONAL DIGIT SHAPES --> + <int>0x206F</int> <!-- NOMINAL DIGIT SHAPES --> + <int>0x3000</int> <!-- IDEOGRAPHIC SPACE --> + <int>0x3164</int> <!-- HANGUL FILLER --> + <int>0xFEFF</int> <!-- ZERO WIDTH NO-BREAK SPACE --> + <int>0xFFA0</int> <!-- HALFWIDTH HANGUL FILLER --> + <int>0xFFF9</int> <!-- INTERLINEAR ANNOTATION ANCHOR --> + <int>0xFFFA</int> <!-- INTERLINEAR ANNOTATION SEPARATOR --> + <int>0xFFFB</int> <!-- INTERLINEAR ANNOTATION TERMINATOR --> + </blank> + <!-- + Rescan configuration every 30 seconds when FcFontSetList is called + --> + <rescan> + <int>30</int> + </rescan> + </config> + + </fontconfig> + +### Fedora Core 6 Devel (from extracted fontconfig binary package) + +The source file was fontconfig-2.3.95-4.i386.rpm. + +Fedora Core 6 Devel the following configuration snippets, + + 10-fonts-persian.conf 10LohitGujarati.conf 40-blacklist-fonts.conf 50-no-hint-fonts.conf + + <?xml version="1.0"?> + <!DOCTYPE fontconfig SYSTEM "fonts.dtd"> + <!-- /etc/fonts/fonts.conf file to configure system font access --> + <fontconfig> + + <!-- + DO NOT EDIT THIS FILE. + IT WILL BE REPLACED WHEN FONTCONFIG IS UPDATED. + LOCAL CHANGES BELONG IN 'local.conf'. + + The intent of this standard configuration file is to be adequate for + most environments. If you have a reasonably normal environment and + have found problems with this configuration, they are probably + things that others will also want fixed. Please submit any + problems to the fontconfig bugzilla system located at fontconfig.org + + Note that the normal 'make install' procedure for fontconfig is to + replace any existing fonts.conf file with the new version. Place + any local customizations in local.conf which this file references. + + Keith Packard + --> + + <!-- Font directory list --> + + <dir>/usr/share/fonts</dir> + <dir>/usr/share/X11/fonts/Type1</dir> <dir>/usr/share/X11/fonts/OTF</dir> + <dir>~/.fonts</dir> + + <!-- + Accept deprecated 'mono' alias, replacing it with 'monospace' + --> + <match target="pattern"> + <test qual="any" name="family"> + <string>mono</string> + </test> + <edit name="family" mode="assign"> + <string>monospace</string> + </edit> + </match> + + <!-- + Accept alternate 'sans serif' spelling, replacing it with 'sans-serif' + --> + <match target="pattern"> + <test qual="any" name="family"> + <string>sans serif</string> + </test> + <edit name="family" mode="assign"> + <string>sans-serif</string> + </edit> + </match> + + <!-- + Accept deprecated 'sans' alias, replacing it with 'sans-serif' + --> + <match target="pattern"> + <test qual="any" name="family"> + <string>sans</string> + </test> + <edit name="family" mode="assign"> + <string>sans-serif</string> + </edit> + </match> + + <!-- + Mark common families with their generics so we'll get + something reasonable + --> + + <!-- + Serif faces + --> + <alias> + <family>DejaVu Serif</family> + <family>Bitstream Vera Serif</family> + <family>Times New Roman</family> + <family>Thorndale AMT</family> + <family>Times</family> + <family>Nimbus Roman No9 L</family> + <family>Luxi Serif</family> + <family>Kochi Mincho</family> + <family>Sazanami Mincho</family> + <family>AR PL ZenKai Uni</family> + <family>AR PL SungtiL GB</family> + <family>AR PL Mingti2L Big5</family> + <family>ï¼ï¼³ ææ</family> + <family>Baekmuk Batang</family> + <family>FreeSerif</family> + <family>MgOpen Canonica</family> + <default><family>serif</family></default> + </alias> + <!-- + Sans-serif faces + --> + <alias> + <family>DejaVu Sans</family> + <family>Bitstream Vera Sans</family> + <family>Helvetica</family> + <family>Arial</family> + <family>Verdana</family> + <family>Albany AMT</family> + <family>Nimbus Sans L</family> + <family>Luxi Sans</family> + <family>Sazanami Gothic</family> + <family>Kochi Gothic</family> + <family>AR PL ShanHeiSun Uni</family> + <family>AR PL KaitiM GB</family> + <family>AR PL KaitiM Big5</family> + <family>ï¼ï¼³ ã´ã·ãã¯</family> + <family>Baekmuk Dotum</family> + <family>SimSun</family> + <family>FreeSans</family> + <family>MgOpen Modata</family> + <default><family>sans-serif</family></default> + </alias> + <!-- + Monospace faces + --> + <alias> + <family>DejaVu Sans Mono</family> + <family>Courier</family> + <family>Courier New</family> + <family>Andale Mono</family> + <family>Luxi Mono</family> + <family>Cumberland AMT</family> + <family>Nimbus Mono L</family> + <family>NSimSun</family> + <family>FreeMono</family> + <default><family>monospace</family></default> + </alias> + <!-- + If the font still has no generic name, add sans-serif + --> + <match target="pattern"> + <test qual="all" name="family" compare="not_eq"> + <string>sans-serif</string> + </test> + <test qual="all" name="family" compare="not_eq"> + <string>serif</string> + </test> + <test qual="all" name="family" compare="not_eq"> + <string>monospace</string> + </test> + <edit name="family" mode="append_last"> + <string>sans-serif</string> + </edit> + </match> + + <!-- + URW provides metric and shape compatible fonts for these 10 Adobe families. + --> + <alias> + <family>Avant Garde</family> + <accept><family>URW Gothic L</family></accept> + </alias> + <alias> + <family>Bookman</family> + <accept><family>URW Bookman L</family></accept> + </alias> + <alias> + <family>Courier</family> + <accept> + <family>Cumberland AMT</family> + <family>Courier New</family> + <family>Nimbus Mono L</family> + </accept> + </alias> + <alias> + <family>Helvetica</family> + <accept> + <family>Nimbus Sans L</family> + <family>Albany AMT</family> + <family>Arial</family> + </accept> + </alias> + <alias> + <family>New Century Schoolbook</family> + <accept><family>Century Schoolbook L</family></accept> + </alias> + <alias> + <family>Palatino</family> + <accept><family>URW Palladio L</family></accept> + </alias> + <alias> + <family>Times</family> + <accept> + <family>Nimbus Roman No9 L</family> + <family>Thorndale AMT</family> + <family>Times New Roman</family> + </accept> + </alias> + <alias> + <family>Zapf Chancery</family> + <accept><family>URW Chancery L</family></accept> + </alias> + <alias> + <family>Zapf Dingbats</family> + <accept><family>Dingbats</family></accept> + </alias> + <alias> + <family>ZapfDingbats</family> + <accept><family>Dingbats</family></accept> + </alias> + <match target="pattern"> + <test name="family"> + <string>Symbol</string> + </test> + <edit name="family" mode="append" binding="strong"> + <string>Standard Symbols L</string> + </edit> + </match> + <!-- + AMT provides metric and shape compatible fonts for these three web font + families. + --> + <alias> + <family>Times New Roman</family> + <accept> + <family>Thorndale AMT</family> + <family>Nimbus Roman No9 L</family> + </accept> + </alias> + <alias> + <family>Arial</family> + <accept> + <family>Albany AMT</family> + <family>Nimbus Sans L</family> + <family>Arial</family> + </accept> + </alias> + <alias> + <family>Courier New</family> + <accept><family>Cumberland AMT</family></accept> + </alias> + + <!-- + Some Asian fonts misadvertise themselves as monospaced when + in fact they are dual-spaced (half and full). This makes + FreeType very confused as it forces all widths to match. + Undo this magic by disabling the width forcing code --> + <match target="font"> + <test name="family"><string>GulimChe</string></test> + <edit name="globaladvance"><bool>false</bool></edit> + </match> + + <match target="font"> + <test name="family"><string>DotumChe</string></test> + <edit name="globaladvance"><bool>false</bool></edit> + </match> + + <match target="font"> + <test name="family"><string>BatangChe</string></test> + <edit name="globaladvance"><bool>false</bool></edit> + </match> + + <match target="font"> + <test name="family"><string>GungsuhChe</string></test> + <edit name="globaladvance"><bool>false</bool></edit> + </match> + + <!-- + The Bitstream Vera fonts have GASP entries suggesting that hinting be + disabled below 8 ppem, but FreeType ignores those, preferring to use + the data found in the instructed hints. The initial Vera release + didn't include the right instructions in the 'prep' table. Fix this + by disabling hinting manually at smaller sizes (< 8ppem) + --> + + <match target="font"> + <test name="family"> + <string>Bitstream Vera Sans</string> + </test> + <test name="pixelsize" compare="less"> + <double>7.5</double> + </test> + <edit name="hinting"> + <bool>false</bool> + </edit> + </match> + + <match target="font"> + <test name="family"> + <string>Bitstream Vera Serif</string> + </test> + <test name="pixelsize" compare="less"> + <double>7.5</double> + </test> + <edit name="hinting"> + <bool>false</bool> + </edit> + </match> + + <match target="font"> + <test name="family"> + <string>Bitstream Vera Sans Mono</string> + </test> + <test name="pixelsize" compare="less"> + <double>7.5</double> + </test> + <edit name="hinting"> + <bool>false</bool> + </edit> + </match> + + <!-- + Load per-user customization file + --> + <include ignore_missing="yes">~/.fonts.conf</include> + + <!-- + Load local system customization file + --> + <include ignore_missing="yes">conf.d</include> + <include ignore_missing="yes">local.conf</include> + + <!-- + Provide required aliases for standard names + --> + <alias> + <family>serif</family> + <prefer> + <family>Nimbus Roman No9 L</family> + <family>Thorndale AMT</family> + <family>Bitstream Vera Serif</family> + <family>Times New Roman</family> + <family>Luxi Serif</family> + <family>Times</family> + <family>KacstQura</family> + <family>Frank Ruehl CLM</family> + <family>Lohit Bengali</family> + <family>Lohit Gujarati</family> + <family>Lohit Hindi</family> + <family>Lohit Punjabi</family> + <family>Lohit Tamil</family> + <family>Sazanami Mincho</family> + <family>Kochi Mincho</family> + <family>ZYSong18030</family> + <family>MgOpen Canonica</family> + <family>FreeSerif</family> + <family>AR PL Zenkai Uni</family> + <family>AR PL SungtiL GB</family> + <family>AR PL Mingti2L Big5</family> + <family>ï¼ï¼³ ææ</family> + <family>Baekmuk Batang</family> + </prefer> + </alias> + <alias> + <family>sans-serif</family> + <prefer> + <family>Luxi Sans</family> + <family>Albany AMT</family> + <family>Bitstream Vera Sans</family> + <family>Verdana</family> + <family>Arial</family> + <family>Nimbus Sans L</family> + <family>Helvetica</family> + <family>KacstQura</family> + <family>Nachlieli</family> + <family>Lohit Bengali</family> + <family>Lohit Gujarati</family> + <family>Lohit Hindi</family> + <family>Lohit Punjabi</family> + <family>Lohit Tamil</family> + <family>Sazanami Gothic</family> + <family>Kochi Gothic</family> + <family>ï¼ï¼³ ã´ã·ãã¯</family> + <family>MgOpen Modata</family> + <family>FreeSans</family> + <family>ZYSong18030</family> + <family>AR PL ShanHeiSun Uni</family> + <family>AR PL SungtiL GB</family> + <family>AR PL Mingti2L Big5</family> + <family>Baekmuk Gulim</family> + <family>SimSun</family> + </prefer> + </alias> + <alias> + <family>monospace</family> + <prefer> + <family>Luxi Mono</family> + <family>Bitstream Vera Sans Mono</family> + <family>Andale Mono</family> + <family>Courier New</family> + <family>Cumberland AMT</family> + <family>KacstQura</family> + <family>Miriam Mono CLM</family> + <family>Lohit Bengali</family> + <family>Lohit Gujarati</family> + <family>Lohit Hindi</family> + <family>Lohit Punjabi</family> + <family>Lohit Tamil</family> + <family>Nimbus Mono L</family> + <family>Courier</family> + <family>Sazanami Gothic</family> + <family>Kochi Gothic</family> + <family>ZYSong18030</family> + <family>AR PL ShanHeiSun Uni</family> + <family>AR PL SungtiL GB</family> + <family>AR PL Mingti2L Big5</family> + <family>Baekmuk Gulim</family> + <family>FreeMono</family> + </prefer> + </alias> + + <!-- + Artificial oblique for fonts without an italic or oblique version + --> + + <match target="font"> + <!-- check to see if the font is roman --> + <test name="slant"> + <const>roman</const> + </test> + <!-- check to see if the pattern requested non-roman --> + <test target="pattern" name="slant" compare="not_eq"> + <const>roman</const> + </test> + <!-- multiply the matrix to slant the font --> + <edit name="matrix" mode="assign"> + <times> + <name>matrix</name> + <matrix><double>1</double><double>0.2</double> + <double>0</double><double>1</double> + </matrix> + </times> + </edit> + <!-- pretend the font is oblique now --> + <edit name="slant" mode="assign"> + <const>oblique</const> + </edit> + <!-- and disable embedded bitmaps for artificial oblique --> + <edit name="embeddedbitmap" mode="assign"> + <bool>false</bool> + </edit> + </match> + + <!-- + Synthetic emboldening for fonts that do not have bold face available + --> + + <match target="font"> + <!-- check to see if the font is just regular --> + <test name="weight" compare="less_eq"> + <const>medium</const> + </test> + <!-- check to see if the pattern requests bold --> + <test target="pattern" name="weight" compare="more"> + <const>medium</const> + </test> + <!-- + set the embolden flag + needed for applications using cairo, e.g. gucharmap, gedit, ... + --> + <edit name="embolden" mode="assign"> + <bool>true</bool> + </edit> + <!-- + set weight to bold + needed for applications using Xft directly, e.g. Firefox, ... + --> + <edit name="weight" mode="assign"> + <const>bold</const> + </edit> + </match> + + + <config> + <!-- + These are the default Unicode chars that are expected to be blank + in fonts. All other blank chars are assumed to be broken and + won't appear in the resulting charsets + --> + <blank> + <int>0x0020</int> <!-- SPACE --> + <int>0x00A0</int> <!-- NO-BREAK SPACE --> + <int>0x00AD</int> <!-- SOFT HYPHEN --> + <int>0x034F</int> <!-- COMBINING GRAPHEME JOINER --> + <int>0x0600</int> <!-- ARABIC NUMBER SIGN --> + <int>0x0601</int> <!-- ARABIC SIGN SANAH --> + <int>0x0602</int> <!-- ARABIC FOOTNOTE MARKER --> + <int>0x0603</int> <!-- ARABIC SIGN SAFHA --> + <int>0x06DD</int> <!-- ARABIC END OF AYAH --> + <int>0x070F</int> <!-- SYRIAC ABBREVIATION MARK --> + <int>0x115F</int> <!-- HANGUL CHOSEONG FILLER --> + <int>0x1160</int> <!-- HANGUL JUNGSEONG FILLER --> + <int>0x1680</int> <!-- OGHAM SPACE MARK --> + <int>0x17B4</int> <!-- KHMER VOWEL INHERENT AQ --> + <int>0x17B5</int> <!-- KHMER VOWEL INHERENT AA --> + <int>0x180E</int> <!-- MONGOLIAN VOWEL SEPARATOR --> + <int>0x2000</int> <!-- EN QUAD --> + <int>0x2001</int> <!-- EM QUAD --> + <int>0x2002</int> <!-- EN SPACE --> + <int>0x2003</int> <!-- EM SPACE --> + <int>0x2004</int> <!-- THREE-PER-EM SPACE --> + <int>0x2005</int> <!-- FOUR-PER-EM SPACE --> + <int>0x2006</int> <!-- SIX-PER-EM SPACE --> + <int>0x2007</int> <!-- FIGURE SPACE --> + <int>0x2008</int> <!-- PUNCTUATION SPACE --> + <int>0x2009</int> <!-- THIN SPACE --> + <int>0x200A</int> <!-- HAIR SPACE --> + <int>0x200B</int> <!-- ZERO WIDTH SPACE --> + <int>0x200C</int> <!-- ZERO WIDTH NON-JOINER --> + <int>0x200D</int> <!-- ZERO WIDTH JOINER --> + <int>0x200E</int> <!-- LEFT-TO-RIGHT MARK --> + <int>0x200F</int> <!-- RIGHT-TO-LEFT MARK --> + <int>0x2028</int> <!-- LINE SEPARATOR --> + <int>0x2029</int> <!-- PARAGRAPH SEPARATOR --> + <int>0x202A</int> <!-- LEFT-TO-RIGHT EMBEDDING --> + <int>0x202B</int> <!-- RIGHT-TO-LEFT EMBEDDING --> + <int>0x202C</int> <!-- POP DIRECTIONAL FORMATTING --> + <int>0x202D</int> <!-- LEFT-TO-RIGHT OVERRIDE --> + <int>0x202E</int> <!-- RIGHT-TO-LEFT OVERRIDE --> + <int>0x202F</int> <!-- NARROW NO-BREAK SPACE --> + <int>0x205F</int> <!-- MEDIUM MATHEMATICAL SPACE --> + <int>0x2060</int> <!-- WORD JOINER --> + <int>0x2061</int> <!-- FUNCTION APPLICATION --> + <int>0x2062</int> <!-- INVISIBLE TIMES --> + <int>0x2063</int> <!-- INVISIBLE SEPARATOR --> + <int>0x206A</int> <!-- INHIBIT SYMMETRIC SWAPPING --> + <int>0x206B</int> <!-- ACTIVATE SYMMETRIC SWAPPING --> + <int>0x206C</int> <!-- INHIBIT ARABIC FORM SHAPING --> + <int>0x206D</int> <!-- ACTIVATE ARABIC FORM SHAPING --> + <int>0x206E</int> <!-- NATIONAL DIGIT SHAPES --> + <int>0x206F</int> <!-- NOMINAL DIGIT SHAPES --> + <int>0x3000</int> <!-- IDEOGRAPHIC SPACE --> + <int>0x3164</int> <!-- HANGUL FILLER --> + <int>0xFEFF</int> <!-- ZERO WIDTH NO-BREAK SPACE --> + <int>0xFFA0</int> <!-- HALFWIDTH HANGUL FILLER --> + <int>0xFFF9</int> <!-- INTERLINEAR ANNOTATION ANCHOR --> + <int>0xFFFA</int> <!-- INTERLINEAR ANNOTATION SEPARATOR --> + <int>0xFFFB</int> <!-- INTERLINEAR ANNOTATION TERMINATOR --> + </blank> + <!-- + Rescan configuration every 30 seconds when FcFontSetList is called + --> + <rescan> + <int>30</int> + </rescan> + </config> + + </fontconfig> + + +### Mandriva 2006.0 (from extracted fontconfig binary package) + +The source file was fontconfig-2.3.2-5mdk.i586.rpm. + +Mandriva uses the following configuration snippets, + + 00-mdk-urwfonts.conf 03-mdk-disable-hinting.conf + 01-mdk-CJK-dualwidth.conf 04-mdk-avoid-bitmap.conf + 02-mdk-disable-antialias.conf + + <?xml version="1.0"?> + <!DOCTYPE fontconfig SYSTEM "fonts.dtd"> + <!-- /etc/fonts/fonts.conf file to configure system font access --> + <fontconfig> + + <!-- + DO NOT EDIT THIS FILE. + IT WILL BE REPLACED WHEN FONTCONFIG IS UPDATED. + LOCAL CHANGES BELONG IN 'local.conf'. + + The intent of this standard configuration file is to be adequate for + most environments. If you have a reasonably normal environment and + have found problems with this configuration, they are probably + things that others will also want fixed. Please submit any + problems to the fontconfig bugzilla system located at fontconfig.org + + Note that the normal 'make install' procedure for fontconfig is to + replace any existing fonts.conf file with the new version. Place + any local customizations in local.conf which this file references. + + Keith Packard + --> + + <!-- Font directory list --> + + <dir>/usr/share/fonts</dir> + <dir>/usr/X11R6/lib/X11/fonts</dir> <dir>/opt/ttfonts</dir> <dir>/usr/share/yudit/fonts</dir> + <dir>~/.fonts</dir> + + <!-- + Accept deprecated 'mono' alias, replacing it with 'monospace' + --> + <match target="pattern"> + <test qual="any" name="family"> + <string>mono</string> + </test> + <edit name="family" mode="assign"> + <string>monospace</string> + </edit> + </match> + + <!-- + Accept alternate 'sans serif' spelling, replacing it with 'sans-serif' + --> + <match target="pattern"> + <test qual="any" name="family"> + <string>sans serif</string> + </test> + <edit name="family" mode="assign"> + <string>sans-serif</string> + </edit> + </match> + + <!-- + Accept deprecated 'sans' alias, replacing it with 'sans-serif' + --> + <match target="pattern"> + <test qual="any" name="family"> + <string>sans</string> + </test> + <edit name="family" mode="assign"> + <string>sans-serif</string> + </edit> + </match> + + <!-- + Mark common families with their generics so we'll get + something reasonable + --> + + <!-- + Serif faces + --> + <alias> + <family>Bitstream Vera Serif</family> + <family>Times New Roman</family> + <family>Thorndale AMT</family> + <family>Times</family> + <family>Nimbus Roman No9 L</family> + <family>Luxi Serif</family> + <family>Sazanami Gothic</family> + <family>SimSun</family> + <family>MingLiu</family> + <family>AR PL ShanHeiSun Uni</family> + <family>AR PL New Sung</family> + <family>AR PL SungtiL GB</family> + <family>AR PL Mingti2L Big5</family> + <family>IPAGothic</family> + <family>Sazanami Gothic</family> + <family>ï¼ï¼³ ææ</family> + <family>Baekmuk Batang</family> + <family>FreeSerif</family> + <default><family>serif</family></default> + </alias> + <!-- + Sans-serif faces + --> + <alias> + <family>Bitstream Vera Sans</family> + <family>Helvetica</family> + <family>Arial</family> + <family>Verdana</family> + <family>Albany AMT</family> + <family>Nimbus Sans L</family> + <family>Luxi Sans</family> + <family>AR PL ZenKai Uni</family> + <family>SimSun</family> + <family>MingLiu</family> + <family>AR PL New Sung</family> + <family>AR PL KaitiM GB</family> + <family>AR PL KaitiM Big5</family> + <family>IPAGothic</family> + <family>Sazanami Gothic</family> + <family>ï¼ï¼³ ã´ã·ãã¯</family> + <family>Baekmuk Dotum</family> + <family>FreeSans</family> + <default><family>sans-serif</family></default> + </alias> + <!-- + Monospace faces + --> + <alias> + <family>Bitstream Vera Sans Mono</family> + <family>Courier</family> + <family>Courier New</family> + <family>Andale Mono</family> + <family>Luxi Mono</family> + <family>Cumberland AMT</family> + <family>Nimbus Mono L</family> + <family>NSimSun</family> + <family>PMingLiu</family> + <family>AR PL New Sung</family> + <family>IPAPGothic</family> + <family>Sazanami Gothic</family> + <family>FreeMono</family> + <default><family>monospace</family></default> + </alias> + <!-- + If the font still has no generic name, add sans-serif + --> + <match target="pattern"> + <test qual="all" name="family" compare="not_eq"> + <string>sans-serif</string> + </test> + <test qual="all" name="family" compare="not_eq"> + <string>serif</string> + </test> + <test qual="all" name="family" compare="not_eq"> + <string>monospace</string> + </test> + <edit name="family" mode="append_last"> + <string>sans-serif</string> + </edit> + </match> + + <!-- + URW provides metric and shape compatible fonts for these 3 Adobe families. + --> + <alias> + <family>Times New Roman</family> + <accept><family>Nimbus Roman No9 L</family></accept> + </alias> + + <alias> + <family>Times</family> + <accept><family>Nimbus Roman No9 L</family></accept> + </alias> + <alias> + <family>Helvetica</family> + <accept><family>Nimbus Sans L</family></accept> + </alias> + <alias> + <family>Courier</family> + <accept><family>Nimbus Mono L</family></accept> + </alias> + <alias> + <family>Arial</family> + <accept> + <family>Nimbus Sans L</family> + <family>Arial</family> + </accept> + </alias> + + + <!-- + AMT provides metric and shape compatible fonts for these three web font + families. + --> + <alias> + <family>Times New Roman</family> + <accept><family>Thorndale AMT</family></accept> + </alias> + <alias> + <family>Arial</family> + <accept><family>Albany AMT</family></accept> + </alias> + <alias> + <family>Courier New</family> + <accept><family>Cumberland AMT</family></accept> + </alias> + + <!-- + Some Asian fonts misadvertise themselves as monospaced when + in fact they are dual-spaced (half and full). This makes + FreeType very confused as it forces all widths to match. + Undo this magic by disabling the width forcing code --> + <!-- not needed, replaced by 01-mdk-CJK-dualwidth.conf + <match target="font"> + <test name="family"><string>GulimChe</string></test> + <edit name="globaladvance"><bool>false</bool></edit> + </match> + + <match target="font"> + <test name="family"><string>DotumChe</string></test> + <edit name="globaladvance"><bool>false</bool></edit> + </match> + + <match target="font"> + <test name="family"><string>BatangChe</string></test> + <edit name="globaladvance"><bool>false</bool></edit> + </match> + + <match target="font"> + <test name="family"><string>GungsuhChe</string></test> + <edit name="globaladvance"><bool>false</bool></edit> + </match> + --> + <!-- + The Bitstream Vera fonts have GASP entries suggesting that hinting be + disabled below 8 ppem, but FreeType ignores those, preferring to use + the data found in the instructed hints. The initial Vera release + didn't include the right instructions in the 'prep' table. Fix this + by disabling hinting manually at smaller sizes (< 8ppem) + --> + + <match target="font"> + <test name="family"> + <string>Bitstream Vera Sans</string> + </test> + <test name="pixelsize" compare="less"> + <double>7.5</double> + </test> + <edit name="hinting"> + <bool>false</bool> + </edit> + </match> + + <match target="font"> + <test name="family"> + <string>Bitstream Vera Serif</string> + </test> + <test name="pixelsize" compare="less"> + <double>7.5</double> + </test> + <edit name="hinting"> + <bool>false</bool> + </edit> + </match> + + <match target="font"> + <test name="family"> + <string>Bitstream Vera Sans Mono</string> + </test> + <test name="pixelsize" compare="less"> + <double>7.5</double> + </test> + <edit name="hinting"> + <bool>false</bool> + </edit> + </match> + + <!-- + Load per-user customization file + --> + <include ignore_missing="yes">~/.fonts.conf</include> + + <!-- + Load local system customization file + --> + <include ignore_missing="yes">conf.d</include> + <include ignore_missing="yes">local.conf</include> + + <!-- + Provide required aliases for standard names + --> + <alias> + <family>serif</family> + <prefer> + <family>DejaVu Serif</family> + <family>Bitstream Vera Serif</family> + <family>Times New Roman</family> + <family>Thorndale AMT</family> + <family>Luxi Serif</family> + <family>Nimbus Roman No9 L</family> + <family>Times</family> + <family>Artsounk</family> <!-- armenian --> + <family>BPG UTF8 M</family> <!-- georgian --> + <family>Phaisarn</family> <!-- thai --> + <family>Phaisarn98</family> <!-- thai --> + <family>Norasi</family> <!-- thai --> + <family>Frank Ruehl</family> <!-- hebrew --> + <family>Dror</family> <!-- hebrew? --> + <family>JG LaoTimes</family> <!-- lao --> + <family>Saysettha Unicode</family> <!-- lao --> + <family>Pigiarniq</family> <!-- canadian syllabics --> + <family>B Davat</family> <!-- ??? --> + <family>B Compset</family> <!-- ??? --> + <family>Roya</family> <!-- arabic (ar,fa) --> + <family>Kacst-Qr</family> <!-- arabic (ar) --> + <family>Urdu Nastaliq Unicode</family> <!-- arabic (ur) --> + <family>Raghindi</family> <!-- devanagari --> + <family>Mukti Narrow</family> <!-- bengali --> + <family>malayalam</family> <!-- malayalam --> + <family>Sampige</family> <!-- kannada --> + <family>padmaa</family> <!-- gujarati --> + <family>Hapax Berbère</family> <!-- tifinagh --> + <family>MS Gothic</family> <!-- han (ja) --> + <family>Sazanami Gothic</family> <!-- han (ja) --> + <family>SimSun</family> <!-- han (zh-cn,zh-tw) --> + <family>MingLiu</family> <!-- han (zh-tw) --> + <family>AR PL ShanHeiSun Uni</family> <!-- han (ja,zh-cn,zh-tw) --> + <family>AR PL New Sung</family> <!-- han (zh-cn,zh-tw) --> + <family>ZYSong18030</family> <!-- han (zh-cn,zh-tw) --> + <family>HanyiSong</family> <!-- han (zh-cn,zh-tw) --> + <family>MS Song</family> <!-- han (zh-cn) --> + <family>Baekmuk Batang</family> <!-- hangul --> + <family>Kochi Mincho</family> + <family>ï¼ï¼³ ææ</family> + <family>FreeSerif</family> + <family>TSCu_Times</family> <!-- tamil --> + <family>Code2000</family> <!-- almost everything --> + <family>Code2001</family> <!-- plane1 and beyond --> + </prefer> + </alias> + <alias> + <family>sans-serif</family> + <prefer> + <family>BPG Glaho International</family> <!-- lat,cyr,arab,geor --> + <family>DejaVu Sans</family> + <family>Bitstream Vera Sans</family> + <family>Luxi Sans</family> + <family>Nimbus Sans L</family> + <family>Arial</family> + <family>Albany AMT</family> + <family>Helvetica</family> + <family>Verdana</family> + <family>Lucida Sans Unicode</family> + <family>Tahoma</family> <!-- lat,cyr,greek,heb,arab,thai --> + <family>Yudit Unicode</family> <!-- ?? --> + <family>Kerkis</family> <!-- greek --> + <family>ArmNet Helvetica</family> <!-- armenian --> + <family>Artsounk</family> <!-- armenian --> + <family>BPG UTF8 M</family> <!-- georgian --> + <family>Norasi</family> <!-- thai --> + <family>Nachlieli</family> <!-- hebrew --> + <family>Saysettha Unicode</family> <!-- lao? --> + <family>JG Lao Old Arial</family> <!-- lao --> + <family>GF Zemen Unicode</family> <!-- ethiopic --> + <family>Pigiarniq</family> <!-- canadian syllabics --> + <family>B Davat</family> <!-- ?? --> + <family>B Compset</family> <!-- ?? --> + <family>Roya</family> <!-- arabic (ar,fa) --> + <family>Kacst-Qr</family> <!-- arabic (ar) --> + <family>Urdu Nastaliq Unicode</family> <!-- arabic (ur) --> + <family>Raghindi</family> <!-- devanagari --> + <family>Mukti Narrow</family> <!-- bengali --> + <family>malayalam</family> <!-- malayalam --> + <family>Sampige</family> <!-- kannada --> + <family>padmaa</family> <!-- gujarati --> + <family>Hapax Berbère</family> <!-- tifinagh --> + <family>MS Gothic</family> <!-- han (ja) --> + <family>Sazanami Gothic</family> <!-- han (ja) --> + <!-- chinese fonts are actually serifed --> + <family>SimSun</family> <!-- han (zh-cn,zh-tw) --> + <family>MingLiu</family> <!-- han (zh-tw) --> + <family>AR PL ShanHeiSun Uni</family> <!--han (ja,zh-cn,zh-tw) --> + <family>AR PL New Sung</family> <!-- han (zh-cn,zh-tw) --> + <family>ZYSong18030</family> <!-- han (zh-cn,zh-tw) --> + <family>AR PL KaitiM GB</family> + <family>AR PL KaitiM Big5</family> + <family>HanyiSong</family> <!-- han (zh-cn) --> + <family>Baekmuk Gulim</family> <!-- hangul --> + <family>Hapax Berbère</family> <!-- tifinagh --> + <family>Kochi Gothic</family> + <family>ï¼ï¼³ ã´ã·ãã¯</family> + <family>Baekmuk Dotum</family> + <family>FreeSans</family> + <family>TSCu_Paranar</family> <!-- tamil --> + <family>Arial Unicode</family> + <family>Code2000</family> <!-- almost everything; serif actually --> + <family>Code2001</family> <!-- plane1 and beyond --> + </prefer> + </alias> + <alias> + <family>monospace</family> + <prefer> + <family>DejaVu Sans Mono</family> + <family>Bitstream Vera Sans Mono</family> + <family>Luxi Mono</family> + <family>Nimbus Mono L</family> + <family>Andale Mono</family> + <family>Courier New</family> + <family>Cumberland AMT</family> + <family>Courier</family> + <family>Courier MonoThai</family> <!-- thai --> + <family>Miriam Mono</family> <!-- hebrew --> + <family>Hasida</family> <!-- hebrew? --> + <family>Mitra Mono</family> <!-- bengali --> + <family>GF Zemen Unicode</family> <!-- ethiopic --> + <family>Hapax Berbère</family> <!-- tifinagh --> + <family>MS Gothic</family> <!-- han (ja) --> + <family>Sazanami Gothic</family> <!-- han (ja) --> + <family>NSimSun</family> <!-- han (zh-cn,zh-tw) --> + <family>PMingLiu</family> <!-- han (zh-tw) --> + <family>AR PL ShanHeiSun Uni</family> <!-- han (ja,zh-cn,zh-tw) --> + <family>AR PL New Sung</family> <!-- han (zh-cn,zh-tw) --> + <family>HanyiSong</family> <!-- han (zh-cn) --> + <family>ZYSong18030</family> <!-- han (zh-cn,zh-tw) --> + <family>Baekmuk Batang</family> <!-- hangul --> + <family>Kochi Gothic</family> + <family>Baekmuk Dotum</family> + <family>FreeMono</family> + </prefer> + </alias> + + <!-- + Artificial oblique for fonts without an italic or oblique version + --> + + <match target="font"> + <!-- check to see if the font is roman --> + <test name="slant"> + <const>roman</const> + </test> + <!-- check to see if the pattern requested non-roman --> + <test target="pattern" name="slant" compare="not_eq"> + <const>roman</const> + </test> + <!-- multiply the matrix to slant the font --> + <edit name="matrix" mode="assign"> + <times> + <name>matrix</name> + <matrix><double>1</double><double>0.2</double> + <double>0</double><double>1</double> + </matrix> + </times> + </edit> + <!-- pretend the font is oblique now --> + <edit name="slant" mode="assign"> + <const>oblique</const> + </edit> + </match> + + <!-- + Synthetic emboldening for fonts that do not have bold face available + --> + + <match target="font"> + <!-- check to see if the font is just regular --> + <test name="weight" compare="less_eq"> + <int>100</int> + </test> + <!-- check to see if the pattern requests bold --> + <test target="pattern" name="weight" compare="more_eq"> + <int>180</int> + </test> + <!-- set the embolden flag --> + <edit name="embolden" mode="assign"> + <bool>true</bool> + </edit> + </match> + + + <config> + <!-- + These are the default Unicode chars that are expected to be blank + in fonts. All other blank chars are assumed to be broken and + won't appear in the resulting charsets + --> + <blank> + <int>0x0020</int> <!-- SPACE --> + <int>0x00A0</int> <!-- NO-BREAK SPACE --> + <int>0x00AD</int> <!-- SOFT HYPHEN --> + <int>0x034F</int> <!-- COMBINING GRAPHEME JOINER --> + <int>0x0600</int> <!-- ARABIC NUMBER SIGN --> + <int>0x0601</int> <!-- ARABIC SIGN SANAH --> + <int>0x0602</int> <!-- ARABIC FOOTNOTE MARKER --> + <int>0x0603</int> <!-- ARABIC SIGN SAFHA --> + <int>0x06DD</int> <!-- ARABIC END OF AYAH --> + <int>0x070F</int> <!-- SYRIAC ABBREVIATION MARK --> + <int>0x115F</int> <!-- HANGUL CHOSEONG FILLER --> + <int>0x1160</int> <!-- HANGUL JUNGSEONG FILLER --> + <int>0x1680</int> <!-- OGHAM SPACE MARK --> + <int>0x17B4</int> <!-- KHMER VOWEL INHERENT AQ --> + <int>0x17B5</int> <!-- KHMER VOWEL INHERENT AA --> + <int>0x180E</int> <!-- MONGOLIAN VOWEL SEPARATOR --> + <int>0x2000</int> <!-- EN QUAD --> + <int>0x2001</int> <!-- EM QUAD --> + <int>0x2002</int> <!-- EN SPACE --> + <int>0x2003</int> <!-- EM SPACE --> + <int>0x2004</int> <!-- THREE-PER-EM SPACE --> + <int>0x2005</int> <!-- FOUR-PER-EM SPACE --> + <int>0x2006</int> <!-- SIX-PER-EM SPACE --> + <int>0x2007</int> <!-- FIGURE SPACE --> + <int>0x2008</int> <!-- PUNCTUATION SPACE --> + <int>0x2009</int> <!-- THIN SPACE --> + <int>0x200A</int> <!-- HAIR SPACE --> + <int>0x200B</int> <!-- ZERO WIDTH SPACE --> + <int>0x200C</int> <!-- ZERO WIDTH NON-JOINER --> + <int>0x200D</int> <!-- ZERO WIDTH JOINER --> + <int>0x200E</int> <!-- LEFT-TO-RIGHT MARK --> + <int>0x200F</int> <!-- RIGHT-TO-LEFT MARK --> + <int>0x2028</int> <!-- LINE SEPARATOR --> + <int>0x2029</int> <!-- PARAGRAPH SEPARATOR --> + <int>0x202A</int> <!-- LEFT-TO-RIGHT EMBEDDING --> + <int>0x202B</int> <!-- RIGHT-TO-LEFT EMBEDDING --> + <int>0x202C</int> <!-- POP DIRECTIONAL FORMATTING --> + <int>0x202D</int> <!-- LEFT-TO-RIGHT OVERRIDE --> + <int>0x202E</int> <!-- RIGHT-TO-LEFT OVERRIDE --> + <int>0x202F</int> <!-- NARROW NO-BREAK SPACE --> + <int>0x205F</int> <!-- MEDIUM MATHEMATICAL SPACE --> + <int>0x2060</int> <!-- WORD JOINER --> + <int>0x2061</int> <!-- FUNCTION APPLICATION --> + <int>0x2062</int> <!-- INVISIBLE TIMES --> + <int>0x2063</int> <!-- INVISIBLE SEPARATOR --> + <int>0x206A</int> <!-- INHIBIT SYMMETRIC SWAPPING --> + <int>0x206B</int> <!-- ACTIVATE SYMMETRIC SWAPPING --> + <int>0x206C</int> <!-- INHIBIT ARABIC FORM SHAPING --> + <int>0x206D</int> <!-- ACTIVATE ARABIC FORM SHAPING --> + <int>0x206E</int> <!-- NATIONAL DIGIT SHAPES --> + <int>0x206F</int> <!-- NOMINAL DIGIT SHAPES --> + <int>0x3000</int> <!-- IDEOGRAPHIC SPACE --> + <int>0x3164</int> <!-- HANGUL FILLER --> + <int>0xFEFF</int> <!-- ZERO WIDTH NO-BREAK SPACE --> + <int>0xFFA0</int> <!-- HALFWIDTH HANGUL FILLER --> + <int>0xFFF9</int> <!-- INTERLINEAR ANNOTATION ANCHOR --> + <int>0xFFFA</int> <!-- INTERLINEAR ANNOTATION SEPARATOR --> + <int>0xFFFB</int> <!-- INTERLINEAR ANNOTATION TERMINATOR --> + </blank> + <!-- + Rescan configuration every 30 seconds when FcFontSetList is called + --> + <rescan> + <int>30</int> + </rescan> + </config> + + </fontconfig> + +### Ubuntu Linux 6.06 (all updates; 8 Jul 2006) VERIFIED + +The file was generated from a stock installation and retrieved on the mentioned date. + +Ubuntu Linux 6.06 use additional configuration snippets on a per-locale basis, which is located in /usr/share/language-selector/fontconfig/. Font preference for each locale is written as snippet in aforementioned directory, then the one representing system locale is symlink'ed to conf.d folder. + + <?xml version="1.0"?> + <!DOCTYPE fontconfig SYSTEM "fonts.dtd"> + <!-- /etc/fonts/fonts.conf file to configure system font access --> + <fontconfig> + + <!-- + DO NOT EDIT THIS FILE. + IT WILL BE REPLACED WHEN FONTCONFIG IS UPDATED. + LOCAL CHANGES BELONG IN 'local.conf'. + + The intent of this standard configuration file is to be adequate for + most environments. If you have a reasonably normal environment and + have found problems with this configuration, they are probably + things that others will also want fixed. Please submit any + problems to the fontconfig bugzilla system located at fontconfig.org + + Note that the normal 'make install' procedure for fontconfig is to + replace any existing fonts.conf file with the new version. Place + any local customizations in local.conf which this file references. + + Keith Packard + --> + + <!-- Font directory list --> + + <dir>/usr/share/fonts</dir> + <dir>/usr/share/X11/fonts</dir> <dir>/usr/local/share/fonts</dir> + <dir>~/.fonts</dir> + + <!-- + Accept deprecated 'mono' alias, replacing it with 'monospace' + --> + <match target="pattern"> + <test qual="any" name="family"> + <string>mono</string> + </test> + <edit name="family" mode="assign"> + <string>monospace</string> + </edit> + </match> + + <!-- + Accept alternate 'sans serif' spelling, replacing it with 'sans-serif' + --> + <match target="pattern"> + <test qual="any" name="family"> + <string>sans serif</string> + </test> + <edit name="family" mode="assign"> + <string>sans-serif</string> + </edit> + </match> + + <!-- + Accept deprecated 'sans' alias, replacing it with 'sans-serif' + --> + <match target="pattern"> + <test qual="any" name="family"> + <string>sans</string> + </test> + <edit name="family" mode="assign"> + <string>sans-serif</string> + </edit> + </match> + + <!-- + Mark common families with their generics so we'll get + something reasonable + --> + + <!-- + Serif faces + --> + <alias> + <family>DejaVu Serif</family> + <family>Bitstream Vera Serif</family> + <family>Times New Roman</family> + <family>Thorndale AMT</family> + <family>Times</family> + <family>Nimbus Roman No9 L</family> + <family>Luxi Serif</family> + <family>Kochi Mincho</family> + <family>AR PL SungtiL GB</family> + <family>AR PL Mingti2L Big5</family> + <family>ï¼ï¼³ ææ</family> + <family>Baekmuk Batang</family> + <family>FreeSerif</family> + <family>MgOpen Canonica</family> + <default><family>serif</family></default> + </alias> + <!-- + Sans-serif faces + --> + <alias> + <family>DejaVu Sans</family> + <family>Bitstream Vera Sans</family> + <family>Helvetica</family> + <family>Arial</family> + <family>Verdana</family> + <family>Albany AMT</family> + <family>Nimbus Sans L</family> + <family>Luxi Sans</family> + <family>Kochi Gothic</family> + <family>AR PL KaitiM GB</family> + <family>AR PL KaitiM Big5</family> + <family>ï¼ï¼³ ã´ã·ãã¯</family> + <family>Baekmuk Dotum</family> + <family>SimSun</family> + <family>FreeSans</family> + <family>MgOpen Moderna</family> + <default><family>sans-serif</family></default> + </alias> + <!-- + Monospace faces + --> + <alias> + <family>DejaVu Sans Mono</family> + <family>Bitstream Vera Sans Mono</family> + <family>Courier</family> + <family>Courier New</family> + <family>Andale Mono</family> + <family>Luxi Mono</family> + <family>Cumberland AMT</family> + <family>Nimbus Mono L</family> + <family>NSimSun</family> + <family>FreeMono</family> + <default><family>monospace</family></default> + </alias> + <!-- + If the font still has no generic name, add sans-serif + --> + <match target="pattern"> + <test qual="all" name="family" compare="not_eq"> + <string>sans-serif</string> + </test> + <test qual="all" name="family" compare="not_eq"> + <string>serif</string> + </test> + <test qual="all" name="family" compare="not_eq"> + <string>monospace</string> + </test> + <edit name="family" mode="append_last"> + <string>sans-serif</string> + </edit> + </match> + + <!-- + Prefer "Standard Symbols L" as Symbol font + --> + <match target="pattern"> + <test name="family"> + <string>Symbol</string> + </test> + <edit name="family" mode="prepend" binding="same"> + <string>Standard Symbols L</string> + </edit> + </match> + + <!-- + URW provides metric and shape compatible fonts for these 3 Adobe families. + commented out, see below + <alias> + <family>Times</family> + <accept><family>Nimbus Roman No9 L</family></accept> + </alias> + <alias> + <family>Helvetica</family> + <accept><family>Nimbus Sans L</family></accept> + </alias> + <alias> + <family>Courier</family> + <accept><family>Nimbus Mono L</family></accept> + </alias> + --> + + <!-- + AMT provides metric and shape compatible fonts for these three web font + families. + --> + <alias> + <family>Times New Roman</family> + <accept><family>Thorndale AMT</family></accept> + </alias> + <alias> + <family>Arial</family> + <accept><family>Albany AMT</family></accept> + </alias> + <alias> + <family>Courier New</family> + <accept><family>Cumberland AMT</family></accept> + </alias> + + <alias> + <family>ZapfDingbats</family> + <accept><family>Dingbats</family></accept> + </alias> + + <alias> + <family>Symbol</family> + <accept><family>Open Symbols L</family></accept> + </alias> + + <!-- + URW provides metric and shape compatible fonts for these 3 Adobe families. + However, th ese fonts are quite ugly and do not render well on-screen, + so we avoid matching them if the application said `anymetrics'; in that + case, a more generic font with different metrics but better appearance + will be used. + --> + <match target="pattern"> + <test name="family"> + <string>Times</string> + </test> + <test name="anymetrics" qual="all" compare="not_eq"> + <bool>true</bool> + </test> + <edit name="family" mode="append"> + <string>Nimbus Roman No9 L</string> + </edit> + </match> + <match target="pattern"> + <test name="family"> + <string>Helvetica</string> + </test> + <test name="anymetrics" qual="all" compare="not_eq"> + <bool>true</bool> + </test> + <edit name="family" mode="append"> + <string>Nimbus Sans L</string> + </edit> + </match> + <match target="pattern"> + <test name="family"> + <string>Courier</string> + </test> + <test name="anymetrics" qual="all" compare="not_eq"> + <bool>true</bool> + </test> + <edit name="family" mode="append"> + <string>Nimbus Mono L</string> + </edit> + </match> + + <!-- + Do the same with the AMT family and the msttcorefonts, but add + the msttcorefonts as an alternative as well. + --> + <match target="pattern"> + <test name="family"> + <string>Times New Roman</string> + <string>Thorndale AMT</string> + <string>Thorndale</string> + </test> + <test name="anymetrics" qual="all" compare="not_eq"> + <bool>true</bool> + </test> + <edit name="family" mode="append"> + <string>Times New Roman</string> + <string>Nimbus Roman No9 L</string> + </edit> + </match> + <match target="pattern"> + <test name="family"> + <string>Arial</string> + <string>Albany AMT</string> + <string>Albany</string> + <string>Verdana</string> + </test> + <test name="anymetrics" qual="all" compare="not_eq"> + <bool>true</bool> + </test> + <edit name="family" mode="append"> + <string>Arial</string> + <string>Nimbus Sans L</string> + </edit> + </match> + <match target="pattern"> + <test name="family"> + <string>Courier New</string> + <string>Cumberland AMT</string> + <string>Cumberland</string> + </test> + <test name="anymetrics" qual="all" compare="not_eq"> + <bool>true</bool> + </test> + <edit name="family" mode="append"> + <string>Courier New</string> + <string>Nimbus Mono L</string> + </edit> + </match> + + <!-- + Some Asian fonts misadvertise themselves as monospaced when + in fact they are dual-spaced (half and full). This makes + FreeType very confused as it forces all widths to match. + Undo this magic by disabling the width forcing code --> + <match target="font"> + <test name="family"><string>GulimChe</string></test> + <edit name="globaladvance"><bool>false</bool></edit> + </match> + + <match target="font"> + <test name="family"><string>DotumChe</string></test> + <edit name="globaladvance"><bool>false</bool></edit> + </match> + + <match target="font"> + <test name="family"><string>BatangChe</string></test> + <edit name="globaladvance"><bool>false</bool></edit> + </match> + + <match target="font"> + <test name="family"><string>GungsuhChe</string></test> + <edit name="globaladvance"><bool>false</bool></edit> + </match> + + <!-- + The Bitstream Vera fonts have GASP entries suggesting that hinting be + disabled below 8 ppem, but FreeType ignores those, preferring to use + the data found in the instructed hints. The initial Vera release + didn't include the right instructions in the 'prep' table. Fix this + by disabling hinting manually at smaller sizes (< 8ppem) + --> + + <match target="font"> + <test name="family"> + <string>Bitstream Vera Sans</string> + </test> + <test name="pixelsize" compare="less"> + <double>7.5</double> + </test> + <edit name="hinting"> + <bool>false</bool> + </edit> + </match> + + <match target="font"> + <test name="family"> + <string>Bitstream Vera Serif</string> + </test> + <test name="pixelsize" compare="less"> + <double>7.5</double> + </test> + <edit name="hinting"> + <bool>false</bool> + </edit> + </match> + + <match target="font"> + <test name="family"> + <string>Bitstream Vera Sans Mono</string> + </test> + <test name="pixelsize" compare="less"> + <double>7.5</double> + </test> + <edit name="hinting"> + <bool>false</bool> + </edit> + </match> + + <!-- + Load per-user customization file + --> + <include ignore_missing="yes">~/.fonts.conf</include> + + <!-- + Load local system customization file + --> + <include ignore_missing="yes">conf.d</include> + <include ignore_missing="yes">local.conf</include> + + <!-- + Load local ubuntu-specific language custom file + --> + <include ignore_missing="yes">language-selector.conf</include> + + <!-- + Provide required aliases for standard names + --> + <alias> + <family>serif</family> + <prefer> + <family>DejaVu Serif</family> + <family>Bitstream Vera Serif</family> + <family>Times New Roman</family> + <family>Thorndale AMT</family> + <family>Luxi Serif</family> + <family>Nimbus Roman No9 L</family> + <family>Times</family> + <family>Frank Ruehl</family> + <family>FreeSerif</family> + <family>MgOpen Canonica</family> + <family>Kochi Mincho</family> + <family>AR PL SungtiL GB</family> + <family>AR PL Mingti2L Big5</family> + <family>ï¼ï¼³ ææ</family> + <family>Baekmuk Batang</family> + </prefer> + </alias> + <alias> + <family>sans-serif</family> + <prefer> + <family>DejaVu Sans</family> + <family>Bitstream Vera Sans</family> + <family>Verdana</family> + <family>Arial</family> + <family>Albany AMT</family> + <family>Luxi Sans</family> + <family>Nimbus Sans L</family> + <family>Helvetica</family> + <family>Nachlieli</family> + <family>FreeSans</family> + <family>MgOpen Moderna</family> + <family>Kochi Gothic</family> + <family>AR PL KaitiM GB</family> + <family>AR PL KaitiM Big5</family> + <family>ï¼ï¼³ ã´ã·ãã¯</family> + <family>Baekmuk Dotum</family> + <family>SimSun</family> + </prefer> + </alias> + <alias> + <family>monospace</family> + <prefer> + <family>DejaVu Sans Mono</family> + <family>Bitstream Vera Sans Mono</family> + <family>Andale Mono</family> + <family>Courier New</family> + <family>Cumberland AMT</family> + <family>Luxi Mono</family> + <family>Nimbus Mono L</family> + <family>Courier</family> + <family>Miriam Mono</family> + <family>FreeMono</family> + <family>Kochi Gothic</family> + <family>AR PL KaitiM GB</family> + <family>Baekmuk Dotum</family> + </prefer> + </alias> + + <!-- + Artificial oblique for fonts without an italic or oblique version + --> + + <match target="font"> + <!-- check to see if the font is roman --> + <test name="slant"> + <const>roman</const> + </test> + <!-- check to see if the pattern requested non-roman --> + <test target="pattern" name="slant" compare="not_eq"> + <const>roman</const> + </test> + <!-- multiply the matrix to slant the font --> + <edit name="matrix" mode="assign"> + <times> + <name>matrix</name> + <matrix><double>1</double><double>0.2</double> + <double>0</double><double>1</double> + </matrix> + </times> + </edit> + <!-- pretend the font is oblique now --> + <edit name="slant" mode="assign"> + <const>oblique</const> + </edit> + </match> + + <!-- + Synthetic emboldening for fonts that do not have bold face available + --> + + <match target="font"> + <!-- check to see if the font is just regular --> + <test name="weight" compare="less_eq"> + <int>100</int> + </test> + <!-- check to see if the pattern requests bold --> + <test target="pattern" name="weight" compare="more_eq"> + <int>200</int> + </test> + <!-- set the embolden flag --> + <edit name="embolden" mode="assign"> + <bool>true</bool> + </edit> + </match> + + + <config> + <!-- + These are the default Unicode chars that are expected to be blank + in fonts. All other blank chars are assumed to be broken and + won't appear in the resulting charsets + --> + <blank> + <int>0x0020</int> <!-- SPACE --> + <int>0x00A0</int> <!-- NO-BREAK SPACE --> + <int>0x00AD</int> <!-- SOFT HYPHEN --> + <int>0x034F</int> <!-- COMBINING GRAPHEME JOINER --> + <int>0x0600</int> <!-- ARABIC NUMBER SIGN --> + <int>0x0601</int> <!-- ARABIC SIGN SANAH --> + <int>0x0602</int> <!-- ARABIC FOOTNOTE MARKER --> + <int>0x0603</int> <!-- ARABIC SIGN SAFHA --> + <int>0x06DD</int> <!-- ARABIC END OF AYAH --> + <int>0x070F</int> <!-- SYRIAC ABBREVIATION MARK --> + <int>0x115F</int> <!-- HANGUL CHOSEONG FILLER --> + <int>0x1160</int> <!-- HANGUL JUNGSEONG FILLER --> + <int>0x1680</int> <!-- OGHAM SPACE MARK --> + <int>0x17B4</int> <!-- KHMER VOWEL INHERENT AQ --> + <int>0x17B5</int> <!-- KHMER VOWEL INHERENT AA --> + <int>0x180E</int> <!-- MONGOLIAN VOWEL SEPARATOR --> + <int>0x2000</int> <!-- EN QUAD --> + <int>0x2001</int> <!-- EM QUAD --> + <int>0x2002</int> <!-- EN SPACE --> + <int>0x2003</int> <!-- EM SPACE --> + <int>0x2004</int> <!-- THREE-PER-EM SPACE --> + <int>0x2005</int> <!-- FOUR-PER-EM SPACE --> + <int>0x2006</int> <!-- SIX-PER-EM SPACE --> + <int>0x2007</int> <!-- FIGURE SPACE --> + <int>0x2008</int> <!-- PUNCTUATION SPACE --> + <int>0x2009</int> <!-- THIN SPACE --> + <int>0x200A</int> <!-- HAIR SPACE --> + <int>0x200B</int> <!-- ZERO WIDTH SPACE --> + <int>0x200C</int> <!-- ZERO WIDTH NON-JOINER --> + <int>0x200D</int> <!-- ZERO WIDTH JOINER --> + <int>0x200E</int> <!-- LEFT-TO-RIGHT MARK --> + <int>0x200F</int> <!-- RIGHT-TO-LEFT MARK --> + <int>0x2028</int> <!-- LINE SEPARATOR --> + <int>0x2029</int> <!-- PARAGRAPH SEPARATOR --> + <int>0x202A</int> <!-- LEFT-TO-RIGHT EMBEDDING --> + <int>0x202B</int> <!-- RIGHT-TO-LEFT EMBEDDING --> + <int>0x202C</int> <!-- POP DIRECTIONAL FORMATTING --> + <int>0x202D</int> <!-- LEFT-TO-RIGHT OVERRIDE --> + <int>0x202E</int> <!-- RIGHT-TO-LEFT OVERRIDE --> + <int>0x202F</int> <!-- NARROW NO-BREAK SPACE --> + <int>0x205F</int> <!-- MEDIUM MATHEMATICAL SPACE --> + <int>0x2060</int> <!-- WORD JOINER --> + <int>0x2061</int> <!-- FUNCTION APPLICATION --> + <int>0x2062</int> <!-- INVISIBLE TIMES --> + <int>0x2063</int> <!-- INVISIBLE SEPARATOR --> + <int>0x206A</int> <!-- INHIBIT SYMMETRIC SWAPPING --> + <int>0x206B</int> <!-- ACTIVATE SYMMETRIC SWAPPING --> + <int>0x206C</int> <!-- INHIBIT ARABIC FORM SHAPING --> + <int>0x206D</int> <!-- ACTIVATE ARABIC FORM SHAPING --> + <int>0x206E</int> <!-- NATIONAL DIGIT SHAPES --> + <int>0x206F</int> <!-- NOMINAL DIGIT SHAPES --> + <int>0x3000</int> <!-- IDEOGRAPHIC SPACE --> + <int>0x3164</int> <!-- HANGUL FILLER --> + <int>0xFEFF</int> <!-- ZERO WIDTH NO-BREAK SPACE --> + <int>0xFFA0</int> <!-- HALFWIDTH HANGUL FILLER --> + <int>0xFFF9</int> <!-- INTERLINEAR ANNOTATION ANCHOR --> + <int>0xFFFA</int> <!-- INTERLINEAR ANNOTATION SEPARATOR --> + <int>0xFFFB</int> <!-- INTERLINEAR ANNOTATION TERMINATOR --> + </blank> + <!-- + Rescan configuration every 30 seconds when FcFontSetList is called + --> + <rescan> + <int>30</int> + </rescan> + </config> + + </fontconfig> + +### SUSE Linux 10.1 (extracted from fontconfig package) + +This file was extracted from the SUSE Linux 10.1 installation package, fontconfig-2.3.94-17.i586.rpm. We are not aware if other packages alter the installed /etc/fonts/fonts.conf file so that the actual installation is different. + + + <?xml version="1.0"?> + <!DOCTYPE fontconfig SYSTEM "fonts.dtd"> + <!-- /etc/fonts/fonts.conf file to configure system font access --> + <fontconfig> + + <!-- + DO NOT EDIT THIS FILE. + IT WILL BE REPLACED WHEN FONTCONFIG IS UPDATED. + LOCAL CHANGES BELONG IN 'local.conf'. + + The intent of this standard configuration file is to be adequate for + most environments. If you have a reasonably normal environment and + have found problems with this configuration, they are probably + things that others will also want fixed. Please submit any + problems to the fontconfig bugzilla system located at fontconfig.org + + Note that the normal 'make install' procedure for fontconfig is to + replace any existing fonts.conf file with the new version. Place + any local customizations in local.conf which this file references. + + Keith Packard + --> + + <!-- Font directory list --> + + <dir>/usr/share/fonts</dir> + <dir>/usr/X11R6/lib/X11/fonts</dir> <dir>/opt/kde3/share/fonts</dir> <dir>/usr/local/share/fonts</dir> + <dir>~/.fonts</dir> + <dir>~/.fonts/kde-override</dir> + + <include ignore_missing="yes">suse-font-dirs.conf</include> + + <!-- + Accept deprecated 'mono' alias, replacing it with 'monospace' + --> + <match target="pattern"> + <test qual="any" name="family"> + <string>mono</string> + </test> + <edit name="family" mode="assign"> + <string>monospace</string> + </edit> + </match> + + <!-- + Accept alternate 'sans serif' spelling, replacing it with 'sans-serif' + --> + <match target="pattern"> + <test qual="any" name="family"> + <string>sans serif</string> + </test> + <edit name="family" mode="assign"> + <string>sans-serif</string> + </edit> + </match> + + <!-- + Accept deprecated 'sans' alias, replacing it with 'sans-serif' + --> + <match target="pattern"> + <test qual="any" name="family"> + <string>sans</string> + </test> + <edit name="family" mode="assign"> + <string>sans-serif</string> + </edit> + </match> + + <!-- + Mark common families with their generics so we'll get + something reasonable + --> + + <include ignore_missing="yes">suse-generic-names.conf</include> + + <!-- + Serif faces + --> + <alias> + <family>Bitstream Vera Serif</family> + <family>Times New Roman</family> + <family>Thorndale AMT</family> + <family>Times</family> + <family>Nimbus Roman No9 L</family> + <family>Luxi Serif</family> + <family>Kochi Mincho</family> + <family>AR PL SungtiL GB</family> + <family>AR PL Mingti2L Big5</family> + <family>ï¼ï¼³ ææ</family> + <family>SimSun</family> + <family>Baekmuk Batang</family> + <family>FreeSerif</family> + <family>MgOpen Canonica</family> + <default><family>serif</family></default> + </alias> + <!-- + Sans-serif faces + --> + <alias> + <family>Bitstream Vera Sans</family> + <family>Helvetica</family> + <family>Arial</family> + <family>Verdana</family> + <family>Albany AMT</family> + <family>Nimbus Sans L</family> + <family>Luxi Sans</family> + <family>Kochi Gothic</family> + <family>AR PL KaitiM GB</family> + <family>AR PL KaitiM Big5</family> + <family>ï¼ï¼³ ã´ã·ãã¯</family> + <family>Baekmuk Dotum</family> + <family>FreeSans</family> + <family>MgOpen Modata</family> + <default><family>sans-serif</family></default> + </alias> + <!-- + Monospace faces + --> + <alias> + <family>Bitstream Vera Sans Mono</family> + <family>Courier</family> + <family>Courier New</family> + <family>Andale Mono</family> + <family>Luxi Mono</family> + <family>Cumberland AMT</family> + <family>Nimbus Mono L</family> + <family>NSimSun</family> + <family>FreeMono</family> + <default><family>monospace</family></default> + </alias> + <!-- + If the font still has no generic name, add sans-serif + --> + <match target="pattern"> + <test qual="all" name="family" compare="not_eq"> + <string>sans-serif</string> + </test> + <test qual="all" name="family" compare="not_eq"> + <string>serif</string> + </test> + <test qual="all" name="family" compare="not_eq"> + <string>monospace</string> + </test> + <edit name="family" mode="append_last"> + <string>sans-serif</string> + </edit> + </match> + + <!-- + URW provides metric and shape compatible fonts for these 3 Adobe families. + --> + <alias> + <family>Times</family> + <accept><family>Nimbus Roman No9 L</family></accept> + </alias> + <alias> + <family>Helvetica</family> + <accept><family>Nimbus Sans L</family></accept> + </alias> + <alias> + <family>Courier</family> + <accept><family>Nimbus Mono L</family></accept> + </alias> + + <!-- + AMT provides metric and shape compatible fonts for these three web font + families. + --> + <alias> + <family>Times New Roman</family> + <accept><family>Thorndale AMT</family></accept> + </alias> + <alias> + <family>Arial</family> + <accept><family>Albany AMT</family></accept> + </alias> + <alias> + <family>Courier New</family> + <accept><family>Cumberland AMT</family></accept> + </alias> + + <!-- + Some Asian fonts misadvertise themselves as monospaced when + in fact they are dual-spaced (half and full). This makes + FreeType very confused as it forces all widths to match. + Undo this magic by disabling the width forcing code --> + <match target="font"> + <test name="family"><string>GulimChe</string></test> + <edit name="globaladvance"><bool>false</bool></edit> + </match> + + <match target="font"> + <test name="family"><string>DotumChe</string></test> + <edit name="globaladvance"><bool>false</bool></edit> + </match> + + <match target="font"> + <test name="family"><string>BatangChe</string></test> + <edit name="globaladvance"><bool>false</bool></edit> + </match> + + <match target="font"> + <test name="family"><string>GungsuhChe</string></test> + <edit name="globaladvance"><bool>false</bool></edit> + </match> + + <!-- + The Bitstream Vera fonts have GASP entries suggesting that hinting be + disabled below 8 ppem, but FreeType ignores those, preferring to use + the data found in the instructed hints. The initial Vera release + didn't include the right instructions in the 'prep' table. Fix this + by disabling hinting manually at smaller sizes (< 8ppem) + --> + + <match target="font"> + <test name="family"> + <string>Bitstream Vera Sans</string> + </test> + <test name="pixelsize" compare="less"> + <double>7.5</double> + </test> + <edit name="hinting"> + <bool>false</bool> + </edit> + </match> + + <match target="font"> + <test name="family"> + <string>Bitstream Vera Serif</string> + </test> + <test name="pixelsize" compare="less"> + <double>7.5</double> + </test> + <edit name="hinting"> + <bool>false</bool> + </edit> + </match> + + <match target="font"> + <test name="family"> + <string>Bitstream Vera Sans Mono</string> + </test> + <test name="pixelsize" compare="less"> + <double>7.5</double> + </test> + <edit name="hinting"> + <bool>false</bool> + </edit> + </match> + + <!-- + Load pre-user SuSE specific customizations: + --> + + <include ignore_missing="yes">suse-pre-user.conf</include> + + <!-- + Load per-user customization file + --> + <include ignore_missing="yes">~/.fonts.conf</include> + + <!-- + Load post-user SuSE specific customizations: + --> + + <include ignore_missing="yes">suse-post-user.conf</include> + + <!-- + Load local system customization file + --> + <include ignore_missing="yes">conf.d</include> + <include ignore_missing="yes">local.conf</include> + + <!-- + Provide required aliases for standard names + --> + <alias> + <family>serif</family> + <prefer> + <family>Bitstream Vera Serif</family> + <family>Times New Roman</family> + <family>Thorndale AMT</family> + <family>Luxi Serif</family> + <family>Nimbus Roman No9 L</family> + <family>Times</family> + <family>Frank Ruehl</family> + <family>MgOpen Canonica</family> + <family>FreeSerif</family> + <family>Kochi Mincho</family> + <family>AR PL SungtiL GB</family> + <family>SimSun</family> + <family>AR PL Mingti2L Big5</family> + <family>ï¼ï¼³ ææ</family> + <family>Baekmuk Batang</family> + </prefer> + </alias> + <alias> + <family>sans-serif</family> + <prefer> + <family>Bitstream Vera Sans</family> + <family>Verdana</family> + <family>Arial</family> + <family>Albany AMT</family> + <family>Luxi Sans</family> + <family>Nimbus Sans L</family> + <family>Helvetica</family> + <family>Nachlieli</family> + <family>MgOpen Modata</family> + <family>FreeSans</family> + <family>Kochi Gothic</family> + <family>AR PL KaitiM GB</family> + <family>AR PL KaitiM Big5</family> + <family>ï¼ï¼³ ã´ã·ãã¯</family> + <family>Baekmuk Dotum</family> + </prefer> + </alias> + <alias> + <family>monospace</family> + <prefer> + <family>Bitstream Vera Sans Mono</family> + <family>Andale Mono</family> + <family>Courier New</family> + <family>Cumberland AMT</family> + <family>Luxi Mono</family> + <family>Nimbus Mono L</family> + <family>Courier</family> + <family>Miriam Mono</family> + <family>FreeMono</family> + <family>Kochi Gothic</family> + <family>AR PL SungtiL GB</family> + <family>AR PL Mingti2L Big5</family> + <family>Baekmuk Dotum</family> + </prefer> + </alias> + + <!-- + Artificial oblique for fonts without an italic or oblique version + --> + + <match target="font"> + <!-- check to see if the font is roman --> + <test name="slant"> + <const>roman</const> + </test> + <!-- check to see if the pattern requested non-roman --> + <test target="pattern" name="slant" compare="not_eq"> + <const>roman</const> + </test> + <!-- multiply the matrix to slant the font --> + <edit name="matrix" mode="assign"> + <times> + <name>matrix</name> + <matrix><double>1</double><double>0.2</double> + <double>0</double><double>1</double> + </matrix> + </times> + </edit> + <!-- pretend the font is oblique now --> + <edit name="slant" mode="assign"> + <const>oblique</const> + </edit> + <!-- and disable embedded bitmaps for artificial oblique --> + <edit name="embeddedbitmap" mode="assign"> + <bool>false</bool> + </edit> + </match> + + <!-- + Synthetic emboldening for fonts that do not have bold face available + --> + + <match target="font"> + <!-- check to see if the font is just regular --> + <test name="weight" compare="less_eq"> + <const>medium</const> + </test> + <!-- check to see if the pattern requests bold --> + <test target="pattern" name="weight" compare="more"> + <const>medium</const> + </test> + <!-- + set the embolden flag + needed for applications using cairo, e.g. gucharmap, gedit, ... + --> + <edit name="embolden" mode="assign"> + <bool>true</bool> + </edit> + <!-- + set weight to bold + needed for applications using Xft directly, e.g. Firefox, ... + --> + <edit name="weight" mode="assign"> + <const>bold</const> + </edit> + <!-- + Hinting will be done before Embolden in freetype2, + but in such case, Embolden will get wrong result + on some glyph contours after applying hinting. + Actually, hinting should be done after embolden, but we can't + fix it in current freetype2. So as a workaround, just turn off + hinting if we want to do embolden. + --> + <edit name="hintstyle" mode="assign"> + <const>hintnone</const> + </edit> + </match> + + + <config> + <!-- + These are the default Unicode chars that are expected to be blank + in fonts. All other blank chars are assumed to be broken and + won't appear in the resulting charsets + --> + <blank> + <int>0x0020</int> <!-- SPACE --> + <int>0x00A0</int> <!-- NO-BREAK SPACE --> + <int>0x00AD</int> <!-- SOFT HYPHEN --> + <int>0x034F</int> <!-- COMBINING GRAPHEME JOINER --> + <int>0x0600</int> <!-- ARABIC NUMBER SIGN --> + <int>0x0601</int> <!-- ARABIC SIGN SANAH --> + <int>0x0602</int> <!-- ARABIC FOOTNOTE MARKER --> + <int>0x0603</int> <!-- ARABIC SIGN SAFHA --> + <int>0x06DD</int> <!-- ARABIC END OF AYAH --> + <int>0x070F</int> <!-- SYRIAC ABBREVIATION MARK --> + <int>0x115F</int> <!-- HANGUL CHOSEONG FILLER --> + <int>0x1160</int> <!-- HANGUL JUNGSEONG FILLER --> + <int>0x1680</int> <!-- OGHAM SPACE MARK --> + <int>0x17B4</int> <!-- KHMER VOWEL INHERENT AQ --> + <int>0x17B5</int> <!-- KHMER VOWEL INHERENT AA --> + <int>0x180E</int> <!-- MONGOLIAN VOWEL SEPARATOR --> + <int>0x2000</int> <!-- EN QUAD --> + <int>0x2001</int> <!-- EM QUAD --> + <int>0x2002</int> <!-- EN SPACE --> + <int>0x2003</int> <!-- EM SPACE --> + <int>0x2004</int> <!-- THREE-PER-EM SPACE --> + <int>0x2005</int> <!-- FOUR-PER-EM SPACE --> + <int>0x2006</int> <!-- SIX-PER-EM SPACE --> + <int>0x2007</int> <!-- FIGURE SPACE --> + <int>0x2008</int> <!-- PUNCTUATION SPACE --> + <int>0x2009</int> <!-- THIN SPACE --> + <int>0x200A</int> <!-- HAIR SPACE --> + <int>0x200B</int> <!-- ZERO WIDTH SPACE --> + <int>0x200C</int> <!-- ZERO WIDTH NON-JOINER --> + <int>0x200D</int> <!-- ZERO WIDTH JOINER --> + <int>0x200E</int> <!-- LEFT-TO-RIGHT MARK --> + <int>0x200F</int> <!-- RIGHT-TO-LEFT MARK --> + <int>0x2028</int> <!-- LINE SEPARATOR --> + <int>0x2029</int> <!-- PARAGRAPH SEPARATOR --> + <int>0x202A</int> <!-- LEFT-TO-RIGHT EMBEDDING --> + <int>0x202B</int> <!-- RIGHT-TO-LEFT EMBEDDING --> + <int>0x202C</int> <!-- POP DIRECTIONAL FORMATTING --> + <int>0x202D</int> <!-- LEFT-TO-RIGHT OVERRIDE --> + <int>0x202E</int> <!-- RIGHT-TO-LEFT OVERRIDE --> + <int>0x202F</int> <!-- NARROW NO-BREAK SPACE --> + <int>0x205F</int> <!-- MEDIUM MATHEMATICAL SPACE --> + <int>0x2060</int> <!-- WORD JOINER --> + <int>0x2061</int> <!-- FUNCTION APPLICATION --> + <int>0x2062</int> <!-- INVISIBLE TIMES --> + <int>0x2063</int> <!-- INVISIBLE SEPARATOR --> + <int>0x206A</int> <!-- INHIBIT SYMMETRIC SWAPPING --> + <int>0x206B</int> <!-- ACTIVATE SYMMETRIC SWAPPING --> + <int>0x206C</int> <!-- INHIBIT ARABIC FORM SHAPING --> + <int>0x206D</int> <!-- ACTIVATE ARABIC FORM SHAPING --> + <int>0x206E</int> <!-- NATIONAL DIGIT SHAPES --> + <int>0x206F</int> <!-- NOMINAL DIGIT SHAPES --> + <int>0x3000</int> <!-- IDEOGRAPHIC SPACE --> + <int>0x3164</int> <!-- HANGUL FILLER --> + <int>0xFEFF</int> <!-- ZERO WIDTH NO-BREAK SPACE --> + <int>0xFFA0</int> <!-- HALFWIDTH HANGUL FILLER --> + <int>0xFFF9</int> <!-- INTERLINEAR ANNOTATION ANCHOR --> + <int>0xFFFA</int> <!-- INTERLINEAR ANNOTATION SEPARATOR --> + <int>0xFFFB</int> <!-- INTERLINEAR ANNOTATION TERMINATOR --> + </blank> + <!-- + Rescan configuration every 30 seconds when FcFontSetList is called + --> + <rescan> + <int>30</int> + </rescan> + </config> + + </fontconfig> diff --git a/Software/FreeType.mdwn b/Software/FreeType.mdwn new file mode 100644 index 00000000..6b5afa00 --- /dev/null +++ b/Software/FreeType.mdwn @@ -0,0 +1,4 @@ + +[[FreeType|http://freetype.org]] is an open-source library for accessing font files and rasterizing glyphs. + +-- Main.[[KeithPackard|KeithPackard]] - 22 Sep 2003 diff --git a/Software/GeoClue.mdwn b/Software/GeoClue.mdwn new file mode 100644 index 00000000..e94b8ec8 --- /dev/null +++ b/Software/GeoClue.mdwn @@ -0,0 +1,153 @@ +[[!table header="no" class="mointable" data=""" + [[!img http://folks.o-hand.com/jku/geoclue-docs/geoclue-small.jpg] + [[!toc ]] +"""]] + + +# GeoClue: The Geoinformation Service + +Geoclue is a modular geoinformation service built on top of the [[D-Bus|http://dbus.freedesktop.org]] messaging system. The goal of the Geoclue project is to make creating location-aware applications as simple as possible. + +Geoclue is Free Software, licensed under [[GNU LGPL|http://www.fsf.org/licensing/licenses/lgpl.html]]. It is developed for Linux, but should be portable to any platform that uses D-Bus. + +Geoclue defines a set of geoinformation APIs, but it also includes some _providers_ that implement those APIs. Here is a list of services provided through Geoclue with the currently included implementations: +Position +: gpsd, gypsy, hostip, plazes, gsmloc + +Address +: hostip, plazes, manual, localnet + +Velocity +: gpsd, gypsy + +Geocode +: nominatim, geonames, yahoo + +ReverseGeocode +: nominatim, geonames + + +Geoclue source code contains: + +* D-Bus definitions for the above APIs +* C bindings for Geoclue clients +* C bindings for data providers +* a set of provider implementations +* (experimental) master provider implementation. + +# Discuss & contribute + +* Discuss on [[mailing list|http://lists.freedesktop.org/mailman/listinfo/geoclue]] +* Chat on `#geoclue` on `irc.gimp.org` +* Bugs are handled in freedesktop.org Bugzilla + * [[File a bug|http://bugs.freedesktop.org/enter_bug.cgi?product=GeoClue]] + * [[see open bugs|http://bugs.freedesktop.org/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&short_desc=&product=GeoClue&long_desc_type=allwordssubstr&long_desc=&bug_file_loc_type=allwordssubstr&bug_file_loc=&status_whiteboard_type=allwordssubstr&status_whiteboard=&keywords_type=allwords&keywords=&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&emailtype1=substring&email1=&emailtype2=substring&email2=&bugidtype=include&bug_id=&chfieldfrom=&chfieldto=Now&chfieldvalue=&cmdtype=doit&order=Reuse+same+sort+as+last+time&field0-0-0=noop&type0-0-0=noop&value0-0-0=]] + * [[Get notified|https://bugs.freedesktop.org/userprefs.cgi?tab=email]] of new Geoclue bugs (add `geoclue-bugs@freedesktop.org` to your watchlist) + +# Learn more + +The [[documentation|http://folks.o-hand.com/jku/geoclue-docs]] includes + +* D-Bus API Interface reference (not finished) +* Client C API reference +* Examples on how to use geoclue in an application +The documentation source also contains documentation on provider API and writing providers, but these are not finished. + +Below is a higher level description of Geoclue interfaces, providers and master provider. + + +## Interfaces + +Geoclue has three interfaces for querying "current situation": _Position_, _Address_ and _Velocity_. They all include a method and a signal to acquire the information in question along with the time and accuracy of the measurement. + +There are also interfaces Geocode (for getting a Position from an Address) and [[ReverseGeocode|ReverseGeocode]] (for getting an Address from a Position). + +Possible future interfaces include _Map_ and _Route_. + + +## Providers + +All Geoclue providers are D-Bus services, and can be accessed either via "raw" D-Bus or the C API. A provider may implement more than one Geoclue interface if that makes sense internally. Providers do not have to run as daemons, as D-Bus will start them when needed (providers may also shut down when they're no longer used). + +There are several reasons for this structure: + +* No single provider will be useful in all situations (GPS does not work indoors, webservices require an internet connection, GSM cell positioning accuracy is not too good, etc.) +* No single set of providers will be best for all people. +* Modularity means that anyone can develop and distribute a provider: Adding new providers requires no changes to Geoclue master. In fact a single geoclue provider is fully self-contained (although libgeoclue will make life easier for clients) +* It also means a master provider (see below) can use all installed providers, not just the ones that were installed with the master. +Providers must naturally implement the methods in the interfaces they support. However, not all providers support signals: E.g. web service based providers usually do not. A client accessing providers directly should be aware of this. + +See also [[list of current provider and their features|http://www.freedesktop.org/wiki/Software/GeoClue/Providers]]. + + +## Master provider + +Geoclue includes a master provider, which implements the same interfaces and is used in the same manner as any other provider. The difference is that internally master uses the best Geoclue provider (based on client requirements and provider availability, accuracy and resource requirements). The provider that is actually used may change over time as conditions change, but the client can just ignore this. + +Using the Master provider is favourable for several reasons: + +* Client does not need to know about the accuracy and availability of a specific data source +* Client does not need to depend on specific providers +* Master caches data so responses will usually be faster +* Master understands network connectivity and basically makes all web service based providers "support signals" +The master implementation is currently experimental. + + +# Get the source + +The code is licensed under the [[GNU LGPL|http://www.fsf.org/licensing/licenses/lgpl.html]] and is available as a tar-ball and in a Git repository. You can also [[browse the source|http://cgit.freedesktop.org/geoclue]]. + +Latest release: [[Geoclue 0.12.99|http://freedesktop.org/~hadess/geoclue-0.12.99.tar.gz]] + +Git repository: + +* [[!format txt """ +git clone git://anongit.freedesktop.org/git/geoclue +"""]] +For help with Git, see [[Usage notes|Infrastructure/git]] here on freedesktop.org and documentation on [[Git homepage|http://git.or.cz/gitwiki/GitDocumentation]]. + +The included providers and the C bindings depend on GLib, GObject and Libxml. + + +# Getting started + +There is a nice [[UI|http://blog.pierlux.com/index.html%3Fp=1122.html]] to see available providers and configure some of them. One can e.g. configure the "manual" provider with a static address. You can get the code [[here|http://git.gnome.org/browse/geoclue-properties/]]. + +Also check out the Python API that [[python-geoclue|https://live.gnome.org/gtg/soc/python_geoclue]] provides. + + +# Miscellany + + +## History + +Geoclue got started during GNOME Summit 2006 in Boston. At least Keith Preston and Tuomas Kuosmanen can be blamed. + +There was a total rewrite after version 0.9. Use tag "0.9" (as in `git checkout 0.9`) if you need the old code. A copy of the Geoclue wiki page from that time is preserved [[here|http://www.freedesktop.org/wiki/Software/GeoClue?action=recall&rev=32]]. + + +## Application ideas + +* F-Spot / GThumb: tag photos with location data +* Stars / [[MaemoStars|MaemoStars]]: show night sky simulation in correct place +* Map applications ([[MaemoMapper|MaemoMapper]]) show correct location on application open +* Jabber / Telepathy: support [[XEP-0080|http://www.xmpp.org/extensions/xep-0080.html]], add location info to Presence +* Blog software: add geotags to posts +* Yahoo Fire Eagle could use Geoclue as data provider +* Use position/address for desktop settings (timezone, printers, SMTP servers, whatever). [[Marco Polo|http://www.symonds.id.au/marcopolo/]] looks like a good implementation on OS X +* disable-screensaver-lock-when-at-home +* Find closest free wifi access point +* Tracking application (save location history). Could be used later for tagging photos etc. +* browser, calendar: autofill address form fields (not sure if current location is wanted that often, though?) +* Browser could expose location to websites: Webkit may support [[Locationaware|http://locationaware.org/]] in the future. +* [[Google Gears|http://code.google.com/p/google-gears/wiki/LocationAPI]] + +## Possible data sources + +* Geocoding for phone numbers - use countries telephone number dial plans to convert phone numbers to general locations (obviously less accuracy with mobiles and world-wide roaming/etc) +* [[Google Maps Geocoding API|http://www.google.com/apis/maps/documentation/#Geocoding_Examples]] -- License says "only for showing places on Google Maps" +* [[Wigle.net|http://www.wigle.net/]]-- WIFI location database (10 million networks). License requires users to login. +* [[geocoder.us|http://geocoder.us]] -- geocoder for the USA (TIGER data) +* gsmloc-provider could easily get the GSM information using AT commands on the [[OpenMoko|OpenMoko]] platform +* We _really_ should have a free network location database (like gsmloc.org, but for WLAN, GSM, BT, ethernet gateway, .. + * A free network location database project has begun at [[http://geomena.org|http://geomena.org]]
\ No newline at end of file diff --git a/Software/GeoClue/Providers.mdwn b/Software/GeoClue/Providers.mdwn new file mode 100644 index 00000000..70d7e444 --- /dev/null +++ b/Software/GeoClue/Providers.mdwn @@ -0,0 +1,135 @@ +[[!table header="no" class="mointable" data=""" + | [[!toc ]] +"""]] + + +# Geoclue providers listed by interface + + +## Position +[[!table header="no" class="mointable" data=""" +**Provider** | **Accuracy** | **signals** | **Requires** +[[Hostip|Software/GeoClue/Providers]] | 3 (locality) | No¹ | network +[[Plazes|Software/GeoClue/Providers]] | 5 (street) | No¹ | network +[[Gsmloc|Software/GeoClue/Providers]] | 4 (postalcode) | No | network, cell +[[Gpsd|Software/GeoClue/Providers]] | 6 (detailed) | Yes | GPS +[[Gypsy|Software/GeoClue/Providers]] | 6 (detaild) | Yes | GPS +"""]] + +1) these providers do support signals when used through Geoclue Master + + +## Address +[[!table header="no" class="mointable" data=""" +**Provider** | **Accuracy** | **signals** | **Requires** +[[Hostip|Software/GeoClue/Providers]] | 3 (locality) | No¹ | network +[[Plazes|Software/GeoClue/Providers]] | 5 (street) | No¹ | network +[[Localnet|Software/GeoClue/Providers]] | 5 (street) | No¹ | +[[Manual|Software/GeoClue/Providers]] | 5 (street) | Yes | +"""]] + +1) these providers do support signals when used through Geoclue Master + + +## Velocity +[[!table header="no" class="mointable" data=""" +**Provider** | **Accuracy** | **signals** | **Requires** +[[Gpsd|Software/GeoClue/Providers]] | 6 (detailed) | Yes | GPS +[[Gypsy|Software/GeoClue/Providers]] | 6 (detaild) | Yes | GPS +"""]] + + +## Geocode +[[!table header="no" class="mointable" data=""" +**Provider** | **Accuracy** | **Requires** +[[Yahoo|Software/GeoClue/Providers]] | 5 (street) | network +[[Geonames|Software/GeoClue/Providers]] | 4 (postalcode) | network +"""]] + + +## ReverseGeocode +[[!table header="no" class="mointable" data=""" +**Provider** | **Accuracy** | **Requires** +[[Geonames|Software/GeoClue/Providers]] | 4 (postalcode) | network +"""]] + + +# Provider Details + +<a name="Hostip"></a> +## Hostip + +This provider uses [[http://www.hostip.info|http://www.hostip.info]] to get current position and address based on the current public IP address. Dynamic IPs are potentially mis-located, but locations can be edited at the web site. Note that when the website says that a location is "guessed", it is exactly that -- geoclue will not use guessed data. See [[http://api.hostip.info/|http://api.hostip.info/]] for the actual data. + +<a name="Plazes"></a> +## Plazes + +This provider uses [[http://plazes.com|http://plazes.com]] to get current position and address based on current router mac address. New locations (router mac addresses with coordinates and address) can be added by logged in Plazes users. Official Plazes client is unfortunately not available for Linux. For testing purposes one can add a "Plaze" with the web interface and then edit the mac address with curl: + +* [[!format txt """ +curl -u 'PLAZES_USERNAME:PLAZES_PASSWORD' -H 'Accept: application/xml' 'http://plazes.com/presences' -F presence[plaze_id]=PLAZES_ID -F presence[status]='hacking geoclue' -F presence[mac_address]=MAC_ADDRESS +"""]] +<a name="Manual"></a> +## Manual + +This provider exists to let the user specify the current address. The intention is that there "a geoclue panel applet" or any suitable application can provide the UI for this and use the D-Bus interface to update Manual provider address. The interface includes a "valid-for" variable: if it is used, the address will turn invalid after the specified time. + +<a name="Localnet"></a> +## Localnet + +This provider does not strictly speaking require an internet connection, but it does require a connection to a router: it uses the current router mac address and a local keyfile to provide Address data. New addresses can be added through d-Bus. Example: + +* [[!format txt """ +dbus-send --print-reply --type=method_call \ + --dest=org.freedesktop.Geoclue.Providers.Localnet \ + /org/freedesktop/Geoclue/Providers/Localnet \ + org.freedesktop.Geoclue.Localnet.SetAddressFields \ + string: "" string:"Finland" string: "" string:"Helsinki" \ + string: "" string: string:"Solnantie 24" +"""]] +After running the above command, Localnet provider will provide that address every time the same router is used. Localnet is especially useful for often visited places (home,office), since it's super fast and low resource but requires adding the address manually. + +A geoclue control UI (or any application) could use this provider and Manual provider in the same user interface: +[[!format txt """ ++------------------------------+ +| Street: _____________ | +| City: _____________ | +| Country: _____________ | +| | +| [X] Remember this location | +| | +| [OK] | ++------------------------------+ +"""]] +(Checking 'remember' would mean location would get saved with Localnet) + +<a name="Gsmloc"></a> +## Gsmloc + +This provider uses the [[Gammu library|http://www.gammu.org/]] and [[http://opencellid.org/|http://opencellid.org/]] to provide position data. It gets cell identification data (MCC, MNC, LAC, CID) from Gammu and queries a position from opencellid with that data. + +There are a couple of problems with this provider: First, a compatible phone and a working .gammurc file are needed. Second, the database does not have a lot of cell locations. Third, a bluetooth query can take a long time if the phone is actually not available. + +<a name="Gypsy"></a> +## Gypsy + +Gypsy is a gps multiplexing daemon with a D-Bus interface. Gypsy provider requires the option _org.freedesktop.Geoclue.GPSDevice_ to be set. Valid values are GPS bluetooth mac addresses (e.g. _00:02:76:C5:81:BF_) and device names (_/dev/pgps_). For the master provider the gconf key _/apps/geoclue/master/org.freedesktop.Geoclue.GPSDevice_ should be used. + +On systems with D-Bus 1.1.2 or newer Gypsy service autostarts when Geoclue tries to use it. With older D-Buses it needs to be started manually. + +<a name="Gpsd"></a> +## GPSd + +GPSd is a gps daemon that uses TCP sockets for communication. The daemon must be running when the provider starts. + +The provider accepts two options _org.freedesktop.Geoclue.GPSDevice_ and _org.freedesktop.Geoclue.GPSHost_. If these options are not defined, the default GPSd port and localhost will be used. + +<a name="Yahoo"></a> +## Yahoo + +This provider uses the [[Yahoo geocoding web service|http://developer.yahoo.com/maps/rest/V1/geocode.html]] to provide Position data based on given address. + +<a name="Geonames"></a> +## Geonames + +This provider uses the [[Geonames web service|http://www.geonames.org/export/web-services.html]] to provide geocoding/reverse geocoding service. At the moment reverse geocoding is done using _findNearby_ and geocoding is done using _postalCodeSearch_ and _Geonames search_ diff --git a/Software/Glamor.mdwn b/Software/Glamor.mdwn new file mode 100644 index 00000000..1b4a5ee1 --- /dev/null +++ b/Software/Glamor.mdwn @@ -0,0 +1,124 @@ + + +# What is Glamor? + +The glamor module is an open-source 2D graphics common driver for the X Window System as implemented by X.org. It supports a variety of graphics chipsets which have OpenGL/EGL/GBM supports. + +It’s a GL-based rendering acceleration library for X server: + +* It uses GL functions and shader to complete the 2D graphics operations. +* It uses normal texture to represent a drawable pixmap if possible. +* It calls GL functions to render to the texture directly. +It’s somehow hardware independently. And could be a building block of any X server’s DDX driver: + +* Xorg’s DDX driver could leverage glamor-egl package to create an egl context without any native X system.Now the xf86-intel-video driver uses glamor as one of its option. When you build it with --enable-glamor, then it will use glamor as its rendering enginee. +This package can support every platform which has OpenGL and gbm and drm libraries. + + +# Why Glamor? + +Basiclly, the biggest two advantages of Glamor is: + +1. Graphic device has powerful 3D capability. To use 3D function to accelerate 2D rendering is possible and many drivers already do so. OpenGL provides a more convenient and standard interface to leverage GFX device’s 3D power. It would be better to call OpenGL directly rather than manually write 3D pipeline control code for each different GFX device. +1. We have heard of complains about why we need to develop two version drivers for a single graphic device for a long time. One is for mesa’s DRI driver and the other is for 2D DDX driver. One of glamor’s purpose is to eliminate the latter one. + +# How Glamor Works? + +In Xorg, upper layer should always use low level DDX functions to handle rendering and never access a drawable directly. The common logic of the DDX is: setup appropriate 2D or 3D pipeline according to the rendering request and draw and render it directly, which will prepare a serial of hardware dependent command, and then upload the command to the GFX device through DRM interface, and if it failed or the feature is not implemented, DDX will map the drawable to a virtual memory buffer and then use fb functions to draw and render it using software. + +The Glamor has similar logic, but replace the 2D or 3D pipeline setup with GL's pipeline. In most caese, pixmap and window have a normal texture object. When doing the render or draw process, the texture object will be binded to a frame buffer object, so all the subsequent draw and render operations can use GL functions or use the according shader. We do not need to setup pipeline and write the control code for each different GFX device, the GL will handle it. If that GL kind render can not complete because of failure or not support, the Glamor will fallback to software rendering, which will use FB functions and upload it then if needs. This process needs memory copy several times and is relative slower, so the fallback cases should be decrease to the minimum. + +The Glamor now is implemented to be embedded in other DDX driver(By now, just xf86-video-intel support) to complete the draw and render functions. In the feature, Glamor will also be implemented as a seperated DDX driver. + + +# How to Enable Glamor? + +To enable the Glamor, the following steps is needed: + +1. Rebuild the mesa using the parameter: --with-egl-platforms=x11,drm --with-gallium-drivers= --enable-gbm --enable-shared-glapi --enable-glx-tls. +1. Rebuild the xf86-video-intel driver, add parameter --enable-glamor to enable glamor module which is embedded in intel driver. +1. Build and install glamor source. The Glamor source can be get at [[git://anongit.freedesktop.org/git/xorg/driver/glamor|http://cgit.freedesktop.org/xorg/driver/glamor/]] +1. Make sure you have the xorg configure file named glamor.conf at conf/glamor.conf under the directory /usr/share/X11/xorg.conf.d or /etc/X11/xorg.conf.d/. Although make install will try to install that file to the correct directory. But it may failed, as if you are installing the xserver to a local directory, then the "make install" will install glamor.conf to your local directory rather than the two system directories. So you may need to manually copy the file to the system's configuration directory. Otherwise, you will encounter segfault when start the xserver. Here is teh content of the glamor.conf. + * Section "Module" + * Load "dri2" + * Load "glamoregl" + * EndSection + * Section "Device" + * Identifier "intel" + * Driver "intel" + * Option "[[AccelMethod|AccelMethod]]" "glamor" + * [[EndSection|EndSection]] +The reason why we need to load dri2/glamoregl earlier is both glx-xserver and glamor are a dri2 loader. And glx-xserver side has a own glapi/dispatch table implementation which is a subset of the standard mesa's implementation. So if the glx module is loaded earlier than dri2/glamoregl, then we will get an incomplete dispatch table and everything is broken in glamor then. This is also why we need to add --enable-glx-tls parameters when build mesa, as we need to keep mesa align with Xserver's behavious, xserver will enable-glx-tls by default, but mesa will not. + +After yuo finish all the above steps, then you can try to start x with glamor enabled DDX. To make sure it's the glamor running, you can refer to Xorg.0.log, and check that the Glamor is enabled if you can find the log like: _<ins>intel(0): Use GLAMOR acceleration.</ins>_ + + +# ChangeLog + + +## version 0.5 + +Here is the new features in version 0.5: + +1. Support tiling large pixmap to multiple small textures. +1. Enable gradient shader. +1. Optimize glyphs rendering performance +1. Implement first shader to generate trapezoids. +Cairo-demo’s spinner on a large picture(12000x12000) get about 10x improvement, and gradient also get about 2x improvement. Aa10text and rgb10text also get about 2x improvement. + + +### Plan + +1. Fix the coexisting problem with glx for latest xserver. Don’t rely on the module loading sequence. +1. Continue performance tuning: + 1. Implement delay flushing mechanism to avoid tiny drawing operation for each [[DrawElements/DrawArrays|DrawElements/DrawArrays]] call. + 1. Implement atlas for small pixmap. + 1. Optimize trapezoid shader to reduce the overhead for those non-edge pixels. + 1. Optimize trapezoid/gradient shader to merge the mask/source creation and compositing into one shader. + 1. Optimize glamor itself’ overhead. +1. Xv support. + +### Restrication + +Glamor has a restriction with latest xserver. The main issue is that glamor rely on the module loading sequence which is not guaranteed by current xserver. We will fix this issue in next version. If you want to try a full functional xserver with glamor, it’s recommended to use the following xserver version: + +* commit a615b90cab7569fae9d123e4da1d3373c871d84b Author: Keith Packard <[[keithp@keithp.com|mailto:keithp@keithp.com]]> Date: Wed Mar 14 11:32:36 2012 -0700 + * Bump version number to 1.12.99.0 Now that 1.12 has branched, reset the version on master to a development number. + * Signed-off-by: Keith Packard [[keithp@keithp.com|mailto:keithp@keithp.com]] + +## version 0.4 + +Here is the new features in version 0.4: + +1. DRI2 now works well, and texture-from-pixmap also works well. +1. Fully support glx including AIGLX, indirect glx's GL context coexists with glamor's GL context safely. Thanks for Chris Wilson's help to refine this function. +1. Optimize most of the fallback path and avoid whole pixmap downloading/uploading as much as possible. +1. 1BPP picture uploading now will not fallback the whole rendering path. +1. Fully support all color formats for GLES2 port. Thanks for Lipeng's contribution and testing for the GLES2 port on PVR545 platform. And thanks Zhengyu to fix some PVR releated problems. +1. Fixed many of the bugs for cairo-test-suite, now we get almost identical or even better result than UXA. +1. Implemented a fbo/texture cache pool mechanism which will reduce the over head of texture/fbo destruction and creation, and bring overall 15-20% performance imprvoement. On PVR545 platform, we even get about 10x performance improvement with this feature. + +### Plan + +We plan to release next version 0.5 at early of June. And the following major features will be added: + +1. Fully gradient optimization including linear and radial. Actually, the code is already in this release, but as it has some bugs and we disable it currently. Will fix those bug and enable it at next release. +1. Large pixmap support. Currently, mesa only support 8Kx8K texture size, if a pixmap has larger size, we have to store it in main memory and is not efficient. This feature will tile a large pixmap to a texture array. +1. Fully trapezoid optimization. Currently, the trapezoid rendering is not optimized, and it will call pixman to do the rasterization and then call glamor_composite to do the following composition, and then many texture uploading overhead is triggered there. +1. Fine tune the fbo cache mechanism. + +# Source + +Glamor is managed in git. Please See [[http://cgit.freedesktop.org/xorg/driver/glamor/|http://cgit.freedesktop.org/xorg/driver/glamor/]] + +To get at the code, you can run: + +* git clone git://anongit.freedesktop.org/git/xorg/driver/glamor +For general information about using git, visit + +[[http://book.git-scm.com|http://book.git-scm.com/]] + + +# Mailing List + +All Glamor discussion is currently on [[glamor@lists.freedesktop.org|http://lists.freedesktop.org/mailman/listinfo/glamor]]. You can join the mail list at [[http://lists.freedesktop.org/mailman/listinfo/glamor|http://lists.freedesktop.org/mailman/listinfo/glamor]]. If you met any problem with using this driver, please feel free to send email to this list, and I will help you to solve them. diff --git a/Software/HalBuildInstructions.mdwn b/Software/HalBuildInstructions.mdwn new file mode 100644 index 00000000..527f28c0 --- /dev/null +++ b/Software/HalBuildInstructions.mdwn @@ -0,0 +1,19 @@ + +HAL requires the Linux kernel 2.6, D-BUS, glib (this dep will be dropped soon) and a recent version of linux-hotplug and udev. For the GUI application at least python, pygtk and pygnome is required. + + * Install [[D-BUS|http://dbus.freedesktop.org]] + * Install [[udev|http://kernel.org/pub/linux/utils/kernel/hotplug/]] + * Checkout the HAL source from git: + * git clone git://git.freedesktop.org/git/hal + * Configure HAL: `./autogen.sh` + * Make sure that your `PKG''CONFIG''PATH` contains `dbus-1.pc` and `dbus-glib-1.pc` + * Use the same prefix (--prefix) as used for installing D-BUS + * Build HAL: `make` + * Install HAL: `make install` (as root) + * Even if you are going to hack on HAL you need to do `make install` + * (re)start the system messagebus (D-BUS) + * `/etc/init.d/messagebus restart` on some distros + * As root, start the HAL daemon in a separate window: hald. For debugging use option --daemon=no + * You can now run hal-device-manager or lshal + * Make sure `PYTHONPATH` containes the path to dbus.py +Happy hacking! Have a look at the [[TODO|Software/HalTODO]]. Send feedback to [[hal@lists.freedesktop.org|mailto:hal@lists.freedesktop.org]]. diff --git a/Software/HalFAQ.mdwn b/Software/HalFAQ.mdwn new file mode 100644 index 00000000..5af84162 --- /dev/null +++ b/Software/HalFAQ.mdwn @@ -0,0 +1,56 @@ + + +## Frequently Asked Questions about HAL + +Feel free to either update this page or send suggestions to [[[mailto:david@fubar.dk|[mailto:david@fubar.dk]][David]]. Some of the answers are copy/paste from public mailing lists and are not necessarily from myself. + + +### What is the point of HAL? + +To merge information from various sources such that desktop applications can locate and use hardware devices. The point is that the exact set of information to merge varies by device and bus type. In order to do this, we need to define a format for the information, hence the HAL specification. + +We may read some stuff from the hardware itself, then add some info provided by the kernel, then add some metadata from some systemwide files, then add some data that has been obtained by the desktop and stored per-user, then look at some blacklist, and finally we have a complete picture of everything known about that particular device. + +An extra value is that we can do this in an operating system independent way. Stuff like this is important to the major desktop environments. + + +### Isn't this already handled today? Why do we need Yet Another Abstraction Layer? + +Things aren't handled properly today in the sense that there's no UI on it, there's no integration with applications. To add that on the desktop/app level, we first have to have a single API that will work with different kinds of device and on different operating systems. + +One principle to keep in mind is: application code should not know the details of specific devices. If I add a new device model, apps should automatically use it. Ideally, I can even add a new kind of bus and apps can use devices on that bus; e.g. an app doesn't care if a scanner is SCSI or USB. From an OEM standpoint, if I submit a patch to one or a small well-defined set of projects, then my device should get used by all the interesting apps. You may be lumping all user space code together. Remember that the main desktop apps are built on dozens of libraries, all with opaque long-term-frozen ABIs that create additional abstraction layers. + + +### Will HAL slow down access to my hardware? + +No. HAL is simply just a piece of user-space software that maintains a list of device with well-defined properties for each device. In addition, HAL provides space for application defined properties per device. + +HAL is *not* concerned with how to use the hardware, nor is HAL concerned with configuring the hardware. However, HAL can be used in applications that needs the hardware by providing the list of devices and space for storing configuration values. One example is configuration files for display servers. + + +### So what's the point of HAL if it's only a list of devices? + +The fun can begin when (existing) libraries for accessing devices adopts HAL. The simplest use-case would be accessing a camera. The application programmer uses HAL for finding a camera device; he then tosses the HAL device id to the camera library and gets the pictures. In the process the application programmer is not concerned with any hardware specific parts of the device. + +Other future applications of HAL include handling of pluggable storage, network-transparent device access, device ACL's, locking of devices etc. Right now we are working on the basics. + + +### How to mount a specific storage device to a specific mountpoint using fdi files + +Answer welcome ;) + +* This link may help : [[HAL and device management|http://www.mythic-beasts.com/~mark/random/hal/]] -- [[OlivierBerger|OlivierBerger]] + +### How to choose the suspend method/backend ? + +Answer welcome ;) + + +### How to mount a media storage in r/w mode? + +It seems that removable media storage are mounted read only, so you can't remove photos with hal. I know that hal doesn't mount anything but nothing is in /etc/fstab but in /etc/mtab and in /proc/mount I got: + + * /dev/sdd1 /media/disk vfat ro,nosuid,nodev,uid=501,fmask=0022,dmask=0022,codepage=cp437,iocharset=iso8859-1 0 0 +Answer welcome ;) + +-- Main.[[DavidZeuthen|DavidZeuthen]] - 24 Nov 2003 diff --git a/Software/HalTODO.mdwn b/Software/HalTODO.mdwn new file mode 100644 index 00000000..55489590 --- /dev/null +++ b/Software/HalTODO.mdwn @@ -0,0 +1,2 @@ + +Please see the [[TODO file in git|http://cgit.freedesktop.org/hal/tree/doc/TODO]] and send patches and/or comments to the [[hal mailing list|mailto:hal@lists.freedesktop.org]]. diff --git a/Software/HalTraces.mdwn b/Software/HalTraces.mdwn new file mode 100644 index 00000000..05444d01 --- /dev/null +++ b/Software/HalTraces.mdwn @@ -0,0 +1,22 @@ + + +## Background + +This page contains information about how to produce good bug reports against hal. If you're using packages from your operating system, first try using that defect tracking system. If you're convinced this bug is not fixed upstream (looking at the upstream [[ChangeLog|http://cvs.freedesktop.org/hal/hal/ChangeLog?view=markup]] is a good idea) please feel free to send a mail to the [[hal mailing list|mailto:hal@lists.freedesktop.org]] or file a bug in [[Bugzilla|https://bugs.freedesktop.org/enter_bug.cgi?product=hal]]. + +If possible, please try to use a recent version of HAL, preferably from [[git|http://cgit.freedesktop.org/hal/]]. + + +## Key information to include + +Apart from information about what is wrong, a bug report against hal should include + +1. Traces from the hal daemon run as root like this: with hal <= 0.5.4: `hald --daemon=no --verbose=yes`, with hal >= 0.5.5: `hald --daemon=yes --verbose=yes --use-syslog`. Depending on your settings (or you distribution) you should maybe add the option `--retain-privileges`. In you need to hotplug devices, please wait until the line "Device probing is complete" have been printed - that makes it easier to read the output. +1. `/var/log/messages` (or other appropriate syslog file) snippet from around the time when the hal daemon was running (e.g. just before till just after) +1. `lshal` output, if applicable (e.g. if the hal daemon didn't crash) +1. If the bug concerns storage devices and missing fstab entries, the contents of `/etc/fstab` just before the haldaemon ran, just after probing and just after you saw the bug. +1. If the hal daemon crashes please obtain a stack trace - see [[this|http://fedora.linux.duke.edu/wiki/StackTraces]] page on how to do that. +1. Please state your OS, and the version of `hal`, `udev` and `hotplug` and `kernel`. If your OS use `PolicyKit` and/or `ConsoleKit` state also the versions of these packages. +Also use your common sense; there is no need to include a file if it doesn't contain useful information to resolve the bug. + +-- [[DavidZeuthen|DavidZeuthen]] - 05 Sep 2004, -- [[DannyKukawka|DannyKukawka]] - 14 Mar 2008 diff --git a/Software/HarfBuzz.mdwn b/Software/HarfBuzz.mdwn new file mode 100644 index 00000000..34466018 --- /dev/null +++ b/Software/HarfBuzz.mdwn @@ -0,0 +1,60 @@ + + +## HarfBuzz + +[[!img HarfBuzz.png] + +[[HarfBuzz|HarfBuzz]] is an [[OpenType|http://www.microsoft.com/OpenType/OTSpec/]] text shaping engine. There are two [[HarfBuzz|HarfBuzz]] code trees in existence today: + +* The current [[HarfBuzz|HarfBuzz]] tree, also known as harfbuzz-ng, is under active development and is what is used in Firefox, GNOME, recent versions of ChromeOS and Chrome Linux, among other places. The canonical source tree is available [[here|http://cgit.freedesktop.org/harfbuzz/]]. Also available on [[github|https://github.com/behdad/harfbuzz]]. See below for release tarballs. +* The old [[HarfBuzz|HarfBuzz]] tree, derived from [[FreeType|http://freetype.org/]], [[Pango|http://pango.org/]], and [[Qt|http://qt-project.org/]], is available [[here|http://cgit.freedesktop.org/harfbuzz.old/]]. It is not actively developed or maintained, and is buggy. All users are encouraged to switch over to the new [[HarfBuzz|HarfBuzz]]. There are no release tarballs of old [[HarfBuzz|HarfBuzz]] whatsoever. + +### Download + +For tarball releases of the new [[HarfBuzz|HarfBuzz]] codebase, look [[here|http://www.freedesktop.org/software/harfbuzz/release/]]. At the same place you will also find Win32 binary bundles that include libharfbuzz DLL, hb-view.exe, hb-shape.exe, and all dependencies. + +The API is not expected to change incompatibly, but we cannot guarantee that until [[HarfBuzz|HarfBuzz]] 1.0.0 is released. Other than that, we consider it very stable, and the API that comes with _hb.h_ is unlikely to change. API in _hb-ft.h_ and other peripheral headers are more likely to through reviews before 1.0. + +There are no tarball releases of the old [[HarfBuzz|HarfBuzz]] codebase available. If you want to use the old [[HarfBuzz|HarfBuzz]], just import it into your project. And be warned that you are on your own. + +If you are not sure whether Pango or [[HarfBuzz|HarfBuzz]] is right for you, read [[this|http://mces.blogspot.in/2009/11/pango-vs-harfbuzz.html]]. + + +### Building + +On Linux, install the development packages for [[FreeType|FreeType]], Cairo, and GLib. For example, on Ubuntu / Debian, you would do: + + * sudo apt-get install libfreetype6-dev libglib2.0-dev libcairo2-dev +whereas on Fedora, RHEL, CentOS, and other Red Hat based systems you would do: + + * sudo yum install freetype-devel glib2-devel cairo-devel +If you are using a tarball, you can now proceed to running configure and make as with any other standard package. That should leave you with a shared library in src/, and a few utility programs including hb-view and hb-shape under util/. + +If you are bootstraping from git, you need a few more tools before you can run autogen.sh for the first time. Namely, [[pkg-config|http://www.freedesktop.org/wiki/Software/pkg-config]] and ragel [[ragel|http://www.complang.org/ragel/]]. Again, on Ubuntu / Debian: + + * sudo apt-get install pkg-config ragel sudo apt-get install autoconf automake libtool sudo apt-get install gcc g++ +and on Fedora, RHEL, CentOS: + + * sudo yum install pkgconfig ragel sudo yum install autoconf automake libtool sudo yum install gcc gcc-c++ + +### Development + +To get a better idea of where [[HarfBuzz|HarfBuzz]] stands in the text rendering stack you may want to read [[State of Text Rendering|http://behdad.org/text/]]. + +Both development and user support discussion around [[HarfBuzz|HarfBuzz]] happens on the [[harfbuzz at lists freedesktop org|http://freedesktop.org/mailman/listinfo/harfbuzz/]] mailing list. Some of the developers frequent the #harfbuzz channel on freenode IRC server. If you write to the mailing list, you are guaranteed to get an answer. The same is not necessarily true about the IRC channel, or if you write to individual developers. Feel free to write to the list to tell us how you are using [[HarfBuzz|HarfBuzz]], or how well it has been suiting your project's needs. + +To report bugs or submit patches, you can either use [[bugzilla|https://bugs.freedesktop.org/enter_bug.cgi?product=HarfBuzz]], or the mailing list. Bugzilla is preferred, since we can track the issue until it has been fixed. + +For a comparison of old vs new [[HarfBuzz|HarfBuzz]] memory consumption see [[this|http://goo.gl/woyty]]. + +See past and upcoming [[HarfBuzz Hackfests|Software/HarfBuzz/Hackfests]] + +You can monitor various aspects of the project using the following online services: + + * The code is replicated on [[GitHub|https://github.com/behdad/harfbuzz]]; pull requests are responded to, + * With each commit, all tests are run on [[Travis CI|https://travis-ci.org/behdad/harfbuzz/builds]], + * Public API / ABI changes are tracked across releases on [[Upstream Tracker|http://upstream-tracker.org/versions/harfbuzz.html]], + +#### ICU LayoutEngine + +If your application uses ICU [[LayoutEngine|LayoutEngine]] library, there is a replacement library called _icu-le-hb_ [[here|https://github.com/behdad/icu-le-hb]] that uses [[HarfBuzz|HarfBuzz]] to provide the ICU [[LayoutEngine|LayoutEngine]] API. The C++ API is not ABI compatible, but the C API is. This library has not been tested seriously. If you use it, please report your experience to the mailing list. diff --git a/Software/HarfBuzz/Hackfests.mdwn b/Software/HarfBuzz/Hackfests.mdwn new file mode 100644 index 00000000..836fcfd1 --- /dev/null +++ b/Software/HarfBuzz/Hackfests.mdwn @@ -0,0 +1,13 @@ + + +## HarfBuzz Hackfests + +Major [[HarfBuzz|HarfBuzz]] development, specially the South / South-East Asian shaper, has happened in [[HarfBuzz Hackfests|Software/HarfBuzz/Hackfests]], intense week-long pair-programming hackathons between [[BehdadEsfahbod|BehdadEsfahbod]] and [[JonathanKew|JonathanKew]]. We have found that these quarterly events are a very productive way to develop [[HarfBuzz|HarfBuzz]], and as such looking to continue them. Here's a timeline: + +* **Ngapi [[HarfBuzz|HarfBuzz]] Hackfest** February 2013, Google London / Mozilla London. Implemented Win8-style Myanmar shaping, and Tai Tham, Cham, and New Tai Lue shaping, and fixed various bugs. Read full [[report|http://lists.freedesktop.org/archives/harfbuzz/2013-February/002952.html]], +* **[[HarfBuzz|HarfBuzz]] "All-You-Can-Eat-Sushi" Hackfest** November 2012, Mozilla Vancouver. Mostly fixed shaping with tricky / old / broken fonts for Sinhala, Khmer, and Thai, and started introspection APIs, +* **Lemongrass [[HarfBuzz|HarfBuzz]] Hackfest** July 2012, Mozilla Toronto. Further streamlines support for main Indic scripts and moved east-ward, adding support for Khmer. Read full [[report|http://lists.freedesktop.org/archives/harfbuzz/2012-July/002199.html]], +* **[[HarfBuzz|HarfBuzz]] Massala Hackfest** May 2012, Google Zurich. Serious work on the Indic shaper was started and a major milestone reached by the end of the week. Read full [[report|http://lists.freedesktop.org/archives/harfbuzz/2012-May/001988.html]], +* May 2010, Reading, UK, +* October 2009, Mozilla Toronto. Read full [[report|http://mces.blogspot.ca/2009/11/harfbuzz-hackfest.html]], +Before these hackfests, there were other gatherings under the umbrella of [[TextLayout|TextLayout]] summits. diff --git a/Software/HarfBuzz/HarfBuzz.png b/Software/HarfBuzz/HarfBuzz.png Binary files differnew file mode 100644 index 00000000..d58d9fc5 --- /dev/null +++ b/Software/HarfBuzz/HarfBuzz.png diff --git a/Software/ImmoduleManualInstallation.mdwn b/Software/ImmoduleManualInstallation.mdwn new file mode 100644 index 00000000..7c2a727f --- /dev/null +++ b/Software/ImmoduleManualInstallation.mdwn @@ -0,0 +1,37 @@ +---+Manual Building instructions for Binary Compatible Immodule for Qt Patch + +This page provides information about the binary compatible version of the immodule for Qt patch, meant for inclusion in distribution with major linux distributions. + +Trolltech has notified us that as a matter of policy, they cannot include this patch in a 3.3.x "bugfix" release. However, we hope that distributions will see the immense value of this functionality and choose to incorporate it into their qt packages. + +---++Downloading + +[[Current download location|http://www.kde.gr.jp/~daisuke/immodule''for''qt/patch/]] + +---++Building Patched Qt + +Below shows the process needed to build using this patch. Execute the following commands in the folder that is created after expanding the Qt source archive. + + patch < qt-x11-immodule-bc-qt3.3.2-20040623.diff + + cd include/ + ln -s ../src/kernel/qinputcontext.h qinputcontext.h + ln -s ../src/input/qinputcontextfactory.h qinputcontextfactory.h + ln -s ../src/input/qinputcontextplugin.h qinputcontextplugin.h + cd private/ + ln -s ../../src/input/qinputcontextinterface''p.h qinputcontextinterface''p.h + ln -s ../../src/input/qximinputcontext''p.h qximinputcontext''p.h + + ./configure , make, etc + +---++Building SVN + +After checking out the SVN, please execute the following commands under the folder where the _configure_ script reside:. + + ./make-symlinks.sh + + ./configure , make, etc + +(NOTE: please pass to the configure script the desired parameters, such as multi-thread etc.) + +-- Main.[[LiuCougar]] - 11 Jul 2004 diff --git a/Software/ImmoduleQt4RequirementsDocument.mdwn b/Software/ImmoduleQt4RequirementsDocument.mdwn new file mode 100644 index 00000000..0857984b --- /dev/null +++ b/Software/ImmoduleQt4RequirementsDocument.mdwn @@ -0,0 +1,173 @@ +# A Requirements document for an Input Method Subsystem in Qt4 + +[[!toc 3]] + + +## Intro + +This document outlines a set of functional requirements for an IM system that we would like to see supported in Qt4. Where relevant, this document also points out current design and implementation issues, and suggests some solutions. + + +## User Requirements + +* Input method modules should be configurable and switchable at runtime. +* A user should be able to quickly find an input method for a particular language +* A simple configuration should not require any 'magic' environment variables. Things should 'just work', and yet still be configurable if needed. +* User should be able to perform configuration through a simple GUI + * Automated configuration through script/config file should also be possible +* pre-edit buffer indication should be clear and salient + * the pre-edit string should have some different rendering attributes (such as underline) from its surrounding text + * a candidate window should be displayed next to the current segment of the pre-edit being converted, not just simply at the beginning of the pre-edit buffer +* IM-specific keyboard shortcuts should be accessible, and should not be overriden by the application shortcuts (current GTK2 problem) + +## System Integrator Requirements + +There should be a mechanism to limit the IM systems available. For example, a distributor may wish to limit support to the IIIMF framework. + +The reason for this requirement is that there is no global switching framework for the linux desktop, and different input method systems attempt to provide switching in different ways. For example, IIIMF adds a level of indirection by running a user-privileged IM server. Desktop-level switching is accomplished by creating an applet that communicates directly with the server instance which is unique for each desktop instance. + +A library such as UIM on the other hand, would require an applet to communicate with each application directly to change the current input method. Because there is no trivial way to unify all these switching mechanisms, the distributor may be limited to forcing only one mechanism, by supporting only one input method library. + +In the GTK2 case, this amounts to setting the GTK_DEFAULT_IMMODULE variable as well as disabling the right-click input method selection sub-menu, in order to avoid confusing the user with an inconsistent set of choices. (GTK immodule may support more methods than IIIMF, therefore the menu and a menu provided by an IIIMF only applet may differ) + +Until the situation stabilizes, Qt will need an equivalent mechanism to allow distributors to provide a consistent set of choices across various applications. + + +## API Requirements / Issues + + +### Changes to QIMEvent + +During the experience of actually writing input system modules, we have discovered that the current structure of IMStart, IMCompose, and IMEnd does not map well to many IM's and thus is an easy source for bugs. + +More details later.. + + +### Error handling + +Semantics and API for error handling need to be carefully defined. + + +### Candidate window positioning + +The setMicroFocusHint() type method needs to be well defined and possible extended. Some widgets may like to exert more control over how the candidate window (or any other input method-controlled window) is displayed. + + +### Multiple input contexts and widget to input context mapping + +In many cases, it is useful to have several input context instances within the same application associated to different widgets. Some simple examples: + +* 1 chat applications: In an instant messenger, a user would likely talk to different users in different languages. Switching the IM language back and forth manually every time the user talks to a different person is cumbersome and error-prone. The application should be able to remember which input context for which conversation. +In general, if an application has multiple ``language contexts_, then it is often if not always desireable to have an separate input context associated with each language context. + + +### event handling and key compression + +The interaction between the event handling mechanism and the input method need to be clearly defined. It appears that the simplest method for doing this is to give the input method the option to filter a key event before anything else sees it. The interaction between the input method and Qt's key compression features also needs to be defined. + + +### language identification of input methods + +An application should be able to query the language of each input method. semantics need to be defined for those input methods that can handle multiple languages. + + +### language tagging for inputted text + +With han unification in unicode, it is often required to know the language of a string of characters to be able to choose the right font. The language can be determined from the method, as usually an input method is designed to input for one specific language. It would be useful if QIMEvent could be modified so that along with the text, the language of the text be carried along as well, so the client widget can act accordingly. Another approach is to add a language() query function to the QInputContext so that the "current" language can be identified, and the text recieving widget can handle the information accordingly. + + +### Surrounding text + +It can be extremely useful for some input methods to obtain text that is immediately before or after the current input positions. For example, in Japanese, this feature can be used to recognize particles and auxilary verbs that are right before or after the cursor position, allowing the system to narrow down conjugation choices by applying the appropriate grammatical rules. + + +### Pluggable Popup Context Menu + +This allows input methods to provide integrated direct UI controls in QT's text widgets. + + +### Default Input Method Specification + +qtrc, environment variable, etc. + +QT_IM_SWITCHER idea proposed by YAMAKEN: + + In our current implementation, there is a usability problem. We + can configure default IM plugin using QT''IM''MODULE env var (or + the equivalent in qtrc), but there is no way to control default + IM on QMultiInputContext because it is an ordinary plugin. The + user interface is not useful. + + application <- QT''IM''MODULE="multi" + | + QMultiInputContext + | + QFooInputContext + + + To resolve such problem, we can introduce additional + configuration variable for QMultiInputContext. The Qt itself is + not aware of QT''IM''MODULE''FOR''SWITCHER variable. + + application <- QT''IM''MODULE="multi" + | + QMultiInputContext <- QT''IM''MODULE''FOR''SWITCHER="bar" + | + QBarInputContext + + + Although the problem itself can be resolved as above, + unnecessary confusion is also introduced by the solution. Most + users will configure QT''IM''MODULE to choose their own favorite + IM because they always configure so in GTK+ environment. They + will be confused if the configuration QT''IM''MODULE="bar" makes + IM-switching menu vanish. + + application <- QT''IM''MODULE="bar" + | + QBarInputContext + + + To avoid the confusion, I propose following naming + convention. The name QT''IM''SWITCHER is just a trick for users to + form appropriate mental model. Qt itself is not treat + IM-switchers specially. It is still ordinary IM plugin. + + application <- QT''IM''SWITCHER="multi" (default) + | + QMultiInputContext <- QT''IM''MODULE="bar" + | + QBarInputContext + + + The convention is upward compatible with GTK+. In GTK+, the + equivalent of QMultiInputContext is hardcoded as default and not + replaceable. But IM-switcher should be replaceable as I said + recently, so I propose the new convention. + + application <- gtk''im''multicontext_new() + | + GtkIMMulticontext <- GTK''IM''MODULE="bar" + | + GtkIMBarContext + + + To accomplish the new convention, I've renamed the identifier + name of QMultiInputContext "multi" as "imsw-multi". The "imsw-" + prefix prevents IM-switchers from being listed in popup menu as + input method. All other IM-switcher implementation is also + expected to follow this "imsw-" convention. I think that it + should not be API such as QInputContextPlugin::isIMSwitcher() + because Qt API should be isolated from IM-switcher issues. + + If a system integrator such as RedHat want to make a specific + IM-framework the switcher, the patch offers following + configuration. + + application <- QT''IM''SWITCHER="iiimqcf" + | + IIIMInputContext + | + (IIIMF's own switching framework) + +-- Main.[[KenDeeter]] - 27 Jun 2004 diff --git a/Software/ImmoduleQtDownload.mdwn b/Software/ImmoduleQtDownload.mdwn new file mode 100644 index 00000000..4c1b1e21 --- /dev/null +++ b/Software/ImmoduleQtDownload.mdwn @@ -0,0 +1,68 @@ + + +## Download immodule for Qt + + +### Patches + +See [[difference between the patches|Software/ImmoduleQtPatches]] to recognize what is provided by the patches. + + +#### 'Unified' patches (stable) + + * Stable patch for daily use. But since some APIs and specifications are still altering in development, be careful about version mismatch between the patch and optional plugins. See "Optional immodule plugins" to select proper one. + * [[%ATTACHURL%/qt-x11-immodule-unified-qt3.3.3-20040910.diff.gz][qt-x11-immodule-unified-qt3.3.3-20040910.diff.gz|%ATTACHURL%/qt-x11-immodule-unified-qt3.3.3-20040910.diff.gz][qt-x11-immodule-unified-qt3.3.3-20040910.diff.gz]] + * [[%ATTACHURL%/qt-x11-immodule-unified-qt3.3.3-20040819.diff.gz][qt-x11-immodule-unified-qt3.3.3-20040819.diff.gz|%ATTACHURL%/qt-x11-immodule-unified-qt3.3.3-20040819.diff.gz][qt-x11-immodule-unified-qt3.3.3-20040819.diff.gz]] + * [[%ATTACHURL%/qt-x11-immodule-unified-qt3.3.2-20040814.diff.gz][qt-x11-immodule-unified-qt3.3.2-20040814.diff.gz|%ATTACHURL%/qt-x11-immodule-unified-qt3.3.2-20040814.diff.gz][qt-x11-immodule-unified-qt3.3.2-20040814.diff.gz]] + * [[%ATTACHURL%/qt-x11-immodule-unified-qt3.3.2-20040812.diff.gz][qt-x11-immodule-unified-qt3.3.2-20040812.diff.gz|%ATTACHURL%/qt-x11-immodule-unified-qt3.3.2-20040812.diff.gz][qt-x11-immodule-unified-qt3.3.2-20040812.diff.gz]] + * [[%ATTACHURL%/qt-x11-immodule-unified-qt3.3.2-20040811.diff.gz][qt-x11-immodule-unified-qt3.3.2-20040811.diff.gz|%ATTACHURL%/qt-x11-immodule-unified-qt3.3.2-20040811.diff.gz][qt-x11-immodule-unified-qt3.3.2-20040811.diff.gz]] + +#### Experimental Qt4 patches + + * [[%ATTACHURL%/qt-x11-immodule-qt4.0.0-tp1-20040822.diff.gz][qt-x11-immodule-qt4.0.0-tp1-20040822.diff.gz|%ATTACHURL%/qt-x11-immodule-qt4.0.0-tp1-20040822.diff.gz][qt-x11-immodule-qt4.0.0-tp1-20040822.diff.gz]] + +#### Obsolete patches + + * [[%ATTACHURL%/qt-x11-immodule-bc-qt3.3.2-20040623.diff][qt-x11-immodule-bc-qt3.3.2-20040623.diff|%ATTACHURL%/qt-x11-immodule-bc-qt3.3.2-20040623.diff][qt-x11-immodule-bc-qt3.3.2-20040623.diff]] + * [[%ATTACHURL%/qt-x11-immodule-all-qt3.3.1-20040316.diff][qt-x11-immodule-all-qt3.3.1-20040316.diff|%ATTACHURL%/qt-x11-immodule-all-qt3.3.1-20040316.diff][qt-x11-immodule-all-qt3.3.1-20040316.diff]] + * [[more old patches|http://www.kde.gr.jp/~daisuke/immodule_for_qt/patch/]] + +### Optional immodule plugins + + +#### for qt-x11-immodule-unified-qt3.3.3-20040910 + + * [[scim-qtimm 0.7.5 (r87)|Software/ScimQtImm]] (requires scim-lib >= 0.99.9) + * [[UimQt 0.1.9|Software/UimQt]] (requires uim >= 0.4.3) + +#### for qt-x11-immodule-unified-qt3.3.3-20040819 + + * [[scim-qtimm 0.7 (r75)|Software/ScimQtImm]] (requires scim-lib >= 0.99.9) + * [[UimQt 0.1.8|Software/UimQt]] (requires uim >= 0.4.3) + +#### for qt-x11-immodule-bc-qt3.3.2-20040623 + + * [[UimQt|http://freedesktop.org/~kzk/uim-qt/quiminputcontextplugin-bc-20040623.tar.gz]] - with uim ver0.3.8 + +### Getting from subversion repository + +You can download latest immodule patches from subversion repository. + + +#### trunk for Qt3 (the 'unified' patch) + + * svn checkout `http://anonsvn.freedesktop.org/svn/immqt/immodule-qt-x11/trunk` immodule-qt-x11/trunk + +#### Qt4 branch + + * svn checkout `http://anonsvn.freedesktop.org/svn/immqt/immodule-qt-x11/branches/qt4` immodule-qt-x11/branches/qt4 +-- Main.[[LiuCougar|LiuCougar]] - 19 Sep 2004 + + + + + + + + + diff --git a/Software/ImmoduleQtPatches.mdwn b/Software/ImmoduleQtPatches.mdwn new file mode 100644 index 00000000..819563d6 --- /dev/null +++ b/Software/ImmoduleQtPatches.mdwn @@ -0,0 +1,23 @@ + + +## Difference between the patches of [[immodule-qt][immodule for Qt]] + +This project produces several related patches intended for different purposes. + + +### 'Unified' patch + + * This patch is created by merging 'Binary Compatible' codes into 'ALL' to reduce maintenance cost. You can configure both 'BC' or 'ALL' functionality. All unified patches are indicated with a '-unified' in the filename (e.g. `qt-x11-immodule-unified-qt3.3.2-20040811.diff.gz`) + +### 'Binary Compatible' patch + + * This patch is intended to be used with Qt3. The resulting patched version of Qt is binary compatible with an unpatched version. All binary compatible patches are indicated with a '-bc' in the filename (e.g. `qt-x11-immodule-bc-qt3.3.2-20040623.diff`) + +### 'ALL' patch + + * The patch is intended to be merged into Qt4 (although currently based on Qt3). Binary compatibility (ABI) is broken with Qt3. The patch contains '-all' in its name (e.g. qt-x11-immodule-all-qt3.3.1-20040316.diff) + +### incremental diffs for developers + + * Some other patches are incremental diff for developers. They are merged into '-bc' and '-all' version once they are validated. (e.g. qt-x11-immodule-simplified-api-qt3.3.2-20040615.diff) +-- Main.[[YamaKen|YamaKen]] - 09 Sep 2004 diff --git a/Software/IrcClients.mdwn b/Software/IrcClients.mdwn new file mode 100644 index 00000000..26007403 --- /dev/null +++ b/Software/IrcClients.mdwn @@ -0,0 +1,42 @@ + + +## UTF-8 compatible IRC clients + + +#### Linux/UNIX + + * [[X-Chat|http://www.xchat.org/]] + * [[savIRC|http://www.savirc.com/]] + * [[KVirc|http://www.kvirc.net/]] + * [[Konversation|http://konversation.kde.org/]] + * [[Chatzilla|http://www.mozilla.org/]] + * [[Opera|http://opera.com/]] (Proprietary) + * [[KSirc|http://www.kde.org/]] (KDE) + * [[Irssi|http://www.irssi.org]] (try _/set term_type UTF-8_) + * [[Pidgin|http://pidgin.im]] +Console clients require a terminal that supports UTF-8. Use the command _unicode_start_ if you want to enable Unicode in your console. + + +#### Windows + + * [[savIRC|http://www.savirc.com/]] + * [[X-Chat|http://www.silverex.info/]] + * [[KVirc|http://www.kvirc.net/]] + * [[Chatzilla|http://www.mozilla.org/]] + * [[Opera|http://opera.com/]] (Proprietary) + * [[Pidgin|http://pidgin.im]] + +#### Mac OS X + + * [[X-Chat Aqua|http://xchataqua.sourceforge.net/]] + * [[Colloquy|http://colloquy.info/]] + * [[Conversation|http://homepage.mac.com/philrobin/conversation/]] + * [[X-Chat|http://www.xchat.org/]] + * [[Chatzilla|http://www.mozilla.org/]] + * [[Opera|http://opera.com/]] (Proprietary) + * [[Pidgin|http://pidgin.im]] + +#### Java + + * [[PJIRC|http://www.pjirc.com/]] (Applet) +-- Main.[[RouNin|RouNin]] - 2 Sep 2004<br> -- Main.[[JohnMcPherson|JohnMcPherson]] - 11 Aug 2004<br> -- Main.[[JohnMcPherson|JohnMcPherson]] - 15 Apr 2004<br> -- Main.[[RouNin|RouNin]] - 13 Apr 2004 diff --git a/Software/LibXklavier.mdwn b/Software/LibXklavier.mdwn new file mode 100644 index 00000000..4e4bb8f8 --- /dev/null +++ b/Software/LibXklavier.mdwn @@ -0,0 +1,34 @@ + + +## General info + +libxklavier is a library providing high-level API for X Keyboard Extension known as XKB. This library is indended to support XFree86 and other commercial X servers. It is useful for creating XKB-related software (layout indicators etc). + +The current features are: + + * Reading XKB configuration registry information (for XFree86) + * Configuring XKB + * Application-defined callbacks for many XKB-related events + * Support for per-window switching etc. +Requirements: + + * Proper support of XKB on X server and X client side + * Any version of X.Org or XFree86 4.3 or above with support of multiple layouts and base.xml/xorg.xml/xfree.xml configuration registry present + +## Documentation + +The API documentation can be found [[here|http://xlibs.freedesktop.org/xkbdesc/doc]]. + +Short document regarding "Why multiple layouts rock" is recommended for reading - available [[in PDF format|http://xlibs.freedesktop.org/xkbdesc/xkbconfig.pdf]] and [[in OOo format|http://xlibs.freedesktop.org/xkbdesc/xkbconfig.sxw]]. + +Some problems of XKB (and XFree implementation) are listed here: [[in PDF format|http://xlibs.freedesktop.org/xkbdesc/antixkb.pdf]] and [[in OOo format|http://xlibs.freedesktop.org/xkbdesc/antixkb.sxw]]. +## Files + +The released files are located at [[Sourceforge web site|http://sourceforge.net/projects/gswitchit/files/libxklavier/]]. + +The anonymous CVS repo at freedesktop.org: :pserver:[[anoncvs@cvs.freedesktop.org|mailto:anoncvs@cvs.freedesktop.org]]:/cvs/xklavier + + +## X servers support + +The library is designed to be usable with any X server with proper implementation of XKB extenstion. So far, it was only tested on XFree86 XKB implementation. The author is interested in supporting other X servers as well. He would be very grateful for any information/patches/feedback regarding usage of libxklavier on platforms other than XOrg/XFree86. diff --git a/Software/LibreOffice.mdwn b/Software/LibreOffice.mdwn new file mode 100644 index 00000000..38f97d6e --- /dev/null +++ b/Software/LibreOffice.mdwn @@ -0,0 +1,2 @@ + +This page has moved to [[http://libreoffice.org|http://libreoffice.org]] and [[http://wiki.documentfoundation.org|http://wiki.documentfoundation.org]] diff --git a/Software/LightDM.mdwn b/Software/LightDM.mdwn new file mode 100644 index 00000000..7781ef3a --- /dev/null +++ b/Software/LightDM.mdwn @@ -0,0 +1,34 @@ + + +# The Light Display Manager (LightDM) + + +## Purpose + +LightDM is a cross-desktop display manager that aims is to be the standard display manager for the X.org X server. The motivation for this project is there have been many new display managers written since XDM (often based on the XDM source). The main difference between these projects is in the GUIs (e.g. different toolkits) and performance - this could be better accomplished with a common display manager that allows these differences. + +Key features are: + +* A well-defined greeter API allowing multiple GUIs +* Support for all display manager use cases, with plugins where appropriate +* Low code complexity +* Fast performance + +## Download + +Development is hosted on [[Launchpad|https://launchpad.net/lightdm]]. [[Tarball releases|http://people.ubuntu.com/~robert-ancell/lightdm/releases/]] are available. + + +## Design + +See [[Software/LightDM/Design|Software/LightDM/Design]] + + +## Customisation + +To produce a new greeter, see the [[API reference|http://people.ubuntu.com/~robert-ancell/lightdm/reference/]]. To test new greeters run `lightdm --test-mode`. + + +## Contact + +Discussion should be done on the [[LightDM mailing list|http://lists.freedesktop.org/mailman/listinfo/lightdm]]. [[File bugs|https://bugs.launchpad.net/lightdm]] for problems/feature requests. diff --git a/Software/LightDM/Design.mdwn b/Software/LightDM/Design.mdwn new file mode 100644 index 00000000..0b2425b9 --- /dev/null +++ b/Software/LightDM/Design.mdwn @@ -0,0 +1,99 @@ + + +# LightDM Design + + +## What is a Display Manager? + +The responsibilities of a display manager are: + +* Starting and managing local instances of the X server. +* Authenticating users. +* Starting and managing user sessions. +Common use cases: + +* Starting a single X server on boot and starting a session (kiosk mode). +* Starting a single X server instance on boot, displaying a greeter GUI (username and password), and starting the user session when connected (traditional). +* Supporting multiple simultaneous logins by exposing what users are logged in, and starting new X servers for each user (user switching). +* Running a thin-client server by allowing X servers to connect using XDMCP, and connecting greeters and sessions to those X servers. + +## Design Goals + +* Fast - The display manager should add no noticeable delay to startup time. +* Fail-safe - Failures should be handled gracefully. +* Secure - Resistant to malicious users. +* Flexible - Able to support a range of use-cases. +* Extensible - Able to support rarer use-cases though plugins. +* Simple - Configuration should be easy and the code should be simple to understand and modify. + +## Definitions + +* Display Manager - A daemon that manages the displays on a system. +* Display - A combination of an X server, greeter and a user session. +* User session - An application that runs on a display and allows the user to run applications. +* Greeter - An application to run on a display and prompt for authentication and session options. + +## Requirements + +Daemon: + +* Able to run as as system service without user interaction +* Provide logging information for debugging +* Launch and monitor X servers +* Launch and monitor greeter applications for displays without a user session +* Launch and monitor user sessions after user is authenticated +* Authenticate users +* Provide an interface to greeter applications +* Provide an interface to user switchers +* Store a database of active displays +* Load sessions from /usr/share/xsessions +* Store session configuration in ~/.dmrc +* Support .dmrc not being readable before login +* Advertise display database to [[Software/ConsoleKit|Software/ConsoleKit]] if available +* Use PAM for authentication +Session environment: + +* Set USER to the username +* Set HOME to users home directory +* Set SHELL to the users shell +* Set PATH to /usr/bin:/bin +* Set LANG to the users language +* Set DISPLAY to the X servers address +* Set environment variables from /etc/environment +Static Display Module: + +* Allow 0-N displays to be enabled at all time +* Support automatic/timed login +User Switcher Module: + +* Interface to switch to existing local display for a logged in user +* Start new static display if user not logged in +XDMCP Server Module: + +* Implement XDMCP protocol +Module interface: + +* Expose display database +Greeter application/interface: + +* User authentication +* Session choice +* Session language +* Session keyboard layout +* Logged in users + +## Implementation + +Daemon: + +* Implemented in C+GObject +* Single process +Greeter Interface: + +* D-Bus +GTK+ Greeter: + + +## Inter-process Relationships + +[[!img LightDM interprocess relationships.png] diff --git a/Software/LightDM/Design/LightDM_interprocess_comminication.svg b/Software/LightDM/Design/LightDM_interprocess_comminication.svg new file mode 100644 index 00000000..32a80a51 --- /dev/null +++ b/Software/LightDM/Design/LightDM_interprocess_comminication.svg @@ -0,0 +1,553 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> + +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="1052.3622" + height="744.09448" + id="svg2" + version="1.1" + inkscape:version="0.48.0 r9654" + sodipodi:docname="LightDM interprocess comminication.svg"> + <defs + id="defs4"> + <marker + inkscape:stockid="Arrow1Lend" + orient="auto" + refY="0.0" + refX="0.0" + id="Arrow1Lend" + style="overflow:visible;"> + <path + id="path4168" + d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z " + style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;marker-start:none;" + transform="scale(0.8) rotate(180) translate(12.5,0)" /> + </marker> + <marker + inkscape:stockid="Arrow1Lstart" + orient="auto" + refY="0.0" + refX="0.0" + id="Arrow1Lstart" + style="overflow:visible"> + <path + id="path4165" + d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z " + style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;marker-start:none" + transform="scale(0.8) translate(12.5,0)" /> + </marker> + </defs> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + inkscape:pageopacity="0.0" + inkscape:pageshadow="2" + inkscape:zoom="0.7" + inkscape:cx="821.61053" + inkscape:cy="367.17841" + inkscape:document-units="px" + inkscape:current-layer="layer1" + showgrid="false" + showguides="true" + inkscape:guide-bbox="true" + inkscape:window-width="1366" + inkscape:window-height="692" + inkscape:window-x="0" + inkscape:window-y="24" + inkscape:window-maximized="1" /> + <metadata + id="metadata7"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + <dc:title></dc:title> + </cc:Work> + </rdf:RDF> + </metadata> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1" + transform="translate(0,-308.2677)"> + <rect + style="fill:#0000ff;fill-rule:evenodd;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;opacity:0" + id="rect2985" + width="212.2191" + height="189.51253" + x="219.20573" + y="102.19722" + transform="translate(0,308.2677)" /> + <g + id="g3854" + transform="translate(-49.74343,49.987283)"> + <rect + y="392.125" + x="617.05768" + height="55.019764" + width="475.31644" + id="rect3781" + style="fill:#ffffff;fill-opacity:1;stroke:#000000;stroke-width:1.26150584;stroke-opacity:1" /> + <flowRoot + transform="translate(81.219654,357.17416)" + style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + id="flowRoot3783" + xml:space="preserve"><flowRegion + id="flowRegion3785"><rect + y="34.950836" + x="702.15698" + height="68.993042" + width="202.61247" + id="rect3787" + style="fill:#000000;fill-opacity:1" /></flowRegion><flowPara + id="flowPara3789">:0</flowPara></flowRoot> </g> + <g + id="g3841"> + <rect + y="426.51672" + x="36.698318" + height="432.96976" + width="434.56778" + id="rect3757" + style="fill:#ffffff;fill-opacity:1;stroke:#000000;stroke-width:2.11077571;stroke-opacity:1" /> + <flowRoot + transform="translate(-649.07401,708.4276)" + style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + id="flowRoot3783-3" + xml:space="preserve"><flowRegion + id="flowRegion3785-7"><rect + y="34.950836" + x="702.15698" + height="123.13948" + width="188.63922" + id="rect3787-6" + style="fill:#000000;fill-opacity:1;stroke:none" /></flowRegion><flowPara + id="flowPara3789-9">Display</flowPara><flowPara + id="flowPara3818">Manager</flowPara></flowRoot> </g> + <g + id="g3869" + transform="translate(0.87332961,9.6066257)"> + <rect + y="434.04483" + x="284.70547" + height="396.4975" + width="165.93263" + id="rect3759" + style="fill:#ffffff;fill-opacity:1;stroke:#000000;stroke-width:1.87601483;stroke-opacity:1" /> + <flowRoot + transform="translate(-14.484858,507.80625)" + style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + id="flowRoot3861" + xml:space="preserve"><flowRegion + id="flowRegion3863"><rect + y="26.217541" + x="310.03201" + height="53.273102" + width="156.326" + id="rect3865" /></flowRegion><flowPara + id="flowPara3867">Display</flowPara></flowRoot> </g> + <g + id="g3917" + transform="translate(-19.662771,75.31384)"> + <rect + y="468.978" + x="588.62421" + height="63.753063" + width="178.54778" + id="rect3761" + style="fill:#ffffff;fill-opacity:1;stroke:#000000;stroke-width:1.14847696;stroke-opacity:1" /> + <flowRoot + transform="translate(51.526447,308.2677)" + style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + id="flowRoot3909" + xml:space="preserve"><flowRegion + id="flowRegion3911"><rect + y="164.20361" + x="546.70435" + height="52.39978" + width="160.69267" + id="rect3913" /></flowRegion><flowPara + id="flowPara3915">Greeter</flowPara></flowRoot> </g> + <g + transform="translate(198.47532,290.23408)" + id="g3917-2"> + <rect + y="468.978" + x="588.62421" + height="63.753063" + width="245.57489" + id="rect3761-4" + style="fill:#ffffff;fill-opacity:1;stroke:#000000;stroke-width:1.34690523;stroke-opacity:1" /> + <flowRoot + transform="translate(87.34361,308.2677)" + style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + id="flowRoot3909-1" + xml:space="preserve"><flowRegion + id="flowRegion3911-1"><rect + y="164.20361" + x="546.70435" + height="52.39978" + width="160.69267" + id="rect3913-9" /></flowRegion><flowPara + id="flowPara3915-4">Session</flowPara></flowRoot> </g> + <g + transform="translate(324.5407,76.112255)" + id="g3917-8"> + <rect + y="468.978" + x="588.62421" + height="63.753063" + width="45.455662" + id="rect3761-2" + style="fill:#ffffff;fill-opacity:1;stroke:#000000;stroke-width:0.57948083;stroke-opacity:1" /> + <flowRoot + transform="translate(51.526447,308.2677)" + style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + id="flowRoot3909-18" + xml:space="preserve"><flowRegion + id="flowRegion3911-2"><rect + y="164.20361" + x="546.70435" + height="52.39978" + width="160.69267" + id="rect3913-4" /></flowRegion><flowPara + id="flowPara3915-0">P</flowPara></flowRoot> </g> + <g + transform="translate(383.22679,76.985584)" + id="g3917-8-9"> + <rect + y="468.978" + x="588.62421" + height="63.753063" + width="45.455662" + id="rect3761-2-6" + style="fill:#ffffff;fill-opacity:1;stroke:#000000;stroke-width:0.57948083;stroke-opacity:1" /> + <flowRoot + transform="translate(51.526447,308.2677)" + style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + id="flowRoot3909-18-6" + xml:space="preserve"><flowRegion + id="flowRegion3911-2-4"><rect + y="164.20361" + x="546.70435" + height="52.39978" + width="160.69267" + id="rect3913-4-0" /></flowRegion><flowPara + id="flowPara3915-0-6">P</flowPara></flowRoot> </g> + <g + transform="translate(194.36321,151.96339)" + id="g3917-8-3"> + <rect + y="468.978" + x="588.62421" + height="63.753063" + width="120.32406" + id="rect3761-2-9" + style="fill:#ffffff;fill-opacity:1;stroke:#000000;stroke-width:0.9428038;stroke-opacity:1" /> + <flowRoot + transform="translate(51.526447,308.2677)" + style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + id="flowRoot3909-18-9" + xml:space="preserve"><flowRegion + id="flowRegion3911-2-5"><rect + y="164.20361" + x="546.70435" + height="53.634853" + width="103.87926" + id="rect3913-4-3" /></flowRegion><flowPara + id="flowPara3915-0-1" + style="font-size:20px">User Switcher</flowPara></flowRoot> </g> + <path + style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-start:url(#Arrow1Lstart);marker-end:url(#Arrow1Lend)" + d="m 992.93501,547.99706 c 0,-5.23998 -0.87333,-49.77979 -0.87333,-49.77979" + id="path4030" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-start:url(#Arrow1Lstart);marker-end:url(#Arrow1Lend)" + d="M 837.25978,618.75805 836.38645,499.24044" + id="path4034" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-start:url(#Arrow1Lstart);marker-end:url(#Arrow1Lend)" + d="m 453.20757,576.60503 c 12.22661,0 115.19858,0 115.19858,0" + id="path4036" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-start:url(#Arrow1Lstart);marker-end:url(#Arrow1Lend)" + d="m 656.29435,545.16517 0,-47.1598" + id="path4038" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#000000;stroke-width:3;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;stroke-miterlimit:4;stroke-dasharray:none" + d="m 451.87316,796.41194 334.5473,-0.38304" + id="path4042" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <text + xml:space="preserve" + style="font-size:20px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + x="704.32751" + y="523.33191" + id="text4052" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4054" + x="704.32751" + y="523.33191">X protocol</tspan></text> + <text + xml:space="preserve" + style="font-size:20px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + x="25.05065" + y="1036.5826" + id="text4056-4" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + x="25.05065" + y="1036.5826" + id="tspan3285">Bold lines indicate a parent-child process relationship</tspan></text> + <text + xml:space="preserve" + style="font-size:20px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + x="648.88391" + y="681.19714" + id="text4081" + sodipodi:linespacing="125%"><tspan + sodipodi:role="line" + id="tspan4083" + x="648.88391" + y="681.19714" /><tspan + sodipodi:role="line" + x="648.88391" + y="706.19714" + id="tspan4101" /><tspan + sodipodi:role="line" + x="648.88391" + y="731.19714" + id="tspan4103" /></text> + <flowRoot + xml:space="preserve" + id="flowRoot4085" + style="fill:black;stroke:none;stroke-opacity:1;stroke-width:1px;stroke-linejoin:miter;stroke-linecap:butt;fill-opacity:1;font-family:Sans;font-style:normal;font-weight:normal;font-size:20px;line-height:125%;letter-spacing:0px;word-spacing:0px"><flowRegion + id="flowRegion4087"><rect + id="rect4089" + width="101.30624" + height="59.386414" + x="530.98438" + y="332.75623" /></flowRegion><flowPara + id="flowPara4091" /></flowRoot> <flowRoot + xml:space="preserve" + id="flowRoot4093" + style="fill:black;stroke:none;stroke-opacity:1;stroke-width:1px;stroke-linejoin:miter;stroke-linecap:butt;fill-opacity:1;font-family:Sans;font-style:normal;font-weight:normal;font-size:20px;line-height:125%;letter-spacing:0px;word-spacing:0px"><flowRegion + id="flowRegion4095"><rect + id="rect4097" + width="2.6199889" + height="36.679844" + x="527.49109" + y="294.32974" /></flowRegion><flowPara + id="flowPara4099" /></flowRoot> <flowRoot + xml:space="preserve" + id="flowRoot4105" + style="font-size:20px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + transform="translate(13.58582,447.83112)"><flowRegion + id="flowRegion4107"><rect + id="rect4109" + width="64.626381" + height="53.273109" + x="482.95126" + y="138.00374" /></flowRegion><flowPara + id="flowPara4111">D-Bus API</flowPara></flowRoot> <flowRoot + xml:space="preserve" + id="flowRoot4113" + style="fill:black;stroke:none;stroke-opacity:1;stroke-width:1px;stroke-linejoin:miter;stroke-linecap:butt;fill-opacity:1;font-family:Sans;font-style:normal;font-weight:normal;font-size:20px;line-height:125%;letter-spacing:0px;word-spacing:0px"><flowRegion + id="flowRegion4115"><rect + id="rect4117" + width="91.699608" + height="48.906456" + x="290.81876" + y="39.317486" /></flowRegion><flowPara + id="flowPara4119" /></flowRoot> <rect + style="fill:#000000;fill-opacity:1;stroke:none" + id="rect4133" + width="4.9402986" + height="1.2350746" + x="242.07462" + y="41.337044" + transform="translate(0,308.2677)" /> + <flowRoot + xml:space="preserve" + style="font-size:20px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + id="flowRoot4135" + transform="translate(263.07088,285.30223)"><flowRegion + id="flowRegion4137" /><flowPara + id="flowPara4141" /></flowRoot> <flowRoot + xml:space="preserve" + id="flowRoot4151" + style="font-size:20px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + transform="translate(167.12206,553.87056)"><flowRegion + id="flowRegion4153"><rect + id="rect4155" + width="353.23132" + height="86.455223" + x="527.37683" + y="405.68405" /></flowRegion><flowPara + id="flowPara4161">Note: This assumes the greeter is a simple single process, it may be a set of processes like the session</flowPara></flowRoot> <text + xml:space="preserve" + style="font-size:20px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + x="1220.8712" + y="216.1001" + id="text4169" + sodipodi:linespacing="125%" + transform="translate(0,308.2677)"><tspan + sodipodi:role="line" + id="tspan4171" + x="1220.8712" + y="216.1001" /></text> + <path + style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-start:url(#Arrow1Lstart);marker-end:url(#Arrow1Lend)" + d="m 935.38812,547.40507 c 0,-5.23998 -0.87333,-49.77979 -0.87333,-49.77979" + id="path4030-7" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#000000;stroke-width:3;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;stroke-miterlimit:4;stroke-dasharray:none" + d="m 997.14186,762.30806 c 0,-5.23998 -0.87333,-151.05591 -0.87333,-151.05591" + id="path4030-6" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;stroke:#000000;stroke-width:3;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;stroke-miterlimit:4;stroke-dasharray:none" + d="m 934.15305,758.60283 c 0,-5.23998 -0.87333,-147.35068 -0.87333,-147.35068" + id="path4030-6-5" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;stroke:#000000;stroke-width:3;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;stroke-miterlimit:4;stroke-dasharray:none" + d="m 840.28738,759.83791 c 0,-5.23998 -0.87333,-76.95143 -0.87333,-76.95143" + id="path4030-6-8" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-start:url(#Arrow1Lstart);marker-end:url(#Arrow1Lend)" + d="m 457.09952,653.43309 c 12.22661,0 324.58076,0 324.58076,0" + id="path4036-4" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <path + style="fill:none;stroke:#000000;stroke-width:3;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + d="m 456.05794,479.01999 c 12.22661,0 110.91286,0 110.91286,0" + id="path4036-8" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-start:url(#Arrow1Lstart);marker-end:url(#Arrow1Lend)" + d="m 450.80222,216.71764 c 12.35075,3.70522 170.44029,0 170.44029,0 l 0,-32.11194" + id="path4259" + inkscape:connector-curvature="0" + transform="translate(0,308.2677)" /> + <path + style="fill:none;stroke:#000000;stroke-width:1.07294427999999997;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:1.07294431999999995, 1.07294431999999995;stroke-dashoffset:0;marker-start:url(#Arrow1Lstart);marker-end:url(#Arrow1Lend)" + d="m 597.7761,439.76519 0,-77.8097 -437.92352,0 0,78.31609" + id="path4261" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cccc" /> + <flowRoot + xml:space="preserve" + id="flowRoot4263" + style="font-size:20px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + transform="translate(16.05597,316.91322)"><flowRegion + id="flowRegion4265"><rect + id="rect4267" + width="260.60074" + height="50.638058" + x="300.12314" + y="12.93033" /></flowRegion><flowPara + id="flowPara4269">XDMCP (if remote)</flowPara></flowRoot> <path + style="fill:none;stroke:#000000;stroke-width:3;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + d="m 454.62937,562.03758 c 12.22661,0 110.91286,0 110.91286,0" + id="path4036-8-6" + inkscape:connector-curvature="0" /> + <path + style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-start:url(#Arrow1Lstart);marker-end:url(#Arrow1Lend)" + d="m 377.93282,532.89673 c 0,19.76119 0,117.33208 0,117.33208" + id="path4289" + inkscape:connector-curvature="0" + transform="translate(0,308.2677)" /> + <flowRoot + transform="translate(23.964286,926.56783)" + style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + id="flowRoot3861-3" + xml:space="preserve"><flowRegion + id="flowRegion3863-0"><rect + y="26.217541" + x="310.03201" + height="53.273102" + width="156.326" + id="rect3865-3" /></flowRegion><flowPara + id="flowPara3867-0">PAM</flowPara></flowRoot> <g + id="g3869-7" + transform="translate(-204.81465,7.2114605)"> + <rect + y="434.04483" + x="284.70547" + height="134.40413" + width="165.93263" + id="rect3759-0" + style="fill:#ffffff;fill-opacity:1;stroke:#000000;stroke-width:1.0922507;stroke-opacity:1" /> + <flowRoot + transform="translate(-14.484858,423.52054)" + style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + id="flowRoot3861-8" + xml:space="preserve"><flowRegion + id="flowRegion3863-6"><rect + y="26.217541" + x="310.03201" + height="116.13025" + width="146.32602" + id="rect3865-2" /></flowRegion><flowPara + id="flowPara3867-4">XDMCP Server</flowPara></flowRoot> </g> + <path + style="fill:none;stroke:#000000;stroke-width:1.02449429px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-start:url(#Arrow1Lstart);marker-mid:none" + d="m 450.25786,462.36218 c 12.83291,0 116.41286,0 116.41286,0" + id="path4036-43" + inkscape:connector-curvature="0" /> + <flowRoot + xml:space="preserve" + id="flowRoot4105-7" + style="font-size:20px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + transform="translate(-8.1049106,290.64581)"><flowRegion + id="flowRegion4107-1"><rect + id="rect4109-2" + width="94.626396" + height="30.41597" + x="482.95126" + y="138.00374" /></flowRegion><flowPara + id="flowPara4111-2">SIGUSR1</flowPara></flowRoot> <path + style="fill:none;stroke:#000000;stroke-width:1.02449429px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-start:url(#Arrow1Lstart);marker-mid:none" + d="m 451.79357,783.65536 c 12.83291,0 334.98429,0 334.98429,0" + id="path4036-43-0" + inkscape:connector-curvature="0" + sodipodi:nodetypes="cc" /> + <flowRoot + xml:space="preserve" + id="flowRoot4105-7-5" + style="font-size:20px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans" + transform="translate(81.287941,611.93899)"><flowRegion + id="flowRegion4107-1-0"><rect + id="rect4109-2-3" + width="94.626396" + height="30.41597" + x="482.95126" + y="138.00374" /></flowRegion><flowPara + id="flowPara4111-2-1">SIGUSR1</flowPara></flowRoot> </g> +</svg> diff --git a/Software/LightDM/Design/LightDM_interprocess_relationships.png b/Software/LightDM/Design/LightDM_interprocess_relationships.png Binary files differnew file mode 100644 index 00000000..3fafcf82 --- /dev/null +++ b/Software/LightDM/Design/LightDM_interprocess_relationships.png diff --git a/Software/Plymouth.mdwn b/Software/Plymouth.mdwn new file mode 100644 index 00000000..7bd2e970 --- /dev/null +++ b/Software/Plymouth.mdwn @@ -0,0 +1,50 @@ + + +# What is Plymouth? + +Plymouth is an application that runs very early in the boot process (even before the root filesystem is mounted!) that provides a graphical boot animation while the boot process happens in the background. + +It is designed to work on systems with [[DRM|http://dri.freedesktop.org/wiki/DRM]] modesetting drivers. The idea is that early on in the boot process the native mode for the computer is set, plymouth uses that mode, and that mode stays throughout the entire boot process up to and after X starts. Ideally, the goal is to get rid of all flicker during startup. + +For systems that don't have DRM mode settings drivers, plymouth falls back to text mode (it can also use a legacy /dev/fb interface). + +In either text or graphics mode, the boot messages are completely occluded. After the root file system is mounted read-write, the messages are dumped to /var/log/boot.log. Also, the user can see the messages at any time during boot up by hitting the escape key. + +Plymouth isn't really designed to be built from source by end users. For it to work correctly, it needs integration with the distribution. Because it starts so early, it needs to be packed into the distribution's initial ram disk, and the distribution needs to poke plymouth to tell it how boot is progressing. + +plymouth ships with two binaries: /sbin/plymouthd and /bin/plymouth . + +The first one, plymouthd, does all the heavy lifting. It logs the session and shows the splash screen. The second one, /bin/plymouth, is the control interface to plymouthd. + +It supports things like plymouth show-splash, or plymouth ask-for-password, which trigger the associated action in plymouthd. + +Plymouth supports various "splash" themes which are analogous to screensavers, but happen at boot time. There are several sample themes shipped with plymouth, but most distributions that use plymouth ship something customized for their distribution. + +Plymouth isn't done yet. It's still under active development, but is used in several popular distros already, including Fedora, Mandriva, Ubuntu and others. See the [[distributions|http://www.freedesktop.org/wiki/Software/Plymouth/Distributions]] page for more information. + + +# Mailing List & Bugzilla + +Plymouth has a fairly low traffic mailing list at [[plymouth@lists.freedesktop.org|mailto:plymouth@lists.freedesktop.org]]. It's a useful place to send patches or discuss distribution integration issues. + +Bugs should be filed at [[http://bugs.freedesktop.org|http://bugs.freedesktop.org]]. Bugzilla is also a good staging area for patches that need more than one iteration before they are ready. + + +# Download + +Plymouth tarball releases are available at [[http://www.freedesktop.org/software/plymouth/releases/|http://www.freedesktop.org/software/plymouth/releases/]]. Note, since Plymouth requires integration with the distribution to be useful, you normally would get Plymouth through your distributor and not from tarballs. [[http://www.freedesktop.org/software/plymouth/releases/|http://www.freedesktop.org/software/plymouth/releases/]] is primarily for distributions to get the latest release. + + +# Source + +Plymouth is managed in git. See [[http://cgit.freedesktop.org/cgit/plymouth/|http://cgit.freedesktop.org/cgit/plymouth/]]. To get at the code, you can run: + +* git clone git://git.freedesktop.org/git/plymouth +For general information about using git, visit [[http://book.git-scm.com|http://book.git-scm.com]] + + +# External Resources + +* A very nice write up about Plymouth can be found at [[http://blog.fpmurphy.com/2009/09/project-plymouth.html|http://blog.fpmurphy.com/2009/09/project-plymouth.html]]. +* Charlie Brej has done a four part series on theme starting at [[http://brej.org/blog/?p=158|http://brej.org/blog/?p=158]] +* Ray Strode did a blog post discussing the transition from Plymouth to X at [[http://blogs.gnome.org/halfline/2009/11/28/plymouth-⟶-x-transition/|http://blogs.gnome.org/halfline/2009/11/28/plymouth-⟶-x-transition/]]
\ No newline at end of file diff --git a/Software/PolicyKit.mdwn b/Software/PolicyKit.mdwn new file mode 100644 index 00000000..4524fd28 --- /dev/null +++ b/Software/PolicyKit.mdwn @@ -0,0 +1,2 @@ + +The contents of this page has been moved to [[this page|http://www.freedesktop.org/wiki/Software/polkit]]. Please update your bookmarks and links. diff --git a/Software/PulseAudio.mdwn b/Software/PulseAudio.mdwn new file mode 100644 index 00000000..018e962b --- /dev/null +++ b/Software/PulseAudio.mdwn @@ -0,0 +1,92 @@ + +[[!inline pages="Software/PulseAudio/TOC" quick="yes" raw="yes"]] + + +# Welcome to PulseAudio! + + +## What Is PulseAudio? + +PulseAudio is a sound system for POSIX OSes, meaning that it is a proxy for your sound applications. It allows you to do advanced operations on your sound data as it passes between your application and your hardware. Things like transferring the audio to a different machine, changing the sample format or channel count and mixing several sounds into one are easily achieved using a sound server. + +PulseAudio is designed for Linux systems. It has also been ported to and tested on Solaris, FreeBSD, NetBSD, MacOS X, Windows 2000 and Windows XP. + +PulseAudio is an integral part of all relevant modern Linux distributions and used in various mobile devices by multiple vendors. + +[[Details ...|Software/PulseAudio/About]] | [[Definition at Wikipedia|http://en.wikipedia.org/wiki/PulseAudio]] | [[Ohloh page|https://www.ohloh.net/p/pulseaudio]] | +[[!format rawhtml """ +#!html +<a href="https://plus.google.com/108655567462001640364" rel="publisher">Google+</a> +"""]] + +## News + + +### March 2013 + +* **2013-03-08**: [[PAVUControl 2.0|http://freedesktop.org/software/pulseaudio/pavucontrol/pavucontrol-2.0.tar.xz]] has been released. ([[Notes|http://freedesktop.org/software/pulseaudio/pavucontrol/]]) + +### December 2012 + +* **2012-12-18**: [[PulseAudio 3.0|http://freedesktop.org/software/pulseaudio/releases/pulseaudio-3.0.tar.xz]] has been released. ([[Changes|http://www.freedesktop.org/wiki/Software/PulseAudio/Notes/3.0]]) + +### July 2012 + +* **2012-07-19**: [[PulseAudio 2.1|http://freedesktop.org/software/pulseaudio/releases/pulseaudio-2.1.tar.xz]] has been released. ([[Changes|http://www.freedesktop.org/wiki/Software/PulseAudio/Notes/2.1]]) + +### May 2012 + +* **2012-05-11**: [[PulseAudio 2.0|http://freedesktop.org/software/pulseaudio/releases/pulseaudio-2.0.tar.xz]] has been released. ([[Changes|http://www.freedesktop.org/wiki/Software/PulseAudio/Notes/2.0]]) + +### March 2012 + +* **2012-03-28**: [[PulseAudio 1.99.2|http://freedesktop.org/software/pulseaudio/releases/pulseaudio-1.99.2.tar.xz]] has been released. +* **2012-03-15**: [[PulseAudio 1.99.1|http://freedesktop.org/software/pulseaudio/releases/pulseaudio-1.99.1.tar.xz]] has been released. + +### October 2011 + +* **2011-10-20**: [[PulseAudio 1.1|http://freedesktop.org/software/pulseaudio/releases/pulseaudio-1.1.tar.xz]] has been released. + +### September 2011 + +* **2011-09-27**: [[PulseAudio 1.0|http://freedesktop.org/software/pulseaudio/releases/pulseaudio-1.0.tar.xz]] has been released. ([[Changes|http://www.freedesktop.org/wiki/Software/PulseAudio/Notes/1.0]]) Also [[PaVuControl 1.0|http://freedesktop.org/software/pulseaudio/pavucontrol/pavucontrol-1.0.tar.xz]] and [[PaPrefs 0.9.10|http://freedesktop.org/software/pulseaudio/paprefs/paprefs-0.9.10.tar.xz]]. +* **2011-09-15:** Fourth pre-release for 1.0, [[PulseAudio 0.99.4|http://freedesktop.org/software/pulseaudio/releases/pulseaudio-0.99.4.tar.gz]] has been released. + +### August 2011 + +* **2011-08-29:** Third pre-release for 1.0, [[PulseAudio 0.99.3|http://freedesktop.org/software/pulseaudio/releases/pulseaudio-0.99.3.tar.gz]] has been released. +* **2011-08-16:** Second pre-release for 1.0, [[PulseAudio 0.99.2|http://freedesktop.org/software/pulseaudio/releases/pulseaudio-0.99.2.tar.gz]] has been released. +* **2011-08-03:** First pre-release for 1.0, [[PulseAudio 0.99.1|http://freedesktop.org/software/pulseaudio/releases/pulseaudio-0.99.1.tar.gz]] has been released. + +### June 2011 + +* **2011-06-23:** [[PulseAudio 0.9.23|http://freedesktop.org/software/pulseaudio/releases/pulseaudio-0.9.23.tar.gz]] has been released. ([[Changes|http://pulseaudio.org/milestone/0.9.23]]) + +### November 2010 + +* **2010-11-26:** [[PulseAudio 0.9.22|http://freedesktop.org/software/pulseaudio/releases/pulseaudio-0.9.22.tar.gz]] has been released. ([[Changes|http://pulseaudio.org/milestone/0.9.22]]) + +### February 2010 + +* **2010-02-12:** Canonical are hiring a sound software engineer. More details can be found at [[[http://webapps.ubuntu.com/employment/canonical_UDSE/|http://webapps.ubuntu.com/employment/canonical_UDSE/]]] + +### January 2010 + +* **2010-01-06:** Please submit translations via [[Transifex.net|http://www.transifex.net/projects/p/pulseaudio/resource/master-tx-po-pulseaudio-pot/]], not any longer through [[Fedora's Transifex installation|https://translate.fedoraproject.org/projects/pulseaudio/master-tx/]]. + +### November 2009 + +* **2009-11-23:** [[PulseAudio 0.9.21|http://freedesktop.org/software/pulseaudio/releases/pulseaudio-0.9.21.tar.gz]] has been released. ([[Changes|http://pulseaudio.org/milestone/0.9.21]]) +* **2009-11-11:** [[PulseAudio 0.9.20|http://freedesktop.org/software/pulseaudio/releases/pulseaudio-0.9.20.tar.gz]] has been released. ([[Changes|http://pulseaudio.org/milestone/0.9.20]]) + +### October 2009 + +* **2009-10-23:** [[Collabora now offers consulting services for PulseAudio.|http://blogs.gnome.org/uraeus/2009/10/23/welcoming-new-team-members-to-collabora-multimedia/]] + +### September 2009 + +* **2009-09-30:** [[PulseAudio 0.9.19|http://freedesktop.org/software/pulseaudio/releases/pulseaudio-0.9.19.tar.gz]] has been released. ([[Changes|http://pulseaudio.org/milestone/0.9.19]]) +* **2009-09-19:** [[PulseAudio 0.9.18|http://freedesktop.org/software/pulseaudio/releases/pulseaudio-0.9.18.tar.gz]] has been released. ([[Changes|http://pulseaudio.org/milestone/0.9.18]]) +* **2009-09-11:** [[PulseAudio 0.9.17|http://freedesktop.org/software/pulseaudio/releases/pulseaudio-0.9.17.tar.gz]] has been released. ([[Changes|http://pulseaudio.org/milestone/0.9.17]]) +* **2009-09-10:** [[PulseAudio 0.9.16|http://freedesktop.org/software/pulseaudio/releases/pulseaudio-0.9.16.tar.gz]] has been released. ([[Changes|http://pulseaudio.org/milestone/0.9.16]]) +[[Old News|Software/PulseAudio/OldNews]] diff --git a/Software/PulseAudio/About.mdwn b/Software/PulseAudio/About.mdwn new file mode 100644 index 00000000..7c28c2f9 --- /dev/null +++ b/Software/PulseAudio/About.mdwn @@ -0,0 +1,130 @@ + +[[!inline pages="Software/PulseAudio/TOC" quick="yes" raw="yes"]] + + +# About PulseAudio + + +## Details + +PulseAudio is a networked sound server, similar in theory to the [[Enlightened Sound Daemon|http://cvs.gnome.org/viewcvs/esound/]] (EsounD). PulseAudio is however much more advanced and has numerous features. + +A sound server can serve many functions: + +* Software mixing of multiple audio streams, bypassing any restrictions the hardware has. +* Network transparency, allowing an application to play back or record audio on a different machine than the one it is running on. +* Sound API abstraction, alleviating the need for multiple backends in applications to handle the wide diversity of sound systems out there. +* Generic hardware abstraction, giving the possibility of doing things like individual volumes per application. +PulseAudio comes with many [[plugin modules|Software/PulseAudio/Documentation/User/Modules]]. All audio from/to clients and audio interfaces goes through modules. + +Manuel Amador created [[a diagram|http://rudd-o.com/linux-and-free-software/how-pulseaudio-works/]] describing how the different parts of PulseAudio play together. (Not all [[modules|Software/PulseAudio/Documentation/User/Modules]] are shown.) Another, simpler architecture diagram is attached to this page (scroll to the bottom). + +PulseAudio clients can send audio to "sinks" and receive audio from "sources". A client can be GStreamer, xinelib, MPlayer or any other audio application. Only the device drivers/audio interfaces can be either sources or sinks (they are often hardware in- and out-puts). + + +## Current Status + +The PulseAudio daemon and utilities are still under development, but are generally considered stable. API, ABI and the protocol are considered release worthy so effort is spent to not break these. Application developers should not feel uneasy using the client library at this point. + + +## Features + +* Licensed under [[LGPL 2.1+|http://www.gnu.org/copyleft/lesser.html]] (might effectively be downgraded to GPL if you link against libsamplerate -- which his optional however) +* Extensible plugin architecture (by loading dynamic loadable modules with dlopen()) +* Support for static linking of modules, allowing a single binary for all your needs +* Module autoloading +* Support for more than one sink/source +* Good low latency behaviour +* Very accurate latency measurement for playback and recording. +* Client side latency interpolation +* Embeddable into other software (the core is available as C library) +* Completely asynchronous C API, complemented by two synchronous variants for simple use in synchronous applications +* Simple command line interface for reconfiguring the daemon while running +* Flexible, implicit sample type conversion and resampling +* "Zero-Copy" architecture +* May be used to combine multiple sound cards to one (with sample rate adjustment) +* Ability to fully synchronize multiple playback streams +* Various network audio streaming options +PulseAudio is intended to provide lower latency than the software mixers dmix and esd. + + +## Supported Operating Systems + +* Linux (any modern distribution) +* Solaris +* FreeBSD +* NetBSD +* [[Mac OSX|Software/PulseAudio/Ports/OSX]] +* Native [[Win32|Software/PulseAudio/Ports/Windows/Support]] + +## Related Software + +The following auxiliary GUI tools have been developed for PulseAudio: + +* [[PulseAudio Volume Control|http://0pointer.de/lennart/projects/pavucontrol]] +* [[PulseAudio Preferences|http://0pointer.de/lennart/projects/paprefs/]] +The following obsolete or out-of-date UI tools have been Developed for PulseAudio as well: + +* [[PulseAudio Manager|http://0pointer.de/lennart/projects/paman]] +* [[PulseAudio Volume Meter|http://0pointer.de/lennart/projects/pavumeter]] +* [[PulseAudio Device Chooser|http://0pointer.de/lennart/projects/padevchooser]] +The following plugins for third-party software have been developed: + +* [[xmms-pulse - PulseAudio plugin for XMMS|http://0pointer.de/lennart/projects/xmms-pulse]] +* [[libao-pulse - PulseAudio plugin for libao|http://0pointer.de/lennart/projects/libao-pulse]] +* [[gst-pulse - PulseAudio plugin for GStreamer in gst-plugins-good|http://gstreamer.freedesktop.org/modules/gst-plugins-good.html]] +The following third-party software also has support for PulseAudio: + +* [[ALSA|http://www.alsa-project.org]] (in alsa-plugins: [[README|http://hg-mirror.alsa-project.org/alsa-plugins/file/14ac70da1259/doc/README-pulse]]) +* [[LiVES|http://lives.sourceforge.net]] versions 1.1.3 and higher. +* [[MPD|http://www.musicpd.org/]] (supported in svn as of revision 4316) +* [[MPlayer|http://www.mplayerhq.hu/]] (with [[this patch|http://0pointer.de/public/mplayer-pulse.patch]]) +* [[xine|http://xinehq.de]] versions 1.1.3 and greater. +* [[VLC media player|http://www.videolan.org/vlc]] and LibVLC from version 0.9.0 (version 1.1.12 or more is recommended) +* [[SXEmacs|http://www.sxemacs.org]] since 22.1.3 +Projects and Software based on [[PulseAudio|PulseAudio]]: + +* **Pulse Whole Home Audio** - A no frills multi-room/zone audio server that uses pulse to do all the heavy audio lifting. You can find details and the code on the project's [[gitorious wiki|http://gitorious.org/pulse-whole-home-audio/pages/Home]]. + +## Screenshots + +Since PulseAudio is a daemon process that sits in the background it's difficult to make a screenshot of it. However we can provide you with a screenshot of the auxiliary tools mentioned above: + +[[http://0pointer.de/public/pulse-screenshot-small.png|http://0pointer.de/public/pulse-screenshot-small.png]] + +(For the full size image follow [[this link|http://0pointer.de/blog/projects/pulse-news]].) + + +## Distributions + +PulseAudio is currently available in the following distributions: + +* [[ALT Linux Sisyphus|http://www.altlinux.com/]]; for more information, see [[ALT Linux Sisyphus and PulseAudio (in Russian, only)|http://www.freesource.info/wiki/ALTLinux/Dokumentacija/PulseAudio]] +* [[ArchLinux|http://www.archlinux.org]] - has a nice [[Wiki page|http://wiki.archlinux.org/index.php/PulseAudio]] +* [[Debian|http://packages.qa.debian.org/p/pulseaudio.html]] +* [[Ubuntu|http://packages.ubuntu.com/search?keywords=pulseaudio&searchon=names&exact=1]] (Enabled by default starting from Ubuntu 8.04.) +* [[Fedora|https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=195221]] (Enabled by default starting from [[Core 8|http://docs.fedoraproject.org/release-notes/f8/en_US/sn-OverView.html]]) +* [[Gentoo|http://packages.gentoo.org/package/media-sound/pulseaudio]] ([[Wiki|http://wiki.gentoo.org/wiki/PulseAudio]]) +* [[T2 SDE Linux|http://www.t2-project.org/packages/pulseaudio.html]] +* [[Lunar Linux|http://lunar-linux.org]] +* [[Mandriva|http://fr2.rpmfind.net/linux/rpm2html/search.php?query=pulseaudio&system=&arch=]] (Enabled by default [[in Mandriva 2008.1|http://wiki.mandriva.com/en/2008.1_Notes#PulseAudio_sound_server_used_by_default]]) +* [[OpenEmbedded|http://www.openembedded.org/filebrowser/org.openembedded.dev/packages/pulseaudio]] +* [[OpenSUSE|http://fr2.rpmfind.net/linux/rpm2html/search.php?query=pulseaudio&system=&arch=]] +* [[Pardus|http://www.pardus.org.tr/eng]] (Enabled by default since Pardus 2008.) +* [[FreeBSD|http://www.freebsd.org/]] +* [[NetBSD|http://www.NetBSD.org/]] (via [[pkgsrc|http://www.pkgsrc.org/]]) +Earlier versions of PulseAudio, then known as Polypaudio, can be found in quite a few distributions: + +* [[ROCK Linux|http://www.rocklinux.net/]] +* [[CRUX|http://crux.nu/]] +* [[SourceMage|http://www.sourcemage.org/]] + +## In The Press + +* [[Wikipedia Article|http://en.wikipedia.org/wiki/PulseAudio]] +* [[Linux Weekly News 2006|http://lwn.net/Articles/185613/]] +* [[GnomeFiles Featured Application 2006-06-02|http://gnomefiles.org/]] +* [[ars.technica 2007-10-17|http://arstechnica.com/journals/linux.ars/2007/10/17/pulseaudio-to-bring-earcandy-to-linux]] +* [[Fedora Interview 2007-10-30|http://fedoraproject.org/wiki/Interviews/LennartPoettering]] +* [[linux.com 2007-11-02|http://www.linux.com/feature/119926]] +* [[TechWorld 2009|http://www.techworld.com.au/article/320807/open_source_identity_pulseaudio_creator_lennart_poettering/]]
\ No newline at end of file diff --git a/Software/PulseAudio/About/pa-arch-1.png b/Software/PulseAudio/About/pa-arch-1.png Binary files differnew file mode 100644 index 00000000..3facd9a3 --- /dev/null +++ b/Software/PulseAudio/About/pa-arch-1.png diff --git a/Software/PulseAudio/About/pa-arch-1.svg b/Software/PulseAudio/About/pa-arch-1.svg new file mode 100644 index 00000000..6bda4261 --- /dev/null +++ b/Software/PulseAudio/About/pa-arch-1.svg @@ -0,0 +1,161 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.0//EN" "http://www.w3.org/TR/2001/PR-SVG-20010719/DTD/svg10.dtd"> +<svg width="32cm" height="20cm" viewBox="-212 266 631 396" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"> + <g> + <ellipse style="fill: #ffc0cb" cx="-121" cy="635.534" rx="80" ry="23.5336"/> + <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-121" cy="635.534" rx="80" ry="23.5336"/> + <text style="fill: #000000;text-anchor:middle;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="-121" y="639.434"> + <tspan x="-121" y="639.434">ALSA</tspan> + </text> + </g> + <g> + <ellipse style="fill: #ffc0cb" cx="59" cy="635.534" rx="80" ry="23.5336"/> + <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="59" cy="635.534" rx="80" ry="23.5336"/> + <text style="fill: #000000;text-anchor:middle;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="59" y="639.434"> + <tspan x="59" y="639.434">Bluetooth</tspan> + </text> + </g> + <g> + <ellipse style="fill: #ffc0cb" cx="297.94" cy="636.735" rx="98.9402" ry="24.7351"/> + <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="297.94" cy="636.735" rx="98.9402" ry="24.7351"/> + <text style="fill: #000000;text-anchor:middle;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="297.94" y="640.635"> + <tspan x="297.94" y="640.635">Network (TCP/RTP/...)</tspan> + </text> + </g> + <g> + <ellipse style="fill: #add8e6" cx="-92.9327" cy="291.534" rx="67.0673" ry="23.5336"/> + <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-92.9327" cy="291.534" rx="67.0673" ry="23.5336"/> + <text style="fill: #000000;text-anchor:middle;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="-92.9327" y="295.434"> + <tspan x="-92.9327" y="295.434">Simple API</tspan> + </text> + </g> + <g> + <ellipse style="fill: #add8e6" cx="67.0673" cy="291.534" rx="67.0673" ry="23.5336"/> + <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="67.0673" cy="291.534" rx="67.0673" ry="23.5336"/> + <text style="fill: #000000;text-anchor:middle;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="67.0673" y="295.434"> + <tspan x="67.0673" y="295.434">Async API</tspan> + </text> + </g> + <g> + <ellipse style="fill: #add8e6" cx="279.156" cy="290.872" rx="79.1556" ry="22.8715"/> + <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="279.156" cy="290.872" rx="79.1556" ry="22.8715"/> + <text style="fill: #000000;text-anchor:middle;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="279.156" y="294.772"> + <tspan x="279.156" y="294.772">ALSA emulation</tspan> + </text> + </g> + <g> + <g> + <ellipse style="fill: #000000" cx="151" cy="289" rx="1" ry="1"/> + <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="151" cy="289" rx="1" ry="1"/> + </g> + <g> + <ellipse style="fill: #000000" cx="171" cy="289" rx="1" ry="1"/> + <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="171" cy="289" rx="1" ry="1"/> + </g> + <g> + <ellipse style="fill: #000000" cx="161" cy="289" rx="1" ry="1"/> + <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="161" cy="289" rx="1" ry="1"/> + </g> + </g> + <g> + <g> + <ellipse style="fill: #000000" cx="160" cy="637" rx="1" ry="1"/> + <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="160" cy="637" rx="1" ry="1"/> + </g> + <g> + <ellipse style="fill: #000000" cx="180" cy="637" rx="1" ry="1"/> + <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="180" cy="637" rx="1" ry="1"/> + </g> + <g> + <ellipse style="fill: #000000" cx="170" cy="637" rx="1" ry="1"/> + <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="170" cy="637" rx="1" ry="1"/> + </g> + </g> + <g> + <ellipse style="fill: #90ee90" cx="-110.623" cy="458.028" rx="49.3767" ry="18.0279"/> + <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-110.623" cy="458.028" rx="49.3767" ry="18.0279"/> + <text style="fill: #000000;text-anchor:middle;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="-110.623" y="461.928"> + <tspan x="-110.623" y="461.928">udev</tspan> + </text> + </g> + <g> + <ellipse style="fill: #90ee90" cx="-115.869" cy="521.033" rx="84.1305" ry="21.0326"/> + <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-115.869" cy="521.033" rx="84.1305" ry="21.0326"/> + <text style="fill: #000000;text-anchor:middle;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="-115.869" y="524.933"> + <tspan x="-115.869" y="524.933">Stream restore</tspan> + </text> + </g> + <g> + <ellipse style="fill: #90ee90" cx="320" cy="400" rx="80" ry="20"/> + <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="320" cy="400" rx="80" ry="20"/> + <text style="fill: #000000;text-anchor:middle;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="320" y="403.9"> + <tspan x="320" y="403.9">Combine</tspan> + </text> + </g> + <g> + <ellipse style="fill: #90ee90" cx="324.131" cy="521.033" rx="84.1305" ry="21.0326"/> + <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="324.131" cy="521.033" rx="84.1305" ry="21.0326"/> + <text style="fill: #000000;text-anchor:middle;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="324.131" y="524.933"> + <tspan x="324.131" y="524.933">Intended roles</tspan> + </text> + </g> + <g> + <ellipse style="fill: #90ee90" cx="309.376" cy="458.027" rx="53.5484" ry="19.551"/> + <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="309.376" cy="458.027" rx="53.5484" ry="19.551"/> + <text style="fill: #000000;text-anchor:middle;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="309.376" y="461.927"> + <tspan x="309.376" y="461.927">X11</tspan> + </text> + </g> + <g> + <ellipse style="fill: #90ee90" cx="-115.869" cy="401.033" rx="84.1305" ry="21.0326"/> + <ellipse style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" cx="-115.869" cy="401.033" rx="84.1305" ry="21.0326"/> + <text style="fill: #000000;text-anchor:middle;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="-115.869" y="404.933"> + <tspan x="-115.869" y="404.933">Echo cancel</tspan> + </text> + </g> + <g> + <rect style="fill: #ffa500" x="20" y="420" width="160" height="60"/> + <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x="20" y="420" width="160" height="60"/> + <text style="fill: #000000;text-anchor:middle;font-size:12.8;font-family:sanserif;font-style:normal;font-weight:normal" x="100" y="453.9"> + <tspan x="100" y="453.9">PulseAudio Daemon</tspan> + </text> + </g> + <g> + <path style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" d="M -49.5084 313.246 C -20.5756,327.712 -44.268,349.012 52.0683,416.448"/> + <polyline style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="-40.3281,312.246 -51.5084,312.246 -44.8001,321.19 "/> + <polyline style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="42.8405,416.092 53.9001,417.73 48.5751,407.899 "/> + </g> + <g> + <path style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" d="M 77.1769 320.04 C 88.6149,352.291 100,349.001 100,414.529"/> + <polyline style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="84.4845,325.686 76.4295,317.932 75.0596,329.029 "/> + <polyline style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="95,406.765 100,416.765 105,406.765 "/> + </g> + <g> + <path style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" d="M 230.512 312.15 C 195.453,327.486 181.337,388.997 144.915,416.314"/> + <polyline style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="225.403,319.843 232.561,311.254 221.395,310.681 "/> + <polyline style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="148.126,407.656 143.126,417.656 154.126,415.656 "/> + </g> + <path style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" d="M -65.0422 418.288 C -9.17276,437.256 -41.0053,426.499 18.9947,436.499"/> + <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x1="-60.5257" y1="456.118" x2="18.998" y2="453.087"/> + <path style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" d="M -68.397 503.161 C -12.5276,482.129 -81.0024,504.301 18.9976,474.301"/> + <path style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" d="M 271.064 416.312 C 211.064,436.312 220.902,419.774 180.902,429.774"/> + <path style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" d="M 259.904 450.546 C 230.528,452.52 250.5,450 180.987,450"/> + <path style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" d="M 284.146 501.976 C 240.016,480.944 241.003,473.5 181.003,463.5"/> + <g> + <path style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" d="M 55.0975 483.677 C 18.6752,510.994 -12.0666,592.807 -67.9032,614.708"/> + <polyline style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="51.8864,492.335 56.8864,482.335 45.8864,484.335 "/> + <polyline style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="-62.5011,607.218 -69.9849,615.524 -58.8497,616.527 "/> + </g> + <g> + <path style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" d="M 100 485.472 C 100,491 99.0445,588.414 81.9406,608.54"/> + <polyline style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="105,493.236 100,483.236 95,493.236 "/> + <polyline style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="83.1583,599.386 80.4925,610.244 90.7783,605.862 "/> + </g> + <g> + <path style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" d="M 144.874 483.656 C 181.297,510.973 187.442,590.362 242.258,613.368"/> + <polyline style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="154.086,484.314 143.086,482.314 148.086,492.314 "/> + <polyline style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" points="233.165,614.973 244.32,614.233 237.034,605.753 "/> + </g> + <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 20; stroke: #7f7f7f" x1="-208.736" y1="355" x2="417.96" y2="354.662"/> + <line style="fill: none; fill-opacity:0; stroke-width: 2; stroke-dasharray: 20; stroke: #7f7f7f" x1="-210.234" y1="570.538" x2="416.464" y2="570.2"/> +</svg> diff --git a/Software/PulseAudio/Apps/FlashPlayer9.mdwn b/Software/PulseAudio/Apps/FlashPlayer9.mdwn new file mode 100644 index 00000000..ff3203e0 --- /dev/null +++ b/Software/PulseAudio/Apps/FlashPlayer9.mdwn @@ -0,0 +1,72 @@ + +[[!inline pages="Software/PulseAudio/TOC" quick="yes" raw="yes"]] + + +# Flash Player 9: Experimental PulseAudio support + +**Update:** Please note that there's now a newer implementation of libflashsupport.so available from the [[PulseAudio|PulseAudio]] developers: [[gitweb|http://git.0pointer.de/?p=libflashsupport.git;a=summary]], `git-clone http://git.0pointer.de/repos/libflashsupport.git/`. Please make sure to use this version for better results. + +_This page describes how to solve the Flash Player 9 problem by building and installing an experimental plugin, libflashsupport.so, which adds support for ESD and [[PulseAudio|PulseAudio]]._ + +This guide is aimed at non-technical users of **Ubuntu 7.10 Gutsy Gibbon** (and previous Ubuntu releases) or other **Debian**-based distributions. + + +## Installation + +Make sure you have the following packages installed, additional to [[PulseAudio|PulseAudio]] + +* build-essential +* automake1.9 +* autoconf +* libtool +* libesd0-dev +* libpulse-dev +* libssl-dev +Start a terminal and run this command: +[[!format txt """ +sudo aptitude install build-essential automake1.9 autoconf libtool libesd0-dev libpulse-dev libssl-dev +"""]] +(You can start the terminal by pressing Alt+F2 and typing `gnome-terminal` or `x-terminal-emulator`) + + +### Download source + +To compile the plugin, you need to get the latest version using `git clone http://git.0pointer.de/repos/libflashsupport.git/` + + +### Compiling and installing + +In a terminal, go into the directory you moved the downloaded files into and: +[[!format txt """ +cd libflashsupport +"""]] +_Ubuntu 7.10 ships with libpulse 0.9.6 while the current (7 feb 2008) configure script requires at least version 0.9.7. Edit the **configure.ac** file and change in the line_ + + +`PKG_CHECK_MODULES(PULSE, [ libpulse >= 0.9.7 ])` + + +_the version number to 0.9.6 and follow the rest of the instructions. This did the trick for me._ + +Now compile the plugin: +[[!format txt """ +./bootstrap.sh +make +sudo make install +"""]] +(Note that it cannot be installed in /usr/local as flash won't find it there) + +Hopefully it should all go well. Restart Firefox and check if it works. + +If something goes wrong (like Firefox crashes), this is how to uninstall it again: + + +### Uninstalling + +Close all instances of Firefox (or anything that uses Flash). + +Open a terminal and run this command: +[[!format txt """ +sudo rm /usr/lib/libflashsupport.* +"""]] +The plugin is now removed. diff --git a/Software/PulseAudio/Backends/ALSA.mdwn b/Software/PulseAudio/Backends/ALSA.mdwn new file mode 100644 index 00000000..b738ec4e --- /dev/null +++ b/Software/PulseAudio/Backends/ALSA.mdwn @@ -0,0 +1,10 @@ + +[[!inline pages="Software/PulseAudio/TOC" quick="yes" raw="yes"]] +# ALSA Backend + +The primary backend used on Linux is [[ALSA|http://alsa-project.org/]]. + +* Information about PulseAudio [[profiles|Software/PulseAudio/Backends/ALSA/Profiles]] for ALSA. +* Misc. [[issues|Software/PulseAudio/Backends/ALSA/Issues]] with ALSA. +* Problems with inaccurate [[decibel|Software/PulseAudio/Backends/ALSA/Decibel]] metadata. +* [[Broken drivers|Software/PulseAudio/Backends/ALSA/BrokenDrivers]].
\ No newline at end of file diff --git a/Software/PulseAudio/Backends/ALSA/BrokenDrivers.mdwn b/Software/PulseAudio/Backends/ALSA/BrokenDrivers.mdwn new file mode 100644 index 00000000..80ba1d5a --- /dev/null +++ b/Software/PulseAudio/Backends/ALSA/BrokenDrivers.mdwn @@ -0,0 +1,64 @@ + +[[!inline pages="Software/PulseAudio/TOC" quick="yes" raw="yes"]] [[↩ Back to ALSA|Software/PulseAudio/Backends/ALSA]] + + +# Broken ALSA Drivers + +At this point in time it is known that the following ALSA sound drivers are broken in regards to "glitch-free" PA: + +* Some snd-intel8x0 supported chips [[http://mailman.alsa-project.org/pipermail/alsa-devel/2009-February/014975.html|http://mailman.alsa-project.org/pipermail/alsa-devel/2009-February/014975.html]] #396 (Seems to be fixed by [[https://bugzilla.redhat.com/show_bug.cgi?id=472339|https://bugzilla.redhat.com/show_bug.cgi?id=472339]]) +* All newer Creative chips (snd-emu*) #435 +* snd-intel-hda on some chips (seems to be fixed by [[https://bugzilla.redhat.com/show_bug.cgi?id=485734|https://bugzilla.redhat.com/show_bug.cgi?id=485734]]) +* Some snd-ice1712 supported chips #334 +* snd-ens1371 [[http://mailman.alsa-project.org/pipermail/alsa-devel/2009-February/014929.html|http://mailman.alsa-project.org/pipermail/alsa-devel/2009-February/014929.html]] +* snd_es1938 +* snd_azt3328 (hardware period size is half of buffer size, yet its struct snd_pcm_hardware pretended full buffer size, azt3328 patch has since been committed as of 2011-02-28; this now means that tsched works yet tsched=0 does NOT! - for some weird reason) +Regarding snd-emu*: Creative doesn't like Open Source -- there are no docs available. If you buy Creative it is hence a bit your own fault. + +In all cases except for ice and emu the problem is the unreliability of snd_pcm_avail(). + +Also, even if your hardware/driver setup might be listed above it doesn't mean that g-f won't work for you at all. I have seen problems with those chips above, but one shouldn't necessarily take pars-pro-toto here. Especially since newer driver versions might already have fixed all or some of the issues. + +Possible workarounds to make PA work on these chips are: + +* - Disabling glitch-free mode. I.e. pass tsched=0 to the alsa modules or module-hal-detect +Other problematic drivers: + +* - Some drivers block the CPU for too long and inhibit PA from getting scheduled in time. (Particularly problematic are closed sources drivers -- hey Ubuntu that means you! nvidia/ndis. latencytop might be useful) +**This is how you can help fixing these issues:** + +Please download alsa-time-test.c: + + +[[!format txt """ +wget -O alsa-time-test.c http://cgit.freedesktop.org/pulseaudio/pulseaudio/plain/src/tests/alsa-time-test.c +"""]] +Compile it: (this obviously requires gcc to be installed as well as the alsa-lib-devel package -- that's the Fedora name, no clue what other distros call that (Ubuntu: libasound2-dev)) + + +[[!format txt """ +gcc -Wall -Wextra -O0 -g alsa-time-test.c -o alsa-time-test `pkg-config --cflags --libs alsa` -lcheck +"""]] +Now run it: + + +[[!format txt """ +./alsa-time-test hw:0 > log +"""]] +(Before running this make sure that nothing blocks the audio device, i.e. kill a running pulseaudio! Also, make sure to pass the correct device string. i.e. if the card in question is not hw:0 change this in the command line! Also, while you run this make sure NOT to run any other program that might cause this tool to get less CPU time than it wants. I.e. the CPU must be _completely idle_ otherwise. alsa-time-test needs all available CPU time.) + +This will run forever, unless an assertion is hit. This will generate a *lot* of data. So make sure you have enough disk space before you run this (a limited-space alternative is to create a fifo/pipe, probably via 'mknod', redirect output to it and then 'cat' out of it into a separate _newly startable_ log file as needed). If after a while an assertion is hit, please send me an email containing the exact message of the assert as well as the beginning and the end of 'log' (You can generate that with 'head -n 50 log' resp. 'tail -n 50 log'). If after 30mins still no assertion is hit then contact me. You might need to send me the entire log (compress it first with gzip) -- but please do that only _after_ contacting me since this is a **lot** of data. Also, I am not interested in duplicates. If you write me an email like this, please also include the lspci line for your card (i.e. 'lspci | grep Multimedia audio controller') as well as the driver name ('lsmod | grep snd_'), and finally the contents of /proc/asound/pcm for the card in question. Please understand that I want to keep my signal-to-noise ratio high, so please DO NOT SEND ME more than this unless I ask for it. My address is lennart poettering net. If the logged data gets too large that is generated this might cause some considereable IO load in which case the tool might get temporarily stopped to finish IO. Hence it might be a good idea to simply pipe the output directly to tail, to make sure no data needs to be written to disk during the run. + +And don't forget, unless you sent me the requested output you have no right to complain! + +Please do not send me this data unless you are sufficiently sure that this is actually a driver problem, i.e. not an application problem! How do you figure out those cases? Try running "pulseaudio -vvvv" and look for suspicious log output regarding detected driver bugs or underruns. + +I already got this data for snd-intel8x0, es1969, snd-ens1371, emu10k1 and snd-intel-hda on AD1989B, STAC92xx, ALC883 (reports for other hda implementations very welcome). Please do not send me any logs for these drivers! + +Thank you! + +If you want to understand the ouput of this tool, here's what it does: It enters a busy loop, writing one sample to the device at a time (unless the card's buffer is already filled up), then querying the various timing parameters of the card. And then the next iteration happens, and so on, and so on. The values printed contain the following information: + +The first column is clock_gettime(CLOCK_MONOTONIC) in us. Second column in the timestamp stored in the snd_pcm_state_t. The third is the calculated playback time (i.e. write count - delay). The fourth column is sample count, the fifth column is avail, the sixth is delay. But better have a look at the .c source file (the printf at the end), since the information on this page was outdated. + +For further details about this debugging, please see the thread "Timer instability", [[http://www.spassets.com/forums/linux.alsa.devel/273962/Timer%20instability|http://www.spassets.com/forums/linux.alsa.devel/273962/Timer%20instability]] diff --git a/Software/PulseAudio/Backends/ALSA/Decibel.mdwn b/Software/PulseAudio/Backends/ALSA/Decibel.mdwn new file mode 100644 index 00000000..011e1259 --- /dev/null +++ b/Software/PulseAudio/Backends/ALSA/Decibel.mdwn @@ -0,0 +1,44 @@ + +[[!inline pages="Software/PulseAudio/TOC" quick="yes" raw="yes"]] [[↩ Back to ALSA|Software/PulseAudio/Backends/ALSA]] + + +# Debugging Bad dB Information of ALSA Drivers + +If (when flat volumes are enabled in PulseAudio) the playback volume of one stream changes whenever another stream is played, this is most likely caused be incorrect dB attenuation data exposed by the ALSA kernel driver. + +To debug and verify that via a listening test, use the "dbverify" tool from by "dbmeasure" tool set: + + +[[!format txt """ +http://git.0pointer.de/?p=dbmeasure.git +git://git.0pointer.de/dbmeasure.git +"""]] +The tool requires only minimal dependencies: besides the libc headers only the alsa headers. It is independent of PulseAudio. After a git checkout and a "make", you may run dbverify like this: + + +[[!format txt """ +$ ./dbverify Aureon51MkII Master 30 200 +"""]] +This will test the dB data of the "Master" mixer control of the "Aureon51MkII" sound card for the mixer volume steps 30 and 200 (note that this assumes you have at least 200 volume steps. How many you have depends on hardware and driver. See below). The list of sound card ids for the first parameter you may find by issuing: + + +[[!format txt """ +$ cat /proc/asound/cards +"""]] +The ALSA card ID string is enclosed in []. Instead of card names you may also use ALSA card indexes as first parameter to dbverify. The list of suitable mixer controls for the second parameter of dbverify you may list with: + + +[[!format txt """ +amixer -D hw:Aureon51MkII | grep "Simple mixer control" +"""]] +If the third and fourth parameter to dbverify are ommited, the tool will test the loudest volume setting against the softest one. If those arguments are specified the tool will compare these two discrete volumes. It is advisable to play around with these values to compare multiple volume steps of the hardware. It is especially wise to pick your own values if the lowest hw volume setting is too silent to be audible. That said it might make sense to omit these arguments when starting your testing. This will then also show you the available volume step range of your card and you can then pick other values to tes from that range. + +The tool will play a 1s sine wave twice and in a loop, and attenuate it once in software and once in hardware. The effect should be that the wave should have the same volume both times if the dB information is reliable. If the dB data is not correct, then they will have different volumes. + +The command line mentioned above will test the "Master" mixer element of your card. Of course, usually this is not the only mixer element in the audio pipeline, which means after you tested "Master" you might want to test "PCM" and "Speaker", too, and possibly others ("Front", ... the available controls depend on the card and driver). + +If this listening test reveals that the dB information of your driver is not correct, then please file a bug on your respective distribution bug tracker or the kernel bugzilla (and NOT the PulseAudio bug tracker!). If you want to help even more then consider measuring the correct dB data for your card. Use the dbmeasure tool from the same git repo for that. You'll need a loopback cable for that to connect line out with line in, a lot of time and a little bit of technical expertise. For more details see the [[README|http://git.0pointer.de/?p=dbmeasure.git;a=blob_plain;f=README]] of dbmeasure. Make sure to file a bug in your distributions bug tracker/kernel bugzilla and ask for your data to be included as a quirk update for your driver (that means also include the output of alsa-info.sh --no-upload in that bug report). + +There's a temporary workaround to make PA skip the invalid dB data. But ha! I won't write down how that works here, to make sure that you really file that bug. Muahaha. Mauahahahahah! + +Also see the [[original announcement mail for dbverify|http://mailman.alsa-project.org/pipermail/alsa-devel/2010-February/025213.html]]! diff --git a/Software/PulseAudio/Backends/ALSA/Issues.mdwn b/Software/PulseAudio/Backends/ALSA/Issues.mdwn new file mode 100644 index 00000000..f4fcbc0f --- /dev/null +++ b/Software/PulseAudio/Backends/ALSA/Issues.mdwn @@ -0,0 +1,61 @@ + +[[!inline pages="Software/PulseAudio/TOC" quick="yes" raw="yes"]] [[↩ Back to ALSA|Software/PulseAudio/Backends/ALSA]] + + +# List of ALSA Issues + +Here's my list of issues I found with the current ALSA API while developing PA: + + +## Mixer + +* There's no way to detect whether a snd_smixer element is implemented in software or not. Thus writing an application that uses the PCM device hw: (or front:, surround51:, ...) and the smixer/mixer interfaces at the same time with sensible behaviour is impossible. Because for those devices software volume adjustments don't take place, and thus the controls we find are useless. +* There is no way to find the right mixer device for a PCM device. There is no way to find which one is the right mixer track to use to control input and output PCM volume, other then guessing by the name. +* ctl, hctl, mixer, smixer. Come on! +* It is not possible to enumerate the ctl/hctl elements that make up a smixer element. +* It is possible to query the dB range of a smixer element. And it is possible to query and set the current dB level. However, it is not possible to have a dB value converted to an integer level or vice versa, without touching the actual setting. i.e. a question like "What is the integer level 0 dB corresponds to?" can not be answered by ALSA. Which happens to be a serious limitation. **Update:** [[This seems fixed now|http://mailman.alsa-project.org/pipermail/alsa-devel/2008-April/007322.html]] +* the dB scale is is almost useless. dB is a relative scale and ALSA didn't define what the reference level is. All mixer controls on all sound drivers use different reference levels. Hence the dB scale is not any more useful than that they are pretty to look at and make you feel like oh-i-am-such-a-guru-i-look-at-dB-levels. +* Naming hinting apparently cannot be used to enumerate mixer devices. +* It's not possible to know the inter-relation of ctls (except single switch/track couple), and the relation with actual devices: internal mic, loudspeaker, laptop red jack, rear green jack, usb headset mike (or at least, this is quite tricky, or not well exposed) +* Multichannel mixer controls are not exposed properly: [[http://mailman.alsa-project.org/pipermail/alsa-devel/2008-October/011830.html|http://mailman.alsa-project.org/pipermail/alsa-devel/2008-October/011830.html]] +* The dB data exposed is sometimes bogus. e.g. on many cheaper USB devices alsa says the volume range is from one dB value to the same dB value. + +## PCM + +* Timestamps such as state->tstmp are in CLOCK_REALTIME, there's no way to use CLOCK_MONOTONIC instead, which makes them kind of impractical to use. **Update:** Since 1.0.16 they are supposed to be CLOCK_MONOTONIC, [[but actually they are still useless|http://mailman.alsa-project.org/pipermail/alsa-devel/2008-April/007044.html]]. **Update 2:** There is now [[snd_pcm_hw_params_is_monotonic() in alsa-lib HG|http://mailman.alsa-project.org/pipermail/alsa-devel/2008-April/007067.html]]. **Update 3:** Unfortunately that call doesn't work: [[http://mailman.alsa-project.org/pipermail/alsa-devel/2009-February/014839.html|http://mailman.alsa-project.org/pipermail/alsa-devel/2009-February/014839.html]] +* There is no way to detect in advance (i.e. when setting up the hw parameters) if _rewind() would ever work on a device, thus making this functionality pretty much useless. **Update:** There is now [[snd_pcm_hw_params_can_forward in alsa-lib HG|http://mailman.alsa-project.org/pipermail/alsa-devel/2008-April/007067.html]]. I am happy! +* There's no way to disable implicit sample type, channel map conversion in plughw:. You either get a fancy-we-do-it-all device (plughw:), or a completely raw device (hw:), there's no way to selectively disable/enable any of the additional features of plughw, except for resampling. That includes the previously mentioned sample type conversion or channel map, and softvol. **Update:** This is fixed now, the SND_PCM_NOAUTO_xxx flags in 1.0.16 offer exactly what I need. +* There's no way to query the active channel map for a device +* [[Device enumeration is completely broken and useless|https://bugtrack.alsa-project.org/alsa-bug/view.php?id=3570]], and not useful for hotplug +* There's no way to detect whether spdif: can be used at the same time as any of the ther other PCM devices (i.e. front: or suchlike) of the same card or if they are exclusive. There is no API to query if opening a certain PCM device with a specific configuration will make a related PCM device return EBUSY. (i.e. there seem to be some devices where opening a 6ch output stream will cause opening the device for capturing to return EBUSY) +* There's no way to disable the buffer management of ALSA, it insists on deciding what a full or an empty buffer is. It is not possible to be notified about interrupts, independantly of the buffer fill level via poll(). +* The is no device string for mono-only devices in style of "front:", "surround50:" and suchlike. +* There is no way to disable fragment interrupts for a device entirely, which would be useful in [[timer-based scheduling|http://0pointer.de/blog/projects/pulse-glitch-free.html]]. **Update:**' This apparently has been fixed at least partially, there is now snd_pcm_sw_params_set_period_event(). +* There is no API to query the granularity of snd_pcm_delay() +* The devices with an explicit channel mapping (i.e. "surround41:", ...) cannot be used for 10ch and 12ch sound cards. There is also no definition for surround91: and surround111. +* [[The buffering model has major issues.|http://mailman.alsa-project.org/pipermail/alsa-devel/2008-April/007354.html]] [[Another iteration of the story.|http://mailman.alsa-project.org/pipermail/alsa-devel/2008-June/008381.html]] Different drivers implement completely different logic for snd_pcm_delay(), e.g. for USB hw snd_pcm_delay() is way off what should really be returned. "Fast" buffer emptying after playback start is not communicated to the application. +* An application which wants to use surround sound has no chance to do so in any sensible way unless it goes directly to the hw devices "surround41:0" and so on. This kicks virtual drivers like PA out of the game however. This boils down to: no practical surround sound for ioplug based plugins. For ioplug based plugins only stereo and mono can be implemented sensibly. +* Currently there is no point in opening "default" in anything but 1ch or 2ch, since otherwise the channel mapping is unknown. +* Async PCM is evil. [[Signals suck|http://mailman.alsa-project.org/pipermail/alsa-devel/2008-May/008030.html]]. +* The maximum buffer size on HDA is a too small for real good glitch-free: [[http://mailman.alsa-project.org/pipermail/alsa-devel/2008-June/008550.html|http://mailman.alsa-project.org/pipermail/alsa-devel/2008-June/008550.html]] +* snd_pcm_rewind() breaks playback and returns nonsense, unless the naked audio device (hw) is accessed. (i.e. *all* plugins such as softvol break snd_pcm_rewind()) (**Update:** This has been fixed in alsa-lib git shortly after the 1.0.17 release) +* The "multi" plugin (and a couple of other drivers as well) sends POLLOUT but then snd_pcm_update_avail() returns 0: [[http://mailman.alsa-project.org/pipermail/alsa-devel/2008-October/011842.html|http://mailman.alsa-project.org/pipermail/alsa-devel/2008-October/011842.html]] +* I want something that tells my how long it is possible to sleep before an underrun happens. [[http://mailman.alsa-project.org/pipermail/alsa-devel/2009-January/014020.html|http://mailman.alsa-project.org/pipermail/alsa-devel/2009-January/014020.html]] +* There is no way to fetch the timestamp, the delay, and the avail value that belong together. [[http://mailman.alsa-project.org/pipermail/alsa-devel/2009-February/014839.html|http://mailman.alsa-project.org/pipermail/alsa-devel/2009-February/014839.html]] + +## ioplug + +* [[ioplug is in a really bad state|https://bugtrack.alsa-project.org/alsa-bug/view.php?id=2601]]. +* There is no way to reflect back XRUN states to the application + +## General + +* Documentation is really bad. Misses documentation of what terms like "trigger" mean and suchlike. However, terms like that are used extensively in the documentation. The examples from the documentation lack any comments. +* The API is *way* too verbose and large. There are too many functions that seem to be obsolete today, or that are completely redundant, or should only be used internally, and not be exported, or even appear in the documentation. +* The API is *way* overengineered. Even if the four abstraction levels of the mixer (ctl, hctl, mixer, smixer) might make some technical sense, there is no point whatsoever to export them all in the user interface. This applies to other stuff in the API as well. +* The library spams to stderr. On my mono usb soundcard (a webcam) opening the PCM device via "front:" (which rightfully fails) produces a lot of noise on stderr, which apparently cannot be disabled. And there are lots of similar cases. **Update:** There's snd_lib_error_set_handler() which can be used to stop this. +* Nobody cares about the [[ALSA BTS|https://bugtrack.alsa-project.org/alsa-bug/]]. Bugs are posted there and forgotten. + +## Individual drivers + +(semi-off-topic) For a list of various ALSA drivers with PA-related bugs, see [[Broken Sound Drivers|Software/PulseAudio/Backends/ALSA/BrokenDrivers]]. diff --git a/Software/PulseAudio/Backends/ALSA/Profiles.mdwn b/Software/PulseAudio/Backends/ALSA/Profiles.mdwn new file mode 100644 index 00000000..df737808 --- /dev/null +++ b/Software/PulseAudio/Backends/ALSA/Profiles.mdwn @@ -0,0 +1,169 @@ + +[[!inline pages="Software/PulseAudio/TOC" quick="yes" raw="yes"]] [[↩ Back to ALSA|Software/PulseAudio/Backends/ALSA]] + + +# Writing pulseaudio profiles + + +## Intended audience + +If you have non-standard sound hardware that is not supported well enough by PulseAudio out of the box, and it falls under approximately one of the following categories: + +* Your hardware cannot be opened with the front:x string that PulseAudio uses by default, and you haven't fixed this at the alsa-lib layer (see your /usr/share/alsa/cards/ for examples of how that is done) +* Your hardware does not expose normal volume control names such as "Master", "PCM", "Headphone" etc but instead e g "Megaphone" and "Leslie speaker". +* Your hardware has a "Ultra Disturb-Your-Neighbour Boom Bass" switch, which sounds slightly worse than a normal EQ, but you yet feel you have to expose it in the UI. + +## How PulseAudio processes config files + +You will have to do this in three steps: + +* you need an **udev rule** to match your device(s) +* you need a **profile set** file to specify how to open the device and what paths to be used +* you need one or more **path** files to specify what input/output is controlled by which volume controls + +### udev rule + +Have a look at `/lib/udev/rules.d/90-pulseaudio.rules` + +Either add to that or make your own to call your custom configuration, for example 91-pulseaudio.rules that could look something like this: + + +[[!format txt """ +SUBSYSTEM!="sound", GOTO="pulseaudio_end" +ACTION!="change", GOTO="pulseaudio_end" +KERNEL!="card*", GOTO="pulseaudio_end" + +SUBSYSTEMS=="pci", RESULT=="?*", ATTRS{vendor}=="0x8086", ATTRS{device}=="0x1c20", ENV{PULSE_PROFILE_SET}="pulseaudio-conexant.conf" + +LABEL="pulseaudio_end" + +"""]] +During the system start, when the card is detected, the PULSE_PROFILE_SET variable will be set in the udev database, and PulseAudio will be forced to use pulseaudio-conexant.conf. We will explain later how to fake that event for debugging. + +[[Here's a guide|http://www.reactivated.net/writing_udev_rules.html]] about how to write your own udev rules. + + +### pulseaudio profile set + +The file mentioned in udev rule, (e g "pulseaudio-conexant.conf") must exist in `/usr/share/lib/pulseaudio/alsa-mixer/profile-sets` + +In the beginning of default.conf, you can see comments describing file format, but not in a great details. Here is an example of the statements from the real file: +[[!format txt """ +[Mapping analog-stereo] +device-strings = front:%f hw:%f +channel-map = left,right +paths-output = analog-output analog-output-speaker analog-output-desktop-speaker analog-output-headphones analog-output-headphones-2 analog-output-mono analog-output-lfe-on-mono +paths-input = analog-input-front-mic-cx analog-input-rear-mic-cx analog-input-mic-cx analog-input-linein-cx +priority = 10 +"""]] +`device-strings` describes the ALSA device string(s) that PulseAudio uses to open the device, where "%f" specifies the card number (should always be present in the string). + +`paths-output` and `path-input` specify names of different paths with .conf added(See next bullet) + + +### pulseaudio paths + +PulseAudio path files must be located in `/usr/share/lib/pulseaudio/alsa-mixer/paths`. + +You need to specify one file per "Use Case", e g "Headphone output" and "Speaker output" would be two different files. + +Here's a quick one to see the inputs and outputs for your HDA card: `ls /proc/asound/card*/codec* | xargs grep "\[\(Jack\|Fixed\|Both\)"` + +Let's take `analog-input-rear-mic-cx.conf` as an example + +Some explanation can be found in `analog-output.conf.common` + + +[[!format txt """ +[General] +priority = 89 +name = Rear Microphone + +[Element Rear Mic Boost] +switch = select +volume = merge +override-map.1 = all +override-map.2 = all-left,all-right + +[Option Rear Mic Boost:on] +name = input-boost-on + +[Option Rear Mic Boost:off] +name = input-boost-off + +[Element Rear Mic] +switch = mute +volume = merge +override-map.1 = all +override-map.2 = all-left,all-right +required = any + +[Element Capture] +switch = mute +volume = merge +override-map.1 = all +override-map.2 = all-left,all-right + +[Element Input Source] +enumeration = select + +[Option Input Source:Rear Mic] +name = analog-input-microphone-rear + +[Element Capture Source] +enumeration = select + +[Option Capture Source:Rear Mic] +name = Rear Microphone + +[Element Mic] +switch = off +volume = off + +[Element Internal Mic] +switch = off +volume = off + +[Element Front Mic] +switch = off +volume = off + +[Element Dock Mic] +switch = off +volume = off + +.include analog-input-mic-cx.conf.common +"""]] +Under `[General]` `name` is the name that will be seen in pulseaudio Input/Output connector + + +[[!format txt """ +[Option Input Source:Rear Mic] +name = analog-input-microphone-rear +"""]] +name here is a name from alsa-mixer.c from pulseaudio sources (makes localization possible) + +It is a good idea to switch off unused `Element` TBD: If not done, does it disabled the whole path? + + +## Debugging + +Info From [[http://pulseaudio.org/ticket/624|http://pulseaudio.org/ticket/624]] + +To test the attached profile without going through udev: + +You should be able to place that in a file in `/lib/udev/rules.d/90-pulseaudio.rules` or create a new one `/lib/udev/rules.d/91-pulseaudio.rules`. And then try it out with +[[!format txt """ +sudo udevadm trigger -ssound +"""]] + + +You will see a speaker indicator blinks and pulseaudio GUI is updated. Now restart pulseaudio by +[[!format txt """ +pulseaudio -k +"""]] +* also can check which profile is used by + +[[!format txt """ +udevadm info -qall -p /sys/class/sound/card0/ +"""]]
\ No newline at end of file diff --git a/Software/PulseAudio/Backends/Bluetooth.mdwn b/Software/PulseAudio/Backends/Bluetooth.mdwn new file mode 100644 index 00000000..c5cc84b2 --- /dev/null +++ b/Software/PulseAudio/Backends/Bluetooth.mdwn @@ -0,0 +1,19 @@ + + +# Instructions to make it work right now + +[[http://www.fedoraforum.org/forum/showthread.php?t=190468|http://www.fedoraforum.org/forum/showthread.php?t=190468]] + + +# Future ideas + +[[https://tango.0pointer.de/pipermail/pulseaudio-discuss/2008-June/001909.html|https://tango.0pointer.de/pipermail/pulseaudio-discuss/2008-June/001909.html]] + +[[http://wiki.bluez.org/wiki/PulseIntegration|http://wiki.bluez.org/wiki/PulseIntegration]] + + +## Bluetooth keys + +Should perhaps be integrated with gnome settings daemon: + +[[http://svn.gnome.org/viewvc/gnome-settings-daemon/tags/GNOME_SETTINGS_DAEMON_2_22_2/plugins/media-keys/gsd-media-keys-manager.xml?view=markup|http://svn.gnome.org/viewvc/gnome-settings-daemon/tags/GNOME_SETTINGS_DAEMON_2_22_2/plugins/media-keys/gsd-media-keys-manager.xml?view=markup]] diff --git a/Software/PulseAudio/Backends/Bluetooth/Issues.mdwn b/Software/PulseAudio/Backends/Bluetooth/Issues.mdwn new file mode 100644 index 00000000..81fb86d8 --- /dev/null +++ b/Software/PulseAudio/Backends/Bluetooth/Issues.mdwn @@ -0,0 +1,20 @@ + +My little list of things I'd like to see fixed in BlueZ: + +* A lot of [[PropertyChanged|PropertyChanged]] signals are sent for properties that haven't actually changed. e.g. each time a device connects/disconnects the [[PropertyChanged|PropertyChanged]] signals for Name and Alias are sent out. It would be good if those could be surpessed. +* /me doesn't like parsing XML for finding out which interfaces are supported by a device. Hence I would prefer a function [[ListInterfaces|ListInterfaces]]() or suchlike to find out which interfaces are implemented. +* It would be good if ipc.[ch] would allow querying the configuration of the current active connection +* It would be good if sbc.[ch] could be compiled with -Wsign-compare without any warnings +* Also, it would be good if ipc.[ch] would be ANSI C conforming. I.e. use "unsigned u:6" instead of "uint8_t u:6" in structs -- what's "uint8_t u:6" supposed to mean anyway? An unsigned 8 bit integer that is 6 bits wide? Uh? Also instead og gcc-only zero-sized arrays as in "foo[0]" its better to use c99 flexible arrays as in "foo[]" +* The Bluetooth Applet needs a nice way to connect to audio devices. Best would be right inside the applet menu like they have on MacOS ([[bug 573759|http://bugzilla.gnome.org/show_bug.cgi?id=573759]]) +* The Bluetooth Applet/Wizard/Properties are a bit weird to use if no BT hw is available. There is no warning about that! The Wizard will silently find no devices. The Applet will gray out all menu options except the "Preferences" and "Setup new device". The latter should probably be grayed out, too. The "Preferences" dialog will be weirdly empty with again no warning that no bt adapter is found! ([[bug 573779|http://bugzilla.gnome.org/show_bug.cgi?id=573779]] and [[bug 573376|http://bugzilla.gnome.org/show_bug.cgi?id=573376]]). +* ~~I don't understand the differnces between the right and the left-click menu in the applet. Why make a difference at all?~~ (Fixed in gnome-bluetooth) +* ~~The "Preferences" menu items needs "..." too since it also shows a dialog.~~ (Fixed in gnome-bluetooth) +* ~~Shouldn't it read "Temporarily visible" instead of "Temporary visible"?~~ (This doesn't exist anymore in gnome-bluetooth) +* It would be good if the applet would try to connect to all devices it was previously connected to (or maybe that have been flagged that way?) when the GNOME session starts. I'd expect that if i power on my laptop and my headset at the same time they'll just work. But without a connection attempt from the PC's side this is not going to happen due to the longer bootup time of the PC. ([[bug 573759|http://bugzilla.gnome.org/show_bug.cgi?id=573759]] as well) +* Hmm, I have doubts that putting codec_capabilities_t in bt_get_capabilities_rsp::data just like that is safe in regards of alignment. +* /me wonders about the rationale behind make some structs typedefs and others not. +* the header files could need a bit of more documentation on what's going on. Especially sbc.h +* sbc.h should use const pointers where applicable. +* sbc.h should use size_t and other types appropriately instead of "int" everywhere. +* Hmm, why isn't the D-Bus logic implementing org.freedesktop.Properties?
\ No newline at end of file diff --git a/Software/PulseAudio/Desktops/KDE.mdwn b/Software/PulseAudio/Desktops/KDE.mdwn new file mode 100644 index 00000000..7cf2d5d5 --- /dev/null +++ b/Software/PulseAudio/Desktops/KDE.mdwn @@ -0,0 +1,98 @@ + +[[!toc ]] + + +# KDE PulseAudio Integration + +This document describes how the [[PulseAudio|PulseAudio]] integration in KDE works and some thoughts for the future. + +I'll describe things first at a high level (i.e. what you should expect to see) and then go on to describe how things work in the lower levels for those that are interested in such things! + +Firstly there are two primary areas of KDE in which [[PulseAudio|PulseAudio]] support is needed: Phonon (the media playback system used by most KDE applications) and KMix (the mixer application used to control device volumes). [[Colin Guthrie|http://colin.guthr.ie/]] has contributed code to integrate [[PulseAudio|PulseAudio]] into both these components. + + +## Phonon + +With regards to a properly integrated Phonon, you can verify that your build supports [[PulseAudio|PulseAudio]] by going to "System Settings" → "Multimedia" (on some distros the "Multimedia" tab is labelled as "Audio and Video Settings"). If all is well, you should see a screen similar to the following: + +[[!img phonon-pulse-working-full.png] + +_NB, the "Speaker Setup" tab in the above screen shot will be/is part of KDE 4.6: See [[Speak(er Setup) now, or Forever hold your Peace|http://colin.guthr.ie/2010/07/speaker-setup-now-or-forever-hold-your-peace/]]_. + +The devices shown will obviously be different on your system, however 99% of systems will have an "Internal Audio Analog Stereo" listing (or an "Internal Audio Digital Stereo" entry). To cross reference, the command `pacmd list-sinks | grep device.description` should list the same device names as the active (i.e. non-greyed out) outputs. + +If you do not see this full list, you may see simply a single [[PulseAudio|PulseAudio]] entry like this: + +[[!img phonon-pulse-working-half.png] + +This generally implies that Phonon has been compiled correctly with [[PulseAudio|PulseAudio]] support but that the KDE-specific support module for [[PulseAudio|PulseAudio]] has not been loaded. This module (called module-device-manager) can be started manually by running the script "start-pulseaudio-kde" which should be shipped with [[PulseAudio|PulseAudio]] since 0.9.21. This file is launched on startup via an XDG compliant .desktop file (`/etc/xdg/autostart/pulseaudio-kde.desktop`). + +Finally you may see a list that looks more like this: + +[[!img phonon-pulse-broken.png] + +This indicates that [[PulseAudio|PulseAudio]] support is NOT enabled in your Phonon build, or that [[PulseAudio|PulseAudio]] itself is not running when the config dialog was launched. On most systems where [[PulseAudio|PulseAudio]] is deployed, it is configured to auto-spawn, so this is an unlikely scenario in which to find yourself. + +If you find yourself in the last state, you should contact your distro (i.e. via their bug reporting tool) and request that they include [[PulseAudio|PulseAudio]] support in their Phonon package and refer them to the [[Phonon Build Instructions|Software/PulseAudio/Desktops/KDE]]. + + +## KMix + +KMix provides a general purpose mixer to adjust device volumes under KDE. With properly integrated [[PulseAudio|PulseAudio]] support, it is also possible to control individual application volumes too as well as move specific applications to different devices (although using the Category-based device preferences in Phonon configuration above is generally preferred). + +If you KMix installation is properly compiled with PA support (full support is included in KDE 4.5 and patches against 4.4 can be found via Colin Guthrie's [[GIT repository|http://colin.guthr.ie/git/]] - simply clone the repo and run `git diff master..pulse` to get a patch that should apply to your KDE Multimedia 4.4 source), you should see the following UI: + +[[!img kmix-pulse-working.png] + +The primary UI will always consist of four fixed tabs - in contrast to the traditional KMix which shows one tab per device. The tabs should be self explanatory, but the first tab will automatically show any new devices when they become available. If you wish to control individual channels, simply right click on the slider and choose the "Split Channels" option. + +If you see a more traditional KMix interface like this: + +[[!img kmix-pulse-broken.png] + +Then chances are that if you see this interface, your KDE Multimedia package was not compiled with support for [[PulseAudio|PulseAudio]] (as above, PA is generally configured to auto-spawn when needed, so it should be running when KMix starts). If this is the case, you should again contact your distro and ask them to integrate support. + + +## Potential Problems + +One thing that can happen is that some other process "hogs" the audio device during [[PulseAudio|PulseAudio]] startup. When this happens PA is unable to use the device until it is restarted. If PA is unable to open your hardware, you will automatically be given a "Dummy Output". As the name suggests, anything that is "Played" via this device is inaudible). This "Dummy Output" should be easily visible in both KMix and Phonon. If this happens, then you can debug which process is hogging the hardware via the command: `sudo lsof /dev/snd/* /dev/dsp*` (Note that apps which have the `/dev/snd/control*` devices open are unlikely to interfere). + +If you need to restart [[PulseAudio|PulseAudio]], generally a reboot is simplest. Alternatively, issue the commands: `pulseaudio -k; start-pulseaudio-x11; start-pulseaudio-kde`. The first command will kill the running daemon, then the second two start [[PulseAudio|PulseAudio]] and load some additional modules that are normally loaded as part of your typical login procedure. Please note that some applications may require to be restarted after restarting [[PulseAudio|PulseAudio]]. + + +## Reporting Bugs + +When reporting bugs either to your distro (preferred), KDE or directly here to the [[PulseAudio|PulseAudio]] project, you should include at least the following information in your bug report: + +* The output of `pacmd ls` (preferably grabbed when a stream is playing - even if you cannot hear anything). +* The output of `amixer -c0` (where 0 is the card number, if you have multiple cards, please include the output for all cards). +* The output of `sudo lsof /dev/snd/* /dev/dsp*` (`sudo` just runs this command as root, you are welcome to use a different mechanism to issue the command as root if you prefer) +* The output of `getfacl /dev/snd/*` +In order to obtain a debug log from [[PulseAudio|PulseAudio]] itself there are two ways: + +1. Rerun pulseaudio via the console and copy/paste the output +1. Turn up the debug level in `/etc/pulse/daemon.conf` (log-level = debug) and copy/paste from syslog (grep pulseaudio /var/log/message). +The first option is generally more useful for hardcore debuggers but it does sometimes come with problems - namely the fact that [[PulseAudio|PulseAudio]] will autospawn itself when needed in it's default setup which can make running it manually a bit tricky!. Normally you would do something like: `pulseaudio -k; pulseaudio -vvvvv`. This kills the currently running process of PA and then immediately starts a new one, but turns up verbosity and stays in the foreground. If you get an error message that mentions "E: main.c: pa_pid_file_create() failed." then chances are, PA automatically respawned between the two commands. Typically running the command a few times will allow the timing to work, but sometimes it can take a while and method 2 becomes more practical. You can also disable autospawning via `/etc/pulse/client.conf` but this can cause some anomalies during startup (e.g. KMix not detecting PA support and loading in ALSA mode etc.), so isn't recommended unless you do a lot of debug work and know these issues. If you do use method 1, then you should run the scripts `start-pulseaudio-x11` and `start-pulseaudio-kde` in a separate terminal once PA has started up. These are normally run for you automatically at login, so you're just repeating those steps. + +For the second option, PA will need to be restarted for the changes in daemon.conf to take effect. A reboot is simplest, but running `pulseaudio -k; start-pulseaudio-x11; start-pulseaudio-kde` should also suffice. You can then grab the data from your syslog (as root) via `grep pulseaudio /var/log/messages`. Please try not to include unnecessary information and try and isolate the particular run that causes problems when including the debug log in bug reports. If you can, it would be great to annotate the log at particular points where some anomaly occurs. + + +## Distro Support + +The following Distributions are known to provide fully integrated support: + +* Mandriva: 2010.0 onwards +* Fedora: 13 onwards + +## Phonon Build Instructions + +Building Phonon is non-trivial due to the fact that there are actually two competing versions: one shipped with Qt itself and one maintained by KDE developers which is hosted on [[Gitorious|http://gitorious.org/phonon/phonon]] The latter version is needed for full [[PulseAudio|PulseAudio]] support. Currently version 4.4.1 + two [[additional|http://gitorious.org/phonon/phonon/commit/b44f19d7038f7e6182db4d29aee39dab5]] [[patches|http://gitorious.org/phonon/phonon/commit/1eb324f60f8df6bc7a866679919d79f1a]] is recommended. Version 4.4.2 will be released shortly. + +In order to have full support, it is generally recommended that you build Qt with Phonon support, but simply do not package/distribute the libraries and headers for phonon, then build a separate package from the Gitorious version to provide the actual libraries and headers. This is how it is done on Mandriva and it seems to work very well. + +Qt 4.7 should support building Phonon externally to deal more elegantly with this general problem. + + +## More Details + +Colin Guthrie outlined the work he did with the Phonon Support in a [[rather detailed post|http://colin.guthr.ie/2009/10/so-how-does-the-kde-pulseaudio-support-work-anyway/]]. It is not necessarily for the feint hearted, and not targeted at general user consumption! diff --git a/Software/PulseAudio/Desktops/KDE/kmix-pulse-broken.png b/Software/PulseAudio/Desktops/KDE/kmix-pulse-broken.png Binary files differnew file mode 100644 index 00000000..c928383f --- /dev/null +++ b/Software/PulseAudio/Desktops/KDE/kmix-pulse-broken.png diff --git a/Software/PulseAudio/Desktops/KDE/kmix-pulse-working.png b/Software/PulseAudio/Desktops/KDE/kmix-pulse-working.png Binary files differnew file mode 100644 index 00000000..edb65e6f --- /dev/null +++ b/Software/PulseAudio/Desktops/KDE/kmix-pulse-working.png diff --git a/Software/PulseAudio/Desktops/KDE/phonon-pulse-broken.png b/Software/PulseAudio/Desktops/KDE/phonon-pulse-broken.png Binary files differnew file mode 100644 index 00000000..ed4d1913 --- /dev/null +++ b/Software/PulseAudio/Desktops/KDE/phonon-pulse-broken.png diff --git a/Software/PulseAudio/Desktops/KDE/phonon-pulse-working-full.png b/Software/PulseAudio/Desktops/KDE/phonon-pulse-working-full.png Binary files differnew file mode 100644 index 00000000..862816db --- /dev/null +++ b/Software/PulseAudio/Desktops/KDE/phonon-pulse-working-full.png diff --git a/Software/PulseAudio/Desktops/KDE/phonon-pulse-working-half.png b/Software/PulseAudio/Desktops/KDE/phonon-pulse-working-half.png Binary files differnew file mode 100644 index 00000000..c9b5a13f --- /dev/null +++ b/Software/PulseAudio/Desktops/KDE/phonon-pulse-working-half.png diff --git a/Software/PulseAudio/Distributions/Ubuntu.mdwn b/Software/PulseAudio/Distributions/Ubuntu.mdwn new file mode 100644 index 00000000..52c3cece --- /dev/null +++ b/Software/PulseAudio/Distributions/Ubuntu.mdwn @@ -0,0 +1,19 @@ + + +## Ubuntu + +This page is for all users of Ubuntu. + +In their infinite wisdom, Ubuntu decided not to include pavucontrol in their default applications even although they enabled Pulseaudio by default. The reason for this relates to the apps non compliance to the HIG, which is a laudable goal, but sadly means that there is no way for users to control pulseaudio. + +Many users, it seems, resorted to padevchooser, but this is a terrible application that does not interface with Pulseaudio in the correct way and is also very misleading with regards to how to make your sound come out of the right device (or sink). + + +## Setting a 'default' sink + +This is a misnomer straight off. Pulseaudio does not really support a 'default' device in the way most people think. Pulse remembers which sink your application was last used with and restores it to that sink when it plays again. This means that the 'default' is only used the very first time an application uses sound. It should really be called a 'fallback' sink. Work is ongoing to support a more 'active' default. + + +## How do I make App X, output to Sink Y? + +Firstly, install pavucontrol and then run it. When you app is playing sound, it will appear in the Playback tab. Use the little menu there (with the down arrow on it) or right click on it and select "Move Stream". Pulse will remember this decision and will use this new sink from then on in for that application. diff --git a/Software/PulseAudio/Distributions/Ubuntu/Bugs.mdwn b/Software/PulseAudio/Distributions/Ubuntu/Bugs.mdwn new file mode 100644 index 00000000..f210bdbb --- /dev/null +++ b/Software/PulseAudio/Distributions/Ubuntu/Bugs.mdwn @@ -0,0 +1,24 @@ + + +# Reporting !PulseAudio Bugs You Experience in Ubuntu + +Please read the following notes before filing bugs against PulseAudio upstream if you encountered them on Ubuntu: + +* Unless you are very sure the problem is an upstream problem, **please report the bugs in [[Launchpad|https://bugs.launchpad.net/ubuntu/+source/pulseaudio/+filebug]]**, not the upstream bug tracking system. The Ubuntu developers will then escalate the bugs upstream if necessary. +* Ubuntu's PulseAudio packages have disabled a substantial number of core features. Please do not file bugs upstream at all that are directly or indirectly related to these areas: + * Flat volumes are disabled by default on Ubuntu 9.10 + * Realtime scheduling (through rtkit) is disabled on Ubuntu 9.10. It is enabled in the upcoming 10.04. + * libcanberra is non-trivially out-of-date (7 versions at the date of release of Ubuntu 9.10) + * Some additional modules have been removed from the Ubuntu packages, such as the JACK module + * In addition, Ubuntu 9.04 disables glitch-free by default. This is enabled in 9.10 and above. +* Please include proper package versions when reporting bugs. As upstream does not follow Ubuntu closely, Ubuntu distribution code names and versions might not be as well known by upstream as they are by you, the reporter. +* When filing a bug, please mention that you run Ubuntu. +(All of this was current on Nov 2009, at release of Ubuntu 9.10. Note that it is not our intention to discriminate against Ubuntu. It's simply that we get more bugs from Ubuntu users than from most other distributions. This has various reasons, but they all have in common that they make us prefer if Ubuntu users and maintainers would filter downstream issues before they get escalated to us.) + +Thank you! + +Please update this page: + + * Libcanberra in Ubuntu 10.10 is 0.25 (upstream stable is 0.26 atm). + * Jack module is [[included|http://packages.ubuntu.com/lucid/pulseaudio-module-jack]] in Ubuntu 10.04 and 10.10 + * Check if it is still true that "Ubuntu's PulseAudio packages have disabled a substantial number of core features".
\ No newline at end of file diff --git a/Software/PulseAudio/Documentation.mdwn b/Software/PulseAudio/Documentation.mdwn new file mode 100644 index 00000000..fc5625d0 --- /dev/null +++ b/Software/PulseAudio/Documentation.mdwn @@ -0,0 +1,10 @@ + +[[!inline pages="Software/PulseAudio/TOC" quick="yes" raw="yes"]] + + +# Documentation + +PulseAudio is an important part of Linux plumbing. As such documentation falls broadly into two primary categories: documentation for users who want to configure their systems to their own personal tastes and documentation for developers wanting to work on or with PulseAudio. For distribution packagers, the information you will need is mostly encompassed by the user documentation although it would make sense to familiarise yourself with at least the debugging sections of the developer documentation. +[[!table header="no" class="mointable" data=""" +[[User Documentation|Software/PulseAudio/Documentation/User]] • [[Developer Documentation|Software/PulseAudio/Documentation/Developer]] +"""]] diff --git a/Software/PulseAudio/Documentation/Developer.mdwn b/Software/PulseAudio/Documentation/Developer.mdwn new file mode 100644 index 00000000..2f6bec08 --- /dev/null +++ b/Software/PulseAudio/Documentation/Developer.mdwn @@ -0,0 +1,51 @@ + +[[!inline pages="Software/PulseAudio/TOC" quick="yes" raw="yes"]] [[↩ Back to Documentation|Software/PulseAudio/Documentation]] + + +# Developer Documentation + + +## Developing Clients + +You may browse the [[Doxygen|http://www.doxygen.org/]] generated [[programming documentation|http://freedesktop.org/software/pulseaudio/doxygen/]] for the client API. (Run make doxygen to generate this documentation from the source tree). + +If you want to write a volume control application, [[make sure to read this|Software/PulseAudio/Documentation/Developer/Clients/WritingVolumeControlUIs]]. + +**Also, make sure to set properties on all PA connections, [[make sure to read this|Software/PulseAudio/Documentation/Developer/Clients/ApplicationProperties]].** + +**Finally, [[make sure you know everything about latency control|Software/PulseAudio/Documentation/Developer/Clients/LactencyControl]]! ** + +Here are some examples that uses the async (complex) API, [[Sample Async Device List|Software/PulseAudio/Documentation/Developer/Clients/Samples/AsyncDeviceList]] and [[Sample Async Playback|Software/PulseAudio/Documentation/Developer/Clients/Samples/AsyncPlayback]]. + + +## Developing PulseAudio + +When working on PulseAudio, please mind the [[Coding Style|Software/PulseAudio/Documentation/Developer/CodingStyle]]. + + +### Developing Modules + +There are several reasons for writing loadable modules for PulseAudio: + +* Extended device driver support +* Protocol support beyond ESOUND's protocol and the native protocol. (such as NAS or a subset of aRts) +* New programming interfaces such as XMLRPC or DBUS for controlling the daemon. +* Hooking audio event sources directly into PulseAudio (similar to `module-x11-bell`) +* For low latency applications such as VOIP: load the VOIP core directly into PulseAudio and have a slim GUI frontend to control it. +There is currently a little bit of documentation available on how to write loadable modules for PulseAudio. Beyond this, read the source, Luke! If you are interested in writing new modules feel free to contact the authors in case you have any questions. + +* [[Writing Modules|Software/PulseAudio/Documentation/Developer/Modules]] +* [[Core API|Software/PulseAudio/Documentation/Developer/CoreAPI]] +* [[Module API|Software/PulseAudio/Documentation/Developer/ModuleAPI]] +* [[Module Arguments API|Software/PulseAudio/Documentation/Developer/ModuleArgumentsAPI]] +* [[Threading Model|Software/PulseAudio/Documentation/Developer/Threading]] +* [[A discussion about writing a sink|Software/PulseAudio/Documentation/Developer/IO]] +* [[Rewinding explained|Software/PulseAudio/Documentation/Developer/Rewinding]] +Some things that might be relevant for people hacking on specific modules: + +* [[BlueZ issues/limitations list|Software/PulseAudio/Backends/Bluetooth/Issues]] +* [[ALSA issues/limitations list|Software/PulseAudio/Backends/ALSA/Issues]] + +### Porting to other platforms + +* [[Building the sources on Mac OS X|Software/PulseAudio/Ports/OSX]]
\ No newline at end of file diff --git a/Software/PulseAudio/Documentation/Developer/CPULoad.mdwn b/Software/PulseAudio/Documentation/Developer/CPULoad.mdwn new file mode 100644 index 00000000..709d9144 --- /dev/null +++ b/Software/PulseAudio/Documentation/Developer/CPULoad.mdwn @@ -0,0 +1,13 @@ + + +# How To Debug CPU Load Bugs + +In some situations [[PulseAudio|PulseAudio]] ends up spinning in a loop eating 100% CPU time. This will then be detected by PA's internal CPU load limiter which will then cause a daemon shutdown with the messages "Soft CPU time limit exhausted, terminating" and "Hard CPU time limit exhausted, terminating forcibly." + +There might be multiple reasons for this: actual bugs in [[PulseAudio|PulseAudio]], or bugs in the ALSA drivers. Or simply clients that ask for very low latency, which results in high CPU load. (the latter you can find out by using "pacmd ls" and looking at the latency settings listed therein) + +[[Please use oprofile to gather some data about where the CPU load is lost|Software/PulseAudio/Documentation/Developer/OProfile]] + +It might be worth trying to disable timer scheduling (i.e. "glitch-free") by passing tsched=0 to module-hal-detect. When g-f is enabled PA will dynamically shorten wakeup times when an underrun is hit, to lower the chance that it happens again. Shorter wakeup times mean higher CPU load. Often enough the underruns are caused by broken timing of sound drivers. See [[Broken Sound Drivers|Software/PulseAudio/Backends/ALSA/BrokenDrivers]] for more information on that. + +Also, while debugging you probably want to disable the CPU load limiter by passing --no-cpu-limit. diff --git a/Software/PulseAudio/Documentation/Developer/Clients/ApplicationProperties.mdwn b/Software/PulseAudio/Documentation/Developer/Clients/ApplicationProperties.mdwn new file mode 100644 index 00000000..82b2100b --- /dev/null +++ b/Software/PulseAudio/Documentation/Developer/Clients/ApplicationProperties.mdwn @@ -0,0 +1,89 @@ + + +# Setting Application Properties + +PulseAudio allows setting of all kinds of properties for clients and streams. They are roughly modelled after X11 window properties, however typeless: usually formatted UTF-8 strings and sometimes binary. These properties can be used for a variety of purposes: for enhancing volume control UIs by showing icons/application names for clients/streams, for doing policy decisions (i.e. route 'phone' streams to a different device than 'music' streams) as well as effects (i.e. if we know which X11 window a stream belongs to we can implement 'volume-follows-focus'). + +The complete list of currently known client/stream properties is defined in [[proplist.h|http://0pointer.de/lennart/projects/pulseaudio/doxygen/proplist_8h.html]]. The list will be extended in the future. Some of these properties can be and are deduced automatically from the process environment, however others cannot and aren't. + +Only applications that directly call into the PA API or the libcanberra API may set those properties directly (for now at least). However, only the minority of code interfaces directly with those APIs. To allow setting the properties for other applications as well here are a few hints. For now this only describes how to set PA_PROP_APPLICATION_NAME, PA_PROP_APPLICATION_ICON_NAME, and PA_PROP_MEDIA_ROLE which are the most important ones and which are currently already being used in [[PulseAudio|PulseAudio]]. + +**Please note that none of the hints listed here requires you to add an explicit dependency on PA to your application in any way! ** Adding these lines will not influence the portability to other sound systems. In fact at least the Gtk+ related functionality listed here is something everyone should probably do, not just the folks doing audio/media programming. + + +## The 3-Line Summary for Gtk+ applictions + + +[[!format txt """ +int main(int argc, char *argv[]) { + ... + gtk_init(&argc, &argv); + ... + g_set_application_name(_("Totem Movie Player")); + gtk_window_set_default_icon_name("totem"); + g_setenv("PULSE_PROP_media.role", "video", TRUE); + ... +"""]] + +## PA_PROP_APPLICATION_NAME + +This property should contain a human readable, localized application name, e.g. "Totem Media Player", or suchlike. + +In GLib applications the PA client libraries will automatically use the application name that may be set via the GLib function g_set_application_name(). Hence make sure to call this function very early when starting up: + + +[[!format txt """ +g_set_application_name(_("Totem Movie Player")); +"""]] +In applications that do not use GLib you may instead set the environment variable PULSE_PROP_application.name: + + +[[!format txt """ +setenv("PULSE_PROP_application.name", _("Foobar Music Player"), 1); +"""]] +Please note that setting environment variables like this is a bit problematic: they are usually inherited by child processes, they are not particularly 'directed' and use awkward memory allocation. But it should be good enough for most cases at least for now. The [[PulseAudio|PulseAudio]] client libraries will look for all env variables starting with PULSE_PROP to initialize the properties that are sent to the PA server. + + +## PA_PROP_APPLICATION_ICON_NAME + +This property should contain an XDG icon name, e.g. as used in the .desktop file of your program. + +In Gtk applications the PA client libraries will automatically use the application icon name that may be set via the Gtk function gtk_window_set_default_icon_name(). Hence make sure to call this function very early when starting up: + + +[[!format txt """ +gtk_window_set_default_icon_name("totem"); +"""]] +Again, in non-Gtk applications use an environment variable: + + +[[!format txt """ +setenv("PULSE_PROP_application.icon_name", "foobar", 1); +"""]] + +## PA_PROP_MEDIA_ROLE + +This property should contain a short string that describes the role of a media stream, where role is one of: + +1. "video": for movie/video streams from media players +1. "music": for music streams from media players +1. "game": for audio from games +1. "event": for event sounds (i.e. button clicks, ...) +1. "phone": for phone data (i.e. voip speech audio) +1. "animation": for animations (i.e. Flash) +1. "production": for audio production applications. +1. "a11y": accessibility applications (i.e. screen readers, ...) +This is a property of the actual streamed data, not so much the application. However usually it is still safe to simply set a process-global environment variable. + +For Glib applications: + + +[[!format txt """ +g_setenv("PULSE_PROP_media.role", "video", TRUE); +"""]] +And for non-GLib applications: + + +[[!format txt """ +setenv("PULSE_PROP_media.role", "music", 1); +"""]]
\ No newline at end of file diff --git a/Software/PulseAudio/Documentation/Developer/Clients/DBus.mdwn b/Software/PulseAudio/Documentation/Developer/Clients/DBus.mdwn new file mode 100644 index 00000000..0657ebb0 --- /dev/null +++ b/Software/PulseAudio/Documentation/Developer/Clients/DBus.mdwn @@ -0,0 +1,453 @@ + + +# PulseAudio's D-Bus interface + +These pages should eventually contain the final D-Bus control interface specification. Currently it's just a draft, comments welcome. + + +## Recent Changes + +* 2012-12-15 + * Add the Ladspa interface. +* 2012-11-09 + * Add signals NewProfile and ProfileRemoved to the Card interface. +* 2012-02-15 + * Change the FallbackSink and FallbackSource semantics so that they can be unset at any time, also when there are sinks and sources present. +* 2011-04-15 + * Add property VolumeWritable to the Stream interface. + * Add error BadStateError. +* 2011-03-13 + * Removed references to "user bus". We will use the session bus, which will behave like a user bus in most systems in the future, hopefully. + * Documented the fact setting stream or device volumes can always be done using a single-channel volume structure, regardless of the real channel map. +* 2010-04-15 + * Change the RestoreEntry property behavior so that changes are applied immediately to existing streams also. +* 2009-08-31 + * Add signals FallbackSinkUnset and FallbackSourceUnset to the Core interface. + * Rename IsMuted everywhere to Mute. +* 2009-08-18 + * Change the volume type of Play and PlayToSink methods in the Sample interface from [Uint32] to Uint32. +* 2009-08-15 + * Add properties PlaybackStreams and RecordStreams to the Client interface. +* 2009-08-04 + * Rename AllMemblocks to AccumulatedMemblocks in Memstats. +* 2009-08-03 + * Add apply_immediately argument to StreamRestore1.AddEntry(). +* 2009-08-02 + * Add signals DeviceUpdated, VolumeUpdated and MuteUpdated to the stream restore entry interface. + * Make properties Device, Volume and IsMuted writable in the stream restore entry interface. + * Add GetEntryByName method to the stream restore interface. +* 2009-07-31 + * Change the non-extension object path prefix from /org/pulseaudio1/ to /org/pulseaudio/core1/. This way the core and the extensions have consistent object path prefix (/org/pulseaudio/). + * Add signals .Core1.NewExtension and .Core1.ExtensionRemoved. + * Rework the stream restore interface. +* 2009-07-15 + * Remove the sink argument from Sample.Play() and add new method Sample.PlayToSink(). +* 2009-07-12 + * Add Cards property to Core. +* 2009-07-09 + * Rearrange the channel position enumeration so that the numbering matches the one used internally and with the C API. +* 2009-07-01 + * Change the org.pulseaudio prefix to org.PulseAudio. + * Replace the lookup service's GetAddress method with the Address property. + * Remove sample loading methods that use files. Hide the difference between lazy and non-lazy samples. + * Add Sinks and Sources properties to Card. + * Prefix boolean properties with "Is" or "Has". + * Move FlatVolume property from Sink to Device. + * Change enumeration types from Byte to Uint32. + * Remove the Self interface, move the functionality to Core and Client interfaces. + * Move everything in the PlaybackStream interface to the Stream interface and remove PlaybackStream. + * Add StreamEvent to the Stream interface. + * Rename proplist -> property list. + * Change argument names to lowercase, as it seems to be the standard way (this statement is actually only based on that the D-Bus spec has them lowercase in the examples). + +## Overview + +Previously the only D-Bus services PulseAudio provided were an implementation of the [[Device Reservation spec|http://git.0pointer.de/?p=reserve.git;a=blob_plain;f=reserve.txt]] for sound cards and reservation of the org.pulseaudio.Server name on the session or system bus for server tracking purposes. Those features remain untouched, and this document doesn't have anything to do with them. + +The new functionality consists of two parts: a server lookup service and the main control interface. When clients want to use the control interface, they have to first figure out where they should connect to. How to connect to the control interface is specified on the [[ConnectingToServer|Software/PulseAudio/Documentation/Developer/Clients/DBus/ConnectingToServer]] page. The main control interface is provided as a "D-Bus server". That is, it's not available on any bus, but instead clients make direct connections to PulseAudio. + + +## Open Questions + +* Does it make sense for clients to save card names? If not, the .Core1.GetCardByName method is probably unneeded. +* Same for .Core1.Card.GetProfileByName. +* Same for .Core1.Device.GetPortByName. +* Do error cases need better documentation? The current guideline has been that if an error can be returned even if the situation is more like a special case than an error, it is explicitly documented. + +## Control API + +The detailed descriptions are spread to separate pages, roughly one per object type. This page provides only a minimal reference and links to the details. + + +### Notation + +* Arrays are written as [<type>]. For example, [Byte] is an array of bytes. +* Dictionaries are written as {<type1> -> <type2>}. For example, {String -> [Byte]} is a dictionary with strings as keys and byte arrays as values. +* Structs are written as (<type1>, <type2>, ..., <typeN>). For example (Byte, Uint32) is a struct with two members: a byte and an unsigned 32 bit integer. +* On this page only, property access is denoted with (r) for read and with (rw) for read/write. +* The rest should be obvious. + +### Property Lists + +Property lists (not to be confused with D-Bus properties) are dictionaries that are associated with many objects. The keys are utf-8 strings and the values are arbitrary data (usually they are utf-8 strings too, though). Property lists are used to attach many kinds of metadata to the objects: names, descriptions, intended roles and so on. For now the best source of information about available properties is the [[proplist.h|http://0pointer.de/lennart/projects/pulseaudio/doxygen/proplist_8h.html]] file documentation. + + +### General Server Functionality + +* Object **/org/pulseaudio/core1** implements interface **org.PulseAudio.Core1**. + +#### org.PulseAudio.Core1 + +[[Properties|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]]: + +* [[InterfaceRevision|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]] : Uint32 (r) +* [[Name|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]] : String (r) +* [[Version|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]] : String (r) +* [[IsLocal|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]]: Boolean (r) +* [[Username|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]] : String (r) +* [[Hostname|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]] : String (r) +* [[DefaultChannels|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]] : [Uint32] (rw) +* [[DefaultSampleFormat|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]] : Uint32 (rw) +* [[DefaultSampleRate|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]] : Uint32 (rw) +* [[Cards|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]] : [ObjectPath] (r) +* [[Sinks|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]] : [ObjectPath] (r) +* [[FallbackSink|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]] : ObjectPath (rw) # Doesn't exist when the fallback sink is unset. +* [[Sources|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]] : [ObjectPath] (r) +* [[FallbackSource|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]] : ObjectPath (rw) # Doesn't exist when the fallback source is unset. +* [[PlaybackStreams|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]] : [ObjectPath] (r) +* [[RecordStreams|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]]: [ObjectPath] (r) +* [[Samples|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]] : [ObjectPath] (r) +* [[Modules|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]] : [ObjectPath] (r) +* [[Clients|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]] : [ObjectPath] (r) +* [[MyClient|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]] : ObjectPath (r) +* [[Extensions|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]] : [String] (r) +[[Methods|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]]: + +* [[GetCardByName|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]](in name : String ; out card : ObjectPath) +* [[GetSinkByName|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]](in name : String ; out sink : ObjectPath) +* [[GetSourceByName|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]](in name : String ; out source : ObjectPath) +* [[GetSampleByName|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]](in name : String ; out sample : ObjectPath) +* [[UploadSample|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]](in name : String, sample_format : Uint32, sample_rate : Uint32, channels : [Uint32], default_volume : [Uint32], property_list : {String -> [Byte]}, data : [Byte] ; out sample : ObjectPath) +* [[LoadModule|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]](in name : String, arguments : {String -> String} ; out module : ObjectPath) +* [[Exit|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]]() +* [[ListenForSignal|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]](in signal : String, objects : [ObjectPath]) +* [[StopListeningForSignal|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]](in signal : String) +[[Signals|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]]: + +* [[NewCard|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]](card : ObjectPath) +* [[CardRemoved|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]](card : ObjectPath) +* [[NewSink|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]](sink : ObjectPath) +* [[SinkRemoved|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]](sink : ObjectPath) +* [[FallbackSinkUpdated|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]](sink : ObjectPath) +* [[FallbackSinkUnset|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]]() +* [[NewSource|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]](source : ObjectPath) +* [[SourceRemoved|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]](source : ObjectPath) +* [[FallbackSourceUpdated|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]](source : ObjectPath) +* [[FallbackSourceUnset|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]]() +* [[NewPlaybackStream|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]](playback_stream : ObjectPath) +* [[PlaybackStreamRemoved|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]](playback_stream : ObjectPath) +* [[NewRecordStream|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]](record_stream : ObjectPath) +* [[RecordStreamRemoved|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]](record_stream : ObjectPath) +* [[NewSample|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]](sample : ObjectPath) +* [[SampleRemoved|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]](sample : ObjectPath) +* [[NewModule|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]](module : ObjectPath) +* [[ModuleRemoved|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]](module : ObjectPath) +* [[NewClient|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]](client : ObjectPath) +* [[ClientRemoved|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]](client : ObjectPath) +* [[NewExtension|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]](extension : String) +* [[ExtensionRemoved|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]](extension : String) + +### Memory Statistics + +* Object **/org/pulseaudio/core1/memstats** implements interface **org.PulseAudio.Core1.Memstats**. + +#### org.PulseAudio.Core1.Memstats + +[[Properties|Software/PulseAudio/Documentation/Developer/Clients/DBus/Memstats]]: + +* [[CurrentMemblocks|Software/PulseAudio/Documentation/Developer/Clients/DBus/Memstats]] : Uint32 (r) +* [[CurrentMemblocksSize|Software/PulseAudio/Documentation/Developer/Clients/DBus/Memstats]] : Uint32 (r) +* [[AccumulatedMemblocks|Software/PulseAudio/Documentation/Developer/Clients/DBus/Memstats]] : Uint32 (r) +* [[AccumulatedMemblocksSize|Software/PulseAudio/Documentation/Developer/Clients/DBus/Memstats]] : Uint32 (r) +* [[SampleCacheSize|Software/PulseAudio/Documentation/Developer/Clients/DBus/Memstats]] : Uint32 (r) + +### Cards + +* Objects **/org/pulseaudio/core1/cardX** implement interface **org.PulseAudio.Core1.Card**. + +#### org.PulseAudio.Core1.Card + +[[Properties|Software/PulseAudio/Documentation/Developer/Clients/DBus/Card]]: + +* [[Index|Software/PulseAudio/Documentation/Developer/Clients/DBus/Card]] : Uint32 (r) +* [[Name|Software/PulseAudio/Documentation/Developer/Clients/DBus/Card]] : String (r) +* [[Driver|Software/PulseAudio/Documentation/Developer/Clients/DBus/Card]] : String (r) +* [[OwnerModule|Software/PulseAudio/Documentation/Developer/Clients/DBus/Card]] : ObjectPath (r) # Does not exist with all cards. +* [[Sinks|Software/PulseAudio/Documentation/Developer/Clients/DBus/Card]] : [ObjectPath] (r) +* [[Sources|Software/PulseAudio/Documentation/Developer/Clients/DBus/Card]] : [ObjectPath] (r) +* [[Profiles|Software/PulseAudio/Documentation/Developer/Clients/DBus/Card]] : [ObjectPath] (r) +* [[ActiveProfile|Software/PulseAudio/Documentation/Developer/Clients/DBus/Card]] : ObjectPath (rw) # Does not exist if there are no profiles. +* [[PropertyList|Software/PulseAudio/Documentation/Developer/Clients/DBus/Card]] : {String -> [Byte]} (r) +[[Methods|Software/PulseAudio/Documentation/Developer/Clients/DBus/Card]]: + +* [[GetProfileByName|Software/PulseAudio/Documentation/Developer/Clients/DBus/Card]](in name : String ; out profile : ObjectPath) +[[Signals|Software/PulseAudio/Documentation/Developer/Clients/DBus/Card]]: + +* [[ActiveProfileUpdated|Software/PulseAudio/Documentation/Developer/Clients/DBus/Card]](profile : ObjectPath) +* [[NewProfile|Software/PulseAudio/Documentation/Developer/Clients/DBus/Card]](profile : ObjectPath) +* [[ProfileRemoved|Software/PulseAudio/Documentation/Developer/Clients/DBus/Card]](profile : ObjectPath) +* [[PropertyListUpdated|Software/PulseAudio/Documentation/Developer/Clients/DBus/Card]](property_list : {String -> [Byte]}) + +### Card Profiles + +* Objects **/org/pulseaudio/core1/cardX/profileY** implement interface **org.PulseAudio.Core1.CardProfile**. + +#### org.PulseAudio.Core1.CardProfile + +[[Properties|Software/PulseAudio/Documentation/Developer/Clients/DBus/CardProfile]]: + +* [[Index|Software/PulseAudio/Documentation/Developer/Clients/DBus/CardProfile]] : Uint32 (r) +* [[Name|Software/PulseAudio/Documentation/Developer/Clients/DBus/CardProfile]] : String (r) +* [[Description|Software/PulseAudio/Documentation/Developer/Clients/DBus/CardProfile]] : String (r) +* [[Sinks|Software/PulseAudio/Documentation/Developer/Clients/DBus/CardProfile]] : Uint32 (r) +* [[Sources|Software/PulseAudio/Documentation/Developer/Clients/DBus/CardProfile]] : Uint32 (r) +* [[Priority|Software/PulseAudio/Documentation/Developer/Clients/DBus/CardProfile]] : Uint32 (r) + +### Devices (Sinks and Sources) + +* Objects **/org/pulseaudio/core1/sinkX** and **/org/pulseaudio/core1/sourceX** implement interface **org.PulseAudio.Core1.Device**. +* Objects **/org/pulseaudio/core1/sinkX** implement interface **org.PulseAudio.Core1.Sink**. +* Objects **/org/pulseaudio/core1/sourceX** implement interface **org.PulseAudio.Core1.Source**. + +#### org.PulseAudio.Core1.Device + +[[Properties|Software/PulseAudio/Documentation/Developer/Clients/DBus/Device]]: + +* [[Index|Software/PulseAudio/Documentation/Developer/Clients/DBus/Device]] : Uint32 (r) +* [[Name|Software/PulseAudio/Documentation/Developer/Clients/DBus/Device]] : String (r) +* [[Driver|Software/PulseAudio/Documentation/Developer/Clients/DBus/Device]] : String (r) +* [[OwnerModule|Software/PulseAudio/Documentation/Developer/Clients/DBus/Device]] : ObjectPath (r) # Does not exist for all devices. +* [[Card|Software/PulseAudio/Documentation/Developer/Clients/DBus/Device]] : ObjectPath (r) # Does not exist with all devices. +* [[SampleFormat|Software/PulseAudio/Documentation/Developer/Clients/DBus/Device]] : Uint32 (r) +* [[SampleRate|Software/PulseAudio/Documentation/Developer/Clients/DBus/Device]] : Uint32 (r) +* [[Channels|Software/PulseAudio/Documentation/Developer/Clients/DBus/Device]] : [Uint32] (r) +* [[Volume|Software/PulseAudio/Documentation/Developer/Clients/DBus/Device]] : [Uint32] (rw) +* [[HasFlatVolume|Software/PulseAudio/Documentation/Developer/Clients/DBus/Device]] : Boolean (r) +* [[HasConvertibleToDecibelVolume|Software/PulseAudio/Documentation/Developer/Clients/DBus/Device]] : Boolean (r) +* [[BaseVolume|Software/PulseAudio/Documentation/Developer/Clients/DBus/Device]] : Uint32 (r) +* [[VolumeSteps|Software/PulseAudio/Documentation/Developer/Clients/DBus/Device]] : Uint32 (r) +* [[Mute|Software/PulseAudio/Documentation/Developer/Clients/DBus/Device]] : Boolean (rw) +* [[HasHardwareVolume|Software/PulseAudio/Documentation/Developer/Clients/DBus/Device]] : Boolean (r) +* [[HasHardwareMute|Software/PulseAudio/Documentation/Developer/Clients/DBus/Device]] : Boolean (r) +* [[ConfiguredLatency|Software/PulseAudio/Documentation/Developer/Clients/DBus/Device]] : Uint64 # usec +* [[HasDynamicLatency|Software/PulseAudio/Documentation/Developer/Clients/DBus/Device]] : Boolean (r) +* [[Latency|Software/PulseAudio/Documentation/Developer/Clients/DBus/Device]] : Uint64 (r) # usec, does not exist with all devices. +* [[IsHardwareDevice|Software/PulseAudio/Documentation/Developer/Clients/DBus/Device]] : Boolean (r) +* [[IsNetworkDevice|Software/PulseAudio/Documentation/Developer/Clients/DBus/Device]] : Boolean (r) +* [[State|Software/PulseAudio/Documentation/Developer/Clients/DBus/Device]] : Uint32 (r) +* [[Ports|Software/PulseAudio/Documentation/Developer/Clients/DBus/Device]] : [ObjectPath] (r) +* [[ActivePort|Software/PulseAudio/Documentation/Developer/Clients/DBus/Device]] : ObjectPath (rw) # Does not exist if there are no ports. +* [[PropertyList|Software/PulseAudio/Documentation/Developer/Clients/DBus/Device]] : {String -> [Byte]} (r) +[[Methods|Software/PulseAudio/Documentation/Developer/Clients/DBus/Device]]: + +* [[Suspend|Software/PulseAudio/Documentation/Developer/Clients/DBus/Device]](in suspend : Boolean) +* [[GetPortByName|Software/PulseAudio/Documentation/Developer/Clients/DBus/Device]](in name : String ; out port : ObjectPath) +[[Signals|Software/PulseAudio/Documentation/Developer/Clients/DBus/Device]]: + +* [[VolumeUpdated|Software/PulseAudio/Documentation/Developer/Clients/DBus/Device]](volume : [Uint32]) +* [[MuteUpdated|Software/PulseAudio/Documentation/Developer/Clients/DBus/Device]](muted : Boolean) +* [[StateUpdated|Software/PulseAudio/Documentation/Developer/Clients/DBus/Device]](state : Uint32) +* [[ActivePortUpdated|Software/PulseAudio/Documentation/Developer/Clients/DBus/Device]](port : ObjectPath) +* [[PropertyListUpdated|Software/PulseAudio/Documentation/Developer/Clients/DBus/Device]](property_list : {String -> [Byte]}) + +#### org.PulseAudio.Core1.Sink + +[[Properties|Software/PulseAudio/Documentation/Developer/Clients/DBus/Device]]: + +* [[MonitorSource|Software/PulseAudio/Documentation/Developer/Clients/DBus/Device]] : ObjectPath (r) + +#### org.PulseAudio.Core1.Source + +[[Properties|Software/PulseAudio/Documentation/Developer/Clients/DBus/Device]]: + +* [[MonitorOfSink|Software/PulseAudio/Documentation/Developer/Clients/DBus/Device]] : ObjectPath (r) # Does not exist if this is not a monitor source. + +### Device Ports + +* Objects **/org/pulseaudio/core1/sinkX/portY** and **/org/pulseaudio/core1/sourceX/portY** implement interface **org.PulseAudio.Core1.DevicePort**. + +#### org.PulseAudio.Core1.DevicePort + +[[Properties|Software/PulseAudio/Documentation/Developer/Clients/DBus/DevicePort]]: + +* [[Index|Software/PulseAudio/Documentation/Developer/Clients/DBus/DevicePort]] : Uint32 (r) +* [[Name|Software/PulseAudio/Documentation/Developer/Clients/DBus/DevicePort]] : String (r) +* [[Description|Software/PulseAudio/Documentation/Developer/Clients/DBus/DevicePort]] : String (r) +* [[Priority|Software/PulseAudio/Documentation/Developer/Clients/DBus/DevicePort]] : Uint32 (r) + +### Streams + +* Objects **/org/pulseaudio/core1/playback_streamX** and **/org/pulseaudio/core1/record_streamX** implement interface **org.PulseAudio.Core1.Stream**. + +#### org.PulseAudio.Core1.Stream + +[[Properties|Software/PulseAudio/Documentation/Developer/Clients/DBus/Stream]]: + +* [[Index|Software/PulseAudio/Documentation/Developer/Clients/DBus/Stream]] : Uint32 (r) +* [[Driver|Software/PulseAudio/Documentation/Developer/Clients/DBus/Stream]] : String (r) +* [[OwnerModule|Software/PulseAudio/Documentation/Developer/Clients/DBus/Stream]] : ObjectPath (r) # Does not exist with all streams. +* [[Client|Software/PulseAudio/Documentation/Developer/Clients/DBus/Stream]] : ObjectPath (r) # Does not exist with all streams. +* [[Device|Software/PulseAudio/Documentation/Developer/Clients/DBus/Stream]] : ObjectPath (r) +* [[SampleFormat|Software/PulseAudio/Documentation/Developer/Clients/DBus/Stream]] : Uint32 (r) +* [[SampleRate|Software/PulseAudio/Documentation/Developer/Clients/DBus/Stream]] : Uint32 (r) +* [[Channels|Software/PulseAudio/Documentation/Developer/Clients/DBus/Stream]] : [Uint32] (r) +* [[Volume|Software/PulseAudio/Documentation/Developer/Clients/DBus/Stream]] : [Uint32] (rw) +* [[VolumeWritable|Software/PulseAudio/Documentation/Developer/Clients/DBus/Stream]] : Boolean (r) +* [[Mute|Software/PulseAudio/Documentation/Developer/Clients/DBus/Stream]] : Boolean (rw) +* [[BufferLatency|Software/PulseAudio/Documentation/Developer/Clients/DBus/Stream]] : Uint64 (r) # usec +* [[DeviceLatency|Software/PulseAudio/Documentation/Developer/Clients/DBus/Stream]] : Uint64 (r) # usec +* [[ResampleMethod|Software/PulseAudio/Documentation/Developer/Clients/DBus/Stream]] : String (r) +* [[PropertyList|Software/PulseAudio/Documentation/Developer/Clients/DBus/Stream]] : {String -> [Byte]} (r) +[[Methods|Software/PulseAudio/Documentation/Developer/Clients/DBus/Stream]]: + +* [[Move|Software/PulseAudio/Documentation/Developer/Clients/DBus/Stream]](in device : ObjectPath) +* [[Kill|Software/PulseAudio/Documentation/Developer/Clients/DBus/Stream]]() +[[Signals|Software/PulseAudio/Documentation/Developer/Clients/DBus/Stream]]: + +* [[DeviceUpdated|Software/PulseAudio/Documentation/Developer/Clients/DBus/Stream]](device : ObjectPath) +* [[SampleRateUpdated|Software/PulseAudio/Documentation/Developer/Clients/DBus/Stream]](sample_rate : Uint32) +* [[VolumeUpdated|Software/PulseAudio/Documentation/Developer/Clients/DBus/Stream]](volume : [Uint32]) +* [[MuteUpdated|Software/PulseAudio/Documentation/Developer/Clients/DBus/Stream]](muted : Boolean) +* [[PropertyListUpdated|Software/PulseAudio/Documentation/Developer/Clients/DBus/Stream]](property_list : {String -> [Byte]}) +* [[StreamEvent|Software/PulseAudio/Documentation/Developer/Clients/DBus/Stream]](name : String, property_list : {String -> [Byte]}) + +### Samples + +* Objects **/org/pulseaudio/core1/sampleX** implement interface **org.PulseAudio.Core1.Sample**. + +#### org.PulseAudio.Core1.Sample + +[[Properties|Software/PulseAudio/Documentation/Developer/Clients/DBus/Sample]]: + +* [[Index|Software/PulseAudio/Documentation/Developer/Clients/DBus/Sample]] : Uint32 (r) +* [[Name|Software/PulseAudio/Documentation/Developer/Clients/DBus/Sample]] : String (r) +* [[SampleFormat|Software/PulseAudio/Documentation/Developer/Clients/DBus/Sample]] : Uint32 (r) # Does not exist with all samples. +* [[SampleRate|Software/PulseAudio/Documentation/Developer/Clients/DBus/Sample]] : Uint32 (r) # Does not exist with all samples. +* [[Channels|Software/PulseAudio/Documentation/Developer/Clients/DBus/Sample]] : [Uint32] (r) # Does not exist with all samples. +* [[DefaultVolume|Software/PulseAudio/Documentation/Developer/Clients/DBus/Sample]] : [Uint32] (r) # Does not exist with all samples. +* [[Duration|Software/PulseAudio/Documentation/Developer/Clients/DBus/Sample]] : Uint64 (r) # usec, does not exist with all samples. +* [[Bytes|Software/PulseAudio/Documentation/Developer/Clients/DBus/Sample]] : Uint32 (r) # Does not exist with all samples. +* [[PropertyList|Software/PulseAudio/Documentation/Developer/Clients/DBus/Sample]] : {String -> [Byte]} (r) +[[Methods|Software/PulseAudio/Documentation/Developer/Clients/DBus/Sample]]: + +* [[Play|Software/PulseAudio/Documentation/Developer/Clients/DBus/Sample]](in volume : Uint32, property_list : {String -> [Byte]}) +* [[PlayToSink|Software/PulseAudio/Documentation/Developer/Clients/DBus/Sample]](in sink : ObjectPath, volume : Uint32, property_list : {String -> [Byte]}) +* [[Remove|Software/PulseAudio/Documentation/Developer/Clients/DBus/Sample]]() +[[Signals|Software/PulseAudio/Documentation/Developer/Clients/DBus/Sample]]: + +* [[PropertyListUpdated|Software/PulseAudio/Documentation/Developer/Clients/DBus/Sample]](property_list : {String -> [Byte]}) + +### Modules + +* Objects **/org/pulseaudio/core1/moduleX** implement interface **org.PulseAudio.Core1.Module**. + +#### org.PulseAudio.Core1.Module + +[[Properties|Software/PulseAudio/Documentation/Developer/Clients/DBus/Module]]: + +* [[Index|Software/PulseAudio/Documentation/Developer/Clients/DBus/Module]] : Uint32 (r) +* [[Name|Software/PulseAudio/Documentation/Developer/Clients/DBus/Module]] : String (r) +* [[Arguments|Software/PulseAudio/Documentation/Developer/Clients/DBus/Module]] : {String -> String} (r) +* [[UsageCounter|Software/PulseAudio/Documentation/Developer/Clients/DBus/Module]] : Uint32 (r) # Does not exist with all modules. +* [[PropertyList|Software/PulseAudio/Documentation/Developer/Clients/DBus/Module]] : {String -> [Byte]} (r) +[[Methods|Software/PulseAudio/Documentation/Developer/Clients/DBus/Module]]: + +* [[Unload|Software/PulseAudio/Documentation/Developer/Clients/DBus/Module]]() +[[Signals|Software/PulseAudio/Documentation/Developer/Clients/DBus/Module]]: + +* [[PropertyListUpdated|Software/PulseAudio/Documentation/Developer/Clients/DBus/Module]](property_list : {String -> [Byte]}) + +### Clients + +* Objects **/org/pulseaudio/core1/clientX** implement interface **org.PulseAudio.Core1.Client**. + +#### org.PulseAudio.Core1.Client + +[[Properties|Software/PulseAudio/Documentation/Developer/Clients/DBus/Client]]: + +* [[Index|Software/PulseAudio/Documentation/Developer/Clients/DBus/Client]] : Uint32 (r) +* [[Driver|Software/PulseAudio/Documentation/Developer/Clients/DBus/Client]] : String (r) +* [[OwnerModule|Software/PulseAudio/Documentation/Developer/Clients/DBus/Client]] : ObjectPath (r) # Does not exist with all clients. +* [[PlaybackStreams|Software/PulseAudio/Documentation/Developer/Clients/DBus/Client]] : [ObjectPath] (r) +* [[RecordStreams|Software/PulseAudio/Documentation/Developer/Clients/DBus/Client]] : [ObjectPath] (r) +* [[PropertyList|Software/PulseAudio/Documentation/Developer/Clients/DBus/Client]] : {String -> [Byte]} (r) +[[Methods|Software/PulseAudio/Documentation/Developer/Clients/DBus/Client]]: + +* [[Kill|Software/PulseAudio/Documentation/Developer/Clients/DBus/Client]]() +* [[UpdateProperties|Software/PulseAudio/Documentation/Developer/Clients/DBus/Client]](in property_list : {String -> [Byte]}, update_mode : Uint32) +* [[RemoveProperties|Software/PulseAudio/Documentation/Developer/Clients/DBus/Client]](in keys : [String]) +[[Signals|Software/PulseAudio/Documentation/Developer/Clients/DBus/Client]]: + +* [[PropertyListUpdated|Software/PulseAudio/Documentation/Developer/Clients/DBus/Client]](property_list : {String -> [Byte]}) +* [[ClientEvent|Software/PulseAudio/Documentation/Developer/Clients/DBus/Client]](name : String, property_list : {String -> [Byte]}) + +### Stream Restore Extension + +* Object **/org/pulseaudio/stream_restore1** implements interface **org.PulseAudio.Ext.StreamRestore1**. +* Objects **/org/pulseaudio/stream_restore1/entryX** implement interface **org.PulseAudio.Ext.StreamRestore1.RestoreEntry**. + +#### org.PulseAudio.Ext.StreamRestore1 + +[[Properties|Software/PulseAudio/Documentation/Developer/Clients/DBus/StreamRestore]]: + +* [[InterfaceRevision|Software/PulseAudio/Documentation/Developer/Clients/DBus/StreamRestore]] : Uint32 (r) +* [[Entries|Software/PulseAudio/Documentation/Developer/Clients/DBus/StreamRestore]] : [ObjectPath] (r) +[[Methods|Software/PulseAudio/Documentation/Developer/Clients/DBus/StreamRestore]]: + +* [[AddEntry|Software/PulseAudio/Documentation/Developer/Clients/DBus/StreamRestore]](in name : String, device : String, volume : [(Uint32, Uint32)], mute : Boolean, apply_immediately : Boolean ; out entry : ObjectPath) +* [[GetEntryByName|Software/PulseAudio/Documentation/Developer/Clients/DBus/StreamRestore]](in name : String ; out entry : ObjectPath) +[[Signals|Software/PulseAudio/Documentation/Developer/Clients/DBus/StreamRestore]]: + +* [[NewEntry|Software/PulseAudio/Documentation/Developer/Clients/DBus/StreamRestore]](entry : ObjectPath) +* [[EntryRemoved|Software/PulseAudio/Documentation/Developer/Clients/DBus/StreamRestore]](entry : ObjectPath) + +#### org.PulseAudio.Ext.StreamRestore1.RestoreEntry + +[[Properties|Software/PulseAudio/Documentation/Developer/Clients/DBus/StreamRestore]]: + +* [[Index|Software/PulseAudio/Documentation/Developer/Clients/DBus/StreamRestore]] : Uint32 (r) +* [[Name|Software/PulseAudio/Documentation/Developer/Clients/DBus/StreamRestore]] : String (r) +* [[Device|Software/PulseAudio/Documentation/Developer/Clients/DBus/StreamRestore]] : String (rw) +* [[Volume|Software/PulseAudio/Documentation/Developer/Clients/DBus/StreamRestore]] : [(Uint32, Uint32)] (rw) +* [[Mute|Software/PulseAudio/Documentation/Developer/Clients/DBus/StreamRestore]] : Boolean (rw) +[[Methods|Software/PulseAudio/Documentation/Developer/Clients/DBus/StreamRestore]]: + +* [[Remove|Software/PulseAudio/Documentation/Developer/Clients/DBus/StreamRestore]]() +[[Signals|Software/PulseAudio/Documentation/Developer/Clients/DBus/StreamRestore]]: + +* [[DeviceUpdated|Software/PulseAudio/Documentation/Developer/Clients/DBus/StreamRestore]](device : String) +* [[VolumeUpdated|Software/PulseAudio/Documentation/Developer/Clients/DBus/StreamRestore]](volume : [(Uint32, Uint32)]) +* [[MuteUpdated|Software/PulseAudio/Documentation/Developer/Clients/DBus/StreamRestore]](muted : Boolean) + +### Ladspa Extension + +* Objects **/org/pulseaudio/core1/sinkX**, where X is the index of a ladspa sink, implement interface **org.PulseAudio.Ext.Ladspa1**. + +#### org.PulseAudio.Ext.Ladspa1 + +[[Properties|Software/PulseAudio/Documentation/Developer/Clients/DBus/Ladspa]]: + +* [[AlgorithmParameters|Software/PulseAudio/Documentation/Developer/Clients/DBus/Ladspa]] : ([Double], [Boolean]) (rw) + +### Enumerations + +* [[Sample formats|Software/PulseAudio/Documentation/Developer/Clients/DBus/Enumerations]] +* [[Channel positions|Software/PulseAudio/Documentation/Developer/Clients/DBus/Enumerations]] +* [[Device states|Software/PulseAudio/Documentation/Developer/Clients/DBus/Enumerations]] +* [[Update modes|Software/PulseAudio/Documentation/Developer/Clients/DBus/Enumerations]] + +### Errors + +* [[org.PulseAudio.Core1.NotFoundError|Software/PulseAudio/Documentation/Developer/Clients/DBus/Errors]] +* [[org.PulseAudio.Core1.NoSuchPropertyError|Software/PulseAudio/Documentation/Developer/Clients/DBus/Errors]] +* [[org.PulseAudio.Core1.BadStateError|Software/PulseAudio/Documentation/Developer/Clients/DBus/Errors]]
\ No newline at end of file diff --git a/Software/PulseAudio/Documentation/Developer/Clients/DBus/Card.mdwn b/Software/PulseAudio/Documentation/Developer/Clients/DBus/Card.mdwn new file mode 100644 index 00000000..f8f0f6da --- /dev/null +++ b/Software/PulseAudio/Documentation/Developer/Clients/DBus/Card.mdwn @@ -0,0 +1,127 @@ + + +# D-Bus Interface: Cards + +[[(Back to the toplevel D-Bus Interface page)|Software/PulseAudio/Documentation/Developer/Clients/DBus]] + +Objects and their interfaces: + +* /org/pulseaudio/core1/cardX + * - org.PulseAudio.Core1.Card - org.freedesktop.DBus.Properties - org.freedesktop.DBus.Introspectable. + +## org.PulseAudio.Core1.Card + + +### Properties + + +#### Index + +* Type: Uint32 +* Access: read +The card index. + + +#### Name + +* Type: String +* Access: read +The card name. + + +#### Driver + +* Type: String +* Access: read +The driver that implements the card object. This is usually expressed as a source code file name, for example "module-alsa-card.c". + + +#### !OwnerModule + +* Type: ObjectPath +* Access: read +The module that owns this card. It's not guaranteed that any module claims ownership; in such case this property does not exist. + +* Errors: + * - [[org.PulseAudio.Core1.NoSuchPropertyError|Software/PulseAudio/Documentation/Developer/Clients/DBus/Errors]] if this card is not owned by any module. + +#### Sinks + +* Type: [ObjectPath] +* Access: read +The sinks belonging to this card. + + +#### Sources + +* Type: [ObjectPath] +* Access: read +The sources belonging to this card. + + +#### Profiles + +* Type: [ObjectPath] +* Access: read +All available card profiles. May be empty. + + +#### !ActiveProfile + +* Type: ObjectPath +* Access: read/write +The currently active card profile. This property doesn't exist if the card does not have any profiles. + +* Errors: + * - [[org.PulseAudio.Core1.NoSuchPropertyError|Software/PulseAudio/Documentation/Developer/Clients/DBus/Errors]] if this card doesn't have any profiles. + +#### !PropertyList + +* Type: {String -> [Byte]} +* Access: read +The card's property list. + + +### Methods + + +#### !GetProfileByName + +* Arguments: name : String + * - name: Profile name +* Returns: profile : ObjectPath + * - profile: Card profile object +Find the card profile with the given name. + +* Errors: + * - [[org.PulseAudio.Core1.NotFoundError|Software/PulseAudio/Documentation/Developer/Clients/DBus/Errors]] if no such profile is available. + +### Signals + + +#### !ActiveProfileUpdated + +* Parameters: profile : ObjectPath + * - profile: Activated card profile +The active card profile was changed. + + +#### NewProfile + +* Parameters: profile : ObjectPath + * - profile: Added profile object +A profile was added to the card. + + +#### ProfileRemoved + +* Parameters: profile : ObjectPath + * - profile: Removed profile object +A profile was removed from the card. + + +#### !PropertyListUpdated + +* Parameters: property_list : {String -> [Byte]} + * - property_list: The new property list. +The card's property list was modified. diff --git a/Software/PulseAudio/Documentation/Developer/Clients/DBus/CardProfile.mdwn b/Software/PulseAudio/Documentation/Developer/Clients/DBus/CardProfile.mdwn new file mode 100644 index 00000000..ed4918d9 --- /dev/null +++ b/Software/PulseAudio/Documentation/Developer/Clients/DBus/CardProfile.mdwn @@ -0,0 +1,57 @@ + + +# D-Bus Interface: Card Profiles + +[[(Back to the toplevel D-Bus Interface page)|Software/PulseAudio/Documentation/Developer/Clients/DBus]] + +Objects and their interfaces: + +* /org/pulseaudio/core1/cardX/profileY + * - org.PulseAudio.Core1.CardProfile - org.freedesktop.DBus.Properties - org.freedesktop.DBus.Introspectable. + +## org.PulseAudio.Core1.!CardProfile + + +### Properties + + +#### Index + +* Type: Uint32 +* Access: read +The profile index. The index is only used in the profile's D-Bus object path, it has no meaning in PulseAudio's internal working. + + +#### Name + +* Type: String +* Access: read +The profile name. + + +#### Description + +* Type: String +* Access: read +The profile description. + + +#### Sinks + +* Type: Uint32 +* Access: read +The number of sinks this profile creates. + + +#### Sources + +* Type: Uint32 +* Access: read +The number of sources this profile creates. + + +#### Priority + +* Type: Uint32 +* Access: read +The priority of the profile. Profiles are usually presented to the user ordered by the priority. The profile with the highest priority is activated by default. diff --git a/Software/PulseAudio/Documentation/Developer/Clients/DBus/Client.mdwn b/Software/PulseAudio/Documentation/Developer/Clients/DBus/Client.mdwn new file mode 100644 index 00000000..aaa89c8e --- /dev/null +++ b/Software/PulseAudio/Documentation/Developer/Clients/DBus/Client.mdwn @@ -0,0 +1,102 @@ + + +# D-Bus Interface: Clients + +[[(Back to the toplevel D-Bus Interface page)|Software/PulseAudio/Documentation/Developer/Clients/DBus]] + +Objects and their interfaces: + +* /org/pulseaudio/core1/clientX + * - org.PulseAudio.Core1.Client - org.freedesktop.DBus.Properties - org.freedesktop.DBus.Introspectable + +## org.PulseAudio.Core1.Client + + +### Properties + + +#### Index + +* Type: Uint32 +* Access: read +The client index. + + +#### Driver + +* Type: String +* Access: read +The driver that implements the client object. This is usually expressed as a source code file name, for example "protocol-native.c". + + +#### !OwnerModule + +* Type: ObjectPath +* Access: read +The module that owns this client object. It's not guaranteed that any module claims ownership; in such case this property does not exist. + +* Errors: + * - [[org.PulseAudio.Core1.NoSuchPropertyError|Software/PulseAudio/Documentation/Developer/Clients/DBus/Errors]] if this client is not owned by any module. + +#### !PlaybackStreams + +* Type: [ObjectPath] +* Access: read +The playback streams created by this client. + + +#### !RecordStreams + +* Type: [ObjectPath] +* Access: read +The record streams created by this client. + + +#### !PropertyList + +* Type: {String -> [Byte]} +* Access: read +The client's property list. + + +### Methods + + +#### Kill + +Cut the client's connection, terminating also its streams. + + +#### !UpdateProperties + +* Arguments: property_list : {String -> [Byte]}, update_mode : Uint32 + * - property_list: The properties to update - update_mode: How the properties should be merged, see [[[[Software/PulseAudio/Documentation/Developer/Clients/DBus/Enumerations|Software/PulseAudio/Documentation/Developer/Clients/DBus/Enumerations]]]] for the list of possible values +Updates the client's property list with new values. A client can modify only its own property list. + +* Errors: + * - org.freedesktop.DBus.Error.AccessDenied if a client tries to modify some other client's property list. + +#### !RemoveProperties + +* Arguments: keys : [String] + * - keys: Array of property names +Removes properties from the client's property list. A client can modify only its own property list. + +* Errors: + * - org.freedesktop.DBus.Error.AccessDenied if a client tries to modify some other client's property list. + +### Signals + + +#### !PropertyListUpdated + +* Parameters: property_list : {String -> [Byte]} + * - property_list: The new property list +The client's property list was modified. + + +#### !ClientEvent + +* Parameters: name : String, property_list : {String -> [Byte]} + * - name: Event name - property_list: Additional event parameters +The server may send per-client events (visible only to the client that is the intended recipient). However, currently no such events are generated, so until some events are actually defined this signal remains unused. diff --git a/Software/PulseAudio/Documentation/Developer/Clients/DBus/ConnectingToServer.mdwn b/Software/PulseAudio/Documentation/Developer/Clients/DBus/ConnectingToServer.mdwn new file mode 100644 index 00000000..899cbdd7 --- /dev/null +++ b/Software/PulseAudio/Documentation/Developer/Clients/DBus/ConnectingToServer.mdwn @@ -0,0 +1,61 @@ + + +# D-Bus Interface: Connecting to a Server + +[[(Back to the toplevel D-Bus Interface page)|Software/PulseAudio/Documentation/Developer/Clients/DBus]] + +**NB:** This scheme will very likely be changed, details about this are in this mailing list message: [[[https://tango.0pointer.de/pipermail/pulseaudio-discuss/2009-July/004437.html|https://tango.0pointer.de/pipermail/pulseaudio-discuss/2009-July/004437.html]]]. At the time of writing, there are no responses so it's not certain yet what the final server discovery scheme will exactly look like. The following description applies to the current development version. + + +## Procedure + +When a client wants to connect to a server, it reads the $PULSE_DBUS_SERVER environment variable, which contains a server address or a list of addresses, as specified in the [[D-Bus Specification, section Server Addresses|http://dbus.freedesktop.org/doc/dbus-specification.html#addresses]]. The client should be able to use the string directly as the address parameter of the underlying D-Bus library's connect function. + +If $PULSE_DBUS_SERVER is not set, the client reads the Address property (part of the org.PulseAudio.ServerLookup1 interface) of object /org/pulseaudio/server_lookup1. The destination of the call is org.PulseAudio1. The property contains a string similar to the $PULSE_DBUS_SERVER environment variable. The returned string is empty if client.conf doesn't set any address (which is the default) and the daemon is configured to not run local servers. Reading the property may autostart pulseaudio. Due to the fact that pulseaudio may exit automatically after a while, the client shouldn't wait long between reading the address and connecting to the server (the default timeout is 20 seconds). + + +## Authentication + +D-Bus handles authentication automatically, so client programmers shouldn't need to care about that otherwise than keeping in mind that authentication may fail. For now the access control is done in the following way (very likely to change): + +* When a server runs in the system mode, it by default listens only for local unix domain socket connections and accepts all connections. +* When a server runs in the user mode and listens only for local unix domain socket connections (the default case), only connections by the same user as the server and connections by root are accepted. +* Whenever a server listens for TCP connections all connections are accepted. + +## Example Python Code + +This is an example (could be improved) of how D-Bus clients can establish a connection to PulseAudio: + + +[[!format txt """ +#!/usr/bin/env python + +import dbus +import os + +def connect(): + if 'PULSE_DBUS_SERVER' in os.environ: + address = os.environ['PULSE_DBUS_SERVER'] + else: + bus = dbus.SessionBus() + server_lookup = bus.get_object("org.PulseAudio1", "/org/pulseaudio/server_lookup1") + address = server_lookup.Get("org.PulseAudio.ServerLookup1", "Address", dbus_interface="org.freedesktop.DBus.Properties") + + return dbus.connection.Connection(address) + + +conn = connect() +core = conn.get_object(object_path="/org/pulseaudio/core1") + +print "Successfully connected to " + core.Get("org.PulseAudio.Core1", "Name", dbus_interface="org.freedesktop.DBus.Properties") + "!" +"""]] + +## Lookup Service Details + +To give some background information (and to document this stuff somewhere), this is how server discovery works from PulseAudio's point of view: + +Contrary to earlier behavior, running the pulseaudio executable with D-Bus support compiled in doesn't necessary start a proper sound server. In certain circumstances only the server lookup service, as described above, is started. This happens in two cases: the executable is run by a non-root user and the daemon is configured to run in the system mode, or the daemon configuration just says that no local server should be started (which is useful when only remote servers are intended to be used). + +There is a new option in daemon.conf: local-server-type. Its value can be either "user", "system" or "none". The default is "user". However, the option conflicts with the old option system-instance. If system-instance is set and local-server-type is not, system-instance value is honored. On the other hand, if local-server-type is set, it overrides whatever is the value of system-instance. + +If user's pulseaudio executable isn't running when a client reads the Address property, D-Bus automatically starts pulseaudio. Depending on server configuration, a real sound server may be started, but another possibility is that only the server lookup service is enabled. The server lookup service, i.e. the Address property, works by first reading the user's (or in absence of that, the system version of) client.conf. client.conf too has a new option: default-dbus-server. If it is set, then that value is returned to the client. If default-dbus-server is not set, the address is deduced from the local-server-type option: in case of "user" the returned address is the unix socket of the user's server (~/.pulse/<machine_id>:runtime/dbus-socket), in case of "system" the returned address is the system server's unix socket (/var/run/pulse/dbus-socket), and in case of "none" the returned address is an empty string. diff --git a/Software/PulseAudio/Documentation/Developer/Clients/DBus/Core.mdwn b/Software/PulseAudio/Documentation/Developer/Clients/DBus/Core.mdwn new file mode 100644 index 00000000..26ea9fad --- /dev/null +++ b/Software/PulseAudio/Documentation/Developer/Clients/DBus/Core.mdwn @@ -0,0 +1,417 @@ + + +# D-Bus Interface: General Server Functionality + +[[(Back to the toplevel D-Bus Interface page)|Software/PulseAudio/Documentation/Developer/Clients/DBus]] + +Objects and their interfaces: + +* /org/pulseaudio/core1 + * - org.PulseAudio.Core1 - org.freedesktop.DBus.Properties - org.freedesktop.DBus.Introspectable + +## org.PulseAudio.Core1 + + +### Properties + + +#### !InterfaceRevision + +* Type: Uint32 +* Access: read +The "major" version of the main D-Bus interface is embedded in the interface name: org.PulseAudio.Core1. When changes are made that break compatibility between old clients and new servers the major version is incremented. This property tells the "minor" version, that is, when new features are added to the interface, this version number is incremented so that new clients can check if the server they talk to supports the new features. This documentation defines revision 0. Extensions are versioned separately (i.e. they have their own major and minor version numbers). + + +#### Name + +* Type: String +* Access: read +The server name. At the time of writing no competing implementations have appeared, so the expected name is "pulseaudio". + + +#### Version + +* Type: String +* Access: read +The server version string, for example "0.9.17". + + +#### !IsLocal + +* Type: Boolean +* Access: read +This per-client property can be used to find out whether the client is connected to a local server. + + +#### Username + +* Type: String +* Access: read +The username that the server is running under. + + +#### Hostname + +* Type: String +* Access: read +The hostname of the machine the server is running on. + + +#### !DefaultChannels + +* Type: [Uint32] +* Access: read/write +The default channel map that is used when initializing a device and the configuration information doesn't specify the desired channel map. The default channel count can be inferred from this. The channel map is expressed as a list of channel positions, see [[[[Software/PulseAudio/Documentation/Developer/Clients/DBus/Enumerations|Software/PulseAudio/Documentation/Developer/Clients/DBus/Enumerations]]]] for the list of possible channel position values. + + +#### !DefaultSampleFormat + +* Type: Uint32 +* Access: read/write +The default sample format that is used when initializing a device and the configuration information doesn't specify the desired sample format. See [[[[Software/PulseAudio/Documentation/Developer/Clients/DBus/Enumerations|Software/PulseAudio/Documentation/Developer/Clients/DBus/Enumerations]]]] for the list of possible values. + + +#### !DefaultSampleRate + +* Type: Uint32 +* Access: read/write +The default sample rate that is used when initializing a device and the configuration information doesn't specify the desired sample rate. + + +#### Cards + +* Type: [ObjectPath] +* Access: read +All currently available cards. + + +#### Sinks + +* Type: [ObjectPath] +* Access: read +All currently available sinks. + + +#### !FallbackSink + +* Type: ObjectPath +* Access: read/write +When a new playback stream is created and there is no other policy about to which sink the stream should be connected, the fallback sink is selected. This property doesn't exist if there's no sink selected as the fallback sink. + +* Errors: + * - [[org.PulseAudio.Core1.NoSuchPropertyError|Software/PulseAudio/Documentation/Developer/Clients/DBus/Errors]] if the fallback sink is not set. + +#### Sources + +* Type: [ObjectPath] +* Access: read +All currently available sources. + + +#### !FallbackSource + +* Type: ObjectPath +* Access: read/write +When a new record stream is created and there is no other policy about to which source the stream should be connected, the fallback source is selected. This property doesn't exist if there's no source selected as the fallback source. + +* Errors: + * - [[org.PulseAudio.Core1.NoSuchPropertyError|Software/PulseAudio/Documentation/Developer/Clients/DBus/Errors]] if the fallback source is not set. + +#### !PlaybackStreams + +* Type: [ObjectPath] +* Access: read +All current playback streams. + + +#### !RecordStreams + +* Type: [ObjectPath] +* Access: read +All current record streams. + + +#### Samples + +* Type: [ObjectPath] +* Access: read +All currently loaded samples. + + +#### Modules + +* Type: [ObjectPath] +* Access: read +All currently loaded modules. + + +#### Clients + +* Type: [ObjectPath] +* Access: read +All currently connected clients. + + +#### !MyClient + +* Type: ObjectPath +* Access: read +This property has a different value for each client: it tells the reading client the client object that is assigned to its connection. + + +#### Extensions + +* Type: [String] +* Access: read +All available server extension interfaces. Each extension interface defines an unique string that clients can search from this array. The string should contain a version part so that if backward compatibility breaking changes are made to the interface, old clients don't detect the new interface at all, or both old and new interfaces can be provided. + +The string is specific to the D-Bus interface of the extension, so if an extension module offers access through both the C API and D-Bus, the interfaces can be updated independently. + +The strings are intended to follow the structure and restrictions of D-Bus interface names, but that is not enforced. The clients should treat the strings as opaque identifiers. + + +### Methods + + +#### !GetCardByName + +* Arguments: name : String + * - name: Card name +* Returns: card : ObjectPath + * - Card: card object +Find the card with the given name. + +* Errors: + * - [[org.PulseAudio.Core1.NotFoundError|Software/PulseAudio/Documentation/Developer/Clients/DBus/Errors]] if no such card is available. + +#### !GetSinkByName + +* Arguments: name : String + * - name: Sink name +* Returns : sink : ObjectPath + * - sink: Sink object +Find the sink with the given name. + +* Errors: + * - [[org.PulseAudio.Core1.NotFoundError|Software/PulseAudio/Documentation/Developer/Clients/DBus/Errors]] if no such sink is available. + +#### !GetSourceByName + +* Arguments: name : String + * - name: Source name +* Returns: source : ObjectPath + * - source: Source object +Find the source with the given name. + +* Errors: + * - [[org.PulseAudio.Core1.NotFoundError|Software/PulseAudio/Documentation/Developer/Clients/DBus/Errors]] if no such source is available. + +#### !GetSampleByName + +* Arguments: name : String + * - name: Sample name +* Returns: sample : ObjectPath + * - sample: Sample object +Find the sample with the given name. + +* Errors: + * - [[org.PulseAudio.Core1.NotFoundError|Software/PulseAudio/Documentation/Developer/Clients/DBus/Errors]] if no such sample is loaded. + +#### !UploadSample + +* Arguments: name : String, sample_format : Uint32, sample_rate : Uint32, channels : [Uint32], default_volume : [Uint32], property_list : {String -> [Byte]}, Data : [Byte] + * - name: Sample name - sample_format: Sample format, see [[[[Software/PulseAudio/Documentation/Developer/Clients/DBus/Enumerations|Software/PulseAudio/Documentation/Developer/Clients/DBus/Enumerations]]]] - channels: Channel map as an array of channel positions, see [[[[Software/PulseAudio/Documentation/Developer/Clients/DBus/Enumerations|Software/PulseAudio/Documentation/Developer/Clients/DBus/Enumerations]]]] - default_volume: The volume at which the sample should be played if the volume isn't given at the time of playing. The volume elements in the array must match the channel positions in the channels array, or alternatively an empty array may be given, in which case the server decides the default volume (this is often a good choice). Volume elements should normally be between 0 (muted) and 65536 (normal). Any bigger values amplify the signal digitally, which very often causes clipping. - property_list: Proplist for the sample - data: Audio data +* Returns: sample : ObjectPath + * - sample: Added sample object +Loads a sample. If there is already a sample loaded with the same name, the old sample is replaced. + + +#### !LoadModule + +* Arguments: name : String, arguments : {String -> String} + * - name: Module name (e.g. "module-alsa-sink"). - arguments: Module arguments. Keys are argument names and values are argument values. Keys must be ASCII only without any whitespace. When loading modules in some other way than by using this D-Bus interface, quoting and escaping needs to be usually applied, but when using this interface you don't need to care about that. +* Returns: module : ObjectPath + * - module: Loaded module object +Loads a module. + +* Errors: + * - org.freedesktop.DBus.Error.AccessDenied if the server is configured to disallow module loading. + +#### Exit + +Shuts down the server. + +* Errors: + * - org.freedesktop.DBus.Error.AccessDenied if the server is configured to disallow exiting. + +#### !ListenForSignal + +* Arguments: signal : String, objects : [ObjectPath] + * - signal: The signal name containing the interface, for example "org.PulseAudio.Core1.Device.ActivePortUpdated" - objects: If non-empty, only signals originating from the listed objects are sent +By default the server doesn't send any signals to clients, but a client can use this method to inform the server about the signals that the client is interested in. + +If the objects argument is an empty list, then all signals of the given type are sent, otherwise the signals are filtered based on the emitting object. If this method is called more than once for the same signal, the latest call always replaces the previous object list. + +In order to support clients that want to receive absolutely all signals, an empty string can be given as the signal name. In that case all previous signal filters are discarded. The objects parameter can still be used to limit the signals to certain objects. If this method is called after giving the "all-pass" filter, the "all-pass" filter is discarded, so the resulting state is equal to as if there weren't any previous filters. + +Note that no error is returned if the signal name or an object path is unknown to the server. This is because an extension could be loaded at any time that would start sending the given signal, or create the object. + + +#### !StopListeningForSignal + +* Arguments: signal : String + * - signal: Signal name containing the interface, for example "org.PulseAudio.Core1.Device.ActivePortUpdated" +Tells the server to stop sending signals of the given type. Empty signal name means that no signals should be sent anymore. If the client has previously called ListenForSignal with an empty signal argument, calling this method with a non-empty signal argument does nothing. + + +### Signals + + +#### !NewCard + +* Parameters: card : ObjectPath + * - card: Added card object +A card was added. + + +#### !CardRemoved + +* Parameters: card : ObjectPath + * - card: Removed card object +A card was removed. + + +#### !NewSink + +* Parameters: sink : ObjectPath + * - sink: Added sink object +A sink was added. + + +#### !SinkRemoved + +* Parameters: sink : ObjectPath + * - sink: Removed sink object +A sink was removed. + + +#### !FallbackSinkUpdated + +* Parameters: sink : ObjectPath + * - sink: New fallback sink +The fallback sink was changed. When the fallback sink becomes unset, [[FallbackSinkUnset|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]] is emitted instead of this signal. + + +#### !FallbackSinkUnset + +The fallback sink became unset. + + +#### !NewSource + +* Parameters: source : ObjectPath + * - source: Added source object +A source was added. + + +#### !SourceRemoved + +* Parameters: source : ObjectPath + * - source: Removed source object +A source was removed. + + +#### !FallbackSourceUpdated + +* Parameters: source : ObjectPath + * - source: New fallback source +The fallback source was changed. When the fallback source becomes unset, [[FallbackSourceUnset|Software/PulseAudio/Documentation/Developer/Clients/DBus/Core]] is emitted instead of this signal. + + +#### !FallbackSourceUnset + +The fallback source became unset. + + +#### !NewPlaybackStream + +* Parameters: playback_stream : ObjectPath + * - playback_stream: Added playback stream object +A playback stream was added. + + +#### !PlaybackStreamRemoved + +* Parameters: playback_stream : ObjectPath + * - playback_stream: Removed playback stream object +A playback stream was removed. + + +#### !NewRecordStream + +* Parameters: record_stream : ObjectPath + * - record_stream: Added record stream object +A record stream was added. + + +#### !RecordStreamRemoved + +* Parameters: record_stream : ObjectPath + * - record_stream: Removed record stream object +A record stream was removed. + + +#### !NewSample + +* Parameters: sample : ObjectPath + * - sample: Loaded sample object +A sample was loaded. + + +#### !SampleRemoved + +* Parameters: sample : ObjectPath + * - sample: Unloaded sample object +A sample was unloaded. + + +#### !NewModule + +* Parameters: module : ObjectPath + * - module: Loaded module object +A module was loaded. + + +#### !ModuleRemoved + +* Parameters: module : ObjectPath + * - module: Unloaded module object +A module was unloaded. + + +#### !NewClient + +* Parameters: client : ObjectPath + * - client: Connected client object +A new client connected. + + +#### !ClientRemoved + +* Parameters: client : ObjectPath + * - client: Disconnected client object +A client disconnected. + + +#### !NewExtension + +* Parameters: extension : String + * - extension: Added extension name +An extension was added. + + +#### !ExtensionRemoved + +* Parameters: extension : String + * - extension: Removed extension name +An extension was removed. diff --git a/Software/PulseAudio/Documentation/Developer/Clients/DBus/Device.mdwn b/Software/PulseAudio/Documentation/Developer/Clients/DBus/Device.mdwn new file mode 100644 index 00000000..557960e5 --- /dev/null +++ b/Software/PulseAudio/Documentation/Developer/Clients/DBus/Device.mdwn @@ -0,0 +1,292 @@ + + +# D-Bus Interface: Devices (Sinks and Sources) + +[[(Back to the toplevel D-Bus Interface page)|Software/PulseAudio/Documentation/Developer/Clients/DBus]] + +Objects and their interfaces: + +* /org/pulseaudio/core1/sinkX + * - org.PulseAudio.Core1.Device - org.PulseAudio.Core1.Sink - org.freedesktop.DBus.Properties - org.freedesktop.DBus.Introspectable +* /org/pulseaudio/core1/sourceX + * - org.PulseAudio.Core1.Device - org.PulseAudio.Core1.Source - org.freedesktop.DBus.Properties - org.freedesktop.DBus.Introspectable + +## org.PulseAudio.Core1.Device + + +### Properties + + +#### Index + +* Type: Uint32 +* Access: read +The device index. Sink and source indices are separate, so it's perfectly normal to have two devices with the same index: the other device is a sink and the other is a source. + + +#### Name + +* Type: String +* Access: read +The device name. + + +#### Driver + +* Type: String +* Access: read +The driver that implements the device object. This is usually expressed as a source code file name, for example "module-alsa-card.c". + + +#### !OwnerModule + +* Type: ObjectPath +* Access: read +The module that owns this device. It's not guaranteed that any module claims ownership; in such case this property does not exist. + +* Errors: + * - [[org.PulseAudio.Core1.NoSuchPropertyError|Software/PulseAudio/Documentation/Developer/Clients/DBus/Errors]] if this device is not owned by any module. + +#### Card + +* Type: ObjectPath +* Access: read +The card that this device belongs to. Not all devices are part of cards; in those cases this property does not exist. + +* Errors: + * - [[org.PulseAudio.Core1.NoSuchPropertyError|Software/PulseAudio/Documentation/Developer/Clients/DBus/Errors]] if this device is not part of any card. + +#### !SampleFormat + +* Type: Uint32 +* Access: read +The sample format of the device. See [[[[Software/PulseAudio/Documentation/Developer/Clients/DBus/Enumerations|Software/PulseAudio/Documentation/Developer/Clients/DBus/Enumerations]]]] for the list of possible values. + + +#### !SampleRate + +* Type: Uint32 +* Access: read +The sample rate of the device. + + +#### Channels + +* Type: [Uint32] +* Access: read +The channel map of the device. The channel count can be inferred from this. The channel map is expressed as a list of channel positions, see [[[[Software/PulseAudio/Documentation/Developer/Clients/DBus/Enumerations|Software/PulseAudio/Documentation/Developer/Clients/DBus/Enumerations]]]] for the list of possible channel position values. + + +#### Volume + +* Type: [Uint32] +* Access: read/write +The volume of the device. The array is matched against the Channels property: the first array element is the volume of the first channel in the Channels property, and so on. + +There are two ways to adjust the volume. You can either adjust the overall volume by giving a single-value array, or you can precisely control the individual channels by passing an array containing a value for each channel. + + +#### !HasFlatVolume + +* Type: Boolean +* Access: read +Whether or not the device is configured to use the "flat volume" logic, that is, the device volume follows the maximum volume of all connected streams. Currently this is not implemented for sources, so for them this property is always false. + + +#### !HasConvertibleToDecibelVolume + +* Type: Boolean +* Access: read +If this is true, the volume values of the Volume property can be converted to decibels with pa_sw_volume_to_dB(). If you want to avoid the C API, the function does the conversion as follows: + +* If input = 0, then output = -200.0 +* Otherwise output = 20 * log10((input / 65536)<sup>3</sup>) + +#### !BaseVolume + +* Type: Uint32 +* Access: read +The volume level at which the device doesn't perform any amplification or attenuation. + + +#### !VolumeSteps + +* Type: Uint32 +* Access: read +If the device doesn't support arbitrary volume values, this property tells the number of possible volume values. Otherwise this property has value 65537. + + +#### Mute + +* Type: Boolean +* Access: read/write +Whether or not the device is currently muted. + + +#### !HasHardwareVolume + +* Type: Boolean +* Access: read +Whether or not the device volume controls the hardware volume. + + +#### !HasHardwareMute + +* Type: Boolean +* Access: read +Whether or not muting the device controls the hardware mute state. + + +#### !ConfiguredLatency + +* Type: Uint64 +* Access: read +The latency in microseconds that device has been configured to. + + +#### !HasDynamicLatency + +* Type: Boolean +* Access: read +Whether or not the device latency can be adjusted according to the needs of the connected streams. + + +#### Latency + +* Type: Uint64 +* Access: read +The length of queued audio in the device buffer. Not all devices support latency querying; in those cases this property does not exist. + +* Errors: + * - [[org.PulseAudio.Core1.NoSuchPropertyError|Software/PulseAudio/Documentation/Developer/Clients/DBus/Errors]] if the device doesn't support latency querying. + +#### !IsHardwareDevice + +* Type: Boolean +* Access: read +Whether or not this device is a hardware device. + + +#### !IsNetworkDevice + +* Type: Boolean +* Access: read +Whether or not this device is a network device. + + +#### State + +* Type: Uint32 +* Access: read +The current state of the device. See [[[[Software/PulseAudio/Documentation/Developer/Clients/DBus/Enumerations|Software/PulseAudio/Documentation/Developer/Clients/DBus/Enumerations]]]] for the list of possible values. + + +#### Ports + +* Type: [ObjectPath] +* Access: read +All available device ports. May be empty. + + +#### !ActivePort + +* Type: ObjectPath +* Access: read/write +The currently active device port. This property doesn't exist if the device does not have any ports. + +* Errors: + * - [[org.PulseAudio.Core1.NoSuchPropertyError|Software/PulseAudio/Documentation/Developer/Clients/DBus/Errors]] if this device doesn't have any ports. + +#### !PropertyList + +* Type: {String -> [Byte]} +* Access: read +The device's property list. + + +### Methods + + +#### Suspend + +* Arguments: suspend : Boolean + * - suspend: True to suspend, false to unsuspend +Suspends or unsuspends the device. + + +#### !GetPortByName + +* Arguments: name : String + * - name: Port name +* Returns: port : ObjectPath + * - port: Device port object +Find the device port with the given name. + +* Errors: + * - [[org.PulseAudio.Core1.NotFoundError|Software/PulseAudio/Documentation/Developer/Clients/DBus/Errors]] if no such port is available. + +### Signals + + +#### !VolumeUpdated + +* Parameters: volume : [Uint32] + * - volume: The new volume values +The device's volume was modified. + + +#### !MuteUpdated + +* Parameters: muted : Boolean + * - muted: The new mute state +The device was muted or unmuted. + + +#### !StateUpdated + +* Parameters: state : Uint32 + * - state: The new device state +The device's state changed. + + +#### !ActivePortUpdated + +* Parameters: port : ObjectPath + * - port: Activated device port +The active device port was changed. + + +#### !PropertyListUpdated + +* Parameters: property_list : {String -> [Byte]} + * - property_list: The new property list +The device's property list was modified. + + +## org.PulseAudio.Core1.Sink + + +### Properties + + +#### !MonitorSource + +* Type: ObjectPath +* Access: read +The monitor source object of this sink. + + +## org.PulseAudio.Core1.Source + + +### Properties + + +#### !MonitorOfSink + +* Type: ObjectPath +* Access: read +The sink of which monitor source this source is. If this source is not a monitor source, this property does not exist. + +* Errors: + * - [[org.PulseAudio.Core1.NoSuchPropertyError|Software/PulseAudio/Documentation/Developer/Clients/DBus/Errors]] if this source isn't a monitor source.
\ No newline at end of file diff --git a/Software/PulseAudio/Documentation/Developer/Clients/DBus/DevicePort.mdwn b/Software/PulseAudio/Documentation/Developer/Clients/DBus/DevicePort.mdwn new file mode 100644 index 00000000..35af642e --- /dev/null +++ b/Software/PulseAudio/Documentation/Developer/Clients/DBus/DevicePort.mdwn @@ -0,0 +1,45 @@ + + +# D-Bus Interface: Device Ports + +[[(Back to the toplevel D-Bus Interface page)|Software/PulseAudio/Documentation/Developer/Clients/DBus]] + +Objects and their interfaces: + +* /org/pulseaudio/core1/sinkX/portY + * - org.PulseAudio.Core1.DevicePort - org.freedesktop.DBus.Properties - org.freedesktop.DBus.Introspectable. +* /org/pulseaudio/core1/sourceX/portY + * - org.PulseAudio.Core1.DevicePort - org.freedesktop.DBus.Properties - org.freedesktop.DBus.Introspectable. + +## org.PulseAudio.Core1.!DevicePort + + +### Properties + + +#### Index + +* Type: Uint32 +* Access: read +The port index. The index is only used in the port's D-Bus object path, it has no meaning in PulseAudio's internal working. + + +#### Name + +* Type: String +* Access: read +The port name. + + +#### Description + +* Type: String +* Access: read +The port description. + + +#### Priority + +* Type: Uint32 +* Access: read +The priority of the port. Ports are usually presented to the user ordered by the priority. The port with the highest priority is activated by default. diff --git a/Software/PulseAudio/Documentation/Developer/Clients/DBus/Enumerations.mdwn b/Software/PulseAudio/Documentation/Developer/Clients/DBus/Enumerations.mdwn new file mode 100644 index 00000000..a4a80537 --- /dev/null +++ b/Software/PulseAudio/Documentation/Developer/Clients/DBus/Enumerations.mdwn @@ -0,0 +1,88 @@ + + +# D-Bus Interface: Enumerations + +[[(Back to the toplevel D-Bus Interface page)|Software/PulseAudio/Documentation/Developer/Clients/DBus]] + + +## Sample formats + +* 0 : Unsigned 8 bit PCM +* 1 : 8 bit a-Law +* 2 : 8 bit mu-Law +* 3 : Signed 16 bit PCM, little endian +* 4 : Signed 16 bit PCM, big endian +* 5 : 32 bit IEEE floating point, little endian, range -1.0 to 1.0 +* 6 : 32 bit IEEE floating point, big endian, range -1.0 to 1.0 +* 7 : Signed 32 bit PCM, little endian +* 8 : Signed 32 bit PCM, big endian +* 9 : Signed 24 bit PCM packed, little endian +* 10 : Signed 24 bit PCM packed, big endian +* 11 : Signed 24 bit PCM in LSB of 32 bit words, little endian +* 12 : Signed 24 bit PCM in LSB of 32 bit words, big endian + +## Channel positions + +* 0 : Mono +* 1 : Front left +* 2 : Front right +* 3 : Front center +* 4 : Rear center +* 5 : Rear left +* 6 : Rear right +* 7 : LFE +* 8 : Front left of center +* 9 : Front right of center +* 10 : Side left +* 11 : Side right +* 12 : Aux 0 +* 13 : Aux 1 +* 14 : Aux 2 +* 15 : Aux 3 +* 16 : Aux 4 +* 17 : Aux 5 +* 18 : Aux 6 +* 19 : Aux 7 +* 20 : Aux 8 +* 21 : Aux 9 +* 22 : Aux 10 +* 23 : Aux 11 +* 24 : Aux 12 +* 25 : Aux 13 +* 26 : Aux 14 +* 27 : Aux 15 +* 28 : Aux 16 +* 29 : Aux 17 +* 30 : Aux 18 +* 31 : Aux 19 +* 32 : Aux 20 +* 33 : Aux 21 +* 34 : Aux 22 +* 35 : Aux 23 +* 36 : Aux 24 +* 37 : Aux 25 +* 38 : Aux 26 +* 39 : Aux 27 +* 40 : Aux 28 +* 41 : Aux 29 +* 42 : Aux 30 +* 43 : Aux 31 +* 44 : Top center +* 45 : Top front left +* 46 : Top front right +* 47 : Top front center +* 48 : Top rear left +* 49 : Top rear right +* 50 : Top rear center + +## Device states + +* 0 : Running, the device is being used by at least one non-corked stream. +* 1 : Idle, the device is active, but no non-corked streams are connected to it. +* 2 : Suspended, the device is not in use and may be currently closed. + +## Update modes + +* 0 : Replace the entire set with the new set, don't keep any old data around. +* 1 : Merge the new set into the existing one, not replacing any old entries if they share a common key with the new set. +* 2 : Merge the new set into the existing one, replacing all old entries that share a common key with the new set.
\ No newline at end of file diff --git a/Software/PulseAudio/Documentation/Developer/Clients/DBus/Errors.mdwn b/Software/PulseAudio/Documentation/Developer/Clients/DBus/Errors.mdwn new file mode 100644 index 00000000..28f7e4eb --- /dev/null +++ b/Software/PulseAudio/Documentation/Developer/Clients/DBus/Errors.mdwn @@ -0,0 +1,22 @@ + + +# D-Bus Interface: Errors + +[[(Back to the toplevel D-Bus Interface page)|Software/PulseAudio/Documentation/Developer/Clients/DBus]] + +None of the errors have other parameters than the human-readable error string. + + +## org.PulseAudio.Core1.!NotFoundError + +Returned when something was not found. + + +## org.PulseAudio.Core1.!NoSuchPropertyError + +Returned when a property is accessed that doesn't exist. + + +## org.PulseAudio.Core1.!BadStateError + +Returned when trying to do something that can't be done right now, but might be possible at some other time. diff --git a/Software/PulseAudio/Documentation/Developer/Clients/DBus/Ladspa.mdwn b/Software/PulseAudio/Documentation/Developer/Clients/DBus/Ladspa.mdwn new file mode 100644 index 00000000..b9b1328f --- /dev/null +++ b/Software/PulseAudio/Documentation/Developer/Clients/DBus/Ladspa.mdwn @@ -0,0 +1,30 @@ + + +# D-Bus Interface: Ladspa Extension + +[[(Back to the toplevel D-Bus Interface page)|Software/PulseAudio/Documentation/Developer/Clients/DBus]] + +When module-ladspa-sink is loaded, it creates a virtual sink with a ladspa filter, and any streams played to that sink will get their audio processed by the filter. The filter parameters can be queried and modified using the interface described here. + +Objects and their interfaces: + +* /org/pulseaudio/core1/sinkX + * - org.PulseAudio.Ext.Ladspa1 +The Ladspa interface is implemented by the sink object that is created by module-ladspa-sink. In order to use the Ladspa interface, the client needs to know the object path of the ladspa sink. That can be provided by the user, or the application can scan all sink objects and look which ones look like ladspa sinks. + + +## org.PulseAudio.Ext.Ladspa1 + + +### Properties + + +#### AlgorithmParameters + +* Type: ([Double], [Boolean]) +* Access: read/write +The filter parameters are stored in a struct with two arrays. The first array contains the parameter values and the second array contains the "use default" flags, one flag for each value. (If you're thinking that it would make more sense to have an array of structs, each struct containing the parameter value and the corresponding "use default" flag, you're right.) + +The meaning of each parameter is defined by the ladspa plugin. There's currently no support for querying any information beyond the current value about the parameter, such as its name, so this interface is pretty much limited to cases where the client knows via some other means what plugin it's dealing with. + +The "use default" flag means that the default value of the parameter is in use (when reading the property) or should be used (when writing the property). When writing the property, if the "use default" flag is set for a parameter, the corresponding parameter value is ignored. diff --git a/Software/PulseAudio/Documentation/Developer/Clients/DBus/Memstats.mdwn b/Software/PulseAudio/Documentation/Developer/Clients/DBus/Memstats.mdwn new file mode 100644 index 00000000..0f709966 --- /dev/null +++ b/Software/PulseAudio/Documentation/Developer/Clients/DBus/Memstats.mdwn @@ -0,0 +1,50 @@ + + +# D-Bus Interface: Memory Statistics + +[[(Back to the toplevel D-Bus Interface page)|Software/PulseAudio/Documentation/Developer/Clients/DBus]] + +Objects and their interfaces: + +* /org/pulseaudio/core1/memstats + * - org.PulseAudio.Core1.Memstats - org.freedesktop.DBus.Properties - org.freedesktop.DBus.Introspectable. + +## org.PulseAudio.Core1.Memstats + + +### Properties + + +#### !CurrentMemblocks + +* Type: Uint32 +* Access: read +The count of currently allocated memblocks. + + +#### !CurrentMemblocksSize + +* Type: Uint32 +* Access: read +The amount of memory consumed by currently allocated memblocks, in bytes. + + +#### !AccumulatedMemblocks + +* Type: Uint32 +* Access: read +The count of memblocks allocated during the lifetime of the server. + + +#### !AccumulatedMemblocksSize + +* Type: Uint32 +* Access: read +The amount of memory consumed by all memblocks allocated during the lifetime of the server, in bytes. + + +#### !SampleCacheSize + +* Type: Uint32 +* Access: read +The amount of memory currently consumed by samples, in bytes. diff --git a/Software/PulseAudio/Documentation/Developer/Clients/DBus/Module.mdwn b/Software/PulseAudio/Documentation/Developer/Clients/DBus/Module.mdwn new file mode 100644 index 00000000..1d0a35b3 --- /dev/null +++ b/Software/PulseAudio/Documentation/Developer/Clients/DBus/Module.mdwn @@ -0,0 +1,70 @@ + + +# D-Bus Interface: Modules + +[[(Back to the toplevel D-Bus Interface page)|Software/PulseAudio/Documentation/Developer/Clients/DBus]] + +Objects and their interfaces: + +* /org/pulseaudio/core1/moduleX + * - org.PulseAudio.Core1.Module - org.freedesktop.DBus.Properties - org.freedesktop.DBus.Introspectable + +## org.PulseAudio.Core1.Module + + +### Properties + + +#### Index + +* Type: Uint32 +* Access: read +The module index. + + +#### Name + +* Type: String +* Access: read +The module name. + + +#### Arguments + +* Type: {String -> String} +* Access: read +The arguments used when loading the module. The keys are argument names and the values are argument values. + + +#### !UsageCounter + +* Type: Uint32 +* Access: read +The number of module users. Not all modules count their users; in those cases this property does not exist. + +* Errors: + * - [[org.PulseAudio.Core1.NoSuchPropertyError|Software/PulseAudio/Documentation/Developer/Clients/DBus/Errors]] if this module doesn't count its users. + +#### !PropertyList + +* Type: {String -> [Byte]} +* Access: read +The module's property list. + + +### Methods + + +#### Unload + +Unloads the module. + + +### Signals + + +#### !PropertyListUpdated + +* Parameters: property_list : {String -> [Byte]} + * - property_list: The new property list +The module's property list was modified. diff --git a/Software/PulseAudio/Documentation/Developer/Clients/DBus/Sample.mdwn b/Software/PulseAudio/Documentation/Developer/Clients/DBus/Sample.mdwn new file mode 100644 index 00000000..273d6ebe --- /dev/null +++ b/Software/PulseAudio/Documentation/Developer/Clients/DBus/Sample.mdwn @@ -0,0 +1,134 @@ + + +# D-Bus Interface: Samples + +[[(Back to the toplevel D-Bus Interface page)|Software/PulseAudio/Documentation/Developer/Clients/DBus]] + +Objects and their interfaces: + +* /org/pulseaudio/core1/sampleX + * - org.PulseAudio.Core1.Sample - org.freedesktop.DBus.Properties - org.freedesktop.DBus.Introspectable + +## org.PulseAudio.Core1.Sample + + +### Properties + + +#### Index + +* Type: Uint32 +* Access: read +The sample index. + + +#### Name + +* Type: String +* Access: read +The sample name. + + +#### !SampleFormat + +* Type: Uint32 +* Access: read +The sample format of the sample (try not to get confused, the two "samples" in that sentence referred to different things). See [[[[Software/PulseAudio/Documentation/Developer/Clients/DBus/Enumerations|Software/PulseAudio/Documentation/Developer/Clients/DBus/Enumerations]]]] for the list of possible values. + +This property doesn't exist if this is a "lazy" sample and is not loaded into memory yet. + +* Errors: + * - [[org.PulseAudio.Core1.NoSuchPropertyError|Software/PulseAudio/Documentation/Developer/Clients/DBus/Errors]] if the sample hasn't been loaded into memory yet. + +#### !SampleRate + +* Type: Uint32 +* Access: read +The sample rate of the sample. + +This property doesn't exist if this is a "lazy" sample and is not loaded into memory yet. + +* Errors: + * - [[org.PulseAudio.Core1.NoSuchPropertyError|Software/PulseAudio/Documentation/Developer/Clients/DBus/Errors]] if the sample hasn't been loaded into memory yet. + +#### Channels + +* Type: [Uint32] +* Access: read +The channel map of the sample. The channel count can be inferred from this. The channel map is expressed as a list of channel positions, see [[[[Software/PulseAudio/Documentation/Developer/Clients/DBus/Enumerations|Software/PulseAudio/Documentation/Developer/Clients/DBus/Enumerations]]]] for the list of possible channel position values. + +This property doesn't exist if this is a "lazy" sample and is not loaded into memory yet. + +* Errors: + * - [[org.PulseAudio.Core1.NoSuchPropertyError|Software/PulseAudio/Documentation/Developer/Clients/DBus/Errors]] if the sample hasn't been loaded into memory yet. + +#### !DefaultVolume + +* Type: [Uint32] +* Access: read +The default volume of the sample. The volume elements in the array match the channel positions in the Channels property. + +This property doesn't exist if there's no default volume stored. In that case the default volume will be decided at the time of playing the sample. + +* Errors: + * - [[org.PulseAudio.Core1.NoSuchPropertyError|Software/PulseAudio/Documentation/Developer/Clients/DBus/Errors]] if the sample doesn't have a stored default volume. + +#### Duration + +* Type: Uint64 +* Access: read +The duration of the sample in microseconds. + +This property doesn't exist if this is a "lazy" sample and is not loaded into memory yet. + +* Errors: + * - [[org.PulseAudio.Core1.NoSuchPropertyError|Software/PulseAudio/Documentation/Developer/Clients/DBus/Errors]] if the sample hasn't been loaded into memory yet. + +#### Bytes + +* Type: Uint32 +* Access: read +The length of the sample in bytes. + +This property doesn't exist if this is a "lazy" sample and is not loaded into memory yet. + +* Errors: + * - [[org.PulseAudio.Core1.NoSuchPropertyError|Software/PulseAudio/Documentation/Developer/Clients/DBus/Errors]] if the sample hasn't been loaded into memory yet. + +#### !PropertyList + +* Type: {String -> [Byte]} +* Access: read +The sample's property list. + + +### Methods + + +#### Play + +* Arguments: volume : Uint32, property_list : {String -> [Byte]} + * - volume: The volume at which to play the sample. Pass 65536 to play at the default level. Larger values are allowed, but those almost never make sense, because digital amplification very likely causes distortion. - property_list: Additional properties to use when playing the sample. This can also be used to override existing properties. +Plays the sample. The server decides which sink will be used. + + +#### !PlayToSink + +* Arguments: sink : ObjectPath, volume : Uint32, property_list : {String -> [Byte]} + * - sink: The sink through which the sample shall be played - volume: The volume at which to play the sample. Pass 65536 to play at the default level. Larger values are allowed, but those almost never make sense, because digital amplification very likely causes distortion. - property_list: Additional properties to use when playing the sample. This can also be used to override existing properties. +Plays the sample to the given sink. + + +#### Remove + +Removes the sample from the sample cache. + + +### Signals + + +#### !PropertyListUpdated + +* Parameters: property_list : {String -> [Byte]} + * - property_list: The new property list +The sample's property list was modified. diff --git a/Software/PulseAudio/Documentation/Developer/Clients/DBus/Stream.mdwn b/Software/PulseAudio/Documentation/Developer/Clients/DBus/Stream.mdwn new file mode 100644 index 00000000..3f04bedb --- /dev/null +++ b/Software/PulseAudio/Documentation/Developer/Clients/DBus/Stream.mdwn @@ -0,0 +1,199 @@ + + +# D-Bus Interface: Streams + +[[(Back to the toplevel D-Bus Interface page)|Software/PulseAudio/Documentation/Developer/Clients/DBus]] + +Objects and their interfaces: + +* /org/pulseaudio/core1/playback_streamX + * - org.PulseAudio.Core1.Stream - org.freedesktop.DBus.Properties - org.freedesktop.DBus.Introspectable +* /org/pulseaudio/core1/record_streamX + * - org.PulseAudio.Core1.Stream - org.freedesktop.DBus.Properties - org.freedesktop.DBus.Introspectable + +## org.PulseAudio.Core1.Stream + + +### Properties + + +#### Index + +* Type: Uint32 +* Access: read +The stream index. Playback and record stream indices are separate, so it's perfectly normal to have two streams with the same index: the other stream is a playback stream and the other is a record stream. + + +#### Driver + +* Type: String +* Access: read +The driver that implements the stream object. This is usually expressed as a source code file name, for example "protocol-native.c". + + +#### !OwnerModule + +* Type: ObjectPath +* Access: read +The module that owns this stream. It's not guaranteed that any module claims ownership; in such case this property does not exist. + +* Errors: + * - [[org.PulseAudio.Core1.NoSuchPropertyError|Software/PulseAudio/Documentation/Developer/Clients/DBus/Errors]] if this stream is not owned by any module. + +#### Client + +* Type: ObjectPath +* Access: read +The client whose stream this is. Not all streams are created by clients, in those cases this property does not exist. + +* Errors: + * - [[org.PulseAudio.Core1.NoSuchPropertyError|Software/PulseAudio/Documentation/Developer/Clients/DBus/Errors]] if this stream is not created by a client. + +#### Device + +* Type: ObjectPath +* Access: read +The device this stream is connected to. + + +#### !SampleFormat + +* Type: Uint32 +* Access: read +The sample format of the stream. See [[[[Software/PulseAudio/Documentation/Developer/Clients/DBus/Enumerations|Software/PulseAudio/Documentation/Developer/Clients/DBus/Enumerations]]]] for the list of possible values. + + +#### !SampleRate + +* Type: Uint32 +* Access: read +The sample rate of the stream. + + +#### Channels + +* Type: [Uint32] +* Access: read +The channel map of the stream. The channel count can be inferred from this. The channel map is expressed as a list of channel positions, see [[[[Software/PulseAudio/Documentation/Developer/Clients/DBus/Enumerations|Software/PulseAudio/Documentation/Developer/Clients/DBus/Enumerations]]]] for the list of possible channel position values. + + +#### Volume + +* Type: [Uint32] +* Access: read/write +The volume of the stream. The array is matched against the Channels property: the first array element is the volume of the first channel in the Channels property, and so on. + +There are two ways to adjust the volume. You can either adjust the overall volume by giving a single-value array, or you can precisely control the individual channels by passing an array containing a value for each channel. + +The volume can only be written if [[VolumeWritable|Software/PulseAudio/Documentation/Developer/Clients/DBus/Stream]] is true. + +* Errors: + * - [[org.PulseAudio.Core1.NoSuchPropertyError|Software/PulseAudio/Documentation/Developer/Clients/DBus/Errors]] if the stream doesn't have volume (record streams don't currently have volume at all). - [[org.PulseAudio.Core1.BadStateError|Software/PulseAudio/Documentation/Developer/Clients/DBus/Errors]] if trying to set a read-only volume. + +#### !VolumeWritable + +* Type: Boolean +* Access: read +Whether or not the [[Volume|Software/PulseAudio/Documentation/Developer/Clients/DBus/Stream]] property can be set. Note that read-only volumes can still change, clients just can't control them. + + +#### Mute + +* Type: Boolean +* Access: read/write +Whether or not the stream is currently muted. Record streams don't currently support muting, so this property exists for playback streams only for now. + +* Errors: + * - [[org.PulseAudio.Core1.NoSuchPropertyError|Software/PulseAudio/Documentation/Developer/Clients/DBus/Errors]] if this is a record stream and the server doesn't implement volume for record streams. + +#### !BufferLatency + +* Type: Uint64 +* Access: read +The length of buffered audio in microseconds that is not at the device yet/anymore. + + +#### !DeviceLatency + +* Type: Uint64 +* Access: read +The length of buffered audio in microseconds at the device. + + +#### !ResampleMethod + +* Type: String +* Access: read +The resampling algorithm that is used to convert the stream audio data to/from the device's sample rate. + + +#### !PropertyList + +* Type: {String -> [Byte]} +* Access: read +The stream's property list. + + +### Methods + + +#### Move + +* Arguments: device : ObjectPath + * - device: The device to move to +Moves the stream to another device. + + +#### Kill + +Kills the stream. + + +### Signals + + +#### !DeviceUpdated + +* Parameters: device : ObjectPath + * - device: The new device +The stream was moved to another device. + + +#### !SampleRateUpdated + +* Parameters: sample_rate : Uint32 + * - sample_rate: The new sample rate +The stream's sample rate was changed. + + +#### !VolumeUpdated + +* Parameters: volume : [Uint32] + * - volume: The new volume values +The stream's volume was modified. + + +#### !MuteUpdated + +* Parameters: muted : Boolean + * - muted: The new mute state +The stream was muted or unmuted. + + +#### !PropertyListUpdated + +* Parameters: property_list : {String -> [Byte]} + * - property_list: The new property list +The stream's property list was modified. + + +#### !StreamEvent + +* Parameters: name : String, property_list : {String -> [Byte]} + * - name: Event name - property_list: Additional event parameters +This signal is emitted when the server sends an event to a stream. Currently two stream events are defined: + +* "request-cork" + * - An application should cork a specific stream. This can be sent for example if the server implements a policy that when a phone call starts, all music streams shall pause. The property list doesn't contain any additional parameters. +* "request-uncork" + * - Opposite of "request-cork". The property list doesn't contain any additional parameters.
\ No newline at end of file diff --git a/Software/PulseAudio/Documentation/Developer/Clients/DBus/StreamRestore.mdwn b/Software/PulseAudio/Documentation/Developer/Clients/DBus/StreamRestore.mdwn new file mode 100644 index 00000000..e0b93811 --- /dev/null +++ b/Software/PulseAudio/Documentation/Developer/Clients/DBus/StreamRestore.mdwn @@ -0,0 +1,152 @@ + + +# D-Bus Interface: Stream Restore Extension + +[[(Back to the toplevel D-Bus Interface page)|Software/PulseAudio/Documentation/Developer/Clients/DBus]] + +TODO: Explain how this extension works. + +Objects and their interfaces: + +* /org/pulseaudio/stream_restore1 + * - org.PulseAudio.Ext.StreamRestore1 - org.freedesktop.DBus.Properties - org.freedesktop.DBus.Introspectable +* /org/pulseaudio/stream_restore1/entryX + * - org.PulseAudio.Ext.StreamRestore1.RestoreEntry - org.freedesktop.DBus.Properties - org.freedesktop.DBus.Introspectable + +## org.PulseAudio.Ext.!StreamRestore1 + + +### Properties + + +#### !InterfaceRevision + +* Type: Uint32 +* Access: read +Similarly to the core API, the "major" version of the stream restore extension interface is embedded in the interface name: org.PulseAudio.Ext.StreamRestore1. When changes are made that break compatibility between old clients and new servers the major version is incremented. This property tells the "minor" version, that is, when new features are added to the interface, this version number is incremented so that new clients can check if the server they talk to supports the new features. This documentation defines revision 0. + + +#### Entries + +* Type: [ObjectPath] +* Access: read +All stored policy entries. + + +### Methods + + +#### !AddEntry + +* Arguments: name : String, device : String, volume : [(Uint32, Uint32)], mute : Boolean, apply_immediately : Boolean + * - name: The entry name, formatted as specified somewhere (TODO: where?) - device: The device that the matching streams should use, or an empty string to not restore the device - volume: The volume as ([[channel position|Software/PulseAudio/Documentation/Developer/Clients/DBus/Enumerations]], volume) pairs that the matching streams should use, or an empty array to not restore the volume. - mute: Whether the matching streams should be muted - apply_immediately: Whether the new rule should be applied to exisiting streams as well as future streams +* Returns: entry : ObjectPath + * - entry: Added entry object +Adds a new entry to the stream restore database. If there already is an entry with the same name, the old entry is replaced with the new. Or rather, the properties of the new entry replace the properties of the old entry - no new entry object is created. + + +#### !GetEntryByName + +* Arguments: name : String + * - name: Entry name +* Returns: entry : ObjectPath + * - entry: Stream restore entry object +Find the restore entry with the given name. + +* Errors: + * - [[org.PulseAudio.Core1.NotFoundError|Software/PulseAudio/Documentation/Developer/Clients/DBus/Errors]] if no such entry exists. + +### Signals + + +#### !NewEntry + +* Parameters: entry : ObjectPath + * - entry: Added entry object +An entry was added. + + +#### !EntryRemoved + +* Parameters: entry : ObjectPath + * - entry: Removed entry object +An entry was removed. + + +## org.PulseAudio.Ext.!StreamRestore1.!RestoreEntry + + +### Properties + + +#### Index + +* Type: Uint32 +* Access: read +The entry index. This index is specific to the D-Bus interface only: the entry name is the real key property, but entries are assigned an index for generating the object path. + + +#### Name + +* Type: String +* Access: read +The entry name. + + +#### Device + +* Type: String +* Access: read/write +The device to which matching streams are connected. May be an empty string, in which case this entry doesn't dictate the device. + +When writing to this property, the change is applied immediately to existing streams. + + +#### Volume + +* Type: [(Uint32, Uint32)] +* Access: read/write +The saved volume as ([[channel position|Software/PulseAudio/Documentation/Developer/Clients/DBus/Enumerations]], volume) pairs. May be an empty array, in which case this entry doesn't dictate the stream volume. + +When writing to this property, the change is applied immediately to existing streams. + + +#### Mute + +* Type: Boolean +* Access: read/write +The saved mute status. + +When writing to this property, the change is applied immediately to existing streams. + + +### Methods + + +#### Remove + +Removes this entry from the stream restore database. + + +### Signals + + +#### !DeviceUpdated + +* Parameters: device : String + * - device: The new device +The restore entry was assigned a new device. + + +#### !VolumeUpdated + +* Parameters: volume : [(Uint32, Uint32)] + * - volume: The new volume +The restore entry was assigned a new volume value. + + +#### !MuteUpdated + +* Parameters: muted : Boolean + * - muted: The new mute state +The restore entry was assigned a new mute state. diff --git a/Software/PulseAudio/Documentation/Developer/Clients/LactencyControl.mdwn b/Software/PulseAudio/Documentation/Developer/Clients/LactencyControl.mdwn new file mode 100644 index 00000000..f4b70c2d --- /dev/null +++ b/Software/PulseAudio/Documentation/Developer/Clients/LactencyControl.mdwn @@ -0,0 +1,42 @@ + + +# Latency Control + +So you are writing an application and want to control the latency PulseAudio provides for it, for example because you are writing a voip tool that needs latencies that are near to some specific value. Here's how you do it with PA: + +First, make sure you run PA in timer scheduling mode (tsched=1) for ALSA devices which is the default for most modern distributions, with the infamous exception of Ubuntu (9.04 only). Only when that is enabled PA is able to adjust the latency to what your application asks for. Non-ALSA devices (such as Bluetooth audio) generally have a fixed latency which cannot be influenced by software. + +In your code you then have to do the following when calling pa_stream_connect_playback() resp. pa_stream_connect_record(): + +1. Pass **PA_STREAM_ADJUST_LATENCY** in the **flags** parameter. Only if this flag is set PA will reconfigure the low-level device's buffer size and adjust it to the latency you specify. +1. Pass a pa_buffer_attr struct in the **buffer_attr** parameter. In the fields of this struct make sure to initialize **every single field** to (uint32_t) -1, with the exception of **tlength** (for playback) resp. **fragsize** (for recording). Initialize those to the latency you want to achieve. Use pa_usec_to_bytes(usec, &ss) to convert the latency from a time unit to bytes. +Please note that clients may ask for a specific latency, but PA takes this only as a hint, it does not guarantee that it will provide it. That means after initialization you MUST base your timing code on the actually measured latency as returned by pa_stream_get_latency() (and friends), you MAY NOT make assumptions that the measured latency will actually be near or even below what you asked for. + +If the underlying device has latency restrictions the actual measured latency might be either higher or lower than what you asked for. If the OS scheduler was not able to provide PA with the necessary scheduling latencies needed to fulfill the audio latencies these will be increased to make sure drop-outs stay the exception, not the rule. If a stream gets moved between devices the latency may change, due to different hardware constraints. Finally, PA will configure the device buffer to the lowest latency of all applications streams connected to it. That means that your measured latency might dynamically change during runtime and might deviate very much from what you initially asked for. But again, PA will try its best to fulfill what you requested. + +_So in summary: tell PA what latency you want, but program defensively so that you can deal with getting both lower or higher measured latencies._ + +If you want to verify how the latencies your application asked for are actually handled by PA check the output of "pacmd list-sinks". This will show you the list of sinks with their configured and measured latencies. The 'current latency' field is the currently measured latency (probably not too useful unless you combine it with a timestamp). The 'configured latency' shows the minimal latency configured by all applications connected to the device, plus the range that is acceptable to the device. It is only shown for variable latency devices. For those with fixed latency, check out the 'fixed latency' field. Also check out the output of "pacmd list-sink-inputs" which shows both the measured latency for the application stream as well as the requested latency for it. + +Side note: If the buffering parameters change during runtime you will get a notification callback which may register via pa_stream_set_buffer_attr_callack(). Note that this will tell you the changes to the buffer_attr structure, which is related to but different from the measured latency! + +You may change the latency during runtime with pa_stream_set_buffer_attr(). + + +# Developing High-Latency Applications + +By default (i.e. when the buffer_attr argument to pa_stream_connect_playback() is NULL) PA will pick a latency that is somewhat similar to what programs used to get when using OSS, or ALSA directly and didn't specify any particular latency requirements. For a lot of use cases where latency does not matter (such as media players) this latency is much smaller then would be good for optimal power consumption. That means it is highly recommended passing a buffer_attr argument in those applications, with a tlength field initialized to (uint32_t) -1, which effectively means "pick the highest latency the device supports". Usually that means that you get 2s latency, which has the effect of reducing wakeups to something near 1/s. Make sure to drop the server side playback buffers when seeking/pausing/..., so that these actions are instantanious although you buffered 2s. + +_Note that passing a NULL buffer_attr is different from passing one with every field initialized to (uint32_t) -1! The former means 'get me the default latency'. The latter means 'get me the highest latency possible'. The latter is a much better idea most of the time than the former! _ + + +# How to pick the latency + +For the sake of reducing power consumption and drop-out safety always make sure to pick the **highest latency possible** that fulfills your needs. Never pick a lower latency than you really need. If you do pick needlessly low latencies you just burn CPU and make it more likely that we will get a drop-out. And worst of all that makes PA and me look bad, since people will blame PA and me for it. And I don't like to look bad! ;-) Extensive CPU load will show up as PA CPU load in 'top'. + + +# Why such a complex API? + +Yes, requiring to set a flag plus filling in a struct is a bit too complex. This has mostly historical reasons. Sorry for that. + +This all applies to PA 0.9.16 and newer. diff --git a/Software/PulseAudio/Documentation/Developer/Clients/Samples/AsyncDeviceList.moin b/Software/PulseAudio/Documentation/Developer/Clients/Samples/AsyncDeviceList.moin new file mode 100644 index 00000000..c68bacc4 --- /dev/null +++ b/Software/PulseAudio/Documentation/Developer/Clients/Samples/AsyncDeviceList.moin @@ -0,0 +1,246 @@ +<<Include(Software/PulseAudio/TOC)>>
+
+This is not production ready code. There’s a lot of error checking that’s not being done. But this should at least give you an idea of how to begin using the PulseAudio asynchronous API.
+
+To compile this program, you will need to link against the pulse library. For example, if you save this program as "pulsedevicelist.c", you should run:
+
+{{{
+gcc -Wall -o pulsedevicelist pulsedevicelist.c -lpulse
+}}}
+
+{{{
+#!c
+
+#include <stdio.h>
+#include <string.h>
+#include <pulse/pulseaudio.h>
+
+// Field list is here: http://0pointer.de/lennart/projects/pulseaudio/doxygen/structpa__sink__info.html
+typedef struct pa_devicelist {
+ uint8_t initialized;
+ char name[512];
+ uint32_t index;
+ char description[256];
+} pa_devicelist_t;
+
+void pa_state_cb(pa_context *c, void *userdata);
+void pa_sinklist_cb(pa_context *c, const pa_sink_info *l, int eol, void *userdata);
+void pa_sourcelist_cb(pa_context *c, const pa_source_info *l, int eol, void *userdata);
+int pa_get_devicelist(pa_devicelist_t *input, pa_devicelist_t *output);
+
+
+int main(int argc, char *argv[]) {
+ int ctr;
+
+ // This is where we'll store the input device list
+ pa_devicelist_t pa_input_devicelist[16];
+
+ // This is where we'll store the output device list
+ pa_devicelist_t pa_output_devicelist[16];
+
+ if (pa_get_devicelist(pa_input_devicelist, pa_output_devicelist) < 0) {
+ fprintf(stderr, "failed to get device list\n");
+ return 1;
+ }
+
+ for (ctr = 0; ctr < 16; ctr++) {
+ if (! pa_output_devicelist[ctr].initialized) {
+ break;
+ }
+ printf("=======[ Output Device #%d ]=======\n", ctr+1);
+ printf("Description: %s\n", pa_output_devicelist[ctr].description);
+ printf("Name: %s\n", pa_output_devicelist[ctr].name);
+ printf("Index: %d\n", pa_output_devicelist[ctr].index);
+ printf("\n");
+ }
+
+ for (ctr = 0; ctr < 16; ctr++) {
+ if (! pa_input_devicelist[ctr].initialized) {
+ break;
+ }
+ printf("=======[ Input Device #%d ]=======\n", ctr+1);
+ printf("Description: %s\n", pa_input_devicelist[ctr].description);
+ printf("Name: %s\n", pa_input_devicelist[ctr].name);
+ printf("Index: %d\n", pa_input_devicelist[ctr].index);
+ printf("\n");
+ }
+ return 0;
+}
+
+int pa_get_devicelist(pa_devicelist_t *input, pa_devicelist_t *output) {
+ // Define our pulse audio loop and connection variables
+ pa_mainloop *pa_ml;
+ pa_mainloop_api *pa_mlapi;
+ pa_operation *pa_op;
+ pa_context *pa_ctx;
+
+ // We'll need these state variables to keep track of our requests
+ int state = 0;
+ int pa_ready = 0;
+
+ // Initialize our device lists
+ memset(input, 0, sizeof(pa_devicelist_t) * 16);
+ memset(output, 0, sizeof(pa_devicelist_t) * 16);
+
+ // Create a mainloop API and connection to the default server
+ pa_ml = pa_mainloop_new();
+ pa_mlapi = pa_mainloop_get_api(pa_ml);
+ pa_ctx = pa_context_new(pa_mlapi, "test");
+
+ // This function connects to the pulse server
+ pa_context_connect(pa_ctx, NULL, 0, NULL);
+
+ // This function defines a callback so the server will tell us it's state.
+ // Our callback will wait for the state to be ready. The callback will
+ // modify the variable to 1 so we know when we have a connection and it's
+ // ready.
+ // If there's an error, the callback will set pa_ready to 2
+ pa_context_set_state_callback(pa_ctx, pa_state_cb, &pa_ready);
+
+ // Now we'll enter into an infinite loop until we get the data we receive
+ // or if there's an error
+ for (;;) {
+ // We can't do anything until PA is ready, so just iterate the mainloop
+ // and continue
+ if (pa_ready == 0) {
+ pa_mainloop_iterate(pa_ml, 1, NULL);
+ continue;
+ }
+ // We couldn't get a connection to the server, so exit out
+ if (pa_ready == 2) {
+ pa_context_disconnect(pa_ctx);
+ pa_context_unref(pa_ctx);
+ pa_mainloop_free(pa_ml);
+ return -1;
+ }
+ // At this point, we're connected to the server and ready to make
+ // requests
+ switch (state) {
+ // State 0: we haven't done anything yet
+ case 0:
+ // This sends an operation to the server. pa_sinklist_info is
+ // our callback function and a pointer to our devicelist will
+ // be passed to the callback The operation ID is stored in the
+ // pa_op variable
+ pa_op = pa_context_get_sink_info_list(pa_ctx,
+ pa_sinklist_cb,
+ output
+ );
+
+ // Update state for next iteration through the loop
+ state++;
+ break;
+ case 1:
+ // Now we wait for our operation to complete. When it's
+ // complete our pa_output_devicelist is filled out, and we move
+ // along to the next state
+ if (pa_operation_get_state(pa_op) == PA_OPERATION_DONE) {
+ pa_operation_unref(pa_op);
+
+ // Now we perform another operation to get the source
+ // (input device) list just like before. This time we pass
+ // a pointer to our input structure
+ pa_op = pa_context_get_source_info_list(pa_ctx,
+ pa_sourcelist_cb,
+ input
+ );
+ // Update the state so we know what to do next
+ state++;
+ }
+ break;
+ case 2:
+ if (pa_operation_get_state(pa_op) == PA_OPERATION_DONE) {
+ // Now we're done, clean up and disconnect and return
+ pa_operation_unref(pa_op);
+ pa_context_disconnect(pa_ctx);
+ pa_context_unref(pa_ctx);
+ pa_mainloop_free(pa_ml);
+ return 0;
+ }
+ break;
+ default:
+ // We should never see this state
+ fprintf(stderr, "in state %d\n", state);
+ return -1;
+ }
+ // Iterate the main loop and go again. The second argument is whether
+ // or not the iteration should block until something is ready to be
+ // done. Set it to zero for non-blocking.
+ pa_mainloop_iterate(pa_ml, 1, NULL);
+ }
+}
+
+// This callback gets called when our context changes state. We really only
+// care about when it's ready or if it has failed
+void pa_state_cb(pa_context *c, void *userdata) {
+ pa_context_state_t state;
+ int *pa_ready = userdata;
+
+ state = pa_context_get_state(c);
+ switch (state) {
+ // There are just here for reference
+ case PA_CONTEXT_UNCONNECTED:
+ case PA_CONTEXT_CONNECTING:
+ case PA_CONTEXT_AUTHORIZING:
+ case PA_CONTEXT_SETTING_NAME:
+ default:
+ break;
+ case PA_CONTEXT_FAILED:
+ case PA_CONTEXT_TERMINATED:
+ *pa_ready = 2;
+ break;
+ case PA_CONTEXT_READY:
+ *pa_ready = 1;
+ break;
+ }
+}
+
+// pa_mainloop will call this function when it's ready to tell us about a sink.
+// Since we're not threading, there's no need for mutexes on the devicelist
+// structure
+void pa_sinklist_cb(pa_context *c, const pa_sink_info *l, int eol, void *userdata) {
+ pa_devicelist_t *pa_devicelist = userdata;
+ int ctr = 0;
+
+ // If eol is set to a positive number, you're at the end of the list
+ if (eol > 0) {
+ return;
+ }
+
+ // We know we've allocated 16 slots to hold devices. Loop through our
+ // structure and find the first one that's "uninitialized." Copy the
+ // contents into it and we're done. If we receive more than 16 devices,
+ // they're going to get dropped. You could make this dynamically allocate
+ // space for the device list, but this is a simple example.
+ for (ctr = 0; ctr < 16; ctr++) {
+ if (! pa_devicelist[ctr].initialized) {
+ strncpy(pa_devicelist[ctr].name, l->name, 511);
+ strncpy(pa_devicelist[ctr].description, l->description, 255);
+ pa_devicelist[ctr].index = l->index;
+ pa_devicelist[ctr].initialized = 1;
+ break;
+ }
+ }
+}
+
+// See above. This callback is pretty much identical to the previous
+void pa_sourcelist_cb(pa_context *c, const pa_source_info *l, int eol, void *userdata) {
+ pa_devicelist_t *pa_devicelist = userdata;
+ int ctr = 0;
+
+ if (eol > 0) {
+ return;
+ }
+
+ for (ctr = 0; ctr < 16; ctr++) {
+ if (! pa_devicelist[ctr].initialized) {
+ strncpy(pa_devicelist[ctr].name, l->name, 511);
+ strncpy(pa_devicelist[ctr].description, l->description, 255);
+ pa_devicelist[ctr].index = l->index;
+ pa_devicelist[ctr].initialized = 1;
+ break;
+ }
+ }
+}
+
+}}}
diff --git a/Software/PulseAudio/Documentation/Developer/Clients/Samples/AsyncPlayback.mdwn b/Software/PulseAudio/Documentation/Developer/Clients/Samples/AsyncPlayback.mdwn new file mode 100644 index 00000000..b40ff85e --- /dev/null +++ b/Software/PulseAudio/Documentation/Developer/Clients/Samples/AsyncPlayback.mdwn @@ -0,0 +1,162 @@ + +This code is not made by any pulseaudio developer. It may not be best practice, but it seems to work and could be used as a start for a playback application that uses the async API. + +This simple application plays a constant note and uses a low latency setup (20 ms) that should be suitable for games. It also increases the latency when underruns are detected, this makes it possible to get good sounding playback over networks as well. + +Save code as e.g. pa-beep.c and build using: +[[!format txt """ +gcc `pkg-config --cflags --libs libpulse` pa-beep.c -o pa-beep +"""]] + +[[!format txt """ +#include <stdio.h> +#include <string.h> +#include <pulse/pulseaudio.h> + +static int latency = 20000; // start latency in micro seconds +static int sampleoffs = 0; +static short sampledata[300000]; +static pa_buffer_attr bufattr; +static int underflows = 0; +static pa_sample_spec ss; + +// This callback gets called when our context changes state. We really only +// care about when it's ready or if it has failed +void pa_state_cb(pa_context *c, void *userdata) { + pa_context_state_t state; + int *pa_ready = userdata; + state = pa_context_get_state(c); + switch (state) { + // These are just here for reference + case PA_CONTEXT_UNCONNECTED: + case PA_CONTEXT_CONNECTING: + case PA_CONTEXT_AUTHORIZING: + case PA_CONTEXT_SETTING_NAME: + default: + break; + case PA_CONTEXT_FAILED: + case PA_CONTEXT_TERMINATED: + *pa_ready = 2; + break; + case PA_CONTEXT_READY: + *pa_ready = 1; + break; + } +} + +static void stream_request_cb(pa_stream *s, size_t length, void *userdata) { + pa_usec_t usec; + int neg; + pa_stream_get_latency(s,&usec,&neg); + printf(" latency %8d us\n",(int)usec); + if (sampleoffs*2 + length > sizeof(sampledata)) { + sampleoffs = 0; + } + if (length > sizeof(sampledata)) { + length = sizeof(sampledata); + } + pa_stream_write(s, &sampledata[sampleoffs], length, NULL, 0LL, PA_SEEK_RELATIVE); + sampleoffs += length/2; +} + +static void stream_underflow_cb(pa_stream *s, void *userdata) { + // We increase the latency by 50% if we get 6 underflows and latency is under 2s + // This is very useful for over the network playback that can't handle low latencies + printf("underflow\n"); + underflows++; + if (underflows >= 6 && latency < 2000000) { + latency = (latency*3)/2; + bufattr.maxlength = pa_usec_to_bytes(latency,&ss); + bufattr.tlength = pa_usec_to_bytes(latency,&ss); + pa_stream_set_buffer_attr(s, &bufattr, NULL, NULL); + underflows = 0; + printf("latency increased to %d\n", latency); + } +} + +int main(int argc, char *argv[]) { + pa_mainloop *pa_ml; + pa_mainloop_api *pa_mlapi; + pa_context *pa_ctx; + pa_stream *playstream; + int r; + int pa_ready = 0; + int retval = 0; + unsigned int a; + double amp; + + // Create some data to play + for (a=0; a<sizeof(sampledata)/2; a++) { + amp = cos(5000*(double)a/44100.0); + sampledata[a] = amp * 32000.0; + } + + // Create a mainloop API and connection to the default server + pa_ml = pa_mainloop_new(); + pa_mlapi = pa_mainloop_get_api(pa_ml); + pa_ctx = pa_context_new(pa_mlapi, "Simple PA test application"); + pa_context_connect(pa_ctx, NULL, 0, NULL); + + // This function defines a callback so the server will tell us it's state. + // Our callback will wait for the state to be ready. The callback will + // modify the variable to 1 so we know when we have a connection and it's + // ready. + // If there's an error, the callback will set pa_ready to 2 + pa_context_set_state_callback(pa_ctx, pa_state_cb, &pa_ready); + + // We can't do anything until PA is ready, so just iterate the mainloop + // and continue + while (pa_ready == 0) { + pa_mainloop_iterate(pa_ml, 1, NULL); + } + if (pa_ready == 2) { + retval = -1; + goto exit; + } + + ss.rate = 44100; + ss.channels = 1; + ss.format = PA_SAMPLE_S16LE; + playstream = pa_stream_new(pa_ctx, "Playback", &ss, NULL); + if (!playstream) { + printf("pa_stream_new failed\n"); + } + pa_stream_set_write_callback(playstream, stream_request_cb, NULL); + pa_stream_set_underflow_callback(playstream, stream_underflow_cb, NULL); + bufattr.fragsize = (uint32_t)-1; + bufattr.maxlength = pa_usec_to_bytes(latency,&ss); + bufattr.minreq = pa_usec_to_bytes(0,&ss); + bufattr.prebuf = (uint32_t)-1; + bufattr.tlength = pa_usec_to_bytes(latency,&ss); + r = pa_stream_connect_playback(playstream, NULL, &bufattr, + PA_STREAM_INTERPOLATE_TIMING + |PA_STREAM_ADJUST_LATENCY + |PA_STREAM_AUTO_TIMING_UPDATE, NULL, NULL); + if (r < 0) { + // Old pulse audio servers don't like the ADJUST_LATENCY flag, so retry without that + r = pa_stream_connect_playback(playstream, NULL, &bufattr, + PA_STREAM_INTERPOLATE_TIMING| + PA_STREAM_AUTO_TIMING_UPDATE, NULL, NULL); + } + if (r < 0) { + printf("pa_stream_connect_playback failed\n"); + retval = -1; + goto exit; + } + + // Iterate the main loop and go again. The second argument is whether + // or not the iteration should block until something is ready to be + // done. Set it to zero for non-blocking. + while (1) { + pa_mainloop_iterate(pa_ml, 1, NULL); + } + +exit: + // clean up and disconnect + pa_context_disconnect(pa_ctx); + pa_context_unref(pa_ctx); + pa_mainloop_free(pa_ml); + return retval; +} + +"""]]
\ No newline at end of file diff --git a/Software/PulseAudio/Documentation/Developer/Clients/WritingVolumeControlUIs.mdwn b/Software/PulseAudio/Documentation/Developer/Clients/WritingVolumeControlUIs.mdwn new file mode 100644 index 00000000..9bed2d5f --- /dev/null +++ b/Software/PulseAudio/Documentation/Developer/Clients/WritingVolumeControlUIs.mdwn @@ -0,0 +1,232 @@ + +[[!inline pages="Software/PulseAudio/TOC" quick="yes" raw="yes"]] [[↩ Back to Developer Documentation|Software/PulseAudio/Documentation/Developer]] + + +# Writing Volume Control UIs + +In the following text you'll find a few hints for folks who want to write mixer/volume control type applications for [[PulseAudio|PulseAudio]]. This text however does not go into a step-by-step detailed list which API functions you should use to enumerate, manipulate and get information about PA objects. For that please consult the doxygen documentation. Instead it is just a rough list of things you should keep in mind and be aware of. + +A lot of this applies only to PA >= 0.9.19. + +For a low-level overview on what is happening underneath [[read this wiki page!|Software/PulseAudio/Documentation/User/PulseAudioStoleMyVolumes]] + + +## Nomenclatura +Sink +: An output device + +Source +: An input device + +Sink input +: A stream that is connected to an output device, i.e. an input for a sink. + +Source output +: A stream that is connected to an input device, i.e. an output of a source. + +Client +: An active client of the PA server, something that can create none/one/many sink inputs/source outputs on any sink/source the PA server has. A sink input/source output can thus be "owned" by a specific client. Sink inputs/sources however can also be "unowned", i.e. not owned by any client. Generally we can consider a client to be a collection of sink inputs/source outputs. + +Card +: A collection of sinks/sources that belong to a single hardware device. Not all sinks/sources must be assigned to a card. Usually this combines one source (for recording) and one sink (for playback) into a single object. + + + +## Basics + +PA is very dynamic. Sinks/sources/sink inputs/source outputs/clients/cards can come and go. Hence make sure to subscribe to changes in the server and always keep your UI up-to-date. + + +## Volumes + +In [[PulseAudio|PulseAudio]] volumes are stored in the pa_volume_t (a single integer) and pa_cvolume (an array of one pa_volume_t integer per channel) data types. The values range from 0 (silence) to 65536 ("maximum" sensible volume). In some situations volumes > 65536 are possible as well (see below). + +Volumes stored in pa_volume_t/pa_cvolume should be considered opaque, i.e. arithmetic calculations like multiplication, addition, division should not be applied to them. Where possible pa_volume_t is chosen in a way that makes it suitable for showing in UI volume controls mapped linearly to pixels. + +Sinks, sources and sink inputs have a volume attached. Source outputs do *not* have a volume attached! In addition a 'mute' boolean is available for the same objects. For normal playback first the sink input volume is applied followed by the sink volume. For recording only the source volume matters. (Also note the part about "Flat volumes" below) + +Generally pa_volume_t/pa_cvolume_t cannot be converted to linear factors or decibel values — except for some cases. These cases are the following: + +* All volumes attached to sink inputs +* All sinks for which the PA_SINK_DECIBEL_VOLUME flag is set +* All sources for which the PA_SOURCE_DECIBEL_VOLUME flag is set +Conversion between linear factors, decibel values and pa_volume_t can be done via the following functions: + +* pa_sw_volume_from_dB() +* pa_sw_volume_to_dB() +* pa_sw_volume_from_linear() +* pa_sw_volume_to_linear() +The relation of the volume values in the different formats is like this: + +Silence ... + + * .. as pa_volume_t is PA_VOLUME_MUTED, i.e. 0 + * .. as linear volume is 0.0 + * .. as decibel value is something near -inf dB +"Maximum" applicable volume: + + * .. as pa_volume_t is PA_VOLUME_NORM, i.e. 65536 + * .. as linear volume is 1.0 + * .. as decibel volume is 0dB +Volumes between PA_VOLUME_MUTED and PA_VOLUME_NORM .. + + * .. as linear volume are > 0.0 and < 1.0 + * .. as decibel volume are negative dB values +Volumes > PA_VOLUME_NORM ... + + * .. as linear volume are > 1.0 + * .. as decibel volume are positive dB values +Please note that the latter only make sense in some situations. And always remember: the conversion between these formats is only valid in the few cases mentioned earlier — not in every case! + +The actual mapping of the gradient of pa_volume_t in relation to the linear volume is hidden inside of PA. It's chosen in a way that makes a volume of 32768 actually feel "half as loud" as a volume of 65536. (Or at least we try to map it like this.) The actual algorithm is not considered part of the ABI. I take the freedom to change it any time. You should not assume that the mapping between linear/decibel volumes on one hand and pa_volume_t volumes on the other will always stay the same in future versions. + +Generally all pa_sw_cvolume_xxx() and pa_sw_volume_xxx() functions (note the _sw_!) may only be called for volumes that may be converted to dB/linear volumes according to the rules listed above. Functions that do not include "_sw_" in the name may be called for all volumes. + +For sinks/sources, the maximum hardware volume (i.e. maximum amplification) is identified with PA_VOLUME_NORM. For sink inputs PA_VOLUME_NORM is identified with "no volume adjustment". + +If the underlying audio layer tells us what decibel values the mixer steps of the device relate to PA will extend the range of the mixer to the full dB range. That means even when the hardware mixer has only a limited dB range and only a few steps on the dB scale we will present the user a full and continuous dB scale. If the underlying audio layer does not tell us anything about the dB mapping of the mixer controls we are unable to do such a range extension and PA will only expose the same limited volume range and the same volume steps to the user the underlying mixer control exports. + + +## What to Present in the UI + +You probably should show sliders for each sink, source and sink input. + +It might be a good idea to list source outputs in some way as well even if they do not have a volume themselves, to know "who's listening" and to allow them to be killed (see below). + +Showing the list of clients in the UI is probably not a good idea, since it might confuse the user and brings not much additional value. + +It probably is a good idea to show the list of cards to allow switching of different card profiles with the UI (see below, not necessarily in the main mixer window however). + + +## Presenting Volumes + +Generally you should present sliders that ranges from PA_VOLUME_MUTED to PA_VOLUME_NORM, possibly extending it beyond that. For sink inputs that slider should probably show no steps (although in fact you have 65537 steps due to the range of 0..65536 that is PA_VOLUME_MUTED..PA_VOLUME_NORM). For sinks and sources the same applies if PA_SINK_DECIBEL/PA_SOURCE_DECIBEL is set. If it is not set the n_volume_steps field will tell you how many steps the hardware actually supports that are between PA_VOLUME_MUTED and PA_VOLUME_NORM. If the flags are set the n_volume_steps field will be set to 65537. + +Normal users probably prefer a a volume range in percent, i.e. 0%..100%. You should map that linearly to 0..65536 (i.e. PA_VOLUME_MUTED..PA_VOLUME_NORM). Advanced users probably prefer dB volumes. Hence it makes sense to present this volume format as well, similarly to how most better Hifi racks do it. It might be a good idea to hide them by default and only show them when you click somewhere or so. + +There is no point in presenting raw pa_volume_t or even linear volumes to the users. They are either incomprehensible or give a wrong "feeling" of volume. + +While generally it is a good idea to limit the volume slider to PA_VOLUME_MUTED..PA_VOLUME_NORM it makes sense to extend this further for sources (and possibly sinks). The reason for this is that some sound cards record audio in a very low bit depth and in the LSBs of the PCM samples and need digital amplification to produce a suitable signal for applications. To deal with these cases it makes sense to extend the volume range to PA_VOLUME_MUTED..PA_VOLUME_NORM*2 or something similar. For all volumes that are > PA_VOLUME_NORM (i.e. beyond the maximum volume setting of the hw) PA will do digital amplification. This works only for devices that have PA_SINK_DECIBEL_VOLUME/PA_SOURCE_DECIBEL_VOLUME set. For devices that lack this flag do *not* extend the volume slider like this, it will not have any effect. For playback devices it might be advisable to extend the scale beyond PA_VOLUME_NORM as well, because often enough digital amplification is useful on limited hardware. + +Internally PA accepts any volume setting for all sinks/source/sink inputs. However devices with PA_SINK_DECIBEL_VOLUME/PA_SOURCE_DECIBEL_VOLUME unset might limit the actually settings to a certain subset. And for UI purposes you should only consider the aformentioned ranges. + +Many underlying drivers provide us with the necessary information for the implementation of the PA_SINK_DECIBEL_VOLUME/PA_SOURCE_DECIBEL_VOLUME logic. However in many cases we do not have the information. Sometimes this situation is ameliorated with newer drivers. However some hardware (such as Bluetooth and some USB) does not include information about decibel mapping at all and hence will never be supported in the PA_SINK_DECIBEL_VOLUME/PA_SOURCE_DECIBEL_VOLUME logic. Due to that you need to make sure you handle both cases correctly: when the flag is set and when it is not. + + +## Base Volumes + +Sinks and sources carry information about a special volume setting, the "base volume". It is not clearly defined what this actually refers to and its meaning highly depending on the backend. Also in most case it will equal PA_VOLUME_NORM. + +Confused now why this might useful? So here's the intended use: it is to be mapped to the volume where the analog output is at some kind of normalized, pre-defined voltage level. I.e. in theory at this base volume all analog sound cards should produce the exact same voltage level (usually measured in dbV) that has a good 'default' volume. In reality however there are multiple established and not-so-established reference voltages around hence the actual meaning is dependant on the driver and hardware. However, generally if a "good default volume" is needed the base volume is the one to use, not PA_VOLUME_NORM! The reason for this is that — as we mentioned before — PA_VOLUME_NORM is mapped to maximum amplification on sound cards. For some cards which include a proper amplifier (such as my pair of USB speakers) PA_VOLUME_NORM is hence incredibly loud. Again, for many cards this value is actually unknown, and hence equals PA_VOLUME_NORM. For SPDIF card the base volume refers to the setting where the output PCM samples are unscaled. + +The UI should probably show explicit markers on the sliders for PA_VOLUME_MUTED, PA_VOLUME_NORM and base_volume. Especially on SPDIF cards base_volume is very important. Also, on many newer cards hardware volume control is implemented digitally, and hence to get the full bit depth out of your DAC base_volume matters a lot, too. + +Note that the base volume is purely a hint for the UI. It should not be used for any calculations. It's definition is very vague. + + +## Coloured volume sliders + +If you want to it might make sense to color certain ranges of the volume slider in green, yellow, red. The logic should probably look like this: + +If base_volume > PA_VOLUME_MUTED and < PA_VOLUME_NORM then use: + +* green for the range between PA_VOLUME_MUTED and base_volume +* yellow for the range between base_volume and PA_VOLUME_NORM +* red for the range beyond PA_VOLUME_NORM. +If base_volume is == PA_VOLUME_MUTED or >= PA_VOLUME NORM then use: + +* green for the range from PA_VOLUME_MUTED to PA_VOLUME_NORM +* no yellow +* red for the range beyond PA_VOLUME_NORM +Or this scheme shown graphically (drawn with my limited graphical skills): + +[[!img volume-slider.png] + +This applies only for sinks/sources where PA_SINK_DECIBEL_VOLUME/PA_SOURCE_DECIBEL_VOLUME is set. Only for those we can extend the hw volume range in software. For those where this flag is not set you need to end the volume range at PA_VOLUME_NORM, i.e. show no red section. + +In the graphic shown above having the slider end at 150% is quite arbitrarily chosen. It's up to you where you let it end. + +To the user this hopefully points out the following: + +* green: a suitable volume range, without any artifacts +* yellow: at the upper end of the hardware amplification possibilities, output level higher than ideal, possibly artifacts +* red: hardware amplification at its limit, software amplification, possibly artifacts +Of course, the technical background of all of this is hard to grasp and not obvious and probably no UI in the world could explain all this without being exceptionally bad. However, the green/yellow/red colouring should give the user a hint that he might drive his audio in ranges that are not ideal. + +Also see [[this GNOME bug report|https://bugzilla.gnome.org/show_bug.cgi?id=582516]]. + + +## Flat Volumes + +As mentioned above for playback the final volume you hear is comprised of the sink and the sink input volume. Having these two volumes in series is of course confusing to the user. That's where the "flat volume" features comes into play. It's based on Vista's flat volume mechanism. Basically when this is enabled, the volume of the sink is always the maximum volume of all inputs connected to the sink. That means when you adjust a sink input volume it will directly influence the sink volume if it is the loudest of the streams connected to it. In reverse, if you manipulate the sink volume this will scale all sink input volumes equally. + +Flat volumes are enabled on a per-sink basis. You can check for this with the PA_SINK_FLAT_VOLUME flag. Generally flat volumes are only available for sinks where PA_SINK_DECIBEL_VOLUME is also set. It might be a good idea to visually present the relation of the sink and the sink input volumes in some way when flat volumes are enabled. Vista does this by drawing a line that shows the connection of the loudest stream volume with the sink volume. + +This also means that for sinks where flat volumes are supported it makes sense to show the base volume (see above) on the sink input sliders as well! + + +## Multichannel Volumes + +As mentioned pa_cvolume stores multiple pa_volume_t, one for each channel of a stream/device. It might not be a good idea to actually show all those separate volumes, especially if you have more than two channels. (Some users might want this however.) In this case showing a single volume slider plus (optionally) a balance slider might be a good idea. + +For converting a pa_cvolume to a single pa_volume_t for presentation the best option is to use pa_cvolume_max() which will return the highest volume of all channels. For applying a single pa_volume_t on a pa_cvolume the best option is to use pa_cvolume_scale(). + +For calculating a balance value from a pa_cvolume use pa_cvolume_get_balance(). It will return a float between -1.0 (sound only on left speakers, right speakers silent) and +1.0 (sound only on right speakers, left speakers silent). 0.0 is returned when left and right speakers have the same volume. This function does the "right thing" for streams/devices with more than two channels. You may adjust the balance of pa_cvolume with pa_cvolume_set_balance(). Of course, not in all cases you actually have channels that are "left" or "right". You can check for this with pa_channel_map_can_balance(). For sinks/sources/streams where this call returns 0, you should not show a balance slider at all. + +Similar functionality is available for the fade value (i.e. balance between front and rear). + + +## Controlling Clients + +It is a good idea to allow the user to terminate certain sink inputs/source outputs form the mixer UI. Generally it might be a good idea to kill the entire client instead of just a sink input/source output. Hence the logic for killing should be: does this sink input/source output belong to a client? If yes, kill the client, if not, kill just the sink input/source output. + + +## Controlling Cards + +Cards can be used in different profiles. In different profiles a card may have a different number of sinks resp. sources in different configurations. For example, for cards that can do only simplex audio, there might be one profile for "Analog Stereo Input" (which will only create a single source when selected, no sink) and one for "Analog Stereo Output" (a single sink when selected, no source). For cards that do duplex there might be one additional profile "Analog Stereo Input + Analog Stereo Output" (one sink, one source). While stereo simplex cards might be a bit out of fashion these days many surround cards are still effectively simplex if you use them in surround mode. Profiles are also used to switch between analog and digital (i.e. SPDIF) output, and mono, stereo and surround mode. Profiles may be switched during runtime. If possible active streams are kept around even when the a stereo sink might be replaced by a surround sink or similar cases. + +It is probably a good idea to present the user with a way to switch profiles of all present cards. If this should happen inside the volume control application, or in a different tool is left to you. + + +## The Default Devices + +When a new stream is created and the client does not specify a specific sink/source to connect it to and no device for that stream has been saved before PA will connect it to the 'default' sink resp. source. Due to the fact that PA tries to save/restore volumes for each stream the default sink/source however acts more like a fallback sink/source, which is only relevant for streams where no data has been stored before. Hence it should probably be exposed as "Fallback Device" in the UI, not as "Default Device". + + +## Saved Volumes/Devices + +PA's module-stream-restore will automatically save/restore volumes/devices for streams. In the database of saved volumes/devices streams are identified by a string that is generated from the stream properties set by the application. The module will add the property "module-stream-restore.id" to each stream that contains this key. Generally more generic properties (such as "media.role") are preferred over more specific ones. + +The database may be read and manipulated from clients. Use the APIs in ext-stream-restore.h for that. Why would you want to do this? Some types of sounds are very short in nature and hence might appear only for a very short time as a proper stream. That makes it difficult to control them in the volume control UI — before you can grab the slider the slider might already be gone again. Those short sounds are usually event sounds. It hence might make sense to add an explicit slider for event sounds that stays available all the time. To implement this simply manipulate the stream database for the "sink-input-by-media-role:event" key (assuming that your event sounds are properly tagged, like libcanberra properly does). You can even make this instant-apply. In future, if more streams are tagged properly you could even show an UI that always controls volume based on the role, and ignores dynamically created streams. i.e. one slider for "Telephony", another one for "Games" and so on. + +This functionality can be used in other interesting ways as well. For example using the mentioned "module-stream-restore.id" property you can continue to show each slider for some time after a stream ended in which case it would not manipulate the stream volume itself anymore but simply the database entry. + +And then, since not only the volume is stored in this database but also the device last used for a stream, you may use this to write an UI that allows you to edit preferred devices for certain streams, for example one dropdown box for selecting a device for all music playback, another one for all telephony, and so on. Again, this can also be made instant-apply. + + +## Monitoring PCM + +Sinks, Sources, Sink Inputs, Source Outputs may all be monitored for the PCM data that passes through them. This is especially useful for showing a volume meter next to each stream to give the user feedback which streams/devices currently receive audio. + +To monitor a source, simple create a PA_STREAM_RECORD stream on it. To monitor a source output simply do the same for the source the source output is connected to. To monitor a sink do the same on the monitor source that is attached t the sink. You'll find the monitor source in pa_sink_info::monitor_source. To monitor a specific sink input connect to the monitor source of the sink the sink input is connected to and then use pa_stream_set_monitor_stream() to select the sink input you are interested in. + +When you want to present a volume meter then it is highly recommended to use the PA_STREAM_PEAK_DETECT feature of pa_stream. This cuts down the traffic and processing time for each monitored stream immensely. + +Please note that monitoring PCM like this will get you PCM data that is untouched by the hardware volume. That means that manipulating a sink's volume might not actually have any affect on the PCM stream your monitoring, or — when PA extends the volume range — a non-obvious effect. + + +## Information for the User + +When you present sinks/sources/sink inputs/source outputs it might be a good idea to show some information about them to make it easy for the user to map them to physical devices or running applications. To ease that this objects carry a set of "properties". Properties are usually UTF8 strings (with the exception of very few that carry raw data). All properties are optional, you should not rely on them being set. + +A list of properties that may be useful to show in an UI is included in pulse/proplist.h. + +Of particular interest are these non-obvious properties: + +* PA_PROP_DEVICE_PROFILE_DESCRIPTION: Shows the "profile" asink/source is currently in. Informs the user if something is an analog or digital (SPDIF) output, which is very valuable information in many cases. +* PA_PROP_WINDOW_X11_xxx: Can be used to attach a stream to a specific X11 window. It might be a good idea to visually present the relation of streams in the mixer tool and windows on the screen in some way. +* PA_PROP_MEDIA_ICON(_NAME), PA_PROP_APPLICATION_ICON(_NAME): an icon to show next to a stream. +* PA_PROP_APPLICATION_PROCESS_MACHINE_ID: This contains the D-Bus machine UUID (as available in /var/lib/dbus/machine-id) of the client that registered the stream. Never forget that PA streams may not necessarily come from a local process! Hence make sure to use this property to identify hosts (and NOT the hostname since it might change at any time). +Please note that at this point in time only the fewest applications set more than the most basic properties. However this is a chicken-and-egg problem: if no one uses the properties applications won't set them. So please, make use of these properties in your mixer application. + +That's all for now. As you might see writing a "perfect" mixer is not a trivial job. Sorry for that. diff --git a/Software/PulseAudio/Documentation/Developer/Clients/WritingVolumeControlUIs/volume-slider.png b/Software/PulseAudio/Documentation/Developer/Clients/WritingVolumeControlUIs/volume-slider.png Binary files differnew file mode 100644 index 00000000..d99c036a --- /dev/null +++ b/Software/PulseAudio/Documentation/Developer/Clients/WritingVolumeControlUIs/volume-slider.png diff --git a/Software/PulseAudio/Documentation/Developer/CodingStyle.mdwn b/Software/PulseAudio/Documentation/Developer/CodingStyle.mdwn new file mode 100644 index 00000000..c3e782d8 --- /dev/null +++ b/Software/PulseAudio/Documentation/Developer/CodingStyle.mdwn @@ -0,0 +1,157 @@ + +[[!inline pages="Software/PulseAudio/TOC" quick="yes" raw="yes"]] [[!inline pages="DevelopingModulesTOC" quick="yes" raw="yes"]] + + +# Coding Style + +Please follow the following rough rules when submitting code for inclusion in PA or committing code into Git. Although this list might appear massive I am still quite liberal in accepting patches that do not follow these rules. OTOH I am not your reindenting monkey, so please follow them, especially if your submissions are non-trivial! + + 1. No tabs please! Please indent exclusively with spaces. + 1. Indentation is 4 characters. + 1. Please keep the opening bracket of a block on the same line as the expression opening it. i.e. This is correct: + * [[!format txt """ +void good_function(void) { + + if (a) { + printf("Hello World!\n"); + a = 0; + } +} +"""]]And this is wrong: [[!format txt """ +void bad_function(void) +{ + if (a) + { + printf("Hello World!\n"); + a = 0; + } +} +"""]] + 1. Avoid unnecessary curly braces. Good code: + * [[!format txt """ +if (!braces_needed) + printf("This is compact and neat.\n"); +"""]]Bad code: [[!format txt """ +if (!braces_needed) { + printf("This is superfluous and noisy.\n"); +} +"""]] + 1. Don't put the return type of a function on a separate line. This is good: + * [[!format txt """ +int good_function(void) { +} +"""]]and this is bad: [[!format txt """ +int +bad_function(void) { +} +"""]] + 1. On function calls and definitions, don't put an extra space between the function name and the opening parenthesis of the argument list. This good: + * [[!format txt """ +double sin(double x); +"""]]This bad: [[!format txt """ +double sin (double x); +"""]] + 1. Exported function names should be prefixed with `pa_`. Static definitions should not be prefixed. Exported structs should be typedef'ed so they can be used without typing "struct" each time. Structs that are used only inside a single source file should not be typedef'ed that way. + 1. Keep private functions private! Make them static! + 1. Data types that are usually passed as call-by-value arguments should be suffixed with `_t` with a typedef. I.e. all enums should be suffixed like this: + * [[!format txt """ +typedef enum pa_resample_method { + /* ... */ +} pa_resample_method_t; +"""]] + 1. No C++ comments please! i.e. this is good: + * [[!format txt """ +/* This is a good comment */ +"""]]and this is bad: [[!format txt """ +// This is a bad comment +"""]]Yes, the newest C iterations allow those comments. But they are ugly. + 1. Comments are good, use them wherever it makes sense. Excessive comments are bad. i.e. comment complicated code, don't comment trivial code. For hackers it's usually easier to understand well written code than prose. Use doxygen only for exported APIs, not for internal code. + 1. Code is about aesthetics. So please, format you code cleanly. + 1. Please do _not_ wrap your lines at 80 characters. Given that most screens are now considerably wider than they used to be, please make use of it. Wrap them at 128 characters. An exception: comments, especially multi-line comments, should be wrapped at 80 characters. + 1. Please check parameters on each function call. Use `pa_assert()` when checking parameters which are -- when wrong -- most likely programming errors in PA. For bad parameters that are not necessarily programming errors, or which might be programming errors outside of PA, return with an error code. Please add a separate `pa_assert()` for each argument. Do not use a single check for all parameters using `&&`. This would make debugging more difficult. Good code: + * [[!format txt """ +void good_code(int a, int b) { + pa_assert(a > 47); + pa_assert(b != 0); + + /* ... */ +} +"""]]Bad code: [[!format txt """ +void bad_code(int a, int b) { + pa_assert(a > 47 && b != 0); + +} +"""]] + 1. Errors are returned from functions as negative values. Success is returned as 0 or positive value. + 1. Check for error codes on every system call, and every external library call. If you you are sure that calls like that cannot return an error, make that clear by wrapping it in `pa_assert_se()`. i.e.: + * [[!format txt """ +pa_assert_se(close(fd) == 0); +"""]]Please note that `pa_assert_se()` is identical to `pa_assert()`, except that it is not optimized away if NDEBUG is defined. (`se` stands for _side effect_) + 1. Every .c file should have a matching .h file (exceptions allowed) + 1. In .c files we include .h files whose definitions we make use of with `#include <>`. Header files which we implement are to be included with `#include ""`. + 1. If `#include <>` is used the full path to the file relative to `src/` should be used. + 1. Please submit code only under LGPL2+, BSD/MIT or GPL2+, but don't make GPL code a hard dependency. Since PA is pluggable this would make it it impossible to load less-free-than-GPL code into the PA daemon. + 1. Booleans: Use int as the boolean type in public APIs. Internally, use bool from stdbool.h. +Yes, not all code that is part of PA right now follows these rules closely. This is mostly due to the fact that the formalization of these rules is newer then most of the code itself. + + +## Localization + +We have some rules for deciding whether a log message should be localized or not (again, the existing code base is mostly older than the rules, so there are a lot of places where the rules are not followed). From a [[message|http://thread.gmane.org/gmane.comp.audio.pulseaudio.general/12554]] on the mailing list: + + +[[!format txt """ +A few of us had an IRC conversation about whether or not to localise +PulseAudio's log messages. +The suggestion/outcome is to add localisation only if all of the +following points are fulfilled: + + 1) The message is of type "warning" or "error". (Debug and info levels +are seldom exposed to end users.) + + 2) The translator is likely to understand the sentence. (Otherwise +we'll have a useless translation anyway.) + + 3) It's at least remotely likely that someone will ever encounter it. +(Otherwise we're just wasting translator's time.) + + 4) The user is likely to be able to help himself, or at least be +informed, after having read the message. + +Example: + +pa_log_warn(_("OK, so you are running PA in system mode. Please note +that you most likely shouldn't be doing that.\n" (etc) + +The above can remain localised. + +pa_log_warn("Unable to set stop threshold: %s\n", pa_alsa_strerror(err)); + +The above should NOT be localised (fails both 2, 3, and 4.) + +pa_log_info(_("Fresh high-resolution timers available! Bon appetit!")); + +The above should be changed to NOT be localised. (fails at least 1. +Maybe also 2 and 4.) +"""]] + +# Indentation in Emacs + +If you use Emacs, consider using this Elisp function for proper indentation: + + +[[!format txt """ +(defun my-c-mode() + "Lennart Poettering's C indentation" + (message "Setting Lennart Poettering's C indentation...") + (c-set-offset 'substatement-open 0) + (c-set-offset 'statement-case-open 0) + (c-set-offset 'case-label '+) + (c-set-offset 'arglist-intro '++) + (c-set-offset 'arglist-close 0) + (define-key c-mode-base-map "\C-m" 'c-context-line-break) + (setq tab-width 8) + (setq c-basic-offset 4) + (c-toggle-hungry-state 1) + (setq indent-tabs-mode nil)) +"""]]
\ No newline at end of file diff --git a/Software/PulseAudio/Documentation/Developer/ConfigurationSystem.mdwn b/Software/PulseAudio/Documentation/Developer/ConfigurationSystem.mdwn new file mode 100644 index 00000000..5264d098 --- /dev/null +++ b/Software/PulseAudio/Documentation/Developer/ConfigurationSystem.mdwn @@ -0,0 +1,171 @@ + + +# Configuration System + +This page can be used as a reference while [[discussing the configuration system|http://thread.gmane.org/gmane.comp.audio.pulseaudio.general/13098]]. This page should be updated as the discussion progresses. + + +## Introduction + +One of the [[Google Summer of Code project ideas for 2012|Software/PulseAudio/GSoC2012]] was a "configuration system". The configuration system was not among the selected projects, but the system was seen as a priority, so the plan now is to design and implement the important bits (the client API and the server-side infrastructure) ourselves within May 2012 or so (the reason for the tight schedule is that we'd like the GSoC students to benefit from this new system). Porting the existing configuration to the new system is not a matter of urgency. All the existing stuff has to be kept in mind while doing the design, though, so that the porting work is possible to do when that time comes. + +The configuration system should make it easy to implement runtime-modifiable persistent configuration options in the core and modules. Currently that involves writing protocol extensions (for multiple protocols, if you aim for completeness) and managing the data storage yourself. The goal is to reduce that work, and also to make life easier for applications. + +There are some notes from previous discussion at [[http://piratepad.net/BLGxYG2lf3|http://piratepad.net/BLGxYG2lf3]]. + + +## Goals + +* The client API should be easy to use. +* The set of supported configuration options should be easy to extend. + * No protocol extensions. + * Make it as easy as possible to add a new option. +* Support also other things than statically named global options. + * For example, options for ports require dynamic keys to identify the port. + * We want (or do we?) to support also persistent data that is less configuration-like, like the stream-restore database or the equalizer data. +* Support change notifications both at client side and at server side. +* Support reading and modifying client.conf. (?) + +## Design + +The configuration system stores "options". Options have a value and a (multi-part) identifier ("option id"). The option id has three parts: "object type", "object id" and "option name". For example, the maximum volume of a port could be stored in an option with the following id parts: "core.Port", "foocard:barport", "max-volume". The object that the object type and id describe is one of the objects in Pulseaudio: it could be a card, sink, source, port or stream-restore entry etc. The object id is whatever property identifies the object in question: in case of ports it would be the card name + port name (the card name is needed, because port names are not globally unique), and in case of stream-restore entries it would be the entry key. The object type has a namespace part, for example "core" in "core.Port" or "stream-restore" in "stream-restore.Entry". This can be used to divide the option storage into multiple files, one per namespace (one namespace for core and one namespace for each module would be the suggested way to group the options). + +The client API doesn't have a concept of namespaces. The applications only need to know that if they want to access port options, they have use "core.Port" as the object_type string. + +It may be sometimes useful to refer to an option by using just one string instead of three. That can be done by just concatenating the three identifiers. The suggested separator is slash. Example: "core.Port/foocard:barport/max-volume". + +The configuration system knows which object types support which options. This is achieved by each "object type owner" (i.e. the code that implements the objects of that type) registering the object type to the configuration system. The registration includes the information about which options the object type supports, i.e. which option names are valid. The configuration system doesn't have any hardcoded knowledge about which object types exist. + +The set of options that an object type supports can not be changed at runtime (except by unloading the object type owner module and then loading another module that registers the same object type with different options, but that should never happen). There may be situations where a module would like to extend a core object type. For example, module-alsa-card might want to have a "tsched" option for core.Card. The way to handle this is to make module-alsa-card register its own object type for cards, e.g. "alsa.Card", and specify in the documentation that the "alsa.Card" type is a subtype of "core.Card". Being a subtype means it's guaranteed that any "alsa.Card" object also has a corresponding "core.Card" object. The association between the two objects is made by using the same object id for both. + +From the configuration system's point of view, all option values are strings. Adding type information would add a lot of complexity and not have very big benefits (is it so?). The options will of course have an implicit type to be useful. The actual users of the options (applications and object type owners in the server) have to validate the values themselves. This means that we should provide parsing functions for clients, at least for all complex types, but preferably also for simple stuff like integers. At server side, values are validated when they are read from the disk and when they are set by clients or by some code in the server other than the object type owner. + +Since validation is done by the object type owner code, and since modules can implement object types, some of the options can be only validated when a specific module is loaded. The way to handle the case, where an application sets an option for a module that is not loaded, is to refuse to set the option. If the module required isn't loaded, from the configuration system's point of view the option doesn't exist. + + +## Client API + +This is how the client API will look like: + + +[[!format txt """ +typedef void (*pa_server_configuration_value_change_cb_t)( + pa_context *c, + const char *object_type, + const char *object_id, + const char *option_name, + const char *value, + int eol, + void *userdata); + +typedef void (*pa_server_configuration_object_type_event_cb_t)( + pa_context *c, + const char *object_type, + int added, /* 1 for added, 0 for removed */ + int eol, + void *userdata); + +pa_operation *pa_server_configuration_set( + pa_context *c, + const char *object_type, + const char *object_id, + const char *option_name, + const char *value, + pa_context_success_cb_t cb, + void *userdata); + +/* object_type, object_id and option_name can be NULL for wildcard selection. + * If object_type is NULL, then all other identifiers have to be NULL also. In + * case of wildcards, the callback may get called multiple times. The last call + * has the object_type, object_id, option_name and value parameters of + * pa_server_configuration_cb_t set to NULL and eol set to 1. */ +pa_operation *pa_server_configuration_get( + pa_context *c, + const char *object_type, + const char *object_id, + const char *option_name, + pa_server_configuration_cb_t cb, + void *userdata); + +/* The wildcard rules described with pa_server_configuration_get apply with + * the value change items too. */ +typedef struct pa_server_configuration_value_change_item { + char *object_type; + char *object_id; + char *option_name; +} pa_server_configuration_value_change_item; + +/* The items parameter is an array with n_items elements. If there are multiple + * value change items given, then the value change callback is called when any + * of the items match the event. If you want to end the subscription, or you + * want to get updates only about added and removed object types, you can set + * items to NULL and n_items to 0. + * + * The object_types parameter is an array with n_object_types elements. If an + * object type is added or removed in the server, and it's one of the types + * you have listed in the object_types array here, the server will send + * a notification. For getting notifications for all object types, set + * object_types to a pointer to a NULL pointer and set n_object_types to 1. If + * you don't want any object type event notifications, set object_types to NULL + * and n_object_types to 0. + * + * If called multiple times, the value change items and object types of the + * last call will replace all the previous items and object types. */ +pa_operation *pa_server_configuration_subscribe( + pa_context *c, + const pa_server_configuration_value_change_item *items, + unsigned n_items, + const char *const *object_types, + unsigned n_object_types, + pa_context_success_cb_t cb, + void *userdata); + +/* When there are option value changes that match the subscription, the + * callback that is set here will be called multiple times. The last call has + * the object_type, object_id, option_name and value parameters of + * pa_server_configuration_value_change_cb_t set to NULL and eol set to 1. */ +void pa_server_configuration_set_value_change_callback( + pa_context *c, + pa_server_configuration_value_change_cb_t cb, + void *userdata); + +/* When there are object type add/remove events that match the subscription, + * the callback that is set here will be called multiple times. The last call + * has the object_type parameter of + * pa_server_configuration_object_type_event_cb_t set to NULL and eol set to + * 1. */ +void pa_server_configuration_set_object_type_event_callback( + pa_context *c, + pa_server_configuration_object_type_event_cb_t cb, + void *userdata); +"""]] +There has been some discussion about supporting also reading and modifying client.conf. client.conf is not centrally managed, it stores simple key-value pairs with static keys, it doesn't support change notifications and working with it probably doesn't require an asynchronous API. Therefore, the API is quite different, and maybe it doesn't need to be a part of this configuration system effort. The main point is that we **might** want such API now or in the future, so we should think how the configuration system API can co-exist with the client.conf API. That means basically that we probably don't want to use "pa_configuration_" as the server configuration prefix, because it's too generic. + + +### Parsing functions + +TODO + + +## Storage format + +TODO + + * I like ini files as described here: [[http://article.gmane.org/gmane.comp.audio.pulseaudio.general/12845|http://article.gmane.org/gmane.comp.audio.pulseaudio.general/12845]] --Tanu + +## Open issues + +The namespace concept might need some refinement. The idea of splitting the storage into one file per module sounds nice, but it might not make sense to dedicate each object type to one module. Modules may want to add options to their own object types and to core object types, and possibly also to other modules' types. Let's say there's an object type "Card" in namespace "core", i.e. "core.Card". The alsa modules might want to add an option to core.Cards for enabling and disabling timer-based scheduling. Maybe the options should have namespacing too, i.e. the new option would be "core.Card/foocard/alsa.tsched"? Would every option name have a namespace part? That would be very ugly. How would this example be handled in storage? Is splitting the storage into many files a bad idea anyway? + + * This is solved by not allowing modules to add options to existing object types. If everybody is happy, this issue can be deleted from here. --Tanu +Is there need for adding an API for clients for querying whether a specific option is supported? Such API could be added also later, if we are not certain yet. + +One limitation with this proposal is that the client API supports only modifying existing objects. For example, adding a new entry to stream-restore is not possible in a nice way. You could set an option of a non-existent object, but that would leave the other fields of the entry uninitialized. Maybe that's tolerable, but if we want to support object creation, it should probably be done in a better way. And object deletion is not possible at all with the current API. + + * I'm a bit against supporting object creation/deletion through the configuration API. Protocol extensions are still needed for that then. Maybe exposing the stream-restore database to clients through the configuration API isn't so good idea after all. The storage part of the system could still be useful also for stream-restore. --Tanu +Should we have a "reset to default" API? What about an "ask what the default is" API? + + * My opinion: yes for "reset to default", no for "ask what the default is" until a good use case is found. --Tanu +Should we have an API for querying the currently supported object types? + + * My opinion: yes. --Tanu
\ No newline at end of file diff --git a/Software/PulseAudio/Documentation/Developer/CoreAPI.mdwn b/Software/PulseAudio/Documentation/Developer/CoreAPI.mdwn new file mode 100644 index 00000000..991d2cf1 --- /dev/null +++ b/Software/PulseAudio/Documentation/Developer/CoreAPI.mdwn @@ -0,0 +1,189 @@ + +[[!inline pages="Software/PulseAudio/TOC" quick="yes" raw="yes"]] [[!inline pages="DevelopingModulesTOC" quick="yes" raw="yes"]] + + +# Interface of `pa_core` + +From [[pulsecore/core.h|http://cgit.freedesktop.org/pulseaudio/pulseaudio/tree/src/pulsecore/core.h]]: "The core structure of PulseAudio. Every PulseAudio daemon contains exactly one of these. It is used for storing kind of global variables for the daemon." + +`pa_core` doesn't have any interesting functions associated with it, it is just a central collection of all the components and globally relevant variables. You're not supposed to modify the fields, at least not directly. + +Actually, in addition to being a variable collection, there are two interesting enumerations too. + +The most important field is perhaps `mainloop`. That can be used for communicating with the daemon mainloop, see [[Daemon Mainloop|Software/PulseAudio/Documentation/Developer/MainLoop]]. + + +## `struct pa_core` +`parent` +: + * `pa_core` is a subclass of `pa_msgobject`, which implies that the first field of `pa_core` is of type `pa_msgobject`. It means also that `pa_core` can receive messages, see "The unnamed enumeration" later on this page. At some point in the future I may write a page about the [[object system|Software/PulseAudio/Documentation/Developer/ObjectSystem]] used inside PulseAudio. I think documenting the [[pa_msgobject API|Software/PulseAudio/Documentation/Developer/MsgobjectAPI]] would be useful too. + +`cookie` +: + * A random value which may be used to identify this instance of PulseAudio. Not cryptographically secure in any way. + +`mainloop` +: + * Pointer to the mainloop API. + +`clients` +: + * Currently connected clients. If you're not familiar with the `pa_idxset` type, see the [[header|http://cgit.freedesktop.org/pulseaudio/pulseaudio/tree/src/pulsecore/idxset.h]]. + +`sinks`, `sources` +: + * Currently existing sinks and sources. + +`sink_inputs`, `source_outputs` +: + * Currently existing sink inputs and source outputs. + +`modules` +: + * Loaded modules. + +`scache` +: + * The sample cache. The contained items are of type `pa_scache_entry`. + +`namereg` +: + * All sink, source and sample names are stored in this hashmap. The hashmap ensures the uniqueness of the names. This is accessed through the [[namereg interface|http://cgit.freedesktop.org/pulseaudio/pulseaudio/tree/src/pulsecore/namereg.h]]. + +`shared` +: + * Modules can share variables through this "shared hashmap". Instead of using the hashmap functions directly, this variable should be accessed through a [[separate interface|http://cgit.freedesktop.org/pulseaudio/pulseaudio/tree/src/pulsecore/shared.h]]. + +`default_source_name`, `default_sink_name` +: + * Pretty self-explanatory, but do not access these directly, but through `pa_namereg_set_default`, `pa_namereg_get_default_sink_name` and `pa_namereg_get_default_source_name` that are defined in [[pulsecore/namereg.h|http://cgit.freedesktop.org/pulseaudio/pulseaudio/tree/src/pulsecore/namereg.h]]. + +`default_sample_spec` +: + * When in need of a default format for an audio stream, you'll find it here. + +`default_n_fragments`, `default_fragment_size_msec` +: + * The default buffering settings that should be used by sinks and sources when opening a hardware device. + +`module_auto_unload_event` +: + * The module system uses this to poll for modules that should be unloaded. Not for you. + +`module_defer_unload_event` +: + * The module system uses this to make mainloop unload modules. Not for you. + +`subscription_defer_event` +: + * The subscription system uses this to make mainloop inform the subscribers about an event. Not for you. (What subscription system? See [[Catching Events|Software/PulseAudio/Documentation/Developer/CatchingEvents]].) + +`subscriptions` +: + * Head of the list of existing subscriptions. Not for you. + +`subscription_event_queue` +: + * Head of the list of unprocessed events. Not for you. + +`subsrciption_event_last` +: + * Last item of the list of unprocessed events. Not for you. + +`mempool` +: + * The memory pool. You may need this as an argument to some functions. + +`exit_idle_time` +: + * The time in seconds between the moment the last client has left and the moment pulseaudio exits, if automatic exiting is used. + +`module_idle_time` +: + * The time in seconds between the moment the last client has stopped using a module and the moment the module gets unloaded, if the module is set to be automatically unloaded. + +`scache_idle_time` +: + * The time in seconds between the moment a sample has been fired last time and the moment the that the sample gets unloaded, if the sample is loaded as "lazy". + +`quit_event` +: + * If the daemon is told to exit after a period of idleness, it uses this to track the idle time. Not for you. + +`scache_auto_unload_event` +: + * The sample cache uses this to track the time that the lazy samples have been unused. Not for you. + +`disallow_module_loading` +: + * Controls whether modules can be loaded (and unloaded) or not. + +`running_as_daemon` +: + * If pulseaudio is daemonized, this is one, otherwise zero. + +`resample_method` +: + * The resample method that the user has chosen. + +`is_system_instance` +: + * This indicates whether pulseaudio is running as a per-user or a system-wide daemon. + +`high_priority` +: + * One, if pulseaudio has made itself a high-priority process (i.e. is running with the SCHED_FIFO scheduling class), zero otherwise. + +`hooks` +: + * The hooks that can be used to catch events in core, see [[Catching Events|Software/PulseAudio/Documentation/Developer/CatchingEvents]]. + + + +## `enum pa_core_hook` + +The enumeration contains all the events that can be catched synchronously, see [[Catching Events|Software/PulseAudio/Documentation/Developer/CatchingEvents]]. + + +## The unnamed enumeration + +There's this enumeration, that has only two elements: `PA_CORE_MESSAGE_UNLOAD_MODULE` and `PA_CORE_MESSAGE_MAX`. It contains all the messages that can be sent from outside the daemon mainloop thread to the core, and currently there is only one such message. + +`PA_CORE_MESSAGE_UNLOAD_MODULE` causes a module (give the pointer as userdata to pa_asyncmsgq_post) to get unloaded. The difference between using this message and calling `pa_module_unload_request()` is that the latter may only be called using the daemon mainloop, the message can be sent from other threads. + +For information on how to use the inter-thread message passing system, see [[Messaging System|Software/PulseAudio/Documentation/Developer/MessagingSystem]], or while waiting for that to materialize, try [[Software/PulseAudio/Documentation/Developer/Threading|Software/PulseAudio/Documentation/Developer/Threading]]. + + +## Functions and macros + +As mentioned earlier, the functions `pa_core` has associated with it, are not interesting for module writers. I'll list them here anyway for completeness's sake. +`pa_core_new` +: + * Creates a new core that will use the given mainloop. The parameter `shared` is a boolean indicating whether the created mempool should be shared or not. + +`pa_core_check_quit` +: + * Updates the quit_event field, called by the client system when clients come and leave. + + +`PA_DECLARE_CLASS(pa_core)` in the header causes the following functions to become available (they are explained in the [[Object System|Software/PulseAudio/Documentation/Developer/ObjectSystem]] page): +`pa_core_isinstance` +: + +`pa_core_cast` +: + +`pa_core_ref` +: + +`pa_core_unref` +: + +`pa_core_refcnt` +: + +`pa_core_assert_ref` +: + + +And then there is the `PA_CORE` macro, that is just an alias for `pa_core_cast`. diff --git a/Software/PulseAudio/Documentation/Developer/GitBranches.mdwn b/Software/PulseAudio/Documentation/Developer/GitBranches.mdwn new file mode 100644 index 00000000..59f4bdd1 --- /dev/null +++ b/Software/PulseAudio/Documentation/Developer/GitBranches.mdwn @@ -0,0 +1,5 @@ + + +# Git Branches + +The development happens in the **master** branch. Major releases (1.0, 2.0, 3.0 etc.) are made from the master branch too, so while preparing for a release, the master branch is frozen (development may continue in unofficial repositories during the freezes). Sometimes, if serious bugs have slipped into major releases, we may make bugfix releases too. These are made from separate branches, for example stable-1.x, stable-2.x, stable-3.x... diff --git a/Software/PulseAudio/Documentation/Developer/IO.mdwn b/Software/PulseAudio/Documentation/Developer/IO.mdwn new file mode 100644 index 00000000..dfa115d5 --- /dev/null +++ b/Software/PulseAudio/Documentation/Developer/IO.mdwn @@ -0,0 +1,173 @@ + +#pulseaudio irc discussion, between João Paulo Rechi Vita and Lennart Poettering, August 2008 + +J: [...] I still didn't get how exactly a sink works, could you give an overview of the process ? I mean, when the sink_process_message is called, when a write is called, or point some place where I can learn by my self + +L: "There is some documentation available in the wiki it's not completely up to date though the basic idea is that each sink or source is driven by its own thread that sleeps on the audio device's fd and then pushes or pulls data to/from the clients. Now the thing about this thread is designed to be lock-free. + +The way how it communicates with the main event loop of PA is not via mutexes/semaphores and stuff but via messages pushed into lock-free queues the RT threads managed by the audio devices never block on those queues however the main event loop on the otherside of those queues may block there are two queues for each thread one from the single main event loop to the thread and one back in some cases more than a single sink or source is driven from a single RT thread the most prominent example here is the OSS driver + +Because we have only a single fd for both recording and playback and the devices are syncrhonous they are driven from the same thread. + +J: those queues are the pa_thread_mq, right? + +L: Yes, pa_thread_mq stores a pair of queues: + +* pa_thread_mq->inq is from the main event loop to the specific thread +* and pa_thread_mq->outq is from the thread back to the event loop +* pa_thread_mq_xxx() can be used to set up the pair +and hook them up with the main event loop + +J: And pa_process_msg is the function that process the messages coming through these queues? + +L: Yes, process_msg() is generally used to dispatch messages, on both sides of queues actually. + +Every object that inherits from pa_msgobject can receive these messages (~signals), you send those msgs with pa_asncmsgq_send(), or _post(). + +* _send() is synchronous (i.e. blocks until the function is reeived + * and handled on the receiving side +* _post() is asynchronous (i.e. it justs enqueues and returns) +* _send() should thus only be used for communication from the main +event loop to the thread but not the other way round + +If no response is required for a messages, then _send() is highly recommended + +J: and how do I know which kind of messages can come through the queue? + +L: All kinds of messages can come through the queues. For example pa_sink, pa_source, pa_sink_input, pa_source_output can receive messages, and defined a few default ones. If you implement a pa_sink/.... you can add your own messages. If you check pulsecore/sink.h, you can see the messages understood by pa_sink in the type pa_sink_message_t there is a default implementation for pa_sink_process_msg() for each class usually if you subclass something you would handle what you want to handle and then call that generic handler to fully understand what is going on. In all this code you always be aware from which context a function is being called (i.e. if it is called from the main event loop or if it is called from one of the IO/RT event loops, or if it can be called from both for more recent code). I added small comments to many functions which explain the context because i got lost myself ;-) + +J: I saw some of this comments, i think on sink.h + +L: For some functionality of pa_sink/.... you can either implement it in the main thread, or in the RT thread: for those you can either overwrite process_msg, or you can fill in some other virtual function. + +One example for this is the volcontrol stuff i.e. for a sink you can either implement set_volume/get_volume as function pointers in the pa_sink structure which would then be called form the main event loop or if you leave them as NULL you will get a message PA_SINK_MESSAGE_GET_VOLUME/PA_SINK_MESSAGE_SET_VOLUME in the RT thread instead. + +This is useful because for some audio devices volume control is done in-line and for others vol control is out-of-line. + +Since vol control is not time critical in any way it is usually a good idea to leav it out of the RT thread but sometimes the underlying API doesn't really allow that. Of course, as little as necessary should be run in the IO thread (oh, sometimes i call it "RT thread" and sometimes i called it "IO thread". those terms refer to the same...) + +J: ok, i got it + +L: The IO threads are supposed to be real-time threads if real-time scheduling is available. That's why i use those terms interchangingly. + +Hmm, what else is there to say you should focus on module-esound-sink i guess it works very similar to your bt stuff i guess i.e. it is modelled around a single fd. + +[...] + +In the RT thread you should be running a pa_rtpoll() event loop, which is actually very similar to the main event loop but a bit more designed for RT stuff (though actually the pa_mainloop stuff should eventually be dropped in favour of pa_rtpoll entirely...) + +J: that's how the esd sink works also, right? + +L: Yes, all sinks use pa_rtpoll + +So, where are you lost? any specific area? i can shed some light on? + +J: This talk clarified some points to me + +L: [[http://pulseaudio.org/wiki/ThreadingModel|http://pulseaudio.org/wiki/ThreadingModel]], that wiki doc stuff is still very much relevant, but unfortunately out of date. + +J: I still not sure which messages should I take care of on sink_process_msg. + +L: Usually you want to implement PA_SINK_MESSAGE_GET_LATENCY. It is necessary of getting the latency right. + +J: I saw on esd_sink that it take cares of some messages about state changing and call pa_sink_process_msg + +L: It uses PA_SINK_MESSAGE_SET_STATE to be notified about state changes of the sink (i.e. if we enter suspended mode), because it uses the time smoother framework and wants to stop the smoother as quickly as possible if we enter suspend mode. + +J: the time smoother stuff I still didn't get, what states can a sink be on? + +L: The states of a sink are these: + +* PA_SINK_INIT: the sink has been allocated, but has not yet been + * installed in the core with pa_sink_put() +* PA_SINK_RUNNING: we are playing something +* PA_SINK_SUSPENDED: the device has been temporarily + * suspended. usually this should cause the device file to be closed +* PA_SINK_IDLE: very similar to PA_SINK_RUNNING but signifies that no + * non-paused stream is connected to the sink. Usually this should be handled like PA_SINK_RUNNING, but can be used as an optimization for some cases, since pa_sink_render() will always return silence in this state +* PA_SINK_UNLINKED: the sink has been removed from the core and is + * being destructed +Since IDLE and RUNNING is so very similar you usually should check for both at the same time, which is why we have PA_SINK_IS_OPENED() which just takes the state and returns TRUE if the state is RUNNING or IDLE. + +To tell the difference between "alive" and "dead" we also have PA_SINK_IS_LINKED() which can be used to check for everything that is not _INIT or _UNLINKED. + +So much about the states. Again, usually you want to treat _RUNNING and _IDLE the same. But _SUSPEND needs special handling for most devices, but doesn't need to either. + +The states for sources are very similar. + +J: when a sink is suspended, does it still show up under volume manager and elsewhere? + +L: Yes it does. As long as it is RUNNING, IDLE, SUSPENDED it is considered "alive" and can be used for everything. If it is INIT or UNLINKED, t is considered "dead" and doesn't show anywhere. + +About the smoother: many audio devices don't really provide any good timing source (i.e. a2dp doesn't have any timing source at all afaik), which makes them difficult to use for uses where timing is crucial. + +To remedy this i came up with the time smoothers they solve two problems: + +1. they synthesize a kind of stable timing source for devices which haven't +1. it helps with estimate the deviations of timing sources from the local clock +To elaborate a bit more about this: + +For some devices you only have at very few points in time an only very vague idea of where the playback pointer currently is, for example: the esound sink. + +Only after you filled up the TCP socket's buffer completely you have a minimal idea how much data is currently on its way to the other side. Otherwise the buffering of the TCP stack makes estimatations of how much data is still on its way completely impossible. + +Hence, when we filled up the TCP socket completely, so that it doesn't take any further write requests for the moment, we tell the time smoother about it, and about how many bytes are currently in the TCP buffers, and then the time smoother will be able to help us telling the current playback time later on, when a client might be asking at arbitrary times. + +I now use it at a lot of places actually. It is used in the alsa sink, for example, to deal with the fact that we need to estimate when the hw playback buffer will underrun, and we need that timing information in the time domain of the system clock, not of the sound card clock. + +Also, on some sound cards asking for the timing info is very expensive. I use it on the client side too, so that whenever a client asks for the latency/playback time, i don't have to go to the server side and ask for the timing, but instead i can interpolate the timing from information i got a bit earlier. + +So, you probably can consider the smoother kind of a black box: you fill in x and y when you have the data. + +x being the local time, y being the estimate time of the source you want to interpolate/smoothen, and then you can ask by passing in another x later what the smooter thinks that y is now going to be on ther other timing source. + +pa_smoother_put() pushes x/y into the smoother. pa_smoother_get() gets y for an x. And then there are a few more functions to deal with timing offsets and suspend/resuming of the timing source. + +Internally, all it does is doing a spline interpolation between the data you fill in, and then use the calculate spline to estimate the values for the future (though actually it still does a little bit more, but that's just detail...) + +J: And what about pa_smoother_set_time_offset() + +L: Various time sources deviate in differnt ways, they can: + +1. have a different start time. i.e. while one clock started on 1st jan 1970 as 0, another clock might have started when your compzter booted up and conisder that 0, or when an audio devcie started to play and consider that 0 +1. have a different speed. i.e. when one clock thinks 1s passed a different clock things 1001ms passed +1. the data from one (or both) of the clocks is noisy. +J: hum, so 1 is corrected with set_offset? + +L: Yes, set_offset corrects the initial offset that is explained in 1). 2) and 3) are automatically corrected by the smoother (or at least it is tried to correct them automatically). + +J: And how can I calculate this offset? + +L: Depends if you just count bytes your write, then you would just call _set_time_offset(s, pa_rtclock_usec(), 0); when you start counting them. + +If you have an explicit timing function (i.e. because your device exports a real clock), then you would just call that function when you start with your stuff, and pass its return value to _set_time_offset(), i.e. _set_time_offset(s, pa_rtclock_usec(), get_time_of_my_device()); + +You call that function only once when you start your stuff (if i remember) + +The smoother is of course not perfect, and contains a lot of tweaks to make things work even in the worst conditions. But sometimes those tweaks might actually break things for you ;-) so if you experience problems, ping me! + +[...] + +J: one quick: what is the easiest way to test a new sink? do I have to hook some application to PA or is there any internal mechanism? + +L: you can load module-sine i.e. write your own minimal default.pa that just loads your module and module-sine module-sink will create a single pa_sink_input on the default sink and just play a sine wave at 440hz + +Oh, if you need to valgrind your stuff in the current git version you can now set $VALGRIND to 1 and run pa like that in a valgrind and it will disable the capabilities code. + +We check for $VALGRIND only if you build without optimizations. + +However, ./bootstrap.sh disables optimizations anyway. o you should be good, just wanted to warn about that ;-) + + +[[!format txt """ +VALGRIND=1 libtool --mode=execute valgrind ./pulseaudio +"""]] +That's how i run pa these days if i need to valgrind it. + +J: Ok, thanks for all the explanations + +L: You're welcome + +jprvita goes back to coding + +jprvita saves chat log for reference diff --git a/Software/PulseAudio/Documentation/Developer/MainLoop.mdwn b/Software/PulseAudio/Documentation/Developer/MainLoop.mdwn new file mode 100644 index 00000000..bef72918 --- /dev/null +++ b/Software/PulseAudio/Documentation/Developer/MainLoop.mdwn @@ -0,0 +1,36 @@ + +[[!inline pages="Software/PulseAudio/TOC" quick="yes" raw="yes"]] [[!inline pages="DevelopingModulesTOC" quick="yes" raw="yes"]] + + +# The daemon mainloop + +The daemon has one mainloop, and its API is available in `pa_core`'s `mainloop` field. All the daemon mainloop does is execute the short functions (_callbacks_) that all the different subsystems and modules give it for execution. The callbacks are short in duration, because the mainloop is single-threaded, so when a callback executes, everything else is stalled. Giving a function for execution is called creating an event. + +There are three different ways to give a function to the mainloop, in other words there are three different kinds of events. + +There is the "deferred event", which happens (the callback gets called) immediately in the sense that the mainloop doesn't wait for anything, but executes the function as soon as it can (there may be other events waiting for processing before yours). + +Another event type is the "timed event". It happens after a fixed amount of time has passed since the event was created (or the timer reset). + +The third event type is the "IO event". It's the only one that can be fired outside the mainloop thread. Creating an IO event registers a file descriptor in the mainloop, and then the mainloop polls that descriptor. So you can construct a pipe and give the reading end to the mainloop, and then you can from some other thread write to the pipe, and that will fire the event, i.e make the mainloop execute the function you gave it on the event creation. + +The functions mentioned here are from the [[mainloop API|http://0pointer.de/lennart/projects/pulseaudio/doxygen/structpa__mainloop__api.html]]. For example, if you happen to have nothing but a pointer to your module's `pa_module` structure, and you want to create a deferred event with `defer_new()`, you could say + + +[[!format txt """ +pa_defer_event* e = module->core->mainloop->defer_new(module->core->mainloop, defer_cb, userdata); +"""]] +Remember: all calls of the mainloop functions must be done from the mainloop thread. + + +## Using deferred events + +There are two reasons the deferred event type exists (if you happen to have some other use cases, that's fine). Firstly, you might want to run some procedure (maybe cleanup) from multiple points in your code, but you don't want to call a function twice. You can enable a deferred event in those places, and when the control returns to the mainloop, the procedure will be run once only. The second case is when you need to escape your own stack frame. That may happen if some object needs to destruct itself and wants to make sure that noone in its execution stack accesses the object after it's been destroyed. This case can be avoided with proper refcounting. + +In order to use a deferred event, the first thing you'll need is an event object, it's created with `defer_new`. You give it the callback and a parameter that will be passed on to the callback function. You will need to clean up the created events, so there should be a pointer for each event in your module's private data structure. You can create the event object just before you want it fired, or you can create it earlier, perhaps in the module initialization. + +Deferred events can be enabled and disabled with `defer_enable`. If you don't disable the event in the callback, it will fire repeatedly. If you choose to create the event before you actually want it fired, you have to disable the event right after you have created it. + +Deferred events are removed from the mainloop (and they'll have their memory freed too) with `defer_free`. If you need to do some cleanup yourself when the event is destroyed, you can set up a callback with `defer_set_destroy`. + +_To be continued..._ diff --git a/Software/PulseAudio/Documentation/Developer/ModuleAPI.mdwn b/Software/PulseAudio/Documentation/Developer/ModuleAPI.mdwn new file mode 100644 index 00000000..2da25a81 --- /dev/null +++ b/Software/PulseAudio/Documentation/Developer/ModuleAPI.mdwn @@ -0,0 +1,119 @@ + +[[!inline pages="Software/PulseAudio/TOC" quick="yes" raw="yes"]] [[!inline pages="DevelopingModulesTOC" quick="yes" raw="yes"]] + + +# Interface of `pa_module` + +When you write a module, it can be thought as a subclass of `pa_module`, if you're familiar with the object oriented programming concepts. `pa_module` with its associated functions define some basic functionality that all the different modules include and refine. Let's see if there's any useful stuff in that basic functionality. + +I'll walk you through the interface, see [[pulsecore/module.h|http://www.pulseaudio.org/browser/branches/lennart/src/pulsecore/module.h]] for a more compact reference, and also for the complete definitions, as I won't repeat the field and function types here. + + +## `struct pa_module` +`core` +: + * Here you have a pointer to the core that the module is connected to. + +`name` +: + * The name that was used when loading the module, i.e. the first argument to the "load-module" command. + +`argument` +: + * The whole argument string that was given with the "load-module" command. You could parse this yourself, but it's better to use the available helper functions. See [[[[Software/PulseAudio/Documentation/Developer/ModuleArgumentsAPI|Software/PulseAudio/Documentation/Developer/ModuleArgumentsAPI]]]]. + +`index` +: + * Every loaded module is assigned an index in the core that is used as an unique identifier. If you're ever going to need the index for any purpose, note that it is set only after `pa__init` returns, so its value is undefined during the initialization. + +`dl` +: + * Handle through which the module's symbols are loaded. You can probably ignore this. + +`init` +: + * Pointer to the `pa__init` function. + +`done` +: + * Pointer to the `pa__done` function. + +`userdata` +: + * This is initially NULL. This field belongs completely to you, you store a pointer to your custom data in this variable and you take care of freeing it too. + + +The next three fields are part of the [[automatic unloading|Software/PulseAudio/Documentation/Developer/ModuleAPI]] functionality, and you need to care about only one of them (`n_used`), and you can ignore that too, if you don't want to support the functionality. +`n_used` +: + * Number of current "users". If you allow automatic unloading, value 0 is a precondition for automatic unloading to happen. Initialized to -1. Don't change this directly, use `pa_module_set_used` instead. + +`auto_unload` +: + * This is managed by the autoload system, don't modify. 0 means that automatic unloading is off and 1 means on. + +`last_used_time` +: + * This gets updated whenever you change `n_used` to 0 with `pa_module_set_used`. Not initialized until the first zeroing of `n_used`! + +`unload_requested` +: + * This is set to 1 when someone (might be you) wants to unload the module. Initialized to 0. Don't change this directly, use `pa_module_unload_request` instead. + + + +## Functions and macros + +Loading and unloading functions are primarily for the daemon, except `pa_module_unload_request`, but if you want to do some module management, feel free. +`pa_module_load` +: + * Loads a module and returns a pointer to it. If module loading is disallowed in the core or loading otherwise fails, NULL is returned. + +`pa_module_unload` +: + * Unloads one module instance. + +`pa_module_unload_by_index` +: + * Same as `pa_module_unload`, but uses an index for identification instead of a `pa_module` pointer. + +`pa_module_unload_all` +: + * Unloads all modules. + +`pa_module_unload_unused` +: + * Unloads those modules that allow automatic unloading and have been unused at least for the time specified in `pa_core`'s `module_idle_time`. + +`pa_module_unload_request` +: + * Ask the core to unload a module instance. The actual unloading doesn't happen immediately. If you'd like to call this outside the mainloop thread, don't do that, but instead send a `PA_CORE_MESSAGE_UNLOAD_MODULE` message to the core, see [[[[Software/PulseAudio/Documentation/Developer/CoreAPI|Software/PulseAudio/Documentation/Developer/CoreAPI]]]]. + +`pa_module_set_used` +: + * Updates the number of module users. + +`PA_MODULE_AUTHOR` +: + +`PA_MODULE_DESCRIPTION` +: + +`PA_MODULE_USAGE` +: + +`PA_MODULE_VERSION` +: + * See [[Writing Modules|Software/PulseAudio/Documentation/Developer/Modules]]#Optionalfunctions. + +`pa_module_get_info` +: + * Returns a structure that holds the information you provide with the functions described in [[Writing Modules|Software/PulseAudio/Documentation/Developer/Modules]]#Optionalfunctions. For details, see [[pulsecore/modinfo.h|http://www.pulseaudio.org/browser/branches/lennart/src/pulsecore/modinfo.h]]. + + + +## Automatic unloading + +Automatic unloading is part of the autoload feature of PulseAudio. The modules that the user has told the system to load automatically are also unloaded automatically, if they support it. + +If you want your module to support automatic unloading, keep the `n_used` field updated by calling `pa_module_set_used` in right places. What are the "right places", is fully up to you. Setting the user count to zero causes an unload if the counter isn't reset to some other value quickly. diff --git a/Software/PulseAudio/Documentation/Developer/ModuleArgumentsAPI.mdwn b/Software/PulseAudio/Documentation/Developer/ModuleArgumentsAPI.mdwn new file mode 100644 index 00000000..dc9d74a5 --- /dev/null +++ b/Software/PulseAudio/Documentation/Developer/ModuleArgumentsAPI.mdwn @@ -0,0 +1,32 @@ + +[[!inline pages="Software/PulseAudio/TOC" quick="yes" raw="yes"]] [[!inline pages="DevelopingModulesTOC" quick="yes" raw="yes"]] + + +# Interface of `pa_modargs` + +The module's raw argument string is stored in `pa_module`'s `argument` field. + +The arguments should be given as key-value pairs so that the pairs are separated with whitespace and the key and the value are separated with '='. The value can be enclosed in ticks (') or double quotes ("). + +Since the arguments are given with the rules specified above, you should parse them using the same rules. Obeying the rules has the additional advantage that you can use ready-made utilities for the parsing task. + +I'll walk you through the interface, see [[pulsecore/modargs.h|http://www.pulseaudio.org/browser/branches/lennart/src/pulsecore/modargs.h]] for the complete but compact reference. + + +## `struct pa_modargs` + +The `pa_modargs` structure's fields are not your concern, so they don't appear in the header file either. (`pa_modargs` is currently really a `pa_hashmap`, in case you're curious.) + + +## Functions +`pa_modargs_new` +: + * This returns the arguments split to key-value pairs (at this point the values are just strings). You can use `pa_module`'s `argument` field as the first parameter. The second parameter is a NULL-terminated array of the argument keys your module accepts. If the user gives any argument key is that is unknown, `pa_modargs_new` returns NULL, as is the case with generally malformed arguments too. + +`pa_modargs_free` +: + * The `pa_modargs` destructor. + +`pa_modargs_get*` +: + * I think the comments in the header file are quite sufficient. The functions that return an `int` return 0 on success and -1 on failure. Documentation for `pa_channel_map` and `pa_channel_map_def_t` is available [[here|http://0pointer.de/lennart/projects/pulseaudio/doxygen/channelmap_8h.html]] and for `pa_sample_spec` [[here|http://0pointer.de/lennart/projects/pulseaudio/doxygen/sample_8h.html]].
\ No newline at end of file diff --git a/Software/PulseAudio/Documentation/Developer/Modules.mdwn b/Software/PulseAudio/Documentation/Developer/Modules.mdwn new file mode 100644 index 00000000..cbb6f0eb --- /dev/null +++ b/Software/PulseAudio/Documentation/Developer/Modules.mdwn @@ -0,0 +1,199 @@ + +[[!inline pages="Software/PulseAudio/TOC" quick="yes" raw="yes"]] [[!inline pages="DevelopingModulesTOC" quick="yes" raw="yes"]] + + +# Writing new PulseAudio modules + + +## Introduction + +I want to rewrite the JACK modules from scratch, and in order to do that I need to know how modules work and how to use the PulseAudio APIs. Instead of reading the sources I'd like to have a friendly guide that tells me what to do. Because there isn't such a guide, I'll write it myself as I learn stuff by other means. Hopefully this will be useful for future module writers too. + +This documentation is for the "master" branch in the git, which will eventually become the 0.9.7 release. After 0.9.7 I think I will keep updating these pages as git changes (the APIs needed to write modules are mostly considered internal and thus unstable), but keeping the information for 0.9.7 users there too. + +This is a wiki, so please improve this yourself whenever you spot inaccuracies, confusion, bad English or straight lies. + +**Update May 6, 2008:** It's been now eight months since this tutorial was last edited. I didn't finish the JACK modules (Lennart made them good enough for the 0.9.7 release), and I didn't finish this tutorial, nor have I been keeping this up to date for the parts that have been written. If you notice something that has changed since 0.9.7, please fix it, or at least add a note about it. Also, I claim no ownership over this tutorial, so if you have more time and motivation than me, feel free to improve it in any way you want. --tanuk + + +## What is a module? + +A module is a shared object file that contains implementations of certain functions. The daemon loads the modules from a predefined directory, which by default is /usr/local/lib/pulse-<version>/modules/ and can be configured when the daemon is built. The module's file name starts with "module-" by convention and has the system specific extension for shared objects, on my system it is ".so". The file name (without the extension) is used as the identifier that is given to the "load-module" command in the daemon startup configuration file or in the pacmd program. For example "load-module module-sine" tells the daemon to load a module from the file module-sine.so. + + +## Compiling to a shared object file + +This section is here in the case you're like me and don't know anything about the specifics of shared object compilation. This works on my machine: + + +[[!format txt """ +gcc -g -shared -o module-<yourmodule>.so module-<yourmodule>.c +"""]] +Copy the resulting .so file to the modules directory and you're done, you can now load your module by running pacmd and saying "load-module module-<yourmodule>". + +**Update on July 30 2008:** Sometime it is not so straightforward, as your module uses some definitions and variables from other files and libraries. You probably use the [[PulseAudio|PulseAudio]] configure script and Makefile to build your module. In the case, you may update configure.ac and Makefile.am to add your module support. + +Here is a code snippet in configure.ac, which adds an optional module abc as an example: +[[!format txt """ +... +#### ABC support #### + +AC_ARG_ENABLE([abc], + AC_HELP_STRING([--disable-abc],[Disable optional ABC module support]), + [ + case "${enableval}" in + yes) abc=yes ;; + no) abc=no ;; + *) AC_MSG_ERROR(bad value ${enableval} for --disable-abc) ;; + esac + ], + [abc=no]) + +if test "x${abc}" != xno ; then + if test "x$HAVE_DBUS" = x1 && test "x$HAVE_GLIB20" = x1 ; then + AC_DEFINE([ABC], 1, [Have ABC module.]) + ABC=1 + else + ABC=0 + fi +else + ABC=0 +fi +AM_CONDITIONAL([ABC], [test "x$ABC" = x1]) +... +"""]] +Here is a code snippet to add abc module to src/Makefile.am +[[!format txt """ +... +if ABC +modlibexec_LTLIBRARIES += \ + libdbus-util.la \ + module-abc.la +endif +... +module_abc_la_SOURCES = modules/module-abc.c +module_abc_la_LDFLAGS = -module -avoid-version +module_abc_la_LIBADD = $(AM_LIBADD) $(DBUS_LIBS) $(GLIB20_LIBS) libpulsecore.la +module_abc_la_CFLAGS = $(AM_CFLAGS) $(DBUS_CFLAGS) $(GLIB20_CFLAGS) +... +"""]] +In configure script and Makefile.am, the module may have some dependencies. You need find the right position to add those codes. -stanley + + +## Required functions + +There is one function that every module must implement, the daemon refuses to load the module if it isn't present. +[[!format txt """ +int pa__init(pa_module* m); +"""]] +`pa_init` is called when the daemon loads the module. Any initialization work is supposed to be done in the `pa_init` function. + +Some modules may be such that their purpose becomes fulfilled already during the initialization. However, most modules need to do some cleanup work when they are unloaded, so some kind of "destructor" is almost mandatory too. It is called `pa__done`. + + +[[!format txt """ +void pa__done(pa_module* m); +"""]] +The return value of `pa__init` tells the daemon whether the initialization succeeded or not. A negative number means failure and zero or greater means success. If `pa__init` fails, `pa__done` won't be called. + +The `pa_module` type is defined in [source:branches/lennart/src/pulsecore/module.h pulsecore/module.h] and will be explained later. + +So the minimal module that the daemon agrees to load is: + + +[[!format txt """ +#include <pulsecore/module.h> + +int pa__init(pa_module* m) +{ + return 0; +} +"""]] + +## Optional functions + +There are a few other functions that are loaded from the .so file if they are implemented. + + +[[!format txt """ +const char* pa__get_author(); + +const char* pa__get_description(); + +const char* pa__get_usage(); + +const char* pa__get_version(); +"""]] +These strings give additional information about the module, which may be extracted from the modules by running: + + +[[!format txt """ +pulseaudio --dump-modules --verbose +"""]] +You can do these functions more compactly with macros that are defined in module.h. This example is from module-null-sink.c: + + +[[!format txt """ +PA_MODULE_AUTHOR("Lennart Poettering") +PA_MODULE_DESCRIPTION("Clocked NULL sink") +PA_MODULE_VERSION(PACKAGE_VERSION) +PA_MODULE_USAGE( + "format=<sample format> " + "channels=<number of channels> " + "rate=<sample rate> " + "sink_name=<name of sink>" + "channel_map=<channel map>" + "description=<description for the sink>") +"""]] + +## Static linking of modules + +It is sometimes desirable to link modules statically in the daemon binary instead of using dynamic loading. If every module defines its own `pa__init`, that's a serious problem, because you could use static linking only for one module. PulseAudio uses libtool, which provides magic that allows the same code to be used either dynamically or statically linked without these problems. That requires a small bit of work from you, the module writer. + +You have to create a header file that you include from the source file. Let's use the module-null-sink as an example again. These are the contents of module-null-sink-symdef.h, copy it to yourself and modify the "null-sink" parts to match your own module's name: + + +[[!format txt """ +#ifndef foomodulenullsinksymdeffoo +#define foomodulenullsinksymdeffoo + +#include <pulsecore/module.h> + +#define pa__init module_null_sink_LTX_pa__init +#define pa__done module_null_sink_LTX_pa__done +#define pa__get_author module_null_sink_LTX_pa__get_author +#define pa__get_description module_null_sink_LTX_pa__get_description +#define pa__get_usage module_null_sink_LTX_pa__get_usage +#define pa__get_version module_null_sink_LTX_pa__get_version + +int pa__init(pa_module*m); +void pa__done(pa_module*m); + +const char* pa__get_author(void); +const char* pa__get_description(void); +const char* pa__get_usage(void); +const char* pa__get_version(void); + +#endif +"""]] +Of course, this is so mechanical stuff that the file can be very well be given to the computer to generate. The PulseAudio developers use a M4 script to generate the symdef files at build time. Read [source:branches/lennart/src/Makefile.am Makefile.am] (search for "SYMDEF") and [source:branches/lennart/src/modules/module-defs.h.m4 modules/module-defs.h.m4] to see how it is done. + + +## State data + +With the interfaces so far introduced, writing modules isn't a terribly useful activity. Now you can basically make a "Hello world" module, optionally with the advanced feature that it prints "Goodbye world" when the module gets unloaded. Next we'll see how a module can carry its internal state data from `pa__init` to `pa__done`. Still not too awesome an ability, but with that you could do for example a module that measures the time how long it takes from loading to unloading, that's almost useful! + +`pa_module` has the field `userdata`. It is a `void` pointer, of which purpose is to store a pointer to the internal state data of your module. So you allocate some data structure that you want to use for your data in `pa__init`, then set the `pa_module`'s (that you get as a parameter) `userdata` field to point to the allocated structure. In `pa__done` you'll have as a parameter the same `pa_module`, and there you'll find your internal data. + + +## Continuing to the PulseAudio internals + +Now that you know the very basics of writing a PulseAudio module, we can start to go through the various APIs inside PulseAudio and see what they offer us. + +You're basically writing a subclass of `pa_module`, so it would probably be a good starting point to have a look on what the superclass contains. [[[[Software/PulseAudio/Documentation/Developer/ModuleAPI|Software/PulseAudio/Documentation/Developer/ModuleAPI]]]] + +For getting the module parameters that the user has given, read [[[[Software/PulseAudio/Documentation/Developer/ModuleArgumentsAPI|Software/PulseAudio/Documentation/Developer/ModuleArgumentsAPI]]]]. + +The only way to expand your abilities inside PulseAudio is to follow the `core` pointer in the `pa_module` structure. Let's go there. [[[[Software/PulseAudio/Documentation/Developer/CoreAPI|Software/PulseAudio/Documentation/Developer/CoreAPI]]]] + +You will likely run into situations where you'd want the daemon mainloop execute some code of your own. For achieving that, read [[[[Software/PulseAudio/Documentation/Developer/MainLoop|Software/PulseAudio/Documentation/Developer/MainLoop]]]]. diff --git a/Software/PulseAudio/Documentation/Developer/OProfile.mdwn b/Software/PulseAudio/Documentation/Developer/OProfile.mdwn new file mode 100644 index 00000000..75272af2 --- /dev/null +++ b/Software/PulseAudio/Documentation/Developer/OProfile.mdwn @@ -0,0 +1,39 @@ + + +# How to Use OProfile for Profiling PulseAudio + +1. Install OProfile. It's available readily packaged on all relevant distributions. +1. Tell OProfile about your kernel: + +[[!format txt """ +opcontrol --vmlinux=/path/to/vmlinux +"""]] +* In case you don't have your uncompressed vmlinux image lying around, you can disable kernel-level profiling like this: + +[[!format txt """ +opcontrol --no-vmlinux +"""]] +* Note that since our task is to profile [[PulseAudio|PulseAudio]] (and not the kernel) passing --no-vmlinux has no practical limitation. +* Start profiling: + +[[!format txt """ +opcontrol --start +"""]] +1. Play around with [[PulseAudio|PulseAudio]] and execute the code paths you want to profile. It is advisable to pass --no-cpu-limit to [[PulseAudio|PulseAudio]] or set no-cpu-limit=yes in daemon.conf to deactivate the CPU load limiter in PA and make sure that if PA starts to spin in some loop it will continue to do that and it really shows up in the profiling output. +1. Generate a per-symbol break down of the profile data: + +[[!format txt """ +opreport -l /usr/bin/pulseaudio +"""]] +1. If you have the sources of PA lying around (i.e. installed debuginfo packages or built PA yourself) you may also generate an annotated source code: + +[[!format txt """ +mkdir -p /home/lennart/pa-annotated-sources +opannotate --source --output-dir=/home/lennart/pa-annotated-sources /usr/bin/pulseaudio +"""]] +1. Send me the per-symbol break down and on request some of the annotated sources. +If you are building and running PA from the source tree then make sure to set dl-search-path in your daemon.conf to the src/.libs subdirectory of your source tree (libtool likes to put the built shared objects there). Also note that you need to pass .../src/.libs/lt-pulseaudio as binary name to opreport/opannotate. + +Also see the cheat sheet on [[The OProfile documentation pages|http://oprofile.sourceforge.net/docs/]]. + +While you run PA under oprofile make sure to disable the load limiter (pass --no-cpu-limit) so that PA continues to run after entering an endless loop and that it actually becomes possible to track down which loop that is. diff --git a/Software/PulseAudio/Documentation/Developer/Passthrough.mdwn b/Software/PulseAudio/Documentation/Developer/Passthrough.mdwn new file mode 100644 index 00000000..47793741 --- /dev/null +++ b/Software/PulseAudio/Documentation/Developer/Passthrough.mdwn @@ -0,0 +1,100 @@ + +**This is an RFC and does not necessarily represent the final implementation** + +--- + + + + +# Goal + +Get all the passthrough support to the point where things work automagically or with minimal user input, for AC3/DTS over S/PDIF or MP3 over Bluetooth. This develops on Pierre-Louis Bossart's patches on the mailing list and subsequent discussion between Pierre and Tanu Kaskinen. + + +# Broad idea + +When a client creates a new stream, it gives a list of formats that it can provide. The list must cover all formats that the client can support (usually the list contains only one tuple with only fixed parameters). The daemon routes the stream to some sink, and then the daemon takes an intersection of the sink formats and the stream formats. + +If the resulting set contains exactly one fixed format, then that is used for the stream. If the set contains more options than one fixed format, then the daemon decides the "best" format using some unspecified algorithm. If the set is empty, then the stream creation fails. + +In the future, we can make it so that the API stops at an intermediate ROUTED state if the client does not provide any formats. The client can then query what formats are available and set the one it prefers. + +If the user switches to a different sink, one of 3 scenarios can occur: + +1. Switch from PCM to compressed format: e.g. a switch to BT headset b. Switch from compressed to PCM format e.g. switch back to sound card c. Stay on current format +Switching from one compressed format to another (e.g. MP3 -> AC3) does not make sense, so need not be supported. It is assumed that all sinks support playing some PCM format (and that PA will convert as appropriate). + +When switching to a new format a format lost event is emitted and the client must close its current stream and open a fresh stream in order to set things up for the new format. + + +# API changes + + +## Formats + +We add a new enum type to represent various encoding formats. For now, we do not worry about VBR streams since all the use cases we're working with are IEC61937 formatted and have a fixed bytes-to-us conversion. The formats we add for now are: + + +[[!format txt """ +typedef enum pa_encoding_t { + PA_ENCODING_PCM, + PA_ENCODING_AC3_IEC61937, + PA_ENCODING_EAC3_IEC61937, + PA_ENCODING_DTS_IEC61937, + PA_ENCODING_MPEG1_L3_IEC61937, + PA_ENCODING_MPEG2_L3_IEC61937, + PA_ENCODING_ANY, +} pa_encoding_t; +"""]] +This isn't exhaustive, and more formats can be added as they are actually tested. + + +[[!format txt """ +typedef struct pa_format_info { + pa_encoding_t encoding; + pa_proplist *plist; + /* `-- allow attaching arbitrary info, such as a priority, bitrate, ... */ +} pa_format_info; +"""]] + +## Stream API + +The stream API gets an alternative version that uses pa_format_info instead of pa_sample_spec: + + +[[!format txt """ +/* format is an array of formats the client can offer */ +pa_stream* pa_stream_new_extended(pa_context *context, + const char *name, + const pa_format_info * const *formats, + pa_proplist *plist); + +"""]] +When making the connection, routing is performed and the selected format can be queried when the stream goes to the PA_STREAM_READY state + + +[[!format txt """ +/* Returns a NULL-terminated list of formats (for now, containing only one item + * - the negotiated format */ +const pa_format_info* pa_stream_get_format_info(pa_stream *s); +"""]] + +[[!format txt """ +/* This is implicit in the format, but still convenient to have, and + * effectively deprecates the PA_SINK_INPUT_PASSTHROUGH flag */ +int pa_format_info_is_pcm(const pa_format_info *f); +"""]] + +## Others + +We still need to make a volume/mute disabled notification for sinks and sink inputs when they are operating in passthrough mode. Currently, volume changes are ignored in passthrough mode. + + +# Credit + +This RFC is based on Pierre's previous work and discussion on-/off-list with: + +* Pierre-Louis Bossart +* Tanu Kaskinen +* Wim Taymans +* Arun Raghavan
\ No newline at end of file diff --git a/Software/PulseAudio/Documentation/Developer/ReleasePlanning.mdwn b/Software/PulseAudio/Documentation/Developer/ReleasePlanning.mdwn new file mode 100644 index 00000000..533dc579 --- /dev/null +++ b/Software/PulseAudio/Documentation/Developer/ReleasePlanning.mdwn @@ -0,0 +1,65 @@ + +[[!inline pages="Software/PulseAudio/TOC" quick="yes" raw="yes"]] + + +# The Plan + +This schedule is a guideline to keep a set of rolling releases rather than a longer cycle with lots of changes in between. + +* All releases happen off the master branch, and are numbered as N.0 +* If a release introduces a major bugs/regressions that need immediate attention, a stable-N.x branch is created and point releases in that series (N.1, N.2, ...) are made off this branch +* Major releases are planned to be made every 4 months +* A feature freeze will be announced ~2-4 weeks before the release, depending on how large the changes that have gone into the release are +* Periodic release candidate tarballs will be rolled out during the freeze period for easy packaging and testing +* World domination is targeted for December 2012 + +## Current Release: 3.0 + +* Target date: Sep 25th, 2012 +* Target freeze date: Sep 11th, 2012 +* Actual date: Oct 31st, 2012 (freeze) + +### Blockers + +* Vala patches [Alexander Kurtz] +* <del>`pa_once` bug</del> done +* <del>module-profile-switcher [Arun Raghavan]</del> deferred +* <del>module-bluetooth-policy [Frederic Dalleau]</del> done +* <del>Fixed resamplers [Pierre-Louis Bossart]</del> deferred +* <del>NEON sconv/mixing [Peter Meerwald]</del> partially done +* <del>Win32 build fixes (Thomas Martitz)</del> done + +# Previous releases + + +## Release: 2.0 + +* Target date: March 26th, 2012 +* Target freeze date: Feb 27th, 2012 +* Actual date: May 11th, 2012 + +### Blockers + +Blocker bugs are tracked on [[bug #45812|https://bugs.freedesktop.org/show_bug.cgi?id=45812]] + +The following patches need to be re viewed and evaluated to see if merging is achievable within a bound timeframe. + +* Vala patches [Alexander Kurtz] +* <del>Jack detection [David Henningsson]</del> done +* <del>module-profile-switcher [Arun Raghavan]</del> deferred +* <del>module-bluetooth-policy [Frederic Dalleau]</del> deferred +* <del>Fixed resamplers [Pierre-Louis Bossart]</del> deferred +* <del>NEON sconv/mixing [Peter Meerwald]</del> deferred +* <del>More Orc [Maarten Bosmans]</del> deferred + +### Highlights + +These should go into release notes. + +* Alternate sample rates +* Echo cancellation: WebRTC canceller, AGC +* Fixed HURD support +* A2DP decoder quality improvements +* Infrastructure + Implementation for headphone/mic jack detection +* Virtual Surround sink support +* Xen Paravirtualised audio sink ([[#43503|https://bugs.freedesktop.org/show_bug.cgi?id=43503]])
\ No newline at end of file diff --git a/Software/PulseAudio/Documentation/Developer/Rewinding.mdwn b/Software/PulseAudio/Documentation/Developer/Rewinding.mdwn new file mode 100644 index 00000000..9f78cf65 --- /dev/null +++ b/Software/PulseAudio/Documentation/Developer/Rewinding.mdwn @@ -0,0 +1,313 @@ + +[[!inline pages="Software/PulseAudio/TOC" quick="yes" raw="yes"]] [[↩ Back to Developer|Software/PulseAudio/Documentation/Developer]] + + +# Rewinding + +(This page talks only about sink rewinding, but supposedly source rewinding works mostly in the same way. I'm not very familiar with that.) + +Rewinding is mostly used for making changes in the audio hearable as quickly as possible. For example, if volume changes, the change should be hearable immediately. The amount of buffered audio may be large, for example 2 seconds, so without rewinding the changed volume would be hearable only after the 2 seconds of buffered audio have been played. With rewinding, the data in the buffer is rewritten using the new volume. + + +## Buffers + +A useful way to think about the system is that there are three buffers: the sink buffer, the render_memblockq and the sink input implementor's buffer. Each buffer has a read and a write index that normally move forward, but on rewinds one or both of them move backwards. The sink read index never moves backwards. You can think the sink read index as the point where the digital audio is converted into analog signal - there's no way to rewrite that data. + +The three buffers can be thought as infinite, so don't think them as ringbuffers (even if the implementation is a ringbuffer). They don't contain an infinite amount of data, though. The word "infinite" means just that the read and write index grow without limit (the indexes are implemented as 64-bit integers, so they are virtually unlimited). The sink buffer has a hard limit on how far ahead the write index can be from the read index. In other words, the sink buffer has a defined size. The sink buffer size is also the maximum rewind amount that the sink supports, and that is stored in pa_sink.thread_info.max_rewind. + +The max_rewind variable is important, because the render_memblockq and the sink implementor have to keep at least that much of old data buffered. "Old data" means data that has already been given to the sink. If a rewind happens, the sink may need to ask for that old data from the sink input again. + +In addition to the old data, render_memblockq may also have some data buffered that has not yet been given to the sink. This happens only when the sink implementation gives a larger chunk of data than requested, so there's at most one extra chunk buffered in the render_memblockq, so usually it's only a small amount, but in theory that chunk can be arbitrarily large, so don't assume that render_memblockq always contains only a small amount of data (in addition to the old data that has to be kept stored). + +The sink input implementor's buffer has to contain enough old data to cover the sink buffer and whatever extra there is in the render_memblockq. On top of that, the sink implementor may or may not have some extra data of its own buffered. If the implementor can generate an arbitrary amount of data at any time (like module-sine), then there's no need to have any extra data buffered. However, usually the data is received from somewhere else, like from clients using the native protocol, and in those cases there needs to be buffering to prevent underruns. + + +[[!format txt """ +alsa-sink +|-------------| +r w + +render_memblockq +--------------|--| + r w + +native protocol stream +-----------------|-----------------------| + r w +"""]] +There's actually another buffer between render_memblockq and the sink input implementor (in the example above the native protocol stream): if a resampler is used, it may sometimes have some data in its leftover buffer. BUG: That buffer is not currently taken into account when rewinding ([[https://bugs.freedesktop.org/show_bug.cgi?id=53911|https://bugs.freedesktop.org/show_bug.cgi?id=53911]]). + + +## Filter Sinks + +With filter sinks there may be an arbitrary amount of sinks and sink inputs stacked. The filter sinks may or may not have a buffer of their own, but the sink inputs certainly will each have a render_memblockq. The "real" sink inputs, for example native protocol streams, need to keep enough old data buffered to cover all audio that is buffered in the stack of filter sinks. + +BUG: Currently this is broken ([[https://bugs.freedesktop.org/show_bug.cgi?id=53709|https://bugs.freedesktop.org/show_bug.cgi?id=53709]]). The sink input implementations assume that storing max_rewind plus the extra data in their own sink input's render_memblockq is enough. That's OK: the assumption really should hold. The problem is that it doesn't. The max_rewind of a filter sink is incorrect. It's simply copied from the root sink. That's not a good idea, because it ignores the data that is buffered in the filter sink's sink input's render_memblockq, and if the filter sink does any buffering of its own, then also that data is missing from max_rewind. Having a too small max_rewind value means that rewind requests get truncated too much, causing unnecessary latency. + +The max_rewind variable is somewhat static. It can change when the latency configuration changes, but it can't change depending on how much data is currently buffered. max_rewind is supposed to tell an upper limit for how much the sink can have data buffered, not the currently buffered amount. Since render_memblockqs can have an arbitrary amount of data buffered, how can a filter sink provide a meaningful value for max_rewind? I think the answer is that the filter sinks should never return more data from their pop callbacks than requested. That way the render_memblockq of the sink input will never contain any extra data. Also the pa_sink_render_* functions need to have a parameter for specifying a maximum size for the rendered data, because the rendering functions are called by the filter sinks, and if the rendering can result in an arbitrarily large chunk that the filter sink has to buffer, then it's still impossible for the filter sink to provide a meaningful max_rewind value. + +When the filter sink max_rewind issue is fixed, the "three buffers" abstraction works with filter sinks also. The filter sink can be thought to have just a single buffer with length of max_rewind. When rewinding the filter sink, the write pointer of the sink buffer will move back, and it doesn't matter to whoever issues the request if behind the scenes there are actually multiple buffers, each of which will be rewound recursively until the request is fulfilled. + + +## Requesting and Processing Rewinds + +Rewinds are handled in two phases: first a rewind is requested, and then processed. The requests must only come from code in the IO thread that is executed as part of handling messages. This means that requesting a rewind from the main thread is forbidden, but it's also forbidden while rendering data, for example. + +The IO thread of a sink runs in a loop that basically does the following things: + +* Sleep until something happens. This usually means that the backend either wakes up the sink to fill the backend buffer, or with timer-based scheduling, the timer expires. Another common thing is that the sink receives a message. +* Process the event that woke up the sink. In case of a received message, this may generate rewind requests, which are merged into one request. +* Process the rewind request if there is one. +* Fill the sink backend buffer by requesting audio from sink inputs. +The first two bullet points are implemented by pa_rtpoll_run(). + +BUG: Rewinds are processed also by filter sinks in their pop callbacks. While this should be pretty harmless (there should never be any rewind requests pending when the callback is called), it's useless code and may cause confusion ([[https://bugs.freedesktop.org/show_bug.cgi?id=53915|https://bugs.freedesktop.org/show_bug.cgi?id=53915]]). + +Rewind requests can be made with pa_sink_request_rewind() or pa_sink_input_request_rewind(). pa_sink_input_request_rewind() always calls pa_sink_request_rewind(). The rewind requests must always reach the sink that implements the IO thread (the "root sink"), because processing of the rewinds is always done from that sink, and it can't process rewinds that have not been requested from it. Requests made on filter sinks are forwarded to the master sink by calling pa_sink_input_request_rewind() on the sink input between the filter sink and the master sink. + +If multiple rewind requests are made before the processing phase, they are merged so that the biggest rewind request wins. + +Sometimes the rewind amount that is requested from a sink is 0, for example if pa_sink_input_request_rewind() was called and the request can be fully satisfied just by discarding some of the data in the render_memblockq of the sink input. Even though there's no need to rewind anything on the sink, pa_sink_input_request_rewind() will anyway call pa_sink_request_rewind() with amount of 0 bytes, because the sink needs to be notified about all rewind requests so that those requests will get processed. + +When the sink notices (in the IO thread loop in the sink implementor code) that a rewind request has been made, it rewinds the backend buffer as much as was requested, or if that's not possible, then as much as possible. Then the sink calls pa_sink_process_rewind() with the real amount of bytes that was rewound. pa_sink_process_rewind() will then call pa_sink_input_process_rewind() for all sink inputs. + +So, rewind requests are propagated towards the root sink, and rewind processing is propagated outwards from the root sink. + + +## Rewinding a Sink + +Doing a rewind on a sink is conceptually rather simple. The sink has a buffer, and there is a read index and a write index. The sound card reads from the read index, and data from sink inputs is written to the write index. When a sink is rewound, the read index is always left alone (what has been played can't be unplayed), so only the write index is involved in the rewind operation. Rewinding the sink by N bytes simply means moving the write index back by N bytes. + +Filter sinks make this a bit more complicated, though. Depending on how many layers of filter sinks there are, there are at least two buffers involved: the sink input buffer (render_memblockq) and the master sink buffer. When the filter sink is requested to rewind by N bytes, the write index of the render_memblockq is moved back by N bytes, and if the render_memblockq doesn't have that much data stored, then also the master sink buffer is rewound by the amount that was not available in the render_memblockq. + +When the sink has processed the rewind for its own part, it calls pa_sink_input_process_rewind() on all of its sink inputs, passing the amount of bytes by which the sink was actually rewound. If there was no rewind request made on a sink input, then the rewind processing will only move the read pointer of the render_memblockq (to match the moving of the sink write pointer). + + +## Rewinding a Sink Input + +The simple case is when there has been no rewind request on the sink input, and pa_sink_input_process_rewind() is called just to move the read index of render_memblockq to compensate the write index moving in the sink buffer, as explained in the previous section. But if there has been a rewind request on the sink input, then things are more complicated. + +When a rewind request is made on a sink input, four parameters are given: + +* nbytes: The amount to rewind. 0 means "as much as possible". +* rewrite: Should the sink input implementor rewrite the rewound amount of data? If this flag is set, the side effect is that the write index gets moved back by the rewound amount. Otherwise the side effect is that the write index is flushed (i.e. moved to point to the read index). +* flush: Should the render_memblockq contents be discarded (both old data and any data on top of it)? This parameter doesn't affect the read or write index. If rewrite is false, then a flush is implied. +* dont_rewind_render: Should the render_memblockq read index (not) be moved? +The parameters are stored in three variables: + +* thread_info.rewrite_nbytes: If any of the merged requests have rewrite unset, then this will be -1. Otherwise this will be the biggest of the merged rewind requests. +* thread_info.rewrite_flush: If any of the merged requests have flush set and request a rewrite of more than 0 bytes, then this flag will be set. A rewrite request of 0 bytes can only happen when the sink has max_rewind of 0 bytes and the render_memblockq is empty, or when thread_info.playing_for is 0 (so the sink input has been just created or having an underrun). In those cases flushing the render_memblockq is probably a no-op. (But is it actually harmful? Why is the check for 0 done if it doesn't matter in any case? Maybe it's just an optimization, avoiding a redundant pa_memblockq_silence() call? But then again, the pa_memblockq_silence() call is only made when the rewrite amount is more than zero... BUG [[https://bugs.freedesktop.org/show_bug.cgi?id=53923|https://bugs.freedesktop.org/show_bug.cgi?id=53923]]) +* thread_info.dont_rewind_render: If any of the merged requests have dont_rewind_render set, then this flag will be set. +(It's hard for me to be sure that the different kinds of rewinds work correctly when merged... But if the current logic works fine, then maybe it's best to not try fixing what is not broken.) + +The rewind amount that pa_sink_input_request_rewind() gives to pa_sink_request_rewind() is what has been stored in thread_info.rewrite_nbytes, if rewrite = true. If rewrite = false, then it's a bit complicated to explain, except that in practice it seems that if rewrite = false, then the original nbytes is always 0, which will make the final nbytes equal max_rewind. + +Based on the stored variables, pa_sink_input_process_rewind(nbytes=N) will behave as follows (N is the real amount that the sink rewound): + +If dont_rewind_render is not set, the read index of render_memblockq is moved back by N bytes. + +If rewrite_nbytes is -1 (i.e. there was a rewind request with rewrite = false), then the write index will be reset to the read index. + +If rewrite_nbytes is not -1, then the write index of render_memblock is moved back, if the following conditions are met: + +* rewrite_nbytes is greater than 0, which implies: + * the sink supports rewinding or the render_memblockq contains data + * playing_for is greater than 0 +* the actual amount that the sink rewound was greater than 0 or the render_memblockq contains data +The amount that the write index of render_memblockq gets moved back is the actual amount that the sink rewound plus the length of the render_memblockq, or rewrite_nbytes, whichever is less. + +The sink input implementor is notified of the rewind with the process_rewind() callback. The nbytes parameter of the callback is the amount by which the render_memblockq write index was moved (or 0 if there was a rewind request with rewrite = false). + + +## Current Usage (as of 2012-08-11) + + +### pa_sink_request_rewind() + + +#### modules/alsa/alsa-sink.c: sink_update_requested_latency_cb(): pa_sink_request_rewind(s, (size_t) -1); + +The alsa sink does a full rewind when the latency is made smaller. There needs to be a rewind to ensure that the sink buffer doesn't contain more data than what is allowed by the new latency. This is because rewind requests can't be larger than the configured latency, and if there's more data than that in the buffer, a later rewind request may end up being too small. BUG (minor performance issue): A full rewind is unnecessary ([[https://bugs.freedesktop.org/show_bug.cgi?id=54007|https://bugs.freedesktop.org/show_bug.cgi?id=54007]]). BUG (not affecting users): The alsa sink shouldn't need to do this at all ([[https://bugs.freedesktop.org/show_bug.cgi?id=54006|https://bugs.freedesktop.org/show_bug.cgi?id=54006]]). + + +#### modules/module-ladspa-sink.c: LADSPA_SINK_MESSAGE_UPDATE_PARAMETERS: pa_sink_request_rewind(u->sink, -1); + +The ladspa sink does a full rewind when the filter parameters change. This makes the effect of the new parameters become immediately hearable. + + +#### pulsecore/sink-input.c: pa_sink_input_request_rewind(): pa_sink_request_rewind(i->sink, nbytes - lbq); + +The sink input requests the sink to rewind the part of the rewind request that couldn't be satisfied just by rewriting the render_memblockq contents. + + +#### pulsecore/sink-input.c: pa_sink_input_request_rewind(): pa_sink_request_rewind(i->sink, 0); + +The sink input is able to satisfy the whole rewind request internally, but it needs to signal the sink that rewind processing is needed. + + +#### pulsecore/sink.c: PA_SINK_MESSAGE_REMOVE_INPUT: pa_sink_request_rewind(s, (size_t) -1); + +When a sink input is removed, the sink buffer still contains audio from that input. Doing a full rewind will remove as much as possible of that audio. + + +#### pulsecore/sink.c: PA_SINK_MESSAGE_START_MOVE: pa_sink_request_rewind(s, (size_t) -1); + +This is essentially the same case as removing a sink input, from the sink point of view (from a wider point of view there are much more details to get right, and things aren't currently perfect. BUG: [[https://bugs.freedesktop.org/show_bug.cgi?id=54182|https://bugs.freedesktop.org/show_bug.cgi?id=54182]]). + + +#### pulsecore/sink.c: PA_SINK_MESSAGE_FINISH_MOVE: pa_sink_request_rewind(s, nbytes); + +Rewind is requested to make the moved sink input hearable in the new sink as quickly as possible. nbytes is the current sink latency, so in practice this is a full rewind (maybe it would make sense to be explicit about it by changing nbytes to (size_t) -1). + + +#### pulsecore/sink.c: PA_SINK_MESSAGE_SET_VOLUME: pa_sink_request_rewind(s, (size_t) -1); + +Rewind is requested if the soft volume of the sink changes. The purpose of the request is to make the new volume hearable as quickly as possible. + + +#### pulsecore/sink.c:2693: PA_SINK_MESSAGE_GET_VOLUME: pa_sink_request_rewind(s, (size_t) -1); + +Sometimes when pa_sink_get_volume() is called, it's desirable to go all the way to the hardware to ask the current volume. When that happens, it may be that the received value is different than the current sink volume, and in that case the sink volume is updated. That may cause a change in the sink soft volume too, and in that case the sink is rewound to make the new soft volume hearable as soon as possible. + + +#### pulsecore/sink.c:2702: PA_SINK_MESSAGE_SET_MUTE: pa_sink_request_rewind(s, (size_t) -1); + +If the soft mute changes, a rewind is requested to make that change hearable as quickly as possible. + + +### pa_sink_input_request_rewind() + + +#### modules/echo-cancel/module-echo-cancel.c: sink_request_rewind_cb(): pa_sink_input_request_rewind(u->sink_input, s->thread_info.rewind_nbytes, TRUE, FALSE, FALSE); + +Someone has requested the echo-cancel sink to rewind, and it passes the request to the master sink via the virtual sink input. The rewind request size is stored in thread_info.rewind_nbytes, capped at thread_info.max_rewind. BUG: If thread_info.rewind_nbytes is 0, then the sink input will interpret the request as a full rewind ([[https://bugs.freedesktop.org/show_bug.cgi?id=54185|https://bugs.freedesktop.org/show_bug.cgi?id=54185]]). BUG: There may be more data buffered than max_rewind ([[https://bugs.freedesktop.org/show_bug.cgi?id=53709|https://bugs.freedesktop.org/show_bug.cgi?id=53709]]). + + +#### modules/echo-cancel/module-echo-cancel.c: sink_input_state_change_cb(): pa_sink_input_request_rewind(i, 0, FALSE, TRUE, TRUE); + +The echo cancel sink input has been just attached after creation. A rewind request is made so that the sink input becomes hearable as soon as possible. BUG (not affecting users): This could actually be handled by the core in PA_SINK_MESSAGE_ADD_INPUT ([[https://bugs.freedesktop.org/show_bug.cgi?id=54243|https://bugs.freedesktop.org/show_bug.cgi?id=54243]]). + + +#### modules/module-combine-sink.c: sink_input_attach_cb(): pa_sink_input_request_rewind(i, 0, FALSE, TRUE, TRUE); + +The sink input is being attached. A rewind request is made so that the sink input becomes hearable as soon as possible. BUG (not affecting users): This could actually be handled by the core in PA_SINK_MESSAGE_ADD_INPUT ([[https://bugs.freedesktop.org/show_bug.cgi?id=54243|https://bugs.freedesktop.org/show_bug.cgi?id=54243]]). BUG (not affecting users): Requesting the rewind in the attach callback is inconsistent with other sink input implementors ([[https://bugs.freedesktop.org/show_bug.cgi?id=54244|https://bugs.freedesktop.org/show_bug.cgi?id=54244]]). + + +#### modules/module-equalizer-sink.c: sink_request_rewind_cb(): pa_sink_input_request_rewind(u->sink_input, s->thread_info.rewind_nbytes + pa_memblockq_get_length(u->input_q), TRUE, FALSE, FALSE); + +Same as sink_request_rewind_cb() in module-echo-cancel.c, with the extra twist that module-equalizer-sink can have some data buffered also in an internal memblockq. BUG: The internally buffered amount should be substracted from the request that is passed on, instead of making the request larger ([[https://bugs.freedesktop.org/show_bug.cgi?id=54245|https://bugs.freedesktop.org/show_bug.cgi?id=54245]]). BUG: If thread_info.rewind_nbytes and the input_q length are 0, then the sink input will interpret the request as a full rewind ([[https://bugs.freedesktop.org/show_bug.cgi?id=54185|https://bugs.freedesktop.org/show_bug.cgi?id=54185]]). BUG: There may be more data buffered than max_rewind ([[https://bugs.freedesktop.org/show_bug.cgi?id=53709|https://bugs.freedesktop.org/show_bug.cgi?id=53709]]). + + +#### modules/module-equalizer-sink.c: sink_input_state_change_cb(): pa_sink_input_request_rewind(i, 0, FALSE, TRUE, TRUE); + +Same as sink_input_state_change_cb() in module-echo-cancel.c. BUG (not affecting users): This could actually be handled by the core in PA_SINK_MESSAGE_ADD_INPUT ([[https://bugs.freedesktop.org/show_bug.cgi?id=54243|https://bugs.freedesktop.org/show_bug.cgi?id=54243]]). + + +#### modules/module-ladspa-sink.c: sink_request_rewind_cb(): pa_sink_input_request_rewind(u->sink_input, s->thread_info.rewind_nbytes + pa_memblockq_get_length(u->memblockq), TRUE, FALSE, FALSE); + +Same as sink_request_rewind_cb() in module-echo-cancel.c. BUG: The internally buffered amount should be substracted from the request that is passed on, instead of making the request larger ([[https://bugs.freedesktop.org/show_bug.cgi?id=54245|https://bugs.freedesktop.org/show_bug.cgi?id=54245]]). BUG: If thread_info.rewind_nbytes and the u->memblockq length are 0, then the sink input will interpret the request as a full rewind ([[https://bugs.freedesktop.org/show_bug.cgi?id=54185|https://bugs.freedesktop.org/show_bug.cgi?id=54185]]). BUG: There may be more data buffered than max_rewind ([[https://bugs.freedesktop.org/show_bug.cgi?id=53709|https://bugs.freedesktop.org/show_bug.cgi?id=53709]]). + + +#### modules/module-ladspa-sink.c: sink_input_state_change_cb(): pa_sink_input_request_rewind(i, 0, FALSE, TRUE, TRUE); + +Same as sink_input_state_change_cb() in module-echo-cancel.c. BUG (not affecting users): This could actually be handled by the core in PA_SINK_MESSAGE_ADD_INPUT ([[https://bugs.freedesktop.org/show_bug.cgi?id=54243|https://bugs.freedesktop.org/show_bug.cgi?id=54243]]). + + +#### modules/module-loopback.c: SINK_INPUT_MESSAGE_POST: pa_sink_input_request_rewind(u->sink_input, (size_t) (u->sink_input->thread_info.underrun_for == (size_t) -1 ? 0 : u->sink_input->thread_info.underrun_for), FALSE, TRUE, FALSE); + +The sink input has been having an underrun which has now ended. A rewind is requested so that the data that has been missing can be added to the sink buffer. + + +#### modules/module-remap-sink.c: sink_request_rewind(): pa_sink_input_request_rewind(u->sink_input, s->thread_info.rewind_nbytes, TRUE, FALSE, FALSE); + +Same as sink_request_rewind_cb() in module-echo-cancel.c. BUG: If thread_info.rewind_nbytes is 0, then the sink input will interpret the request as a full rewind ([[https://bugs.freedesktop.org/show_bug.cgi?id=54185|https://bugs.freedesktop.org/show_bug.cgi?id=54185]]). BUG: There may be more data buffered than max_rewind ([[https://bugs.freedesktop.org/show_bug.cgi?id=53709|https://bugs.freedesktop.org/show_bug.cgi?id=53709]]). + + +#### modules/module-remap-sink.c: sink_input_state_change_cb(): pa_sink_input_request_rewind(i, 0, FALSE, TRUE, TRUE); + +Same as sink_input_state_change_cb() in module-echo-cancel.c. BUG (not affecting users): This could actually be handled by the core in PA_SINK_MESSAGE_ADD_INPUT ([[https://bugs.freedesktop.org/show_bug.cgi?id=54243|https://bugs.freedesktop.org/show_bug.cgi?id=54243]]). + + +#### modules/module-sine.c: sink_input_state_change_cb(): pa_sink_input_request_rewind(i, 0, FALSE, TRUE, TRUE); + +Same as sink_input_state_change_cb() in module-echo-cancel.c. BUG (not affecting users): This could actually be handled by the core in PA_SINK_MESSAGE_ADD_INPUT ([[https://bugs.freedesktop.org/show_bug.cgi?id=54243|https://bugs.freedesktop.org/show_bug.cgi?id=54243]]). + + +#### modules/module-virtual-sink.c: sink_request_rewind_cb(): pa_sink_input_request_rewind(u->sink_input, s->thread_info.rewind_nbytes + pa_memblockq_get_length(u->memblockq), TRUE, FALSE, FALSE); + +Same as sink_request_rewind_cb() in module-echo-cancel.c. BUG: The internally buffered amount should be substracted from the request that is passed on, instead of making the request larger ([[https://bugs.freedesktop.org/show_bug.cgi?id=54245|https://bugs.freedesktop.org/show_bug.cgi?id=54245]]). BUG: If thread_info.rewind_nbytes and the u->memblockq length are 0, then the sink input will interpret the request as a full rewind ([[https://bugs.freedesktop.org/show_bug.cgi?id=54185|https://bugs.freedesktop.org/show_bug.cgi?id=54185]]). BUG: There may be more data buffered than max_rewind ([[https://bugs.freedesktop.org/show_bug.cgi?id=53709|https://bugs.freedesktop.org/show_bug.cgi?id=53709]]). + + +#### modules/module-virtual-sink.c: sink_input_state_change_cb(): pa_sink_input_request_rewind(i, 0, FALSE, TRUE, TRUE); + +Same as sink_input_state_change_cb() in module-echo-cancel.c. BUG (not affecting users): This could actually be handled by the core in PA_SINK_MESSAGE_ADD_INPUT ([[https://bugs.freedesktop.org/show_bug.cgi?id=54243|https://bugs.freedesktop.org/show_bug.cgi?id=54243]]). + + +#### modules/module-virtual-surround-sink.c: sink_request_rewind_cb(): pa_sink_input_request_rewind(u->sink_input, s->thread_info.rewind_nbytes + pa_memblockq_get_length(u->memblockq), TRUE, FALSE, FALSE); + +Same as sink_request_rewind_cb() in module-echo-cancel.c. BUG: The internally buffered amount should be substracted from the request that is passed on, instead of making the request larger ([[https://bugs.freedesktop.org/show_bug.cgi?id=54245|https://bugs.freedesktop.org/show_bug.cgi?id=54245]]). BUG: If thread_info.rewind_nbytes and the u->memblockq length are 0, then the sink input will interpret the request as a full rewind ([[https://bugs.freedesktop.org/show_bug.cgi?id=54185|https://bugs.freedesktop.org/show_bug.cgi?id=54185]]). BUG: There may be more data buffered than max_rewind ([[https://bugs.freedesktop.org/show_bug.cgi?id=53709|https://bugs.freedesktop.org/show_bug.cgi?id=53709]]). + + +#### modules/module-virtual-surround-sink.c: sink_input_state_change_cb(): pa_sink_input_request_rewind(i, 0, FALSE, TRUE, TRUE); + +Same as sink_input_state_change_cb() in module-echo-cancel.c. BUG (not affecting users): This could actually be handled by the core in PA_SINK_MESSAGE_ADD_INPUT ([[https://bugs.freedesktop.org/show_bug.cgi?id=54243|https://bugs.freedesktop.org/show_bug.cgi?id=54243]]). + + +#### modules/rtp/module-rtp-recv.c: rtpoll_work_cb(): pa_sink_input_request_rewind(s->sink_input, (size_t) (s->sink_input->thread_info.underrun_for == (uint64_t) -1 ? 0 : s->sink_input->thread_info.underrun_for), FALSE, TRUE, FALSE); + +The sink input has been having an underrun which has now ended. A rewind is requested so that the data that has been missing can be added to the sink buffer. + + +#### pulsecore/play-memblockq.c: sink_input_state_change_cb(): pa_sink_input_request_rewind(i, 0, FALSE, TRUE, TRUE); + +Same as sink_input_state_change_cb() in module-echo-cancel.c. BUG (not affecting users): This could actually be handled by the core in PA_SINK_MESSAGE_ADD_INPUT ([[https://bugs.freedesktop.org/show_bug.cgi?id=54243|https://bugs.freedesktop.org/show_bug.cgi?id=54243]]). + + +#### pulsecore/protocol-esound.c: SINK_INPUT_MESSAGE_POST_DATA: pa_sink_input_request_rewind(c->sink_input, 0, FALSE, TRUE, FALSE); + +The sink input has been having an underrun which has now ended. A rewind is requested so that the data that has been missing can be added to the sink buffer. BUG: Instead of requesting a full rewind, the code should check how long the underrun has been. Doing a full rewind can cause skipping if the underrun was short and the sink buffer still has valid data from before the underrun started ([[https://bugs.freedesktop.org/show_bug.cgi?id=54251|https://bugs.freedesktop.org/show_bug.cgi?id=54251]]). + + +#### pulsecore/protocol-native.c: handle_seek(): pa_sink_input_request_rewind(s->sink_input, (size_t) (s->sink_input->thread_info.underrun_for == (uint64_t) -1 ? 0 : s->sink_input->thread_info.underrun_for), FALSE, TRUE, FALSE); + +The sink input has been having an underrun which has now ended. A rewind is requested so that the data that has been missing can be added to the sink buffer. + + +#### pulsecore/protocol-native.c: handle_seek(): pa_sink_input_request_rewind(s->sink_input, (size_t) (indexr - indexw), TRUE, FALSE, FALSE); + +The client does a rewrite of data that is already in the sink input's render_memblockq and possibly also in the sink buffer. The old data needs to be discarded and replaced with the new data. + + +#### pulsecore/protocol-simple.c: SINK_INPUT_MESSAGE_POST_DATA: pa_sink_input_request_rewind(c->sink_input, 0, FALSE, TRUE, FALSE); + +The sink input has been having an underrun which has now ended. A rewind is requested so that the data that has been missing can be added to the sink buffer. BUG: Instead of requesting a full rewind, the code should check how long the underrun has been. Doing a full rewind can cause skipping if the underrun was short and the sink buffer still has valid data from before the underrun started ([[https://bugs.freedesktop.org/show_bug.cgi?id=54251|https://bugs.freedesktop.org/show_bug.cgi?id=54251]]). + + +#### pulsecore/sink-input.c: pa_sink_input_set_state_within_thread(): pa_sink_input_request_rewind(i, 0, TRUE, TRUE, FALSE); + +The sink input is being corked. A rewind is requested to remove the old data from the sink buffer. The "rewrite" parameter is true, because when uncorking, we want the playback to continue from where it was before corking, so we don't want to lose the old data. The "flush" parameter shouldn't matter, because it's a full rewind anyway, but setting it to true ensures that there will be no old data left in the render_memblockq. The "dont_rewind_render" parameter is false, because otherwise the render_memblockq write index would get moved past the read index. With these parameters the read and write indexes will be the same after the rewind. + + +#### pulsecore/sink-input.c: pa_sink_input_set_state_within_thread(): pa_sink_input_request_rewind(i, 0, FALSE, TRUE, TRUE); + +The sink input is being uncorked. A rewind is requested so that the sink input becomes hearable as quickly as possible. The "rewrite" parameter is false, because the head of the sink input implementor's buffer is already at the point where the cork happened (see the previous section). The "flush" parameter doesn't matter, because there's no data in the render_memblockq anyway. The "dont_rewind_render" parameter is true, because the read and write indexes of the render_memblockq are the same. Moving the read pointer would cause silence to be generated, because the write pointer is not moving. + + +#### pulsecore/sink-input.c: PA_SINK_INPUT_MESSAGE_SET_SOFT_VOLUME: pa_sink_input_request_rewind(i, 0, TRUE, FALSE, FALSE); + +The sink input's soft volume changed, so a rewind is requested to make that change audible as quickly as possible. + + +#### pulsecore/sink-input.c: PA_SINK_INPUT_MESSAGE_SET_SOFT_MUTE: pa_sink_input_request_rewind(i, 0, TRUE, FALSE, FALSE); + +The sink input's soft mute changed, so a rewind is requested to make that change audible as quickly as possible. + + +#### pulsecore/sink.c: sync_input_volumes_within_thread(): pa_sink_input_request_rewind(i, 0, TRUE, FALSE, FALSE); + +The sink updates its sink inputs' soft volumes, so a rewind is requested to make those changes audible as quickly as possible. BUG (not affecting users): This duplicates the code in the PA_SINK_INPUT_MESSAGE_SET_SOFT_VOLUME handler, so it would be better to just send that message to the sink inputs ([[https://bugs.freedesktop.org/show_bug.cgi?id=54252|https://bugs.freedesktop.org/show_bug.cgi?id=54252]]). + + +#### pulsecore/sound-file-stream.c: sink_input_state_change_cb(): pa_sink_input_request_rewind(i, 0, FALSE, TRUE, TRUE); + +Same as sink_input_state_change_cb() in module-echo-cancel.c. BUG (not affecting users): This could actually be handled by the core in PA_SINK_MESSAGE_ADD_INPUT ([[https://bugs.freedesktop.org/show_bug.cgi?id=54243|https://bugs.freedesktop.org/show_bug.cgi?id=54243]]). diff --git a/Software/PulseAudio/Documentation/Developer/Threading.mdwn b/Software/PulseAudio/Documentation/Developer/Threading.mdwn new file mode 100644 index 00000000..7973de77 --- /dev/null +++ b/Software/PulseAudio/Documentation/Developer/Threading.mdwn @@ -0,0 +1,99 @@ + +[[!inline pages="Software/PulseAudio/TOC" quick="yes" raw="yes"]] [[!inline pages="DevelopingModulesTOC" quick="yes" raw="yes"]] + + +## A quick description of the threading model + +PA now supports a new RT threading model. That means that access to the audio drivers is now seperated from the main event loop. Originally, doing all stuff in the single event loop seemed to be a good idea but as we started to hook up more and more stuff (including X11 now) to the event loop this turned out to be a bad idea. + +In the new model, each driver should run its I/O code in a seperate thread. Usually this means that each sink and each source are handled in a thread of their own. In some cases (like OSS) a single thread is shared for a pair for sink and source. Communication between the (non-realtime) main thread (that still exists and where a lot of code remains) and the real-time I/O threads is intended to be done entirely lock-free (at least on the RT side). For this we have added couple of lock-free APIs. Most importantly this is pa_asyncmsgq which is a message queue object where pushing and popping is most of the time a lock-free operation, unless we have to sleep an event in which case a unix pipe is used internally. + +[[PulseThreads.png, left|PulseThreads.png, left]] + +A good example for a driver that uses this new model is the OSS driver: [source:src/modules/module-oss.c module-oss.c] (this driver is quite complete but also relatively complicated due to support for both mmap and non-mmap access to the audio driver) Simpler drivers are the NULL and the pipe drivers: [source:src/modules/module-pipe-sink.c module-pipe-sink.c], [source:src/modules/module-null-sink.c module-null-sink.c] (since they do not support the full set of features they might also not be the best example, so please take this with a grain of salt) + +The driver modules are responsible for starting up/shutting down the real-time threads. Where possible the PA internal thread API should be used. The module is also responsible for allocating two pa_asyncmsgq objects. One for communicating from the io thread to the main event loop, and another for the other direction. Then, every time a sink or source object is created the pa_asyncmsgq objects need to be attached to it (using pa_sink_set_asyncmsgq()). Since usually communication between the IO thread and the main thread needs to be both ways it makes a lot of sense to use the pa_thread_mq object which combines two pa_asyncmsgq objects into one: one for each direction. Even if the your driver code does not make direct use of the pa_asyncmsgq objects, you need to allocate them, because some code in PA relies on having them around. + +Event handling inside the thread should be done through a pa_rtpoll object which is an event loop abstraction that supports high resolution timers. The implementing module should usually have a pa_rtpoll for each thread and should attach it to the pa_sink/pa_source objects with pa_sink_set_rtpoll(). + +PA now supports a very basic glib-inspired object model. See [source:src/pulsecore/object.h object.h] and [source:src/pulsecore/msgobject.h msgobject.h] for details. Every object that is a child of pa_msgobject can received messages from a pa_asyncmsgq. + +Most of the methods of pa_sink/pa_source are intended to be called only from the main thread, not from the real-time threads. Notable exceptions are pa_sink_render() and friends and pa_source_post(). Many of the operations that can be done on a pa_sink object require some work in the RT threads. Due to that the default implementations will notify the RT thread via a pa_asyncmsgq. To make sure that no locking is necessary for accessing the data attached to a pa_sink the threads maintain their own copy of a couple of variables in pa_sink::thread_info. + +The RT thread should look like this (in very rough pseudocode, with no error handling or anything): + + +[[!format txt """ +void thread_func(...) { + +for (;;) { + + /* Write something to the device */ + if (something_needs_to_be_done_for_io()) { + do_something_for_io(); + continue; + } + + /* TODO: update this section */ + /* Give the inputs connected to this sink some extra time, if they need it */ + //if (pa_sink_process_inputs(u->sink) > 0) + // continue; + + /* Process the incoming pa_asyncmsgq */ + //if (pa_thread_mq_process(&thread_mq) > 0) + // continue; + + /* Hmm, there's no message for us, really nothing to do, than I guess we have to sleep on the device */ + pa_rtpoll_run(rtpoll); + +} +"""]] +Of course, this is very, very rough pseudocode. Please consult one of the actual drivers for real code. The final pa_rtpoll() should be the *only* function where the RT thread might need to acquire a lock (which is hidden inside the kernel for us), all of the remaining code should be coded lock-free. Only if there's *really nothing* to do we sleep on some kernel code. Otherwise we do the best to process whatever requests we got from anywhere. + +IO from/to the device is obviously our priority in the RT loop. Thus is should be the first thing to deal with in each iteration. Then, the inputs connected to our sink might need some processing time and get it through pa_sink_process_inputs(). Thirdly we process asynchronous messages from our pa_asyncmsq. Fourthly we sleep for new events. If everything is set up properly for the pa_rtpoll object our sleep ends when either messages are received on the pa_asyncmsgq, or IO events happen, or some timer expires, or any other event that is attached to the pa_rtpoll object happens. If any non-trivial processing is done in any of the parts of the RT loop you should use "continue" to restart the loop again. Of course, the question is what "non-trivial" is? I am not sure about this either, it's probably better to be here relatively liberal. + +Since many of the operations that can be issued on a pa_sink are passed to the RT threads via a pa_asyncmsgq message you can overwrite your pa_sink's process_msg() function to handle them. A good example for one of the messages you probably should handle yourself is PA_SINK_MESSAGE_GET_LATENCY which you get whenever someone calls pa_sink_get_latency in the main event loop. The pa_sink object also allows you to overwrite the implementation of get_latency() entirely. You should do this instead of processing the async message, in case you can execute the operation without acquiring a lock. So basically the rule is like this: if you can do an operation (e.g. querying the latency) lock-free from the main thread, then overwrite the get_latency() function pointer. That function will be called from main event loop context. OTOH if you cannot do the operation lock-free then do not overwrite the function but instead process the PA_SINK_MESSAGE_GET_LATENCY message. + +Please note that calling pa_sink_render() might take some time to compute because it involves asking every connected stream for data, resampling that and finally mixing it. Usually this operation takes more or less the same time. Unless of course the number of attached streams changes. I have no clear guideline what should be done in the driver in such a case. To avoid buffer underruns you might hook into the PA_SINK_MESSAGE_ADD_INPUT message which is sent to the pa_asyncmsgq everytime a new stream is connected to a sink and than practively enlarge the playback fragment sizes if required. This works only of course when the underlying driver supports that. If the fragment size is fixed then it might make sense to calculate the current CPU load of the RT thread and estimating for the case when the new thread is added. If it appears to be near 1 than it might be a better idea to refuse the new stream. The entirely handling of this needs to be fledged out a little bit more. Comments welcome. + +Memory management in PA should be done in a zero-copy way. I.e. instead of passing around data and copying it from memory buffer to memory buffer we just pass around pointers to memory. In PA this is encapsulated by a pa_memblock, which is reference counted and should stay immutable after initialization. A ring buffer in PA terms is just a linked list of pointers to the real data (called a pa_memblockq). You can send pa_memblocks through pa_asyncmsgqs. Please do not use the oh-so-famed JACK ringbuffer for this buffer. Besides the fact that the JACK ringbuffer is borked (misuse of "volatile", missing memory barriers) it also involves copy operations which we don't want in our zero-copy PA. Please note that allocation/deconstruction of pa_memblock is lock-free and thread-safe. However, access to pa_memblockqs is NOT thread-safe. In several modules you'll find that the RT thread manages a pa_memblockq and writes pa_memblocks it receives via pa_asyncmsgq to it. That's the way it should be done. + +Please note that to get to the actual data of a pa_memblock you have to call pa_memblock_acquire(). After accessing it you need to call pa_memblock_release(). This is required in some places to safely know when we can swap the actual data pointer in the pa_memblock. It is not a lock or anything, just a very simple atomic operation. + +Please make sure to always have a matching pa_memblock_release() for each pa_memblock_acquire()! And also to have a matching pa_memblock_unref() for each pa_memblock_ref()! + +Please note that malloc() and free() are usually not lock-free (oh, and even GSlice and stuff is not lock-free when the thread allocating the block and the one freeing it is not the same). Thus it is best to not use them from the RT thread during runtime. In many cases you can do this by calling them exclusively in the setup and construction functions. If this is not possible you should be using a pa_flist, a lock-free, thread-safe free()-list implementation. There is even a static version of this around that is used in several locations, such as the pa_hashmap implementation. To be really efficient and to guarantee lock-freeness in all cases this data structure needs to be "prefilled" with a set of memory object. Something which we don't do yet. But we'll add this in the future. + +Yes, of course we could use some real guaranteed-to-be-lock-free malloc() implementation. But as of now I don't know any free enough implementation without major drawbacks. The free-list solution should be good enough for the time being. + +We don't do mlock()'ing yet. Something else that we might add eventually. It is questionnable anyway if mlock()ing all memory the RT threads ever touches make sense. If there is memory pressure on the system audio is usually not the most important part that should not get paged out. Most code and data accessed in the RT thread should be "hot" anyway, so no need for mlock() protection. And for the few cases where data that might get accessed from the RT thread might indeed have been paged out it probably makes sense to call pa_memblock_will_need() or pa_memchunk_will_need() from the main event loop (which will tell the kernel to page in that specific block of memory) before passing it to the RT thread. + +Yepp, this documentation is very terse and very rough. And also everything is still in flux. Hence, in case of questions: ping me on #pulseaudio, or read the source. Or better even: do both! + +**Oh, this page is a wiki, so feel welcome to update it! ** + + +## Reference Counting + +A few rules for reference counting: + +* Increasing the refcounter should be done by a _ref() function, decreasing with _unref() +* Refcount only the pointers that point from the longer-living object to the shorter-living object - NOT the other way round! +* Provide an _unlink() method on the short-living object that deregisters the object from the longer-living object and also unlinks every attached shorter-living object. This should not be confused with _unref() +* Only use refcounting as defined in [source:src/pulsecore/refcnt.h refcnt.h] or by pa_object, because this one is guaranteed to be atomic. +Yes, not all code currently in PA abides to these rules, but this is being worked on. e.g. a couple of functions that should be called _unlink() are called _disconnect() right now. + + +## Atomicity and Memory Barriers + +Since PA now uses a (mostly) lock-free core, we provide a set of atomic integer and pointer routines in form of pa_atomic_xxx() (defined in [source:src/pulsecore/atomic.h atomic.h]). They include full implicit memory barriers, which allows you to forget about memory access ordering issues on SMP -- as long as you do use pa_atomic_xxx(). + +Besides that, the pa_thread_xxx thread creation/termination APIs, pa_semaphore_xxx and pa_mutex_xxx provide implicit full memory barriers. Everything that is built on top of these building blocks, such as pa_asyncmsgq thus also includes implicit memory barriers. + +So, to avoid race conditions in your code, make sure to use the existing APIs and you should be able to forget about memory barriers. It is always preferable to implement algorithms lock-free. However, very often this is very difficult to get right, if possible at all. In those cases, a good solution is usually to leave the actual work on a complex data structure to the rt thread and to request it via a message on a pa_asyncmsgq (Of course only if the actual processing of this stuff is not tooo difficult, i.e. has a low complexity). Also, keeping everything lock-free is not worth it in many cases. So please, if you feel that some algorithm is best implemented with taking a lock, than just do it and don't feel bad about it. We have the pa_mutex_xxx APIs for these cases! + +pa_semaphore_post() does not require taking a lock. Hence in many cases, it is better to use pa_semaphores over pa_cond. + +Don't bother with implementing your own lock-free reference counting based directly on pa_atomic_xxx(). Instead, use the refcnt.h API mentioned above, or use pa_object. + +Nota bene: all our memory barriers are _full_ memory barriers. The most important architectures are x86/x86-64 where only this type of barriers exists. Since only very few people fully understand the differences between all the barriers, and we have no access to more exotic architectures the full memory barriers must suffice for our uses. diff --git a/Software/PulseAudio/Documentation/Developer/Threading/PulseThreads.png b/Software/PulseAudio/Documentation/Developer/Threading/PulseThreads.png Binary files differnew file mode 100644 index 00000000..1c12d1ab --- /dev/null +++ b/Software/PulseAudio/Documentation/Developer/Threading/PulseThreads.png diff --git a/Software/PulseAudio/Documentation/Developer/Threading/PulseThreads.svg b/Software/PulseAudio/Documentation/Developer/Threading/PulseThreads.svg new file mode 100644 index 00000000..7255df2b --- /dev/null +++ b/Software/PulseAudio/Documentation/Developer/Threading/PulseThreads.svg @@ -0,0 +1,1327 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<!-- Created with Inkscape (http://www.inkscape.org/) --> + +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + width="1052.3622" + height="744.09448" + id="svg2" + version="1.1" + inkscape:version="0.47 r22583" + sodipodi:docname="PulseThreads.svg" + inkscape:export-filename="/home/ensonic/Pictures/PulseThreads.png" + inkscape:export-xdpi="87.57" + inkscape:export-ydpi="87.57"> + <defs + id="defs4"> + <linearGradient + id="linearGradient3612"> + <stop + style="stop-color:#d2d2d2;stop-opacity:1;" + offset="0" + id="stop3614" /> + <stop + style="stop-color:#3c3c3c;stop-opacity:1;" + offset="1" + id="stop3616" /> + </linearGradient> + <inkscape:perspective + sodipodi:type="inkscape:persp3d" + inkscape:vp_x="0 : 526.18109 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_z="744.09448 : 526.18109 : 1" + inkscape:persp3d-origin="372.04724 : 350.78739 : 1" + id="perspective10" /> + <inkscape:perspective + id="perspective3683" + inkscape:persp3d-origin="0.5 : 0.33333333 : 1" + inkscape:vp_z="1 : 0.5 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 0.5 : 1" + sodipodi:type="inkscape:persp3d" /> + <linearGradient + id="linearGradient3612-6"> + <stop + style="stop-color:#d2d2d2;stop-opacity:1;" + offset="0" + id="stop3614-2" /> + <stop + style="stop-color:#3c3c3c;stop-opacity:1;" + offset="1" + id="stop3616-7" /> + </linearGradient> + <linearGradient + id="linearGradient3692"> + <stop + style="stop-color:#d2d2d2;stop-opacity:1;" + offset="0" + id="stop3694" /> + <stop + style="stop-color:#2d2d2d;stop-opacity:1;" + offset="1" + id="stop3696" /> + </linearGradient> + <inkscape:perspective + id="perspective3683-3" + inkscape:persp3d-origin="0.5 : 0.33333333 : 1" + inkscape:vp_z="1 : 0.5 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 0.5 : 1" + sodipodi:type="inkscape:persp3d" /> + <linearGradient + id="linearGradient3612-9"> + <stop + style="stop-color:#d2d2d2;stop-opacity:1;" + offset="0" + id="stop3614-20" /> + <stop + style="stop-color:#3c3c3c;stop-opacity:1;" + offset="1" + id="stop3616-0" /> + </linearGradient> + <linearGradient + id="linearGradient3692-8"> + <stop + style="stop-color:#d2d2d2;stop-opacity:1;" + offset="0" + id="stop3694-7" /> + <stop + style="stop-color:#3c3c3c;stop-opacity:1;" + offset="1" + id="stop3696-5" /> + </linearGradient> + <inkscape:perspective + id="perspective3772" + inkscape:persp3d-origin="0.5 : 0.33333333 : 1" + inkscape:vp_z="1 : 0.5 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 0.5 : 1" + sodipodi:type="inkscape:persp3d" /> + <linearGradient + id="linearGradient3612-3"> + <stop + style="stop-color:#c9c9db;stop-opacity:1;" + offset="0" + id="stop3614-8" /> + <stop + style="stop-color:#303048;stop-opacity:1;" + offset="1" + id="stop3616-75" /> + </linearGradient> + <linearGradient + id="linearGradient3781"> + <stop + style="stop-color:#d2d2d2;stop-opacity:1;" + offset="0" + id="stop3783" /> + <stop + style="stop-color:#2d2d2d;stop-opacity:1;" + offset="1" + id="stop3785" /> + </linearGradient> + <inkscape:perspective + id="perspective3868" + inkscape:persp3d-origin="0.5 : 0.33333333 : 1" + inkscape:vp_z="1 : 0.5 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 0.5 : 1" + sodipodi:type="inkscape:persp3d" /> + <linearGradient + id="linearGradient3612-9-9"> + <stop + style="stop-color:#d2d2d2;stop-opacity:1;" + offset="0" + id="stop3614-20-3" /> + <stop + style="stop-color:#2d2d2d;stop-opacity:1;" + offset="1" + id="stop3616-0-6" /> + </linearGradient> + <linearGradient + id="linearGradient3877"> + <stop + style="stop-color:#d2d2d2;stop-opacity:1;" + offset="0" + id="stop3879" /> + <stop + style="stop-color:#2d2d2d;stop-opacity:1;" + offset="1" + id="stop3881" /> + </linearGradient> + <linearGradient + id="linearGradient3612-6-4"> + <stop + style="stop-color:#d2d2d2;stop-opacity:1;" + offset="0" + id="stop3614-2-1" /> + <stop + style="stop-color:#2d2d2d;stop-opacity:1;" + offset="1" + id="stop3616-7-6" /> + </linearGradient> + <linearGradient + id="linearGradient3888"> + <stop + style="stop-color:#d2d2d2;stop-opacity:1;" + offset="0" + id="stop3890" /> + <stop + style="stop-color:#2d2d2d;stop-opacity:1;" + offset="1" + id="stop3892" /> + </linearGradient> + <linearGradient + id="linearGradient3612-34"> + <stop + style="stop-color:#d2d2d2;stop-opacity:1;" + offset="0" + id="stop3614-7" /> + <stop + style="stop-color:#3c3c3c;stop-opacity:1;" + offset="1" + id="stop3616-3" /> + </linearGradient> + <linearGradient + id="linearGradient3899"> + <stop + style="stop-color:#d2d2d2;stop-opacity:1;" + offset="0" + id="stop3901" /> + <stop + style="stop-color:#2d2d2d;stop-opacity:1;" + offset="1" + id="stop3903" /> + </linearGradient> + <inkscape:perspective + id="perspective4016" + inkscape:persp3d-origin="0.5 : 0.33333333 : 1" + inkscape:vp_z="1 : 0.5 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 0.5 : 1" + sodipodi:type="inkscape:persp3d" /> + <linearGradient + id="linearGradient3612-34-9"> + <stop + style="stop-color:#d2d2d2;stop-opacity:1;" + offset="0" + id="stop3614-7-8" /> + <stop + style="stop-color:#3c3c3c;stop-opacity:1;" + offset="1" + id="stop3616-3-6" /> + </linearGradient> + <linearGradient + id="linearGradient4025"> + <stop + style="stop-color:#d2d2d2;stop-opacity:1;" + offset="0" + id="stop4027" /> + <stop + style="stop-color:#2d2d2d;stop-opacity:1;" + offset="1" + id="stop4029" /> + </linearGradient> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient3612-3" + id="linearGradient4272" + gradientUnits="userSpaceOnUse" + gradientTransform="matrix(2.7264958,0,0,7.3877553,101.77384,-2285.3247)" + x1="155.66031" + y1="439.56476" + x2="155.66031" + y2="357.87357" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient3612-3" + id="linearGradient4274" + gradientUnits="userSpaceOnUse" + gradientTransform="matrix(2.7264958,0,0,7.3877553,101.77384,-2285.3247)" + x1="155.66031" + y1="357.87357" + x2="155.66031" + y2="439.56476" /> + <inkscape:perspective + id="perspective4284" + inkscape:persp3d-origin="0.5 : 0.33333333 : 1" + inkscape:vp_z="1 : 0.5 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 0.5 : 1" + sodipodi:type="inkscape:persp3d" /> + <linearGradient + id="linearGradient3612-37"> + <stop + style="stop-color:#cbdbc9;stop-opacity:1;" + offset="0" + id="stop3614-3" /> + <stop + style="stop-color:#334830;stop-opacity:1;" + offset="1" + id="stop3616-8" /> + </linearGradient> + <linearGradient + id="linearGradient3692-8-1"> + <stop + style="stop-color:#d2d2d2;stop-opacity:1;" + offset="0" + id="stop3694-7-6" /> + <stop + style="stop-color:#3c3c3c;stop-opacity:1;" + offset="1" + id="stop3696-5-6" /> + </linearGradient> + <inkscape:perspective + id="perspective4355" + inkscape:persp3d-origin="0.5 : 0.33333333 : 1" + inkscape:vp_z="1 : 0.5 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 0.5 : 1" + sodipodi:type="inkscape:persp3d" /> + <linearGradient + id="linearGradient3612-34-4"> + <stop + style="stop-color:#dbc9d8;stop-opacity:1;" + offset="0" + id="stop3614-7-0" /> + <stop + style="stop-color:#483044;stop-opacity:1;" + offset="1" + id="stop3616-3-1" /> + </linearGradient> + <linearGradient + id="linearGradient4364"> + <stop + style="stop-color:#d2d2d2;stop-opacity:1;" + offset="0" + id="stop4366" /> + <stop + style="stop-color:#3c3c3c;stop-opacity:1;" + offset="1" + id="stop4368" /> + </linearGradient> + <inkscape:perspective + id="perspective4413" + inkscape:persp3d-origin="0.5 : 0.33333333 : 1" + inkscape:vp_z="1 : 0.5 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 0.5 : 1" + sodipodi:type="inkscape:persp3d" /> + <linearGradient + id="linearGradient3612-37-2"> + <stop + style="stop-color:#dbc9d8;stop-opacity:1;" + offset="0" + id="stop3614-3-3" /> + <stop + style="stop-color:#483044;stop-opacity:1;" + offset="1" + id="stop3616-8-2" /> + </linearGradient> + <linearGradient + id="linearGradient3692-8-1-2"> + <stop + style="stop-color:#d2d2d2;stop-opacity:1;" + offset="0" + id="stop3694-7-6-3" /> + <stop + style="stop-color:#3c3c3c;stop-opacity:1;" + offset="1" + id="stop3696-5-6-0" /> + </linearGradient> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient3612-37-2" + id="linearGradient4486" + gradientUnits="userSpaceOnUse" + gradientTransform="matrix(0.51282049,0,0,5.040816,393.41167,-1300.7095)" + x1="155.66031" + y1="439.56476" + x2="155.66031" + y2="357.87357" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient3692-8-1-2" + id="linearGradient4488" + gradientUnits="userSpaceOnUse" + gradientTransform="matrix(0.51282049,0,0,5.040816,393.41167,-1300.7095)" + x1="155.66031" + y1="357.87357" + x2="155.66031" + y2="439.56476" /> + <inkscape:perspective + id="perspective4498" + inkscape:persp3d-origin="0.5 : 0.33333333 : 1" + inkscape:vp_z="1 : 0.5 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 0.5 : 1" + sodipodi:type="inkscape:persp3d" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient3612-34-4-2" + id="linearGradient4475-7" + gradientUnits="userSpaceOnUse" + gradientTransform="translate(493.47523,168.56065)" + x1="155.66031" + y1="439.56476" + x2="155.66031" + y2="357.87357" /> + <linearGradient + id="linearGradient3612-34-4-2"> + <stop + style="stop-color:#dbc9d8;stop-opacity:1;" + offset="0" + id="stop3614-7-0-0" /> + <stop + style="stop-color:#483044;stop-opacity:1;" + offset="1" + id="stop3616-3-1-3" /> + </linearGradient> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient3612-34-4-2" + id="linearGradient4477-9" + gradientUnits="userSpaceOnUse" + gradientTransform="translate(493.47523,168.56065)" + x1="155.66031" + y1="357.87357" + x2="155.66031" + y2="439.56476" /> + <linearGradient + id="linearGradient4507"> + <stop + style="stop-color:#dbc9d8;stop-opacity:1;" + offset="0" + id="stop4509" /> + <stop + style="stop-color:#483044;stop-opacity:1;" + offset="1" + id="stop4511" /> + </linearGradient> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient3612-34-9" + id="linearGradient4555" + gradientUnits="userSpaceOnUse" + gradientTransform="translate(773.74618,498.49951)" + x1="155.66031" + y1="439.56476" + x2="155.66031" + y2="357.87357" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient3612-34-9" + id="linearGradient4557" + gradientUnits="userSpaceOnUse" + gradientTransform="translate(773.74618,498.49951)" + x1="155.66031" + y1="357.87357" + x2="155.66031" + y2="439.56476" /> + <inkscape:perspective + id="perspective4577" + inkscape:persp3d-origin="0.5 : 0.33333333 : 1" + inkscape:vp_z="1 : 0.5 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 0.5 : 1" + sodipodi:type="inkscape:persp3d" /> + <linearGradient + y2="357.87357" + x2="155.66031" + y1="439.56476" + x1="155.66031" + gradientTransform="translate(497.64052,492.41066)" + gradientUnits="userSpaceOnUse" + id="linearGradient4516-9" + xlink:href="#linearGradient3612-34-4-2-9" + inkscape:collect="always" /> + <linearGradient + id="linearGradient3612-34-4-2-9"> + <stop + style="stop-color:#dbc9d8;stop-opacity:1;" + offset="0" + id="stop3614-7-0-0-1" /> + <stop + style="stop-color:#483044;stop-opacity:1;" + offset="1" + id="stop3616-3-1-3-4" /> + </linearGradient> + <linearGradient + y2="439.56476" + x2="155.66031" + y1="357.87357" + x1="155.66031" + gradientTransform="translate(497.64052,492.41066)" + gradientUnits="userSpaceOnUse" + id="linearGradient4518-6" + xlink:href="#linearGradient3612-34-4-2-9" + inkscape:collect="always" /> + <linearGradient + id="linearGradient4586"> + <stop + style="stop-color:#dbc9d8;stop-opacity:1;" + offset="0" + id="stop4588" /> + <stop + style="stop-color:#483044;stop-opacity:1;" + offset="1" + id="stop4590" /> + </linearGradient> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient3612-34-4-2" + id="linearGradient4627" + gradientUnits="userSpaceOnUse" + gradientTransform="translate(497.64052,492.41066)" + x1="155.66031" + y1="439.56476" + x2="155.66031" + y2="357.87357" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient3612-34-4-2" + id="linearGradient4629" + gradientUnits="userSpaceOnUse" + gradientTransform="translate(497.64052,492.41066)" + x1="155.66031" + y1="357.87357" + x2="155.66031" + y2="439.56476" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient3612-34-4" + id="linearGradient4631" + gradientUnits="userSpaceOnUse" + gradientTransform="translate(493.47523,168.56065)" + x1="155.66031" + y1="439.56476" + x2="155.66031" + y2="357.87357" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient3612-34-4" + id="linearGradient4633" + gradientUnits="userSpaceOnUse" + gradientTransform="translate(493.47523,168.56065)" + x1="155.66031" + y1="357.87357" + x2="155.66031" + y2="439.56476" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient3612-37" + id="linearGradient4635" + gradientUnits="userSpaceOnUse" + gradientTransform="matrix(0.51282049,0,0,5.040816,260.22995,-1281.0959)" + x1="155.66031" + y1="439.56476" + x2="155.66031" + y2="357.87357" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient3692-8-1" + id="linearGradient4637" + gradientUnits="userSpaceOnUse" + gradientTransform="matrix(0.51282049,0,0,5.040816,260.22995,-1281.0959)" + x1="155.66031" + y1="357.87357" + x2="155.66031" + y2="439.56476" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient3612-34" + id="linearGradient4639" + gradientUnits="userSpaceOnUse" + gradientTransform="translate(773.74618,167.34371)" + x1="155.66031" + y1="439.56476" + x2="155.66031" + y2="357.87357" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient3612-34" + id="linearGradient4641" + gradientUnits="userSpaceOnUse" + gradientTransform="translate(773.74618,167.34371)" + x1="155.66031" + y1="357.87357" + x2="155.66031" + y2="439.56476" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient3612-9" + id="linearGradient4643" + gradientUnits="userSpaceOnUse" + gradientTransform="translate(-17.81035,495.55413)" + x1="155.66031" + y1="439.56476" + x2="155.66031" + y2="357.87357" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient3612-9" + id="linearGradient4645" + gradientUnits="userSpaceOnUse" + gradientTransform="translate(-17.81035,495.55413)" + x1="155.66031" + y1="357.87357" + x2="155.66031" + y2="439.56476" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient3612-6" + id="linearGradient4647" + gradientUnits="userSpaceOnUse" + gradientTransform="translate(-21.10386,330.30434)" + x1="155.66031" + y1="439.56476" + x2="155.66031" + y2="357.87357" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient3612-6" + id="linearGradient4649" + gradientUnits="userSpaceOnUse" + gradientTransform="translate(-21.10386,330.30434)" + x1="155.66031" + y1="357.87357" + x2="155.66031" + y2="439.56476" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient3612" + id="linearGradient4651" + gradientUnits="userSpaceOnUse" + gradientTransform="translate(-26.82594,165.05461)" + x1="155.66031" + y1="439.56476" + x2="155.66031" + y2="357.87357" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient3692-8" + id="linearGradient4653" + gradientUnits="userSpaceOnUse" + gradientTransform="translate(-26.82594,165.05461)" + x1="155.66031" + y1="357.87357" + x2="155.66031" + y2="439.56476" /> + <inkscape:perspective + id="perspective4663" + inkscape:persp3d-origin="0.5 : 0.33333333 : 1" + inkscape:vp_z="1 : 0.5 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 0.5 : 1" + sodipodi:type="inkscape:persp3d" /> + <linearGradient + id="linearGradient3612-4"> + <stop + style="stop-color:#d2d2d2;stop-opacity:1;" + offset="0" + id="stop3614-5" /> + <stop + style="stop-color:#3c3c3c;stop-opacity:1;" + offset="1" + id="stop3616-5" /> + </linearGradient> + <linearGradient + id="linearGradient3692-8-11"> + <stop + style="stop-color:#d2d2d2;stop-opacity:1;" + offset="0" + id="stop3694-7-3" /> + <stop + style="stop-color:#3c3c3c;stop-opacity:1;" + offset="1" + id="stop3696-5-3" /> + </linearGradient> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient3612-4" + id="linearGradient4713" + gradientUnits="userSpaceOnUse" + gradientTransform="matrix(0.63247862,0,0,0.53061223,-16.22058,814.77174)" + x1="155.66031" + y1="439.56476" + x2="155.66031" + y2="357.87357" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient3692-8-11" + id="linearGradient4715" + gradientUnits="userSpaceOnUse" + gradientTransform="matrix(0.63247862,0,0,0.53061223,-16.22058,814.77174)" + x1="155.66031" + y1="357.87357" + x2="155.66031" + y2="439.56476" /> + <inkscape:perspective + id="perspective4730" + inkscape:persp3d-origin="0.5 : 0.33333333 : 1" + inkscape:vp_z="1 : 0.5 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 0.5 : 1" + sodipodi:type="inkscape:persp3d" /> + <linearGradient + id="linearGradient3612-4-9"> + <stop + style="stop-color:#cfdbc9;stop-opacity:1;" + offset="0" + id="stop3614-5-0" /> + <stop + style="stop-color:#394830;stop-opacity:1;" + offset="1" + id="stop3616-5-2" /> + </linearGradient> + <linearGradient + id="linearGradient3692-8-11-4"> + <stop + style="stop-color:#d2d2d2;stop-opacity:1;" + offset="0" + id="stop3694-7-3-1" /> + <stop + style="stop-color:#3c3c3c;stop-opacity:1;" + offset="1" + id="stop3696-5-3-0" /> + </linearGradient> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient3612-4-9" + id="linearGradient4780" + gradientUnits="userSpaceOnUse" + gradientTransform="matrix(0.63247862,0,0,0.53061223,120.56713,814.44883)" + x1="155.66031" + y1="439.56476" + x2="155.66031" + y2="357.87357" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient3692-8-11-4" + id="linearGradient4782" + gradientUnits="userSpaceOnUse" + gradientTransform="matrix(0.63247862,0,0,0.53061223,120.56713,814.44883)" + x1="155.66031" + y1="357.87357" + x2="155.66031" + y2="439.56476" /> + <inkscape:perspective + id="perspective4851" + inkscape:persp3d-origin="0.5 : 0.33333333 : 1" + inkscape:vp_z="1 : 0.5 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 0.5 : 1" + sodipodi:type="inkscape:persp3d" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient3612-4-9-2" + id="linearGradient4780-6" + gradientUnits="userSpaceOnUse" + gradientTransform="matrix(0.63247862,0,0,0.53061223,120.56713,814.44883)" + x1="155.66031" + y1="439.56476" + x2="155.66031" + y2="357.87357" /> + <linearGradient + id="linearGradient3612-4-9-2"> + <stop + style="stop-color:#dbc9d8;stop-opacity:1;" + offset="0" + id="stop3614-5-0-1" /> + <stop + style="stop-color:#483044;stop-opacity:1;" + offset="1" + id="stop3616-5-2-9" /> + </linearGradient> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient3692-8-11-4-6" + id="linearGradient4782-6" + gradientUnits="userSpaceOnUse" + gradientTransform="matrix(0.63247862,0,0,0.53061223,120.56713,814.44883)" + x1="155.66031" + y1="357.87357" + x2="155.66031" + y2="439.56476" /> + <linearGradient + id="linearGradient3692-8-11-4-6"> + <stop + style="stop-color:#d2d2d2;stop-opacity:1;" + offset="0" + id="stop3694-7-3-1-5" /> + <stop + style="stop-color:#3c3c3c;stop-opacity:1;" + offset="1" + id="stop3696-5-3-0-0" /> + </linearGradient> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient3612-4-9-2" + id="linearGradient4901" + gradientUnits="userSpaceOnUse" + gradientTransform="matrix(0.63247862,0,0,0.53061223,258.06249,815.14521)" + x1="155.66031" + y1="439.56476" + x2="155.66031" + y2="357.87357" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient3692-8-11-4-6" + id="linearGradient4903" + gradientUnits="userSpaceOnUse" + gradientTransform="matrix(0.63247862,0,0,0.53061223,258.06249,815.14521)" + x1="155.66031" + y1="357.87357" + x2="155.66031" + y2="439.56476" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient3612-9" + id="linearGradient3007" + gradientUnits="userSpaceOnUse" + gradientTransform="matrix(1,0,0,2.0696187,-17.81035,5.9222303)" + x1="155.66031" + y1="439.56476" + x2="155.66031" + y2="357.87357" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient3612-9" + id="linearGradient3009" + gradientUnits="userSpaceOnUse" + gradientTransform="matrix(1,0,0,2.0696187,-17.81035,5.9222303)" + x1="155.66031" + y1="357.87357" + x2="155.66031" + y2="439.56476" /> + <inkscape:perspective + id="perspective3019" + inkscape:persp3d-origin="0.5 : 0.33333333 : 1" + inkscape:vp_z="1 : 0.5 : 1" + inkscape:vp_y="0 : 1000 : 0" + inkscape:vp_x="0 : 0.5 : 1" + sodipodi:type="inkscape:persp3d" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient3612-34-4-7" + id="linearGradient4631-7" + gradientUnits="userSpaceOnUse" + gradientTransform="translate(493.47523,168.56065)" + x1="155.66031" + y1="439.56476" + x2="155.66031" + y2="357.87357" /> + <linearGradient + id="linearGradient3612-34-4-7"> + <stop + style="stop-color:#dbc9d8;stop-opacity:1;" + offset="0" + id="stop3614-7-0-6" /> + <stop + style="stop-color:#483044;stop-opacity:1;" + offset="1" + id="stop3616-3-1-4" /> + </linearGradient> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient3612-34-4-7" + id="linearGradient4633-3" + gradientUnits="userSpaceOnUse" + gradientTransform="translate(493.47523,168.56065)" + x1="155.66031" + y1="357.87357" + x2="155.66031" + y2="439.56476" /> + <linearGradient + id="linearGradient3028"> + <stop + style="stop-color:#dbc9d8;stop-opacity:1;" + offset="0" + id="stop3030" /> + <stop + style="stop-color:#483044;stop-opacity:1;" + offset="1" + id="stop3032" /> + </linearGradient> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient3612-34-4-7" + id="linearGradient3072" + gradientUnits="userSpaceOnUse" + gradientTransform="matrix(0.85470085,0,0,1,-110.36973,505.32553)" + x1="155.66031" + y1="439.56476" + x2="155.66031" + y2="357.87357" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient3612-34-4-7" + id="linearGradient3074" + gradientUnits="userSpaceOnUse" + gradientTransform="matrix(0.85470085,0,0,1,-110.36973,505.32553)" + x1="155.66031" + y1="357.87357" + x2="155.66031" + y2="439.56476" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient3612-34-4-7" + id="linearGradient3115" + gradientUnits="userSpaceOnUse" + gradientTransform="matrix(0.85470085,0,0,1,-110.36973,505.32553)" + x1="155.66031" + y1="439.56476" + x2="155.66031" + y2="357.87357" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient3612-34-4-7" + id="linearGradient3117" + gradientUnits="userSpaceOnUse" + gradientTransform="matrix(0.85470085,0,0,1,-110.36973,505.32553)" + x1="155.66031" + y1="357.87357" + x2="155.66031" + y2="439.56476" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient3612-9" + id="linearGradient3131" + gradientUnits="userSpaceOnUse" + gradientTransform="matrix(1,0,0,2.0696187,-17.81035,5.9222303)" + x1="155.66031" + y1="439.56476" + x2="155.66031" + y2="357.87357" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient3612-9" + id="linearGradient3133" + gradientUnits="userSpaceOnUse" + gradientTransform="matrix(1,0,0,2.0696187,-17.81035,5.9222303)" + x1="155.66031" + y1="357.87357" + x2="155.66031" + y2="439.56476" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient3612-34-4-7" + id="linearGradient3135" + gradientUnits="userSpaceOnUse" + gradientTransform="matrix(0.85470085,0,0,1,-110.36973,505.32553)" + x1="155.66031" + y1="439.56476" + x2="155.66031" + y2="357.87357" /> + <linearGradient + inkscape:collect="always" + xlink:href="#linearGradient3612-34-4-7" + id="linearGradient3137" + gradientUnits="userSpaceOnUse" + gradientTransform="matrix(0.85470085,0,0,1,-110.36973,505.32553)" + x1="155.66031" + y1="357.87357" + x2="155.66031" + y2="439.56476" /> + </defs> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + inkscape:pageopacity="1" + inkscape:pageshadow="2" + inkscape:zoom="0.60725336" + inkscape:cx="324.86431" + inkscape:cy="362.87729" + inkscape:document-units="px" + inkscape:current-layer="layer1" + showgrid="false" + inkscape:window-width="1234" + inkscape:window-height="770" + inkscape:window-x="0" + inkscape:window-y="24" + inkscape:window-maximized="0" + showguides="true" + inkscape:guide-bbox="true" /> + <metadata + id="metadata7"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + <dc:title /> + </cc:Work> + </rdf:RDF> + </metadata> + <g + inkscape:label="Layer 1" + inkscape:groupmode="layer" + id="layer1" + transform="translate(0,-308.2677)"> + <g + id="g4164" + transform="translate(0,-20)"> + <rect + ry="0.5" + rx="0.38513514" + y="523.42816" + x="32.498981" + height="80.691193" + width="192.67081" + id="rect2818" + style="opacity:0.9;fill:url(#linearGradient4651);fill-opacity:1;stroke:url(#linearGradient4653);stroke-width:3;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <text + id="text2820" + y="578.68585" + x="70.26992" + style="font-size:40px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + style="font-size:40px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;font-family:Sans;-inkscape-font-specification:Sans" + y="578.68585" + x="70.26992" + id="tspan2822" + sodipodi:role="line">Client</tspan></text> + </g> + <g + id="g4204" + transform="translate(0,-60)"> + <rect + ry="0.5" + rx="0.38513514" + y="688.67792" + x="38.221062" + height="80.691193" + width="192.67081" + id="rect2818-7" + style="opacity:0.9;fill:url(#linearGradient4647);fill-opacity:1;stroke:url(#linearGradient4649);stroke-width:3;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <text + id="text2820-5" + y="743.93561" + x="75.991997" + style="font-size:40px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + style="font-size:40px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;font-family:Sans;-inkscape-font-specification:Sans" + y="743.93561" + x="75.991997" + id="tspan2822-1" + sodipodi:role="line">Client</tspan></text> + </g> + <rect + style="opacity:0.9;fill:url(#linearGradient4272);fill-opacity:1;stroke:url(#linearGradient4274);stroke-width:3.00000024;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + id="rect2818-9" + width="525.31616" + height="596.12671" + x="263.52301" + y="362.25159" + rx="0.38513511" + ry="0.50000006" /> + <text + xml:space="preserve" + style="font-size:40px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans" + x="325.66351" + y="429.03665" + id="text2820-3"><tspan + sodipodi:role="line" + id="tspan2822-8" + x="325.66351" + y="429.03665" + style="font-size:40px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;font-family:Sans;-inkscape-font-specification:Sans">PulseAudio Daemon</tspan></text> + <g + id="g4228" + transform="translate(0,-20)"> + <rect + ry="0.5" + rx="0.38513514" + y="525.71729" + x="833.07111" + height="80.691193" + width="192.67081" + id="rect2818-1" + style="opacity:0.9;fill:url(#linearGradient4639);fill-opacity:1;stroke:url(#linearGradient4641);stroke-width:3;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <text + id="text2820-6" + y="580.97498" + x="844.98267" + style="font-size:40px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + style="font-size:40px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;font-family:Sans;-inkscape-font-specification:Sans" + y="580.97498" + x="844.98267" + id="tspan2822-0" + sodipodi:role="line">SndCard</tspan></text> + </g> + <g + id="g4240" + transform="translate(0,-26)"> + <rect + ry="0.5" + rx="0.38513514" + y="856.87311" + x="833.07111" + height="80.691193" + width="192.67081" + id="rect2818-1-3" + style="opacity:0.9;fill:url(#linearGradient4555);fill-opacity:1;stroke:url(#linearGradient4557);stroke-width:3;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <text + id="text2820-6-0" + y="912.1308" + x="844.98267" + style="font-size:40px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + style="font-size:40px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;font-family:Sans;-inkscape-font-specification:Sans" + y="912.1308" + x="844.98267" + id="tspan2822-0-3" + sodipodi:role="line">SndCard</tspan></text> + </g> + <g + id="g4342" + transform="translate(0,-20)"> + <rect + ry="0.49999997" + rx="0.38513514" + y="525.39929" + x="290.65298" + height="406.74945" + width="98.805534" + id="rect2818-40" + style="opacity:0.9;fill:url(#linearGradient4635);fill-opacity:1;stroke:url(#linearGradient4637);stroke-width:3;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <text + transform="matrix(0,-1,1,0,0,0)" + id="text2820-0" + y="351.09091" + x="-807.0553" + style="font-size:40px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + style="font-size:40px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;font-family:Sans;-inkscape-font-specification:Sans" + y="351.09091" + x="-807.0553" + id="tspan2822-7" + sodipodi:role="line">libpulse</tspan></text> + </g> + <g + id="g4564" + transform="translate(0,-20)"> + <rect + ry="0.5" + rx="0.38513514" + y="526.9342" + x="552.80017" + height="80.691193" + width="192.67081" + id="rect2818-1-7" + style="opacity:0.9;fill:url(#linearGradient4631);fill-opacity:1;stroke:url(#linearGradient4633);stroke-width:3;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <text + id="text2820-6-3" + y="577.96338" + x="572.32892" + style="font-size:40px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + style="font-size:40px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;font-family:Sans;-inkscape-font-specification:Sans" + y="577.96338" + x="572.32892" + id="tspan2822-0-0" + sodipodi:role="line">IO Loop</tspan></text> + </g> + <rect + style="opacity:0.9;fill:url(#linearGradient4486);fill-opacity:1;stroke:url(#linearGradient4488);stroke-width:3;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + id="rect2818-40-7" + width="98.805534" + height="406.74945" + x="423.83472" + y="505.78564" + rx="0.38513514" + ry="0.49999997" /> + <text + xml:space="preserve" + style="font-size:40px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans" + x="-803.73267" + y="484.27264" + id="text2820-0-5" + transform="matrix(0,-1,1,0,0,0)"><tspan + sodipodi:role="line" + id="tspan2822-7-3" + x="-803.73267" + y="484.27264" + style="font-size:40px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;font-family:Sans;-inkscape-font-specification:Sans">Main Loop</tspan></text> + <g + transform="translate(13.756022,-32.503287)" + id="g4559-3"> + <rect + ry="0.5" + rx="0.38513514" + y="850.78424" + x="556.96545" + height="80.691193" + width="192.67081" + id="rect2818-1-7-6-6" + style="opacity:0.9;fill:url(#linearGradient4516-9);fill-opacity:1;stroke:url(#linearGradient4518-6);stroke-width:3;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <text + id="text2820-6-3-0-8" + y="899.81342" + x="576.4942" + style="font-size:40px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + style="font-size:40px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;font-family:Sans;-inkscape-font-specification:Sans" + y="899.81342" + x="576.4942" + id="tspan2822-0-0-2-5" + sodipodi:role="line">IO Loop</tspan></text> + </g> + <g + id="g4559" + transform="translate(0,-20)"> + <rect + ry="0.5" + rx="0.38513514" + y="850.78424" + x="556.96545" + height="80.691193" + width="192.67081" + id="rect2818-1-7-6" + style="opacity:0.9;fill:url(#linearGradient4627);fill-opacity:1;stroke:url(#linearGradient4629);stroke-width:3;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <text + id="text2820-6-3-0" + y="899.81342" + x="576.4942" + style="font-size:40px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + style="font-size:40px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;font-family:Sans;-inkscape-font-specification:Sans" + y="899.81342" + x="576.4942" + id="tspan2822-0-0-2" + sodipodi:role="line">IO Loop</tspan></text> + </g> + <g + id="g4717"> + <rect + ry="0.5" + rx="0.38513517" + y="1004.9291" + x="21.301165" + height="42.815735" + width="121.86017" + id="rect2818-2" + style="opacity:0.9;fill:url(#linearGradient4713);fill-opacity:1;stroke:url(#linearGradient4715);stroke-width:3;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <text + id="text2820-9" + y="1031.8545" + x="49.609177" + style="font-size:40px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + style="font-size:20px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;font-family:Sans;-inkscape-font-specification:Sans" + y="1031.8545" + x="49.609177" + id="tspan2822-2" + sodipodi:role="line">Things</tspan></text> + </g> + <g + id="g4838"> + <rect + ry="0.5" + rx="0.38513517" + y="1004.6061" + x="158.08887" + height="42.815735" + width="121.86017" + id="rect2818-2-9" + style="opacity:0.9;fill:url(#linearGradient4780);fill-opacity:1;stroke:url(#linearGradient4782);stroke-width:3;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <text + id="text2820-9-9" + y="1033.304" + x="204.10196" + style="font-size:40px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + style="font-size:20px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;font-family:Sans;-inkscape-font-specification:Sans" + y="1033.304" + x="204.10196" + id="tspan2822-2-9" + sodipodi:role="line">API</tspan></text> + </g> + <g + id="g4905"> + <rect + ry="0.5" + rx="0.38513517" + y="1005.3025" + x="295.58423" + height="42.815735" + width="121.86017" + id="rect2818-2-9-2" + style="opacity:0.9;fill:url(#linearGradient4901);fill-opacity:1;stroke:url(#linearGradient4903);stroke-width:3;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <text + id="text2820-9-9-0" + y="1034.1664" + x="316.82196" + style="font-size:40px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + style="font-size:20px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;font-family:Sans;-inkscape-font-specification:Sans" + y="1034.1664" + x="316.82196" + id="tspan2822-2-9-2" + sodipodi:role="line">Threads</tspan></text> + </g> + <g + id="g3121" + transform="translate(0,-4)"> + <rect + ry="0.5" + rx="0.38513514" + y="747.61896" + x="41.514572" + height="167" + width="192.67081" + id="rect2818-4" + style="opacity:0.9;fill:url(#linearGradient3131);fill-opacity:1;stroke:url(#linearGradient3133);stroke-width:3;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" /> + <text + id="text2820-50" + y="801.18542" + x="79.285507" + style="font-size:40px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans" + xml:space="preserve"><tspan + style="font-size:40px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;font-family:Sans;-inkscape-font-specification:Sans" + y="801.18542" + x="79.285507" + id="tspan2822-4" + sodipodi:role="line">Client</tspan></text> + <g + transform="translate(115.17667,-41.168978)" + id="g3109"> + <rect + style="opacity:0.9;fill:url(#linearGradient3135);fill-opacity:1;stroke:url(#linearGradient3137);stroke-width:3;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none" + id="rect2818-1-7-3" + width="164.6759" + height="80.691193" + x="-59.664646" + y="863.6991" + rx="0.38513514" + ry="0.5" /> + <text + xml:space="preserve" + style="font-size:28px;font-style:normal;font-weight:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Bitstream Vera Sans" + x="-47.969273" + y="894.26929" + id="text2820-6-3-09"><tspan + sodipodi:role="line" + id="tspan2822-0-0-25" + x="-47.969273" + y="894.26929" + style="font-size:28px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;font-family:Sans;-inkscape-font-specification:Sans">Threaded</tspan><tspan + sodipodi:role="line" + x="-47.969273" + y="929.26929" + style="font-size:28px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;font-family:Sans;-inkscape-font-specification:Sans" + id="tspan3076">Main Loop</tspan></text> + </g> + </g> + </g> +</svg> diff --git a/Software/PulseAudio/Documentation/Developer/Volumes.mdwn b/Software/PulseAudio/Documentation/Developer/Volumes.mdwn new file mode 100644 index 00000000..698f27e4 --- /dev/null +++ b/Software/PulseAudio/Documentation/Developer/Volumes.mdwn @@ -0,0 +1,59 @@ + +A little overview on the different volumes PA handles internally: + + +## pa_sink_input + +**volume** is the volume that is visible to the user. In classic volume mode this is relative to the current sink volume. In flat volume mode it is absolute, i.e. in the same units/range as the sink's volume. + +**volume_factor** is an internal volume factor that can be used by effect modules to apply additional software volume adjustments to a stream. Primary user for now is module-position-event-sounds. + +**reference_ratio** is the ratio of the sink input's volume to the sink's reference volume. + +**real_ratio** is the ratio of the sink input's volume to sink's real volume. + +**soft_volume** is an internal volume calculated as the multiplication of **real_ratio** by **volume_factor**. It is as such the actual factor applied on the PCM data of this stream. + + +## pa_sink + +**reference_volume** is the volume that is visible to the user. Saved/restored stream volumes are relative to this. + +**real_volume** is the volume the hardware is actually configured to. This is always lower or equal than the reference volume. In flat volume mode this equals the highest volume of all streams. In non-flat volume mode this equals the reference volume. + +**base_volume** is an informational value that stores where a 'good' virtual volume level is for the device. Depending on the backend drivers this might be set to something < 0dB but most often is 0dB. This value stays constant and may not be modified. + +**soft_volume** is an internal volume that is applied to the PCM data before it is handed out to the device. For devices lacking hw volume control this is used to apply volumes. Also, on devices that do dB based volumes this is used to extend the volume range. + + +## Formulas + +Object _i_ shall be a pa_sink_input, object _s_ a pa_sink. + + +[[!format txt """ +i->soft_volume := i->real_ratio * i->volume_factor +"""]] +This is always true: + + +[[!format txt """ +i->real_ratio <= i->reference_ratio +s->real_volume <= s->reference_volume +"""]] +In flat volume mode: + + +[[!format txt """ +i->real_ratio := i->real_volume / s->volume +i->reference_ratio := i->reference_volume / s->volume + +s->real_volume = MAX(i->volume for all i of s) +"""]] +In classic volume mode: +[[!format txt """ +i->real_ratio := i->volume +i->reference_ratio := i->volume + +s->real_volume := s->reference_volume +"""]]
\ No newline at end of file diff --git a/Software/PulseAudio/Documentation/User.mdwn b/Software/PulseAudio/Documentation/User.mdwn new file mode 100644 index 00000000..1c66de11 --- /dev/null +++ b/Software/PulseAudio/Documentation/User.mdwn @@ -0,0 +1,58 @@ + +[[!inline pages="Software/PulseAudio/TOC" quick="yes" raw="yes"]] [[↩ Back to Documentation|Software/PulseAudio/Documentation]] + + +# Documentation + + +## First Steps + +If you are new to [[PulseAudio|PulseAudio]], consider reading about the [[first steps|Software/PulseAudio/Documentation/User/FirstSteps]]. + + +## The Perfect Setup + +After doing your first steps with PulseAudio you might want to know everything about [[the perfect setup|Software/PulseAudio/Documentation/User/PerfectSetup]]. + + +## Network Setup + +There are several ways of controlling PulseAudio and streaming audio over the network. For a detailed description about configuring those, see [[Network Setup|Software/PulseAudio/Documentation/User/Network]]. + + +## Frequently Asked Questions + +Before asking for help on the [[mailing lists|Software/PulseAudio/Documentation/User/Community]] or on [[IRC|Software/PulseAudio/Documentation/User/Community]] make sure to consult our [[list of frequently asked questions|Software/PulseAudio/FAQ]]. + + +## Modules + +PulseAudio has whole bunch of loadable modules, each with its own set of functions and parameters. See the [[modules|Software/PulseAudio/Documentation/User/Modules]] page for a description of them all. + + +## Command Line Interface + +The PulseAudio daemon can be configured with its own [[command line language|Software/PulseAudio/Documentation/User/CLI]]. + + +## Daemon + +Read all about the [[daemon's command line parameters|Software/PulseAudio/Documentation/User/Daemon]]. + + +## Server Strings + +The syntax of server address strings understood by PulseAudio are documented [[here|Software/PulseAudio/Documentation/User/ServerStrings]]. + + +## Running PulseAudio as System-Wide Daemon + +In some setups it might be sensible to [[run PulseAudio as system-wide daemon|Software/PulseAudio/Documentation/User/SystemWide]] instead of per-user. + + +## Authentication + +PulseAudio clients can be required to authenticate them to the server they try to connect to. This can be done by cookie files, or if the native protocol is used on unix and the daemon runs in system-wide mode, by group permissions. The module module-simple-protocol-{unix,tcp} is is always open for all clients. + + +IP-based access control lists can be used, by giving certain modules arguments starting with "auth-ip-acl=" as showed on other documentation pages like [[FAQ|Software/PulseAudio/FAQ]] and [[Modules|Software/PulseAudio/Documentation/User/Modules]]. diff --git a/Software/PulseAudio/Documentation/User/Audiophile.mdwn b/Software/PulseAudio/Documentation/User/Audiophile.mdwn new file mode 100644 index 00000000..1accb9ef --- /dev/null +++ b/Software/PulseAudio/Documentation/User/Audiophile.mdwn @@ -0,0 +1,16 @@ + +Desktop users, or other curious folks, may be interested in configuring [[PulseAudio|PulseAudio]] to best reproduce sound that they have on their hard drives. In order to do so it requires both the right hardware and right [[PulseAudio|PulseAudio]] settings. + +=Hardware= The best hardware for desktops for stereo audio is the ASUS Xonar Essense [[ST|http://www.asus.com/Multimedia/Audio_Cards/Xonar_Essence_ST/]] (PCI) or [[STX|http://www.asus.com/Multimedia/Audio_Cards/Xonar_Essence_STX/]] (PCI-Express). It provides the best, consumer-level Digital to Analog conversion circuitry and shielding to prevent erroneous noise. [citation needed] + +=[[PulseAudio|PulseAudio]]= By default, [[PulseAudio|PulseAudio]] (PA) uses very conservative settings. This will work fine for most audio media as you will most likely have 44,100Hz sample rate files. However, if you have higher sample rate recordings it is recommended that you increase the sample rate that PA uses. + +In /etc/pulse/daemon.conf add: default-sample-format = s32le default-sample-rate = 96000 + +Resampling your 44,100Hz media may be an issue with the above settings so you can increase the resampler quality from the PA default. + +In /etc/pulse/daemon.conf add: resample-method = speex-float-5 + +For the most geniune resampling at the cost of high CPU usage (even on 2011 CPUs) you can add: resample-method = src-sinc-best-quality + +=Enhancements= [[PulseAudio|PulseAudio]] could be enhanced to make some of this a bit easier. It could open a channel for each sample rate to provide bit-perfect playback of any sample of audio media. diff --git a/Software/PulseAudio/Documentation/User/CLI.mdwn b/Software/PulseAudio/Documentation/User/CLI.mdwn new file mode 100644 index 00000000..fa2a6d3f --- /dev/null +++ b/Software/PulseAudio/Documentation/User/CLI.mdwn @@ -0,0 +1,7 @@ + +[[!inline pages="Software/PulseAudio/TOC" quick="yes" raw="yes"]] + + +# Simple Command Line Language + +(To avoid maintaining the documentation in two places, the contents of this page have been removed. The documentation is maintained as a man page, see "man pulse-cli-syntax".) diff --git a/Software/PulseAudio/Documentation/User/Community.mdwn b/Software/PulseAudio/Documentation/User/Community.mdwn new file mode 100644 index 00000000..396dffa7 --- /dev/null +++ b/Software/PulseAudio/Documentation/User/Community.mdwn @@ -0,0 +1,83 @@ + +[[!inline pages="Software/PulseAudio/TOC" quick="yes" raw="yes"]] + + +# PulseAudio Community + + +## Mailing Lists + +Please join our [[mailing list|http://lists.freedesktop.org/mailman/listinfo/pulseaudio-discuss]]. (Posting requires subscription) + +You can subscribe to GIT changes on [[pulseaudio-commits|http://lists.freedesktop.org/mailman/listinfo/pulseaudio-commits]]. (No posting allowed) + +You can subscribe to Bugzilla Bug/Trac Ticket changes on [[pulseaudio-bugs|http://lists.freedesktop.org/mailman/listinfo/pulseaudio-bugs]]. (No posting allowed) + + +## IRC + +You have a chance to meet the developers on [[[irc://irc.freenode.org/pulseaudio|irc://irc.freenode.org/pulseaudio]] #pulseaudio on irc.freenode.org]. + + +## Tracking + +[[PulseAudio on CIA|http://cia.navi.cx/stats/project/polypaudio]] (CIA hasn't been reconfigured yet after the recent project name change) + +[[PulseAudio on Freshmeat|http://freshmeat.net/projects/pulseaudio/]] (If you want to be notified whenever a new version of [[PulseAudio|PulseAudio]] is released, consider subscribing here) + +[[PulseAudio on SWIK|http://swik.net/pulseaudio]] + +[[PulseAudio on Ohloh|http://www.ohloh.net/projects/4038]] (Don't forget to give us kudos!) [[OhlohBadge(4038)|OhlohBadge(4038)]] + + +## Bugs, Patches & Translations + +**Bugs** are reported in freedesktop.org's [[Bugzilla|https://bugs.freedesktop.org/enter_bug.cgi?product=PulseAudio]]. See also the list of [[open bugs in Bugzilla|https://bugs.freedesktop.org/buglist.cgi?quicksearch=product%3APulseAudio]]. Also, there might be a chance that the bug you want to report is not actually one. For those we have prepared a list of **[[canned responses|CannedResponses]]**. Please check this list before filing a bug because otherwise you might find your bug closed quickly with a reference to one of the items of that list. Because of heavy spamming, you have to be logged in to the freedesktop.org Bugzilla to create and modify bugs. + +**Important:** If you are encountering a **crash**, please make sure to provide a **stack trace** when you file a bug. The various distributions usually provide documentation how you do this best. Here are the guides for [[Fedora|http://fedoraproject.org/wiki/StackTraces]], [[Mandriva|http://wiki.mandriva.com/en/Development/Howto/Software_Crash]] and [[Ubuntu|https://wiki.ubuntu.com/Backtrace]]. Also, make sure to include the verbose output of PA when this problem happens. For that run "pulseaudio -vvvvv" in a terminal and try to reproduce your issue. You might need to stop a running PA first by issuing "pulseaudio -k". If autospawning is enabled (which it now is by default) you might have to race against it when restarting PA, so it might be a good idea to issue "pulseaudio -k ; pulseaudio -vvvvv" in a single command and try a few times. Usually that should work well enough to win the race. If it doesn't, adding "autospawn=no" to ~/.config/pulse/client.conf will disable autospawning. + +**Important:** If you are using **Ubuntu** [[please read this before filing a bug|http://pulseaudio.org/wiki/UbuntuBugs]]. + +Below is a rough outline of how a stack trace can be acquired with gdb: +[[!format txt """ +$ LD_BIND_NOW=1 gdb pulseaudio +>> run -vvvvv +>> ... +>> *** crash *** +>> thread apply all bt full +>> ... +>> *** etc. etc. *** +"""]] +Before posting a bug report you might want to check [[this list of broken ALSA sound drivers|Software/PulseAudio/Backends/ALSA/BrokenDrivers]]. (might be out of date) + +If you are encountering a CPU load issue, [[make sure to read this|Software/PulseAudio/Documentation/Developer/CPULoad]]. + +If you want to complain about PulseAudio's **mixer handling**, [[read this first!|Software/PulseAudio/Documentation/User/PulseAudioStoleMyVolumes]] If you want to complain about **memory consumption** [[read this first!|Software/PulseAudio/Documentation/User/MemoryConsumption]] If you want to complain that PA doesn't honour your **default device** choices, [[read this first!|Software/PulseAudio/Documentation/User/DefaultDevice]] Other **canned responsed** [[you find in this list.|CannedResponses]] + +**Patches** are preferably submitted to the mailing list, ideally using `git send-email` ([[instructions here|Software/PulseAudio/HowToUseGitSendEmail]]). It's ok send patches also by filing a bug and attaching the patch there, but the mailing list is the preferred way. Patches should be made against the current Git master branch. Before submitting patches please read through our [[coding style guidelines|Software/PulseAudio/Documentation/Developer/CodingStyle]]. + +**Translations** <del>shall be submitted via **[[Transifex|http://www.transifex.net/projects/p/pulseaudio/c/master-tx/]]**. This will commit your translations directly to our GIT repository and lessen our burden to merge patches. Please note that translations submitted by other means (bug tickets, mailed patches) will be ignored (or closed as "wontfix" in the case of bug tickets). You don't need an [[PulseAudio|PulseAudio]] BTS user account if you want to submit translations this way.</del> Currently Transiflex integration is [[not hooked up|https://bugs.freedesktop.org/show_bug.cgi?id=45524]]. Until this situation changes, please [[open a bug|https://bugs.freedesktop.org/enter_bug.cgi?product=PulseAudio]] and attach your patch against latest git. Please include _i18n_ in the keywords section. + + +## People + +PulseAudio has been developed by: + +* **[[Lennart Poettering|http://0pointer.de/lennart/]]** (mezcalero) through his employer **[[Red Hat|http://redhat.com]]** +* **[[Pierre Ossman|http://drzeus.cx/]]** (ossman, DrZeus) through his employer **[[Cendio|http://www.cendio.com]]** +* **[[Colin Guthrie|http://colin.guthr.ie/]]** (coling) +* **[[Arun Raghavan|http://arunraghavan.net/]]** (Ford_Prefect) through his employer **[[Collabora|http://www.collabora.com/]]** +* **Tanu Kaskinen** (tanuk) through his employer **[[Intel|http://intel.com]]** +* **[[David Henningsson|http://voices.canonical.com/david.henningsson/]]** (diwic) through his employer **[[Canonical|http://www.canonical.com/]]** +The following people have also made contributions (this list isn't really maintained at all): + +* **Jeff Waugh** - Initial Ubuntu/Debian packages +* **Miguel Freitas** - Xine driver +* **Joe Marcus Clarke**, **Diego Pettenó** - Porting to FreeBSD +* **Sebastien Estienne** - Testing +* **Igor Zubkov** - Some portability patches and packages for ALT Linux Sisyphus +* **Jan Schmidt** - Some latency interpolation love +* **Shahms E. King** (shahms) +And a lot of other folks. Consult git for a complete list of contributors. + +The PulseAudio logo has been designed by **Pierre Ossman** and **Rafael Jannone**. diff --git a/Software/PulseAudio/Documentation/User/Daemon.mdwn b/Software/PulseAudio/Documentation/User/Daemon.mdwn new file mode 100644 index 00000000..bccd37ce --- /dev/null +++ b/Software/PulseAudio/Documentation/User/Daemon.mdwn @@ -0,0 +1,83 @@ + +[[!inline pages="Software/PulseAudio/TOC" quick="yes" raw="yes"]] + + +# Daemon + + +## Command Line Arguments + +The PulseAudio daemon accepts several command line arguments: + + +[[!format txt """ +COMMANDS: + -h, --help Show this help + --version Show version + --dump-conf Dump default configuration + --dump-modules Dump list of available modules + -k --kill Kill a running daemon + --check Check for a running daemon + +OPTIONS: + --system[=BOOL] Run as system-wide instance + -D, --daemonize[=BOOL] Daemonize after startup + --fail[=BOOL] Quit when startup fails + --verbose[=BOOL] Be slightly more verbose + --high-priority[=BOOL] Try to set high process priority + (only available as root) + --disallow-module-loading[=BOOL] Disallow module loading after startup + --exit-idle-time=SECS Terminate the daemon when idle and this + time passed + --module-idle-time=SECS Unload autoloaded modules when idle and + this time passed + --scache-idle-time=SECS Unload autoloaded samples when idle and + this time passed + --log-level[=LEVEL] Increase or set verbosity level + -v Increase the verbosity level + --log-target={auto,syslog,stderr} Specify the log target + -p, --dl-search-path=PATH Set the search path for dynamic shared + objects (plugins) + --resample-method=[METHOD] Use the specified resampling method + (one of src-sinc-medium-quality, + src-sinc-best-quality,src-sinc-fastest + src-zero-order-hold,src-linear,trivial) + --use-pid-file[=BOOL] Create a PID file + +STARTUP SCRIPT: + -L, --load="MODULE ARGUMENTS" Load the specified plugin module with + the specified argument + -F, --file=FILENAME Run the specified script + -C Open a command line on the running TTY + after startup + + -n Don't load default script file +"""]] + +### Example + +It is a good idea to run the daemon like this: + + +[[!format txt """ +pulseaudio -D +"""]] +This will run `/etc/pulse/default.pa` after startup. This should be a script written in the [[CLI language|Software/PulseAudio/Documentation/User/CLI]]. + + +## Signals + +The following signals are trapped specially: + +SIGINT + + * The daemon is shut down cleanly. +SIGUSR1 + + * The daemon tries to load the module `module-cli`, effectively providing a command line interface on the calling TTY. +SIGUSR2 + + * The daemon tries to load the module `module-cli-protocol-unix`, effectively providing a command line interface on a special UNIX domain socket. +SIGHUP + + * The daemon logs the current server layout.
\ No newline at end of file diff --git a/Software/PulseAudio/Documentation/User/DefaultDevice.mdwn b/Software/PulseAudio/Documentation/User/DefaultDevice.mdwn new file mode 100644 index 00000000..960e57ea --- /dev/null +++ b/Software/PulseAudio/Documentation/User/DefaultDevice.mdwn @@ -0,0 +1,42 @@ + + +# Default devices + + +## The difference between "default" and "fallback" + +Standard PulseAudio setup doesn't really have a concept of a "default" device. Whenever a new stream appears, PulseAudio's stream-restore module checks if the same stream has been seen before, and if it is, then the stream is connected to the same sink or source where it was previously. There is a concept of a "fallback" device, which is used if the stream has not been seen before. + + +## How to set the fallback device + +The fallback sink and source can be set with pavucontrol or pacmd, or configured in /etc/pulse/default.pa. + +Setting the device with pavucontrol happens in the "Output Devices" and "Input Devices" tabs by checking the "Default" or "Fallback" (depending on pavucontrol version) item in a device's menu. + +The pacmd commands are +[[!format txt """ +pacmd set-default-sink <sink index or sink name> +pacmd set-default-source <source index or source name> +"""]] +Similarly the lines to put to /etc/pulse/default.pa are +[[!format txt """ +set-default-sink <sink index or sink name> +set-default-source <source index or source name> +"""]] + +## How to set the default device + +If you, for example, plug in a new sound card and want it to be the default device from now on, you can tell PulseAudio to change the fallback sink to the new sound card, but that will only have effect on programs that PulseAudio hasn't seen before. For this particular use case the current (as of 2010-01-23) state-of-the-art method to move everything to the new sound card is to use gnome-volume-control version 2.28, which modifies the stream-restore database when you set some device as the default. + +The second alternative is to use pavucontrol to move streams to the new sound card whenever you notice that some program is playing to a wrong sound card. + +The third alternative is to first set the fallback device, then stop PulseAudio, then erase the stream-restore database by deleting the file containing the string "stream-volumes" in its name in the ~/.pulse directory, and finally restarting PulseAudio. + +There is also the fourth option to make default sink and source to work to all applications by disabling stream target device reading from the stream cache. Simply modify the `load-module module-stream-restore` line that should already be in your /etc/pulse/default.pa, so that it looks like this: +[[!format txt """ +load-module module-stream-restore restore_device=false +"""]] +Then restart PulseAudio. + +Now all opened streams will open to default sink or source even in the case that there is a record in the stream-volumes for the stream. Now you can plug an USB audio device and set it as default sink and source and all opened streams (new and or already seen) will go to the new device. Only streams that are open need to be moved by pavucontrol or re-opened. diff --git a/Software/PulseAudio/Documentation/User/Equalizer.mdwn b/Software/PulseAudio/Documentation/User/Equalizer.mdwn new file mode 100644 index 00000000..61b0e2ac --- /dev/null +++ b/Software/PulseAudio/Documentation/User/Equalizer.mdwn @@ -0,0 +1,123 @@ + +The equalizer is available in pulseaudio's master git branch so instead of the git repository below, you may just want to compile from there. + + +## Getting the equalizer + +Binary packages are available for the following platforms:. + +**openSUSE 11.2 and factory**: + + +[[!format txt """ +http://download.opensuse.org/repositories/home://jenewton/ +"""]] +**Ubuntu 9.10**: + + +[[!format txt """ +Add the following to your sources.list: +deb http://ppa.launchpad.net/nevion/ppa/ubuntu/ karmic main +Add the following PPA key: +apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 5291C76F +You may have to force these packages to be installed (synaptic->package->force version to the jenewton build). +"""]] +Unfortunately due to dependencies within pulseaudio, older platforms are not available. + +Up to date sources are available here: +[[!format txt """ +git clone git://gitorious.org/pulseaudio-equalizer/pulseaudio-equalizer.git pulseaudio-equalizer +cd pulseaudio-equalizer && git checkout -t origin/master +"""]] + +## Getting the GUI (pqaeq): + +Note that currently, qpaeq is included in the pulseaudio source tree under src/utils and will be installed alongside the equalizer module to /usr/bin/qpaeq in most setups automatically. Qpaeq is still maintained in the below repositories, however. +[[!format txt """ +Git: git clone git://gitorious.org/qpaeq/qpaeq.git +Direct qpaeq single file download of git: http://gitorious.org/qpaeq/qpaeq/blobs/raw/master/qpaeq.py +Releaseish form here: http://sourceforge.net/projects/qpaeq/ + +"""]] +**Git versions are usually much more up to date, so give them a try first.** + + +## Compiling (for those without packages provided above) + +You will then need to install all normal pulseaudio devel dependencies and fftw3 and dbus devel packages (ex dbus-1-devel / libdbus-1-dev). I prefer a local installation but this will still overwrite your old configurations in /etc/pulse, be sure to back up! You can probably use the following commands: + + +[[!format txt """ +cd pulseaudio-equalizer.git +./autogen.sh +CFLAGS="-O0 -ggdb -mtune=native -fno-strict-aliasing" ./configure --disable-static --disable-rpath --with-system-user=pulse --with-system-group=pulse --with-access-group=pulse-access --libdir=/usr/local/lib64 --sysconfdir=/etc +make +sudo make install +sudo ldconfig +"""]] +(32bit users will want to use lib instead of lib64 in the above) + + +## Disabling tsched + +**You probably won't need to do this** but if things are messing up, it's something to try (in /etc/pulse/default.pa): + + +[[!format txt """ +### Automatically load driver modules depending on the hardware available +.ifexists module-udev-detect.so +load-module module-udev-detect tsched=0 +.else +### Alternatively use the static hardware detection module (for systems that +### lack udev support) +load-module module-detect tsched=0 +.endif +"""]] + +## Configuring + +**Update**: The module now automatically makes itself the default sink, so for most users, simply load module-dbus-protocol and module-equalizer-sink. See below for a reference snippet. + +You will need to find out the name of your current sink. You can use a gui (paman) for this or perform this command: + + +[[!format txt """ +pacmd list-sinks|grep 'name:' +"""]] +The names should be in between the < >. You will probably only have one. + +Put something **like** the following in your default.pa (a few lines are added for context): + + +[[!format txt """ +.ifexists module-esound-protocol-unix.so +load-module module-esound-protocol-unix +.endif +.ifexists module-dbus-protocol.so +load-module module-dbus-protocol +.endif +load-module module-native-protocol-unix +load-module module-equalizer-sink sink_name=equalized master=alsa_output.pci-0000_00_1b.0.analog-surround-51 set_default=true +set-default-sink equalized +"""]] +Make sure the dbus module is also loaded as above and that you replace the master=alsa part with master=YOURSINKNAME or it will use the default sink. You can set set_default=false if you do not want the new sink to be the default. + + +## GUI and Equalizing: + +You will need **python, pyqt4, and python-dbus** to launch the gui (qpaeq). Debian packages for those are **python, python-dbus, python-qt4 and python-qt4-dbus**. + +Launch the GUI via: + + +[[!format txt """ +qpaeq (if you installed from git or opensuse packages) +--or-- +python qpaeq.py +"""]] +If the frequency bands in there aren't good enough for you, add in your own (in order) inside qpaeq.py, its under the variable named DEFAULT_FREQUENCIES. Restart the gui and voilà. The equalizer also automatically subdivides frequency ranges depending on the width of the window and supports presets. + + +## Questions/Comments/Problems + +Drop phish3 a line in the irc channel on freenode or join the [[mailing list|http://pulseaudio.org/wiki/Community#MailingLists]]. diff --git a/Software/PulseAudio/Documentation/User/FirstSteps.mdwn b/Software/PulseAudio/Documentation/User/FirstSteps.mdwn new file mode 100644 index 00000000..8fce8847 --- /dev/null +++ b/Software/PulseAudio/Documentation/User/FirstSteps.mdwn @@ -0,0 +1,32 @@ + +[[!inline pages="Software/PulseAudio/TOC" quick="yes" raw="yes"]] + + +# First Steps + +Simply start the PulseAudio daemon with the argument `-nC`: + + +[[!format txt """ +pulseaudio -nC +"""]] +This will present you a screen like this: + + +[[!format txt """ +Welcome to PulseAudio! Use "help" for usage information. +>>> +"""]] +Now you can issue CLI commands as described [[here|Software/PulseAudio/Documentation/User/CLI]]. If you already have `pulseaudio` started use pacmd command to open the CLI. Another way to start `pulseaudio` is by specifying a configuration script like that one included in the distribution on the command line: + + +[[!format txt """ +pulseaudio -nF pulseaudio.pa +"""]] +This will load some drivers and protocols automatically. + +The best idea is to configure your daemon in `/etc/pulse/daemon.conf` and `/etc/pulse/default.pa` and to run `pulseaudio` without any arguments. + +**Beware! ** Unless you pass the option `--sysconfdir=/etc` to `configure`, the directory `/etc/pulse/` is really `/usr/local/etc/pulse/`. + +More information about available arguments and signals for the daemon can be found [[here|Software/PulseAudio/Documentation/User/Daemon]]. diff --git a/Software/PulseAudio/Documentation/User/MemoryConsumption.mdwn b/Software/PulseAudio/Documentation/User/MemoryConsumption.mdwn new file mode 100644 index 00000000..68225804 --- /dev/null +++ b/Software/PulseAudio/Documentation/User/MemoryConsumption.mdwn @@ -0,0 +1,17 @@ + + +# PulseAudio shows up as memory hogger in top! Why? + +When starting up PulseAudio allocates a 64 MiB shared memory segment and then for each active client another 64 MiB segment is added. For the uninitiated this might look as if PA wastes substantial amounts of memory. However this is actually not the case. And here's why: + +What PA does is allocating address space that is not actually backed with real memory. Most modern operating systems distinguish between allocation of memory and allocation of address space. Allocating address space comes at virtually no cost. When PA first uses a part of its address space, it gets backed by memory. Usually only a very small part of the address space of PA is actually used. This technique is called "memory overcommiting." + +Also note that these shared memory segments are shared between the process that allocates them and the processes that access them (due to their very nature as _shared memory_ segments). + +That means that if you just look at the amount of address space that is allocated for each process you will get a value that is substantially higher than the actual memory consumption of PA and the PA clients. Due to that tools like "top"/"ps" are not very useful to determine memory consumption of PA. This LWN article has a few hints how to better measure memory consumption: [[http://lwn.net/Articles/230975/|http://lwn.net/Articles/230975/]] + +Nevertheless, there are special cases when PA does allocate unused amounts of memory: + + 1. OS does not employ memory overcommiting. To my knowledge the only current OS that does not do overcommiting is OpenSolaris (probably because Solaris is only useful on servers and hence these machines are equipped with substantially more memory so that this limitation does not become apparent). + 1. You have the option "lock-memory = yes" in "daemon.conf". Then the address space of PA is backed with memory even if it is not used. +You may control the size of the shared memory segment by changing the "shm-size-bytes" configuration option in "daemon.conf". diff --git a/Software/PulseAudio/Documentation/User/Modules.mdwn b/Software/PulseAudio/Documentation/User/Modules.mdwn new file mode 100644 index 00000000..dae42148 --- /dev/null +++ b/Software/PulseAudio/Documentation/User/Modules.mdwn @@ -0,0 +1,778 @@ + +[[!inline pages="Software/PulseAudio/TOC" quick="yes" raw="yes"]] <span style="display:none">[[!inline pages="ModulesTOC" quick="yes" raw="yes"]]</span> [[!toc 3]] + + +# Loadable Modules + +To show all currently loaded modules with their arguments, run `pacmd` and enter the [[CLI|Software/PulseAudio/Documentation/User/CLI]] command `list-modules` . The following loadable modules are provided with the PulseAudio distribution: + + +## Device Drivers + +All device driver modules support the following parameters: + + * sink_name, source_name + * Name for the sink (resp. source). Allowed characters in the name are a-z, A-Z, numbers, period (.) and underscore (_). The length must be 1-128 characters. format + * The sample format (one of u8, s16, s16be, s16le, float32, float32be, float32le, alaw, ulaw) (defaults to s16) rate + * The sample rate (defaults to 44100) channels + * Audio channels (defaults to 2) channel_map + * Channel map. A list of comma-separated channel names. The currently defined channel names are: left, right, mono, center, front-left, front-right, front-center, rear-center, rear-left, rear-right, lfe, subwoofer, front-left-of-center, front-right-of-center, side-left, side-right, aux0, aux1 to aux15, top-center, top-front-left, top-front-right, top-front-center, top-rear-left, top-rear-right, top-rear-center, (Default depends on the number of channels and the driver) +**Since 0.9.8** + + * format + * The sample format can be signed 32 bit (s32, s32le, s32be) +**Since 0.9.15** + + * format + * The sample format can be signed 24 bit, packed in 3 or 4 bytes (s24, s24le, s24be, s24-32, s24-32le, s24-32be) +**Since 0.9.16** + + * sink_properties, source_properties + * Set additional properties of the sink/source. For example, you can set the description directly when the module is loaded by setting this parameter. + +[[!format txt """ +load-module module-alsa-sink sink_name=headphones sink_properties=device.description=Headphones +"""]] + * This is the same as using the update-sink-proplist command after the sink is setup, either with `pacmd` or in `default.pa`. + +[[!format txt """ +update-sink-proplist SINKNAME device.description="DESCRIPTION" +"""]] + +### module-pipe-sink + +Provides a simple test sink that writes the audio data to a FIFO special file in the file system. The sink name defaults to fifo_output. + +The following option is supported: + + * file + * The name of the FIFO special file to use. (defaults to: /tmp/music.output) + +### module-pipe-source + +Provides a simple test source that reads the audio data from a FIFO special file in the file system. The source name defaults to fifo_input. + +The following option is supported: + + * file + * The name of the FIFO special file to use. (defaults to: /tmp/music.input) + +### module-null-sink + +Provides a simple null sink. All data written to this sink is silently dropped. This sink is clocked using the system time. + +This module doesn't support any special parameters + + +### module-alsa-sink + +Provides a playback sink for devices supported by the Advanced Linux Sound Architecture (ALSA). The sink name defaults to alsa_output. + +You should (almost) never need to load this module manually. Let module-udev-detect look for the supported cards and then select the profile you want, that will make the right sinks show up. + +In addition to the general device driver options described above this module supports: + + * device + * The ALSA device to use. (defaults to "default") fragments + * The desired fragments when opening the device. (defaults to 12) fragment_size + * The desired fragment size in bytes when opening the device (defaults to 1024) tsched + * **Since 0.9.11.** Use system-timer based model (aka glitch-free). Defaults to 1 (enabled). If your hardware does not return accurate timing information (e.g. Creative sound cards) you can try to set tsched=0 to enable the interupt based timing which was used in 0.9.10 and before. mmap name + * String to prefix to the automatically determined sink name. device_id tsched_buffer_size, tsched_watermark ignore_dB + * Ignore dB information from the device control + * Name of mixer control namereg_fail + * Boolean deferred_volume + * Syncronize sw and hw volume changes in IO-thread fixed_latency_range + * **Since 2.0.** Boolean. Normally when there's an alsa underrun, and timer based scheduling is used, the alsa sink will raise the minimum latency that applications can get to avoid further underruns. If this option is enabled, the minimum latency will stay constant even if underruns occur. + +### module-alsa-source + +Provides a recording source for devices supported by the Advanced Linux Sound Architecture (ALSA). The source name defaults to alsa_input. + +You should (almost) never need to load this module manually. Let module-udev-detect look for the supported cards and then select the profile you want, that will make the right sources show up. + +This module supports device=, fragments=, fragment_size= and tsched= arguments the same way as module-alsa-sink. Also mmap, name, device, control, tsched_buffer_size, tsched_watermark, ignore_dB, namereg_fail, fixed_latency_range + + +### module-alsa-card + +Creates a PulseAudio card for an ALSA card. The "device_id" argument is mandatory, it tells PulseAudio which ALSA card to use. + + * card_name + * Name for the PulseAudio card. card_properties + * Extra properties to be stored in the card's property list. sink_name + * Name to be used by the card's sinks. If the card has any profiles that have multiple sinks, then this argument can't be used, because the sink names can't all be the same. sink_properties + * Extra properties to be stored in the property lists of the card's sinks. source_name + * Name to be used by the card's sources. If the card has any profiles that have multiple sources, then this argument can't be used, because the source names can't all be the same. namereg_fail + * A boolean. If "true", loading the card will fail if there already exists a card with the same name. If "false", a suffix is added to the card name if there already exists a card with the same name. profile + * The initial profile to activate when loading the module. profile_set + * Profile set configuration file. Can be an absolute path, or relative to the standard profile-sets directory. device_id + * The alsa card identifier. Can be the card index or the name. See `/proc/asound/cards` for the list of available cards and their identifiers. format + * The sample format to be used by the card's sinks and sources. rate + * The sample rate to be used by the card's sinks and sources. name + * The "device_id" argument is used by default as a part of the card name (if "card_name" is not given), and also in the card's sink and source names. If you're not happy with that for some reason, this argument can be given to be a substitute for "device_id" in the card, sink and source names. tsched + * A boolean. If "true", the sinks and sources of this card will use the timer-based scheduling. ignore_dB + * A boolean. If "true", any decibel information given by the ALSA drivers will be ignored (useful if that information is wrong). fragments + * The number of fragments to be used in the sink and source buffers. Only effective if the timer-based scheduling is disabled. fragment_size + * The size of one fragment (in bytes) to be used in the sink and source buffers. Only effective if the timer-based scheduling is disabled. mmap + * A boolean. If "true", PulseAudio will access ALSA using the mmap interface. tsched_buffer_size + * The total sink and source buffer size in bytes. Only effective if the timer-based scheduling is enabled. tsched_buffer_watermark + * The buffer fill level (in bytes) at which the sinks must refill the buffer. Only effective if the timer-based scheduling is enabled. deferred_volume + * A boolean. If "true", PulseAudio will slightly delay hardware volume changes in order to synchronize the changes with software volume changes. fixed_latency_range + * A boolean. Normally when there's an alsa underrun or overrun, and timer-based scheduling is used, the alsa sink or source will raise the minimum latency that applications can get to avoid further underruns or overruns. If this option is enabled, the minimum latency will stay constant even if underruns or overruns occur. use_ucm + * A boolean. If "true", the card will use the ALSA Use Case Manager interface for configuration, if it's available. If "false", or if there's no UCM configuration for the card, PulseAudio's own profile and path configuration files will be used instead. + +### module-oss + +Provides both a sink and a source for playback, resp. recording on Open Sound System (OSS) compatible devices. This module supports the following options: + + * record, playback + * Accepts a boolean value for enabling the playback, resp. recording on this device. (defaults: to 1) device + * The OSS device to use. (defaults to /dev/dsp), mmap + * Accepts a boolean value for enabling (resp. disabling) memory mapped (mmap()) access to the input/output buffers of the audio device. This provides better latency behaviour but is less compatible. (defaults: to 1). fragments, fragment_size + * As in module-alsa-sink. +The sink name (resp. source name) defaults to oss_output (resp. oss_input). + + +### module-solaris + +Provides a sink and source for the Solaris audio device. + +In addition to the general device driver options described above this module supports: + + * record, playback + * Accepts a boolean value for enabling the playback, resp. recording on this device. (defaults: to 1) device + * Audio device filename buffer_length + * Record buffer length in ms. + +### module-waveout + +Provides both a sink and source for the Win32 audio device. This module supports the following options: + + * record, playback + * Accepts a boolean value for enabling the playback, resp. recording on this device. (defaults: to 1) device + * Accepts an integer specifying the Windows audio device to be opened. If not set the [[WaveMapper|WaveMapper]] service is used. fragments, fragment_size + * As in module-alsa-sink. +The sink name (resp. source name) defaults to wave_output (resp. wave_input). + + +### module-combine + +Renamed to module-combine-sink in 1.0. See [[module-combine-sink|Software/PulseAudio/Documentation/User/Modules]] for the documentation for this module. + + +### module-combine-sink + +**Since 1.0 (prior to 1.0 this same module was available with name "module-combine").** This combines two or more sinks into one. A new virtual sink is allocated. All data written to it is forwarded to all connected sinks. In equidistant intervals the sample rates of the output sinks is recalculated: i.e. even when the sinks' crystals deviate (which is normally the case) output appears synchronously to the human ear. The resampling required for this may be very CPU intensive. + + * sink_name + * The name for the combined sink. (defaults to "combined") sink_properties + * **Since 0.9.15.** Property list for the combined sink. slaves + * Name of sinks to link into the combined think, separated by commas. adjust_time + * Time in seconds when to readjust the sample rate of all sinks. Zero means that readjustment should be disabled. Default: 10. resample_method + * Resampling algorithm to use when adjusting to the sample rate differences between the slave sinks. TODO: Create a page, and add a link to it here, that explains all the different resamplers that are available. While waiting for that to happen, users can refer to `man pulse-daemon.conf`, more specifically the `resample-method` option documentation. format, rate, channels, channel_map + * Parameters for the combined sink. See the [[Device Drivers section|Software/PulseAudio/Documentation/User/Modules]] at the top of this page for details. + +### module-remap-sink + +**Since 0.9.7.** This allows one to route streams' channels to arbitrary channels in a sink, for example to route stereo streams to rear channels. One common use case is to use one surround sound card as multiple virtual stereo cards. + +In order to configure the remapped sink, you'll have to decide two things: what channels the new sink will accept, and where each of them will be relayed to. + + * sink_name + * The name for the new virtual sink. master + * The name of the sink of which channels you're remapping. channels + * Channel count of the new sink. channel_map + * List of the channels that this sink will accept. master_channel_map + * The channels in the master sink, where the channels listed in channel_map will be relayed to. channel_map and master_channel_map must have equal number of channels listed, because the channels will be mapped based on their position in the list, i.e. the first channel in channel_map will be relayed to the first channel in master_channel_map and so on. remix + * Allow remixing of the mono or stereo streams to multiple channels (default is yes; set to "no" if you don't want the stereo stream to be up-mixed to all channels except subwoofer and channels named aux0-aux15). +An example to split a surround sound card to two stereo devices (remember to disable automatic device configuration first, by commenting out `module-udev-detect` and `module-detect`): + + +[[!format txt """ +# Use aux channels so that the channels won't be used for anything +# else than the rear_stereo sink. +load-module module-alsa-sink sink_name=front_stereo device=hw:0 channels=4 channel_map=front-left,front-right,aux0,aux1 + +load-module module-remap-sink sink_name=rear_stereo master=front_stereo channels=2 master_channel_map=aux0,aux1 channel_map=front-left,front-right +"""]] +<a name="module-tunnel"></a> +### module-tunnel-{sink,source} + +Tunnel a remote sink/source to a local "ghost" sink/source. Requires a running PulseAudio daemon on the remote server with module-native-protocol-tcp loaded. See [[Network Setup|Software/PulseAudio/Documentation/User/Network]] for reasons on whether to use a tunnel or direct connection to the remote server. + + * server + * The server to connect to source + * The source on the remote server. Only available for module-tunnel-source. sink + * The sink on the remote server. Only available for module-tunnel-sink. cookie + * The authentication cookie file to use. + +### module-esound-sink + +Create a playback sink using an ESOUND server as backend. Whenever you can, try to omit this module since it has many disadvantages including bad latency and even worse latency measurement. + +This module lacks the channel_map argument. + + * server + * The server to connect to cookie + * The authentication cookie file to use. + +## Protocols + + +### module-cli + +Provides the user with a simple [[command line interface|Software/PulseAudio/Documentation/User/CLI]] on the controlling TTY of the daemon. This module may not be loaded more than once. + + * exit_on_eof + * Accepts a binary numerical argument specifying whether the daemon should exit after an EOF was received from STDIN (default: 0) +<a name="module-cli-protocol"></a> +### module-cli-protocol-{unix,tcp} + +An implementation of a simple [[command line based protocol|Software/PulseAudio/Documentation/User/CLI]] for controlling the PulseAudio daemon. If loaded, the user may connect with tools like `netcat`, `telnet` or `bidilink` to the listening sockets and execute commands the same way as with module-cli. + +**Beware:** Users are not authenticated when connecting to this service. + +This module exists in two versions: with the suffix -unix the service will listen on an UNIX domain socket in the local file system. With the suffix -tcp it will listen on a network transparent TCP/IP socket. (Both IPv6 and IPv4 - if available) + +This module supports the following options: + + * port (only for -tcp) + * The port number to listen on (defaults to 4712) loopback (only for -tcp) + * **Removed in 0.9.3**: Accepts a numerical binary value. If 1 the socket is bound to the loopback device, i.e. not publicly accessible. (defaults to 1) listen (only for -tcp) + * The IP address to listen on. If specified, supersedes the value specified in loopback= socket (only for -unix) + * The UNIX socket name (defaults to /tmp/pulse/cli) +<a name="module-simple-protocol"></a> +### module-simple-protocol-{unix,tcp} + +An implementation of a simple protocol which allows playback by using simple tools like netcat. Just connect to the listening socket of this module and write the audio data to it, or read it from it for playback, resp. recording. + +**Beware!** Users are not authenticated when connecting to this service. + +See module-cli-protocol-{unix,tcp} for more information about the two possible suffixes of this module. + +In addition to the options supported by module-cli-protocol-*, this module supports: + + * rate, format, channels + * Sample format for streams connecting to this service. playback, record + * Enable/disable playback/recording sink, source + * Specify the sink/source this service connects to +<a name="module-esound-protocol"></a> +### module-esound-protocol-{unix,tcp} + +An implementation of a protocol compatible with the Enlightened Sound Daemon (ESOUND, esd). When you load this module you may access the PulseAudio daemon with tools like esdcat, esdrec or even esdctl. Many applications, such as XMMS, include support for this protocol. + +See module-cli-protocol-{unix,tcp} for more information about the two possible suffixes of this module. + +In addition to the options supported by module-cli-protocol-*, this module supports: + + * sink, source + * Specify the sink/source this service connects to auth-anonymous + * If set to 1 no authentication is required to connect to the service auth-cookie + * **New in 0.9.12:** Name of the cookie file for authentication purposes. Defaults to ".esd_auth". The homedir of the user running pulse is automatically prepended to non-absolute paths. auth-cookie-enabled + * **New in 0.9.12:** enable/disable auth-cookie authentication, takes a boolean value (0 or 1). Defaults to 1. cookie + * The old name for auth-cookie. Don't use this, it's only here for compatibility with versions before 0.9.12. auth-ip-acl (only for -tcp} + * **New in 0.9.3:** A semicolon separated list of IP address range to which anonymous access is allowed. Example: _auth-ip-acl=10.11.12.13;192.168.50.0/24;127.0.0.0/8_ +<a name="module-native-protocol"></a> +### module-native-protocol-{unix,tcp} + +The native protocol of PulseAudio. + +See module-cli-protocol-{unix,tcp} for more information about the two possible suffixes of this module. + +In addition to the options supported by module-cli-protocol-*, this module supports: + + * auth-anonymous + * If set to 1 no authentication is required to connect to the service auth-group (only for -unix) + * members of the specified unix group may access the server without further authentication. **Changed in 0.9.3:** if the daemon is running in system-wide mode (`--system` passed when starting up) defaults to `pulse-access`, otherwise is disabled. auth-group-enable (only for -unix) + * **New in 0.9.3:** enable/disable auth-group authentication, takes a boolean value (0 or 1). If `auth-group=` is specified or started in system-wide mode defaults to 1, otherwise 0. auth-cookie + * **New in 0.9.12:** Name of the cookie file for authentication purposes. Defaults to ".pulse-cookie". The homedir of the user running pulse is automatically prepended to non-absolute paths. auth-cookie-enabled + * **New in 0.9.12:** enable/disable auth-cookie authentication, takes a boolean value (0 or 1). Defaults to 1. cookie + * The old name for auth-cookie. Don't use this, it's only here for compatibility with versions before 0.9.12. auth-ip-acl (only for -tcp} + * **New in 0.9.3:** A semicolon separated list of IP address range to which anonymous access is allowed. Example: _auth-ip-acl=10.11.12.13;192.168.50.0/24;127.0.0.0/8_ + +### module-native-protocol-fd + +This is used internally when auto spawning a new daemon. Don't use it directly. + + +### module-http-protocol-tcp + +A proof-of-concept HTTP module, which can be used to introspect the current status of the PulseAudio daemon using HTTP. Just load this module and point your browser to [[http://localhost:4714/|http://localhost:4714/]]. This module takes the same arguments as module-cli-protocol-tcp. + + +## Saving/restoring settings + + +### module-default-device-restore + +**Since 0.9.7.** Automatically restore the default sink and source (configuration is saved in a file) + + +### module-card-restore + +Automatically restore profile of cards. + + +### module-device-restore + +**Since 0.9.11.** Automatically restore the volume/mute state of devices (configuration is saved in a GDBM database) + + * restore_volume + * Restore volume (default to true) restore_muted + * Restore mute state (default to true) +**Since 0.9.16** + + * restore_port + * Restore port (default to true) + +### module-stream-restore + +**Since 0.9.11.** Automatically restore the volume/mute/device state of streams (configuration is saved in a GDBM database) + + * restore_volume + * Restore volume (default to true) restore_muted + * Restore mute state (default to true) restore_device + * Restore the selected sink/source (default to true) on_hotplug + * **Since 0.9.16.** Recheck streams when new device becomes available. (default to true) on_rescue + * **Since 0.9.16.** Recheck streams when device becomes unavailable. (default to true) fallback_table + * **Since 2.0.** File name for a fallback table, containing stream-restore entries (with volume only). The file name can be absolute or relative to the configuration directory. When module-stream-restore is loaded, each fallback entry is saved to the database if that entry didn't already exist. The original purpose was to have a way to configure initial volumes for streams already before the first boot. If this argument is not specified, "stream-restore.table" will be loaded if it happens to exist (by default it doesn't). The file format is explained in the [[example file|http://cgit.freedesktop.org/pulseaudio/pulseaudio/tree/doc/stream_restore_fallback_table_example.table]]. + +### module-device-manager + +**Since 0.9.20.** Implement a history of devices and a per-role device priority list routing scheme. This module was primary written to enable the routing system employed in KDE to work at a lower level. It is conditionally loaded via the start-pulsaudio-kde script which only runs when working with KDE sessions. The longer term goal for this module is for the functionality to be integrated into PA more fully. See Software/PulseAudio/RFC/PriorityRouting + + * do_routing + * Enable the routing mode. + +## X Window System + + +### module-x11-bell + +Intercepts X11 bell events and plays a sample from the sample cache on each occurence. + + * display + * X11 display to connect to. If ommited defaults to the value of $DISPLAY sample + * The sample to play. If omitted defaults to x11-bell. Note that this is not a file name, but a name that is given to the sample when the sample is loaded. This module doesn't load any sample itself. Instead, use load-sample with pacmd or in default.pa. sink + * Name of the sink to play the sample on. If omitted defaults to the default sink. + +### module-x11-publish + +Publishes the access credentials to the PulseAudio server in the X11 root window. The following properties are used: PULSE_SERVER, POYLP_SINK, PULSE_SOURCE, PULSE_COOKIE. This is very useful when using SSH or any other remote login tool for logging into other machines and getting audio playback to your local speakers. The PulseAudio client libraries make use of this data automatically. Instead of using this module you may use the tool pax11publish which may be used to access, modify and import credential data from/to the X11 display. + + * display + * X11 display to connect to. If omitted defaults to the value of $DISPLAY sink + * Name of the default sink. If omitted this property isn't stored in the X11 display. source + * Name of the default source. If omitted this property isn't stored in the X11 display. cookie + * Name of the cookie file of the cookie to store in the X11 display. If omitted the cookie of an already loaded protocol module is used. + +### module-x11-xsmp + +**Since 0.9.7.** Register to the X11 session manager + + * session_manager + * Session manager to connect to. If omitted defaults to the value of $SESSION_MANAGER display + * X11 display to connect to. If omitted defaults to the value of $DISPLAY + +## Volume Control + +Common options to both modules + + * sink + * The sink to control +**Since 1.0** + + * volume_limit + * Volume limit. volume_step + * Volume change step size + +### module-mmkbd-evdev + +Adjust the volume of a sink when the special multimedia buttons of modern keyboards are pressed. + + * device + * Linux input device ("evdev", defaults to /dev/input/event0) + +### module-lirc + +Adjust the volume of a sink when the volume buttons of an infrared remote control are pressed (through LIRC). + + * config + * The LIRC configuration file appname + * The application name to pass to LIRC (defaults to PulseAudio) +Here is a sample _~/.lircrc_ entry configured to forward signals to PulseAudio. Note that you may have to change the button names (Vol_Up, Vol_Down...) to match those in your _/etc/lirc/lircd.conf_. +[[!format txt """ +begin + prog = PulseAudio + remote = * + button = Vol_Up + config = volume-up + repeat = 5 +end + +begin + prog = PulseAudio + remote = * + button = Vol_Down + config = volume-down + repeat = 5 +end + +begin + prog = PulseAudio + remote = * + button = Mute + config = mute-toggle +end +"""]] +Available _config_s include: _volume-up_, _volume-down_, _mute_, _mute-toggle_ and _reset_. + + +## Bluetooth + + +### module-bluetooth-discover + +Detects available bluetooth audio devices using BlueZ. For each audio device, a module-bluetooth-device instance is loaded automatically. + +Some hardware uses alsa devices for the SCO link (used by the HSP/HFP and HFGW profiles). This is called the "SCO over PCM" mode. For such hardware, the alsa sink and source need to be specified with the "sco_sink" and "sco_source" arguments. + + * sco_sink + * Name of the alsa sink that should be used in the "SCO over PCM" mode. sco_source + * Name of the alsa source that should be used in the "SCO over PCM" mode. + +### module-bluetooth-device + +Creates a card for a bluetooth audio device. Normally module-bluetooth-device instances should be automatically loaded by module-bluetooth-discover, but it's also possible to load module-bluetooth-device manually. + +The module needs to be given an identifier for the device so that it knows what device to talk to. Either the device address (such as 00:1E:DE:29:B7:3B) or the D-Bus object path (such as /org/bluez/2613/hci0/dev_00_1E_DE_29_B7_3B) can be used as the identifier. So, it's mandatory to give the "address" or the "path" argument when loading the module. + + * sink_name, source_name, card_name + * The name for the sink/source/card. sink_properties, source_properties, card_properties + * Extra properties for the sink/source/card. name + * Automatic name prefix address + * The device address. profile + * The initial card profile: "a2dp", "a2dp_source", "hsp", "hfgw" or "off". path + * The D-Bus object path of the device. auto_connect + * Boolean, the default value is "true". What does this option do?? sco_sink, sco_source + * See the documentation of module-bluetooth-discover. + +### module-bluetooth-policy + +Takes care of any bluetooth specific policy. Currently two features are implemented: + +* Switch the card profile automatically to "hfgw" or "a2dp_source" when the remote end starts playing audio. +* Load module-loopback automatically for A2DP and HFGW sources, so that the received audio is automatically played back to some output. +Supported arguments: + + * a2dp_source + * A boolean argument controlling whether the module-loopback loading should be enabled for A2DP sources. hfgw + * A boolean argument controlling whether the module-loopback loading should be enabled for HFGW sources. + +### module-bluetooth-proximity + +**Since 0.9.11** Bluetooth proximity volume control + + * sink + * The sink to adjust the volume hci + * hci device + +## RTP/SDP/SAP Transport + +PulseAudio can stream audio data to an IP multicast group via the standard protocols RTP, SAP and SDP (RFC3550, RFC3551, RFC2327, RFC2327). This can be used for multiple different purposes: for sharing a single microphone on multiple computers on the local LAN, for streaming music from a single controlling PC to multiple PCs with speakers or to implement a simple "always-on" teleconferencing solution. + +The current implementation is designed to be used exclusively in local area networks, though Internet multicasting is theoretically supported. Only uncompressed audio is supported, hence you won't be able to multicast more than a few streams at the same time over a standard LAN. + +PulseAudio implements both a sender and a receiver for RTP traffic. The sender announces itself via SAP/SDP on the same multicast group as it sends the RTP data to. The receiver picks up the SAP/SDP announcements and creates a playback stream for each session. Alternatively you can use any RTP capable client to receive and play back the RTP data (such as mplayer, see [[How To Listen To The Rtp Stream|Software/PulseAudio/Documentation/User/Network/RTP]]). + + +### module-rtp-send + +This is the sender side of the RTP/SDP/SAP implementation. It reads audio data from an existing source and forwards it to the network encapsulated in RTP. In addition it sends SAP packets with an SDP session description. + +In combination with the monitor source of module-null-sink you can use this module to create an RTP sink. + + * source + * The source to read the audio data from. If omitted defaults to the default source. format, rate, channels + * Sample format to use, defaults to the source's. destination + * Destination multicast group for both RTP and SAP packets, defaults to 224.0.0.56 port + * Destination port number of the RTP traffic. If omitted defaults to a randomly chosen even port number. Please keep in mind that the RFC suggests to use only even port numbers for RTP traffic. mtu + * Maximum payload size for RTP packets. If omitted defaults to 1280 loop + * Takes a boolean value, specifying whether locally generated RTP traffic should be looped back to the local host. Disabled by default. ttl + * TTL + +### module-rtp-recv + +This is the receiver side of the RTP/SDP/SAP implementation. It picks up SAP session announcements and creates an RTP playback stream for each. + +In combination with module-null-sink you can use this module to create an RTP source. + + * sink + * The sink to connect to. If omitted defaults to the default sink. sap_address + * The multicast group to join for SAP announcements, defaults to 224.0.0.56. + +## RAOP Sink (Wireless Network Sound aka Apple Airtunes) + +PulseAudio can stream audio data to products that support the RAOP protocol. + + +### module-raop-discover + +mDNS/DNS-SD Service Discovery of RAOP devices + + +### module-raop-sink + +The main module used to create a virtual output device which pipes all audio to the RAOP device. + + * sink_name + * The name of the sink (see [[Modules|Software/PulseAudio/Documentation/User/Modules]]) server + * The server to connect to sink_properties, format, rate, channels + * All supported as per [[Modules|Software/PulseAudio/Documentation/User/Modules]] + +## JACK Connectivity + +PulseAudio can be hooked up to a JACK Audio Connection Kit server which is a specialized sound server used for professional audio production on Unix/Linux. Both a PulseAudio sink and a source are available. For each channel a port is created in the JACK server. + + +### module-jack-sink + +This module implements a PulseAudio sink that connects to JACK and registers as many output ports as requested. + + * sink_name + * The name for the PulseAudio sink. If omitted defaults to jack_out. server_name + * The JACK server to connect to. If omitted defaults to the default server. client_name + * The client name to tell the JACK server. If omitted defaults to PulseAudio. channel_map channels + * Number of channels to register. If omitted defaults to the number of physical playback ports of the JACK server. connect + * Takes a boolean value. If enabled (the default) PulseAudio will try to connect its ports to the physical playback ports of the JACK server + +### module-jack-source + +This module implements a PulseAudio source that connects to JACK and registers as many input ports as requested. Takes the same arguments as module-jack-sink, except for sink_name which is replaced by source_name (with a default of jack_in) for obvious reasons. + + +### module-jackdbus-detect + +This module automatically adds JACK sinks and sources whenever the JACK server is started. For this to work, you need to use JACK 2, and enable JACK's D-Bus interface. + + * channels + * The number of channels to create for both module-jack-sink and module-jack-source. If omitted, the sink will use the number of physical output ports and the source will use the number of physical input ports registered in the JACK server. connect + * Takes a boolean value. If enabled (the default) PulseAudio will try to connect its ports to the physical playback ports of the JACK server. + +## Filters + +These modules create a virtual sink and/or source on top of a given sink and source and filter the data flowing through. + + +### module-echo-cancel + +Used to perform acoustic echo cancellation between a designated sink and source. **Since 1.0** + + * source_name + * Name to give the virtual source that is created source_properties + * Properties to set on the virtual source source_master + * Name of the source to filter sink_name + * Name to give the virtual sink that is created sink_properties + * Properties to set on the virtual sink sink_master + * Name of sink to filter autoloaded + * Set if this module is being loaded automatically. Don't set this manually unless you know what you're doing. use_volume_sharing + * Whether to use volume sharing with master sink/source adjust_time + * How often to readjust sync between sink and source (in seconds) adjust_threshold + * **Since 2.0.** How much drift to readjust after (in milliseconds) format + * The sample format of the virtual sink and source. rate + * The sample rate of the virtual sink and source. channels + * The number of channels of the virtual sink and source. channel_map + * The channel map of the virtual sink and source. aec_method + * Specific AEC implementation to use ("speex", "webrtc", "adrian" (not a very good canceller) or "null"). aec_args + * Parameters for the AEC engine (to be documented) save_aec + * If set, saves AEC data in /tmp/aec_* + +### module-equalizer-sink + +General purpose equalizer that can be applied over a given sink. **Since 1.0** + + * sink_name + * Name to give the virtual sink that is created sink_properties + * Properties to set on the virtual sink sink_master + * Name of sink to filter autoloaded + * Set if this module is being loaded automatically. Don't set this manually unless you know what you're doing. use_volume_sharing + * Whether to use volume sharing with master sink/source + +### module-ladspa-sink + +Adds signal processing (for example equalizing) to a sink with a [[LADSPA|http://www.ladspa.org/]] plugin. + +The module shows up as a separate sink. + + * sink_name + * Name for this sink. sink_properties + * Extra properties to be stored in the sink's property list. master + * The sink where the processed audio is forwarded to. channels, rate, channel_map + * Normal sink parameters. It's best to leave these unspecified, so that the master sink parameters will be used. plugin + * The name of the .so file that contains the desired filter without the ".so" part. Specify only the file name, not the full directory path. The directories where the plugin files are searched from can be specified with the environment variable LADSPA_PATH. Multiple directories can be specified using colon (:) as the separator. If the environment variable isn't set, "$libdir/ladspa:/usr/local/lib/ladspa:/usr/lib/ladspa" is used instead ($libdir is specified at build time, so the default search path should include the directory where your distribution installs LADSPA plugins). label + * One plugin file may contain multiple plugins, which are identified by a label. Specify it here. control + * If the plugin has control input ports, you have to specify their values here. That is done by simply listing the numeric values using comma as the separator. Default values can be used by leaving the number out. Examples: Plugin with five control ports, leaving the third to the default value: `control=0.34,-2.3,,0.00346,5` Plugin with three control ports, leaving all to the default values: `control=,,` input_ladspaport_map + * Comma separated list of input LADSPA audio port names. The list is matched with the sink channel map so that each LADSPA port in the list is assigned for the corresponding channel channel map. If this argument is not given, the ports are assigned in the order that the plugin lists them. output_ladspaport_map + * Comma separated list of output LADSPA audio port names. The list is matched with the sink channel map so that each LADSPA port in the list is assigned for the corresponding channel channel map. If this argument is not given, the ports are assigned in the order that the plugin lists them. +An example: adding an equalizer to a normal alsa sink (on Debian the mbeq plugin is in the `swh-plugins` package). +[[!format txt """ +load-module module-ladspa-sink sink_name=ladspa_out master=alsa_out plugin=mbeq_1197 label=mbeq control=11.621622,10,4.594594,2.702703,0,0,-1.621622,-0.270270,-5.405406,-3.513514,-8.648648,-5.675676,-4.054054,1.351351,9.189189 +"""]] +The control values can't be modified at run-time, so it can be a problem to figure out good control values for the plugin. The writer of this documentation used [[JACK Rack|http://jack-rack.sourceforge.net/]] to find the values. This is a good solution if you already are familiar with Jack, but if you're not, this is one more thing to learn. If someone knows a handier way to fiddle with the parameters, please edit this page. + +Control output ports are ignored. + + +## Miscellaneous + + +### module-sine + +Creates a sink input and generates a sine waveform stream. + + * sink + * The sink to connect to. If omitted defaults to the default sink. frequency + * The frequency to generate in Hertz. Defaults to 440. + +### module-sine-source + +Creates a source and generates a sine waveform stream. + + * source_name + * Name for the source. (defaults to sine_input) rate + * Sample rate for the source. frequency + * The frequency to generate in Hertz. Defaults to 440. + +### module-esound-compat-spawnfd + +This is a compatibility module for libesd based autospawning of PulseAudio. Don't use it directly. + + +### module-esound-compat-spawnpid + +This is a compatibility module for libesd based autospawning of PulseAudio. Don't use it directly. + + +### module-match + +Adjust the volume of a playback stream automatically based on its name. + + * table + * The regular expression matching table file to use (defaults to ~/.pulse/match.table) +The table file should contain a regexp and volume on each line, separated by spaces. An example: + + +[[!format txt """ +^sample: 32000 +"""]] +The volumes of all streams with titles starting with sample: are automatically set to 32000. (FYI: All sample cache streams start with sample:) + + +### module-udev-detect + +**Since 0.9.16.** Detects ALSA audio devices on the system using [[udev|http://en.wikipedia.org/wiki/Udev]]. + + * tsched + * Enable timer based scheduling? Default: yes. ignore_dB + * Ignore the decibel information that ALSA provides? Default: no. deferred_volume + * **Since 1.0.** Syncronize sw and hw volume changes? Default: yes. fixed_latency_range + * **Since 2.0.** Boolean. Normally when there's an alsa underrun or overrun, and timer based scheduling is used, the alsa sink or source will raise the minimum latency that applications can get to avoid further underruns or overruns. If this option is enabled, the minimum latency will stay constant even if underruns or overruns occur. + +### module-detect + +**This module is deprecated on systems where udev is available. Please use module-udev-detect instead.** + +Automatically detect the available sound hardware and load modules for it. Supports OSS, ALSA, Solaris and Win32 output drivers, and the information is taken directy from them, not through udev. + +Do not use this together with module-udev-detect! + +The parameter: + + * just-one + * If set to 1 the module will only try to load a single sink/source and than stop. + +### module-zeroconf-publish + +Publish all local sinks/sources using mDNS Zeroconf. For more information, see [[Network Setup|Software/PulseAudio/Documentation/User/Network]]. + + +### module-zeroconf-discover + +Discover sinks/sources on other [[PulseAudio|PulseAudio]] servers using mDNS Zeroconf. + + +### module-rescue-streams + +Automatically route a stream whose sink has become unavailable (e.g. USB hw plugged out) to another working sink. + + +### module-systemd-login + +**Since 2.0.** Create a client for each login session of this user. + +This module doesn't do anything on systems that don't use systemd, so this module can be loaded at the same time with module-console-kit. + + +### module-console-kit + +**Since 0.9.11.** Create a client for each [[ConsoleKit|ConsoleKit]] session of this user + +This module doesn't do anything on systems that use systemd, so this module can be loaded at the same time with module-systemd-login. + + +### module-position-event-sounds + +**Since 0.9.11.** Position event sounds between L and R depending on the position on screen of the widget triggering them. + + +### module-always-sink + +**Since 0.9.11.** Always keeps at least one sink loaded even if it's a null one + + * sink_name + * The name for the new virtual sink. + +### module-suspend-on-idle + +**Since 0.9.11.** Disconnects sinks and sources from their backend after a predetermined amount of idle time. Idle time is accumulated when the sink/source in question is not connected to any streams. + +Advantages: Saves power. ALSA uses considerably more CPU cycles when pulseaudio has to send empty data to the soundcard during idle. If you don't plan to have an active stream all the time, set the timer to a low value for best power savings. + +Disadvantages: When pulseaudio gives up the backend, and the backend is not capable of mixing, errant applications can grab the sound device and hold exclusive control over it, making pulseaudio stop working. If pulseaudio does not give up the backend, errant applications won't be able to play sound, but they will not disrupt pulseaudio's operation either. This scenario is possible 99% of the time, since most users run an ALSA sink/source without a card that has software mixing. An "errant application" would, for example, try to open hw:0 or front:0 rather than the 'default' ALSA device. + + * timeout + * Time, in seconds, which must elapse before a sink or source is deemed idle. + +### module-loopback + +**Since 0.9.16.** This allows one to route audio from a source directly back to a sink. + + * source + * The name of the input source to connect to. If not specified the source will be picked automatically. You can use a tool like pavucontrol to move the loopback stream to the right source. sink + * The name of the sink the audio is forwarded to. If not specified the sink will be picked automatically. adjust_time + * How often to readjust the sample rates in seconds. Defaults to 10. latency_msec + * The desired latency in milliseconds, from 1 to 2000. Defaults to 200. (Note that this is only a friendly request, the actually latency might be higher or lower thatn this value) format + * The sample format. Defaults to that of specified sink. rate + * The sample rate. Defaults to that of specified sink. channels + * Number of source channels to use. Defaults to that of specified sink. channel_map + * List of the channels to connect to the sink. sink_input_properties + * **Since 1.0.** Property list for the playback stream object. source_output_properties + * **Since 1.0.** Property list for the capture stream object. source_dont_move + * **Since 1.0.** Takes a boolean value. Disallows moving the capture stream to some other than the initial source. Defaults to "false". sink_dont_move + * **Since 1.0.** Takes a boolean value. Disallows moving the playback stream to some other than the initial sink. Defaults to "false". remix + * **Since 1.0.** Takes a boolean value. If the channel map of the capture stream doesn't match the source's channel map, or the channel map of the playback stream doesn't match the sink's channel map, the mismatch has to be handled somehow. If remixing isn't disabled in the global server configuration, by default the audio will get remixed. This parameter can be used to disable remixing for the loopback streams (but if remixing is disabled in the global server configuration, this parameter can't be used for forcing remixing - setting this parameter simply has no effect at all). + +### module-switch-on-connect + +Whenever a new sink or source appears, this module will switch the default sink/source to be the new sink/source, and will move all currently running streams to the new sink/source. Takes no arguments. + + +### module-role-ducking + +This module lowers the volume of less important streams when a more important stream appears, and raises the volume back up once the important stream has finished (this is called "ducking"). The decision whether a stream has high or low priority is made based on the stream role (the media.role property). By default, "music" and "video" streams are ducked, and "phone" streams trigger the ducking. + + * trigger_roles + * Comma separated list of roles that will trigger ducking. ducking_roles + * Comma separated list of roles that will be ducked. global + * A boolean. If true, ducking will be applied to all streams that have a ducking role. If false, ducking will be applied only to streams that are connected to the same device as the triggering stream. volume + * Attenuation to be used while ducking. The value can be given either as a percentage (for example, "40%"), in decibels (for example, "-20dB") or as a plain integer between 0 and 65536 (this is the representation that PulseAudio uses for volume internally).
\ No newline at end of file diff --git a/Software/PulseAudio/Documentation/User/Network.mdwn b/Software/PulseAudio/Documentation/User/Network.mdwn new file mode 100644 index 00000000..3c9a93ce --- /dev/null +++ b/Software/PulseAudio/Documentation/User/Network.mdwn @@ -0,0 +1,126 @@ + +[[!inline pages="Software/PulseAudio/TOC" quick="yes" raw="yes"]] + + +# Network Setup + +[[!toc 3]] + +There are several different ways to connect to another PulseAudio server (direct connection, tunnel, RTP) or some other network audio device (RTP, RAOP, Rygel). + +Note all methods described here stream raw PCM audio over the network. This can use pretty much network bandwidth (around 1.4 Mb/s for CD-quality sound). If you get choppy sound, try setting a lower sample rate for the network stream. Furthermore, even while many WiFi connections can sustain such bitrates, often the jitter in packet latency makes transmitting low-latency audio over a wireless link infeasible in practice. + + +## Direct connection + +Just set the environment variable `$PULSE_SERVER` to the host name of the PulseAudio server. Alternatively you can modify `~/.pulse/client.conf` or `/etc/pulse/client.conf` and set `default-server`. See [[Server Strings|Software/PulseAudio/Documentation/User/ServerStrings]] for an explanation of the format. In this [[FAQ entry|Software/PulseAudio/FAQ]] all locations you can specify the server to use are listed. All the methods that connect to the daemon over the network using the native protocol need [[module-native-protocol-tcp|Software/PulseAudio/Documentation/User/Modules]] loaded. This includes tunnels and Zeroconf setups. With this module loaded, the server listens on port 4713 for incoming client connections. + + +#### Authorization + +For authentication you need the same auth cookies on all sides. For that copy `~/.pulse-cookie` to all clients that shall be allowed to connect. Alternatively the authorization cookies can be stored in the X11 server. The server must have [[module-native-protocol-tcp|Software/PulseAudio/Documentation/User/Modules]] loaded. To enable all audio from all over the network, set the `auth-anonymous=1` argument. A more secure options is to manage access to these servers with an IP ACL. This can look like this in your `/etc/pulse/default.pa` or `~/.pulse/default.pa` startup script for PulseAudio: +[[!format txt """ +load-module module-esound-protocol-tcp auth-anonymous=1 +load-module module-native-protocol-tcp auth-ip-acl=127.0.0.1;192.168.0.0/16 +"""]] +These two modules are not loaded in the default configuration because they might open PulseAudio for remote attackers. + + +#### X forwarding + +If the `$PULSE_SERVER` variable does not exist or is empty, PulseAudio will then check for X11 properties on the root window. These properties are much like environment variables, but will be available remotely if you SSH to another machine with X11 forwarding. You can see a list of PulseAudio related properties by doing: +[[!format txt """ +xprop -root | grep PULSE +"""]] +The variables names used are the same as those used in the environment, so PulseAudio will look for a property called `PULSE_SERVER`. Note that only the X11 properties are forwarded over the SSH tunnel, but the pulseaudio client still connects to the server using its own native protocol. + +If connecting back to the pulse daemon running on the computer that has the X display is not desired, you can either set `PULSE_SERVER=localhost` from the SSH connection (make sure module-native-protocol-tcp is loaded though) or run `pax11publish -r` before SSHing to the remote computer to remove the properties on the root window. + + +## Using a tunnel + +With a tunnel you can create a new sink that forwards all audio over the network to another server. For the sink at the remote server the tunnel looks like just another stream connecting over the network. The same holds for sources. See the documentation on [[module-tunnel|Software/PulseAudio/Documentation/User/Modules]] for details on the module arguments. + +Setting up a tunnel requires a running PulseAudio daemon on the remote server with module-native-protocol-tcp loaded, just like with the direct connection. After the tunnel is set up, client applications connect to the tunnel sink on the local PulseAudio daemon. This has the advantage that you can switch the stream seamlessly between a local hardware sink and the tunnel sink. With a direct connection the client generally has to be restarted in order to switch servers. A direct connection has the advantage that the client has more control over buffering parameters. + + +### mDNS + +In order to avoid having to setup tunnel manually between computers on a network, Zeroconf can be used. + +Setup `module-zeroconf-publish` and `module-zeroconf-discover` manually or use the check box in paprefs. + +You can connect to other sound servers running on the LAN by using Zeroconf/[[Avahi|http://avahi.org/]] technolgy. Therefore make sure to compile PulseAudio with Avahi support and load the Zeroconf modules on all machines on the LAN. In addition make sure to load the `module-native-protocol-tcp` and that it allows connections from other hosts, see [[Authorization|Software/PulseAudio/Documentation/User/Network]] above. + + +[[!format txt """ +#for servers +load-module module-zeroconf-publish +#for clients +load-module module-zeroconf-discover +"""]] +These modules are not loaded in the default configuration because they might open PulseAudio for remote attackers. + + +## RTP + +RTP is the _Realtime Transfer Protocol_. It is a well-known protocol for transferring audio and video data over IP. Two related protocols are SDP and SAP. SDP is the _Session Description Protocol_ and can be used to describe RTP sessions. SAP is the _Session Announcement Protocol_ and can be used to announce RTP sessions that are described with SDP. (Modern SIP based VoIP phones use RTP/SDP for their sessions, too) All three protocols are defined in IETF RFCs (RFC3550, RFC3551, RFC2327, RFC2327). They can be used in both multicast and unicast fashions. PulseAudio exclusively uses multicast RTP/SDP/SAP containing audio data. + +For more information about using these technologies with PulseAudio have a look on the [[modules documentation|Software/PulseAudio/Documentation/User/Modules]]. + + +### How can I use PulseAudio to stream music from my main PC to my LAN with multiple PCs with speakers? + +On the sender side create an RTP sink: +[[!format txt """ +load-module module-null-sink sink_name=rtp +load-module module-rtp-send source=rtp.monitor +set-default-sink rtp +"""]] +This will make rtp the default sink, i.e. all applications will write to this virtual RTP device by default. + On the client sides just load the reciever module: +[[!format txt """ +load-module module-rtp-recv +"""]] +Now you can play your favourite music on the sender side and all clients will output it simultaneously. + BTW: You can have more than one sender machine set up like this. The audio data will be mixed on the client side. + + +### How can I use PulseAudio to share a single LINE-IN/MIC jack on the entire LAN? + +On the sender side simply load the RTP sender module: +[[!format txt """ +load-module module-rtp-send +"""]] +On the reciever sides, create an RTP source: +[[!format txt """ +load-module module-null-sink sink_name=rtp +load-module module-rtp-recv sink=rtp +set-default-source rtp_monitor +"""]] +Now the audio data will be available from the default source `rtp_monitor`. + + +### How can I use PulseAudio as an RTP based N:N multicast conferencing solution for the LAN? + +After loading all the necessary audio drivers for recording and playback, just load the RTP reciever and sender modules with default parameters: +[[!format txt """ +load-module module-rtp-send +load-module module-rtp-recv +"""]] +As long as the PulseAudio daemon runs, the microphone data will be streamed to the network and the data from other hosts is played back locally. Please note that this may cause quite a lot of traffic. Hence consider passing `rate=8000 format=ulaw channels=1` to the sender module to save bandwith while still maintaining good quality for speech transmission. + + +### Can I have more than one multicast RTP group? + +Yes! Simply use a new multicast group address. Use the `destination`/`sap_address` arguments of the RTP modules to select them. Choose your group addresses from the range 225.0.0.x to make sure the audio data never leaves the LAN. + + +## !AirPort RAOP streaming + +With `module-raop-sink`. + + +## Rygel + +With `module-rygel-media-server` diff --git a/Software/PulseAudio/Documentation/User/Network/RTP.mdwn b/Software/PulseAudio/Documentation/User/Network/RTP.mdwn new file mode 100644 index 00000000..7308e5ff --- /dev/null +++ b/Software/PulseAudio/Documentation/User/Network/RTP.mdwn @@ -0,0 +1,109 @@ + +[[!toc ]] + +* = How to listen to the pulseaudio RTP Stream = +Various methods on how to listen to the RTP Stream with other clients than native pulseaudio. + +Preparations: You must know the following stream parameters: + + * Multicast address and port + * Sample rate / channel count + * Sample format (according to [[this post|https://tango.0pointer.de/pipermail/pulseaudio-discuss/2007-September/000678.html]], it is always s16be) +Disclaimer: + + * I am not responsible if this fries any of your machines, deletes all your data, eats your breakfast etc. It worked for me so I decided to post it in the wiki for other people who want to try this and skip the googling. Feel free to edit this page, correct typos, add new cool ideas and so on. That's what a wiki is for, right? +* == How to get the multicast address and port - the quick and dirty way - with tcpdump == + 1. Start the stream. + 1. On the target machine, enter the command + +[[!format txt """ +tcpdump -n net 224.0.0.0/8 -c 10 +"""]] + 1. Examine the output, for example + +[[!format txt """ +12:18:20.404866 IP 10.54.5.9.33043 > 224.0.0.56.46454: UDP, length 1292 +"""]] + 1. Congratulations, you now know three things: + 1. The packets are arriving + 1. The multicast address (in my case 224.0.0.56) + 1. The multicast port (in my case 46454) +* == Play it using mplayer == +From the [[pulseaudio-discuss mailing list|https://tango.0pointer.de/pipermail/pulseaudio-discuss/2007-September/000704.html]]: +[[!format txt """ +mplayer -demuxer rawaudio -rawaudio channels=2:rate=44100:samplesize=2:format=0x10001 rtp://[addr]:[port] +"""]] +For me it did not really work, mplayer always played it back at 48000hz - although I specified it otherwise - and thus pitch was too high and lots of buffer-underruns (guess why ; ) Mplayer ignores in that case your rate parameter and uses the rate from formatstring(dvdpcm). This works for me good +[[!format txt """ +mplayer -cache 2048 -demuxer rawaudio -rawaudio format=0x20776172 rtp://[addr]:[port] +"""]] + 1. -cache - use a buffersize of 2048 kbyte + 1. format - take a look here [[http://www.mplayerhq.hu/DOCS/codecs-status.html|http://www.mplayerhq.hu/DOCS/codecs-status.html]] for explanation. Does somebody know a better site with detailed informations of the fourcc strings ? +* == Play it using rtpdump and sox (invoked as "play") == +Now for the really cool and low-resource way. + + 1. Download and compile the rtptools from [[http://www.cs.columbia.edu/irt/software/rtptools/|http://www.cs.columbia.edu/irt/software/rtptools/]] (direct link [[http://www.cs.columbia.edu/irt/software/rtptools/download/|http://www.cs.columbia.edu/irt/software/rtptools/download/]]), if it is not in your distro's packet management. + 1. Download and compile sox from [[http://sox.sourceforge.net/|http://sox.sourceforge.net/]] (but THAT should really be in your distro...) + 1. Make a fifo for the RTP payload data (rtpdump doesn't support `-` aka stdout) + +[[!format txt """ +mkfifo /tmp/audiofifo +"""]] + 1. Fire up rtpdump, dumping payload data to the fifo (note the addr slash port noation, instead of the usual addr colon port notation) + +[[!format txt """ +rtpdump -F payload -o /tmp/audiofifo [addr]/[port] & +"""]] + 1. Start sox (invoked as "play", make a symlink if you need to) with the stream parameters. + +[[!format txt """ +play -c 2 -f s -r 44100 -s w -t raw -x --file=/tmp/audiofifo +"""]] + 1. -c 2 : 2 Channels (stereo) + 1. -f s : signed (_signed_ 16 bit big-endian, remember?) + 1. -r 44100 : sample rate (I'm playing MP3 music from CDs) + 1. -s w : sample size "word" (16 bit aka 2 bytes) + 1. -t raw : raw pcm audio data + 1. -x : swap endianness (I am using a little-endian based system) + 1. Edit! with sox v14.0.0 the following commandline worked: + +[[!format txt """ +play -t raw -r 44100 -s -2 -c 2 -B /tmp/audiofifo +"""]] + 1. -r 44100 : rate 44100hz + 1. -s : signed + 1. -2 : 2 bytes (16 bit) per sample + 1. -c 2 : channels 2 (stereo) + 1. -B : big endian + 1. If you don't like to listen anymore, simply kill play with CTRL-C. rtpdump should automagically terminate. (aka crash because of the broken pipe ; ) +* == Play it using rtpdump and aplay == +As above but use aplay from alsa-utils instead of sox: +[[!format txt """ +rtpdump -F payload [addr]/[port] | aplay -f cdr +"""]] +* == Play it using vlc == +The swiss-army knife vlc can be used to simply receive one stream. It's more for testing purpose then for daily usage. + + +[[!format txt """ +vlc rtp://@0.0.0.0:46444/ +"""]] +In this simple configuration vlc does not support more then one stream and is not very stable when it comes to changing streams. + +* == Stream it with vlc as mp3 for low bandwidth == +As uncompressed audio needs a lot of bandwidth you can compress the stream first and then send it as a mp3 stream + +1. You should change the configuration file default.pa to send the RTP traffic to 127.0.0.1 and a specific port (in my case 46998) +[[!format txt """ +load-module module-null-sink sink_name=rtp format=s16be channels=2 rate=44100 description="RTP Multicast Sink" +load-module module-rtp-send source=rtp.monitor destination=127.0.0.1 port=46998 loop=1 +"""]] +2. Log off and back on or reboot to enable the changes 3. Now you can transcode the incomming RTP/s16be stream with vlc and send the RTP/mp3 stream to a multicast address +[[!format txt """ +cvlc --ipv4 rtp://@127.0.0.1:46998 ":sout=#transcode{acodec=mp3,ab=256,channels=2}:duplicate{dst=rtp{dst=225.0.0.1,mux=ts,port=12345}}" +"""]] +4. Playback the stream on any computer +[[!format txt """ +vlc --ipv4 rtp://@225.0.0.1:12345 +"""]] +You can stream your audio to a lot of PCs (in different rooms) and playback songs synchronic (You just need to fist start the clients for the vlc playback and then the transcoder) This way I wrote a little shell script to start playing music in my whole house ;-) diff --git a/Software/PulseAudio/Documentation/User/Passthrough.mdwn b/Software/PulseAudio/Documentation/User/Passthrough.mdwn new file mode 100644 index 00000000..12baf02b --- /dev/null +++ b/Software/PulseAudio/Documentation/User/Passthrough.mdwn @@ -0,0 +1,25 @@ + +As of PulseAudio 1.0, we support passthrough output of compressed formats. This allows us to directly support passing compressed audio to hardware that supports it. Currently, the only hardware for which we support this is A/V receivers plugged in over S/PDIF or HDMI, but this can include hardware decoders on SoCs and streaming MP3/AAC/... to Bluetooth headsets that support it in the future. + +**If you have any trouble setting this up or using the new API, just get on IRC or the mailing list and holler to get some help.** + + +## For users + +Passthrough output for the GStreamer PulseAudio plugin will be available in the next release (0.10.31) of gst-plugins-good. Once this is installed, you should be able to have passthrough output just work with Totem and most other players that use `playbin2`. + +VLC media player and LibVLC support passthrough starting with version 1.1.12. However fail-over from passthrough output to normal PCM output is only available from version 1.2.0. + +To configure passthrough output, you need to do the following: + +1. Make sure no clients (other than your video player) are connected for playback (you can see the list of connected clients in pavucontrol under the Playback tab) +1. In the Configuration tab, select the appropriate digital output profile +1. (You only need to do this once unless you change the receiver.) In the Output Devices tab, select the formats that your receiver supports (your receiver documentation may refer to Dolby Digital (which is AC3), Dolby Digital+ (which is EAC3) +That's it! + + +## For developers + +Clients need to be aware of two changes to the API -- you need to use the `pa_stream_new_extended()` function for setting up a stream, and the `struct pa_format_info` instead of `struct pa_sample_spec` to specify what type of data you're providing. More information on the API design can be found at [[[[Software/PulseAudio/Documentation/Developer/Passthrough|Software/PulseAudio/Documentation/Developer/Passthrough]]]]. + +If you're adapting your sink to expose this capability, look at the documentation for `pa_sink->get_formats()` and `pa_sink->set_formats()`. diff --git a/Software/PulseAudio/Documentation/User/PerfectSetup/pulseaudio-patch.patch b/Software/PulseAudio/Documentation/User/PerfectSetup/pulseaudio-patch.patch new file mode 100644 index 00000000..3ca72184 --- /dev/null +++ b/Software/PulseAudio/Documentation/User/PerfectSetup/pulseaudio-patch.patch @@ -0,0 +1,1030 @@ +Index: AUTHORS +=================================================================== +--- AUTHORS (revision 24361) ++++ AUTHORS (working copy) +@@ -635,7 +635,7 @@ + * Darwin VCD/SVCD support + + Poettering, Lennart <mzzcynlre@0pointer.de> +- * audio driver for the Polypaudio sound server ++ * audio driver for the PulseAudio sound server + + Poirier, Guillaume (poirierg) <poirierg@gmail.com> + * French documentation translation and synchronization +Index: libao2/ao_pulse.c +=================================================================== +--- libao2/ao_pulse.c (revision 0) ++++ libao2/ao_pulse.c (revision 0) +@@ -0,0 +1,567 @@ ++#include <assert.h> ++#include <string.h> ++#include <stdio.h> ++ ++#include <pulse/pulseaudio.h> ++ ++#include "config.h" ++#include "libaf/af_format.h" ++#include "mp_msg.h" ++#include "audio_out.h" ++#include "audio_out_internal.h" ++ ++#define PULSE_CLIENT_NAME "MPlayer" ++ ++/*#define PULSE_DEBUG*/ ++ ++/** General driver info */ ++static ao_info_t info = { ++ "PulseAudio audio output", ++ "pulse", ++ "Lennart Poettering", ++ "" ++}; ++ ++/** The sink to connect to */ ++static char *sink = NULL; ++ ++/** PulseAudio playback stream object */ ++static struct pa_stream *stream = NULL; ++ ++/** PulseAudio connection context */ ++static struct pa_context *context = NULL; ++ ++/** Main event loop object */ ++static struct pa_threaded_mainloop *mainloop = NULL; ++ ++/** A temporary variable to store the current volume */ ++static pa_cvolume volume; ++static int volume_initialized = 0; ++ ++/** Some special libao macro magic */ ++LIBAO_EXTERN(pulse) ++ ++#define CHECK_DEAD_GOTO(label) do { \ ++if (!context || pa_context_get_state(context) != PA_CONTEXT_READY || \ ++ !stream || pa_stream_get_state(stream) != PA_STREAM_READY) { \ ++ mp_msg(MSGT_AO, MSGL_ERR, "AO: [pulse] Connection died: %s\n", context ? pa_strerror(pa_context_errno(context)) : "NULL"); \ ++ goto label; \ ++ } \ ++} while(0); ++ ++static void context_state_cb(pa_context *c, void *userdata) { ++ assert(c); ++ ++ switch (pa_context_get_state(c)) { ++ case PA_CONTEXT_READY: ++ case PA_CONTEXT_TERMINATED: ++ case PA_CONTEXT_FAILED: ++ pa_threaded_mainloop_signal(mainloop, 0); ++ break; ++ ++ case PA_CONTEXT_UNCONNECTED: ++ case PA_CONTEXT_CONNECTING: ++ case PA_CONTEXT_AUTHORIZING: ++ case PA_CONTEXT_SETTING_NAME: ++ break; ++ } ++} ++ ++static void stream_state_cb(pa_stream *s, void * userdata) { ++ assert(s); ++ ++ switch (pa_stream_get_state(s)) { ++ ++ case PA_STREAM_READY: ++ case PA_STREAM_FAILED: ++ case PA_STREAM_TERMINATED: ++ pa_threaded_mainloop_signal(mainloop, 0); ++ break; ++ ++ case PA_STREAM_UNCONNECTED: ++ case PA_STREAM_CREATING: ++ break; ++ } ++} ++ ++static void stream_request_cb(pa_stream *s, size_t length, void *userdata) { ++ assert(s); ++ ++ pa_threaded_mainloop_signal(mainloop, 0); ++} ++ ++static void stream_latency_update_cb(pa_stream *s, void *userdata) { ++ assert(s); ++ ++ pa_threaded_mainloop_signal(mainloop, 0); ++} ++ ++static void success_cb(pa_stream *s, int success, void *userdata) { ++ assert(s); ++ ++ if (userdata) ++ *(int*) userdata = success; ++ pa_threaded_mainloop_signal(mainloop, 0); ++} ++ ++/** libao initialization function, arguments are sampling frequency, ++ * number of channels, sample type and some flags */ ++static int init(int rate_hz, int channels, int format, int flags) { ++ struct pa_sample_spec ss; ++ struct pa_channel_map map; ++ char hn[128]; ++ char *host = NULL; ++ ++ assert(!context); ++ assert(!stream); ++ assert(!mainloop); ++ ++ if (ao_subdevice) { ++ int i = strcspn(ao_subdevice, ":"); ++ if ((size_t) i >= sizeof(hn)) ++ i = sizeof(hn)-1; ++ ++ if (i > 0) { ++ strncpy(host = hn, ao_subdevice, i); ++ hn[i] = 0; ++ } ++ ++ if (ao_subdevice[i] == ':') ++ sink = ao_subdevice+i+1; ++ } ++ ++ ss.channels = channels; ++ ss.rate = rate_hz; ++ ++ ao_data.samplerate = rate_hz; ++ ao_data.format = format; ++ ao_data.channels = channels; ++ ++ switch (format) { ++ case AF_FORMAT_U8: ++ ss.format = PA_SAMPLE_U8; ++ break; ++ case AF_FORMAT_S16_LE: ++ ss.format = PA_SAMPLE_S16LE; ++ break; ++ case AF_FORMAT_S16_BE: ++ ss.format = PA_SAMPLE_S16BE; ++ break; ++ case AF_FORMAT_FLOAT_LE: ++ ss.format = PA_SAMPLE_FLOAT32LE; ++ break; ++ case AF_FORMAT_FLOAT_BE: ++ ss.format = PA_SAMPLE_FLOAT32BE; ++ break; ++ case AF_FORMAT_MU_LAW: ++ ss.format = PA_SAMPLE_ULAW; ++ break; ++ case AF_FORMAT_A_LAW: ++ ss.format = PA_SAMPLE_ALAW; ++ break; ++ default: ++ mp_msg(MSGT_AO, MSGL_ERR, "AO: [pulse] Unsupported sample spec\n"); ++ goto fail; ++ } ++ ++ if (!pa_sample_spec_valid(&ss)) { ++ mp_msg(MSGT_AO, MSGL_ERR, "AO: [pulse] Invalid sample spec\n"); ++ goto fail; ++ } ++ ++ pa_channel_map_init_auto(&map, ss.channels, PA_CHANNEL_MAP_ALSA); ++ ao_data.bps = pa_bytes_per_second(&ss); ++ ++ if (!volume_initialized || ss.channels != volume.channels) { ++ pa_cvolume_reset(&volume, ss.channels); ++ volume_initialized = 1; ++ } ++ ++ if (!(mainloop = pa_threaded_mainloop_new())) { ++ mp_msg(MSGT_AO, MSGL_ERR, "AO: [pulse] Failed to allocate main loop\n"); ++ goto fail; ++ } ++ ++ if (!(context = pa_context_new(pa_threaded_mainloop_get_api(mainloop), PULSE_CLIENT_NAME))) { ++ mp_msg(MSGT_AO, MSGL_ERR, "AO: [pulse] Failed to allocate context\n"); ++ goto fail; ++ } ++ ++ pa_context_set_state_callback(context, context_state_cb, NULL); ++ ++ if (pa_context_connect(context, host, 0, NULL) < 0) { ++ mp_msg(MSGT_AO, MSGL_ERR, "AO: [pulse] Failed to connect to server: %s\n", pa_strerror(pa_context_errno(context))); ++ goto fail; ++ } ++ ++ pa_threaded_mainloop_lock(mainloop); ++ ++ if (pa_threaded_mainloop_start(mainloop) < 0) { ++ mp_msg(MSGT_AO, MSGL_ERR, "AO: [pulse] Failed to start main loop\n"); ++ goto unlock_and_fail; ++ } ++ ++ /* Wait until the context is ready */ ++ pa_threaded_mainloop_wait(mainloop); ++ ++ if (pa_context_get_state(context) != PA_CONTEXT_READY) { ++ mp_msg(MSGT_AO, MSGL_ERR, "AO: [pulse] Failed to connect to server: %s\n", pa_strerror(pa_context_errno(context))); ++ goto unlock_and_fail; ++ } ++ ++ if (!(stream = pa_stream_new(context, "audio stream", &ss, &map))) { ++ mp_msg(MSGT_AO, MSGL_ERR, "AO: [pulse] Failed to create stream: %s\n", pa_strerror(pa_context_errno(context))); ++ goto unlock_and_fail; ++ } ++ ++ pa_stream_set_state_callback(stream, stream_state_cb, NULL); ++ pa_stream_set_write_callback(stream, stream_request_cb, NULL); ++ pa_stream_set_latency_update_callback(stream, stream_latency_update_cb, NULL); ++ ++ if (pa_stream_connect_playback(stream, sink, NULL, PA_STREAM_INTERPOLATE_TIMING|PA_STREAM_AUTO_TIMING_UPDATE, &volume, NULL) < 0) { ++ mp_msg(MSGT_AO, MSGL_ERR, "AO: [pulse] Failed to connect stream: %s\n", pa_strerror(pa_context_errno(context))); ++ goto unlock_and_fail; ++ } ++ ++ /* Wait until the stream is ready */ ++ pa_threaded_mainloop_wait(mainloop); ++ ++ if (pa_stream_get_state(stream) != PA_STREAM_READY) { ++ mp_msg(MSGT_AO, MSGL_ERR, "AO: [pulse] Failed to connect to server: %s\n", pa_strerror(pa_context_errno(context))); ++ goto unlock_and_fail; ++ } ++ ++ pa_threaded_mainloop_unlock(mainloop); ++ ++ return 1; ++ ++unlock_and_fail: ++ ++ if (mainloop) ++ pa_threaded_mainloop_unlock(mainloop); ++ ++fail: ++ ++ uninit(1); ++ return 0; ++} ++ ++/** Destroy libao driver */ ++static void uninit(int immed) { ++#ifdef PULSE_DEBUG ++ fprintf(stderr, "uninit(%i) ***\n", immed); ++#endif ++ ++ if (stream) { ++ if (!immed) { ++ pa_operation *o; ++ ++ pa_threaded_mainloop_lock(mainloop); ++ ++ if ((o = pa_stream_drain(stream, success_cb, NULL))) { ++ ++ while (pa_operation_get_state(o) != PA_OPERATION_DONE) { ++ CHECK_DEAD_GOTO(fail); ++ pa_threaded_mainloop_wait(mainloop); ++ } ++ ++ fail: ++ ++ pa_operation_unref(o); ++ } ++ ++ pa_threaded_mainloop_unlock(mainloop); ++ } ++ } ++ ++ if (mainloop) ++ pa_threaded_mainloop_stop(mainloop); ++ ++ if (stream) { ++ pa_stream_disconnect(stream); ++ pa_stream_unref(stream); ++ stream = NULL; ++ } ++ ++ if (context) { ++ pa_context_disconnect(context); ++ pa_context_unref(context); ++ context = NULL; ++ } ++ ++ if (mainloop) { ++ pa_threaded_mainloop_free(mainloop); ++ mainloop = NULL; ++ } ++} ++ ++/** Play the specified data to the pulseaudio server */ ++static int play(void* data, int len, int flags) { ++ int r = -1; ++ pa_operation *o = NULL; ++ ++ assert(stream); ++ assert(context); ++ ++#ifdef PULSE_DEBUG ++ fprintf(stderr, "playing %lu ***\n", len); ++#endif ++ ++ pa_threaded_mainloop_lock(mainloop); ++ ++ CHECK_DEAD_GOTO(fail); ++ ++ if (len) { ++ ++ if (pa_stream_write(stream, data, len, NULL, 0, PA_SEEK_RELATIVE) < 0) { ++ mp_msg(MSGT_AO, MSGL_ERR, "AO: [pulse] pa_stream_write() failed: %s\n", pa_strerror(pa_context_errno(context))); ++ goto fail; ++ } ++ ++ } else { ++ ++ if (!(o = pa_stream_trigger(stream, NULL, NULL))) { ++ mp_msg(MSGT_AO, MSGL_ERR, "AO: [pulse] pa_stream_trigger() failed: %s\n", pa_strerror(pa_context_errno(context))); ++ goto fail; ++ } ++ ++ /* We don't wait for this operation to complete */ ++ } ++ ++ r = len; ++ ++fail: ++ if (o) ++ pa_operation_unref(o); ++ ++ pa_threaded_mainloop_unlock(mainloop); ++ ++ return r; ++} ++ ++static void cork(int b) { ++ pa_operation *o = NULL; ++ int success = 0; ++ ++ assert(stream); ++ assert(context); ++ ++#ifdef PULSE_DEBUG ++ fprintf(stderr, "cork(%i) ***\n", b); ++#endif ++ ++ pa_threaded_mainloop_lock(mainloop); ++ ++ CHECK_DEAD_GOTO(fail); ++ ++ if (!(o = pa_stream_cork(stream, b, success_cb, &success))) { ++ mp_msg(MSGT_AO, MSGL_ERR, "AO: [pulse] pa_stream_cork() failed: %s\n", pa_strerror(pa_context_errno(context))); ++ goto fail; ++ } ++ ++ while (pa_operation_get_state(o) != PA_OPERATION_DONE) { ++ CHECK_DEAD_GOTO(fail); ++ pa_threaded_mainloop_wait(mainloop); ++ } ++ ++ if (!success) ++ mp_msg(MSGT_AO, MSGL_ERR, "AO: [pulse] pa_stream_cork() failed: %s\n", pa_strerror(pa_context_errno(context))); ++ ++ pa_operation_unref(o); ++ ++fail: ++ pa_threaded_mainloop_unlock(mainloop); ++} ++ ++/** Pause the audio stream by corking it on the server */ ++static void audio_pause(void) { ++ cork(1); ++ } ++ ++/** Resume the audio stream by uncorking it on the server */ ++static void audio_resume(void) { ++ cork(0); ++} ++ ++/** Reset the audio stream, i.e. flush the playback buffer on the server side */ ++static void reset(void) { ++ pa_operation *o = NULL; ++ int success = 0; ++ ++ assert(stream); ++ assert(context); ++ ++#ifdef PULSE_DEBUG ++ fprintf(stderr, "reset() ***\n"); ++#endif ++ ++ pa_threaded_mainloop_lock(mainloop); ++ ++ CHECK_DEAD_GOTO(fail); ++ ++ if (!(o = pa_stream_flush(stream, success_cb, &success))) { ++ mp_msg(MSGT_AO, MSGL_ERR, "AO: [pulse] pa_stream_flush() failed: %s\n", pa_strerror(pa_context_errno(context))); ++ goto fail; ++ } ++ ++ while (pa_operation_get_state(o) != PA_OPERATION_DONE) { ++ CHECK_DEAD_GOTO(fail); ++ pa_threaded_mainloop_wait(mainloop); ++ } ++ ++ if (!success) ++ mp_msg(MSGT_AO, MSGL_ERR, "AO: [pulse] pa_stream_flush() failed: %s\n", pa_strerror(pa_context_errno(context))); ++ ++ pa_operation_unref(o); ++ ++fail: ++ pa_threaded_mainloop_unlock(mainloop); ++} ++ ++/** Return number of bytes that may be written to the server without blocking */ ++static int get_space(void) { ++ size_t l = (size_t) -1; ++ ++ pa_threaded_mainloop_lock(mainloop); ++ ++ CHECK_DEAD_GOTO(fail); ++ ++ l = pa_stream_writable_size(stream); ++ ++#ifdef PULSE_DEBUG ++ fprintf(stderr, "\nspace = %lu\n", l); ++#endif ++ ++fail: ++ ++ pa_threaded_mainloop_unlock(mainloop); ++ ++ return l == (size_t) -1 ? -1 : (int) l; ++} ++ ++/** Return the current latency in seconds */ ++static float get_delay(void) { ++ pa_usec_t latency = (pa_usec_t) -1; ++ ++ pa_threaded_mainloop_lock(mainloop); ++ ++ for (;;) { ++ CHECK_DEAD_GOTO(fail); ++ ++ if (pa_stream_get_latency(stream, &latency, NULL) >= 0) ++ break; ++ ++ if (pa_context_errno(context) != PA_ERR_NODATA) { ++ mp_msg(MSGT_AO, MSGL_ERR, "AO: [pulse] pa_stream_get_latency() failed: %s\n", pa_strerror(pa_context_errno(context))); ++ goto fail; ++ } ++ ++ /* Wait until latency data is available again */ ++ pa_threaded_mainloop_wait(mainloop); ++ } ++ ++#ifdef PULSE_DEBUG ++ fprintf(stderr, "latency=%0.3f sec\n", (double) latency / 1000000); ++#endif ++ ++fail: ++ pa_threaded_mainloop_unlock(mainloop); ++ ++ return (latency == (pa_usec_t) -1) ? 0 : ((float) latency / 1000000.0); ++} ++ ++/** A callback function that is called when the ++ * pa_context_get_sink_input_info() operation completes. Saves the ++ * volume field of the specified structure to the global variable volume. */ ++static void info_func(struct pa_context *c, const struct pa_sink_input_info *i, int is_last, void *userdata) { ++ if (is_last < 0) { ++ mp_msg(MSGT_AO, MSGL_ERR, "AO: [pulse] Failed to get sink input info: %s\n", pa_strerror(pa_context_errno(context))); ++ return; ++ } ++ ++ if (!i) ++ return; ++ ++ volume = i->volume; ++ volume_initialized = 1; ++ ++ pa_threaded_mainloop_signal(mainloop, 0); ++} ++ ++/** Issue special libao controls on the device */ ++static int control(int cmd, void *arg) { ++ ++ if (!context || !stream) ++ return CONTROL_ERROR; ++ ++ switch (cmd) { ++ ++ case AOCONTROL_GET_VOLUME: { ++ /* Return the current volume of the playback stream */ ++ ao_control_vol_t *vol = (ao_control_vol_t*) arg; ++ pa_operation *o; ++ ++ if (!(o = pa_context_get_sink_input_info(context, pa_stream_get_index(stream), info_func, NULL))) { ++ mp_msg(MSGT_AO, MSGL_ERR, "AO: [pulse] pa_stream_get_sink_input_info() failed: %s\n", pa_strerror(pa_context_errno(context))); ++ return CONTROL_ERROR; ++ } ++ ++ while (pa_operation_get_state(o) != PA_OPERATION_DONE) { ++ CHECK_DEAD_GOTO(fail); ++ pa_threaded_mainloop_wait(mainloop); ++ } ++ ++ fail: ++ pa_operation_unref(o); ++ ++ if (!volume_initialized) { ++ mp_msg(MSGT_AO, MSGL_ERR, "AO: [pulse] pa_stream_get_sink_input_info() failed: %s\n", pa_strerror(pa_context_errno(context))); ++ return CONTROL_ERROR; ++ } ++ ++ if (volume.channels != 2) ++ vol->left = vol->right = (int) ((pa_cvolume_avg(&volume)*100)/PA_VOLUME_NORM); ++ else { ++ vol->left = (int) (volume.values[0]*100)/PA_VOLUME_NORM; ++ vol->right = (int) (volume.values[1]*100)/PA_VOLUME_NORM; ++ } ++ ++ return CONTROL_OK; ++ } ++ ++ case AOCONTROL_SET_VOLUME: { ++ /* Set the playback volume of the stream */ ++ const ao_control_vol_t *vol = (ao_control_vol_t*) arg; ++ pa_operation *o; ++ ++ if (!volume_initialized) { ++ pa_cvolume_reset(&volume, 2); ++ volume_initialized = 1; ++ } ++ ++ if (volume.channels != 2) ++ pa_cvolume_set(&volume, volume.channels, ((pa_volume_t) vol->left*PA_VOLUME_NORM)/100); ++ else { ++ volume.values[0] = ((pa_volume_t) vol->left*PA_VOLUME_NORM)/100; ++ volume.values[1] = ((pa_volume_t) vol->right*PA_VOLUME_NORM)/100; ++ } ++ ++ if (!(o = pa_context_set_sink_input_volume(context, pa_stream_get_index(stream), &volume, NULL, NULL))) { ++ mp_msg(MSGT_AO, MSGL_ERR, "AO: [pulse] pa_context_set_sink_input_volume() failed: %s\n", pa_strerror(pa_context_errno(context))); ++ return CONTROL_ERROR; ++ } ++ ++ pa_operation_unref(o); ++ ++ /* We don't wait for completion here */ ++ ++ return CONTROL_OK; ++ } ++ ++ default: ++ /* Unknown CONTROL command */ ++ return CONTROL_UNKNOWN; ++ } ++} ++ ++ +Index: libao2/ao_polyp.c +=================================================================== +--- libao2/ao_polyp.c (revision 24361) ++++ libao2/ao_polyp.c (working copy) +@@ -1,324 +0,0 @@ +-#include <assert.h> +-#include <string.h> +- +-#include <polyp/polyplib.h> +-#include <polyp/polyplib-error.h> +-#include <polyp/mainloop.h> +- +-#include "config.h" +-#include "audio_out.h" +-#include "audio_out_internal.h" +-#include "libaf/af_format.h" +-#include "mp_msg.h" +- +-#define POLYP_CLIENT_NAME "MPlayer" +- +-/** General driver info */ +-static ao_info_t info = { +- "Polypaudio audio output", +- "polyp", +- "Lennart Poettering", +- "" +-}; +- +-/** The sink to connect to */ +-static char *sink = NULL; +- +-/** Polypaudio playback stream object */ +-static struct pa_stream *stream = NULL; +- +-/** Polypaudio connection context */ +-static struct pa_context *context = NULL; +- +-/** Main event loop object */ +-static struct pa_mainloop *mainloop = NULL; +- +-/** Some special libao macro magic */ +-LIBAO_EXTERN(polyp) +- +-/** Wait until no further actions are pending on the connection context */ +-static void wait_for_completion(void) { +- assert(context && mainloop); +- +- while (pa_context_is_pending(context)) +- pa_mainloop_iterate(mainloop, 1, NULL); +-} +- +-/** Make sure that the connection context doesn't starve to death */ +-static void keep_alive(void) { +- assert(context && mainloop); +- +- while (pa_mainloop_iterate(mainloop, 0, NULL) > 0); +-} +- +-/** Wait until the specified operation completes */ +-static void wait_for_operation(struct pa_operation *o) { +- assert(o && context && mainloop); +- +- while (pa_operation_get_state(o) == PA_OPERATION_RUNNING) +- pa_mainloop_iterate(mainloop, 1, NULL); +- +- pa_operation_unref(o); +-} +- +-/** libao initialization function, arguments are sampling frequency, +- * number of channels, sample type and some flags */ +-static int init(int rate_hz, int channels, int format, int flags) { +- struct pa_sample_spec ss; +- struct pa_buffer_attr a; +- char hn[128]; +- char *host = NULL; +- +- assert(!context && !stream && !mainloop); +- +- if (ao_subdevice) { +- int i = strcspn(ao_subdevice, ":"); +- if (i >= sizeof(hn)) +- i = sizeof(hn)-1; +- +- if (i > 0) { +- strncpy(host = hn, ao_subdevice, i); +- hn[i] = 0; +- } +- +- if (ao_subdevice[i] == ':') +- sink = ao_subdevice+i+1; +- } +- +- mp_msg(MSGT_AO, MSGL_ERR, "AO: [polyp] -%s-%s-\n", host, sink); +- +- +- ss.channels = channels; +- ss.rate = rate_hz; +- +- switch (format) { +- case AF_FORMAT_U8: +- ss.format = PA_SAMPLE_U8; +- break; +- case AF_FORMAT_S16_LE: +- ss.format = PA_SAMPLE_S16LE; +- break; +- case AF_FORMAT_S16_BE: +- ss.format = PA_SAMPLE_S16BE; +- break; +- case AF_FORMAT_FLOAT_NE: +- ss.format = PA_SAMPLE_FLOAT32; +- break; +- default: +- mp_msg(MSGT_AO, MSGL_ERR, "AO: [polyp] Unsupported sample spec\n"); +- goto fail; +- } +- +- +- if (!pa_sample_spec_valid(&ss)) { +- mp_msg(MSGT_AO, MSGL_ERR, "AO: [polyp] Invalid sample spec\n"); +- goto fail; +- } +- +- +- mainloop = pa_mainloop_new(); +- assert(mainloop); +- +- context = pa_context_new(pa_mainloop_get_api(mainloop), POLYP_CLIENT_NAME); +- assert(context); +- +- pa_context_connect(context, host, 1, NULL); +- +- wait_for_completion(); +- +- if (pa_context_get_state(context) != PA_CONTEXT_READY) { +- mp_msg(MSGT_AO, MSGL_ERR, "AO: [polyp] Failed to connect to server: %s\n", pa_strerror(pa_context_errno(context))); +- goto fail; +- } +- +- stream = pa_stream_new(context, "audio stream", &ss); +- assert(stream); +- +- a.maxlength = pa_bytes_per_second(&ss)*1; +- a.tlength = a.maxlength*9/10; +- a.prebuf = a.tlength/2; +- a.minreq = a.tlength/10; +- +- pa_stream_connect_playback(stream, sink, &a, PA_STREAM_INTERPOLATE_LATENCY, PA_VOLUME_NORM); +- +- wait_for_completion(); +- +- if (pa_stream_get_state(stream) != PA_STREAM_READY) { +- mp_msg(MSGT_AO, MSGL_ERR, "AO: [polyp] Failed to connect to server: %s\n", pa_strerror(pa_context_errno(context))); +- goto fail; +- } +- +- return 1; +- +-fail: +- uninit(1); +- return 0; +-} +- +-/** Destroy libao driver */ +-static void uninit(int immed) { +- if (stream) { +- if (!immed && pa_stream_get_state(stream) == PA_STREAM_READY) +- wait_for_operation(pa_stream_drain(stream, NULL, NULL)); +- +- pa_stream_unref(stream); +- stream = NULL; +- } +- +- if (context) { +- pa_context_unref(context); +- context = NULL; +- } +- +- if (mainloop) { +- pa_mainloop_free(mainloop); +- mainloop = NULL; +- } +-} +- +-/** Play the specified data to the polypaudio server */ +-static int play(void* data, int len, int flags) { +- assert(stream && context); +- +- if (pa_stream_get_state(stream) != PA_STREAM_READY) +- return -1; +- +- if (!len) +- wait_for_operation(pa_stream_trigger(stream, NULL, NULL)); +- else +- pa_stream_write(stream, data, len, NULL, 0); +- +- wait_for_completion(); +- +- if (pa_stream_get_state(stream) != PA_STREAM_READY) +- return -1; +- +- return len; +-} +- +-/** Pause the audio stream by corking it on the server */ +-static void audio_pause(void) { +- assert(stream && context && pa_stream_get_state(stream) == PA_STREAM_READY); +- wait_for_operation(pa_stream_cork(stream, 1, NULL, NULL)); +-} +- +-/** Resume the audio stream by uncorking it on the server */ +-static void audio_resume(void) { +- assert(stream && context && pa_stream_get_state(stream) == PA_STREAM_READY); +- wait_for_operation(pa_stream_cork(stream, 0, NULL, NULL)); +-} +- +-/** Reset the audio stream, i.e. flush the playback buffer on the server side */ +-static void reset(void) { +- assert(stream && context && pa_stream_get_state(stream) == PA_STREAM_READY); +- wait_for_operation(pa_stream_flush(stream, NULL, NULL)); +-} +- +-/** Return number of bytes that may be written to the server without blocking */ +-static int get_space(void) { +- uint32_t l; +- assert(stream && context && pa_stream_get_state(stream) == PA_STREAM_READY); +- +- keep_alive(); +- +- l = pa_stream_writable_size(stream); +- +- return l; +-} +- +-/* A temporary latency variable */ +-/* static pa_usec_t latency = 0; */ +- +-/* static void latency_func(struct pa_stream *s, const struct pa_latency_info *l, void *userdata) { */ +-/* int negative = 0; */ +- +-/* if (!l) { */ +-/* mp_msg(MSGT_AO, MSGL_ERR, "AO: [polyp] Invalid sample spec: %s\n", pa_strerror(pa_context_errno(context))); */ +-/* return; */ +-/* } */ +- +-/* latency = pa_stream_get_latency(s, l, &negative); */ +- +-/* /\* Nor really required *\/ */ +-/* if (negative) */ +-/* latency = 0; */ +-/* } */ +- +-/** Return the current latency in seconds */ +-static float get_delay(void) { +- pa_usec_t latency; +- assert(stream && context && pa_stream_get_state(stream) == PA_STREAM_READY); +- +- /* latency = 0; */ +-/* wait_for_operation(pa_stream_get_latency(stream, latency_func, NULL)); */ +- /* pa_operation_unref(pa_stream_get_latency(stream, latency_func, NULL)); */ +- +- latency = pa_stream_get_interpolated_latency(stream, NULL); +- +- return (float) latency/1000000; +-} +- +-/** A temporary variable to store the current volume */ +-static pa_volume_t volume = PA_VOLUME_NORM; +- +-/** A callback function that is called when the +- * pa_context_get_sink_input_info() operation completes. Saves the +- * volume field of the specified structure to the global variable volume. */ +-static void info_func(struct pa_context *c, const struct pa_sink_input_info *i, int is_last, void *userdata) { +- if (is_last < 0) { +- mp_msg(MSGT_AO, MSGL_ERR, "AO: [polyp] Failed to get sink input info: %s\n", pa_strerror(pa_context_errno(context))); +- return; +- } +- +- if (!i) +- return; +- +- volume = i->volume; +-} +- +-/** Issue special libao controls on the device */ +-static int control(int cmd, void *arg) { +- +- if (!context || !stream) +- return CONTROL_ERROR; +- +- switch (cmd) { +- +- case AOCONTROL_SET_DEVICE: +- /* Change the playback device */ +- sink = (char*)arg; +- return CONTROL_OK; +- +- case AOCONTROL_GET_DEVICE: +- /* Return the playback device */ +- *(char**)arg = sink; +- return CONTROL_OK; +- +- case AOCONTROL_GET_VOLUME: { +- /* Return the current volume of the playback stream */ +- ao_control_vol_t *vol = (ao_control_vol_t*) arg; +- +- volume = PA_VOLUME_NORM; +- wait_for_operation(pa_context_get_sink_input_info(context, pa_stream_get_index(stream), info_func, NULL)); +- vol->left = vol->right = (int) (pa_volume_to_user(volume)*100); +- return CONTROL_OK; +- } +- +- case AOCONTROL_SET_VOLUME: { +- /* Set the playback volume of the stream */ +- const ao_control_vol_t *vol = (ao_control_vol_t*) arg; +- int v = vol->left; +- if (vol->right > v) +- v = vol->left; +- +- wait_for_operation(pa_context_set_sink_input_volume(context, pa_stream_get_index(stream), pa_volume_from_user((double)v/100), NULL, NULL)); +- +- return CONTROL_OK; +- } +- +- default: +- /* Unknown CONTROL command */ +- return CONTROL_UNKNOWN; +- } +-} +- +Index: libao2/audio_out.c +=================================================================== +--- libao2/audio_out.c (revision 24361) ++++ libao2/audio_out.c (working copy) +@@ -25,8 +25,8 @@ + #ifdef USE_ESD + extern ao_functions_t audio_out_esd; + #endif +-#ifdef USE_POLYP +-extern ao_functions_t audio_out_polyp; ++#ifdef USE_PULSE ++extern ao_functions_t audio_out_pulse; + #endif + #ifdef USE_JACK + extern ao_functions_t audio_out_jack; +@@ -112,8 +112,8 @@ + #ifdef USE_ESD + &audio_out_esd, + #endif +-#ifdef USE_POLYP +- &audio_out_polyp, ++#ifdef USE_PULSE ++ &audio_out_pulse, + #endif + #ifdef USE_JACK + &audio_out_jack, +Index: configure +=================================================================== +--- configure (revision 24361) ++++ configure (working copy) +@@ -390,7 +390,7 @@ + --disable-ossaudio disable OSS audio output [autodetect] + --disable-arts disable aRts audio output [autodetect] + --disable-esd disable esd audio output [autodetect] +- --disable-polyp disable Polypaudio audio output [autodetect] ++ --disable-pulse disable Pulseaudio audio output [autodetect] + --disable-jack disable JACK audio output [autodetect] + --disable-openal disable OpenAL audio output [autodetect] + --disable-nas disable NAS audio output [autodetect] +@@ -555,7 +555,7 @@ + _ossaudio=auto + _arts=auto + _esd=auto +-_polyp=auto ++_pulse=auto + _jack=auto + _openal=auto + _libcdio=auto +@@ -880,8 +880,8 @@ + --disable-arts) _arts=no ;; + --enable-esd) _esd=yes ;; + --disable-esd) _esd=no ;; +- --enable-polyp) _polyp=yes ;; +- --disable-polyp) _polyp=no ;; ++ --enable-pulse) _pulse=yes ;; ++ --disable-pulse) _pulse=no ;; + --enable-jack) _jack=yes ;; + --disable-jack) _jack=no ;; + --enable-openal) _openal=yes ;; +@@ -5075,32 +5075,30 @@ + _noaomodules="esd $_noaomodules" + fi + +-echocheck "Polyp" +-if test "$_polyp" = auto ; then +- _polyp=no +- if $_pkg_config --exists 'polyplib >= 0.6 polyplib-error >= 0.6 polyplib-mainloop >= 0.6' ; then ++echocheck "pulse" ++if test "$_pulse" = auto ; then ++ _pulse=no ++ if $_pkg_config --exists 'libpulse >= 0.9' ; then + + cat > $TMPC << EOF +-#include <polyp/polyplib.h> +-#include <polyp/mainloop.h> +-#include <polyp/polyplib-error.h> ++#include <pulse/pulseaudio.h> + int main(void) { return 0; } + EOF +-cc_check `$_pkg_config --libs --cflags polyplib polyplib-error polyplib-mainloop` && tmp_run && _polyp=yes ++cc_check `$_pkg_config --libs --cflags libpulse` && tmp_run && _pulse=yes + + fi + fi +-echores "$_polyp" ++echores "$_pulse" + +-if test "$_polyp" = yes ; then +- _def_polyp='#define USE_POLYP 1' +- _aosrc="$_aosrc ao_polyp.c" +- _aomodules="polyp $_aomodules" +- _libs_mplayer="$_libs_mplayer `$_pkg_config --libs polyplib polyplib-error polyplib-mainloop`" +- _inc_extra="$_inc_extra `$_pkg_config --cflags polyplib polyplib-error polyplib-mainloop`" ++if test "$_pulse" = yes ; then ++ _def_pulse='#define USE_PULSE 1' ++ _aosrc="$_aosrc ao_pulse.c" ++ _aomodules="pulse $_aomodules" ++ _libs_mplayer="$_libs_mplayer `$_pkg_config --libs libpulse`" ++ _inc_extra="$_inc_extra `$_pkg_config --cflags libpulse`" + else +- _def_polyp='#undef USE_POLYP' +- _noaomodules="polyp $_noaomodules" ++ _def_pulse='#undef USE_PULSE' ++ _noaomodules="pulse $_noaomodules" + fi + + +@@ -8098,7 +8096,7 @@ + $_def_arts + $_def_esd + $_def_esd_latency +-$_def_polyp ++$_def_pulse + $_def_jack + $_def_openal + $_def_openal_h diff --git a/Software/PulseAudio/Documentation/User/PulseAudioStoleMyVolumes.mdwn b/Software/PulseAudio/Documentation/User/PulseAudioStoleMyVolumes.mdwn new file mode 100644 index 00000000..35e7fd77 --- /dev/null +++ b/Software/PulseAudio/Documentation/User/PulseAudioStoleMyVolumes.mdwn @@ -0,0 +1,46 @@ + +[[!inline pages="Software/PulseAudio/TOC" quick="yes" raw="yes"]] [[↩ Back to User Documentation|Software/PulseAudio/Documentation/User]] + + +# What PulseAudio does to your low-level mixer controls + +Since PulseAudio 0.9.16 we merge the capabilities of all hardware mixer controls that are in the mixer pipeline between the application writing the PCM audio and the speakers actually synthesizing the audio waves into one powerful synthetic control, and expose this as our user volume control. This has various advantages: a lot of complexity and user-unfriendliness is removed, as there is only one volume control for the entire pipeline. And when audio is too faint it is clear that it is this control that needs to be changed, the user no longer has to search which control is to blame for the wrong volume. Also, a lot of technical control names such as "PCM", "Master" and suchlike that are generally not understood by the average user are hidden. The resulting volume control will provide a range that is the combined range of all mixer controls it is built of, and the combined granularity of all mixer controls in the pipeline. Also, PulseAudio will make sure that the mixer controls are initialized in the optimal way, when two or more different ways exist to configure the same volume. i.e. if -3dB can be reached by setting PCM to -3dB and Master to 0dB OR by setting Master to -3dB and PCM to 0dB the latter is preferred. Finally, if a mixer element does not provide certain functionality (for example: independant per-channel volumes), other elements' capabilities can be used to add this. As last step PulseAudio will emulate in software all the functionality the entire pipeline of hardware volume elements cannot provide, thus providing the same level of functionality on all cards. + + +## So how does the algorithm work? + +First of all, when trying to understand the volume logic please do not think in percentages! Volume percentages are an artificial unit, whose definition changes between different hardware and different software. If you speak of 50% volume it is not clear what is meant by that in a device-independant way and what physically happens if you apply that. In fact the percantage scales of most sound cards are defined very arbitrarly. + +If talking about volumes, always talk about dB. If you don't know what dB are, [[read the Wikipedia page|http://en.wikipedia.org/wiki/Decibel]]. + +When PulsaAudio is asked to set a specific volume x in dB, it will go from the outermost to the innermost mixer element and apply the volume there: on consumer cards, the "Master" element is usually the outermost. Hence first it is asked to apply the volume x there. Of course, the hardware usually allows only a number of discrete volume steps, hence what can be applied is only a volume x' with x' near (and usually lower than) x. As next step we then subtract the volume adjustment done in 'Master' from the volume we want to set y = x - x'. (Remember that dB is logarithmic, so we actually divide the linear factors here). Then we apply y on the next element in the pipeline, in this case "PCM". Again, the hardware only knows a discrete step y', that is near to the requested y. Then again we subtract what we set from what we wanted: z = y - y'. Since this is the last element in our pipeline we apply that volume z in software. This example pipeline is very short. Depending on the sound card used the pipeline might get much longer. + +The effect of this logic is that "greatest" part of the volume adjustment is applied on the outermost volume element, while the inner elements are usually configured to something near 0dB. If the dB information exported by ALSA's mixer controls is correct this should be the optimal configuration: the outermost control usually influences an analog amp if there is any. The innermost controls should provide the maximum resolution while not inducing clipping. + + +## But this is evil, my PCM control is always set to 100% this way! + +First of all, as mentioned above please do not think in volume percentages! They have no meaning. Think in the dB values ALSA shows you, too. + +PulseAudio depends on the correctness of the dB information the ALSA drivers export. That means that the "inner" controls should usually be configured to something next to 0dB which is the optimal setting for getting the best resolution whith no distortion/clipping. If the inner controls are configured to a volume greater than 0dB this means that you requested an overall volume greater than the "base" volume. Simply lowering the overall volume to the base volume should then make sure clipping goes away. + +If you are experiencing distortions/clipping even though the inner volumes are set to 0dB, then this means that the dB information your ALSA driver exports is simply incorrect. In this case please file a bug against your audio driver and ask them to correct (i.e. shift up) the volume scale of that volume control. + + +## But I hate all this, you suck! + +We love you too. + +If you want to disable the merging of volume controls like this you may pass the 'control=' parameter to module-alsa-sink (and friends) and pass the name of a single mixer control that PulseAudio should control. PulseAudio will then refrain from changing any other controls. + + +## I think PulseAudio is confused about the order in which it applies volumes to the controls of my pipeline! + +The order in which PulseAudio applies volumes to the mixer controls is mostly based on assumptions (i.e. the control "Master" is more 'outside' than "PCM"). For almost all consumer cards these assumptions should be valid. However for some drivers this might turn out to be incorrect. In that case it is highly recommended to file a bug against those drivers so that their naming of mixer controls is fixed. If that is not possible or not applicable it is possible to influence the mixer handling of PulseAudio by editing the files in /usr/share/pulseaudio/alsa-mixer/paths/*, /usr/share/pulseaudio/alsa-mixer/profile-sets/* and /lib/udev/rules.d/90-pulseaudio.rules. + + +## I want to know more! + +[[Please read the initial announcement of the new mixer handling logic.|https://tango.0pointer.de/pipermail/pulseaudio-discuss/2009-June/004229.html]] This contains quite a few hints on the lower-level control functionality. + +[[Read this introduction on writing volume control UIs.|http://pulseaudio.org/wiki/WritingVolumeControlUIs]] If you want to do development with the volume control handling this is what you want to read. diff --git a/Software/PulseAudio/Documentation/User/Recipes/ActiveSpeakerCrossoverLADSPA.mdwn b/Software/PulseAudio/Documentation/User/Recipes/ActiveSpeakerCrossoverLADSPA.mdwn new file mode 100644 index 00000000..0c1f1e02 --- /dev/null +++ b/Software/PulseAudio/Documentation/User/Recipes/ActiveSpeakerCrossoverLADSPA.mdwn @@ -0,0 +1,110 @@ + + +## A digital crossover for an active-speaker-system: + +With LADSPA plugins applied to virtual sinks you can have a configurable active setup. You can seperate the sound for each of the speaker and apply equalisation and delay too. + + +#### ''summary'' + +-- This is a rather static setup so you do have to reload the virtual sinks if you change the LADSPA-filter parameters. + -- These are IIR filters, not FIR. + -- I would use a passive crossover (bipolar capacitors) for the tweeter so when PA would shut down for some reason and your tweeter got the full audio spectrum, it would not get fried. + -- I have an AMDX2 3800+ CPU and this setup is quite stable (since PA 0.9.16 CPU load has been about 2%). A kernel with high resolution timers (1000Hz) and realtime scheduling mode of PA is needed to keep the sinks in sync (under high system load) though. + + +#### ''software'' + +-- I installed LADSPA plugins from Steve Harris ([[[http://plugin.org.uk/|http://plugin.org.uk/]]]) and CMT ([[[http://www.ladspa.org/cmt/]).<<BR>>|http://www.ladspa.org/cmt/]).<<BR>>]] -- I tried two soundcards, a multichannel onboard soundchip (Realtek RC888) and an X-Fi Extreme Music. You need a channel for each speaker-driver so for four-way stereo speakers you need a 7.1 card. + -- The current pulse plugin for Mplayer and SDL seem broken, but the ESD-types are good alternatives. The Xine backend for Phonon in KDE4 doesn't support PA well either. + + + +--- + + + + +### 1. default.pa for a Realtek integrated audio with one surround device in ALSA: + +I left out automatic hardware detection and loaded a custom four-channel alsa-module instead (card number _0_ and its device _surround40_ - if you have two cards and 7.1 it may look like _device=surround71:1_ instead). The aux channels let PA override whatever the card "naturally" would want to do with them. Then I create LADPSA sinks for the crossover. Note that I have a mono setup so I use extra remap-sinks too (You have to set the combined sink to about 73% volume so the mono remapping doesn't generate clipping. Also descriptions for the sinks are changed because they get quite long by default. + + +[[!format txt """ +### LADSPA crossover +load-module module-alsa-sink sink_name=front_stereo sink_properties=device.description=front_stereo device=surround40:0 channels=4 channel_map=front-left,front-right,aux0,aux1 + +load-module module-remap-sink sink_name=sub sink_properties=device.description=sub master=front_stereo channels=1 master_channel_map=front-left channel_map=mono +load-module module-remap-sink sink_name=low master=front_stereo sink_properties=device.description=low channels=1 master_channel_map=front-right channel_map=mono +load-module module-remap-sink sink_name=mid sink_properties=device.description=mid master=front_stereo channels=1 master_channel_map=aux0 channel_map=mono +load-module module-remap-sink sink_name=high sink_properties=device.description=high master=front_stereo channels=1 master_channel_map=aux1 channel_map=mono + +load-module module-ladspa-sink sink_name=subHp sink_properties=device.description=subHp master=sub plugin=highpass_iir_1890 label=highpass_iir control=26,4 +load-module module-ladspa-sink sink_name=subLp sink_properties=device.description=subLp master=subHp plugin=lowpass_iir_1891 label=lowpass_iir control=40,4 + +load-module module-ladspa-sink sink_name=lowHp sink_properties=device.description=lowHp master=low plugin=highpass_iir_1890 label=highpass_iir control=60,4 +load-module module-ladspa-sink sink_name=lowLp sink_properties=device.description=lowLp master=lowHp plugin=lowpass_iir_1891 label=lowpass_iir control=290,2 +load-module module-ladspa-sink sink_name=lowEq sink_properties=device.description=lowEq master=lowLp plugin=single_para_1203 label=singlePara control=-8,300,1.9 + +load-module module-ladspa-sink sink_name=midDelay sink_properties=device.description=midDelay master=mid plugin=cmt label=delay_0.01s control=0.0001,0.00006 +load-module module-ladspa-sink sink_name=midHp sink_properties=device.description=midHp master=midDelay plugin=highpass_iir_1890 label=highpass_iir control=370,2 +load-module module-ladspa-sink sink_name=midLp sink_properties=device.description=midLp master=midHp plugin=lowpass_iir_1891 label=lowpass_iir control=2000,4 + +load-module module-ladspa-sink sink_name=highDelay sink_properties=device.description=highDelay master=high plugin=cmt label=delay_0.01s control=0.0005,0.00015 +load-module module-ladspa-sink sink_name=highHp sink_properties=device.description=highHp master=highDelay plugin=highpass_iir_1890 label=highpass_iir control=2100,4 + +load-module module-combine sink_name=jacks sink_properties=device.description=jacks slaves=subLp,lowEq,midLp,highHp + +set-default-sink jacks +"""]] + +### 2. default.pa for an X-Fi audio card with multiple stereo devices ALSA (one for each output jack): + +Here I left automatic hardware detection enabled (I use hw:0,0 for standard headphone output). Additionally loaded custom modules for hw:0,1 and hw:0,2. As above I create LADPSA sinks for the filters and combine them in the end. + + +[[!format txt """ +### LADSPA crossover +load-module module-alsa-sink sink_name=rearJack sink_properties=device.description=rearJack device=hw:0,1 +load-module module-alsa-sink sink_name=centreLfeJack sink_properties=device.description=centreLfeJack device=hw:0,2 channel_map=aux0,aux1 + +load-module module-remap-sink sink_name=sub sink_properties=device.description=sub master=rearJack channels=1 master_channel_map=front-left channel_map=mono +load-module module-remap-sink sink_name=low master=rearJack sink_properties=device.description=low channels=1 master_channel_map=front-right channel_map=mono +load-module module-remap-sink sink_name=mid sink_properties=device.description=mid master=centreLfeJack channels=1 master_channel_map=aux0 channel_map=mono +load-module module-remap-sink sink_name=high sink_properties=device.description=high master=centreLfeJack channels=1 master_channel_map=aux1 channel_map=mono + +load-module module-ladspa-sink sink_name=subHp sink_properties=device.description=subHp master=sub plugin=highpass_iir_1890 label=highpass_iir control=26,4 +load-module module-ladspa-sink sink_name=subLp sink_properties=device.description=subLp master=subHp plugin=lowpass_iir_1891 label=lowpass_iir control=40,4 + +load-module module-ladspa-sink sink_name=lowHp sink_properties=device.description=lowHp master=low plugin=highpass_iir_1890 label=highpass_iir control=60,4 +load-module module-ladspa-sink sink_name=lowLp sink_properties=device.description=lowLp master=lowHp plugin=lowpass_iir_1891 label=lowpass_iir control=290,2 +load-module module-ladspa-sink sink_name=lowEq sink_properties=device.description=lowEq master=lowLp plugin=single_para_1203 label=singlePara control=-8,300,1.9 + +load-module module-ladspa-sink sink_name=midDelay sink_properties=device.description=midDelay master=mid plugin=cmt label=delay_0.01s control=0.0001,0.00006 +load-module module-ladspa-sink sink_name=midHp sink_properties=device.description=midHp master=midDelay plugin=highpass_iir_1890 label=highpass_iir control=370,2 +load-module module-ladspa-sink sink_name=midLp sink_properties=device.description=midLp master=midHp plugin=lowpass_iir_1891 label=lowpass_iir control=2000,4 + +load-module module-ladspa-sink sink_name=highDelay sink_properties=device.description=highDelay master=high plugin=cmt label=delay_0.01s control=0.0005,0.00015 +load-module module-ladspa-sink sink_name=highHp sink_properties=device.description=highHp master=highDelay plugin=highpass_iir_1890 label=highpass_iir control=2100,4 + +load-module module-combine sink_name=jacks sink_properties=device.description=jacks slaves=subLp,lowEq,midLp,highHp + +set-default-sink jacks +"""]] + +### daemon.conf: + +I change the default resampler in ~/.pulse/daemon.conf as well. You may need to omit this if your CPU is too slow. My X-Fi sound-card wants 48KHz (I hear clicks on initialization when using 44.1kHz), so I put in a line for that too. + + +[[!format txt """ +resample-method = src-sinc-best-quality +default-sample-rate = 48000 +"""]] + + +--- + + + +Enjoy! :) diff --git a/Software/PulseAudio/Documentation/User/ServerStrings.mdwn b/Software/PulseAudio/Documentation/User/ServerStrings.mdwn new file mode 100644 index 00000000..cd063645 --- /dev/null +++ b/Software/PulseAudio/Documentation/User/ServerStrings.mdwn @@ -0,0 +1,30 @@ + +[[!inline pages="Software/PulseAudio/TOC" quick="yes" raw="yes"]] + + +# The Format of Server Strings + +A server string contains information how to contact a PulseAudio server. You can specify it via _$PULSE_SERVER_ or as first argument to _pa_context_new()_ or _pa_simple_new()_. Normally it should be OK to leave it alone, but sometimes it is necessary to specify your own. + +The server string is a space-seperated list of server addresses. A server address is parsed according the following rules: + +1. If it starts with a string enclosed in **{}** the address string is ignored unless the local hostname or D-Bus machine id equals the string in the **{}**. Otherwise this prefix is skipped. +1. If the string starts with **/** or **unix:** the remaining address string is taken as UNIX socket name. +1. If the string starts with **tcp4:** or **tcp:** the remaining address string is split at the next colon, the first part is taken as hostname/IP address for IPv4, the second part as port number. If no colon is specified the default port number is assumed and the full remaining string is used as hostname/IP address. +1. If the string starts with **tcp6:** a similar rule applies, but this time for IPv6 +1. Otherwise a similar rule applies, but it is left to the resolver whether IPv4 or IPv6 is used for the connection. +An example string: + + +[[!format txt """ +{ecstasy}unix:/tmp/pulse-6f7zfg/native tcp6:ecstasy.ring2.lan:4713 tcp:ecstasy.ring2.lan:4713 +"""]] +This tells PulseAudio to connect to the UNIX socket _/tmp/pulse-6f7zfg/native_ if the local host name is _ecstasy_. If that fails (or the hostname doesn't match) try to connect to host _ecstasy.ring2.lan_ on port 4713 usng TCP/IPv6. If even that fails, connect to the same host/port with TCP/IPv4. + +Another example string: + + +[[!format txt """ +gurki +"""]] +This tells PulseAudio to connect to the host _gurki_ with either IPv4/IPv6 and that's it. diff --git a/Software/PulseAudio/Documentation/User/Startup.mdwn b/Software/PulseAudio/Documentation/User/Startup.mdwn new file mode 100644 index 00000000..9a56e129 --- /dev/null +++ b/Software/PulseAudio/Documentation/User/Startup.mdwn @@ -0,0 +1,47 @@ + +[[!inline pages="Software/PulseAudio/TOC" quick="yes" raw="yes"]] + + +# Documentation + + +## Suggested implementation on Unix type systems + +To make the most portable, per-user daemon startup possible, use the X or Xorg Xsession or xinit mechanism. Because PulseAudio depends on a running console kit session, PulseAudio Daemon must be started after the call to ck-xinit-session. If care is taken to order the scripts properly, xinitrc.d could contain one script which starts console kit and another which starts PulseAudio Daemon. Otherwise, insert the PulseAudio startup line in the Xsession startup script before the desktop environment is started. + +Using this mechanism will ensure that no matter what window manager or desktop environment gets started, pulseaudio daemon will get started running as the logged in user. Individual desktop environments can then determine best how to hook into the PulseAudio Daemon, be it through the ESD replacement, through the ALSA layer, or via direct library support (e.g. Xine). + +Xsession specific modules should be loaded using the same mechanism. + + +## Existing Alternatives + + +### Gnome + +Gnome runs PulseAudio Daemon as part of the gnome session startup, but is the only desktop environment that has native support for starting the daemon. All other desktop environments implement session startup differently. + + +### KDE3 + +For KDE3, special care must be taken so that pulseaudio starts both after the console kit session, and before artsd starts. Otherwise an error message pops up in KDE3: +[[!format txt """ +Sound server informational message: +Error while initializing the sound driver: +device: default can't be opened for playback (Connection refused) +The sound server will continue, using the null output device. +"""]] + +### KDE 4.x + +In KDE4, Fedora 9 uses an env script to start PulseAudio Daemon as part of the KDE environment. + + +### OpenBox + +In [[OpenBox|OpenBox]] on Foresight Linux, a .desktop file is dropped into /etc/xdg/autostart to start the daemon. This solution required adding support for the xdg autostart mechanism in [[OpenBox|OpenBox]]. + + +## Loading X specific modules + +It appears that several Linux distros are using a .desktop file in /etc/xdg/autostart to load module-x11-xsmp. This is problematic as not all Desktop Environments support the xdg standard. diff --git a/Software/PulseAudio/Documentation/User/SystemWide.mdwn b/Software/PulseAudio/Documentation/User/SystemWide.mdwn new file mode 100644 index 00000000..4a2ec63e --- /dev/null +++ b/Software/PulseAudio/Documentation/User/SystemWide.mdwn @@ -0,0 +1,43 @@ + +[[!inline pages="Software/PulseAudio/TOC" quick="yes" raw="yes"]] + + +# Running PulseAudio as System-Wide Daemon + +Starting with PulseAudio 0.9.3 the daemon can be run as a system-wide instance which than can be shared by multiple local users. We recommend running the PulseAudio daemon per-user, just like the traditional ESD sound daemon. In some situations however, such as embedded systems where no real notion of a user exists, it makes sense to use the system-wide mode. + +Before you now go ahead and use it please read about [[what is wrong with system mode|Software/PulseAudio/Documentation/User/WhatIsWrongWithSystemWide]]. + +To run PulseAudio in system-wide mode, start it as `root` and pass the `--system` argument to it. It will then drop priviliges and change to the `pulse` UNIX user and group. The directory `/var/run/pulse/` is used as home directory. In this mode the module `module-native-protocol-unix` will automatically allow access to all members of the group `pulse-access`. All user/group names and paths can be changed by passing compile-time arguments to `configure`. The system user `pulse` and the groups `pulse` and `pulse-access` need to be created manually. On Debian this works like this: + + +[[!format txt """ +addgroup --system pulse +adduser --system --ingroup pulse --home /var/run/pulse pulse +addgroup --system pulse-access + +# Some distributions restrict access to the sound devices to a group audio +adduser pulse audio + +# Add a user to the pulse-access group +adduser lennart pulse-access +"""]] +The runtime directory `/var/run/pulse` is created automatically on daemon startup. This directory contains the .esd_auth file, which is the authentication cookie for esound. If you want to use esound without disabling authentication, create a symlink from this file in your home directory: + + +[[!format txt """ +ln -sf /var/run/pulse/.esd_auth ~/.esd_auth +"""]] +_Please note that creating these groups/users is not necessary when running the PulseAudio in the traditional per-user setup_ + +Running PulseAudio in system-wide mode has some limitations: + +* All users with access to the sound server cann kill/modify all sinks/sources and streams of all other connected clients +* There is only a single namespace for cached sound samples, i.e. there can be only a single Gnome event sound profile active at the same time +It has some disadvantages: + +* Worse security, because the user can now command a server app running under another user name. He could even load/unload modules from that sound server +* Settings like the stored volume levels managed by `module-volume-restore` are no longer per-user but system-wide +Read more about [[what is wrong with system mode|Software/PulseAudio/Documentation/User/WhatIsWrongWithSystemWide]]. + +If the system-wide mode is enabled it is advisable to disable module loading during runtime by passing `--disallow-module-loading` to the daemon, to inhibit the user from loading arbitrary modules with potentially vulnerable code into the daemon. However, this might break some modules like `module-hal-detect` which will load a sound driver module each time HAL signals that a new sound card became available in the system. diff --git a/Software/PulseAudio/Documentation/User/WhatIsWrongWithSystemWide.mdwn b/Software/PulseAudio/Documentation/User/WhatIsWrongWithSystemWide.mdwn new file mode 100644 index 00000000..67b36f14 --- /dev/null +++ b/Software/PulseAudio/Documentation/User/WhatIsWrongWithSystemWide.mdwn @@ -0,0 +1,37 @@ + + +# What is wrong with system mode? + +Many folks seem to think it is a good idea to run PA in [[system mode|Software/PulseAudio/Documentation/User/SystemWide]]. But it is not. Nobody should run it that way, with the exception of very few cases, which are listed further down. + +Here are a couple of reasons why running PA in system mode is a bad idea. + +* Security: Much like the X server as soon as you are authenticated you have complete control of the sound server, no further per-object access checks are done. +* When in system mode, module loading after startup is disabled for security reasons, which means: no hotplug handling in system mode +* When in system mode, shared memory data transport is disabled for security reasons, which means: much higher memory usage and CPU load in system mode +* The module-xxx-restore modules maintain state that is inheritely user specific, but when run in system mode is shared between users. +* Security: there are no size limits on state data, which enables users to flood /var unless you employ quotas on the pulse user +* Security: all users that have access to the server can sniff into each others audio streams, listen to their mikes, and so on. +* When in system mode you also lose a lot of further functionality, like the bridging to jack, to rygel (upnp), to X11, to ckit, and so on +And, most importantly: it is explicitly not designed for it, you are on your own if you use it. The maintainer's interest in making sure system mode is well supported is rather minimal. + + +# So why have it then? + +System mode is around for usage on thin client or embedded setups, wher no real local user exists, where access is exclusively via the network, and where state data is flushed on each session termination. + +Or with other words: if you run it that way on your desktop, then you are doing it the wrong way. + + +# So you want to set it up nonetheless? + +You are on your own. You need to know you way around, be able to write init scripts, dbus policies, to fix up device permissions, and unix users, you need to pass around security cookies and more. + +You are expected to know your way around if you use system mode. You are using PA against the explicit recommendations of the maintainers, so **don't expect particularly enthusiastic support from them in doing so**. + +Good luck! + + +# But my distro is shipping an init script for PA! + +Ignore that. It's stupid. They shouldn't be doing this. diff --git a/Software/PulseAudio/Documentation/Users/Troubleshooting.mdwn b/Software/PulseAudio/Documentation/Users/Troubleshooting.mdwn new file mode 100644 index 00000000..460567c8 --- /dev/null +++ b/Software/PulseAudio/Documentation/Users/Troubleshooting.mdwn @@ -0,0 +1,103 @@ + +[[!inline pages="TroubleshootingTOC" quick="yes" raw="yes"]] + +_Note that this is a stub and needs some substantial work to get actually usable_ + + +# Troubleshooting + +Now that more and more distros (e.g. Fedora, Mandriva, Ubuntu etc.) are switching to use [[PulseAudio|PulseAudio]] by default, and also because nothing is perfect (except freshly made doughnuts!) this page will lead you through a few tests and processes to check your pulseaudio installation is working properly. + + +## Is Pulseaudio running? + +This is the software equivalent of the "is it turned on at the wall" question! You can run the command `ps aux | grep pulseaudio` to see if there is a pulseaudio process currently running (ignore the grep command if it shows up in the list returned!). If pulseaudio is not running, you can start it by running `pulseaudio -D`, although it is probably better to understand **why** it is not running. Different distributions start pulseaudio in different ways, and, as of v0.9.11, pulseaudio will actually autospawn itself whenever anything needs to make use of it. Typically, to start pulse at X11 login and keep it running (so it can detect removable, bluetooth and network sound devices), an XDG _.desktop_ file is used to run the script `start-pulseaudio-x11`. Please ask your distro support group for more info if you are interested in the startup procedure. + + +## Pulse is running but I hear no sound + +OK, so we know that pulseaudio is running, but when you play something, you don't hear anything. Let's start with the basics: + +* If you have a desktop computer, are your speakers plugged in correctly to the (usually) green socket? +* Do the speakers still work? (try plugging in your mp3 player to test!). +* Do you have multiple sound cards, and have you tried the speakers in all of them to make sure you're using the device you think you are? +I know the above may be simple and obvious sounding, but please do check this and don't skip this check as it can (and does) happen to the best of us! + +OK, so we know sound is physically capable of coming out of our speakers. Now you should run `pavucontrol` and check under the "Output Devices" tab to see if your sound hardware is listed there. If pulseaudio cannot open the hardware device on startup (e.g. due to the device being "hogged" by some other application), then it will automatically load a "NULL sink" for you. This appears to your applications like everything is working correctly but will silently discard all the audio data. This is done because many applications do not like it when sound hardware is not present in pulseaudio. If you find that the "Output Devices" tab shows only the automatic NULL sink, you need to debug what other applications are using your sound hardware on startup or find out why pulse cannot open your hardware. Running `fuser /dev/snd/*` may give some clues as to what applications are hogging things, and failing any information from this, you can run `pulseaudio -k; pulseaudio -vvv`. The lines beginning with `E:` specifically may give some clues. + + +## Pulse is running and has loaded my devices + +OK, so let's test a few things. First things first, make sure you can hear sound output directly to ASLA. The easiest way to do this is with mplayer. Find some music track (e.g. an MP3 or Ogg file) and run `mplayer -ao alsa:device=hw=0 yourchosentrack.mp3`. This should play your track and bypass pulseaudio completely. If you still hear nothing then the problem is at the level below pulse. + + +## I don't hear any output from sound applications + +Open a terminal and try playing a sound with `paplay`: + + +[[!format txt """ +$ paplay /usr/share/sounds/generic.wav +$ +"""]] +In case you don't see any error message and hear the sound, your applications need to be configured to use [[PulseAudio|PulseAudio]]. See [Software/PulseAudio/Documentation/User/PerfectSetup#[[ThirdPartyApplications|ThirdPartyApplications]] the relevant section in [[Perfect Setup|Software/PulseAudio/Documentation/User/PerfectSetup]]]. + +If you neither get an error message, nor hear the sound, check volume settings. For pulseaudio, use `pavucontrol` utlity. For ALSA use `alsamixer -c 0`. + + +[[!format txt """ +$ paplay /usr/share/sounds/generic.wav +Connection failure: Connection refused +$ +"""]] +This most likely means that [[your pulseaudio server is not running|Software/PulseAudio/Documentation/Users/Troubleshooting]]. + + +## Sound server is not running + +Check that it is enabled to be started up in your desktop environment. See relevant sections of [[Perfect Setup|Software/PulseAudio/Documentation/User/PerfectSetup]] for [Software/PulseAudio/Documentation/User/PerfectSetup#GNOME GNOME] and [Software/PulseAudio/Documentation/User/PerfectSetup#KDE KDE]. Note that your OS distribution may already take care of this via dedicated packages. + +Look into logs for reason why might pulseaudio startup have failed: +[[!format txt """ +# grep pulseaudio /var/log/messages +"""]] +Try to launch pulseaudio manually with verbose output enabled: (the output might be valuable to troubleshoot a potential bug) + + +[[!format txt """ +$ pulseaudio -vvv +"""]] +If your output seems like following, you might not have permissions to access the sound device: + + +[[!format txt """ +D: alsa-util.c: Trying front:0... +ALSA lib conf.c:3949:(snd_config_expand) Unknown parameters 0 +ALSA lib pcm.c:2145:(snd_pcm_open_noupdate) Unknown PCM front:0 +I: alsa-util.c: Couldn't open PCM device front:0: Invalid argument +D: alsa-util.c: Trying surround40:0... +ALSA lib conf.c:3949:(snd_config_expand) Unknown parameters 0 +ALSA lib pcm.c:2145:(snd_pcm_open_noupdate) Unknown PCM surround40:0 +I: alsa-util.c: Couldn't open PCM device surround40:0: Invalid argument +D: alsa-util.c: Trying surround41:0... +ALSA lib conf.c:3949:(snd_config_expand) Unknown parameters 0 +ALSA lib pcm.c:2145:(snd_pcm_open_noupdate) Unknown PCM surround41:0 +I: alsa-util.c: Couldn't open PCM device surround41:0: Invalid argument +D: alsa-util.c: Trying surround50:0... +ALSA lib conf.c:3949:(snd_config_expand) Unknown parameters 0 +ALSA lib pcm.c:2145:(snd_pcm_open_noupdate) Unknown PCM surround50:0 +I: alsa-util.c: Couldn't open PCM device surround50:0: Invalid argument +D: alsa-util.c: Trying surround51:0... +ALSA lib conf.c:3949:(snd_config_expand) Unknown parameters 0 +ALSA lib pcm.c:2145:(snd_pcm_open_noupdate) Unknown PCM surround51:0 +I: alsa-util.c: Couldn't open PCM device surround51:0: Invalid argument +D: alsa-util.c: Trying surround71:0... +ALSA lib conf.c:3949:(snd_config_expand) Unknown parameters 0 +ALSA lib pcm.c:2145:(snd_pcm_open_noupdate) Unknown PCM surround71:0 +I: alsa-util.c: Couldn't open PCM device surround71:0: Invalid argument +D: alsa-util.c: Trying hw:0 as last resort... +ALSA lib pcm_hw.c:1207:(_snd_pcm_hw_open) Invalid value for card +E: alsa-util.c: Error opening PCM device hw:0: No such device +E: module.c: Failed to load module "module-alsa-sink" (argument: "device_id=0 sink_name=alsa_output.pci_8086_284b_sound_card_0_alsa_playback_0"): initialization failed. +"""]] +Check the permission with `getfacl /dev/snd/*`. diff --git a/Software/PulseAudio/Download.mdwn b/Software/PulseAudio/Download.mdwn new file mode 100644 index 00000000..7e505090 --- /dev/null +++ b/Software/PulseAudio/Download.mdwn @@ -0,0 +1,66 @@ + +[[!inline pages="Software/PulseAudio/TOC" quick="yes" raw="yes"]] [[!toc ]] + + +# Download PulseAudio + + +## Distribution + +Typically PulseAudio would be provided by your OS distribution. As PulseAudio forms part of what is typically preferred to as the _plumbing layer_ of Linux userspace, it is a non-trivial job to integrate it fully to form a complete system. This is why we **strongly** encourage you to go via your distribution whenever possible. + + +## Source Code + +The current releases can always be found in our [[releases directory|http://freedesktop.org/software/pulseaudio/releases/]]. + + +## Development Sources + +Current development sources of PulseAudio are managed with [[GIT|http://git-scm.com/]] hosted here on [[freedesktop.org|http://www.freedesktop.org/wiki/]]. Browse the repository [[online|http://cgit.freedesktop.org/pulseaudio/pulseaudio/]] or check out the code with: + + +[[!format txt """ +git clone git://anongit.freedesktop.org/pulseaudio/pulseaudio +"""]] +Alternatively if you have trouble connecting (due to firewalls and such), try with the slower HTTP protocol: `git clone http://anongit.freedesktop.org/git/pulseaudio/pulseaudio.git` + +[[Read this explanation about the Git Branches and the release cycle|http://pulseaudio.org/wiki/GitBranches]]. + + +## Windows Binaries + +Windows is also supported thanks to our awesome community. For more information, see [[Windows Support|Software/PulseAudio/Ports/Windows/Support]]. + + +## Build Dependencies + +* [[libsndfile|http://www.mega-nerd.com/libsndfile/]] (>= 1.0.18) +* [[libatomic_ops 1.2|http://www.hpl.hp.com/research/linux/atomic_ops/]] or newer (1.1 and older do not work in all situations, and result in inline assembly compilation failures when compiling PulseAudio) Download v1.2 from [[libatomic_ops-1.2.tar.gz|http://www.hpl.hp.com/research/linux/atomic_ops/download/libatomic_ops-1.2.tar.gz]] +* [[libspeexdsp|http://www.speex.org/downloads/]] Required as of 0.9.11, >= 1.2rc1 as of 1.0 +* [[libtool|http://www.gnu.org/software/libtool/libtool.html]] (>= 2.4) +* [[json-c|http://oss.metaparadigm.com/json-c/]] (>= 0.9, required as of 1.0) +* [[libsamplerate|http://www.mega-nerd.com/SRC/]] (optional) +* [[X11|http://x.org/]] (optional) +* [[libcap|http://www.kernel.org/pub/linux/libs/security/linux-privs/libcap2]] (optional) +* [[alsa-lib|http://alsa-project.org/]] (optional) (alsa-lib 1.0.17 or later required for ALSA support with PulseAudio 0.9.11 or later. PulseAudio will still build if your ALSA is older, but it will not have ALSA support enabled.) +* [[glib 2.0|http://gtk.org/]] (optional) +* [[Avahi|http://avahi.org/]] (optional) +* [[jack|http://jackaudio.org/]] (optional) +* [[libasyncns|http://0pointer.de/lennart/projects/libasyncns/]] (optional) +* [[tcpwrap|ftp://ftp.porcupine.org/pub/security]] (optional) +* [[lirc|http://www.lirc.org/]] (optional) +* [[BlueZ|http://www.bluez.org/download/]] (>= 4.99, optional) +* [[[ftp://ftp.gnome.org/pub/GNOME/sources/GConf/|ftp://ftp.gnome.org/pub/GNOME/sources/GConf/]] GConf 2.0] (optional as of 0.9.12) +* [[D-Bus|http://www.freedesktop.org/wiki/Software/dbus]] (>= 1.4.12, optional) +* [[fftw|http://www.fftw.org/]] (>= 3.0, optional as of 1.0, used for the equalizer plugin) +* [[orc|http://code.entropywave.com/projects/orc/]] (>= 0.4.9, optional as of 1.0) +* [[libgdbm|http://www.gnu.org/software/gdbm/]] (mandatory from 0.9.11 to 0.9.15, optional as of 0.9.16) +* [[libtdb|http://tdb.samba.org/]] (optional as of 0.9.16) +* [[Check|http://check.sourceforge.net/]] (optional) +* [[sbc|http://www.kernel.org/pub/linux/bluetooth/]] (>= 1.0, optional) + +## Runtime Dependencies + +* [[RealtimeKit|http://git.0pointer.de/?p=rtkit.git]] (optional) +Can't find the dependencies on your distribution? Check out the [[DependenciesListDistroSpecific|DependenciesListDistroSpecific]] page. diff --git a/Software/PulseAudio/FAQ.mdwn b/Software/PulseAudio/FAQ.mdwn new file mode 100644 index 00000000..37eb0b7f --- /dev/null +++ b/Software/PulseAudio/FAQ.mdwn @@ -0,0 +1,468 @@ + +[[!inline pages="Software/PulseAudio/TOC" quick="yes" raw="yes"]] + + +# Frequently Asked Questions + +**Some of the answers need updating! ** Also, some questions are too long for the outline, and they get truncated. + + + +--- + + [[!toc 3]] + +--- + + + + +## Uncategorized questions + + +### How does PulseAudio compare with ESOUND/aRts/NAS? + + * PulseAudio is sound daemon similar to ESOUND and NAS, but much more powerful. aRts is a realtime-synthesizer-cum-sound-server, i.e. it does much more than PulseAudio. However, I believe that PulseAudio does what it does much better than any other free sound server. + +### Is PulseAudio a GNOME program? + + * No, PulseAudio has no dependency on GNOME/GTK/GLIB. All it requires is a UNIX-like operating system and very few dependency libraries. However, the accompanying GUI tools are written with gtkmm, i.e. require both GLIB and GTK. + +### I want to write a new driver for PulseAudio, are there any docs? + + * Support for audio backends is added by writting a new module. Currently, only the client API is documented with doxygen, for module development you have to use the internal API of [[PulseAudio|PulseAudio]]. Read the source and base your work on a simple module like `module-pipe-sink`, `module-oss` or `module-virtual-{sink,source`}. See [Software/PulseAudio/Documentation/Developer#[[DevelopingModules|DevelopingModules]] [[DevelopingModules|DevelopingModules]]] for more information. + +### How does PulseAudio acquire realtime capabilities? + + * PulseAudio activates SCHED_FIFO scheduling if the user passes `--high-priority=1`. For the root user this will succeed. For normal users `rtkit` is used to give PulseAudio realtime priviliges. + +### What environment variables does PulseAudio care about? + + * The client honors: + * `$PULSE_SINK` (default sink to connect to) + * `$PULSE_SOURCE` (default source to connect to) + * `$PULSE_SERVER` (default server to connect to, like `ESPEAKER`, see [[Server Strings|Software/PulseAudio/Documentation/User/ServerStrings]] for an explanation of the format) + * `$PULSE_BINARY` (the binary to start when autospawning a daemon) + * `$PULSE_CLIENTCONFIG` (path to the client configuration file). + * `$PULSE_PROP` (A space seperated list of properties of the form 'media.role=event' to set for all streams) + * `$PULSE_PROP_xxxx` (Set property xxx for all streams) + * The daemon honors: + * `$PULSE_SCRIPT` (default CLI script file run after startup) + * `$PULSE_CONFIG` (default daemon configuration file) + * `$PULSE_DLPATH` (colon separated list of paths where to look for modules) + * `$PULSE_NO_SIMD` (disable SIMD optimizations. i.e. MMX, SSE, NEON) + +### How do the PulseAudio libraries decide where to connect to? + + * The following rule applies: (see [[Server Strings|Software/PulseAudio/Documentation/User/ServerStrings]] for an explanation of the format of server specifications) + * If the the application using the library specifies a server to connect to it is used. If the connection fails, the library fails too. + * If the environment variable `$PULSE_SERVER` is defined the library connects to that server. If the connection fails, the library fails too. + * If `$DISPLAY` is set, the library tries to connect to that server and looks for the root window property `PULSE_SERVER` for the host to connect to. If `PULSE_COOKIE` is set it is used as authentication cookie. + * If the client configuration file (`~/.pulse/client.conf` or `/etc/pulse/client.conf`) sets the server address, the library connects to that server. If the connection fails, the library fails too. + * The library tries to connect to the default local UNIX socket for PulseAudio servers. If the connection fails, it proceeds with the next item. + * The library tries to connect to the default local TCP socket for PulseAudio servers. If the connection fails, it proceeds with the next item. + * If `$DISPLAY` is set, the library tries to connect to the default TCP port of that host. If the connection fails, it proceeds with the next item. + * The connection fails. + +### Why the heck does libpulse link against libX11? + + * The PulseAudio client libraries look for some X11 root window properties for the credentials of the PulseAudio server to access. You may compile PulseAudio without X11 for disabling this feature. + +### Why did you rename Polypaudio to PulseAudio? + + * Please read this [[blog story|http://0pointer.de/blog/projects/pulse.html]] for an explanation. + +## Compatibility with other software + + +### What about ESOUND compatibility? + + * PulseAudio is a drop in replacement for ESOUND. That means: you can load a esound compatibility module which implements an ESOUND compatible protocol which allows you to use most of the classic ESOUND compatible programs (including the command line programs like `esdcat`). + +### Can I integrate PulseAudio in my GLIB/GTK/GNOME application? + + * Yes! PulseAudio comes with a GLIB main loop adapter. You can embed both the client library and the daemon (!) into your GLIB based application. + +### Can I integrate PulseAudio in my Qt/KDE application? + + * Yes! PulseAudio uses a main loop abstraction layer that allows you to integrate PulseAudio in any program that supports main loops. Unfortunately there is no adapter for Qt publicly available yet. + +### What about compatibility with NAS? + + * Is not available (yet?). It is doable, but noone has implemented it yet. + +### What about compatibility with aRts? + + * Is not available. Since aRts is as synthesizer application you'd have to reimplement very much code for PulseAudio. It should be easy to implement limited support for libartsc based applications. Noone has done this yet. It is probably a better idea to run arts on top of PulseAudio (through a PulseAudio driver for aRts, which nobody has written yet). Another solution would be to embed PulseAudio in the aRts process. + +### Can I get OSS and ALSA applications to work with PulseAudio? + + * Yes, you can! OSS applications are handled using the `padsp` utility shipped with PulseAudio: + +[[!format txt """ +padsp myapp <arguments to myapp> +"""]] + * ALSA applications are handled using the PulseAudio backend for alsa-lib. Documentation and the backend itself are shipped in the alsa-plugins package as part of the ALSA project. + +### Is there a Win32/Windows driver that act like a PulseAudio client? + + * Not exactly, but there use to be a ESoundD driver like that, and [[PulseAudio|PulseAudio]] can connect to a ESoundD client. + This project is [[WinESD|http://www.clingman.org/winesd/]] at [[WinESD|http://www.clingman.org/winesd/]]. This software was developped for NT4 and Windows 2000. It has been reported to work under Windows XP connected to a [[PulseAudio|PulseAudio]] server (One computer under Microsoft Windows XP using WinESD, connected to another computer under Microsoft Windows XP using [[PulseAudio|PulseAudio]]). This project looks unmaintained and last version was "pre-alpha". It still works, but with restrictions : + * Sometimes, the sound is "broken". It look like it's when two processes try to emit sounds in the same time. Perhaps it's different from one computer to another. + * There is no easy installers as for July 2007, neither for WinESD nor [[PulseAudio|PulseAudio]] for Win32/Windows. It's a "Let's play with configuration by hands" installation. + * You need to unactivate your sound card if you already have one on the computer running WinESD. This will need a reboot. This is undocumented on the [[WinESD site|http://www.clingman.org/winesd/]]. + * Switching from one driver to another will need to play with Activate/Unactivate drivers, which will cause reboot. + +## Troubleshooting + + +### I get this error message: "Connection refused" + + * It is a network level error, which is caused by libpulse trying to connect to the daemon. The most likely reason for this error is that pulseaudio isn't running. + +### I get this error message: "Invalid argument" + + * A likely reason for this is that no devices have been loaded. Stop pulseaudio (run "pulseaudio -k"), and start it again with "pulseaudio -vv". That will print verbose output of the daemon startup. If you can't figure out what might go wrong yourself, send a link to the whole output of the command to the irc channel (see [[Community|Software/PulseAudio/Documentation/User/Community]]). (Help is not guaranteed. Patience is a virtue.) + +### I often hear noises when playing back with PulseAudio, what can I do? + + * There are two possible solutions: run PulseAudio with argument `--high-priority=1` and make yourself member of the group `pulse-rt`, or increase the fragment sizes of the audio drivers. The former will allow PulseAudio to activate `SCHED_FIFO` high priority scheduling (root rights are dropped immediately after this). Keep in mind that this is a potential security hole! + +### I have a surround sound card, but PulseAudio uses just the front speakers! + + * Many people have a surround card, but have speakers for just two channels, so PulseAudio can't really default to a surround setup. To enable all the channels, edit `/etc/pulse/daemon.conf`: uncomment the `default-sample-channels` line (i.e. remove the semicolon from the beginning of the line) and set the value to 6 if you have a 5.1 setup, or 8 if you have 7.1 setup etc. After doing the edit, restart pulseaudio. + +### When sending multicast RTP traffic it is recieved on the entire LAN but not by the sender machine itself! + + * Pass `loop=1` to the sender module! + +### Hmm, tcpwrap (aka /etc/hosts.allow, /etc/hosts.deny) support doesn't work properly for me! + + * Have you compile [[PulseAudio|PulseAudio]] with tcpwrap support? Are you using the right tcpwrap service name? PA uses five different names for its five protocols: + +[[!format txt """ +pulseaudio-native +pulseaudio-simple +pulseaudio-cli +pulseaudio-http +esound +"""]] + +### Why doesn't the system-wide mode detect my default.pa file? Or, why does the system-wide daemon exit telling me there are no modules? + +As of [[PulseAudio|PulseAudio]] 0.9.11, the system-wide daemon looks for a separate pa file by default: /etc/pulse/system.pa + +If you want to continue using default.pa for system-wide mode, just symlink /etc/pulse/default.pa to /etc/pulse/system.pa. + + +### Why do I not see remote sinks in control applications? + +Sending a stream to a remote server is done through control apps such as pavucontrol or padevchooser (marked obsolete). The streams to choose from are selected using zeroconf (avahi) publishing and discovering of services. If pavucontrol or padevchooser does not list a sink on a remote server the problem can be that the server is not reachable or the zeroconf mechanism is not working. + +1. Make sure your host is reachable, firewall allows connections, cables are plugged in, whatever, ... + +2. Check if you can reach the remote server using the PULSE_SERVER environment variable from CLI: run a pulseaudio configured application like this: +[[!format txt """ +$ PULSE_SERVER=<hostname> <command> +"""]] +If your host does not start playing you need to fix the network protocols supported by your server. Refer to protocol sections in the [[Modules|Software/PulseAudio/Documentation/User/Modules]] page, refer to [[Server Strings|Software/PulseAudio/Documentation/User/ServerStrings]] page, refer to FAQ item [[How do I use PulseAudio over the network?|Software/PulseAudio/FAQ]]. + +Assuming that your host started playing we can probably limit the problem to zeroconf. + +3. Check that module-zeroconf-publish is loaded on the remote server using paman: +[[!format txt """ +$ PULSE_SERVER=<hostname> paman +"""]] +and that module-zeroconf-discover is loaded on the local server, also using paman. + +If either are not, load them and see if the sink is discovered. + +4. Check, using avahi-browse (in avahi-utils for debian based distros), that services are discovered okay. Use following command on both the local and the remote end to dump all (-a) services found on the network and the terminate (-t) the avahi-browse process after dumping: +[[!format txt """ +$ avahi-browse -ta +"""]] +If in this step the remote end does not show the PulseAudio services locally then check avahi configuration for things like disabled publishing for example. Consider restarting the avahi process. Make sure firewalls allow the avahi traffic. ... + + +### alsmamixer doesn't work since making the pulse plugin the alsa default + +Normally, volume can be adjusted in alsamixer using the Up/Down Arrow keys. After [[making ALSA use PulseAudio by default|Software/PulseAudio/Documentation/User/PerfectSetup]], the mixer/control/slider presented as PulseAudio in alsamixer doesn't respond to the up/down arrow keys. + +The up/down are actually working, incrementing or decrementing the volume by 1 unit, but the pulse alsa plugin provides about 65k (16 bits of) volume levels, so you won't notice a 1/65,536 adjustment. Remember this too when passing hardware values to amixer. + +You can adjust the volume in alsamixer from 0 to 90% in 1/9 increments with the number keys 0-9. + + +### Sound doesn't work when switching users + +PulseAudio works with a single user, but when an additional user logs in ([[fast user switching|http://en.wikipedia.org/wiki/Fast_user_switching]]), sound/audio does not work for the additional user. + +Check that no users are part of the "audio" [[group|http://en.wikipedia.org/wiki/Group_identifier_%28Unix%29]]. + +In simple setups (e.g. singe user, without PulseAudio), users must be a member of the "audio" group to access the sound devices (/dev/snd/* (which have group "audio" write permissions)). Switching users will not automatically stop programs using those sound devices though, so those sound devices will not be accessible to a new (faster user switched) user's programs. + +By removing all users from the "audio" group (the PulseAudio server still runs in the "audio" group), PulseAudio is able manage access to sound devices (/dev/snd/*) amongst multiple users with the help of [[ConsoleKit|http://www.freedesktop.org/wiki/Software/ConsoleKit]]. + + +## I want to do this specific thing... + + +### I want to run PulseAudio only when it is needed, how do I do this? + + * Set `autospawn = yes` in `client.conf`. That configuration file may be found either in `/etc/pulse/` or in `~/.pulse/`. + +### How do I list all PulseAudio modules installed? + + +[[!format txt """ +pulseaudio --dump-modules +"""]] + * Add `-v` for terse usage instructions. + +### How do I use PulseAudio over the network? + +See the wiki page about [[Network Setup|Software/PulseAudio/Documentation/User/Network]]. + + +### I saw that {{{SIGUSR2}}} provokes loading of the module {{{module-cli-protocol-unix}}}. But how do I make use of that? + + * A brilliant guy named Lennart Poettering once wrote a nifty tool for that purpose: [[bidilink|http://0pointer.de/lennart/projects/bidilink/]]. To connect to a running PulseAudio daemon try using the following commands: + +[[!format txt """ +killall -USR2 pulseaudio +bidilink unix-client:/tmp/pulse-$USER/cli +"""]] + * _BTW: Someone should package this great tool for Debian! _ + **New:** There's now a tool `pacmd` that automates sending `SIGUSR2` to the daemon and running a bidilink like tool for you. + +### Can I use PulseAudio to playback music on two sound cards simultaneously? + + * Yes! Use `module-combine` for that. + +[[!format txt """ +load-module module-alsa-sink device="front:Intel" sink_name=output0 +load-module module-alsa-sink device="front:HDA" sink_name=output1 +load-module module-combine sink_name=combined slaves=output0,output1 +set-sink-default combined +"""]] + * This will combine the two sinks `output0` and `output1` into a new sink combined. Every sample written to the latter will be forwarded to the former two. PulseAudio will make sure to adjust the sample rate of the slave device in case it deviates from the master device. You can have more than one slave sink attached to the combined sink, and hence combine even three and more sound cards. +Much fancier is to use the automatic mode. To make use of that simply check the "Simultaneous Output" checkbox in paprefs. + + +### Can I use PulseAudio to combine two stereo soundcards into a virtual surround sound card? + + * Yes! You can use use `module-combine` for that. + +[[!format txt """ +load-module module-oss-mmap device="/dev/dsp" sink_name=output0 channel_map=left,right channels=2 +load-module module-oss-mmap device="/dev/dsp1" sink_name=output1 channel_map=rear-left,rear-right channels=2 +load-module module-combine sink_name=combined master=output0 slaves=output1 channel_map=left,right,rear-left,rear-right channels=4 +"""]] + * This is mostly identical to the previous example. However, this time we manually specify the channel mappings for the sinks to make sure everything is routed correctly. + Please keep in mind that PulseAudio will constantly adjust the sample rate to compensate for the deviating quartzes of the sound devices. This is not perfect, however. Deviations in a range of 1/44100s (or 1/48000s depending on the sampling frequency) can not be compensated. The human ear will decode these deviations as minor movements (less than 1cm) of the positions of the sound sources you hear. + +### How can use my Windows box to play the sound from my Linux box? + + * Download the windows binary of pulseaudio from the download page. + * In the pulseaudio directory, create a file **default.pa** whith a content similar to this one (you may have to adjust the auth-ip-acl to reflect your network's settings): + +[[!format txt """ +load-module module-waveout + +load-module module-native-protocol-tcp auth-ip-acl=127.0.0.1;192.168.0.0/16 +"""]] + * In pulseaudio applet: PA applet -> Default Server -> Other -> Enter the hostname or ip of your windows box. + +### How can I reverse my left and right speaker channels? + +This is the same as "reverse stereo", where the left and right channels are to be swapped. + + * cat /proc/asound/cards and use the name string for the device you wish to use (the one in square brackets) + * Edit /etc/pulse/default.pa and comment out module-hal-detect and module-detect lines. + * Search for the commented-out line that starts "#load-module module-alsa-sink", uncomment it and change it to + +[[!format txt """ +load-module module-alsa-sink device=hw:[answer from step 0] channel_map=right,left +"""]] + * Restart the pulseaudio deamon by running `pulseaudio -k; pulseaudio -D` + +### How do I record stuff? + +(Question added 2009-03-14) + + +#### Selecting the input device + +Most recording programs use ALSA. In those cases you need to set the input device in the recording program to be either "default" (if you have PulseAudio set up as the default ALSA device) or whatever name you or your distribution has set up for the pulse plugin for ALSA. If the recording program offers input devices that have a more descriptive name, including the sound card name or something like that, don't choose those, because in those cases the recording program will access the sound card directly (that may not be such a bad thing, actually, if you don't have any real reason to record through PulseAudio). + +If the recording program uses ALSA, and you configure it to use the pulse plugin (as described in the previous paragraph), then the real device you will use depends on which source (source is a PulseAudio term for input devices, physical or virtual) is the default. If you're not happy with the default, you can change the default for example with pavucontrol, but there's another way to choose the device. When the PULSE_SOURCE environment variable is set when starting the recording program, the environment variable will be used to select the source. So, if we assume that you want to use the fictious myrecordingapp program, you would start it in the console like this: + + +[[!format txt """ +PULSE_SOURCE=<source_name> myrecordingapp +"""]] +<source_name> is of course the name of the source you want to use, but how to find out what the name is? This command lists all available sources: + + +[[!format txt """ +LANG=C pactl list | grep -A2 'Source #' | grep 'Name: ' | cut -d" " -f2 +"""]] +The names can be rather cryptic, but hopefully you can figure out which name identifies which source. + + +#### Which program to use for recording + +I don't do any recording myself, so I'm not an expert on what is available, but here is some information anyway. If you know more, please edit this! The situation for PulseAudio support in GUI programs doesn't look too good. Audacity is quite nice, but getting it to work can currently be a hassle. See [[Perfect Setup|Software/PulseAudio/Documentation/User/PerfectSetup]]#Audacity for more information. I gave Jokosher 0.9 a quick try recently, but didn't get it to work properly. In my experience, command line programs work much better (you can of course edit the file with any program you want after recording it). The two programs I have tested are arecord (comes with ALSA) and parec (comes with PulseAudio). I'll give an example command for both: + +parec: + + +[[!format txt """ +parec --device=alsa_input.usb_device_46d_990_BF15FF18_if2_alsa_capture_0 --format=s16le --rate=44100 --channels=2 | sox --type raw -s2L --rate 44100 --channels 2 - --type wav output.wav +"""]] +As you can see, in addition to parec, we use sox. That is done because parec generates only raw data, which is not nice to work with. sox is used to add the WAV header to the file. For information about parec and sox parameters, see `parec --help` and `man sox`, respectively. + +arecord: + + +[[!format txt """ +PULSE_SOURCE=alsa_input.usb_device_46d_990_BF15FF18_if2_alsa_capture_0 arecord --format=S16_LE --rate=44100 --channels=2 output.wav +"""]] +That command assumes that PulseAudio is the default ALSA device. If that's not the case, but instead PulseAudio is assigned a device name "pulse", add `-D pulse` somewhere to the command (see `man arecord` for more information about the parameters). + +And the arecord command seems to not be working because the PULSE_SOURCE seems to be out of order. But the parec is working. + + +### How do I record other programs' output? + +(Question added 2009-03-14) + +After reading the answer to the previous question, all you need to know is that every sink automatically has a monitor source, which you can use for recording. To list all monitor source names, run + + +[[!format txt """ +pactl list | grep -A2 'Source #' | grep 'Name: .*\.monitor$' | cut -d" " -f2 +"""]] + +### How do I play sounds from my chroot to my host's Pulseaudio daemon? + +(Question added 2009-04-29) + +First, ensure that pulseaudio is working and playing audible sound within your host. If it is not, look through the rest of this wiki and make sure it works. + +Setup of the chroot is outside the scope of this wiki, and should be done in whatever manner is recommended by your distro. Pulseaudio then needs to be installed within the chroot. A default install should be sufficient, no need to run the daemon or change any of the .conf files. Finally, Pulseaudio needs access to certain folders within the host system, the following list should enable all functionality on a default Pulseaudio install. + + +[[!format txt """ +/var/lib/dbus +~/.pulse +/tmp +/dev/shm +"""]] +/var/lib/dbus contains a reference to the machine-id which pulse uses to identify the local instance of the daemon. ~/.pulse contains various files created by the daemon, one of them, named <id_number>:runtime, symlinks to a folder in /tmp, hence both these folders should be accessible. /dev/shm is needed for proper running of pulseaudio, to prevent audio glitches. + +Most guides to setting up chroots (for example, 32-bit chroots in a 64-bit host) will already have /home and /tmp mounted, at least. Some would include /dev/shm, but very few, if any, would include /var/lib/dbus. You can manually mount the appropriate directories using the following commands, where /path/to/chroot is the path to your chroot. + + +[[!format txt """ +mount --bind /var/lib/dbus /path/to/chroot/var/lib/dbus +mount --bind /home /path/to/chroot/home +mount --bind /tmp /path/to/chroot/tmp +mount --bind /dev/shm /path/to/chroot/dev/shm +"""]] +If you use a helper app for your chroot, such as schroot, you will need to change the mount options for that helper app instead. Here is an example of a /etc/schroot/mount-<name_of_chroot> file, including the necessary options for Pulseaudio within the chroot:- + + +[[!format txt """ +# mount.defaults: static file system information for chroots. +# Note that the mount point will be prefixed by the chroot path +# (CHROOT_PATH) +# +# <file system> <mount point> <type> <options> <dump> <pass> +/proc /proc proc defaults 0 0 +/proc/bus/usb /proc/bus/usb none rw,bind 0 0 +/dev /dev none rw,bind 0 0 +/dev/pts /dev/pts none rw,bind 0 0 +/dev/shm /dev/shm none rw,bind 0 0 +/sys /sys none rw,bind 0 0 +/tmp /tmp none rw,bind 0 0 +/var/lib/dbus /var/lib/dbus none rw,bind 0 0 +/home /home none rw,bind 0 0 +"""]] + +### How do I change the default sink or source? + +(Question added 2009-11-14) + +This is answered on a separate page: [[Default Device|Software/PulseAudio/Documentation/User/DefaultDevice]]. + + +### How do I connect an input source to an output sink? + +Load the loopback module. + +The following example maps the output of a USB TV Tuner to the main sink. +[[!format txt """ +pactl load-module module-loopback source="alsa_input.usb-Hauppauge_WinTV_HVR-950_4034194782-01-U0x20400x7200.analog-stereo" sink="alsa_output.pci-0000_00_08.0.analog-stereo" +"""]] + +### How do I switch the default sound card, moving all applications? + +(Question added 2011-02-02) + +The simple answer is to use pavucontrol, click on the 'default' button, and move the apps individually. To do the same from the CLI, read the 'Command Line Interface' article. + +Here's a quick script (which you can bind to a shortcut key of your choice) to accomplish the above. Deleting the second half means it will only change default sound card without moving apps. Remember, unless you have set restore_device=false on module-stream-restore, all currently playing apps will be permanently moved to the new sound card till the next time you move them. + + +[[!format txt """ +#/bin/bash +# paswitch 2011-02-02 by Ng Oon-Ee <ngoonee@gmail.com> +# I can't remember where I found this script, can't locate the original author. +# Please inform me if you know, so that I can give proper attribution. +# CHANGES: Added auto-move all inputs to new default sound card. +# WAS: Pulse Audio Sound Card Switcher v1.0 2010-01-13 +# Switches between soundcards when run. All streams are moved to the new default sound-card. + +# $totalsc: Number of sound cards available +totalsc=$(pacmd "list-sinks" | grep card: | wc -l) # total of sound cards: $totalsc +if [ $totalsc -le 1 ]; then # Check whether there are actually multiple cards available + notify-send -u critical -t 5000 "Nothing to switch, system only has one sound card." + exit +fi +# $scindex: The Pulseaudio index of the current default sound card +scindex=$(pacmd list-sinks | awk '$1 == "*" && $2 == "index:" {print $3}') +# $cards: A list of card Pulseaudio indexes +cards=$(pacmd list-sinks | sed 's|*||' | awk '$1 == "index:" {print $2}') +PICKNEXTCARD=1 # Is true when the previous card is default +count=0 # count of number of iterations +for CARD in $cards; do + if [ $PICKNEXTCARD == 1 ]; then +# $nextsc: The pulseaudio index of the next sound card (to be switched to) + nextsc=$CARD + PICKNEXTCARD=0 +# $nextind: The numerical index (1 to totalsc) of the next card + nextind=$count + fi + if [ $CARD == $scindex ]; then # Choose the next card as default + PICKNEXTCARD=1 + fi + count=$((count+1)) +done +pacmd "set-default-sink $nextsc" # switch default sound card to next + +# $inputs: A list of currently playing inputs +inputs=$(pacmd list-sink-inputs | awk '$1 == "index:" {print $2}') +for INPUT in $inputs; do # Move all current inputs to the new default sound card + pacmd move-sink-input $INPUT $nextsc +done +# $nextscdec: The device.description of the new default sound card +# NOTE: This is the most likely thing to break in future, the awk lines may need playing around with +nextscdesc=$(pacmd list-sinks | awk '$1 == "device.description" {print substr($0,5+length($1 $2))}' \ + | sed 's|"||g' | awk -F"," 'NR==v1{print$0}' v1=$((nextind+1))) +notify-send "Default sound-card changed to $nextscdesc" +exit +# Below text was from original author and remains unaltered +# CC BY - creative commons +# Thanks God for help :) and guys lhunath, geirha, Tramp and others from irc #bash on freenode.net +"""]]
\ No newline at end of file diff --git a/Software/PulseAudio/GSoC.mdwn b/Software/PulseAudio/GSoC.mdwn new file mode 100644 index 00000000..913c3434 --- /dev/null +++ b/Software/PulseAudio/GSoC.mdwn @@ -0,0 +1,8 @@ + +[[!inline pages="Software/PulseAudio/TOC" quick="yes" raw="yes"]] + + +# Google Summer of Code + +* **[[2013|Software/PulseAudio/GSoC2013]]** +* [[2012|Software/PulseAudio/GSoC2012]]
\ No newline at end of file diff --git a/Software/PulseAudio/GSoC2012.moin b/Software/PulseAudio/GSoC2012.moin new file mode 100644 index 00000000..2f77851b --- /dev/null +++ b/Software/PulseAudio/GSoC2012.moin @@ -0,0 +1,237 @@ +<<Include(Software/PulseAudio/TOC)>>
+
+= Google Summer of Code: 2012 =
+
+== Dates ==
+[[http://www.google-melange.com/gsoc/events/google/gsoc2012|Official timeline]].
+
+The next important deadline is for students to apply: '''April 6: 19:00 UTC'''
+
+== Important information ==
+=== Reference ===
+The official website is at: http://www.freedesktop.org/wiki/Software/PulseAudio
+
+API documentation is at: http://freedesktop.org/software/pulseaudio/doxygen/
+
+The code is at: http://cgit.freedesktop.org/pulseaudio/pulseaudio/
+
+=== Contacts ===
+Feel free to contact us on IRC (#pulseaudio on Freenode) or via our [[http://lists.freedesktop.org/mailman/listinfo/pulseaudio-discuss|mailing list]]). We don't bite! (Note about IRC: there's no guarantee of a fast response. Some of us are present on the channel 24/7, but that doesn't mean that we pay attention all the time. So if you contact us via IRC and you don't get a quick reply, don't think that we're ignoring you, just hang around on the channel until you get an answer or try again later.)
+
+ * Arun Raghavan (Ford_Prefect on IRC, <<MailTo(arun AT SPAMFREE accosted DOT net)>> (admin, mentor)
+ * Colin Guthrie (coling on IRC, <<MailTo(colin AT SPAMFREE guthr DOT ie)>>) (backup admin, mentor)
+ * Tanu Kaskinen (tanuk on IRC, <<MailTo(tanuk AT SPAMFREE iki DOT fi)>>) (mentor)
+ * Peter Meerwald (??? on IRC, <<MailTo(pmeerw AT SPAMFREE pmeerw DOT net)>>) (mentor)
+ * João Paulo Rechi Vita (jprvita on IRC, <<MailTo(jprvita@gmail.com)>> (mentor)
+
+== Applying ==
+Once you've looked at the ideas below (or have one of your own), feel free to drop by our mailing list or IRC if you'd like some help fleshing things out. Once you're done, write up a proposal. Having the following bits will likely help make a coherent proposal:
+
+ * A description of the project
+ * A break-down of the tasks involved and possibly what you will ''not'' be covering (more detail is good)
+ * A schedule that describes how much you expect those tasks to take time
+ * What you will be finally delivering
+ * A ''short'' note about yourself
+ * Any other notes such as related prior experience (not required, but a bonus), why you think your proposal should be selected, etc. (keep this ''short'' as well!)
+
+As a bonus, pick one of our [[https://bugs.freedesktop.org/buglist.cgi?quicksearch=product%3Apulseaudio keyword%3Alove|easy bugs]], fix it, submit a nice git formatted patch to the PulseAudio mailing list. Include a link to your mailing list post from the [[http://lists.freedesktop.org/archives/pulseaudio-discuss/|list archives]] in your proposal so we don't miss it.
+
+== Ideas ==
+These are some ideas that the community would like to see pursued, Feel free to contribute your own ideas! The initial list is rough ideas. Use the template in the next section for more concreted ideas.
+
+ * Improve RTP performance (Maarten?) [needs to be more concrete]
+ * Add "high priority" events (Arun) [these would preempt passthrough streams, possible notify on all outputs, ...]
+ * Efficient resampling (Peter) [esp. on embedded CPUs; maybe fixed ratio sample rate conversion]
+
+
+{{{#!wiki diff-removed
+=== Project Title (template) ===
+
+'''Brief description:'''
+
+'''Expected results:'''
+
+'''Contact(s):''' <list of people to talk to about this idea, mark potential mentors distinctly>
+
+'''Necessary background:''' <if any, such as networking, assembly, ...>
+
+'''Mentor:'''
+}}}
+
+{{{#!wiki diff-removed
+=== Configurable maximum volume for sinks and sources ===
+
+'''Brief description:'''
+
+Some outputs may be capable of producing louder sound than what is comfortable. The user should be able to set a limit for the maximum volume.
+
+Some inputs may need software amplification, while others don't. Software amplification is prone to cause clipping, so it should be avoided when possible. If software amplification is not needed, it's useful to be able to prevent it from ever happening by setting the source maximum volume accordingly.
+
+'''Expected results:'''
+
+Several stages, the more gets done, the better:
+
+ * Ability to configure volume limits with module parameters, and enforce those limits.
+ * Ability to configure the limits on the fly (without reloading any modules).
+ * Make the volume limit configuration persistent so that when Pulseaudio is restarted, the configuration is restored automatically.
+ * A GUI for configuring the volume limits.
+ * Preferably implemented by modifying the audio configuration tool of the desktop environment of your choice, or by modifying pavucontrol.
+ * Ability to set a global maximum volume to cap maxmimum s/w gain
+
+'''Contact(s):''' Tanu
+
+'''Necessary background:''' C. For the GUI part some experience from writing graphical applications would be useful. Pavucontrol is written in C++ using Gtk.
+
+'''Mentor:''' Tanu
+}}}
+
+{{{#!wiki diff-removed
+=== Configurable latency for Bluetooth devices ===
+
+'''Brief description:'''
+
+Bluetooth's A2DP profile (the "high quality stereo mode") doesn't support latency information to be provided by the Bluetooth device to Pulseaudio. That's a limitation of the spec; we can't fix that. The effect of this limitation is that the audio-video synchronization ("lip-sync") is usually not very good. Pulseaudio currently uses the same hard-coded latency value for all Bluetooth devices. Assuming that the actual latency stays pretty much constant for any given device, but varies between different devices (how to verify this assumption?), it would make sense to make it possible to configure per-device latencies. This would potentially be useful for non-Bluetooth devices too, but I can't name any other concrete use cases right now. Anyway, the feature is general enough to not require any Bluetooth knowledge or hardware.
+
+'''Expected results:'''
+
+Several stages, the more gets done, the better:
+
+ * Ability to configure the "fixed latency" of devices with module parameters. (This is easier than it probably sounds. Applying the configured latency should be trivial.)
+ * Ability to configure the latency on the fly (without reloading any modules).
+ * Make the latency configuration persistent so that when Pulseaudio is restarted, the configuration is restored automatically.
+ * A GUI for configuring the volume limits.
+ * Preferably implemented by modifying the audio configuration tool of the desktop environment of your choice if the tool maintainers want such feature (this feature is quite rarely needed, so they might not want it), or by modifying pavucontrol. Since this feature is quite rarely needed, a custom configuration tool probably wouldn't be too bad either, though, if you don't like the prospect of modifying pavucontrol.
+
+'''Contact(s):''' Tanu
+
+'''Necessary background:''' C. For the GUI part some experience from writing graphical applications would be useful. Pavucontrol is written in C++ using Gtk.
+
+'''Mentor:''' Tanu, jprvita
+}}}
+
+{{{#!wiki diff-removed
+=== Logging and testing overhaul ===
+
+'''Brief description:'''
+PulseAudio provides pretty extensive logging on the server-side, and some amount of the same on the client side. However, this could undergo significant improvement. We also have a fairly rudimentary set of tests, but these cover a very small part of the actual code.
+
+'''Expected results:'''
+
+Improvements to the logging infrastructure, including:
+
+ * The ability to modify the log level at runtime
+ * Support for log "categories" (see GStreamer logging for an example)
+ * Filtering of what log categories turn up based on, for example, a regex
+ * A log buffer to allow querying the last X lines of log
+
+Revamp the testing infrastructure
+
+ * Add the ability to run tests and assert on various conditions on a PA instance running from the build
+ * Run gcov and figure out how abysmal our coverage is
+ * Add some useful tests, develop a framework for writing tests rapidly
+
+'''Contact(s):''' Arun
+
+'''Necessary background:''' Mostly C, some bash for testing, hacking other systems with advanced logging/testing/CI a bonus
+
+'''Mentor:''' Arun
+}}}
+
+{{{#!wiki diff-removed
+=== Better HDMI support ===
+
+'''Brief description:'''
+HDMI provides a number of nice features that we can use to make a better experience in PulseAudio. Part of it is coming with the new jack detection work, but there is still some room for improvement. This project is not very complex, however, and will likely take 1/2 the time give for SoC, so should be clubbed with some other task.
+
+'''Expected results:'''
+ * ELD parsing (can reuse some existing work for this)
+ * Set up sink formats based on this
+ * Set up sink # of channels, and channel map (possible?) based on this
+ * Parse latency information and expose this for A/V sync
+
+'''Contact(s):''' Arun
+
+'''Necessary background:''' C, access to a device with HDMI output and an HDMI receiver (TV, etc.)
+
+'''Mentor:''' Arun
+}}}
+
+{{{#!wiki diff-removed
+=== Improved RAOP Support (Airtunes™) ===
+
+'''Brief description:'''
+Colin introduced initial RAOP support some time ago but the implementation still needs work to make it universally useful. This project would see an upgrade to the newer Airtunes2 protocol, a new timing and buffering model and support for additional hardware including newer models of the Airport Express, AppleTV and e.g. Denon 4311 or Phillips SoundCurve. Some initial work has been done by Christophe Fergeau (author/maintainer of libgpod) to investigate and update to Airtunes2 protocol. This work is far from complete, but could form a starting point. Analysis of existing solutions, including protocol analysis, will likely be needed as the protocol is mostly undocumented.
+
+'''Expected results:'''
+ * Analysis of the Airtunes2 protocol on existing implementations and creation of protocol documentation
+ * Convert code to use Airtunes2 protocol
+ * Implement a robust timing and buffering model for reduced latency.
+ * Ensure timing information is accurately relayed to applications such that GUIs showing song timing information, lyrics etc. are all in sync even if there is a higher overall latency.
+ * Become completely sick of the student's chosen test song that will no doubt be played repeatedly ad infinitum during testing.
+
+'''Contact(s):''' Colin
+
+'''Necessary background:''' C, Wireshark/Protocol Analysis, Access to Airtunes h/w - preferably several different models.
+
+'''Mentor:''' Colin
+}}}
+
+{{{#!wiki diff-removed
+=== GUI Interaction/User Feedback ===
+
+'''Brief description:'''
+!PulseAudio is a daemon and thus GUI interaction is normally left for other people to integrate as they see fit. However, support for specific forms of GUI interaction could be facilitated more easily via a !PulseAudio module. Most Linux desktop environments now support the Desktop Notification specification which provides an infrastructure for showing passive/unobtrusive notifications to the user and for collecting simple feedback (i.e. answering basic questions).
+
+'''Expected results:'''
+ * Provide a mechanism to let the user know a new (never seen before device) has been plugged in and ask if they want to use it by default.
+ * Ensure that remote-sink detection modules (using zeroconf) are converted to offer an interactive mode (i.e. show the user they have found something but ask if they want to connect and, if necessary, prompt for authentication).
+ * Adjust volume control GUIs to know when Pass-through-mode is active for a given sink and thus volume controls are disabled.
+ * Integrate work appropriately into the Desktop Environments of GNOME and KDE
+ * ''Note'': Ubuntu uses a fork of the Desktop Notifications specification and uses a different feedback specification: Indicators. While it would be nice to support this variation, emphasis should be first placed on official upstream implementations. It would be nice if the final implementation was sufficiently flexible to work with both systems.
+
+'''Contact(s):''' Colin
+
+'''Necessary background:''' C, D-Bus, GTK, Qt, GUI/HCI
+
+'''Mentor:''' Colin
+}}}
+
+{{{#!wiki diff-removed
+=== Extend HTTP Protocol ===
+
+'''Brief description:'''
+Web-centric desktops are more common place these days, as are home media solutions where control and command is performed via smart phones. Since Pass-through support was merged in !PulseAudio 1.0, we have used json-c which facilitates the used of JSON formatted data in some selective places. The HTTP protocol is currently quite simplistic, primary designed to push out audio for e.g. UPnP. It would be nice if the HTTP protocol could be updated to include a simpler level of "command and control" introspection as the native protocol (i.e. listing sinks, sources etc. with notification of changes and the ability to make changes to volume, move sinks etc.)
+
+'''Expected results:'''
+ * Review native protocol and design introspection parts of HTTP protocol and document.
+ * Implementation of HTTP protocol.
+ * Create a web based interface to control PA devices and volumes.
+
+'''Contact(s):''' Colin
+
+'''Necessary background:''' C, JSON, HTML/CSS/JavaScript, JQuery (JQuery Mobile) or similar and perhaps Web Sockets.
+
+'''Mentor:''' Colin
+}}}
+
+
+
+{{{#!wiki diff-removed
+=== Configuration system ===
+
+'''Brief description:'''
+This is a much-needed core PulseAudio feature. We currenty store a lot of configuration in various places -- config files, databases for various things (volumes, properties, ...). We need a single configuration API that modules can use and clients can query and talk to as well. Some discussion on the merits of having notifications on changes to configuration would be required. dconf solves a lot of these problems already, but is not supported on sufficient platforms. One option is to use dconf where supported, and fallback to ini file-based configuration where it is not (so we lose the ability to be notified of changes on these platforms).
+
+Step one in this task would be to get consensus on the backend. Step two would be to write up documentation for an API if one needs to be designed, post to list, get consensus. Next is implementation, with test cases, and moving over config options to it. Finally, if time permits to hook up some common config options in pavucontrol. There is a work-in-progress [[[http://piratepad.net/BLGxYG2lf3]|discussion]] about this.
+
+This is a somewhat hard project, involving a lot of community interaction and pretty good software engineering skills from the start. On the other hand, this is core API and a great way to experience the Real Thing™ as far as open source development goes.
+
+'''Expected results:'''
+A configuration API that modules and clients can use, proper documentation for developers, automated test cases, and some implementation of actual use of this API.
+
+'''Contact(s):''' Arun, Colin, Tanu
+
+'''Necessary background:''' C, general configation mechanisms (simple databases like tdb/gdbm, ini files, gconf/dconf/ ...) would be useful too
+
+'''Mentor:''' Arun, Tanu
+}}}
diff --git a/Software/PulseAudio/GSoC2012/LoggingAndTesting.mdwn b/Software/PulseAudio/GSoC2012/LoggingAndTesting.mdwn new file mode 100644 index 00000000..bf36d168 --- /dev/null +++ b/Software/PulseAudio/GSoC2012/LoggingAndTesting.mdwn @@ -0,0 +1,55 @@ + +This is Deng Zhengrong to track the status of GSoC 2012. + + +# Logging + + +## change log's output on the fly via pacmd command + +This is done by adding a new command _set-log-target_ in file _cli-command.c_. and this patch is already accepted. + + +## add log category support + +The original proposal is to have a mechanism that's similar to _gstreamer_ 's category support, therefore we can give it a category's name and a log level to decide whether we want to turn some logs on or off. + + * The first version of this category support: + * add a _pa_log_category_t_ type and in this type, we have log level, its category name, its category description and its output color. + * when a log message comes in, it has a function called _init_defaults_ in _log.c_ and I need to register some pre-defined categories before I can use it. + * and in every file when we want to use the category, we need to a line _#define PA_LOG_CATEGORY_DEFAULT PA_LOG_CATEGORY_CORE_. + * for modules' usage, it's a little different, we need to register the category in _pa_init()_ and therefore we can use this category. + * I've discussed with Arun on IRC and it seems that the first version is not good enough. We'd better have a on-the-go interface. So thanks to Arun's advice, we've second proposal: + * Whenever we want to use a specific category, we only need to add one line _PA_SET_CATEGORY("sink-input")_ at the top of the c file. + * Then when a log message comes in, it checks whether the requested category exists or not, if it's not, then it creates it dynamically, + * For users to take advantage of the category support, we have to add some 'category' related commands, (just like what we've done with the modules), something just come out of my mind is: + * list all avaiable categories + * set categories to different log level + * Now the implementation is done and the patch is sent to mailing list for review. + +## look into systemd journal support + + * Sadly when I tried to install a new systemd on my old Fedora Core 15, the system can't boot anymore... + * Discussion with Arun on IRC shows that there are two ways we can take from systemd journal + * either make the journal part in systemd a reusable library + * or to do the logging by ourselves. + * Ping Colin and Lennart on IRC, but there's no replies. + +## circular buffer support + +The purpose of this support is to have a buffer to hold the last few lines of the log and then users can query about these logs, e.g. filtering about the messages etc. + +* A demo is done and I've sent it out to mailing list for review. +* But the problem is that it incorporates the usage of a mutex and in pulseaudio, we'd prefer to remove that lock. So the next step is to see how we can overcome this shortcoming. + +# Testing + +* Setup gcov to see how pulseaudio is covered by the current code. Planning... + +# Contributions + +* [[fix compilation warning via PRI prefix|http://cgit.freedesktop.org/pulseaudio/pulseaudio/commit/?id=737a6180d44c3f4dbe9def42e38c47665b28af15]] +* [[cli: Add set-log-target command for pacmd|http://cgit.freedesktop.org/pulseaudio/pulseaudio/commit/?id=9d40957c79c7690886728296faf25de9f7cb6da5]] +* [[daemon: use pa_streq instead of plain strcmp|http://cgit.freedesktop.org/pulseaudio/pulseaudio/commit/?id=9be176f40312a38882e1db46645b136e69b2cad4]] +* fix the wrong parameter sequence in pax11publish pending.... +* add log category support pending...
\ No newline at end of file diff --git a/Software/PulseAudio/GSoC2013.mdwn b/Software/PulseAudio/GSoC2013.mdwn new file mode 100644 index 00000000..bedc8e87 --- /dev/null +++ b/Software/PulseAudio/GSoC2013.mdwn @@ -0,0 +1,105 @@ + +[[!inline pages="Software/PulseAudio/TOC" quick="yes" raw="yes"]] + + +# Google Summer of Code: 2013 + + +## Important Dates + +[[Official timeline|http://www.google-melange.com/gsoc/events/google/gsoc2013]]. + +Students can start submitting applications: 2013-04-22. + +Deadline for student applications: 2013-05-03. + +List of accepted students announced: 2013-05-27. + + +## General PulseAudio Information + +Homepage: [[http://www.freedesktop.org/wiki/Software/PulseAudio|http://www.freedesktop.org/wiki/Software/PulseAudio]] + +Code: [[http://cgit.freedesktop.org/pulseaudio/pulseaudio/|http://cgit.freedesktop.org/pulseaudio/pulseaudio/]] + +Mailing list: [[http://lists.freedesktop.org/mailman/listinfo/pulseaudio-discuss|http://lists.freedesktop.org/mailman/listinfo/pulseaudio-discuss]] + +[[IRC|https://en.wikipedia.org/wiki/IRC]]: #pulseaudio at irc.freenode.net ([[webchat|https://webchat.freenode.net/?channels=pulseaudio]]) + +Bug tracker: [[https://bugs.freedesktop.org/|https://bugs.freedesktop.org/]] ([[list of open PulseAudio bugs|https://bugs.freedesktop.org/buglist.cgi?quicksearch=product%3APulseAudio]]) + + +## Contacts + +Feel free to contact us on IRC or via the mailing list (see the links above). We don't bite! (Note about IRC: there's no guarantee of a fast response. Some of us are present on the channel 24/7, but that doesn't mean that we pay attention all the time. So if you contact us via IRC and you don't get a quick reply, don't think that we're ignoring you, just hang around on the channel until you get an answer or try again later.) + +* Arun Raghavan (Ford_Prefect on IRC, arun AT SPAMFREE accosted DOT net) (admin) +* Colin Guthrie (coling on IRC, colin AT SPAMFREE guthr DOT ie) (backup admin) +* Tanu Kaskinen (tanuk on IRC, tanu DOT kaskinen AT SPAMFREE intel DOT com) (mentor) +* Peter Meerwald (pmeerw on IRC, pmeerw AT SPAMFREE pmeerw DOT net) (mentor) +* David Henningsson (diwic on IRC, david.henningsson AT SPAMFREE canonical DOT com) (mentor) + +## Applying + +Once you've decided which project idea suits you the best (pick an idea from the list below or one of your own), write up a proposal. Having the following bits will likely help make a coherent proposal: + +* A description of the project +* A break-down of the tasks involved and possibly what you will _not_ be covering (more detail is good) +* A schedule that describes how much you expect those tasks to take time (if a task takes much more than a couple of weeks, it should probably be split into subtasks) +* A _short_ note about yourself +* Any other notes such as prior open source contributions (not required, but a bonus), why you think your proposal should be selected, etc. (keep this _short_ as well!) +The application that you submit is only one factor when we think whether you should be accepted instead of someone else. You can greatly improve your chances of getting selected by demonstrating in practice that you have the necessary skills and that you're a nice person to work with. Join the mailing list and the IRC channel and be active. Pick some suitably small task to work on (nothing wrong with big tasks either, if you have lots of free time). Ask questions and send patches. There's a [[list of "easy" bugs|https://bugs.freedesktop.org/buglist.cgi?quicksearch=product%3Apulseaudio keyword%3Alove]] that can be useful when thinking what to work on. + + +## Ideas + + +### Project Title (template) + +**Problem statement:** What problem does this project solve? + +**Suggested solution:** A rough outline of what needs to be done. If this is very detailed, this inevitably ends up being copied as the project plan (not necessarily verbatim), which makes it impossible to judge whether the student knows what he or she is talking about. I'm not sure if this is a huge problem, though. Ideally, the student capability would mostly be judged based on the pre-selection contributions. + +**Contacts:** List of people to talk about this idea, mark potential mentors distinctly. + +**Necessary background:** What skills are required/beneficial? + +**Potential mentors:** List of people who volunteer to mentor this project. + + +### Better JACK Configurability + +**Problem statement:** [[JACK|http://jackaudio.org/]] is a sound server for so called "pro audio" use cases, such as music production or live performances. Many people want to run PulseAudio on top of JACK, so that JACK has direct access to the sound card and PulseAudio accesses the sound card through JACK. When running PulseAudio on top of JACK, the default configuration creates one two-channel sink (i.e. output device) and one two-channel source (i.e. input device) for JACK inside PulseAudio. If the user wants something different, the only way to change the configuration is to edit the configuration file by hand, which isn't particularly user-friendly. Furthermore, the configuration parameters are very limited: only the number of channels per device can be changed, and it's not possible to have different number of channels for input and output. (Actually, to be more accurate, it is possible to have different number of channels for input and output, if you load module-jack-sink and module-jack-source manually instead of relying on module-jackdbus-detect, but then you lose the convenience that module-jackdbus-detect provides.) + +Things that users might want to configure: + +* channels for input and output separately +* disabling input or output altogether +* multiple input or output devices +* modes for quickly switching between several configurations +**Suggested solution:** The set of parameters that module-jackdbus-detect supports should be expanded to cover the given use cases. As the responsibilities of module-jackdbus-detect grow beyond bare detection, it might make sense to rename the module to simply module-jack. + +The switchable modes should be implemented as card profiles. Currently, the JACK code doesn't implement a card object, so one task is to implement a "JACK card". + +To achieve user-friendliness, there should be a GUI for changing the settings. Just implementing the JACK card with a good default set of profiles would go a long way, because the existing GUIs already support changing card profiles. + +Implementing only the JACK card would probably make this project too small to fill the whole summer, so there could be some extra GUI options added for JACK: for example, the "auto-connect" option could be exposed in a GUI (maybe separately for each device or card profile). It's a simple boolean option that is already supported, but changing the option value requires editing the configuration file by hand. Adding new run-time-editable configuration options is far from trivial: the GUI code needs to be written, the client API needs to be extended, the IPC protocol needs to be extended and persistent storage for the options needs to be implemented. + +**Contacts:** Tanu + +**Necessary background:** C for PulseAudio code. C++ for pavucontrol code (the preferred GUI application to modify is pavucontrol). + +**Potential mentors:** Tanu + + +### Resampling Improvements + +**Problem statement:** PulseAudio aims to match the sample rates supported by the hardware to the sample rates requsted by the application. This process is called resampling and is quite CPU intensive. PulseAudio resorts mostly to external code to provide resampling: speex, ffmpeg, libsamplerate. Speex seems unmaintained, ffmpeg now provides a library interface (libav) and code duplication is unnecessary (we have a copy of the ffmpeg resampler in our source tree). libsamplerate is GPL. Lightweight, high-quality and optimized resampling code is desirable. + +**Suggested solution:** Assess available audio resampling code, performance-wise and feature-wise. Implement interface to enable resampling provided by libav and drop code copied from ffmpeg. + +**Contacts:** Peter + +**Necessary background:** C for PulseAudio, signal processing, possibly assembler for SIMD optimization (SSE, NEON). + +**Potential mentors:** Peter diff --git a/Software/PulseAudio/HowToUseGitSendEmail.mdwn b/Software/PulseAudio/HowToUseGitSendEmail.mdwn new file mode 100644 index 00000000..aa19c54b --- /dev/null +++ b/Software/PulseAudio/HowToUseGitSendEmail.mdwn @@ -0,0 +1,99 @@ + +[[!inline pages="Software/PulseAudio/TOC" quick="yes" raw="yes"]] + + +# How to Use git send-email + +The preferred way to send patches is by email, using git send-email (more information about sending patches can be found on the [[Community|Software/PulseAudio/Documentation/User/Community]] page). This page explains how to use git send-email. + + +## Installing send-email + +You probably already have git already installed, but that's not necessarily enough to have also the send-email command available. You can check if send-email is available by running "git send-email --help". If it shows the man page for send-email, then send-email is available. Otherwise, you need to install the send-email command. Your distribution probably has a package for it; on Debian the package name is "git-email". + + +## Configuring Your Name and Email Address + +You should tell git your name and email address. You have probably done this already, but if not, run these commands: + + +[[!format txt """ +git config --global user.name "My Name" +git config --global user.email "myemail@example.com" +"""]] + +## Configuring the Mail Sending Options + +git send-email sends the emails through your SMTP server, so you need to configure the server parameters. Refer to your email provider documentation to find the right parameters. This is how I would configure my mail settings: + + +[[!format txt """ +git config --global sendemail.smtpencryption tls +git config --global sendemail.smtpserver mail.messagingengine.com +git config --global sendemail.smtpuser tanuk@fastmail.fm +git config --global sendemail.smtpserverport 587 +git config --global sendemail.smtppass hackme +"""]] +Storing the password in the git configuration file is obviously a security risk. It's not mandatory to configure the password. If it's not configured, git send-email will ask it every time the command is used. + + +## Configuring the Default Destination Address + +For PulseAudio, the patches should be sent to our mailing list. In order to avoid having to remember it and retyping it all the time, you can configure the address to be used by default by git send-email. As you may contribute to many projects using git, it does not make sense to set this option globally so instead we'll only set it in our clone of the [[PulseAudio|PulseAudio]] code. + + +[[!format txt """ +git config sendemail.to pulseaudio-discuss@lists.freedesktop.org +"""]] + +## Using the send-email Command + +See "git send-email --help" for the full reference. I'll go through only the basic usage here. + +git send-email will ask a few questions before the patches are sent. Most of the questions have a sensible default value shown in square brackets. Just press enter to use the default value. Type the answer to the question if you don't want to use the default answer. The questions are: + +* Who should the emails appear to be from? + * This will be used as the "From" header. You should have configured your name and email address earlier, so the default is usually correct. +* Who should the emails be sent to? + * As noted above, patches should be sent to our mailing list: _[[pulseaudio-discuss@lists.freedesktop.org|mailto:pulseaudio-discuss@lists.freedesktop.org]]_ +* Message-ID to be used as In-Reply-To for the first email? + * This can usually be left empty, in which case the patch or patches will appear as a new thread. When sending updated patches, in my opinion it's nice to set this to the "Message-Id" header of the previous version of the patch (for multi-patch series, use the cover letter's Message-Id), so that the full patch history can be easily accessed. This is the only valid use case for setting the "In-Reply-To" header (again, in my opinion). In other words, please do NOT send patches as replies to regular discussion. +* Send this email? + * The mail headers are visible above the question, so that you can check that everything looks OK. + +### Sending a Single Patch + +Sending the last commit in the current branch: + + +[[!format txt """ +git send-email -1 +"""]] +Sending some other commit: + + +[[!format txt """ +git send-email -1 <commit reference> +"""]] + +### Sending Multiple Patches + +Sending the last 10 commits in the current branch: + + +[[!format txt """ +git send-email -10 --cover-letter --annotate +"""]] +The --cover-letter option creates an extra mail that will be sent before the actual patch mails. You can add write some introduction to the patch set in the cover letter. If you need to explain the patches, be sure to include the explanations also in the commit messages, because the cover letter text won't be recorded in the git history. If you don't think any introduction or explanation is necessary, it's fine to only have the shortlog that is included in the cover letter by default, and only set the "Subject" header to something sensible. + +The --annotate option causes an editor to be started for each of the mails, allowing you to edit the mails. The option is always necessary, so that you can edit the cover letter's "Subject" header. + + +### Adding Patch Version Information + +By default the patch mails will have "[PATCH]" in the subject (or "[PATCH n/m]", where n is the sequence number of the patch and m is the total number of patches in the patch set). When sending updated versions of patches, the version should be indicated: "[PATCH v2]" or "[PATCH v2 n/m]". To do this, use the --annotate option and edit the "Subject" header of the mails. + + +### Adding Extra Notes to Patch Mails + +Sometimes it's convenient to annotate patches with some notes that are not meant to be included in the commit message. For example, one might want to write "I'm not sure if this should be committed yet, because..." in a patch, but the text doesn't make sense in the commit message. Such messages can be written below the three dashes "---" that are in every patch after the commit message. Use the --annotate option with git send-email to be able to edit the mails before they are sent. diff --git a/Software/PulseAudio/Ideas.mdwn b/Software/PulseAudio/Ideas.mdwn new file mode 100644 index 00000000..dfd1268d --- /dev/null +++ b/Software/PulseAudio/Ideas.mdwn @@ -0,0 +1,64 @@ + +[[!inline pages="Software/PulseAudio/TOC" quick="yes" raw="yes"]] + + +# PulseAudio Development + + +## Documentation + +* [Software/PulseAudio/Documentation/Developer Developer Documentation] + * [Software/PulseAudio/Documentation/Developer#[[DevelopingClients|DevelopingClients]] Developing Clients] + * [Software/PulseAudio/Documentation/Developer#[[DevelopingModules|DevelopingModules]] Developing Modules] + +## Future Developments + +This section will list some future proposals and plans for PulseAudio and it's related helper applications. + +Below are listed the development proposals and (where relevant) a link to their tracking tickets. + + +### Support for Apple !AirTunes (Airport Express) as Remote Network Sinks + +* **Status**: In Progress - Working, but needs refinement[[br|br]] **Developer**: Colin Guthrie (coling)[[br|br]] **Ticket**: #69 +Support using Apple Airport devices as network sinks. These can be auto-detected via Avahi. + +This will be part of PulseAudio 0.9.14 although the initial support has several limitations (including not being able to automatically reconnect and hogging any devices it finds) + + +### Passive Popup Notifications + +* **Status**: Proposed, some development started[[br|br]] **Developer**: Colin Guthrie (coling)[[br|br]] **Ticket**: None as of yet. +As padevchooser is no longer actively developed but did provide nice popups (via libnotify), there is a gap in the market! I am proposing to create a new pulseaudio module that would be started at X11 login (in the same manner as module-x11-publish/xsmp). This module will sit in the background and inform the user when new sinks are detected and other similar events. As libnotify can provide callbacks this interface could be used to provided simple interaction for common tasks (e.g. setting a USB sink as default and moving all streams across to it. + +Initial development for this has been started but integration with the GTK mainloop is proving problematic. Lennart has a plan for this so development is stalled until this comes to fruition. + + +### Active 'Default' Sink Support + +* **Status**: Proposal Only[[br|br]] **Developer**: ??? Maybe Colin Guthrie (coling)[[br|br]] **Ticket**: None as of yet. +One of the most confusing things for new PulseAudio users is how the setting of the default sink actually works (i.e. a pavucontrol UI issue), but also what setting the "default" actually means. As pulse remembers the sink chosen for a given stream, the "default" is only every used for the initial choice of where to play a _new_ stream. After it's initial play the choice of which sink to play a stream on falls typically to module-stream-restore. For most people this is not what they expect of a "default", therefore this is a proposal to create a module which creates a virtual sink that can attach itself to the users choice of default sink. If the users sets a new default sink, this module will automatically reattach itself to this device. This will allow users to still manually select which sink they want to play a given stream on, but also have an "active" default sink that behaves as one would typically expect a default to behave (where changing the default would automatically appear to "move" the running tracks to that sink. + +NB I'm not 100% sure of the practicalities of writing a virtual sink that can change the master sinks it connects to and what this means for e.g. sample rates, formats and channels etc. + + +### Default Sink Priority List with Disconnected Sink Memory + +* **Status**: Proposal Only[[br|br]] **Developer**: ???[[br|br]] **Ticket**: None as of yet. +Of many people, the setting of the default (see above) does not work as well as it could when it involves removable devices (be it network sinks or USB auto devices etc.) A common scenario would be similar to the following: + +1. A laptop with built in sound +1. A workstation with USB sound system. +1. Want to use the USB system when at workstation and built in when not. +1. Do not want to continually tweak preferences. +In order to achieve this goal, this proposal would redefine the "set-default-sink" command and internally handling to work as a priority list where all sinks are rated in order of desirability. As is should be possible to prefer sinks that do not currently exist, it must be possible to record all the sinks that have ever been added to the system and obtain their current status (e.g. active or disconnected). There should also be a method of removing disconnected sinks from this list (e.g. from a housekeeping/tidy up perspective). This approach clearly needs a modification to the protocol in order to provide the necessary information to the client application that will implement the GUI portion of this proposal. + +This approach would work well with e.g. a bluetooth enabled hi-fi system such that as soon as you turn it on and it's detected, your music will suddenly move to this device! Ditto for network sinks and USB devices. This would be very user friendly and combined with the notification feedback above, would be quite obvious to the user as to why a sudden change in output device has been invoked (of course the user would have to have chosen this default manually already, but users can be forgetful!) + +NB module-rescue-streams could be adapted to use this list as appropriate (although with the changed "default" sink handling outlined in a above proposal, this module would be used much less frequently on a typical setup). + + +### D-Bus Control Interface + +* **Status**: In progress - implementation work ongoing[[br|br]] **Developer**: Tanu Kaskinen (tanuk)[[br|br]] **Ticket**: None as of yet. +The grand goal that will hopefully be someday achieved is to split the current native protocol into two parts: server query and control with D-Bus and audio streaming with RTP/RTSP. The D-Bus interface is documented at the [[DBusInterface|Software/PulseAudio/Documentation/Developer/Clients/DBus]] page (a draft version is completed - suggestions for improvement are welcome). diff --git a/Software/PulseAudio/Meetings.mdwn b/Software/PulseAudio/Meetings.mdwn new file mode 100644 index 00000000..1d836fa4 --- /dev/null +++ b/Software/PulseAudio/Meetings.mdwn @@ -0,0 +1,12 @@ + +This page will list minutes for meetings that have occurred and things we want to take up in future meetings. + + +## Meeting Minutes + +* [[Feb 24th, 2011|Software/PulseAudio/Meetings/2011-02-24]] + +## Potential Agenda Items + +* Migration/layout of fd,o wiki +* Release process
\ No newline at end of file diff --git a/Software/PulseAudio/Notes/1.0.mdwn b/Software/PulseAudio/Notes/1.0.mdwn new file mode 100644 index 00000000..c2592fc2 --- /dev/null +++ b/Software/PulseAudio/Notes/1.0.mdwn @@ -0,0 +1,1075 @@ + +[[!inline pages="Software/PulseAudio/TOC" quick="yes" raw="yes"]] + + +## Release Notes + +The first thing you need to know is that 1.0 is just a number. We do not attach specific significance to the 1.0 moniker. It's really just a way to clean up version numbers - it's an eternal debate as to what constitutes "1.0 quality" and in the end we could easily go on forever with the previous numbering scheme. But with such a long time in development and the general state of PulseAudio adoption in the major distros and integration into the major Desktop Environments, we felt that this was as good a time as any to try and clean up the version numbers and call it 1.0! In time, we may even drop the minor number and just have one version number, but we'll see how things go first before making that decision. Certainly most releases will be based on the major number (so expect to see v2.0 next!) with the minor number reserved for bugfix updates should there be demand for us to do so keeping in mind that such bugfix updates will have to be supported mostly by the community. + +PulseAudio 1.0 has been a long time in the making. The git branch is actually from based several releases back (around the 0.9.19 release) but for various reasons the subsequent releases have been made from the stable tree as git master was home to too many experimental features. This wasn't ideal from a management perspective and has caused more than a little confusion (not to mention it makes the git changelogs look weird), so we're going to try not to let this happen again. + +But with some diligent work, and diligent use of git cherry, git master contains all the fixes that were pushed into the releases that have been made along the way, and adds some significant features too. + + +## Key Features of 1.0 + +* D-Bus based control protocol (beta) +* Source Output Volumes +* Passthrough Support +* Windows support restored +* Improved sample rate adaptation in module-rtp-receive +* Volume Change Sync for flat volumes +* Enhanced Port Volume controls +* New, future proof format for metadata files +* New equalizer and acoustic echo cancellation modules +* If [[Jack|http://jackaudio.org/]] is running, PulseAudio will connect to it automatically by default (previously this required editing a configuration file) + +### Features in more detail + +* **D-Bus based control protocol (beta)** + * Everything except audio streaming (and source output volumes) can now be done also via D-Bus. We are not completely certain about the API (due in part to internal code structure and upcoming planned changes), so we make no API stability guarantees. If you can live with the API changing in the next PulseAudio release, feel free to experiment with the D-Bus interface. Any feedback is very welcome - good ideas for improving the API will likely be implemented. Here's the [[documentation|http://pulseaudio.org/wiki/DBusInterface]] (might be down for a bit due to heavy load). +* **Source Output Volumes** + * Previously you could alter the volume of sinks (playback devices), sources (capture devices), sink-inputs (playback streams) but not of the source-outputs (capture streams). Now it is possible to adjust the volume or mute the stream of each recording application separately, just like it always has been for playback. This brings symmetry to the API which is certainly a bonus for e.g. VoIP apps which typically integrate volume controls. It was originally left unimplemented due to the fact that the case for multiple capture streams is very rare and you certainly didn't want to include software volumes into your only capture stream if at all possible. However, with the introduction of "flat volumes", any volume set on a capture stream will be "flattened" through to the underlying hardware volume if at all possible, thus avoiding problems with integrating additional artefacts or clipping the data with a standard software volume adjustment. +* **Passthrough Support** + * PulseAudio now supports passthrough audio natively. This means that applications can now send compressed audio directly to hardware that supports it (for now, high-end A/V receivers, but this can include embedded SoCs with decoder blocks and Bluetooth headsets that support formats other than SBC). For more details, see [[Passthrough|http://pulseaudio.org/wiki/Passthrough]] (might be down for a bit due to heavy load). +* **Echo Cancellation** + * A new module (module-echo-cancel) for acoustic echo cancellation (AEC) has been added. If you are using Empathy 3.2, echo cancellation should work out of the box. For other clients which set the "phone" media role, you can just load module-echo-cancel manually or in your configuration to take advantage of this. More details on [[Arun's blog post.|http://arunraghavan.net/2011/08/hello-hello-hello/]] +* **Windows Support Restored** + * The old Windows port dated back to PulseAudio 0.9.6. Since then a lot of features had been added which broke the building of PA on Windows. Thanks primarily to the work of Maarten Bosmans, the 1.0 release restores Windows support for PulseAudio. Additionally, the WaveOut driver received some minor improvements. +* **Improved sample rate adaptation in module-rtp-receive** + * A new algorithm is used to determine the resampling rate, in order to more reliably match the rate to the clock of the RTP-stream sender. This will eliminate some bugs related to the sound becoming distorted due to a wildly varying sample rate. + +## Removed Stuff + +* **pabrowse and libpulse-browse** + * pabrowse and libpulse-browse have been removed after a long time of deprecation. The functionality is now directly provided by avahi-browse and libavahi. This also means that padevchooser will no longer build. This is fully intended as that tool itself has also been deprecated for many years and operates in a manner that generally breaks your setup for several corner cases. + +## Management Changes + +As most people following the Linux community any depth will know, Lennart is now primarily engaged in the development of [[systemd|http://www.freedesktop.org/wiki/Software/systemd]]. While he has not abandoned PulseAudio, his development focus has certainly changed for now and as such, Colin Guthrie will manage future releases and generally head up the community. Colin really assumed this role some time ago, herding the cats on the mailing lists and IRC channels, building bridges to various interested parties and trying to review patches and develop new code himself, so this transition is rather smooth. Colin has yet to develop skin quite as thick as Lennart, so please be kind. + + +## Infrastructure Changes + +Along with Lennart's management departure, most of the PulseAudio infrastructure has also moved. We would like to extend our thanks to the good folks over at [[freedesktop.org|http://freedesktop.org/wiki/]] for hosting our [[git repositories|http://cgit.freedesktop.org/pulseaudio/]], [[mailing lists|http://lists.freedesktop.org/mailman/listinfo/pulseaudio-discuss]] and [[bug tracking|https://bugs.freedesktop.org/buglist.cgi?query_format=specific&order=relevance+desc&bug_status=__all__&product=PulseAudio&content=]]. In due course we will also migrate our wiki content from Trac to the FDO wiki, but we want to plan this out carefully as the current wiki isn't as organised as it could be. + + +## What's Next? + +Several developments are now lined up for the future. Upcoming features will likely include: + +* **UCM: Use Case Manager Support** + * Support for UCM will be included in the near future. The people behind UCM (namely Liam Girdwood @ TI and Mark Brown @ Wolfson with support from many others) have already developed some PA patches that go some way to implementing the necessary logic, and we hope the get these patches cleaned up and included quickly. +* **Headphone/Mic Jack Detection** + * David Henningsson from Canonical has been working on the various different bits required to ensure that PA responds properly when a set of (3.5mm) headphones are inserted - i.e. switching over to using them and ensuring the correct underlying ALSA kcontrols are used for volume adjustments. The same is true when an external mic is inserted - i.e. taking over from the internal mic. While the kernel interfaces are perhaps subject to change, we will be integrating the core changes needed to support this infrastructure as soon as the 1.0 release is out of the door. +* **Module Loading Improvements** + * Colin Guthrie has plans to deprecate module-gconf (which is just a module loader) in favour of a slightly more intelligent and contextually aware module loader. This loader module would be able to load modules based on "trigger" conditions such as a certain sink, source or a combination of sinks and sources existing. This will allow for the configuration of loopback, combine or effect modules that are only activated when certain devices are present. +* **Routing Infrastructure** + * As has been known for a long time, the current infrastructure for dealing with stream routing is insufficient. Colin Guthrie hopes to expand on his earlier work with module-device-manager (which is used under KDE and implements a priority-list based routing policy) to integrate support for a much more flexible routing system into the PA core, although still retaining the ability for fine-grained policy to be specified (such as using headsets on voip calls and using never-seen-before devices as the default). +* **Adoption of WebRTC code for Echo Cancellation** + * Arun Raghavan's work on the echo cancellation code will be augmented using various systems developed by Google and released as the WebRTC system. +* **More use of Orc for CPU-intensive tasks** + * The OIL Runtime Compiler allows SIMD code to be written in a CPU-agnostic way, which is later, at runtime, compiled into code optimized for the specific CPU. Currently PulseAudio uses Orc at a couple of places. Future releases will make more use of Orc, resulting in less CPU-time used by PulseAudio. + +## Git Shortlog + + +[[!format txt """ +Antonio Ospite (2): + alsa-mixer: Add support for the Microsoft Kinect Sensor device + doc: Add info about running pulseaudio from the build dir + +Antti-Ville Jansson (1): + core: Drop empty gaps in the memblockq when playing data from it. + +Arun Raghavan (149): + build: Fix make distcheck + cpu: Add CPU information to pa_core + echo-cancel: Add SSE optimisation to the adrian module + echo-cancel: orc-ify some bits for optimisation + build: Copy orc dist files to the correct directory + volume: Use a macro to check if a volume is valid + volume: Clamp volume to PA_VOLUME_MAX + cli: Validate volume before setting + pactl: Validate volume before setting + volume: Decrease PA_VOLUME_MAX to be < 2^31 + volume: Fix incorrect usage of PA_VOLUME_IS_VALID + alsa: Sprinkle some PA_UNLIKELYs around error checks + build-sys: Fix a warning during distcheck + build: Move orc.mak out of build/ + build: Simplify Orc-related make rules + echo-cancel: Make Orc file names less silly + Revert "core: volume ramping fix" + Revert "ramping: minor cleanups" + Revert "Add volume ramping feature - sink modification" + Revert "Add volume ramping feature - sink-input modification" + Revert "Add volume ramping feature - envelop fix" + Revert "Add new subsystem for applying envelopes (such as volume ramps) to audio signals" + Remove remaining ramping/envelope references + introspect: Client-side implementation for has_volume/read_only_volume + volume: Make tests use only valid volumes + volume: Fix sample array size for tests + volume: Add Orc-based optimised volume scaling + daemon: Fix missing include - cpu-orc.h + build: Bump Orc dependency to 0.4.11 + cork-on-phone: Handle sink-inputs with NULL sinks + bluetooth: Pull a2dp-codecs.h from BlueZ + stream-restore: Check for readability before reading volume + volume: Get more data from volume tests + filter-apply: Make housekeeping optional + filter-heuristics: Only apply AEC if we're not already on a phone sink + filters: Handle stream moves properly + filters: Handle filters on sources as well + echo-cancel: Play nice with module-filter-* + filter-heuristics: Match roles correctly + filter-apply: Mark modules as being autoloaded + sink: Trivial typo fix + sample: Use PA_SAMPLE_INVALID instead of numeric value + core: Add a pa_format_info structure + format: Add some properties and internal API + sink: Extend API for compressed formats support + core: Add extended stream API to support compressed formats + format: Add convenience API to check if a format is PCM or not + sink: Remove PASSTHROUGH flag + tests: Add a trivial test for the extended API + sink-input: Minor cleanups + sink-input: Return NOTSUPPORTED if format negotiation fails + sink-input: Don't assert on bad formats + format: Avoid some code duplication + sink: Fix leak in pa_sink_check_formats() + sink-input: Kill passthrough streams if moving to an unsupported sink + core: Fix some FIXMEs for the extended API + alsa-mixer: Remove passthrough profiles + sink: Trivial typo fix in comment + core: Suspend monitor when a sink enters passthrough mode + alsa: Reconfigure sink sample rate for passthrough inputs + format: Const-ify some parameters + format: Add some convenience functions for printing + stream: Add API to get a stream's pa_format_info + introspect: Get formats for sinks + introspect: Get format of sink input + format: Add a type for DTS + core: Factor out passthrough checks into their own functions + filter-apply: Mark modules as being autoloaded + echo-cancel: Handle alignment requirement manually + echo-cancel: Remove unnecessary noalign attribute + sink-input: Don't print an error if a passthrough connection fails + sink-input: Don't restore volume for passthrough streams + sink-input: Add a format-lost event + format: Export pa_format_info_is_compatible in API + format: Add correct sample spec conversion for E-AC3 + sink-input: Provide more information to client when format is lost + format: Extend properties to handle lists/ranges + format: Add some convenience API for setting properties + doxygen: generate documentation for format.h + module-tunnel: Update for recent protocol changes + echo-cancel: Don't overpad variable + echo-cancel: Remove extraneous debug message + format: Fix channel map handling + echo-cancel: Add speex preprocessing + echo-cancel: Fix a crash is speex cleanup + tests: Update extended API test + echo-cancel: Fix preprocessor initialisation + echo-cancel: More preprocessing fixes + protocol-native: Use original requested latency on stream moves + protocol-native: Don't leak formats + stream: Fix a couple of format_info leaks + stream: Simplify passing of formats in extended API + source-output: Trivial code move + pactl: Add a set-source-output-volume command + echo-cancel: Set sane defaults for module initialisation + protocol-native: Fix backward compatibility break + protocol-native: Fix invalid assert + padsp: Handle eol in info callbacks correctly + protocol-native: Trivial fix for a compiler warning + doc: Document subscription events better + log: Add missing pulsecore/thread.h include + sink: Add a set_formats() API + alsa: Implement get/set_formats() + device-restore: Make bools not be bit fields + device-restore: Set sink format when possible + format: Make pa_format_info_snprint() more parseable + format: Add string to pa_format_info conversion function + pactl: Add a set-sink-formats command + sink: Fix lazy commenting + device-restore: Log invalid sink index while setting formats + Remind people not to break module-tunnel + proplist: Make filter properties line up prettily + filter-heuristics: Don't force AEC on all phone streams + conf: Load module-filter-* by default + build-sys: Bump JACK dependency to 0.117.0 + sink: Add a SET_FORMATS flag + alsa: Set SET_FORMATS flag when appropriate + format: Remove stupid copy-paste-o + source: Remove the PA_SOURCE_PASSTHROUGH flag + alsa: Don't always suspend/unsuspend on sink-input removal + formats: Use correct API to check for passthrough streams + alsa: Open iec958 device with NONAUDIO bit set in passthrough mode + formats: Fix bad passsthrough check + alsa: Fix bad function name + daemon: Fix compiler warning about missing function prototype + passthrough: We must not plug in a resampler on stream move + sink-input: Ensure no volumes are applied for passthrough streams + source-output: Ensure no volumes are applied for passthrough streams + Revert "device-restore: Make bools not be bit fields" + sample-util: Fix off-by-one in error check + sink: Add PA_SINK_SET_FORMATS macro + build-sys: Fix some LDFLAGS vs. LDADD usage + echo-cancel: Add multiple include protection for header + echo-cancel: Use pa_streq instead of strcmp + echo-cancel: Move speex preprocessing out of the main module + passthrough: Fix what volume we set sinks/sources to + passthrough: Fix setting volume to unamplified again + echo-cancel: Make save_aec modarg a bool instead of an int + echo-cancel: Don't allow streams to attach while unloading + echo-cancel: Get rid of annoying compiler warnings + equalizer: Comment out unused function + vala: Add has_type_id=false to all enums, structs and classes + stream: Relax assert for extended API + def: Hide server-side sink/source flags + volume: Handle varying channel count for shared volumes + virtual: Make volume sharing on by default + equalizer: Use volume sharing by default + echo-cancel: Use volume sharing by default + sink,source: Handle missing in the shared volume case + +Bart Cerneels (2): + echo-cancel: Speex preprocessor has to run *after* the AEC. + echo-cancel: Fix echo suppression, add some knobs + +Bryan Gleeson (1): + raop: Change socket buffer size handling to avoid playback underruns + +Cai Yuanqing (2): + coreaudio: Make coreaudio-detect safer by adding asserts before dereferencing + loopback: Add new arguments to disable stream move + +Cheng-Chia Tseng (4): + l10n: Updates to Chinese (Taiwan) (zh_TW) translation + l10n: Updates to Chinese (Taiwan) (zh_TW) translation + l10n: Updates to Chinese (Taiwan) (zh_TW) translation + l10n: Updates to Chinese (Taiwan) (zh_TW) translation + +Colin Guthrie (100): + stream-restore: Preventative initialistion to NULL + pacat: Don't use any buffer attr if we don't set any latency/process time params + cli: Allow .include on directories as well as files. + introspect: Include whether a stream is corked in the info callback. + log: Totally trivial spelling 'correction' (for en-US) + dbus: Fix log message after volume changes. + version: Drop the micro version number + doxygen: Fix version numbers for new features + build-sys: Add some smarts to version extraction from git tags. + volume: Trivial cosmetics (remove a space) + Revert "core: make use of dbus_message_iter_append_fixed_array" + core: Add a new hook PA_CORE_HOOK_CARD_PROFILE_CHANGED + x11: Make pax11publish -r remove PULSE_SESSION_ID + alsa-mixer: Fix a git-am cockup in b0f72311 + cork-on-phone: Only cork (and subsequently uncork) streams that are not already corked. + build-sys: No need to create folder for echo-cancel module. + bluetooth: Fix build errors relating to SBC + build-sys: Whitespace changes + build-sys: Fix bluetooth update-sbc now that it's in a subfolder. + build-sys: Make update-sbc, update-reserve and update-rtkit work in OOT builds + bluetooth: Run 'make update-sbc' + tunnel: Fix tunnel streams with recent servers + echo-cancel: Fix warning/typo + daemon: Fix regression with --start introduced with the double fork in 8e94f653 + po: Remove files no longer in the tree (and which didn't have any translations anyway). + daemon: Fix some more error paths in the double forking. + daemon: Fix regression introduced in f1d1447e. + dbus: Do not refcnt the core. + bluetooth: Fix a double-free-esque error introduced in 8f3ef04b + doc: Fix typo + equalizer: Use sink_master as the module argument rather than just master. + filter-apply: New module to automatically load filter sinks (and move streams) based on sink-input property hints. + filter-heuristics: New module that applies some basic heuristics regarding filters. + filter: Move the proplist defines into the central place and document them. + test: Make the connect-stress less likely to bail out due to >32 streams. + combine: Rename module-combine to module-combine-sink. + tests: Fix resampler-test. + i18n: Fix POTFILES + bluetooth: Fix early return styling and add missing return value + sink-input: Fix memory leak of proplist when sending format-changed events + protocol-native: Fix memory leaks introduced in protocol 21 (passthrough support) + pulsecore: Add a couple pa_asserts() on pa_tagstruct* calls. + combine: Fix a crash on shutdown if the module is loaded outside of our control. + build-sys: module-equalizer-sink needs dbus. + alsa-sink: Some trivial tidyups + introspect: Clear out memory properly on error. + def: Add some flags for source outputs. + capture: Add the passthrough format negotiation to capture streams. + introspect: Get formats for sources + capture: Implement per-stream volume control for capture streams. + introspect: Get format of source output + alsa: Remove unneeded include + streams: Tidy up includes + alsa-mixer: When setting hw volume, always round up with playback and down with capture. + capture: Remove support for synchronised capture streams. + esound,streams: Fix some crashes. + database: Convert our use of database files to save in tagstruct format. + device-restore: Add a new protocol extension for device-restore. + database: Support legacy format database entries. + alsa-mixer: Add an mixer profile exception for a BT Agile handset + alsa-mixer: Add UAC1.0 Sennheiser Dongle to the usb-headset profile. + alsa-mixer: Whoops, forgot to git-add this in a previous. + build-sys: equalizer-sink needs DBus aswell as FFTW + devices: Use wrapper functions to set the *_volume and *_mute callbacks. + devices: Set certain sink/source flags automatically. + alsa: Reinitialise the mixer on port change. + alsa-mixer: Do not 'unify' mixer paths. + alsa-mixer: Detect and then drop pointless paths in the path set. + alsa: No need to go via sink/source to get the core. + alsa-mixer: Remove workaround for USB head/handsets + reserve: Fix compile warning when compiling without dbus + source-output: Fix resampling. + stream-restore: Save/restore source output volume/mute + device-restore: Various fixes for the protocol extension. + pactl: Make stat backwards compatible with previous versions. + alsa-mixer: Fix rounding direction on mixer initialisation + alsa: Ensure that volumes are written to the h/w at startup. + ext-device-restore: Include format.h + sink-input: Drop redundant assert (PA_SINK_INPUT_IS_LINKED() checked already) + core: Unload the modules and cached samples before unref'ing the core. + def: Add a new enum to allow differntiation between sinks and sources. + dbus: Use pa_device_type_t rather than an internal equivalent + device-restore: Change the API to include type information (sink vs. source) + device-restore: Split device restore database into two parts. + device-restore: Restore volumes on port change. + device-restore: Simplify the migration of data to per-port keys. + stream-restore: Add in some variable sets that were missing from 9ffa93. + stream-restore: Add proper data validity checks to the legacy database entry read. + formats: The format code should be in libpulse, not libpulsecommon + formats: Export more functions needed for a clean build. + device-restore: Fix use-after-free error. + raop: Use the port supplied by avahi when connecting to RAOP devices. + bluetooth: Bump DBus version to 1.3.0 and drop conditional code. + alsa: Tidy up argument descriptions + modargs: Ensure modargs can be accessed in their raw form. + raop: Properly deal with the name coming from the device. + build-sys: Oops forgot to add the Kinect profile to the build system. + volume: Rename 'sync volume' to 'deferred volume'. + doc: Update README with fresh links. + build-sys: Switch to the tar-ustar format (as per a lot of GNOME stuff for 3.2) and distribute .xz files. + +Daniel Mack (34): + make bootstrap.sh aware of Darwin environment + Revert "make bootstrap.sh aware of Darwin environment" + buil-sys: fix build w/o DBus + Wrap clock_gettime and friends + Mac OS X: add semaphore implementation + configure.ac: enable check for CoreAudio + core-rtclock.c: tweak OS_IS_DARWIN constraints + poll() is totally broken on Mac OS X + hack around another OS X bug: recv() with MSG_PEEK does not work + CoreAudio: add device detection module + CoreAudio: add audio device module + osx: add native zeroconf implementation via Bonjour + fix a number of warnings + fix a number of warnings + osx: don't build the once-test binary on OS X + modules/coreaudio: replace deprecated functions + module-bonjour-publish: don't include avahi headers + alsa: Add two more ALSA audio card profiles + module-coreaudio-detect: fix variable assignment in pa__done() + osx: re-order module locations + osx: add -headerpad_max_install_names to LDFLAGS + configure.ac: add --mac-universal directive for OS X + osx: add routines for real-time thread scheduling + tests: add a connection stress test + pa_poll(): Simplify detection of invalid fds in select() emulation mode + module-coreaudio-detect: Add 'ioproc_frames' parameter + util: Implement pa_get_binary_name() for Mac OS X + pulsecore:: Define _POSIX_C_SOURCE locally for rtclock on OSX + thread-posix: Use pthread_(get|set)name_np() if available + module-coreaudio-device: Dispatch sink/source state messages from main loop + module-coreaudio-device: Set the thread name to device name + module-coreaudio-device: Fix two build warnings + build-sys: Make -isysroot and -mmacosx-version-min configurable + osx: pass -headerpad_max_install_names to the linker, too + +Daniel Schaal (1): + man: add manpage for start-pulseaudio-kde and start-pulseaudio-x11 + +Daniel T Chen (2): + build-sys: Add missing profile and alsa-mixer/paths to src/Makefile.am + alsa: Handle 'Digital Mic' as an 'Input Source' + +David Henningsson (25): + alsa-mixer: Add a few well-known descriptions + alsa-mixer: add required-any and required-* for enum options + alsa-mixer: always round towards 0 dB + alsa-mixer: Add new paths for Internal Mic, Front Mic, Rear Mic and Dock Mic + alsa-mixer: Fixup "Mic"/"Line"/"analog-input" paths to work with the new paths + alsa-mixer: Make sure capture source and input source use right path + alsa-mixer: Add support for "Line Boost" element + alsa-mixer: Add workaround for some USB headsets + protocol-native: Allow clients to know at what index underrun occurred + Fix crash in path subset elimination + Document PA_COMMAND_UNDERFLOW protocol change + alsa-mixer: Mute IEC958 optical raw for several Audigy models + alsa-mixer: Add "Line HP Swap" element + JACK: Load module-jackdbus-detect in default.pa + Remove offensive part of error message + switch-on-connect: Don't switch to a monitor source + Fix spelling sucess -> success + Set better priorities on input paths + module-switch-on-connect: Don't switch unlinked sink input and source outputs + alsa-mixer: Set "Front" control to 0 dB on headphone path + raop: Don't crash if fd is not open when trying to close it + sink,source: Avoid crash by not updating volume on shutdown + conf: Make sure module-dbus-protocol is loaded after module-default-device-restore + dbus: Don't crash if the module does not load + Fix crash in threaded message queues + +Diego Elio Pettenò (12): + Fix out-of-tree builds when dbus module is enabled. + Add check for FFTW, and add option to disable it at build-time. + Move the platform-specific defines after the compiler has been found. + Fix build on Solaris: pass the third parameter to pa_cloexec_open. + Don't declare the variable l if FIONREAD is not defined. + Include sys/filio.h if present; this makes use of FIONREAD on Solaris. + Check for stow using AC_CHECK_PROG rather than type -p. + Simplify handling of NetBSD atomic ops discovery. + Since now we have FreeBSD atomic operations, don't require libatomic_ops. + Rename all the signal parameters and variables to something more explicit. + Avoid using devname as a variable name. + Simplify Makefile.am handling of ALSA-related files. + +Dimitris Glezos (1): + l10n: Updates to Greek (el) translation + +Edward Rudd (3): + coreaudio: Fix call to pa_thread_new + solaris: update call of pa_thread_new to new prototype + sconv_sse: Exclude SSE optimizations for Mac OS X + +Fritz Elfert (1): + Disable check for pthreads on win32 + +Gustavo F. Padovan (1): + sbc: Fix redundant null check on calling free() + +Harri Mähönen (1): + stream-restore: add version to new entry. + +Henning Heinold (2): + src/Makefile.am: add missing space to fix build using uClibc + build-sys: look for function 'backtrace' also in library 'ubacktrace' + +Jason Newton (48): + module-equalizer-sink added src/Makefile.am: added module-equalizer-sink + module-equalizer-sink: added temporary debugging output to track filter output removed dead code only a small amount of crackling remains + module-equalizer-sink: added more assertions to aid in debugging + module-equalizer-sink: attempt different buffering strategy + module-equalizer-sink: trying new buffering strategies + module-equalizer-sink: simplified sink_input pop callback and introduced new variables that simplify different strategies. + module-equalizer-sink: first commit of a working state (cpu speed dependant) added noop processing for filter debugability + module-equalizer-sink: removed liboil added sse2 optimized dsp logic implementation cleaned up a bit + module-equalizer-sink: added dbus support removed cruft from inherited from ladspa module and improved clarity switched dsp processing to reference implementation until project is more mature tsched=0 seems to help with the micro-dropouts/crackling! oh my! reformatting/spaces + module-equalizer-sink: added support for suspend/resume of filter coefficients unregister the correct dbus interface. made equalizer state file sink index dependent expanded dbus properties whitespace + module-equalizer-sink: dbus properties and manager so that multiple sinks can be loaded and mixers can be equalizer-sink aware functionality to seed new filters quickly (rteq guis) profile support extra checking in client->server dbus messages + module-equalizer-sink: add lennard's fix for piggy-back sinks in pop_cb fixed some tsched issues + module-equalizer-sink: reverted buffering logic back to how the ladspa sink did it + module-equalizer-sink: dbus: eliminated some redundant code in dbus handlers/getall switched filter back to being a property signals for changed profiles, added/removed sinks, filter updates and sink reconfigurations fixed timing routines + module-equalizer-sink: proper fix for pa_xmalloc(0) given that 0 is illegal fix coefficients in case there's no resume state loadprofile now signals filterchanged + module-equalizer-sink: fix for peek returning a null memblock pa_log -> pa_log_debug for fft size updated module description fixed a comment in dbus error for incorrect x positions + module-equalizer-sink: reworked processing so we don't have input->output delay of R samples + module-equalizer-sink: merging in upstream changes whitespace fix and fix for first iteration un-windowing + module-equalizer-sink exchanged improper usage of memblockq_peek'd memchunk for silence block dropped unneeded function prototypes changed mround to be slightly more elegant __restrict__ -> restrict for c99 removed unneeded pa_aupdate_swap calls first_iteration -> pa_bool_t cleaned up some usage of pa_malloc0 where pa_new0 was more appropriate cruft removal, whitespace fixes and reordering of variables + module-equalizer-sink.c i->sink -> i in pa_get_sink_max_request* + module-equalizer-sink.c: swapped order of attach_within_thread and set_max_request within sink_input_attach_cb + module-equalizer-sink: fixed timeval initialization + module-equalizer-sink: drop old macros for new library based ones + module-equalizer-sink: added support for preamp + module-equalizer-sink: fixed a bug w/ new zero-latency input scheme (that was an interesting/cool bug!) + module-equalizer-sink: per-channel filtering support + profiles, easier default configuration + module-equalizer-sink: added server side persistance of profile names + module-equalizer-sink: fix improper usage of pa_modargs_get_value_boolean for u->set_default + module-equalizer-sink: resync with ladspa parent sink + module-equalizer-sink: resyncing with head and fix invalid writes * pa_log->debug for default equalizer notification * partially fixed infinite rewind bug * set max_request to window_size first iteration * swap order inside ROUND_UP calls * resync pa_sink_input_new changes * change pa_sample_clamp parameters to be correct to fix invalid writes * reenable proper reset logic + proper request size + module-equalizer-sink: *added client initiated sync support for filter state *added note of possible unstable behavior with next-power-of-2 sample rate calculation + module-equalizer-sink: disable active profile name restoration as something in pack/unpack is funky and I don't have time for a proper fix + module-equalizer-sink: fixed equalizer state save/restore + module-equalizer-sink: *fixed SSE2 optimized dsp logic (default if available) *cleaned up whitespace formatting (again) + module-equalizer-sink: drop source executable permissions configure.ac: add enable/disable + summary line for fftw + module-equalizer-sink: fixed equalizer state save/restore + module-equalizer-sink: *fixed SSE2 optimized dsp logic (default if available) *cleaned up whitespace formatting (again) + module-equalizer-sink: drop source executable permissions configure.ac: add enable/disable + summary line for fftw + drop redundant alloc call + module-equalizer-sink: try to limit buffering to mempool's max_block_size and disable debug output + module-equalizer-sink: add premultipliar to sse2 dsp_logic implementation + module-equalizer-sink: (re)added output memblockq commented out timing debug statements + module-equalizer-sink: switch back to reference dsp implementation - cpu usage doesn't really change and there may be a bug in the vectorized version + module-equalizer-sink: add latency of output_q and input_q to get latency calculation + added qpaeq script for GUI equalizer control to src/util + remove .py extension from qpaeq + Makefile.am: added qpaeq to installed scripts + src/utils/qpaeq: added more friendly error messages to common errors + +Jens Georg (2): + rygel: Properly close {sv} iters for GetAll + rygel: Fix introspection XML for MediaItem2 + +Joe Marcus Clarke (2): + freebsd: fix atomic ops implementations + freebsd: implement pa_get_binary_name + +Jonny Lamb (2): + introspect: fix source output and sink input docs mix-up + introspect: fix typo in default sink/source docs + +João Paulo Rechi Vita (2): + bluetooth: improve dbus logging + bluetooth: add HFP Gateway support + +Juho Hämäläinen (3): + alsa-sink: take base volume into account when applying hw volume + bluetooth-device: fix rounding errors caused by few bt volume steps + alsa-mixer: select nearest alsa volume step in sync-volume mode + +Jyri Sarha (15): + core: Add infrastructure for synchronizing HW and SW volume changes + alsa: Take syncronized HW volume infra into use for alsa-sink + udev-detect: Add sync_volume parameter + daemon-conf: Add sync volume parameters to daemon-conf + man: sync_volume parameters to manual page + core: New LIFO style flist implementation v2.2 + core: Lower "flist is full" log message level to debug and ratelimit it + core: Add name to flist struct for more informative log messages + core: Change sematics of pa_flist_new_with_name() (v1.1) + core: Use volume_change_safety_margin when rewinding sync-volume events + core: Use pa_sink_get_latency_within_thread() in sync-volume code + alsa-sink: Fix double use of string + alsa-sink: Don't assume we were able to enable hw-volume or sync-volume (v1.1) + protocol-native: Stop auto timing updates if connected to suspended sink or source + suspend-on-idle: Trigger mempool vacuuming + +Kim Lester (2): + configure.ac: add DARWIN_OS variable + src/Makefile.am: add specific OS_IS_DARWIN files + +Kim Therkelsen (2): + Support for multichannel DSP processing in module-ladspa-sink + core: Added new hooks: PA_CORE_HOOK_SOURCE_PORT_CHANGED and PA_CORE_HOOK_SINK_PORT_CHANGED + +Kurt Taylor (1): + PulseAudio: added IT block to fix thumb conditional instruction build error messages + +Lennart Poettering (41): + memblock: decrease tile size to 64k again + libpulse: introduce pa_context_get_tile_size() call + clients: drop definition of BUFSIZE which is unused + pactl: include information about client context in pactl stat output + pactl: format cookie a little bit nicer + libpulse: introduce PA_STREAM_RELATIVE_VOLUME + smoother: add comments about optimization recommendations from Jason Newton + simd: update test cases + core-util: introduce FD_CLOEXEC wrappers for open/socket/pipe/accept + use cloexec wrappers wherever applicable + core-util: make sure to enable FD_CLOEXEC unconditionally to cope with kernels that silently accept but ignore O_CLOEXEC + core-util: introduce pa_fopen_cloexec() + tdb: use O_CLOEXEC if available + use pa_fopen_cloexec() where applicable + socket-util: allocate at least sizeof(sockaddr_storage) space + socket-util: drop redundant casts + git: ignore kde related files + daemon: make sure pa has its own session and process group, but is not its leader so that we cannot acquire a tty ever + ramping: minor cleanups + pulse: ask for timing updates both *before* and *after* triggering a stream state change so that in the STARTED/UNDERFLOW callbacks we accurate transport latency information + tests: add pa_once_xxx() test + client: introduce auto-connect-localhost= option in client.conf + client: introduce auto-connect-display= following the scheme of auto-connect-localhost= + native: fallback to another port if the default port is taken + native: when run in system mode, do not look for fallback port + start: we don't need to check for $PULSE_SERVER anymore + shm: explicitly mark shm seg for MAP_NORESERVE to request overcommiting no matter what + pactl: implement pactl subscribe + Revert "pacat: Don't use any buffer attr if we don't set any latency/process time params" + build-sys: fix check for pthread_setaffinity_np() + i18n: update LINGUAS + i18n: run make update-po + conf-parser: make use of pa_strip() wherever applicable + iochannel: remove fd from poll() when we don't care from events + various modernizations + equalizer: various smaller cleanups for m-e-s + virtual: minor simplifications for the virtual sink + virtual: document how to implement fixed block size filters + virtual: when fixed block sizes are used the memblockq must have a silence block + tests: fix once test + memblockq: decode unset chunks as NULL chunks again + +Leonid Kurbatov (13): + l10n: Updates to Russian (ru) translation + l10n: Updates to Russian (ru) translation + l10n: Updates to Russian (ru) translation + l10n: Updates to Russian (ru) translation + l10n: Updates to Russian (ru) translation + l10n: Updates to Russian (ru) translation + l10n: Updates to Russian (ru) translation + l10n: Updates to Russian (ru) translation + l10n: Updates to Russian (ru) translation + l10n: Updates to Russian (ru) translation + l10n: Updates to Russian (ru) translation + l10n: Updates to Russian (ru) translation + l10n: Updates to Russian (ru) translation + +Leszek Koltunski (1): + X11: attach X11 properties to Screen, not Display + +Lu Guanqun (7): + alsa-mixer: Fix the assumption that volume is always positive + log: add thread name + sample-util: use built-in function + i18n: po file fixes + memblock: fix memory leak when pa_shm_create_rw fails + memblock: use built-in function + pacat: make pacat respond to cork/uncork events + +Luiz Augusto von Dentz (14): + bluetooth: Add support for Media API + bluetooth: make use of dbus-util helper functions + core: make use of dbus_message_iter_append_fixed_array + bluetooth: fix case of profile UUIDs to match what BlueZ uses + bluetooth: fix build for libdbus < 1.3 + bluetooth: detect when bitpool has changed on sbc codec + bluetooth: handle Acquire API change + bluetooth: reduce bitpool if audio start skipping + bluetooth: fix a2dp_process_push + bluetooth: add proper handling for bluetooth.nrec property + build: move sbc related files to its own directory + bluetooth: Fix not updating sample spec when using Media API + bluetooth: Fix using pointer-pointer when appending an array as variant + bluetooth: Only close SCO if status has changed + +Maarten Bosmans (119): + module-rtp-recv: Request proper rewind after underrun + build: Use MODULE_LIBADD in Makefile.am + build: Generate module symdefs in src/modules directory + build: Don't include empty Makefile.am in subdirs + build: Remove unnecessary flags in AM_CFLAGS + Use setenv instead of putenv + Clean up <poll.h> includes + Use <pulsecore/socket.h> instead of <sys/socket.h> + Adapt win32 specific code to current API + Apply #ifdefs around functionality not available on win32 + Use PCRE if POSIX regex.h is not available + Fix dependencies and include necessary headers + Add AM_LDFLAGS more consistently to all commands + Repair some typos + Implement some functions for win32 + win32: flush stderr after log output + win32: Implement rtclock based on QueryPerformanceCounter + win32: Implement pa_random + module-waveout: Adapted to updated API + Give module-waveout a configure switch + Use pa_* instead of generic functions to improve portability + tests/rtstutter: Use pa_rtclock + Use pa_read, pa_write and pa_poll instead of system functions + Include <time.h> where necessary + Get rid of some unused-function compiler warnings + Various fixes for build warnings + configure: Drop some warnings + Fix up according to Coding Style + Fixup #include directives according to Coding Style + build: Use silent rules for generating files + module-waveout: Add device_name parameter + build-sys: Flip default to no git pull on make dist + Fix up some double spaces + Make pulse compile with clang + Update PA_MODULE_USAGE to be in line with actual implementation + Find modules and config files relative to the installed libraries. + build: copy instead of link pacat to other utils on win32 + build: Protect some more variables by ifdefs + Use pulsecore/arpa-inet.h to make arpa/inet.h functionality available + Fix pa_rtclock_from_wallclock + module-waveout: Query device for supported samplerate + module-waveout: Move thread creation + module-waveout: Fix record/playback args + Get rid of some warnings: -Wunused-result + Get rid of some warnings: -Wunsafe-loop-optimizations + Get rid of some warnings + win32: Simplify dl_search_path code + Move compile-time checks around pa_run_from_build_tree to core-util + pactl: Accept more volume specification formats + pactl: Add subcommands to the list command + pactl: Separate stat and info actions + pactl: Add short output format for list action + build-system: Simplify AC_ARG_ENABLE usage + build-system: Use AS_IF macro for configure output + build-system: Move AC_DEFINE to separate line with AS_IF + build-system: Move dependency error messages to outer scope + build-system: Replace some more conditionals with AS_IF + build-system: Rearrange database selection + build-system: Small fixes + Make connect-stress test compile for win32 + win32: define WIN32_LEAN_AND_MEAN + build-sys: Remove unnecessary AC_SUBST calls + build-sys: Consolidate host_os handling + build-sys: Reset CFLAGS after DBUS check + build-sys: Define PA_CFLAGS at right time + build-sys: Clean up configure.ac + build-sys: Move some stuff around in configure.ac + build-sys: Move acx_lirc.m4 contents to configure.ac + build-sys: Use AX_TLS macro from autoconf archive + build-sys: Use AX_CHECK_DEFINE macro from autoconf archive + build-sys: Use AX_PTHREAD macro from autoconf archive + Remove unnecessary #includes + Remove obsolete description property from modules + Add sys/time.h include to rtclock.c + build-sys: Cleanup Makefile.am + win32: Make once-test work + win32: Make some unused-variable warnings go away + Update todo + Remove libpulse-browse and pabrowse + build-sys: Update orc.m4 to latest upstream version + build-sys: Use ax_check_flag macros from autoconf archive + build-sys: Use AX_DEFINE_DIR macro instead of setting AM_CFLAGS + build-sys: Move some more defines from CFLAGS to config.h + parecord: Automatically detect file format from extension + build-sys: Move some more defines to configure.ac + build-sys: Use configure AC_OUTPUT to process config files + build-sys: Process configuration files with m4 + build-sys: Add more build-time conditionals to config files + build-sys: Fix handling of Bluez, Hal dependency on D-Bus + module-waveout: Correctly handle mono volume controls on waveout device + build-sys: Check for necessary programs in bootstrap.sh + Fix default.pa on non udev systems + pactl: Update manpage + pactl: Short --help output a bit by consolidating sink/source commands + pactl: Split help string up in shorter pieces for easier translation + Include config.h consistently in source files and not in headers + Add some missing format.h includes + Move i18n.[ch] to src/pulsecore + Plug some memory leaks and an invalid read + module-tunnel: Fix for new protocol versions + Plug some memory leaks + Initialise variables + Avoid read from freed memory + Initialise write_volume + default.pa: Update rtp null sink line + pactl: Add set-source-output-mute command + Spelling fixes in public headers + More spelling fixes + gitignore: Add Orc autogenerated files + echo-cancel: Use stream index in debug message + Remove extra ; s where they are not allowed in strict C99 + sndfile-util: Check return value of sf_command for errors + module-equalizer-sink: Use %z for printf of size_t variables + module-equalizer-sink: Use = in initialising variables + bluetooth/sbc: Use __asm__ keyword + module-equalizer-sink: Use correct limit in loop + Squash the last gcc warnings + Make gcc --std=c99 happy + module-suspend-on-idle: Move vacuum code to core + +Maarten Lankhorst (1): + bluetooth: Fix a2dp processing + +Mads Kiilerich (1): + headers: Some trivial fixes for some documentation typos + +Marc-André Lureau (9): + bluetooth: use sco_sink/source to start with right state + bluetooth: fix set_volume_cb on sco over pcm + bluetooth: restore original sco_{sink, src}->set_volume when unloading + bluetooth: drop data every 500ms on oor condition + interpol-test: remove unused include getopt.h + tests: improve resampler test + match: Don't double free in case of missing table file + match: Match rule earlier, in SINK_INPUT_NEW + module-null-source: New null-source module + +Michael Terry (1): + switch-on-connect: Add a new module to allow for hotplugged devices to be used by default. + +Pascal Terjan (2): + l10n: Updates to French (fr) translation + l10n: Updates to French (fr) translation + +Paul Menzel (9): + Typo. s/a/are/ + man pages: correct formatting/markup of options + client.conf.in: Typo. s/a/are/ + man: Clarify wording in volume sync documentation. + man: Reference correct `--use-pid-file` and fix typo (`s/Of/If/`). + build-sys: Correct typos in configure + tunnel: Remove bogus `{` + bluetooth: run `make update-sbc` to pull in build fix for thumb mode + .gitignore: add `.tarball-version` + +Pierre-Louis Bossart (9): + rtpoll: better support for DEBUG_TIMING logs + virutal-sink: boilerplate virtual sink to add PCM processing + virtual-source: boilerplate virtual source for PCM processing on inputs + virtual-sink,source: enable virtual-source and virtual-sink + alsa: fix mixer profiles, add passthrough config + alsa: add missing iec958 files from previous commit + AC3 passthrough support + alsa: disable period wakeups in tsched mode if possible + sink-input: Don't resample passthrough inputs + +Ralph Giles (1): + Fix two comment typos. + +Siarhei Siamashka (13): + sbc: ensure 16-byte buffer position alignment for 4 subbands encoding + sbc: added saturated clipping of decoder output to 16-bit + sbc: new 'sbc_calc_scalefactors_j' function added to sbc primitives + sbc: MMX optimization for scale factors calculation + sbc: ARM NEON optimization for scale factors calculation + sbc: fix signedness of parameters + sbc: ARM NEON optimized joint stereo processing in SBC encoder + sbc: ARM NEON optimizations for input permutation in SBC encoder + sbc: slightly faster 'sbc_calc_scalefactors_neon' + sbc: faster 'sbc_calculate_bits' function + sbc: added "cc" to the clobber list of mmx inline assembly + sbc: ARMv6 optimized version of analysis filter for SBC encoder + sbc: add iwmmxt optimization for sbc for pxa series cpu + +Sjoerd Simons (1): + build-sys: Link libpulse directly to libdbus-1 if needed + +Tanu Kaskinen (154): + Create module-dbus-protocol with "Hello, world!" functionality. + daemon: Implement the DBus server lookup service. + dbus-protocol: Connection handling for local connections. + dbus-common: Implement infrastructure for registering D-Bus objects on all client connections and for receiving method calls from clients. + dbus-protocol: Implement TCP server startup. + module-dbus-protocol: Allow anyone to connect the daemon in system mode. + module-cli: Fix compilation by adding libpulsecommon to module_cli_la_LIBADD. + server-lookup: Update the D-Bus identifiers to be versioned. + dbus: Implement the Name property of the core object. + Finish the Core dbus interface. + Add the forgotten src/modules/dbus directory to git. + Bug fixing and minor cleanups. + dbus/iface-core.c: Make sure D-Bus objects are created only once. + dbus-protocol: Implement extension registration. + dbusiface-core: Send signals whenever extensions are registered and unregistered. + dbusiface-core: Don't die if we get a default sink/source change event before the new default device is actually created. + dbus-protocol: Add debugging output (temporary change). + dbus-util: Fix broken proplist reading logic. + stream-restore: Expose module to D-Bus. + dbusiface-core: Make the interface string a public constant. + dbus-protocol, dbusiface-core: Take a reference when storing the core pointer. + dbus-protocol: Make debug logging saner. + dbus-protocol: Remove erroneous protocol object unref. + dbusiface-memstats: Implement the Memstats D-Bus interface. + proplist: New function: pa_proplist_equal() + dbus: Three entangled changes: + dbus: Take advantage of the PA_HASHMAP_FOREACH macro. + dbusiface-core: Generate more informative error messages. + dbusiface-core: Add functions for getting various object paths. + dbus-util: Add helpers for proplist handling. + dbus-util: Trivial comment punctuation fix. + dbus-protocol: Split some overly long lines. + dbus-protocol: Take advantage of the helpers in dbus-util. + dbusiface-card: Implement the Card D-Bus interface. + dbusiface-card-profile: Implement the CardProfile D-Bus interface. + dbus-protocol: Add a note for _send_signal that by default the signal isn't actually sent. + dbus-protocol: Fix signal sending for the case when the client doesn't listen for all signals. + dbusiface-card: Split some overly long lines. + dbusiface-card-profile: Assert the core argument isn't NULL. + dbusiface-card: Use the ++ operator like it's meant to be used. + dbusiface-card: Assert that the profiles list is empty if there's no active profile. + dbusiface-card: Fix the OwnerModule property type in handle_get_all(). + dbusiface-core: New function: pa_dbusiface_core_get_card_path(). + dbus-protocol: Use pa_hashmap_remove() instead of _get(). + dbusiface-device: Implement the Device and DevicePort D-Bus interfaces. + dbusiface-core: Two new functions: pa_dbusiface_core_get_playback/record_stream_path(). + dbusiface-client: Implement the properties of the Client D-Bus interface. + dbusiface-client: Fix the interface name. + dbusiface-client: Fix indentation. + dbusiface-device: Free the copied proplist. + dbusiface-stream: Implement about a half of the Stream D-Bus interface. + namereg: Revert default device handling back to the upstream version. + dbusiface-core: New function: pa_dbusiface_core_get_client_path(). + dbusiface-core: Two new functions: pa_dbusiface_core_get_sink/source(). + dbusiface-device: Split some overly long lines. + dbusiface-device: Use a single if-else section instead of ternary operator overuse. + dbusiface-device: Fix argument reading in handle_suspend(). + dbusiface-device: Save one level of identation by returning early. + dbusiface-stream: Finish the Stream D-Bus interface. + dbusiface-core: Split some overly long lines. + dbusiface-core: Use the PA_IDXSET_FOREACH macro. + dbusiface-core: Assert that _add/remove_interface calls succeed. + dbusiface-sample: Implement the Sample D-Bus interface. + dbusifaca-device: Adapt to the changed pa_sink_get/set_volume() interface. + proplist: Return early from pa_proplist_equal() if the pointers are equal. + proplist: A couple of documentation fixes. + modargs: New function: pa_modargs_iterate(). + dbus-protocol: Print a debug line whenever interfaces are unregistered. + dbusiface-module: Implement the Module D-Bus interface. + dbus: Save one level of identation by returning early. + dbus: Make sure that subscription callbacks don't try to access removed objects. + dbusiface-stream: Only send stream event signals from the right D-Bus objects. + dbus: Finish the Client D-Bus interface. + dbus: Do message argument type checking early, centrally. + dbusiface-core: Add signals FallbackSinkUnset and FallbackSourceUnset. + dbus: Change IsMuted property names to Mute. + dbus-protocol: Implement argument type checking for normal methods. + dbusiface-client: Fix the destructor (stop leaking stuff). + dbus: Handle the cases when a non-existing interface is detected in an incoming message. + dbus: Add a missing break statement in handle_message_cb(). + stream-restore: Fix a few assertion misuses with the D-Bus code. + stream-restore: Add a missing pa_xnew0() call in handle_add_entry(). + stream-restore: At startup, create dbus entries only for valid database entries. + idxset: Fix _get_by_data() comment. + sink-input: Replace a tab indentation with spaces. + daemon: Don't autospawn if a server address is explicitly configured. + alsa-mixer: Use pa_xfree() instead of pa_xstrdup() for freeing a string. + alsa-mixer: Replace erroneous PA_ALSA_VOLUME_IGNORE with PA_ALSA_ENUMERATION_IGNORE. + alsa: Fix log output to inform about positive base volumes correctly. + cli: Increase the command maximum length from 1024 to 2048. + dbus: Make it possible to allow remote connections from outside localhost. + dbus: Initialize properly the type field of new server structs. + dbus: Fix segfault when receiving a property access call that isn't permitted. + stream-restore: Fix segfaulting. The dbus entry callbacks expect a dbus_entry pointer instead of a userdata pointer. + dbus: Use a struct as the hashmap items for listening_signals. + dbus: Fix slightly messed up assertions. + stream-restore: When changing restore entries with D-Bus, apply the changes immediately. + dbus: Stop polling every 10 seconds to check whether all clients are still alive. + dbusiface-core: Track sinks and sources using synchronous hooks instead of asynchronous subscription events. + loopback: Make stream names and roles configurable. + core: New function: pa_module_update_proplist(). + module-alsa-card: New argument: namereg_fail. + module-udev-detect: When loading module-alsa-card, use namereg_fail=false. + alsa-sink/source: Use the "namereg_fail" module argument. + alsa: Print dB values in addition to percentages in debug messages. + core: Link virtual sinks and sources to their streams. + dbusiface-stream: Send the Device property in the GetAll handler. + Allow read-only or non-existing sink input volume. + alsa-mixer: Fix path set building when using the element-output or element-input mapping options in profile set configuration. + alsa-card: Add a new modarg "profile_set" for giving the card a custom profile set configuration file. + Implement the "volume sharing" feature. + virtual-sink: Add a modarg for enabling volume sharing. + virtual-sink: Add a modarg for forcing flat volume. + virtual-sink/source: Use a more descriptive stream name. + virtual-sink/source: Remove an unused variable. + virtual-sink: Fix a crash when moving the sink to a new master right after setup. + sink: Don't send unnecessary PA_SINK_MESSAGE_SET_SHARED_VOLUME messages. + sink: Add casts to some printf arguments to get rid of compiler warnings. + Add src/*-symdef.h to .gitignore. + alsa-mixer: Add DecibelFix section to the profile set config file format. + alsa-mixer: Use decibel fixes when getting and setting decibel volumes. + pacat: Fix memory leak when draining the context. + alsa-mixer: Add a default case for a switch, so that the compiler won't complain about unhandled cases. + alsa-card: Print the profile set configuration when loading the card. + dbusiface-stream: Fix crash when there's no resampling used. + dbus: Always accept mono volumes when setting device or stream volume. + alsa-mixer: Implement support for setting element specific upper limits for volume. + alsa-mixer: When figuring out the max_dB of a path, use only channels that are used by the path elements. + alsa-mixer: Implement constant volume. + alsa-mixer: Refactoring: merge element_mute_volume(), element_zero_volume() and element_apply_constant_volume() into a single function. + bluetooth: Don't log an error if an endpoint type is disabled. + bluetooth: Get rid of warnings about unused stuff when building against a D-Bus version that doesn't have fd-passing support. + .gitignore: Add ChangeLog to the ignore list. + alsa-mixer: Get rid of a compiler warning. + sink-input: Add volume_writable to pa_sink_input. + alsa-mixer: Make probing elements with more than two volume channels fail. + alsa-mixer: Make sure that SND_MIXER_SCHN_UNKNOWN isn't used when indexing e->masks. + alsa-mixer: Check that the kernel driver returns consistent limits with both snd_mixer_selem_get_*_dB_range() and _ask_*_vol_dB(). + bluetooth: Drop all "#ifdef NOKIA" directives. + bluetooth: Fix HSP volume handling. + alsa: Fix log output to inform about positive base volumes correctly. + sink-input: Check flat volume with pa_sink_flat_volume_enabled(). + protocol-dbus: Fix some memory management bugs. + stream-restore: Enable database dumping if DEBUG_VOLUME is defined. + match: Support for both merging and replacing proplist updates. + dbus: Fix connection idxset freeing when unloading the module. + dbus: Fix the order of freeing stuff when unloading module-dbus-protocol. + loopback: Add a modarg for disabling remixing. + gitignore: Add connect-stress, extended-test and format-test. + bluetooth-discover: Remove remaining ifdef NOKIAs. + virtual: Fix volume callback setting. + daemon-conf: Don't make log files executable. + svolume: Make log messages more precise. + loopback: New modargs: sink_input_properties and source_output_properties. + +Vincent Becker (3): + Correct wav file creation for 24/32 and 24 bits sample formats HSD=3669357 + log: Add a new log target to a file descriptor + log: Correct bad function implementation + +Vladimir Kokarev (2): + volume: add pa_cvolume_inc_clamp function + lirc,mmkvd: added module parameters volume_limit, volume_step + +Wang Xingchao (3): + alsa: Update process_usec before going to sleep + alsa: resets POLLOUT event + sink-input: Avoid fake rewind in corked state + +Wu Fengguang (1): + alsa-sink: fix mmap_write() work_done + +amitakhya (1): + Sending translation for Assamese + +anipeter (1): + Sending translation for Malayalam + +chocolateboy (1): + Fix typo in log message: s/may no be/may not be/ + +elad (1): + Sending translation for po/he.po + +hedda (1): + Sending translation for German + +huan zheng (1): + core: volume ramping fix + +ifelix (1): + Sending translation for Tamil + +jassy (1): + Sending translation for Punjabi + +khasida (3): + Sending translation for Japanese + Sending translation for Japanese + Sending translation for Japanese + +kkrothap (1): + Sending translation for Telugu + +leahliu (1): + Sending translation for Chinese (Simplified) + +mgiri (1): + Sending translation for Oriya + +mrtom (1): + Sending translation for French + +rajesh (1): + Sending translation for Hindi + +runab (1): + Sending translation for Bengali (India) + +sandeeps (1): + Sending translation for Marathi + +shanky (1): + Sending translation for Kannada + +snowlet (1): + Sending translation for po/zh_TW.po + +swkothar (1): + Sending translation for Gujarati + +ypoyarko (1): + Sending translation for Russian + +zbt (3): + Add volume ramping feature - envelop fix + Add volume ramping feature - sink-input modification + Add volume ramping feature - sink modification + +zerng07 (1): + l10n: Updates to Chinese (Taiwan) (zh_TW) translation +"""]]
\ No newline at end of file diff --git a/Software/PulseAudio/Notes/2.0.mdwn b/Software/PulseAudio/Notes/2.0.mdwn new file mode 100644 index 00000000..403f84f8 --- /dev/null +++ b/Software/PulseAudio/Notes/2.0.mdwn @@ -0,0 +1,452 @@ + +[[!inline pages="Software/PulseAudio/TOC" quick="yes" raw="yes"]] + + +# Release Notes + +Just a little over 6 months after our last release, we're back with another one! While a little later than promised, this release contains a lot of awesome new features. Also, a big welcome to our 2 new committers, David Henningsson and Tanu Kaskinen (who squashed the last of the 2.0 blockers). + + +## Key Features + +* Alternate sample rates +* Jack detection +* Echo cancellation: WebRTC canceller, automatic gain control, drift compensation +* Virtual Surround module +* Xen Paravirtualised audio sink +* Fixed HURD support +* A2DP decoder quality improvements + +## Packaging + +* The `webrtc` echo canceller depends on a new library: [[webrtc-audio-processing|http://www.freedesktop.org/software/pulseaudio/webrtc-audio-processing/]] +* The `adrian` canceller is optional and will likely be dropped in a future release +* The Speex library is now optional (but highly recommended -- don't drop this unless you really know what you're doing) +* Xen support has been added and will be of interest while building gest images + +## Features in more detail + + +### Alternate sample rates + +A lot of common (desktop) hardware supports multiple sample rates. Interesting, among these, are 44100 Hz and 48000 Hz, since all common sample rates can be expressed as a simple multiple of one of these, which implies cheaper resampling, when it is required. Previous versions of PulseAudio only supported opening the device at a single sample rate, requiring all streams that did not match this rate to be resampled. We now support switching the device's sample rate dynamically at run time, allowing us to avoid resampling, or reduce resampling overhead. This should result in CPU and power savings on hardware that supports such switching (most Intel HDA-based devices at least). + + +### Jack detection + +With PulseAudio 1.0, we added infrastructure to loosely support the concept of "ports", which are meant to be mapped to actual supported audio paths (read: physical outputs like your speaker or 3.5mm jack). These needed to be dealt with manually, and thus were not too interesting to users. With PulseAudio 2.0 and a recent Linux kernel (3.3.0 or higher), we now automatically detect whether a jack is plugged in to your device or not, and act accordingly. Currently, this buys us the ability to manage volumes for different outputs separately, and future work will allow more advanced features like easing the set up of multichannel output, etc. + + +### VOIP improvements + +The echo cancellation module got significant improvements with the addition of support for a new echo canceller based on the code from the [[WebRTC.org|http://www.webrtc.org]] project. This canceller has a much shorter learning time, and is generally of higher quality than the previous default Speex canceller (which is still available). The module also uses the WebRTC.org code to add automatic gain control (AGC) which the microphone volume automatically adjust to the input sound level, and drift compensation to allow echo cancellation between different devices (such as speakers on your laptop and the microphone on your USB webcam). + + +## Next Steps + +While this release was delayed by ~1.5 months, we are continuing to work towards a shorter release schedule of 4 months in order to get new features out early and often. There will, be intermediate point releases for major fix and regressions (but that could never happen, right? ;)). + + +## git shortlog + + +[[!format txt """ +Alexander E. Patrakov (1): + alsa: add DTS profile + +Antti-Ville Jansson (1): + stream: Fix upload samples' cleanup + +Arun Raghavan (97): + extended: Fix doxygen comment style typos + sink,source: Avoid unnecessary call to pa_rtclock_now() + alsa: Give compressed formats preference over PCM + alsa: Better error handling in mixer rtpoll callback + echo-cancel: Fail if loaded between a sink and its monitor + alsa: Make mixer error handling more robust still + echo-cancel: Add a standalone test program + echo-cancel: Remove redundant variable + echo-cancel: Don't crash if adjust_time = 0 + echo-cancel: Increase threshold for resyncing, make it configurable + echo-cancel: Skip canceller when no source outputs are connected + echo-cancel: Skip processing till there's enough data + echo-cancel: Drop sink/source samples before processing begins + namereg: Don't set default sink/source on get() + echo-cancel: Close debug files on module unload + echo-cancel: Don't process if sink is unconnected + filter-apply: Move sink/source unlink callbacks before m-s-r + build-sys: Drop libsamplerate from pulsecommon deps + echo-cancel: Simplify checking if AEC is active + macro: typedef pa_bool_t to bool instead of _Bool + echo-cancel: Add the WebRTC echo canceller + build-sys: Minor CXXFLAGS fix + source: Bring rate update code in sync with sink code + sink,source: Add the ability to disable alternat sample rate switching + sink,source: Handle equal default and alternate sample rates + alsa: Remove unused variable + alsa: Probe sink/source sample rates + sink,source: Account for corked streams in update_rate() + native: Fix Solaris build + solaris: Use real_volume for set/get volume + gitignore: Update for recent additions + doc: Correct intended roles property documentation + core: Add a string list membership check function + echo-cancel: Plug in WebRTC drift compensation + echo-cancel: Adapt test code for drift compensation + doc: Fix some old 0pointer.de references + echo-cancel: Fix webrtc gain control initialisation + cli: Add a dump-volumes command + sink,source: Fix corked stream handling in update_rate() + sink-input,source-output: Add an update_rate() function + sink,source: Allow sample rate switching with corked streams + sink,source: Update sample rate if possible on stream uncork + echo-cancel: Add infrastructure for cancellers to do AGC + echo-cancel: Hook up WebRTC analog gain control + echo-cancel: Turn WebRTC analog gain control on by default + echo-cancel: Make WebRTC the default canceller + core: Make debugging a bit simpler + tests: Add playback tests to check-daemon + alsa: Minor debug code cleanup + core: Look up /etc/machine-id if D-Bus machine-id is not found + echo-cancel: Use speex by default if webrtc isn't available + echo-cancel: Use more human-friendly descriptions + filters: Fix the master source/sink when autoloaded + filters: Allow a filter to have both sink and source + proplist: Add internal API to get stream group + filters: Handle echo-cancel streams better + echo-cancel: Fix warning for undefined HAVE_WEBRTC + build-sys: Fix building without NLS + build-sys: Use absolute path for map-file while linking + mime: Move assert to correct position + iochannel: Handle missing un.h correctly + utils: Fixes for building without NLS + utils: Typo fixes in qpaeq + resampler: Remove invalid channel asserts in peak and trivial + resampler: Move some peak resampler asserts around + protocol-native: Fix 'auth-group-enabled' modarg + x11: Fix build without NLS support + build-sys: Fix map-file check + build-sys: Fix po/ build with --disable-nls + build-sys: Make esound bits optional + doc: Clarify pa_stream_get_latency() return value + daemon: Fix *-idle-time arguments + daemon: Drop --module-idle-time from docs + orc: Trivial documentation typo fix + orc: Another trivial documentation fix + alsa-mixer: Turn off the IEC958 element for analog outputs + stream: Clarify the sign of error return codes + alsa-mixer: Fix mixer path for AC3 profiles + format: Add "since 1.0" documentation tags where they were missing + loopback: Trivial whitespace fix + sink-input,source-output: Handle devices going away in unlink hooks + pacmd: Fix compiler warning + build: Fix out-of-tree build + format: Export pa_format_info int and string property getters + format: Don't assert on errors in getters + format: Expose pa_format_info<->pa_sample_spec conversion functions + format: Add more property getters + format: Update map-file + format: Trivial reorganisation + format: Add API to query a property's type + format: Allow format->sample spec conversion for compressed formats + build-sys: Bump soname + protocol-native: Reinstate assert that was incorrectly removed + protocol-native: Remove redundant asserts + stream: Fix sample spec initialisation for extended API + bluetooth: Fix crash due to usage of pa_bool_t instead of dbus_bool_t + build-sys: Bump soname + +Colin Guthrie (20): + libpulse: Always return a three part version number in API calls. + build-sys: Provide a simple CMake Config setup (similar to pkgconfig) + Update LICENSE. + conf: Use .nofail when loading module-jackdbus-detect + role-cork: Rename module-cork-music-on-phone to module-role-cork. + role-cork: Make module-role-cork more generic. + role-cork: Allow module-role-cork to act globally. + pulsecore: Fix issue with circuilar definitions. + x11: Drop unneeded 'struct' and use the typedef directly. + device-port: Remove redundant include after the better circular dep fix. + i18n: Fudge translations after previous commit to avoid mixing English/localized phrases. + i18n: Do not translate strings that cannot have any sensible translations. + i18n: Run make update-po + cli: Ensure source output volumes are printed via cli interface (pacmd ls) + bluetooth: Run update-sbc + core-util: Attempt to make runtime paths smaller to avoid 108 char limit. + Revert "resamplers: Optimize trivial resampler" + man: Document the cli inteface a little. + cli: Allow source-output volumes/mute to be set via CLI + alsa: Add the DTS/DCA mapping to extra-hdmi.conf too. + +Daniel Mack (2): + osx: don't build the once-test binary on OS X + osx: module_bonjour_publish needs to be linked against libprotocol-native.la + +David Henningsson (46): + module-jackdbus-detect: Avoid double-free of modargs + source-output: Do not use unset channel map in pa_source_output_new + Fix deferred volume not being applied if sink is closed + Introduce "available" concept for ports, and communicate that to clients. Bump protocol version to 24. + Turn device ports into reference counted objects + Cards now has ports directly, and device port has list of profiles + Notify port available status changes, and update protocol version + cli: Show card ports and jack detection status + alsa: Ignore the virtual "thinkpad-acpi" card + alsa: add card ports and path probe cache + Fixup a few things in the new path probing + pactl: Show port availability + device-port: Add a property list to ports. + alsa-mixer: When selecting an input, turn off boosts of other inputs + alsa-mixer: Refactor pa_alsa_profile_set_probe(). + alsa: Fix log message "synchronous volume" -> "deferred volume" + alsa-mixer: Allow speaker port to control "Front Speaker" + alsa: Improve "well known descriptions" for ports + alsa-mixer: Make sure unsupported paths are removed after probing + alsa-mixer: Take override-maps into account in subset elimination + sample-util: Fix "Darth Vader" panning bug + alsa-mixer: Don't use dangling pointers as port hashmap keys + PROTOCOL: Fix documentation for version 22 + tunnel: fixup create_record_stream + flist: Avoid the ABA problem + alsa: Jack detection kcontrol implementation + alsa: Add port information to HDMI profiles + Add a new module switch-on-port-available that acts on port changes + conf: Load switch-on-port-available module by default + introspect: Expose port info per card to clients + alsa-mixer: Make speaker get available=no when headphones are plugged in + alsa-mixer: Don't remove paths if jacks state.(un)plugged differ + daemon: Initialize dbus to use thread-safe mode by default + protocol-native: Protect against clients trying to set a NULL port + module-loopback: Never call adjust_rates after teardown + module-switch-on-port-available: Do not switch profile if current port is available + pactl: show availability information for "list cards" + build-sys: padsp target should not be phony + alsa-mixer: Show HDMI ports for older Nvidia cards + alsa-mixer: Fix a small issue when detecting required-any + Fix input device for M-audio fasttrack pro + sink-input/source-output: Prevent filter sink/source cycles + module-loopback: Reset process_msg callbacks in teardown + alsa-sink/source: Really set volumes on port change + alsa-sink/source: Make sure volumes are synchronised after fast user switching + sink/source.h: Clarify set_port comment + +Deng Zhenrong (1): + fix compilation warning via PRI prefix + +Dylan Reid (1): + alsa: Set return code before printing it. + +Frédéric Dalleau (9): + bluetooth: Fix Media Endpoint for HandsfreeGateway + bluetooth: Do not unload module-bluetooth-device on ERR or HUP + bluetooth: Release MediaEnpoint if card profile is set to Off + bluetooth: Set off profile on SCO disconnect + bluetooth: Set hfgw profile when HandsfreeGateway is playing + bluetooth: Use static string in DBUS signal handler description + bluetooth: Remove match for org.bluez.MediaTransport.PropertyChanged + loopback: Fix crash when moving sink-input fails + loopback: Fix crash on error during init + +Giorgos Boutsioukis (1): + xen: Add Xen paravirtualized sink support. + +Johan Hedberg (1): + bluetooth: sbc: Reduce for-loop induced indentation in sbc_unpack_frame + +Lars R. Damerow (3): + alsa: support fixed latency range in alsa modules + alsa: fixed latency range handling for udev-detect + alsa: fixed_latency_range modarg for module-alsa-card + +Lennart Poettering (1): + systemd: complement module-console-kit with module-systemd-login + +Luiz Augusto von Dentz (1): + bluetooth: Fix calling many times Audio.GetProperties for the same device + +Maarten Bosmans (32): + Make pulse build with clang again + doc: Add some more doxygen tags to existing comments + Do something sensible when compiled without iconv support + pacat: Fail early if the media name cannot be set + tests: Fix calculation of memblock size in resampler-test + qpaeq: Make it python3 and python2 compatible + tests: refactor ipacl-test + tests: Make sure tests assert on failures and return error status + tests: More useful output of make check + tests: Rename voltest to volume-test + tests: Revisit which tests to run with make check + tests: Add a target for running manual tests + rtpoll: Update comment + build-sys: Remove time-smoother and shm from libpulsecore + Remove vector.h and vector-test + Squash unused variable compiler warning + oss: Use log2 function from core-util instead of own implementation + Update LICENSE + pulsecore: Hardcode FRAME_SIZE_MAX_ALLOW + resamplers: Use fastpath assert in trivial resampler + build-sys: Disable fastpath asserts by default + resamplers: Use better variable name in trivial resampler + resamplers: Optimize trivial resampler + Use simple free function in pa_dynarray_free + Use simple free function in pa_queue_free + win32: Avoid some compiler warnings when cross-compiling for mingw32 + shm: Use a goto rather than early return for consistency. + resamplers: Rework the peaks resampler + resamplers: Improve performance of peaks resampler + tests: Don't link tests that only use public api to libpulsecommon + resampler: Some minor tweaks + Remove pa_prioq priority queue implementation + +Maarten Lankhorst (3): + loopback: Fix crashes + pulse: Fix old bug in stream_free + module-jack-sink/source: Set fixed latency correctly on creation + +Marc-André Lureau (1): + stream-restore: Support a simple fallback volume table + +Marcel Holtmann (1): + bluetooth: audio: Update license for shared header files + +Michael Biebl (2): + build: Move libpulsecommon into $pkglib + padsp: Move the padsp helper lib into a private library + +Mikel Astiz (1): + bluetooth: Fix property reply handling for hfgw + +Niels Ole Salscheider (1): + Add module-virtual-surround-sink. + +Paul Menzel (3): + svolume_{mmx, sse}, sconv_sse: Fix compilation errors with X32 toolchain + doc: Add entry for correct spelling + Correct spelling of PulseAudio + +Peter Meerwald (45): + echo-cancel: Fix memory leak in test program + pstream: Fix spelling of 'receive'. + stream: Fix comments + def: Document that pa_buffer_attr.maxlength is in bytes. + format: Fix unknown doxygen command \second + format: Add periods to fix brief documentation for pa_format_info_is_pcm() + format: Add description for format.h + introspect: Fix unresolved doxygen link pa_port_available_t + proplist: Add doxygen file description for proplist.h + proplist: Fix typos in doxygen documentation + utf8: Fix doxygen file description for utf8.h + proplist: Consistently use parameter name p for a pa_proplist* in prototype + error: Fix spelling of 'initialization' in errortab for PA_ERR_MODINITFAILED + stream: Fix 'e g' as 'e.g.\ ' + simple: Fix typos in simple.h doxygen documentation + mainloop: Fix typos and rewording of thread-mainloop.h doxygen documentation + stream: Fix typos and formatting in stream.h doxygen documentation + build-sys: Make speex library optional + echo-cance: Make Adrian canceller optional + echo-cancel: Set file mode to binary in test code + echo-cancel: Begin log message with uppercase letter + echo-cancel: Better handling of error conditions in test + tests: Fix resampler-test compilation without NLS support + core: fix potential memory leak + core: sample_spec.rate is in Hz, not kHz; change logging output + core: fix typo in logging + core: comment typo + alsa: Mention correct ALSA function in debug log + core: Fix return of pa_cpu_init_arm() + core: Fix log message about ARM feature detection + sconv: Fix generation of floats in SSE test code + pulse: Turn the anonymous error code enum into pa_error_code_t. + pulse: Document general error handling. + manpage: document --log-target=file:PATH + manpage: document --log-meta, --log-time, log-backtrace + fix the ever-popular 'the the' typo + alsa: fix comment + core: whitespace typo + core: svolume tests should generate realistic random volume data + dbus: Fix dbus argument type in iface-stream.c handle_move(). + build: Fix spelling in src/Makefile.am. + echo-cancel: Upper/lowercase in comment. + core: Fix comments. + pulse: Clarify proplist doxygen documentation. + pulse: Fix warning in introspect.h; minor rewording and punctuation. + +Pierre-Louis Bossart (5): + alsa: reset watermark to initial values on resume + core: infrastructure for alternate sampling rate + sink,source: support for rate update + alsa: support for alternate sampling rate + alsa: fix list of sampling rates + +Pino Toscano (6): + pipe: use pa_pipe_buf instead of the macro PIPE_BUF + rtp: use the right type when checking cmsg_type + module-rtp-recv: fail when SO_TIMESTAMP is not defined + mutex: handle gracefully if a PTHREAD_PRIO_INHERIT protocol cannot be set + pacmd: dynamically allocate ibuf and obuf + libpulse: Cope with systems not implementing SA_NOCLDWAIT + +Piotr Drąg (1): + i18n: Update Polish translation + +Siarhei Siamashka (1): + bluetooth: sbc: overflow bugfix and audio decoding quality improvement + +Sjoerd Simons (2): + build: Force order of library installation + .gitignore: Add padsp to gitignore + +Sudarshan Bisht (1): + null-sink: Set latency range at the time of initialization of module. + +Tanu Kaskinen (43): + sink: Move updating the requested latency after the rewind request when finishing a stream move. + sink: Add some comments about the rewind handling during stream moves. + memblockq: Improve debuggability by storing a name and a sample spec. + doc: Add an example stream-restore fallback table file. + daemon: Don't treat it as a fatal error if we can't connect to the session bus + alsa: New modarg "paths_dir" for module-alsa-card + alsa: Handle the "profile" modarg in module-alsa-card + sink, source: Join two ifs with the same condition. + device-port: Fix the circular dependency problem more cleanly. + alsa-mixer: Remove unused pa_alsa_path_set_probe() declaration. + dbus: New helper function: pa_dbus_get_error_message(). + bluetooth: When receiving D-Bus errors, print also the error message. + dbus: Give NULL as the error parameter to dbus_bus_remove_match(). + bluetooth: Remove the right match in the proximity module. + bluetooth: Change function name add_matches to update_matches. + stream-restore: Clean up the database at startup. + stream-restore: Don't verify entry validity needlessly. + virtual-sink: Remove irrelevant comment. + man: Document the local-server-type daemon.conf option. + dbus: Use correct free function. + flist: Make name non-const to avoid casting with pa_xfree(). + proplist: Constify the pa_proplist_copy and _update input pointers. + proplist: Match pa_proplist_copy argument name between header and implementation. + build-sys: Remove the public API stuff from libpulsecommon. + i18n: Fix POTFILES. + Revert "build-sys: Remove the public API stuff from libpulsecommon." + bluetooth: Remove unused variable. + dbus: Check method call signatures. + dbus: Fix device latency querying. + padsp: Fix a double-free bug. + sample-util: Remove redundant check from pa_volume_memchunk. + device-manager: Fix a memory leak. + alsa: Fix SND_MIXER_SCHN_LAST related stuff. + dbus: Add an assertion to get rid of a warning from Coverity. + device-manager: Add an assertion to get rid of a warning from Coverity. + dbus: Add assertions to get rid of warnings from Coverity. + echo-cancel: Drop the correct amount of samples when skipping. + echo-cancel: Fix memblockq length check. + echo-cancel: Clarify function call contexts. + resampler: Use pa_xnew0() to avoid manual zeroing. + resampler: Use more descriptive buffer names. + resampler: Add support for resamplers that consume less data than asked. + alsa: Add support for sound cards with 4-channel input. + +Yuri Chornoivan (1): + Update Ukrainian translation. + +poljar (1): + pacmd: Added --help and --version options. +"""]]
\ No newline at end of file diff --git a/Software/PulseAudio/Notes/2.1.mdwn b/Software/PulseAudio/Notes/2.1.mdwn new file mode 100644 index 00000000..588797a8 --- /dev/null +++ b/Software/PulseAudio/Notes/2.1.mdwn @@ -0,0 +1,7 @@ + +[[!inline pages="Software/PulseAudio/TOC" quick="yes" raw="yes"]] + + +# Release Notes + +This is a bugfix release from the 2.0 branch. diff --git a/Software/PulseAudio/Notes/3.0.mdwn b/Software/PulseAudio/Notes/3.0.mdwn new file mode 100644 index 00000000..2a1b973f --- /dev/null +++ b/Software/PulseAudio/Notes/3.0.mdwn @@ -0,0 +1,532 @@ + +[[!inline pages="Software/PulseAudio/TOC" quick="yes" raw="yes"]] + + +# PulseAudio 3.0 Release Notes + +We're, back with another shiny PulseAudio release! While the 3.0 release was a little delayed, it brings a number of important improvements, and bug fixes. A summary of changes follows. + + +## Notable Changes + +* ALSA Use Case Manager (UCM) support +* Runtime editable LADSPA filter parameters +* Out-of-the-box support for Bluetooth sources +* ARM NEON optimisations +* Configurable device latency offset +* Adhere to the XDG Base Directory Specification +* Various ALSA changes +* Lots of infrastructure improvements + +## Packaging + +* Bluetooth support requires now "sbc", a library for the SBC codec. The codec used to be included within PulseAudio, but it has now been split off into a separate library. It's available at [[http://www.bluez.org|http://www.bluez.org]]. +* Support for the "socket API" of BlueZ has been dropped in favour of the D-Bus based "media API". Due to this change, the minimum supported version of BlueZ is now 4.99. Also, make sure that you don't have "Disable=Media" in /etc/bluetooth/audio.conf. And due to a bug in BlueZ, it's probably necessary to have "Disable=Socket", otherwise there will be problems with the A2DP profile. +* Support for HAL has been removed. This shouldn't affect anyone, but if it does, please configure PulseAudio to use udev instead. module-hal-detect still exists for maintaining configuration file compatibility, but all it does is to load module-udev-detect. module-hal-detect may get completely removed in 4.0. + +## Changes in More Detail + + +### ALSA Use Case Manager (UCM) Support + +The audio hardware on desktop and laptop computers is usually standard enough for PulseAudio to handle using a common set of configuration files. The situation is different on e.g. phones and tablets. Practically all of those devices need separate configuration files for describing the hardware so that PulseAudio can properly use all basic features of the hardware. The configuration could be shipped as PulseAudio configuration files, but the ALSA folks have been working on a system that allows applications (such as PulseAudio) to use the hardware without needing any extra configuration in the application. The system is called UCM, and PulseAudio now has support for it. + + +### Runtime Editable LADSPA Filter Parameters + +The LADSPA module now exposes a basic D-Bus interface for changing the filter parameters on the fly. Previously the parameters could not be changed after loading the filter. + + +### Out-of-the-box support for Bluetooth sources + +PulseAudio can be used in a Bluetooth headset role, for example to connect a laptop to a mobile phone and pretend that the laptop is a headset. It's often desirable in that case to loop back the audio from the phone to the laptop's sound card. That is now done automatically by module-bluetooth-policy, which is loaded by default. Users do need to enable Source support in their BlueZ configuration, though. + + +### ARM NEON optimisations + +Optimisations were added for sample format conversion between S16LE and floating point formats using the ARM NEON instructions. Support for these is detected at compile-time (based on FPU flags) as well as run-time (based on /proc/cpuinfo). As part of this effort, the groundwork has been laid for adding more NEON optimisations in the future. + + +### Configurable Device Latency Offset + +Accurate latency reporting is important for e.g. "lip sync" in video playback. PulseAudio relies on the audio hardware to provide accurate information about the audio delay. If that information is not accurate for some reason, it is now possible to configure an offset to be applied to each latency report, thanks to Damir Jelić's Google Summer of Code work. For example, if you're watching a video and you use a Bluetooth headset for audio output, the lip sync might be a bit off, because PulseAudio doesn't currently have proper support for querying the latency for Bluetooth devices. With the upcoming version of pavucontrol, you will be able to fix the synchronization problem by adjusting the latency offset of the Bluetooth headset. + + +### Adhere to the XDG Base Directory Specification + +The location of configuration files has been moved from ~/.pulse to ~/.config/pulse (or if $XDG_CONFIG_HOME is set, then use that). If ~/.pulse exists, however, it will still be used so that the user configuration is not lost when updating PulseAudio. The authentication cookie has also been moved from ~/.pulse-cookie to ~/.config/pulse/cookie. + +The location of runtime files (i.e. files that don't need to be kept across reboots, e.g. sockets) has been moved from a random directory under /tmp to $XDG_RUNTIME_DIR/pulse. In case $XDG_RUNTIME_DIR is not set, the old scheme is still used as a fallback. + + +### Various ALSA Changes + +A regression in 2.0, that could cause some machines not to have "Speaker" or "Internal Mic" ports, has been mostly fixed in 3.0 - when used together with Linux 3.6 or higher. Also, a workaround for older kernels is applied to certain most common machines. + +Pierre-Louis Bossart introduced a change to improve accuracy of timestamp queries, and thus timer-based scheduling, by querying a number of ALSA timing parameters atomically. + +We have added icon name property to ALSA ports, which could help UI makers to display better per-port icons. + +Also, there has been a few other changes, such as removing the troublesome lfe-on-mono port, and adding more mixer control names to better stay in sync with the kernel. + + +### Improvements for Automatic Testing + +Deng Zhengrong improved PulseAudio's automatic testing support as part of his Google Summer of Code work. The improvements include support for test coverage reporting with gcov, changing the existing tests to use the "check" framework, and making it possible to launch a PulseAudio daemon for testing purposes while simultaneously having the normal daemon running. + + +### Unloading Modules by Name + +pactl and pacmd now support unloading modules by name. Previously unloading could only be done by the module index, which was a bit inconvenient, because usually you don't know the index without somehow looking it up first. + + +### Logging Improvements + +In addition to the automatic testing improvements, GSoC student Deng worked also on PulseAudio's logging facilities. It's now possible to change the log target of a running daemon with pacmd, using the set-log-target command. Also, a new log target type was added: "newfile". The "newfile" target is like the old "file" target, with the difference that if the given file name already exists, the file is not overwritten, but instead a new file is created with a numbered suffix. + + +### Bluetooth Code Refactoring + +There has been a lot of refactoring work done on the Bluetooth modules, as preparation for the upcoming BlueZ 5 support and for making the code more pleasant to work with in general. These are not directly user-visible changes, but we'd like to take the opportunity here to thank Mikel Astiz anyway for the great work he has done. + + +## Next Steps + +The development continues as always, and the 4.0 release is targeted to happen in April (so far we haven't been very good at maintaining a 4 month release cycle, though, so take that with a grain of salt). The [[report from PulseConf 2012|http://arunraghavan.net/2012/11/pulseconf-2012-report/]] offers some clues about what might be coming next. + + +## git shortlog + + +[[!format txt """ +Andika Triwidada (1): + i18n: Add Indonesian translation. + +Arti Trivedi Bora (4): + modules: Use pa_streq instead of strcmp. + pulsecore: Use pa_streq instead of strcmp. + tests: use pa_streq instead of strcmp + daemon: use pa_streq instead of strcmp + +Arun Raghavan (68): + sink-input,source-output: Avoid unneccessary rate updates + role-cork: Fix a minor leak + core-util: Add a pa_split_in_place() string utility function + core-util: Make pa_make_secure_dir() act like mkdir -p + auth: Create cookie directory if it doesn't exist + pactl: Print sink-input/source-output corked status + glib: Stop using g_source_get_current_time() + core-util: Fix permissions handling while creating directories + Revert "role-cork: Fix a minor leak" + role-cork: Fix incorrect check at deinitialisation time + Revert "Revert "role-cork: Fix a minor leak"" + role-cork: Fix another minor leak + alsa: Allow channel count probe on open by mapping + alsa: Add a proplist to mappings + alsa: Add separate sinks/sources for UCM modifiers if needed + i18n: Remove module-hal-detect reference in POTFILES + echo-cancel: Print what AEC engine is being used + build: Avoid libstdc++ dep for module-echo-cancel if possible + i18n: module-coreaudio-device now has some translatable strings + build: Fix distcheck failure on libwebrtc-util + tests: Factor out Orc test code into cpu-test + tests: Make cpu-test less verbose + build: Merge bluez pkg-config checks into one + Revert "build: Merge bluez pkg-config checks into one" + stream: Allow record streams to start muted + core: Separate ARM CPU detection from initialisation + tests: Factor out ARM svolume test into cpu-test + tests: Minor cpu-test reorganisation + core: Document ARM-optimised svolume code a bit + core: Fix a litte-endian bug in ARM svolume code + tests: Add a copyright header to cpu-test + tests: Factor out core sconv test code in cpu-test + tests: Reorganise cpu-test to reuse code + tests: Add a basic sanity test to sconv cpu-test + tests: Run sconv tests with multiple alignments + build-sys: Add volume code to libpulsecommon + sconv: Fix NEON sconv rounding code + tests: Allow off-by-one error in sconv test + tests: Increase sconv cpu-test timeout + tests: Print average outer-loop iteration time in cpu-test + tests: Minor cpu-test fixes for non-NEON builds + core: Fix warning on non-win32 builds + tests: Run svolume test for various sample alignments + tests: Make cpu-test less verbose + tests: Run svolume on different channel counts + tests: Fix a cpu-test debug message + build-sys: Drop -Wvla from compiler flags + tests: Minor alignment adjustment fix for cpu-test + svolume: Fix ARM alignment issues + Revert "core: adjust playing_for and underrun_for at rewind" + build-sys: Bump soname + i18n: Fix POTFILES for poll changes + build-sys: Document libpulsecommon vs. libpulse duplication + alsa: Drop verbosity on UCM message + Revert "tests: modify alsa-time-test to use 'check' framework" + introspect: Minor documentation fix + man: Correction for how sample rate switching is disabled + sink, source: Prevent unnecessary rate update attempts + modules: Micro-optimisation for rewind_requested paths + build-sys: Bump BlueZ dependency to 4.99 + build-sys: Bump soname + build-sys: Drop ChangeLog generation + source-output: Fix volume fixup for rate update + sink-input, source-output: Check rate update success for passthrough + core: Remove bad free() call + alsa: Try to support non-standard rates in alsa-sink/source + build-sys: Bump soname + build-sys: Bump soname + +Chan-yeol Park (1): + bluetooth: Remove ipc.[ch] files in the bluetooth module + +Colin Walters (1): + git-version-gen: Honor GIT_DESCRIBE_FOR_BUILD environment variable + +David Henningsson (22): + once: Fix race causing pa_once to sometimes run twice + alsa-mixer: Add special profiles for some laptops missing speaker and/or internal mic + alsa-mixer: Add Phantom Jack support + alsa-mixer: Always turn "Inverted Internal Mic" off + alsa-mixer: Add "Front Headphone" jack + alsa-mixer: Document "state.plugged" and "state.unplugged" + alsa-mixer: Add "Front Headphone Jack" (fixup) + alsa-mixer: Add "Headphone Mic" support for 3-pin ASUS netbooks + resampler: Fix volume on downmix to mono + alsa-mixer: Add "iec958-stereo-input" to well known path names + flist: Increase default list size to 256 + alsa-mixer: Cache failure to open inputs/output mappings + alsa-mixer: Remove analog-output-lfe-on-mono + cli: Output asterisk when default sink/source is found + alsa-sink/source: Warn for scheduling delays + alsa-mixer: Don't let "Mic Jack Mode" alone create a "Line In" path + alsa-mixer: Add a few more machines to internal mic whitelist + alsa-mixer: Add "CLFE" and "Bass Speaker" names + alsa-mixer: Prefer "Digital Input Source:Digital Mic 1" + alsa udev quirks: Add some more Dell devices to speaker whitelist + alsa-mixer: Add Dell Inspiron One 2020 to mic whitelist + alsa-mixer: Add device.icon-name property for some common ports + +Deng Zhengrong (48): + cli: Add set-log-target command for pacmd + daemon: use pa_streq instead of plain strcmp + x11: fix the wrong parameter sequence in pax11publish + build: Add gcov coverage support + pacmd: add help info for 'set-log-target' + xen: add the HAVE_CONFIG_H macro guard + add a new log target that enables to create new log file if it exists + bluetooth: add a parenthesis around pa_streq() + man: document option `set-log-target` + core: add more verbose error info + build-sys: add `check` test framework + tests: modify mix-test to use new 'check' test framework + tests: add cpu test + tests: modify mainloop-test to use new 'check' framework + tests: modify utf8-test to use new 'check' test framework + tests: modify strlist-test to use new 'check' framework + build: add a target to ease the creation of coverage files + tests: enable to test standalone pulseaudio daemon + tests: modify volume_test to use new 'check' framework + tests: modify usergroup-test to use 'check' test framework + tests: modify format-test to use 'check' framework + tests: modify get-binary-name-test to use 'check' framework + tests: modify thread-test to use 'check' framework + tests: modify thread-mainloop-test to use 'check' framework + tests: modify alsa-time-test to use 'check' framework + tests: modify asyncmsgq-test to new 'check' framework + tests: modify asyncq-test to use 'check' framework + tests: modify channelmap-tets to use 'check' framework + tests: modify cpulimit-test to use 'check' framework + tests: modify queue-test to use 'check' framework + tests: modify connect-stress to use 'check' framework + tests: modify memblock-test to use 'check' framework + tests: modify proplist-test to use 'check' framework + tests: modify memblockq-test to use 'check' framework + tests: modify hook-list-test to use 'check' framework + tests: modify extended-test to use 'check' framework + tests: modify sync-playback to use 'check' framework + tests: modify smoother-test to use 'check' framework + tests: modify interpol-test to use 'check' framework + tests: modify sigbus-test to use 'check' framework + tests: modify sig2str-test to use 'check' framework + tests: modify rtpoll-test to use 'check' framework + tests: modify lock-autospawn-test to use 'check' framework + tests: modify once-test to use 'check' framework + tests: modify ipacl-test to use 'check' framework + tests: fix the wrong library path in check-daemon + tests: make 'check' optional + build: fix Mac OS X configure process + +Eero Nurkkala (2): + alsa-sink: add missing header 'signal.h' + alsa-source: add missing header 'signal.h' + +Feng Wei (3): + alsa: Integrate UCM basic functions + alsa: Add UCM jack detection + alsa: Catch role matched streams to enable/disable modifier + +Flavio Ceolin (4): + sink-input: Remove redundant check in pa_sink_input_request_rewind(). + modargs: New function: pa_modargs_get_value_double(). + pulse: Fix for volume documentation + utils: Adding a function to get volume from string + +Frédéric Dalleau (6): + loopback: Enable routing on loopback streams + bluetooth: module-bluetooth-policy initial commit + pacmd: Display inputs and outputs PASSTHROUGH flag + loopback: Cork sink-input if source is suspended + loopback: Cork source-output if sink is suspended + resampler: Fix crash if 'auto' resampler chooses ffmpeg with variable rate + +Frédéric Danis (2): + bluetooth: Fix crash on disconnection + bluetooth: Fix bluetooth.nrec property not updated + +Harsh Prateek Bora (2): + modules: Use PA_IDXSET_FOREACH wherever applicable. + pulsecore: Use PA_IDXSET_FOREACH wherever applicable. + +Ismo Puustinen (2): + ladspa: D-Bus interface for setting algorithm parameters on-the-fly. + ladspa: Added a python script for testing. + +Jan Alexander Steffens (heftig) (1): + alsa-mixer: Actually install analog-input-headphone-mic.conf + +Jarkko Nikula (2): + alsa: move pa_alsa_setting_select close to pa_alsa_path_select + alsa: Merge pa_alsa_setting_select with pa_alsa_path_select + +Jarkko Suontausta (1): + bluetooth: Release transport when the pa_rtpoll_run loop finishes. + +Juho Hämäläinen (1): + stream-restore: Add missing method handler argument. + +Lennart Poettering (14): + util: XDG_SESSION_COOKIE is unsuitable as session ID + proplist: document new meaning of the session ID + util: /etc/machine-id should be tried first, the D-Bus only as fallback for legacy systems + util: use the return value of gethosid() as fallback, not the address of the function + build-sys: readd stub makefiles to subdirectories to make building with emacs easier + build-sys: remove HAL support, it's obsolete since years + rtkit: update drop-in files + context: get rid of really old runtime dir logic, i.e. break compat with >4y-old PA + util: hook up pa_get_runtime_dir() with XDG_RUNTIME_DIR + core-util: move configuration home directory from ~/,pulse to ~/.config/pulse to follow XDG basedir spec + man: update man pages to only refer to the new place for the configuration files + core-util: when searching for configuration files, honour XDG basedir spec + auth: move cookie file to ~/.config/pulse/cookie + gnome: start PA early in the gnome session + +Luiz Augusto von Dentz (2): + bluetooth: Remove built-in/static SBC codec + bluetooth: Don't force any profile on discovery module + +Marc-Antoine Perennou (1): + udev: Don't use deprecated udev_get_*_path() functions + +Martin-Éric Racine (1): + manpage, finnish translation: fix spelling errors + +Matthijs Kooijman (1): + equalizer: Don't cleanup u->sink in sink_input_kill_cb yet + +Mihai Moldovan (1): + core-util: use the generic PATH_MAX variant of pa_realpath on Mac OS X + +Mikel Astiz (67): + bluetooth: Don't use the old socket IPC mechanism with BlueZ + bluetooth: Refactor property parsing code + bluetooth: Remove library for IPC to BlueZ + bluetooth: Minor style fixes + bluetooth: Consider different input and output MTU + bluetooth: Avoid duplicating profile argument twice + bluetooth: Replace deprecated ListAdapters() + bluetooth: Replace deprecated ListDevices() + bluetooth: Remove minor unnecessary check + bluetooth: Minor style fix + bluetooth: Fix missing state checks for a2dp_source + bluetooth: Fix bluetooth.protocol property + bluetooth: Trivial style fix + bluetooth: Generalize module-bluetooth-policy + bluetooth: Support HFGW in module-bluetooth-policy + loopback: Disable adjust timer when suspended + bluetooth: Remove return value of bt_transport_config() + bluetooth: Remove return value of setup_stream() + bluetooth: Refactor parsing of signal PropertyChanged + bluetooth: Refactor code to helper function + bluetooth: Fix wrongly set "phone" role for HFGW + bluetooth: Fix using garbage memory + bluetooth: Fix check if transport exists before acquire + sink, source: Support creating suspended sinks and sources + bluetooth: Provide dummy set_port callbacks + bluetooth: Config MTU transport after acquire + bluetooth: Support port availability flag + bluetooth: Set profile even if transport not acquired + bluetooth: Do not acquire transport during profile change + bluetooth: Acquire transport when becomes available + bluetooth: Release transport when not available + bluetooth: Do not switch to HFGW automatically + bluetooth: Let suspend-on-idle request audio in headset + bluetooth: Add port availability transition policies + bluetooth: Ignore Device.DisconnectRequested + bluetooth: Trivial function rename + bluetooth: Fix potential assertion failure + bluetooth: Don't find device if set profile is off + bluetooth: Release transport in stop_thread() + bluetooth: Unlink sink-sources in stop_thread() + bluetooth: Remove stream moving code + bluetooth: Use assertions when setting off profile + bluetooth: Check return value of init_profile() + bluetooth: Check return value of start_thread() + bluetooth: Remove const qualifier for transports + bluetooth: Add hook to tell transport was removed + bluetooth: Set to off if transport removed + bluetooth: Set to off instead of failing module load + bluetooth: Hold transport pointer while profile set + bluetooth: Remove const qualifier for device + bluetooth: Add hook to tell device was removed + bluetooth: Self unload module-bluetooth-device + bluetooth: Hold device pointer while module loaded + bluetooth: Refactor code to create card profiles + bluetooth: Refactor code to create profile ports + card: Support adding profiles dynamically + card: Support adding ports dynamically + bluetooth: Add hook to announce late UUIDs + bluetooth: Rename former device_is_audio() + bluetooth: Run the discovery hook only when necessary + bluetooth: Merge headset ports into one + bluetooth: Disable profile auto-switch policy for headsets + conf: Load bluetooth-policy module by default + bluetooth: Trivially refactor to call setup_stream() directly + bluetooth: Do not setup stream before thread starts + bluetooth: Request headset audio during profile switch + bluetooth: Fix unacquired transports during sink resume + +Niels Ole Salscheider (3): + virtual-surround: Add silence to hrir if necessary. + virtual-surround: Limit the number of hrir samples. + virtual-surround: check if resampled memblock is not equal to input + +Paul Menzel (1): + Fix spelling of separated: s, sepera, separa, g + +Peter Meerwald (13): + pipe: whitespace and log output cleanup + pipe: check return value of mkfifo() + memblock: Fix typos. + build: Fix static linking + core: Set volumes const in pa_do_volume_func_t + modules: Add null/dummy echo canceller + daemon: Fix redundant redeclaration warning + svolume_arm: Fix a const warning. + echo-cancel: Fix false warning in webrtc AEC. + rtp: Fix warning using pa_assert_not_reached() + core: Add ARM NEON optimized sample conversion code + tests: Fix test description in cpu-test + tests: Implement test code for ARM NEON sconv s16_to_float + +Pierre-Louis Bossart (1): + alsa: get avail, delay, timestamps in a single kernel call + +Sjoerd Simons (2): + build-sys: webrtc-utils needs to be installed before module-echo-cancel + build-sys: Correct bluez support error if sbc is missing + +Sjors Gielen (1): + osx: Add a single "On" profile to coreaudio devices. Fixes crash on OS X. + +Tanu Kaskinen (51): + device-port: Create the profiles hashmap at initialization. + device-port: Remove an out-of-date comment. + native: Don't save device, volume or mute of new streams. + sink, source: Fix setting the latency offset when the sink/source is unlinked. + Fix a copy-paste error in PROTOCOL. + pulse: Use more intuitive indexing with port infos in introspect.c. + proplist: Change proplist_name_valid() to be public function pa_proplist_key_valid(). + tagstruct: Allow NULL proplist with pa_tagstruct_get_proplist(). + conf-parser: Pass parser state in a struct instead of function parameters. + conf-parser: Pass parser state in a struct also for parse callbacks. + conf-parser: Add support for parsing property lists. + alsa-mixer: Add support for defining port property lists in the path configuration files. + native: Send the actual port proplists with card info. + pactl: Print card port properties with the "list" command. + card: Don't crash if someone gives NULL name to pa_card_set_profile(). + sink, source: Always create a hashmap for ports. + card: Ensure that there's always at least one profile. + Assume that the profiles hashmap of ports is always non-NULL. + Assume that the ports hashmap of cards is always non-NULL. + card-restore: Handle reading NULL profile name from the database. + alsa-mixer: Implement a new path option: "mute-during-activation". + build-sys: Link utf8-test to libpulsecommon. + Add comments referring to bug #53709. + memblock: Add pa_memblock_acquire_chunk(). + object: Get rid of "warning: cast increases required alignment of target type" + sink-input: Fix comment: s/push/peek/ + sink-input: Add a comment in pa_sink_input_request_rewind(). + sink: Remove an incorrect FIXME comment. + bluetooth: Remove commented out code. + .gitignore: Add cpu-test. + rtp: Fix rtp_port reading. + card: Store a pa_card pointer in pa_card_profile. + build: Add a2dp-codecs.h to libbluetooth-util sources. + memblockq: Fix the order of setting minreq and prebuf. + resampler: Make sure that there are no overflows when multiplying potentially big numbers. + loopback: Use the real sample spec once it's known. + loopback: Don't fix the source output format/rate/channels. + virtual-surround-sink: Fix setting max_request and max_rewind. + combine: Keep the timer active in the null mode only when running. + match: Use the SINK_INPUT_FIXATE hook instead of NEW. + build: Add .gitignore files to EXTRA_DIST. + device-restore: When restoring volume, print the restored volume to the log. + build: Add PROTOCOL to EXTRA_DIST. + pulse: Fix hole handling in pa_stream_peek(). + mainloop: Change wakeup_requested type from pa_bool_t to pa_atomic_t. + mainloop: Don't care about the mainloop state variable when waking up the mainloop. + sink: Process rewind requests also when suspended. + bluetooth: Add a pa_bluetooth_discovery pointer to pa_bluetooth_device. + bluetooth: Ignore Device.Connected + bluetooth: Add helper pa_bluetooth_device_any_audio_connected() + bluetooth: Unload device module when no audio profiles connected + +Thomas Martitz (7): + pacat: Enable binary mode on Windows. + core: Transparently handle non-blocking sockets on Windows + pacat: Replace read(), write() with pa_* equivalent. + core: Slightly more helpful pa_cstrerror for unknown errors + gccmacro: Disable printf-like format checking on mingw32 compilers. + core: Proper poll() emulation to fix pacat and friends on Windows + core-util: Don't error out on existing runtime directory. + +Uoti Urpala (2): + sink-input: Fix underrun_for calculation when resampling. + core: adjust playing_for and underrun_for at rewind + +Wieland Hoffmann (1): + man pulse-daemon.conf: Correct typoes + +poljar (8): + pacmd: Added --help and --version descriptions to the man page. + native: Use foreach to iterate trough modules. + pactl: Add unloading modules by name. + pacmd: Add unloading modules by name. + bluetooth: Add ports to the bluetooth sink/source + device-port: Add a latency variable to the port struct + sink, source: Add a latency offset which is inherited from the port + pacmd: Add functions to handle the latency offset + +poljar (Damir Jelic) (2): + introspect: Add functions to handle the latency offset. + pactl: Add set-latency-offset command. + +poljar (Damir Jelić) (5): + device-port: Change the latency offset type to a signed int. + conf-parser: Initialize the state to zero immediately. + device-port: Send a subscription event when the offset changes. + man: Add latency offset documentation to the cli syntax. + card-restore: Add the ability to save and restore the latency offset. +"""]]
\ No newline at end of file diff --git a/Software/PulseAudio/Notes/4.0.mdwn b/Software/PulseAudio/Notes/4.0.mdwn new file mode 100644 index 00000000..9ef95976 --- /dev/null +++ b/Software/PulseAudio/Notes/4.0.mdwn @@ -0,0 +1,42 @@ + +[[!inline pages="Software/PulseAudio/TOC" quick="yes" raw="yes"]] + + +# PulseAudio 4.0 Release Notes + +TODO: Short introduction. + + +## Notes for Application Developers + +So far card profiles have been static, that is, the set of profiles on a card has never changed after the creation of the card object. While that has never been promised in the API documentation, it may be that some applications have the assumption that the profiles are static. Due to the nature of the Bluetooth protocol, it has turned out to be necessary to be able to add profiles to a card after it has been created. So, make sure your application doesn't crash or otherwise behave badly if new profiles suddenly appear on a card. It's best to prepare for profiles disappearing too. + +Have you ever wanted to get a callback from pa_operation when it's cancelled (perhaps due to disconnection)? That's now possible with this new function: pa_operation_set_state_callback(). + + +## Notes for Packagers + +D-Bus dependency version has been bumped to 1.4.12. + +pa_format_info_free2 symbol has been dropped from libpulse. The pa_format_info_free2 symbol was never part of the public API, but was still exported in the ABI in the previous version of [[PulseAudio|PulseAudio]]. It is now completely dropped. Since it was never exposed in any header files, the only programs affected should be test tools specifically looking for missing symbols. + + +## Changes in More Detail + + +### New Module: module-role-ducking + +module-role-ducking lowers the volume of less important streams when a more important stream appears, and raises the volume back up once the important stream has finished (this is called "ducking"). The decision whether a stream has high or low priority is made based on the stream role (the media.role property). By default, "music" and "video" streams are ducked, and "phone" streams trigger the ducking. This module is not loaded by default. + + +## Next Steps + +TODO + + +## git shortlog + + +[[!format txt """ +TODO +"""]]
\ No newline at end of file diff --git a/Software/PulseAudio/OldNews.mdwn b/Software/PulseAudio/OldNews.mdwn new file mode 100644 index 00000000..6e8d388c --- /dev/null +++ b/Software/PulseAudio/OldNews.mdwn @@ -0,0 +1,161 @@ + +[[!inline pages="Software/PulseAudio/TOC" quick="yes" raw="yes"]] + + +# Old PulseAudio News + + +### April 2009 + +* **2009-04-13:** [[PulseAudio 0.9.15|http://freedesktop.org/software/pulseaudio/releases/pulseaudio-0.9.15.tar.gz]] has been released. ([[Changes|http://pulseaudio.org/milestone/0.9.15]]) + +### January 2009 + +* **2009-01-13:** [[PulseAudio 0.9.14|http://freedesktop.org/software/pulseaudio/releases/pulseaudio-0.9.14.tar.gz]] has been released. ([[Changes|http://pulseaudio.org/milestone/0.9.14]]) + +### October 2008 + +* **2008-10-06:** [[PulseAudio 0.9.13|http://freedesktop.org/software/pulseaudio/releases/pulseaudio-0.9.13.tar.gz]] has been released. ([[Changes|http://pulseaudio.org/milestone/0.9.13]]) + +### September 2008 + +* **2008-09-24:** Lennart Poettering published a [[Guide Through The Linux Sound API Jungle|http://0pointer.de/blog/projects/guide-to-sound-apis.html]] +* **2008-09-09:** [[PulseAudio 0.9.12|http://freedesktop.org/software/pulseaudio/releases/pulseaudio-0.9.12.tar.gz]] has been released. ([[Changes|http://pulseaudio.org/milestone/0.9.12]]) + +### July 2008 + +* **2008-07-24:** [[PulseAudio 0.9.11|http://freedesktop.org/software/pulseaudio/releases/pulseaudio-0.9.11.tar.gz]] has been released. ([[Changes|http://pulseaudio.org/milestone/0.9.11]]) + +### April 2008 + +* **2008-04-08:** Lennart Poettering goes [[into detail|http://0pointer.de/blog/projects/pulse-glitch-free.html]] what's up next with PulseAudio's new glitch-free playback model. + +### March 2008 + +* **2008-03-30:** [[PulseAudio 0.9.10|http://freedesktop.org/software/pulseaudio/releases/pulseaudio-0.9.10.tar.gz]] has been released. This is an important bugfix release. ([[Changes|http://pulseaudio.org/milestone/0.9.10]]) + +### January 2008 + +* **2008-01-24:** [[PulseAudio 0.9.9|http://freedesktop.org/software/pulseaudio/releases/pulseaudio-0.9.9.tar.gz]] has been released. The only change from 0.9.8 is a fix for CVE-2008-0008. An upgrade is **highly recommended**. (People using -NDEBUG should also check [[out this email|https://tango.0pointer.de/pipermail/pulseaudio-discuss/2008-January/001228.html]].) + +### November 2007 + +* **2007-11-20:** [[PulseAudio 0.9.8|http://freedesktop.org/software/pulseaudio/releases/pulseaudio-0.9.8.tar.gz]] has been released. This is a major feature enhancement release ([[Changes|http://pulseaudio.org/milestone/0.9.8]]) +* **2007-11-02:** [[Linux.com on PulseAudio|http://www.linux.com/feature/119926]] + +### October 2007 + +* **2007-10-30:** Don't miss [[this interview with Lennart|http://fedoraproject.org/wiki/Interviews/LennartPoettering]] which goes a bit into detail what's coming next for PulseAudio +* **2007-10-30:** [[PulseAudio 0.9.7|http://freedesktop.org/software/pulseaudio/releases/pulseaudio-0.9.7.tar.gz]] has been released. This is a major feature enhancement release ([[Changes|http://pulseaudio.org/milestone/0.9.7]], [[announcement|https://tango.0pointer.de/pipermail/pulseaudio-discuss/2007-October/000824.html]], [[blog|http://0pointer.de/blog/projects/pa-097.html]]); The Volume Control, Volume Meter, Preferences, Manager, gst-pulse, xmms-pulse have been updated, too. +* **2007-10-17:** [[ars.technica on PulseAudio and GNOME|http://arstechnica.com/journals/linux.ars/2007/10/17/pulseaudio-to-bring-earcandy-to-linux]] +* **2007-10-12:** Please read this [[blog story|http://0pointer.de/blog/projects/pulseaudio-fud.html]] and the [[email linked therein|http://mail.gnome.org/archives/desktop-devel-list/2007-October/msg00136.html]] about how GNOME and [[PulseAudio|PulseAudio]] relate. + +### May 2007 + +* **2007-05-27:** [[PulseAudio 0.9.6|http://freedesktop.org/software/pulseaudio/releases/pulseaudio-0.9.6.tar.gz]] has been released. This is mostly a bugfix release. ([[Changes|http://pulseaudio.org/milestone/0.9.6]]) + +### February 2007 + +* **2007-02-06:** The [[video (Theora)|http://mirror.linux.org.au/pub/linux.conf.au/2007/video/talks/211.ogg]] and the [[slides|http://0pointer.de/public/pulseaudio-presentation-lca2007.pdf]] of Lennart's PulseAudio talk at [[linux.conf.au 2007 in Sydney|http://lca2007.linux.org.au/]] are now available for download. + +### August 2006 + +* **2006-08-26:** The new tool [[PulseAudio Preferences 0.9.5|http://0pointer.de/lennart/projects/paprefs/]] has been released. +* **2006-08-26:** [[PulseAudio Volume Control 0.9.4|http://0pointer.de/lennart/projects/pavucontrol/]], [[PulseAudio Manager 0.9.3|http://0pointer.de/lennart/projects/paman/]], [[PulseAudio Device Chooser 0.9.3|http://0pointer.de/lennart/projects/padevchooser/]] released +* **2006-08-26:** [[PulseAudio 0.9.5|http://freedesktop.org/software/pulseaudio/releases/pulseaudio-0.9.5.tar.gz]] released. Changes include: + * Add module-hal-detect, a module that detects all local sound hardware using [[HAL|http://freedesktop.org/wiki/Software_2fhal]] and loads the necessary modules. Handles hot-plug and hot-removal of audio devices. (By Shahms E. King) + * Add shared memory transfer method for local clients + * Update module-volume-restore to automatically restore the output device last used by an application in addition to the volume it last used. + * Add a new module module-rescue-streams for automatically moving streams to another sink/source if the sink/source they are connected to dies + * Add support for moving streams "hot" between sinks/sources + * Reduce memory consumption and CPU load as result of Valgrind/Massif profiling + * Add new module module-gconf for reading additional configuration statements from GConf + * Fix module-tunnel to work with the latest protocol + * Miscellaneous fixes + +### July 2006 + +* **2006-07-24:** [[PulseAudio Volume Control 0.9.3|http://0pointer.de/lennart/projects/pavucontrol/]] released. +* **2006-07-24:** [[PulseAudio Version 0.9.4|http://freedesktop.org/software/pulseaudio/releases/pulseaudio-0.9.4.tar.gz]] released. Changes include: + * Fix broken time event handling in the GLIB event loop adapter (0.9.3 shipped with a broken adapter for GLIB which caused tools like [[padevchooser|http://0pointer.de/lennart/projects/padevchooser/]] to hang on startup. This fix solves the problem only half-way. To fix it wholly please make sure to update [[Avahi|http://avahi.org/]] to 0.6.12) + * Some valgrind/massif results: halve memory consumption, make PulseAudio even more lightweight + * Fix pkg-config files for AMD64 +* **2006-07-21:** [[libao-pulse 0.9.3|http://0pointer.de/lennart/projects/libao-pulse/]], [[xmms-pulse 0.9.3|http://0pointer.de/lennart/projects/xmms-pulse/]], [[gst-pulse 0.9.3|http://0pointer.de/lennart/projects/gst-pulse/]] released. +* **2006-07-21:** [[PulseAudio 0.9.3|http://freedesktop.org/software/pulseaudio/releases/pulseaudio-0.9.3.tar.gz]] released. Changes include: + * add support for running the PulseAudio daemon as system-wide instance (See [[System Wide Instance|Software/PulseAudio/Documentation/User/SystemWide]] for more information) + * add authentication by IP address range ACL (`auth-ip-acl=`) + * update FreeBSD compatibility + * add support to set resource limits on platforms that support them and set some of them + * remove `loopback=` argument for `module-*-protocol-tcp` since it is a superset of `listen=` and has an unexpected default + * remove GLIB 1.2 event loop adapter + * rework GLIB 2.0 event loop adapter to act as a single GSource, make it compatible with recursive main loops + * add an API to check whether a source/sink is hardware or virtual + * remove warning about SIGPIPE in client apps + * improve latency calculation of NULL sink which allows it to be used for video playback + * port Zeroconf code from the HOWL API to the native [[Avahi|http://avahi.org]] API +* **2006-07-08:** [[PulseAudio Volume Control 0.9.2|http://0pointer.de/lennart/projects/pavucontrol/]], [[PulseAudio Volume Meter 0.9.2|http://0pointer.de/lennart/projects/pavumeter/]], [[PulseAudio Manager 0.9.2|http://0pointer.de/lennart/projects/paman/]], [[PulseAudio Device Chooser 0.9.2|http://0pointer.de/lennart/projects/padevchooser/]], [[libao-pulse 0.9.2|http://0pointer.de/lennart/projects/libao-pulse/]], [[xmms-pulse 0.9.2|http://0pointer.de/lennart/projects/xmms-pulse/]], [[gst-pulse 0.9.2|http://0pointer.de/lennart/projects/gst-pulse/]] released. +* **2006-07-08:** [[PulseAudio 0.9.2|http://freedesktop.org/software/pulseaudio/releases/pulseaudio-0.9.2.tar.gz]] released. Changes include: + * Rename project to PulseAudio (see [[this blog article|http://0pointer.de/blog/projects/pulse.html]] for an explanation) + * increase maximum number of concurrent connections + * fix latency interpolation + * add support for reverse endian sound cards + * add support for recording in padsp + * reenable CPU load limiter + * other bugfixes + +### June 2006 + +* **2006-06-02:** [[Version 0.9.1|http://freedesktop.org/software/pulseaudio/releases/polypaudio-0.9.1.tar.gz]] released. Changes include: + * load modules even when libtool `.la` files are missing + * generate better ALSA device names from `module-detect` + * if an ALSA device doesn't support the requested number of channels or the frequency, accept what ALSA suggests instead + * AMD64 portability + * drop `.sh` suffix of `esdcompat.sh` + * build system fixes No API or ABI changes were made + +### May 2006 + +* **2006-05-26:** [[Version 0.9.0|http://freedesktop.org/software/pulseaudio/releases/polypaudio-0.9.0.tar.gz]] released. Changes include: + * new module `module-volume-restore` + * new OSS API emulation tool `padsp` + * require valid UTF-8 strings everywhere + * properly support ALSA channel maps for surround sound + * increase maximum number of channels per stream to 32 + * add new threaded main loop API for synchronous programs + * introduce real shared object versioning + * a few API additions + * many, many bugfixes + +### April 2006 + +* **2006-04-28:** [[Version 0.8.1|http://freedesktop.org/software/pulseaudio/releases/polypaudio-0.8.1.tar.gz]] released. Changes include: + * support for specifying the channel map on the command lines of `paplay` and `pacat` and as arguments to the driver modules + * ALSA hardware mixer compatibility + * fix linking + * properly remove `PF_UNIX` sockets when unloading protocol modules + * fix sample cache + * many other fixes +* **2006-04-13:** [[Version 0.8|http://freedesktop.org/software/pulseaudio/releases/polypaudio-0.8.tar.gz]] released. Changes are too many to count - consider reading [[this blog entry|http://0pointer.de/blog/projects/polypaudio-0.8.html]] for more information. Many, many minor fixes. + +### November 2004 + +* **2004-11-21:** [[Version 0.7|http://freedesktop.org/software/pulseaudio/releases/polypaudio-0.7.tar.gz]] released; changes include: IPv6 support; PID file support; publish credentials in X11 root window (module-x11-publish; new tool pacmd; ESOUND backend; new command load-sample-dir-lazy; many, many minor fixes. + +### October 2004 + +* **2004-10-28:** [[Version 0.6|http://freedesktop.org/software/pulseaudio/releases/polypaudio-0.6.tar.gz]] released; changes include: TCP wrappers support; don't load the complete sound file into memory when playing back using pa_play_file(); autoload API change; don't load all sound files as FLOAT32; shorten default buffers; client-side latency interpolation; add new user volume metrics; add module-tunnel, module-null-sink, module-match and new tool paplay; new API version macros; many client API improvements; correctly lock cookie file generation; correctly lock daemon autospawning; print daemon layout to STDERR on SIGHUP; new options for pacat: allow sample type specification. + +### September 2004 + +* **2004-09-24:** [[Version 0.5.1|http://freedesktop.org/software/pulseaudio/releases/polypaudio-0.5.1.tar.gz]] released; changes include: improve esound protocol compatibility; fix autospawning via libesd; make use of POSIX capabilities; allow SCHED_FIFO scheduling only for users in group realtime; minor build system fix. +* **2004-09-20:** [[Version 0.5|http://freedesktop.org/software/pulseaudio/releases/polypaudio-0.5.tar.gz]] released; changes include: extensive API improvements, new module module-combine for combining multiple sound cards into one, gcc 2.95 compatibility, configuration files, add "lazy" samples, support for source and network latency measurements, add module-pipe-source, many other fixes and improvements. +* **2004-09-08:** [[Version 0.4|http://freedesktop.org/software/pulseaudio/releases/polypaudio-0.4.tar.gz]] released; changes include: daemon auto spawning, support for SCHED_FIFO scheduling, three new modules, proper logging, CPU load watchdog, many fixes. + +### August 2004 + +* **2004-08-27:** [[Version 0.3|http://freedesktop.org/software/pulseaudio/releases/polypaudio-0.3.tar.gz]] released; changes include: support for both glib 2.0 and glib 1.2, future cancellation, API updates, many fixes, relicense client library to [[LGPL|http://www.gnu.org/copyleft/lesser.html]]. +* **2004-08-20:** [[Version 0.2|http://freedesktop.org/software/pulseaudio/releases/polypaudio-0.2.tar.gz]] released; changes include: added sample cache, introspection API, client API documentation, module autoloading, glib support, a module for intercepting X11 bell events, and much more. + +### July 2004 + +* **2004-07-17:** [[Version 0.1|http://freedesktop.org/software/pulseaudio/releases/polypaudio-0.1.tar.gz]] released
\ No newline at end of file diff --git a/Software/PulseAudio/Ports/Android.mdwn b/Software/PulseAudio/Ports/Android.mdwn new file mode 100644 index 00000000..2c84ae38 --- /dev/null +++ b/Software/PulseAudio/Ports/Android.mdwn @@ -0,0 +1,66 @@ + +[[!inline pages="Software/PulseAudio/TOC" quick="yes" raw="yes"]] + + +# Android Port + +These build steps assume that you have set up a basic AOSP build environment as described in the [[Android Open Source Project pages|http://source.android.com/source/building.html]]. + + +## Hardware + +The repository has been tested on and has configuration for the Samsung/Google Galaxy Nexus, which at the time of writing this is the reference platform for Android development. It should be fairly straightforward to port to a Pandaboard, and just a little less so for other devices with ALSA support (it's mostly a matter of making sure the mixer paths are correctly configured or adding appropriate ALSA UCM configuration). + + +## androgenizer + +Get [[androgenizer|http://cgit.collabora.com/git/user/derek/androgenizer.git/]], build it, and make sure the binary is in your path. + + +## Get the code + +This assumes you have a checkout of the AOSP code from Google upstream already. + + +[[!format txt """ +$ cd <top-level-AOSP-source-dir> +$ wget http://people.collabora.com/~arun/android/local_manifest.xml -O .repo/local_manifest.xml +$ .repo/repo/repo sync +"""]] + +## Compile + + +[[!format txt """ +$ (assuming you've run envsetup.sh and lunch from the AOSP build instructions) +$ export PATH=$PATH:/path/to/androgenizer +$ make pulseaudio-aggregate-configure +$ (you will see a failure while configuring pulseaudio) +$ make libltdl +$ make pulseaudio-aggregate-configure +$ make +"""]] + +## Running + +When you flash and restart the system image, you are now running [[PulseAudio|PulseAudio]] as a replacement for [[AudioFlinger|AudioFlinger]]. Various bits of functionality are available, and this is a moving target. The following are tested at the time of writing this section: + +* Audio playback for most apps using native Android APIs +* Volume control +* Switching of outputs depending on the device plugged in (headphones, headset) + +## To Be Done + +The following pieces are either partially or not at all implemented + +* Audio playback API completeness: infrequently-used bits of the API (loops, markers, etc.) are not implemented +* Calls: this is work-in-progress, but needs to be cleaned and merged +* Policy: initial implementations of volumes and port switching are done. There are probably a lot of bits of policy that still need to be implemented for us to have feature/bug-parity with standard Android. +* Audio record API: can be implemented fairly easily like the playback API was +* Audio effects API (we don't support this in PulseAudio at the moment) + +## Misc + +That's about it. Instructions on pulling powertop into the build are TBF. + +Information on the porting effort and some performance numbers is at [[this blog post|http://arunraghavan.net/2012/01/pulseaudio-vs-audioflinger-fight/]]. diff --git a/Software/PulseAudio/Ports/OSX.mdwn b/Software/PulseAudio/Ports/OSX.mdwn new file mode 100644 index 00000000..8992c258 --- /dev/null +++ b/Software/PulseAudio/Ports/OSX.mdwn @@ -0,0 +1,49 @@ + +[[!inline pages="Software/PulseAudio/TOC" quick="yes" raw="yes"]] + + +# Ports: OSX + +This page is work in progress. I'm just writing down the steps I'm taking to make this work. + + +## git + +If you want to be at PA's bleeding edge, you need to have [[git|http://www.git-scm.com]] installed. There's a resource for [[git for Mac OS X|http://code.google.com/p/git-osx-installer/downloads/list?can=3]] which even has a nice installer. + + +## Mac Ports + +PA depends on quite some libraries which need to be installed in order to make it build from the sources. Fortunately, [[Mac Ports|http://www.macports.org/]] provides all of them. Download and install it, following the instructions found on their side. + +Once set up, you need at least to install the following packages: + + +[[!format txt """ +sudo port install autoconf automake intltool libtool libsndfile speex-devel gdbm liboil json-c +"""]] +Make sure you add the path to the binaries built by Mac Ports to your $PATH variable. This is usually /opt/local/bin. And since there are some binaries provided by Mac Ports that also ship with Mac OS X in older versions, make sure the Mac Ports path comes first in the list. Otherwise the build will break. + + +## Building + +There are some variables that need to be set to make the build process look at the right places of your system. + + +[[!format txt """ +export CC="gcc-4.2" +export CFLAGS="-I/opt/local/include" +export LDFLAGS="-L/opt/local/lib" +"""]] +Then run + + +[[!format txt """ +./autogen.sh \ + --disable-jack \ + --disable-hal \ + --disable-bluez \ + --disable-dbus \ + --disable-avahi +make +"""]]
\ No newline at end of file diff --git a/Software/PulseAudio/Ports/Windows.mdwn b/Software/PulseAudio/Ports/Windows.mdwn new file mode 100644 index 00000000..759eb27c --- /dev/null +++ b/Software/PulseAudio/Ports/Windows.mdwn @@ -0,0 +1,2 @@ + +Page moved to [[WindowsSupport|WindowsSupport]] diff --git a/Software/PulseAudio/Ports/Windows/Support.mdwn b/Software/PulseAudio/Ports/Windows/Support.mdwn new file mode 100644 index 00000000..48224816 --- /dev/null +++ b/Software/PulseAudio/Ports/Windows/Support.mdwn @@ -0,0 +1,15 @@ + + +# PulseAudio on Windows + +PulseAudio is automatically build for Windows using the [[OpenSUSE BuildService|https://build.opensuse.org/project/monitor?package=&project=home%3Amkbosmans%3Amingw32%3Apulseaudio]]. For convenience, a [[zipfile containing preview binaries|http://bosmans.ch/pulseaudio/pulseaudio-1.1.zip]] is available. + + +### Known problems + +Of course not all functionality can be ported from Linux to Windows. Some features are missing and other things are currently just buggy. + +* RTP isn't working yet +* Assert failure when using pacat -t raw +* No UNIX sockets support +* GUI utilities not ported
\ No newline at end of file diff --git a/Software/PulseAudio/Quotes.mdwn b/Software/PulseAudio/Quotes.mdwn new file mode 100644 index 00000000..d930540f --- /dev/null +++ b/Software/PulseAudio/Quotes.mdwn @@ -0,0 +1,36 @@ + +Fun quotes from IRC. Take this stuff seriously at your own peril. + + + +--- + + +[[!format txt """ +Ford_Prefect | What I want to know is when we're going to have + | S64LE +Ford_Prefect | What's the point of buyng a 64-bit processor if I'm + | using 32-bit samples + heftig | what do you want to do? accurately replay a jet, + | then a gnat? + ohsix | when we need to represent the center of the sun and + | the universe background radiation in the same + | perceptible segment +Ford_Prefect | I want to play the sound of a tree falling in a + | forest when there's nobody around to watch +"""]] + + +--- + + +[[!format txt """ +courmisch | I don't wanna hear excuses! the fact is that PA + | does not support double precision + heftig | fuck double, implement a 'bc' backend +"""]] + + +--- + + diff --git a/Software/PulseAudio/RFC/PriorityRouting.mdwn b/Software/PulseAudio/RFC/PriorityRouting.mdwn new file mode 100644 index 00000000..9468b1d4 --- /dev/null +++ b/Software/PulseAudio/RFC/PriorityRouting.mdwn @@ -0,0 +1,201 @@ + +[[!inline pages="Software/PulseAudio/TOC" quick="yes" raw="yes"]] + + +# RFC: Priority Routing + +It's been pretty much about 19 months since I clearly spent a very satisfying Valentines day and [[first wrote about this|http://colin.guthr.ie/2010/02/this-is-the-route-to-hell/]], but here goes at actually getting on with implementing it! + +Firstly, while we pretty much all accept that we want to have priority list routing in PA, we also do not want to restrict usage and limit the usefulness of other routing systems. + +For this reason the "routing" infrastructure in PA will be split be the initial functionality added. It is a very basic patch that utilises the current HOOK structure within PA which has a built in priority system. + +We will then build on this generic routing system to create a priority list routing infrastructure. + +I've knocked up [[a proposed implementation|http://colin.guthr.ie/git/pulseaudio/commit/?h=route&id=61d73564c1c2b0b832f14bfd4f2b77c98febb735]] of this approach. + +The above patch is untested and is a proof of concept, and opinions are, of course, welcome. + + +## Priority Lists + +Fundamentally, "priority lists" will be a core concept (unless someone can come up with a way to define objects that can be used in multiple separate modules easily). + +Modules will be able to "register" a priority list in much the same way as they register a sink, source or card etc. One thing that is perhaps not immediately obvious is that a "priority list" may actually contain multiple device lists, each with a different "lookup key". This structure allows us to implement "role" based priority within a single object with each role ("music", "event", "voip", etc.) having it's own individual list of devices in priority order. + +The API will look something like: + + +[[!format txt """ + pa_priority_list *pa_priority_list_register(pa_core *core, const char *name, const char *uiname, const char* propname, pa_device_type_t dtype, pa_hook_priority_t weight) { + pa_priority_list *priolist; + + pa_assert(core); + pa_assert(name); + pa_assert(uiname); + + priolist = pa_xnew0(pa_priority_list, 1); + /* OR */ + priolist = pa_msgobject_new(pa_priority_list); + + if (!(name = pa_namereg_register(core, name, PA_NAMEREG_PRIOLIST, s, TRUE))) { + pa_log_debug("Failed to register priority list name %s.", name); + pa_xfree(priolist); + return NULL; + } + + priolist->core = core; + priolist->name = name; + priolist->uiname = uiname; + priolist->dtype = dtype + priolist->weight = weight; + if (propname) + priolist->propname = pa_xstrdup(propname); + + priolist->hook = pa_hook_connect(&m->core->hooks[PA_CORE_HOOK_SINK_ROUTE], weight, (pa_hook_cb_t) priority_list_route, priolist); + + return priolist; + } +"""]] +We will implement a generic function that "does priority list routing" which will look something like: + + +[[!format txt """ + static pa_hook_result_t priority_list_route(pa_core *c, pa_priority_list *priolist, pa_route_decision_t *route) { + const char* key = NULL; + + pa_assert(c); + pa_assert(priolist); + pa_assert(route); + + /* If a device is already set, short-circuit return */ + if ((priolist->dtype == PA_DEVICE_TYPE_SINK && route->device.sink) + || (priolist->dtype == PA_DEVICE_TYPE_SOURCE && route->device.source) + return PA_HOOK_OK; + + if (priolist->propname) { + /* Find the routing key from the proplist */ + key = pa_proplist_gets(priolist->proplist, priolist->propname); + + if (!key) { + /* This stream has no lookup key but this is a keyed, list therefore + it we cannot match anything */ + return PA_HOOK_OK; + } + } + + /* Go through priority list (for key) and attempt to find an appropriate device */ + pa_sink *sink = NULL; + pa_source *source = NULL; + + ... + + if (sink) + route.device.sink = sink; + else if (source) + route.device.source = source; + + return PA_HOOK_OK; + } +"""]] +This method will be able to implement the necessary priority based logic within the generic routing framework mentioned earlier. + +Lets put this into action a little with some examples. Lets say a module implements a "default" priority list. It therefore calls pa_priority_list_register in the following way: + + +[[!format txt """ + u->priolist = pa_priority_list_register(core, "default-sink", "Default Playback", NULL, PA_DEVICE_TYPE_SINK, 0); +"""]] +This call creates a non-keyed (i.e. it will not look up anything in the proplist to find which internal priority list to use - thus there is only one internal priority list in this case) priority list to decide the "Default Playback" device. The internal name "default-sink" is given along with a more user friendly name (more about that later). It of course automatically registers the hook and thus the complexity at the module level is minimal. There would be further complexity to HOOK into when the user sets a default sink/source and automatically update the priority list to move that device to the top of the priority list. + +So lets look at a more complicated example, a module which implements role base routing. Despite being "more complicated" it's actually just as simple. + + +[[!format txt """ + u->priolist = pa_priority_list_register(core, "role-sink", "Role Playback", "media.role", PA_DEVICE_TYPE_SINK, 0); +"""]] +Now application specific routing can also be done easily via an appropriate module too, but using the "application.name" property. Simple! + +If a given module wants to do a more complicated "lookup key", they can simply do something like: + + +[[!format txt """ + u->priolist = pa_priority_list_register(core, "complex-sink", "Complex Playback", "route.complexkey", PA_DEVICE_TYPE_SINK, 0); + + /* Subscription to new/changed streams */ + + /* Subscription callback code to set the route.complexkey property if it's not already set */ +"""]] +So the general structure is still pretty useful and flexible should it be needed. + + +## LTBAQ + + +### What is LTBAQ? + +Likely To Be Asked Questions :) + + +### Introspection + +So much like the sinks/sources etc. There will be an introspection and API calls to update priority lists. If you update a list but do not specify all the device+ports in the list currently, then the all non-specified device+ports will be appended in their current order to the ones supplied. Whenever a user updates a priority list, all streams will be re-routed. + + +### What's actually in the lists? + +Each entry in the actual priority list is a device (sink or source) + it's port. + + +### How will they be saved on disk? + +Using the current 'database' support in PA to write them to disk. It not necessarily amazing but there is no need to change this. The internal name given to the priory list will determine it's name on disk. + + +### Can I see what's in a priority list easily? + +As a core object, I intend to dump the contents of the priority lists via `pacmd list-priorities` or a similar such command. Whether we add this to the default `pacmd ls` output is open to debate. + + +### Can it switch ports/profiles if a device is higher up the priority list? + +The current plan is to add two configuration variables to allow the priority lists to automatically switch profiles and/or ports as needed. This mode of operation would make routing non-deterministic, as it could only switch if no other stream is playing on a device+port that would have to be removed to enable the device+port of the stream we are routing. Thus this mode is both complicated and non-deterministic and as a result may not be enabled by default. As, however, it may be needed for some scenarios we would like to support out of the box (e.g. digital output from media players) we will have to see exactly how well this works in practice and defer the "enable by default" until we have evaluated the side effects. + + +### I'm going to make an editor for the priority lists, how can I get nice names for the device+port entries that are not currently available? + +This is a problem. At the moment we do not record anything in PA that covers device+ports that are not currently active (e.g. an unplugged USB device). This problem was previously solved with module-device-manager and a protocol extension. It turned into a more generic system for device routing (which is a system that has inspired this expanded proposal). I would therefore propose that we keep module-device-manager but simplify it greatly (keeping the APIs for a while to ensure backwards compatibility but ensuring they are just passes through to the newer system whenever possible) and thus returning m-d-m to it's primary role, which is to collect details of devices seen for use in UIs that need that information. I would propose that for each device+port it would store and make available: the card name+description+icon, the device name+description+icon, the port name+description+icon (at present ports do not have icons, but this should be changed - headphones vs. speaker ports clearly need to be shown differently in GUIs) + + +### What if I want to stop routing? + +Sometimes, a stream specifies exactly what sink they want. This is especially true for "speaker test" apps where a stream really should not be moved under any circumstances. This is not shown in the above linked patch, but when streams are connected in this way, we simply add a new flag to streams: STREAM_DONT_ROUTE. When this flag is present on the stream, we simply avoid any calls to the routing system and the whole process is totally bypassed. Specifying a (valid) non-null device name in the pa_stream_connect_plaback/record() will add this flag automatically. Thus existing applications (e.g. libcanberra used in a speaker test scenario) will still work correctly. + + +### I want to use new devices that I plug in by default. Is that supported? + +If you plug in a new USB device that we don't yet know about (i.e. not present in a priority list), then there could, in principle, be a configuration flag that ensures that the new devices are injected at the top of the priority list. This, much like the automatic stuff above, would have to be configurable in some capacity, probably via some form of callback that is used to calculate where to inject a new device in a given priority list. + + +### What about automatic stuff, like magically using headsets for phone calls? + +This would still be possible. This is currently done by module-intended-roles and it actively moves/sets the device for certain streams. I would propose a change here to make this module "inject" the device into the appropriate priority list system (with the appropriate "lookup key") if the device is not already in that list. We would ensure that any changes made to the priority lists are only written when using the public API calls - e.g. as a result of "user action". Anything that happens automatically will not persist across reboots. Of course as soon as the user take some action (like moving their voip call to their internal USB headset rather than their Bluetooth one), their priority list will be written to disk and used for the future. This system would likely use the same callback mechanism to determine where to inject the item as mentioned above. As there may be multiple callbacks registered in which case we may utilise the HOOK system again, with weights, in the same way as the routing patch linked at the beginning operates. It may however be simpler to just implement a simpler system for multiple, weighted callbacks. Open to suggestions here. + + +### What about existing API calls for moving streams? + +At present, a stream is tagged with a "stream restore id". When you move the stream to a device, it's device is saved/restored keyed on this id. This stream restore id can be used to set different devices for different roles, or (if a role is not present) for each application itself. I would propose that a similar methodology is used when integrating this with priority list routing. i.e. we find the first priority list (by weight) which this stream would match, then ensure the device it is being moved to is moved to the top of that priority list. This would trigger an automatic "reroute" (as the priority list had changed) and the stream will be moved. So while this is how the code would work, there are essentially two different approaches that could employed to make things work sensibly with the existing APIs. + +* **Option 1** is to simply leave the current APIs working as they do but ensure that some code (modular) somewhere notices the stream moves and then updates the priority lists retro-actively which then triggers a reroute (which we want as there may be other streams also playing that will be affected by the change). This code would have to be able to distinguish a stream move that happens as a result of a reroute and thus ignore it otherwise unnecessary work would be undertaken (although this should, in theory at least) be the only problem if we were to not ignore some stream moves. +* **Option 2** is to alter existing code for moving streams to allow for priority list routing. Rather than do any direct moving, the code would simply edit the priority lists pro-actively and let the reroute triggered as a result do the actual moving of the streams. Thus our work would end here. Of course if it does not match any priority list (which would certainly be the case if no priority list routing modules are loaded), then the code would operate as now. +Either approach means that existing applications will continue to operate without any major changes (although full support for manipulating/listing priority lists is obviously possible through direct introspection mentioned above). + + +### What about setting default/fall-back devices? + +This would likely be solved in a very similar way to the above problem for moving streams. + + +### What happens if I have two streams playing that match the same priority list and that list is updated? + +Both streams will be moved. If this is done via the existing APIs as mentioned above, the fact that both streams move may come as a surprise, however, a similar problem exists just now with the current streams-restore-id approach with module-stream-restore. While currently only the moved stream will change device immediately, the other stream will only be rerouted when the streams is next created. Depending on the client implementation this could be at track change or it could be when the application is restarted. Either way the change does not happen when the user triggers it and as a result it is arguably confusing to the user when it does eventually kick in. I would argue that the new proposed approach is clearer, even if the user may be confused as to why moving the stream from [[RhythmBox|RhythmBox]] also affects his Amarok stream. That said, the likelihood of him running both applications at the same time is minimal and thus I do not believe that this is a major problem in practice. diff --git a/Software/PulseAudio/Requirements.mdwn b/Software/PulseAudio/Requirements.mdwn new file mode 100644 index 00000000..b2d02f17 --- /dev/null +++ b/Software/PulseAudio/Requirements.mdwn @@ -0,0 +1,14 @@ + +[[PulseAudio|PulseAudio]] contains a lot of non-trivial code that has the side effect of triggering a few bugs in libraries it uses. + +1. libtool's libltdl 1.5.22 is buggy and causes PA to abort immediately after startup with a mutex locking error. Upgrade to 1.5.24 at least. +1. Some recent libc versions have a locking problem in the dynamic module loader, which will cause [[PulseAudio|PulseAudio]] to freeze randomly. This has been fixed in Fedora glibc 2.6.90-14. [[rhbz|https://bugzilla.redhat.com/show_bug.cgi?id=284171]] +1. Some older libc6 versions have problems linking [[PulseAudio|PulseAudio]], see #152 +1. libatomic_ops for AMD64 is causes random bugs. Make sure to use a compiler that supports !<ins>sync to avoid these issues. +1. Some distros don't properly configure /dev/tmpfs to enable POSIX shared memory. This will cause PA to print warnings on startup and will cause PA to disable shared memory data transfer. +1. Some distros don't enable "POSIX" capabilities in the kernel. However, [[PulseAudio|PulseAudio]] expects them to be available when compiled with support for them. Make sure to enable them in the kernel. +1. If you compile PA on an embedded platform (i.e. one with exotic CPU) it will fall back to emulated atomic operations. Those are not real-time safe and also very slow. For the ARM case, read [[this blog story|http://0pointer.de/blog/projects/atomic-rt.html]]. +1. There is a known and somewhat annoying issue with PA and ALSA that affects some apps using ALSA output via the PA ALSA plugin (e.g. Ekiga). See #23 and the upstream [[ALSA Bug|https://bugtrack.alsa-project.org/alsa-bug/view.php?id=2601]] for more details. +The latest version that is known to compile fine on Solaris is 0.9.6. Newer versions are tested on Linux only. Patches welcome. + +Compatibility with Win32 (with mingw32) is described at [[Windows Support|Software/PulseAudio/Ports/Windows/Support]]. diff --git a/Software/PulseAudio/TOC.mdwn b/Software/PulseAudio/TOC.mdwn new file mode 100644 index 00000000..ec386752 --- /dev/null +++ b/Software/PulseAudio/TOC.mdwn @@ -0,0 +1,11 @@ + +[[!img Logo] +[[!table header="no" class="mointable" data=""" +[[Home|Software/PulseAudio]] • [[About|Software/PulseAudio/About]] • [[Community|Software/PulseAudio/Documentation/User/Community]] • [[Download|Software/PulseAudio/Download]] • [[Documentation|Software/PulseAudio/Documentation]] • [[Planet|http://freedesktop.org/software/pulseaudio/planet/]] +"""]] + + +[[!format rawhtml """ +#!html +<br clear="both"/> +"""]]
\ No newline at end of file diff --git a/Software/PulseAudio/TOC/logo.png b/Software/PulseAudio/TOC/logo.png Binary files differnew file mode 100644 index 00000000..f90a8ad7 --- /dev/null +++ b/Software/PulseAudio/TOC/logo.png diff --git a/Software/ScimDownload.mdwn b/Software/ScimDownload.mdwn new file mode 100644 index 00000000..8ed921af --- /dev/null +++ b/Software/ScimDownload.mdwn @@ -0,0 +1,58 @@ + + +## Download SCIM and related packages. + + +### Source packages: + + * [[scim-1.0.1.tar.gz|http://freedesktop.org/~suzhe/sources/scim-1.0.1.tar.gz]]<br>Source code of the main package of SCIM. + * [[skim-1.0.2.tar.bz2|http://prdownloads.sourceforge.net/scim/skim-1.0.2.tar.bz2?download]]<br>Source code of skim, including scim-panel-kde, KConfig config module and setupUIs for scim-lib and its own. + * [[scim-tables-0.4.3.tar.gz|http://freedesktop.org/~suzhe/sources/scim-tables-0.4.3.tar.gz]]<br>Source code of the table based input methods. + * [[scim-chinese-0.4.2.tar.gz|http://freedesktop.org/~suzhe/scim-chinese/scim-chinese-0.4.2.tar.gz]]<br>Source code of SCIM Chinese Smart Pinyin input method. + * [[scim-uim-0.1.3.tar.gz|http://freedesktop.org/~suzhe/sources/scim-uim-0.1.3.tar.gz]]<br>Source code of SCIM-UIM input method engine which use uim library as the backend. + * [[scim-m17n-0.1.3.tar.gz|http://freedesktop.org/~suzhe/sources/scim-m17n-0.1.3.tar.gz]]<br>Source code of SCIM-M17N input method engine which use m17n library as the backend. + * [[scim-hangul-0.1.2.tar.gz|http://freedesktop.org/~suzhe/sources/scim-hangul-0.1.2.tar.gz]]<br>Source code of SCIM-HANGUL input method engine which is ported from imhangul project (imhangul.kldp.net). + * [[Sourceforge Mirror|http://sourceforge.net/project/showfiles.php?group_id=108454]]<br>Some old releases are also available here. + * [[Gentoo ebuilds|http://packages.gentoo.org/search/?sstring`scim]]<br>All of these packages are incorporated in [[Gentoo official portage|http://packages.gentoo.org/search/?sstring`scim]], so you can just emerge the corresponding ebuild. (Do not forget to specify `ACCEPT_KEYWORDS`"~x86"= to install the latest version) + * [[Mandrake Cooker|http://sourceforge.net/projects/mdk-ut/]]<br>Latest SCIM project packages for Mandrake Cooker can be found at the download page of the project [[UT Extra Packages for Mandrake|http://sourceforge.net/projects/mdk-ut/]]. + +### Binary packages: + + * Default Build (GCC 3.3.1 GLIBC 2.3.x GTK+ 2.2.x) + * [[scim-0.99.8-1.i586.rpm|http://freedesktop.org/~suzhe/binaries/scim-0.99.8-1.i586.rpm]] The main package of SCIM platform. + * [[scim-devel-0.99.8-1.i586.rpm|http://freedesktop.org/~suzhe/binaries/scim-devel-0.99.8-1.i586.rpm]] The development package. + * [[scim-chinese-0.4.1-1.i586.rpm|http://freedesktop.org/~suzhe/scim-chinese/scim-chinese-0.4.1-1.i586.rpm]] The binary package of Smart Pinyin IMEngine. + * [[scim-hangul-0.1.0-1.i586.rpm|http://freedesktop.org/~suzhe/binaries/scim-hangul-0.1.0-1.i586.rpm]] The binary package of Hangul IMEngine. + * SUSE Linux 9.1 Build (GCC 3.3.3 GLIBC 2.3.x GTK+ 2.2.x) + * [[scim-1.0.1-1suse.i586.rpm|http://freedesktop.org/~suzhe/binaries/scim-1.0.1-1suse.i586.rpm]] The main package of SCIM platform. + * [[scim-devel-1.0.1-1suse.i586.rpm|http://freedesktop.org/~suzhe/binaries/scim-devel-1.0.1-1suse.i586.rpm]] The development package. + * [[skim-1.0.0-1suse.i586.rpm|http://prdownloads.sourceforge.net/scim/skim-1.0.0-1suse.i586.rpm?download]] Skim package (Thanks to Jan Hefti <j.hefti ZAI hamburg.de>). + * [[scim-chinese-0.4.1-1suse.i586.rpm|http://freedesktop.org/~suzhe/scim-chinese/scim-chinese-0.4.1-1suse.i586.rpm]] The binary package of Smart Pinyin IMEngine. + * [[scim-hangul-0.1.2-1suse.i586.rpm|http://freedesktop.org/~suzhe/binaries/scim-hangul-0.1.2-1suse.i586.rpm]] The binary package of Hangul IMEngine. + * Fedora Core 3 Build (GCC 3.4.x GLIBC 2.3.x GTK+ 2.4.x) + * [[scim-1.0.2-1fc3.i386.rpm|http://prdownloads.sourceforge.net/scim/scim-1.0.2-1fc3.i386.rpm?download]] All in one package of SCIM platform. + * [[scim-devel-1.0.2-1fc3.i386.rpm|http://prdownloads.sourceforge.net/scim/scim-devel-1.0.2-1fc3.i386.rpm?download]] The core package of SCIM platform. + * [[scim-1.0.2-1fc3.src.rpm|http://prdownloads.sourceforge.net/scim/scim-1.0.2-1fc3.src.rpm?download]] The source rpm of SCIM platform. + * [[scim-uim-0.1.3-4fc3.i386.rpm|http://prdownloads.sourceforge.net/scim/scim-uim-0.1.3-4fc3.i386.rpm?download]] The uim support for SCIM platform. + * [[scim-uim-0.1.3-4fc3.src.rpm|http://prdownloads.sourceforge.net/scim/scim-uim-0.1.3-4fc3.src.rpm?download]] The source rpm of SCIM-UIM. + * [[scim-qtimm-0.7.5-1fc3.i386.rpm|http://prdownloads.sourceforge.net/scim/scim-qtimm-0.7.5-1fc3.i386.rpm?download]] The rpm of SCIM-QTIMM. + * [[scim-qtimm-0.7.5-1fc3.src.rpm|http://prdownloads.sourceforge.net/scim/scim-qtimm-0.7.5-1fc3.src.rpm?download]] The source rpm of SCIM-QTIMM. + * Fedora Core 2 Build (GCC 3.3.3 GLIBC 2.3.x GTK+ 2.4.x) + * [[scim-1.0.0-1fc2.i386.rpm|http://freedesktop.org/~suzhe/binaries/scim-1.0.0-1fc2.i386.rpm]] The main package of SCIM platform. + * [[scim-devel-1.0.0-1fc2.i386.rpm|http://freedesktop.org/~suzhe/binaries/scim-devel-1.0.0-1fc2.i386.rpm]] The development package. + * [[skim-1.0.1-1fc2.i386.rpm|http://prdownloads.sourceforge.net/scim/skim-1.0.1-1fc2.i386.rpm?download]] Skim package (Thanks to Roland Wolters <[[wolters.liste@gmx.net|mailto:wolters.liste@gmx.net]]>). + * [[scim-chinese-0.4.1-1fc2.i386.rpm|http://freedesktop.org/~suzhe/scim-chinese/scim-chinese-0.4.1-1fc2.i386.rpm]] The binary package of Smart Pinyin IMEngine. + * [[scim-hangul-0.1.2-1fc2.i386.rpm|http://freedesktop.org/~suzhe/binaries/scim-hangul-0.1.2-1fc2.i386.rpm]] The binary package of Hangul IMEngine. + * Free BSD 5.x + * [[textproc/scim|http://www.freshports.org/textproc/scim/]] The main port of SCIM platform. + * [[textproc/skim|http://www.freshports.org/textproc/skim]] The port of skim package. + * [[chinese/scim-chinese|http://www.freshports.org/chinese/scim-chinese/]] The port of Smart Pinyin IMEngine. + * [[chinese/scim-tables|http://www.freshports.org/chinese/scim-tables/]] The port of scim-tables-zh package. + * [[japanese/scim-tables|http://www.freshports.org/japanese/scim-tables/]] The port of scim-tables-ja package. + * [[korean/scim-tables|http://www.freshports.org/korean/scim-tables/]] The port of scim-tables-ko package. + * scim-tables packages: + * [[scim-tables-zh-0.4.3-1.i586.rpm|http://freedesktop.org/~suzhe/binaries/scim-tables-zh-0.4.3-1.i586.rpm]] Input Method data for Chinese, including WuBi, CangJie, etc. + * [[scim-tables-ja-0.4.3-1.i586.rpm|http://freedesktop.org/~suzhe/binaries/scim-tables-ja-0.4.3-1.i586.rpm]] Input Method data for Japanese, including Hiragana, Katakana, etc. + * [[scim-tables-ko-0.4.3-1.i586.rpm|http://freedesktop.org/~suzhe/binaries/scim-tables-ko-0.4.3-1.i586.rpm]] Input Method data for Korean, including Hangul, Hanja, etc. + * [[scim-tables-additional-0.4.3-1.i586.rpm|http://freedesktop.org/~suzhe/binaries/scim-tables-additional-0.4.3-1.i586.rpm]] Input Method data for other languages, including Russian etc. +-- Main.[[LiuCougar|LiuCougar]] - 10 Oct 2004 diff --git a/Software/ScimHangul.mdwn b/Software/ScimHangul.mdwn new file mode 100644 index 00000000..ab67ae6b --- /dev/null +++ b/Software/ScimHangul.mdwn @@ -0,0 +1,40 @@ +## scim-hangul -- A Hangul !IMEngine for SCIM + +<img align`"right" src`"%ATTACHURLPATH%/scim_hangul_logo.png" alt="scim_hangul_logo.png" /> + + +### Introduction + +scim-hangul is a Hangul !IMEngine for SCIM, which is ported from [[imhangul|http://imhangul.kldp.net]] project. It supports both Hangul and Hanja input. + + +### Download + +---+++++ Source package + + * [[scim-hangul-0.0.1.tar.gz|http://freedesktop.org/~suzhe/sources/scim-hangul-0.0.1.tar.gz]] Early Snapshot. + * [[scim-hangul-0.0.2.tar.gz|http://freedesktop.org/~suzhe/sources/scim-hangul-0.0.2.tar.gz]] Early Snapshot. + * [[scim-hangul-0.0.3.tar.gz|http://freedesktop.org/~suzhe/sources/scim-hangul-0.0.3.tar.gz]] Early Snapshot. + * [[scim-hangul-0.1.0.tar.gz|http://freedesktop.org/~suzhe/sources/scim-hangul-0.1.0.tar.gz]] Early Snapshot. + * [[scim-hangul-0.1.1.tar.gz|http://freedesktop.org/~suzhe/sources/scim-hangul-0.1.1.tar.gz]] Early Snapshot. + * [[scim-hangul-0.1.2.tar.gz|http://freedesktop.org/~suzhe/sources/scim-hangul-0.1.2.tar.gz]] Early Snapshot. +---+++++ Subversion repository + +You may check out the latest code from svn repository by the following command: + + svn co http://freedesktop.org:8080/svn/scim/scim-hangul/trunk scim-hangul + +---+++++ Gentoo + + * The [[scim-hangul ebuild|http://packages.gentoo.org/search/?sstring`scim-hangul]] is in the offical portage, so `emerge scim-hangul` will do all the work for you. (At present, you must specify the ACCEPT_KEYWORDS`"~x86" to emerge scim-hangul). + +### TODO + + * More user configurable options. + +### THANKS + +Thanks Main.[[ChoeHwanjin]], the author of imhangul, very much. Without his great work, scim-hangul won't be realized. + +-- Main.[[KitaeKim]] - 09 Sep 2004 + diff --git a/Software/ScimHowtoTranslate.mdwn b/Software/ScimHowtoTranslate.mdwn new file mode 100644 index 00000000..b1c423c2 --- /dev/null +++ b/Software/ScimHowtoTranslate.mdwn @@ -0,0 +1,32 @@ + + +## Howto Translate SCIM to My Language? + +As SCIM and all its sub projects are NLSed compliant with the GNU gettext system, the task of the translation of SCIM project is to edit several pot files just like any other GNU softwares. These files contains: + +| *Package Name* | *Pot File(s)* | *Existing Translation* | | scim-lib | [[po/scim.pot|http://savannah.nongnu.org/cgi-bin/viewcvs/scim/scim-lib/po/scim.pot]] | de, fr, ja, ko, zh_CN, zh_TW | | skim | [[po/skim.pot|http://savannah.nongnu.org/cgi-bin/viewcvs/scim/skim/po/skim.pot]] <br> [[po/desktop.pot|http://savannah.nongnu.org/cgi-bin/viewcvs/scim/skim/po/desktop.pot]] | de, fr, ja, ko, zh_CN, zh_TW | | scim-chinese | [[po/scim-chinese.pot|http://savannah.nongnu.org/cgi-bin/viewcvs/scim/scim-chinese/po/scim-chinese.pot]] | de, fr, ja, ko, zh_CN, zh_TW | | scim-hangul | [[po/scim-hangul.pot|http://freedesktop.org:8080/svn/scim/scim-hangul/trunk/po/scim-hangul.pot]] | de, fr, ja, ko, zh_CN | + +When you finish with your po files, please send them to the [[mailing list|http://freedesktop.org/mailman/listinfo/scim]] and the developers will incorporate your po files in next release. + +Any comments or patches to existing translations are welcome all the time in our [[mailing list|http://freedesktop.org/mailman/listinfo/scim]]. + + +### Acknoledgement of Translators + +| Translator(s) | *Package Name* |||| | *Language* | *scim-lib* | *skim* | *scim-chinese* | *scim-hangul* | | *de* | Jan Hefti, Hendrik Brandt |||| | *fr* | Damien Menanteau |||| | *ja* | Yukiko Bando |||| | *ko* | kitae |||| | *zh_CN* | Developers |||| | *zh_TW* | Tetralet | Jim Huang | Tetralet | - | + +"-" in a cell denotes that the translation for this package is missing. + + +#### Details of Translators + + * Damien Menanteau <damien.menanteau ZAI cegetel.net> + * Hendrik Brandt <eru ZAI gmx.li> + * Jan Hefti <j.hefti ZAI hamburg.de> + * Jim Huang <jserv ZAI kaffe.org> + * kitae <neeum ZAI yahoo.com> + * Tetralet <tetralet ZAI pchome.com.tw> + * Yukiko Bando <ybando ZAI k6.dion.ne.jp> +(Please replace ZAI with @ to retrieve the original Email address) + +-- Main.[[LiuCougar|LiuCougar]] - 13 Nov 2004 diff --git a/Software/ScimIdeas.mdwn b/Software/ScimIdeas.mdwn new file mode 100644 index 00000000..40548bf4 --- /dev/null +++ b/Software/ScimIdeas.mdwn @@ -0,0 +1,19 @@ + + +## Ideas for SCIM + + +### Miscellaneous + +| *Ideas and Suggestion* | *Stats & Comment* | |\ Add the url of the SCIM homepage to the SCIM Help panel. It might help lead new users to the right place (instead of the old page). ;)\ -- Main.[[YukikoBando|YukikoBando]] - 07 Sep 2004\ |\ + +* | +|\ (In scim-hangul)How about show current input mode(Hangul, English) in tray icon. if then there will be need one more icon\ -- Main.[[KitaeKim|KitaeKim]] - 09 Sep 2004\ |\ + +* | +|\ How about add supported Language List table in Homepage\ -- Main.[[KitaeKim|KitaeKim]] - 11 Sep 2004\ | in progress | |\ For using SCIM, there is XMODIFIERS`"@im`SCIM" GTK_IM_MODULES="scim need. Sometimes that different,"SCIM"\ + +* and "scim",make some confuse, how about both,XMODIFIERS`"@im`SCIM" and XMODIFIERS`"@im`scim",\ support? \ +-- Main.[[KitaeKim|KitaeKim]] - 13 Sep 2004\ |\ Comments: \ I am afraid this is impossible from within this project: the case sensitive nature of XMODIFIERS is decided by the Xlib, not scim-lib itself. \ -- Main.[[LiuCougar|LiuCougar]] - 19 Sep 2004\ | |Skim: dcop support and kommander GUI \ -- Main.[[LiuCougar|LiuCougar]] - 27 Sep 2004| | |scim-console-panel: like uim-fep \ -- Main.[[LiuCougar|LiuCougar]] - 27 Sep 2004| | |\ Is it possible to use the same instance of SCIM in multiple windows of an application without pressing Ctrl+Space for each? Personally I appreciate the way it works at the moment as a feature, which makes it possible to use different IMs in different windows at the same time, but maybe it's not for people who only use one input method. Is it feasible to add such an option to SCIM?\ -- Main.[[YukikoBando|YukikoBando]] - 17 Oct 2004\ | | + +-- Main.[[KitaeKim|KitaeKim]] - 18 Oct 2004 diff --git a/Software/ScimInstall.mdwn b/Software/ScimInstall.mdwn new file mode 100644 index 00000000..0753e0db --- /dev/null +++ b/Software/ScimInstall.mdwn @@ -0,0 +1,125 @@ +## Install + + +### Requirements + +The core components of scim-lib generally depends on ``NOTHING``: if you have a c++ compiler, you would be able to compile it. However should you prefer Gtk GUIs, then Gtk2 is required. scim-lib comes with several config modules, one of which is `gconf` config module: you would need gconf (which is depend on other Gnome2 packages) to compile and make use of it. + +(If you prefer KDE/Qt GUIs, then you would like to try [[Software.ScimKDE][skim|Software.ScimKDE][skim]].) + + +### Install scim-lib from source + +There are two choices to install scim-lib from source code: One is using released tarballs, the other is checking out from !CVS. The releases are relatively well tested and more stable, but may be a little outdated. The !CVS checkout is very bleeding-edge, but it's in heavy development, so more error-prone. + + +#### Install from releases + +After downloading and uncompressing the released tarballs: + + $ ./configure --prefix`/usr --sysconfdir`/etc + $ make + # make install + +If you don't use options in `configure`, SCIM is going to be installed in `/usr/local`. + + +#### Install from !CVS + +First, checkout the source from !CVS + + $ export CVS_RSH="ssh" + $ cvs -z3 -d:ext:anoncvs@savannah.nongnu.org:/cvsroot/scim checkout -P scim-lib + $ cd scim-lib + +After checking out the source: + + $ ./bootstrap + $ ./configure --prefix`/usr --sysconfdir`/etc + $ make + # make install + +If you prefer KDE, you can checkout [[Software.ScimKDE][skim|Software.ScimKDE][skim]], the procedure is just the same as above, you only need to replace scim-lib with skim. + + +#### Gentoo + +All the SCIM packages are included in the official portage, so all you have to do is + + # emerge scim + +If you want Pinyin (Simplified Chinese) input method, please emerge `scim-chinese`; If table based (including Simplified/Traditional Chinese, Japanese, Russian etc.) input method is prefered, please emerge `scim-table`; If you are the users of `[[Software.uim][UIM]]`, then `scim-uim` (and/or `scim-m17n`) is (are) what you want. + +(Do not forget to specify the `ACCEPT_KEYWORDS`"~x86"= before you emerge anything in SCIM if the latest versions are desired) + +If `-gtk` (and/or `-gnome`) is included in your `USE` variable, or *KDE/Qt* is prefered, then probably you should also emerge `[[Software.ScimKDE][skim]]`. + +-- Main.[[LiuCougar]] - 18 Jul 2004 + + +## Configure locales + +On many systems, it will also be necessary to configure the locales. + +For some versions of the locales package, you should edit the file (as user `root`) + + /etc/locale.gen + +and for at least locales version 2.3.18, you should edit such a file as + + /var/lib/locales/supported.d/zh + +(or "/jp", depending on the language) to include a locale and encoding appropriate for your purposes. For example, to use Simplified Chinese with Unicode encodings, insert the line + + zh_CN.UTF-8 UTF-8 + +See `/usr/share/i18n/SUPPORTED` for a list of locales supported on your system. + +Then create and install the locales in your system by running + + locale-gen + +See `man locale` for more information on locales. + + +## Environment + +If your system is set up for a language other than the target language, an application to be used with SCIM will need to run in an environment set up for the target language. + +For example, in a terminal running the `bash` shell, type + + export XMODIFIERS=@im=SCIM + export LC_CTYPE=zh_CN.UTF-8 + +Now if SCIM is running, you can run, say, `gedit` from this terminal session, and use SCIM within that application to type Simplified Chinese. + +To use the SCIM input methods in GTK applications (and in Gnome generally) + + export GTK_IM_MODULE=scim + +To use the SCIM input methods in Qt applications (KDE desktop) + + export QT_IM_SWITCHER=imsw-multi + export QT_IM_MODULE=scim + +Of course, one can simplify this process by writing scripts that set the environment and run the desired application at once. For example, put the following in a file named "chinese", and make the file executable, and put it in your `PATH`. + + #!/bin/bash + # Launches argument program in an environment appropriate to use + # with SCIM Chinese input method. Launches scim as daemon if it + # doesn't find it running. + export XMODIFIERS=@im=SCIM + export GTK_IM_MODULE=scim + export QT_IM_SWITCHER=imsw-multi + export QT_IM_MODULE=scim + export LC_CTYPE=zh_CN.UTF-8 + + scim_running=`ps cax | grep -c ' scim'` + + if [ $scim_running == 0 ]; then + scim -d + fi + + exec $@ + +Then for example the command `chinese gedit` will bring up gedit with everything set up properly. diff --git a/Software/ScimIntroduction.mdwn b/Software/ScimIntroduction.mdwn new file mode 100644 index 00000000..9f965ab1 --- /dev/null +++ b/Software/ScimIntroduction.mdwn @@ -0,0 +1,37 @@ + + +### What is SCIM? + +Smart Common Input Method platform, in short SCIM, is a development platform to make Input Method developer life easier. It honors a very clear architecture and provides a pretty simple and powerful programming interface. + + +### Why SCIM? + +There are many Input Method programs and platforms living in the world, such as XIM, IIIMF, UIM, kinput, XCIN, Chinput etc. Then why we do want another Input Method platform? + +First of all, SCIM is a common IM platform written in C++. It abstracts input method interface into several classes and try to make these classes as simple and independent as possible. With such simple interfaces, developers can write their own input method in a few lines code very easily. + +Second, SCIM is highly modularized: most components can be implemented as dynamically loadable modules, thus can be loaded at runtime as you wish. For example, input methods written for SCIM could be IMEngine modules, and users can use such IMEngine modules combined with different interface modules (FrontEnd) in different environment without rewrite/recompile the IMEngine modules. + +Third, SCIM is a higher level library comparing with XIM or IIIMF.It has much simpler interface than XIM and IIIMF. And it can work with XIM or even IIIMF (in the future). SCIM can also support client specific input method interface, like gtk2 immodule and [[qt immodule|http://immodule-qt.freedesktop.org/]]. + + +### Key features of SCIM: + + * Fully Object Oriented structure written in C++. + * Highly modularized. + * Very flexible architecture, can be used as a dynamically loaded library as well as a C/S input method environment. + * Simple programming interface. + * Fully i18n support with UCS-4/UTF-8 encoding. + * Include many handy utility functions to speedup the development. + * GUI Panel with very rich features. + * Unified configuration framework. + +### The goal of SCIM: + + * Act as an unified frontend for current available input method libraries. Currently bindings to uim and m17n library are available. + * Act as a language engine of IIIMF input method framework (TBD). + * Provide as many native IMEngines as possible. + * Support as many input method protocol/interface as possible. + * Support as many operating systems as possible. +-- Main.[[JamesSu|JamesSu]] - 18 Aug 2004 diff --git a/Software/ScimKDE.mdwn b/Software/ScimKDE.mdwn new file mode 100644 index 00000000..95d6b26b --- /dev/null +++ b/Software/ScimKDE.mdwn @@ -0,0 +1,77 @@ + +<img align`"right" src`"%ATTACHURLPATH%/skim_logo.png" alt="scim_log_ltt.png" /> +## Skim (SCIM for KDE) + + +### Introduction + +skim is an input method platform based upon scim-lib under *NIX systems (including [[GNU/Linux|http://www.gnu.org/gnu/the-gnu-project.html]] and [[FreeBSD|http://www.freebsd.org/]]) optimized for KDE. It provides a GUI panel (named scim-panel-kde), a KConfig config module and !SetupUIs for itself and scim-lib. It also has its own plugin system which supports on-demand loadable actions. +#### Features + + * KDE compliant: + * Default settings are retrieved from KDE and the GUI honors the KDE/Qt global styles, including but not limited to the apperances colors of widgets and icons; + * GUI language is determined by the KDE global setting, rather than LANG (or similar) environment variable, so no matter what your locale is, you can select preferrable user interface language. What's more, skim ships with a bunk of translations, currently including: (Simplified/Traditional) Chinese, French, German, Japanese and Korean; + * Fully KDE integration: if you close your KDE when skim is still running, next time you login KDE, skim will get loaded automatically; After installation of skim, you can start it from "KDE Menu->Utilitis->skim"; + * Fully customizable: a setup GUI is shipped with skim, in which you can modify all settings not only about skim but also SCIM and most the settings will take efforts immediately without the hassle of restart; + * Based on modular concept: nearly everything you see are in seperate plugins, so you can configure which one you want. Not specified plugins would not get loaded at all to save your memery; some temporary functions such as configuration dialogs will be loaded on-demand, and will be unloaded automatically when they are no longer needed; + * Object Oriented: like any other KDE/Qt application skim is written in C++. + +#### [[SkimScreenshots][Screenshots]] + +Everyone loves [[SkimScreenshots][screenshots|SkimScreenshots][screenshots]], don't they? ;) Please also have a look at [[The English skim Handbook|http://scim.sourceforge.net/skim/doc/user/en/#screenshots]] and [[The German skim Handbook|http://scim.sourceforge.net/skim/doc/user/de/]]. + + +#### Downloads + +---+++++ Skim-1.0.2 Source + + * [[Sourceforge|http://prdownloads.sourceforge.net/scim/skim-1.0.2.tar.bz2?download]] + * [[Freedesktop|http://freedesktop.org/~scim/skim/downloads/skim-1.0.2.tar.bz2]] +Previous versions are also available on [[Sourceforge|http://sourceforge.net/project/showfiles.php?group''id`108454&package''id`118018]]. ---+++++ Latest Source from [[CVS|http://savannah.nongnu.org/cgi-bin/viewcvs/scim/skim/]] + + * You can get the latest source for skim from [[CVS|http://savannah.nongnu.org/cgi-bin/viewcvs/scim/skim/]]: + + + cvs -z3 -d:ext:anoncvs@savannah.nongnu.org:/cvsroot/scim co skim + +---+++++ Gentoo + + * The [[skim ebuild|http://packages.gentoo.org/search/?sstring`skim]] is in the offical portage, so `emerge skim` will do all the work for you. (At present, you must specify the ACCEPT_KEYWORDS`"~x86" to emerge skim). +---+++++ !FreeBSD + + * If your !FreeBSD is 5.x version, then you can execute `pkg_add -r skim` to install it. Please see the [[details|http://www.freshports.org/textproc/skim]]. +---+++++ !Binaries for Various Distros | *Distro* | *Version* | *File* | *Extra Info* | | !SuSE | 9.1 | \ [[skim-1.0.2-1suse.i586.rpm|http://prdownloads.sourceforge.net/scim/skim-1.0.2-1suse.i586.rpm?download]] || | Mandrake | Cooker | \ [[UT Extra Packages for Mandrake|http://sourceforge.net/project/showfiles.php?group''id`109779&package''id`121561]] | src rpm only | | Magic | Latest | \ [[rpm|http://www.magiclinux.org/people/kanker/os/rpms/]] [[srpm|http://www.magiclinux.org/people/kanker/os/srpms/]] | All scim related packages | | Fedora | fc2 | \ [[skim-1.0.1-1fc2.i386.rpm|http://prdownloads.sourceforge.net/scim/skim-1.0.1-1fc2.i386.rpm?download]] || + +---++++Requirements + +``scim-lib`` >` 0.99.4, ``Qt`` >` 3.2.0 and ``KDE`` >= 3.2.0 are required to compile skim. + +*NOTICE*: After installing skim, you should also install at least an IMEngine (refer to a input method), such as ``scim-chinese`` (currently contains the Pinyin IMEngine for Simplified Chinese), ``scim-tables`` (contains table-based input methods, such as Wubi, Erbi for Simplified Chinese), ``scim-hangul`` (a popular Korean input method), ``scim-uim`` (contains a lot of Janpanese IMEngines) or ``scim-m17n`` (contains more than 30 input methods for various languages). + +---+++++Install (Binary) RPM + +If you want to use RPM directly, then please install RPMs for scim and skim. + +---+++++Compile from Source + +If you want to compile skim from source, then please make sure before compiling skim at least the RPMs for ``scim`` and ``scim-devel`` are installed. + +Otherwise, if scim-lib was compiled in your box, you have all necessary files. + +If you do not want Gtk2 based original GUI from scim-lib, you can disable them while configure it: after you compile it, you can still install skim. In a word, skim does not depend on original Gtk2 based GUI. + +The header files for Qt and KDE are also required to compile skim, which are normally included in libqt-devel and libkdecore-devel/libkdelibs-devel RPMs. + +---++++User Manual + + * [[End User Manual|http://scim.sourceforge.net/skim/doc/user]] for latest skim version. This manual is also installed in your system along with skim. You can access it from the "Help" action. +---++++[[skimRoadmap][Roadmap|skimRoadmap][Roadmap]] Roadmap (future plan) for skim can be found here. + +---++++Acknoledgement ---+++++Art Designer + + * kitae <neeum ZAI yahoo.com>: designer of skim logo and icon +---+++++Package Maintainer + + * Mamoru KOMACHI <usata ZAI gentoo.org>: maintainer of Gentoo skim ebuild. + * Jie Gao <gaoj ZAI cpsc.ucalgary.ca>: maintainer of !FreeBSD skim port. +-- Main.[[LiuCougar|LiuCougar]] - 13 Nov 2004 diff --git a/Software/ScimLinks.mdwn b/Software/ScimLinks.mdwn new file mode 100644 index 00000000..0c0404b8 --- /dev/null +++ b/Software/ScimLinks.mdwn @@ -0,0 +1,26 @@ + + +## SCIM related + + * [[Old SCIM Homepage|http://www.freedesktop.org/~suzhe/]] + * [[SCIM Project page|http://savannah.nongnu.org/projects/scim/]] + * [[SCIM Freshmeat record|http://freshmeat.net/projects/scim]] + * [[SCIM Sourceforge mirror|http://sourceforge.net/projects/scim]] (Only contains sources of packages) + +## Input Method Related + + * [[IIIMF|http://www.openi18n.org/subgroups/im/IIIMF/]] Internet/Intranet Input Method Framework. + * [[UIM|http://uim.freedesktop.org]] is a library to support input many languages. + * [[Qt-immodule|http://immodule-qt.freedesktop.org/]] Immodule support in Qt (in progress). +Come to join us to discuss [[what should be incorporated|http://www.kde.gr.jp/~daisuke/immodule''for''qt/pukiwiki/?ImmoduleForQt4RequirementsDocument]] into Qt4 in terms of built-in qt-immodule support. + + +## Other Input Method Implementation + + * [[gcin|http://www.csie.nctu.edu.tw/~cp76/gcin/]] (Chinese) is a traditional Chinese zhuyin input method. + * [[Qooing|http://jserv.sayya.org/wiki/index.php/Qooing]] (Chinese) is a library for chewing (similar to zhuyin) input method. + +## Other Things about Complex Input + + * [[Dead Keys Controversy|http://wauug.erols.com/~balsa/linux/deadkeys/]] provides information on using international character sets under Linux and particularly under [[X11R6|X11R6]]. +-- Main.[[LiuCougar|LiuCougar]] - 17 Jul 2004 diff --git a/Software/ScimNews.mdwn b/Software/ScimNews.mdwn new file mode 100644 index 00000000..35d13a50 --- /dev/null +++ b/Software/ScimNews.mdwn @@ -0,0 +1,56 @@ + + +## What's NEW + + +#### skim 1.0.2 released (10 Oct 2004) + + * Fixed bug [[#1042106|http://sourceforge.net/tracker/index.php?func`detail&aid`1042106&group_id`108454&atid`650539]]; + * Incorporated Qt-immodule related info in the English doc; + * Updated to support latest Intel compiler (icc/icpc); + * Other minor improvement. + +#### skim 1.0.1 released (28 Sep 2004) + + * New option in configure dialog: Autostart skim when KDE starts; + * Updated document; + * Display less candidates in the lookuptable window if it is too long. + +#### scim-lib 1.0.1 has been released (21 Sep 2004) + + * Added missing assignment for SCIM_BUILD_GTK_UTILS variable in configure.ac + * Call focus_out when turnning off input method in gtkimmodule. + * Fixed gtk2 binary compatibility issue. Now scim binary compiled against gtk2-2.2.x can be used with gtk2-2.4.x. + +#### scim-qtimm 0.7.5 released (17 Sep 2004) + + * Fixed a crash bug; + * Updated according to latest qt immodule patch (0910); + * New German translation; + * Other minor improvement. + +#### skim 1.0.0 released (08 Sep 2004) + + * New German document; + * New icons; + * Fixed/Enhanced the factory menu shortcut support; + * Updated English document; + * Other small improvement and cleanup. + +#### 3 new contributors join SCIM project (07 Sep 2004): + + * Main.[[JanHefti|JanHefti]]: Doc writer and German translator + * Main.[[KitaeKim|KitaeKim]]: Art designer and Korean translator + * Main.[[YukikoBando|YukikoBando]]: Japanese translator + +#### scim-qtimm first public version released (4 Sep 2004) + + * scim-qtimm 0.7 has implemented all the functionalities of its gtk counterpart. Currently there is one option for scim-qtimm which can be modified in the skim configuration dialog. + +#### scim-lib 1.0.0 has been released (4 Sep 2004) + + * Minor configure.ac improvement. + +### [[ScimNews200409][News before September 2004]] + +-- Main.[[LiuCougar|LiuCougar]] - 11 Oct 2004 diff --git a/Software/ScimQtImm.mdwn b/Software/ScimQtImm.mdwn new file mode 100644 index 00000000..7fa07f86 --- /dev/null +++ b/Software/ScimQtImm.mdwn @@ -0,0 +1,41 @@ + +<img align`"right" src`"%ATTACHURLPATH%/scim-qtimm.png" alt="scim-qtimm.png" /> +## scim-qtimm + + +### Introduction + +This is the [[Qt input module plugin|http://immodule-qt.freedesktop.org]] for SCIM. + +The latest version works with qt-immodule unified BC patch (including qt-x11-immodule-unified-qt3.3.3-20040910). + +**ATTENTION:** This should be treated as a beta quality software, so you have been warned ;) + +#### Downloads + +[[scim-qtimm-0.7.5.tar.bz2|http://prdownloads.sourceforge.net/scim/scim-qtimm-0.7.5.tar.bz2?download]] (Revision 87) + +[[Local Mirror|http://freedesktop.org/~scim/scim-qtimm/downloads/scim-qtimm-0.7.5.tar.bz2]] + +Or you can checkout the lastest revision from svn: + + svn co http://freedesktop.org:8080/svn/scim/scim-qtimm/trunk scim-qtimm + +The repository can also be browsed [[online|http://freedesktop.org:8080/svn/scim/scim-qtimm/trunk]]. + + +### Gentoo + +scim-qtimm can be installed just like any other packages: + + emerge scim-qtimm + +Make sure you have emerged the qt-3.3.0-r1 with qtimm-bc or qtimm in the USE flag before emerging scim-qtimm. + + +### !Mandrake Cooker + +* SRC RPM for Mandrake Cooker can be downloaded from the project [[UT Extra Packages for Mandrake|http://sourceforge.net/project/showfiles.php?group''id`109779&package''id`121561]]. + +-- Main.[[LiuCougar]] - 19 Sep 2004 + diff --git a/Software/ScimReportBug.mdwn b/Software/ScimReportBug.mdwn new file mode 100644 index 00000000..5d5b7d84 --- /dev/null +++ b/Software/ScimReportBug.mdwn @@ -0,0 +1,31 @@ + + +## Reporting Bug + +If you want to ask for help or send bug reports, please use the [[Bugzilla|http://bugs.freedesktop.org/]] and select scim as the product or ask in the SCIM official [[mailing list|http://freedesktop.org/mailman/listinfo/scim]]. In addition to the infomation asked in the bugzilla, please also be sure to include these information in your mail: + + +#### Your system distribution + +Please specify the exact distribution and version of your system (for example, Fedora Core 2, SUSE LINUX Enterprise Server 9, Mandrake 10.0, Debian Sarge, etc.). If you have any unofficial packages installed, it is also good to tell us. The packages especially related to SCIM includes GTK+, g++ (if you built from source), Qt and KDE (if you use skim and/or qt-immodule). + + +#### How you installed SCIM + +Please tell us if you built from source or installed binary packages. + +If you built SCIM from source, please tell the tarball version (or !CVS), and the command you used to install SCIM. The [[ScimInstall][installation instructions|ScimInstall][installation instructions]] are recommended, and if you used something different, be sure to say so! + +If you installed pre-built binary packages, please tell which packages you used, especially if they are not from this site. It would be also good to tell us the command (or actions, if you used some GUI package tool) you installed these binary packages. + + +#### Your desktop environment + +If SCIM installed fine but you can't invoke it, most likely you are having something wrong with your desktop environment. Please send these information with your report: Your locale (paste the output of command `locale` is sufficient), your desktop enviroment (GNOME, KDE, etc.), the value of the environment variables $XMODIFIERS and $GTK_IM_MODULE. + + +#### How you started SCIM + +It is also important to tell us how you started SCIM on your system -- whether you run the commands by hand, or put them in some config file. Please tell exact what command you used, and which file you put them in. + +-- Main.[[LiuCougar|LiuCougar]] - 19 Aug 2004 diff --git a/Software/ScimRoadmap.mdwn b/Software/ScimRoadmap.mdwn new file mode 100644 index 00000000..945be377 --- /dev/null +++ b/Software/ScimRoadmap.mdwn @@ -0,0 +1,32 @@ + + +## Roadmap for SCIM project + + +### SCIM 1.0 + +All features for 1.0 are available, official 1.0 version is released(4 Sep 2004). + + +### SCIM 1.5 + + * Generic reverse lookup support between (Chinese) IMEngines; + * Automatic online Simplified Chinese <-> Traditional Chinese transform support (transparent to IMEngines); + * Support for exporting/importing user defined phrases; + * API/GUI for editing user-defined phrases; + * API/GUI for creating user-defined table-based input method (as the one shipped with Windows); + * [[Linux Registry|http://registry.sourceforge.net/]] config module; + * [[DOAP|http://usefulinc.com/doap/]] description. + +### SCIM 2.0 + + * Complete multi-user support; + * Console Frontend; + * Split Gtk/Gnome related components into a separate packages. + +### SCIM Future + + * Context sensitive keyboard layout switch; + * Each IMEngine can have a default keyboard layout; + * Pure XML based configure interface support. +-- Main.[[KitaeKim|KitaeKim]] - 09 Sep 2004 diff --git a/Software/ScimScreenShots.mdwn b/Software/ScimScreenShots.mdwn new file mode 100644 index 00000000..962f430a --- /dev/null +++ b/Software/ScimScreenShots.mdwn @@ -0,0 +1,89 @@ + + +## Screen Shots + +People always like these :-) + + * [[[#SimplifiedChineseEnv|[]][Simplified Chinese Environment]] + * [[[#KoreanEnv|[]][Korean Environment]] + * [[[#JapaneseEnv|[]][Japanese Environment]] + + +--- + + + + +### Simplified Chinese Environment + +#[[SimplifiedChineseEnv|SimplifiedChineseEnv]] + + * Input methods menu in Chinese.: <br /> + * <img src`"%ATTACHURLPATH%/zh-menu-1.jpg" alt`"zh-menu-1.jpg" width`"840" height`"999" /> + * Pinyin input method for Simplified Chinese: <br /> + * <img src`"%ATTACHURLPATH%/zh-pinyin-1.jpg" alt`"zh-pinyin-1.jpg" width`"801" height`"600" /> + * [[ZhuYin|ZhuYin]] input method for Traditional Chinese: <br /> + * <img src`"%ATTACHURLPATH%/zh-zhuyin-1.jpg" alt`"zh-zhuyin-1.jpg" width`"801" height`"600" /> + * Anthy input method for Japanese: <br /> + * <img src`"%ATTACHURLPATH%/zh-anthy-1.jpg" alt`"zh-anthy-1.jpg" width`"801" height`"600" /> + * Hangul input method for Korean: <br /> + * <img src`"%ATTACHURLPATH%/zh-hangul-1.jpg" alt`"zh-hangul-1.jpg" width`"801" height`"600" /> + * Splash page of setup tool: <br /> + * <img src`"%ATTACHURLPATH%/zh-setup-1.jpg" alt`"zh-setup-1.jpg" width`"640" height`"468" /> + * Input method enable/disable page: <br /> + * <img src`"%ATTACHURLPATH%/zh-setup-2.jpg" alt`"zh-setup-2.jpg" width`"657" height`"502" /> + * Hangul module setup page: <br /> + * <img src`"%ATTACHURLPATH%/zh-setup-3.jpg" alt`"zh-setup-3.jpg" width`"657" height`"502" /> + * Pinyin module setup page: <br /> + * <img src`"%ATTACHURLPATH%/zh-setup-4.jpg" alt`"zh-setup-4.jpg" width`"657" height`"502" /> + * Table module setup page: <br /> + * <img src`"%ATTACHURLPATH%/zh-setup-5.jpg" alt`"zh-setup-5.jpg" width`"657" height`"502" /> + * GTK panel setup page: <br /> + * <img src`"%ATTACHURLPATH%/zh-setup-6.jpg" alt`"zh-setup-6.jpg" width`"657" height`"502" /> + * X11 FrontEnd setup page: <br /> + * <img src`"%ATTACHURLPATH%/zh-setup-7.jpg" alt`"zh-setup-7.jpg" width`"657" height`"502" /> + + +--- + + + + +### Korean Environment + +#[[KoreanEnv|KoreanEnv]] + + * Setup tool: <br /> + * <img src`"%ATTACHURLPATH%/ko-setup-1.jpg" alt`"ko-setup-1.jpg" width`"934" height`"672" /> + * Hangul input method: <br /> + * <img src`"%ATTACHURLPATH%/ko-hangul-1.jpg" alt`"ko-hangul-1.jpg" width`"774" height`"732" /> + + +--- + + + + +### Japanse Environment + +#[[JapaneseEnv|JapaneseEnv]] + + * X11 [[FrontEnd|FrontEnd]] setup and Japanese input method: <br /> + * <img src`"%ATTACHURLPATH%/ja-anthy.png" alt`"ja-anthy.png" /> + * GTK panel setup and Japanese input method: <br /> + * <img src`"%ATTACHURLPATH%/ja-skk.png" alt`"ja-skk.png" /> + + + + + + + + + + + + + + + diff --git a/Software/ScimSupportLanguage.mdwn b/Software/ScimSupportLanguage.mdwn new file mode 100644 index 00000000..f7263ebb --- /dev/null +++ b/Software/ScimSupportLanguage.mdwn @@ -0,0 +1,64 @@ + + +## SCIM supported language list + +This page is under construction and not all scim supported languages are listed. + + +### Language Table +[[!table header="no" class="mointable" data=""" +**Language** | **Package Name** | **Support Version** | **Input Method** | **current status** | **Extra Info** + **Amharic** | [[scim-m17n|Software/ScimM17N]] | 0.1.3 | am-sera | good | + | [[scim-tables|Software/ScimTables]] | 0.4.3 | amharic | good | + **Arabic** | [[scim-m17n|Software/ScimM17N]] | 0.1.3 | ar-kbd | good | Egypt + **Assamese** | [[scim-m17n|Software/ScimM17N]] | 0.1.3 | as-itrans | well | + **Bengali** | [[scim-m17n|Software/ScimM17N]] | 0.1.3 | bn-itrans | good | + **Cambodian** | [[scim-m17n|Software/ScimM17N]] | 0.1.3 | km-yannis | good | + **Chinese** | [[scim-chinese|Software/ScimChinese]] | 0.4.2 | smart-pinyin | best | simplified + | [[scim-m17n|Software/ScimM17N]] | 0.1.3 | zh-py | not bad | simplified + | [[scim-tables|Software/ScimTables]] | 0.4.3 | santonese-pinyin, erbi, erbi-QS, wubi, ziranma | good | simplified + | [[scim-tables|Software/ScimTables]] | 0.4.3 | array30, cangjie-5, dayi3, ez, jyutping, simplex, zhuyin | good | traditional + | [[scim-uim|Software/ScimUim]] | 0.1.2 | py, pyunihan, pinyin-big5 | good | simplified + **Croatian** | [[scim-m17n|Software/ScimM17N]] | 0.1.3 | hr-kbd | good | + **English** | [[scim-m17n|Software/ScimM17N]] | 0.1.3 | en-ispell | good | support spell check + **Greek** | [[scim-m17n|Software/ScimM17N]] | 0.1.3 | el-kbd | good | + **Gujarati** | [[scim-m17n|Software/ScimM17N]] | 0.1.3 | gu-itrans | good | + **Hebrew** | [[scim-m17n|Software/ScimM17N]] | 0.1.3 | he-kbd | good | + **Hindi** | [[scim-m17n|Software/ScimM17N]] | 0.1.3 | hi-itrans | good | + **Japanese** | [[scim-uim|Software/ScimUim]] | | tcode, anthy, prim, turcode, skk | best | + | [[scim-m17n|Software/ScimM17N]] | 0.1.3 | tcode | not-bad | + | [[scim-tables|Software/ScimTables]] | 0.4.3 | hiragana, katakana, nippon | | + **Kannada** | [[scim-m17n|Software/ScimM17N]] | 0.1.3 | kn-itrans | good | + **Kazakh** | [[scim-m17n|Software/ScimM17N]] | 0.1.3 | kk-arabic | good | + **Korean** | [[scim-hangul|Software/ScimHangul]] | 0.1.2 | 2bul, 3bul-390, 3bul-Final, 3bul-No-shift, 3bul-yetgeul | best | + | [[scim-m17n|Software/ScimM17N]] | 0.1.2 | 2bul | not bad | + | [[scim-tables|Software/ScimTables]] | 0.4.3 | 2bul | not bad | + | [[scim-uim|Software/ScimUim]] | 0.1.2 | 2bul, 3bul 390, romaja | not bad | romaja using the Korean syllables + **Laothian** | [[scim-m17n|Software/ScimM17N]] | 0.1.3 | lo-lrt | good | + **Malayalam** | [[scim-m17n|Software/ScimM17N]] | 0.1.3 | ml-itrans | good | + **Oriya** | [[scim-m17n|Software/ScimM17N]] | 0.1.3 | or-itrans | good | + **Panjabi** | [[scim-m17n|Software/ScimM17N]] | 0.1.3 | pa-itrans | good | + **Persian** | [[scim-m17n|Software/ScimM17N]] | 0.1.3 | fa-isiri | good | + **Russian** | [[scim-m17n|Software/ScimM17N]] | 0.1.3 | ru-yawerty | good | + | [[scim-tables|Software/ScimTables]] | 0.4.3 | Yawerty | good | + **Tibetan** | [[scim-m17n|Software/ScimM17N]] | 0.1.3 | bo-wylie | good | + **Serbian** | [[scim-m17n|Software/ScimM17N]] | 0.1.3 | sr-kbd | good | + **Slavak** | [[scim-m17n|Software/ScimM17N]] | 0.1.3 | sk-kbd | good | + **Thai** | [[scim-m17n|Software/ScimM17N]] | 0.1.3 | th-kesmanee | good | + **Tamil** | [[scim-m17n|Software/ScimM17N]] | 0.1.3 | ta-itrans | good | + **Telugu** | [[scim-m17n|Software/ScimM17N]] | 0.1.3 | te-itrans | good | + **Vietnamese** | [[scim-m17n|Software/ScimM17N]] | 0.1.3 | vi-telenx, vi-viqr | good | + | [[scim-uim|Software/ScimUim]] | 0.1.2 | vi-viqr | good | +"""]] + + +### Other Input Method Table +[[!table header="no" class="mointable" data=""" +**Input Method** | **Package Name** | **Support Version** | **current status** | **Extra Info** + t-latin-post | [[scim-m17n|Software/ScimM17N]] | 0.1.3 | good | + t-unicode | [[scim-m17n|Software/ScimM17N]] | 0.1.3 | good | + ipa | [[scim-uim|Software/ScimUim]] | 0.1.2 | good | + raw code | [[SCIM|Software/scim]] | 1.0.0 | good | +"""]] + +-- [[KitaeKim|KitaeKim]] - 14 Sep 2004 diff --git a/Software/ScimSupportLanguageNewM17n.mdwn b/Software/ScimSupportLanguageNewM17n.mdwn new file mode 100644 index 00000000..7f3fb644 --- /dev/null +++ b/Software/ScimSupportLanguageNewM17n.mdwn @@ -0,0 +1,101 @@ +# How to create a new IME on Linux in about 15 minutes with SCIM and m17n + + +## Introduction + +SCIM already supports many languages. It is easy to use, you just click on it's icon on the taskbar, select the one you want to use and start writing. Your input appears in your web browser's input fields, mail program or general purpose editor. But what happens if SCIM does not have an input method that you need? The reasons for this can be different - maybe your language is just not supported (ex. you are using some exotic African language), maybe you are a scholar and want to use some strange transcription, or maybe you are just a creative person and want to have something tailored for your needs (ex. you need a special input method for the language of your own). + +With SCIM, you can easily create your own input methods, and you do not necessarily have to be a programmer to do this, though you can achieve more spectacular results if you are one. In this article I am proposing to extend m17n database. If you are using scim-m17n, your extension will be read in when SCIM restarts and you will be able to use your own input method in all the programs supported by SCIM. + +This is not the only way to achieve this result, I will describe alternative solutions in future articles. + + +## Specification of the problem + +I am creating a webpage about languages. I would like to input transcription of foreign words in International Phonetic Alphabet. The problem is that I do not have IME for this. Quick search shows, that such IME exists in UIM, but I do not use it with SCIM. Searching the web I found information about SAMPA and X-SAMPA. Looking further I came to this webpage: [[http://www.theiling.de/ipa/cxs.html|http://www.theiling.de/ipa/cxs.html]] It describes a variant of X-Sampa used on Conlang Mailing List. I decided this is what I needed. I would like to write in Sampa, and get IPA in the document. + + +## The approach to the solution + +As we look at the problem, we see that we want some characters be substituted by other characters. For example, "&" should input "æ". But this is not all. Sometimes other characters following the given one can modify it. For example, "@" should be substituted by "ə", but if we write "@\", we want to get "ɘ", and "@`" should be substituted by "ɚ". Such modifing strings can be longer. + +The similar problem is solved in Vietnamese VIQR and latin-post input methods, available in scim-m17n. Scim-m17n is using m17n library as the backend. If we make m17n support our new input method, SCIM will use it as well. + + +## Technical documentation + +If you want to understand what you will be doing, you should read the documentation of m17n. This is not necessary in the very beginning, and I suggest that you first create your first simple input method, then read more. + +This is the main page of the m17n-lib and m17n-db: [[http://www.m17n.org/m17n-lib/|http://www.m17n.org/m17n-lib/]] + +This page describes the format of input method data: [[http://www.m17n.org/m17n-lib/m17n-docs/m17nDBFormat.html#mdbIM|http://www.m17n.org/m17n-lib/m17n-docs/m17nDBFormat.html#mdbIM]] + +This page provides short explanations for each input method: [[http://www.m17n.org/m17n-lib/m17n-docs/m17nDBData.html#mim-list|http://www.m17n.org/m17n-lib/m17n-docs/m17nDBData.html#mim-list]] + + +## OK, let us do it! + +When we create a new XXX.mim file (our input method), we put it under the directory where the m17n-db is installed (usually, `/usr/share/m17n` or `/usr/local/share/m17n`). We have to edit the file mdb.dir in the same directory and add this line: + +`(input-method LL NAME "XXX.mim")` + +LL is a two letter language code of ISO639-1 (e.g. "vi" is for Vietnamese), NAME identifies the input method. + +Let us open mdb.dir file and register new table (the last entry is the new one): + + ... + (input-method vi telenx "vi-telex.mim") + (input-method vi viqr "vi-viqr.mim") + (input-method zh py "zh-py.mim") + (input-method t latin-post "latin-post.mim") + (input-method t unicode "unicode.mim") + (input-method t x-sampa "x-sampa.mim") + ... + +As you can see, I decided to name my input table ``x-sampa``. I followed the example of `latin-post`, as it's purpose is very similar to what I try to create. We have to create the *.mim file: + + touch /usr/share/m17n/x-sampa.mim + +A quick look inside `latin-post.mim` shows what do we have to enter in `x-sampa.mim` : + + ;;; <li> x-sampa.mim + ;;; + ;;; Modified X-Sampa Used on the Conlang Mailing List. + + (title "x-sampa") + + (map + (trans + + ("''0" 0x030A) ("''0\\" 0x0325) + ("&" 0x00E6) + ("|\\" 0x01C0) + ("|\\|\\" 0x01C1) + + ... + + ("z\\" 0x0291) + ("Z" 0x0292) + ("Z_j" 0x0293) + + )) + + (state + (init + (trans))) + +That is all. We just have to check whether our IME is working. The easiest way is to start ``medit``, select our new input method and make sure it works as expected. + + +## Final step + +The only thing we still have to do is to restart SCIM (I just reboot my computer, but restarting X Windows should be enough). That's it! + + +## Thanks + +I would like to thank Mr Kenichi Handa from m17n project for his kind help during my own struggle with this simple problem. + +-- Main.[[JanuszPrusaczyk]] - 06 Oct 2004 + + * [[%ATTACHURL%/x-sampa.mim][x-sampa.mim|%ATTACHURL%/x-sampa.mim][x-sampa.mim]]: CXS IME for m17n-lib diff --git a/Software/ScimSupportLanguageNewTable.mdwn b/Software/ScimSupportLanguageNewTable.mdwn new file mode 100644 index 00000000..2e4d2aa3 --- /dev/null +++ b/Software/ScimSupportLanguageNewTable.mdwn @@ -0,0 +1,178 @@ +# How to create a new IME in about 15 minutes with SCIM and scim-tables + + +## Introduction + +There are many input methods available in SCIM. But sometimes we may need something special - maybe you want to input cuneiform, Tangut, Jurchen, Rongo Rongo or Tocharian. You will not find IMEs for these languages (at least now. I guess it will change in the future :-) ) Another reason can be your desire to input a supported language more conveniently. If you you use English keyboard and are not a native speaker, the existing IMEs may not be convenient for you at all. Yet another example: maybe you came up with a proposition of a new transcription for an existing language (I know this happened with Cantonese) and want to use it in IME on your own computer. + +I assume that your system already supports the language you need IME for, ie. there is some standard of encoding, you have fonts and generally programs on your system handle the data in your target language, you just lack suitable IME. + +With SCIM, you can create a table based input method without programming. We are going to use scim-tables IME engine. + + +## Specification of the problem + +Let us assume that we want to modify existing Korean IME to allow input using transcription (similar to Chinese pinyin input). It is more convenient for non-native speaker with English keyboard. + + +## It is easier with a simple project + +We can save ourselves effort by creating a simple project with a makefile. I mean, it saves effort if we continue to work on one or more input tables. I did create a project, you do not have to follow my example. It is not worth the effort for one-time job, but if you want to spend some time editing your tables, I suggest you to create a project. + +First, we create a directory structure (yours can be different, but then you will have to modify makefile): + + mkdir tables + cd tables + touch Makefile + mkdir bin + mkdir icons + mkdir src + +My `Makefile` looks like this (I have three tables in the `./src` right now): + + SCIM''TABLES''DIR=/usr/share/scim/tables + SCIM''ICONS''DIR=/usr/share/scim/icons + + SRC_DIR=./src + BIN_DIR=./bin + ICON_DIR=./icons + + SCIM''MAKE''TABLE=scim-make-table + + compile: compile-korean compile-Viqr compile-akkadian + + compile-ko-latin: $(BIN_DIR)/korean.bin + compile-Viqr: $(BIN_DIR)/Viqr.bin + compile-akkadian: $(BIN_DIR)/akkadian.bin + + install: install-korean install-Viqr install-akkadian + uninstall: uninstall-korean uninstall-Viqr uninstall-akkadian + + install-korean: compile-korean + cp $(BIN''DIR)/korean.bin $(SCIM''TABLES_DIR) + cp $(ICON''DIR)/korean.png $(SCIM''ICONS_DIR) + + uninstall-korean: + rm $(SCIM''TABLES''DIR)/korean.bin + rm $(SCIM''ICONS''DIR)/korean.png + + install-Viqr: compile-Viqr + cp $(BIN''DIR)/Viqr.bin $(SCIM''TABLES_DIR) + cp $(ICON''DIR)/Viqr.png $(SCIM''ICONS_DIR) + + uninstall-Viqr: + rm $(SCIM''TABLES''DIR)/Viqr.bin + rm $(SCIM''ICONS''DIR)/Viqr.png + + install-akkadian: compile-akkadian + cp $(BIN''DIR)/akkadian.bin $(SCIM''TABLES_DIR) + cp $(ICON''DIR)/akkadian.png $(SCIM''ICONS_DIR) + + uninstall-akkadian: + rm $(SCIM''TABLES''DIR)/akkadian.bin + rm $(SCIM''ICONS''DIR)/akkadian.png + + clean: + rm -f $(BIN_DIR)/* + + $(BIN''DIR)/korean.bin: $(SRC''DIR)/korean.txt.in + sed -e 's,@SCIM''ICONDIR@,$(SCIM''ICONS''DIR),g' $(SRC''DIR)/korean.txt.in > $(BIN_DIR)/korean.txt + $(SCIM''MAKE''TABLE) $(BIN''DIR)/korean.txt -b -o $(BIN''DIR)/korean.bin + rm $(BIN_DIR)/korean.txt + + $(BIN''DIR)/Viqr.bin: $(SRC''DIR)/Viqr.txt.in + sed -e 's,@SCIM''ICONDIR@,$(SCIM''ICONS''DIR),g' $(SRC''DIR)/Viqr.txt.in > $(BIN_DIR)/Viqr.txt + $(SCIM''MAKE''TABLE) $(BIN''DIR)/Viqr.txt -b -o $(BIN''DIR)/Viqr.bin + rm $(BIN_DIR)/Viqr.txt + + $(BIN''DIR)/akkadian.bin: $(SRC''DIR)/akkadian.txt.in + sed -e 's,@SCIM''ICONDIR@,$(SCIM''ICONS''DIR),g' $(SRC''DIR)/akkadian.txt.in > $(BIN_DIR)/akkadian.txt + $(SCIM''MAKE''TABLE) $(BIN''DIR)/akkadian.txt -b -o $(BIN''DIR)/akkadian.bin + rm $(BIN_DIR)/akkadian.txt + +It generally means that if I am in the `tables` directory and run `make` command, it will generate source files with correct icon path in `./bin` directory (the `.in` extension gets cut off), and compile it afterwards. For example in case of Korean table the compile command looks like this: `scim-make-table ./bin/korean.txt -b -o ./bin/korean.bin` . The binary table will be written to `./bin` directory. If I update one file, for example `korean.txt.in`, I do not need to compile and reinstall everything. In this case I use command `make install-korean`. This command will first compile the updated table, and install it afterwards. + +The installation is equal to copying the binary table and icon to correct locations: + + cp ./bin/korean.bin /usr/share/scim/tables + cp ./icons/korean.png /usr/share/scim/icons + +I can also do `make uninstall-korean`. Another command, `make clean` clears the `./bin` directory. + + +## Let us finally begin + +The first thing that we need is an icon. Mine is korean.png and I put it in `./icons` directory. Remember, it will be copied to `/usr/share/scim/icons`. You may as well put it directly in this location. + +Now we need the source of the table. As we just modify existing table, we copy the source of the table that we modify. It is in scim-tables sources. + + cp /dat/src/cpp/scim/scim-tables-0.4.3/ko/Hangul.txt.in ./src + mv ./src/Hangul.txt.in ./src/korean.txt.in + +We need UUID for our new input: + + $ uuidgen + ec1343c3-cd84-421c-b653-fd4793759e6c + +We open `./src/korean.txt.in` in our favourite text editor and make necessary corrections. + +First, we change UUID line to: + + UUID = ec1343c3-cd84-421c-b653-fd4793759e6c + +We also update serial number, icon location and input name: + + SERIAL_NUMBER = 20041005 + ICON = @SCIM_ICONDIR@/korean.png + NAME = Korean + +This is enough to compile and install the table ( `make && make install` ). Now is your part - modify the table data and do not forget to update MAX_KEY_LENGTH value after that. + +Sometimes we start the table from scratch. In these cases it may help to generate the dummy table of characters to begin your work with. I do it with Perl - it saves me time. For example, I am going to start work on an latin prefix notation table to allow input of latin accented characters. The script I used to generate the raw table to begin my work with was: + + #!/usr/bin/perl + + # Basic + for my $char (0x0021 .. 0x007e) { + print "x", sprintf("%x",$char), "\t", pack('U',$char), "\t0\n"; + } + + # Suplement + + for my $char (0x00A1 .. 0x00ff) { + print "x", sprintf("%x",$char), "\t", pack('U',$char), "\t0\n"; + } + + # Extended A + + for my $char (0x0100 .. 0x017f) { + print "x", sprintf("%x",$char), "\t", pack('U',$char), "\t0\n"; + } + + # Extended B + + for my $char (0x0180 .. 0x0236) { + print "x", sprintf("%x",$char), "\t", pack('U',$char), "\t0\n"; + } + + # Extended Additional + + for my $char (0x1e00 .. 0x1ef9) { + print "x", sprintf("%x",$char), "\t", pack('U',$char), "\t0\n"; + } + +This script prints the table to `STDIN`. We save it by redirecting it's output to a file, like this: `./latintab.pl > latin.txt`. + +When you are ready with your input tables, type this command in your project directory: + + make install + +## Final word + +You have to restart SCIM to load (or reload) your table. It makes testing difficult. + +I did not test much this approach. I just describe what worked for me. Good luck! + +-- Main.[[JanuszPrusaczyk]] - 06 Oct 2004 + + * [[%ATTACHURL%/Korean.txt][Korean.txt|%ATTACHURL%/Korean.txt][Korean.txt]]: Korean input using latin transcription diff --git a/Software/TinderboxWiki.mdwn b/Software/TinderboxWiki.mdwn new file mode 100644 index 00000000..ecf45473 --- /dev/null +++ b/Software/TinderboxWiki.mdwn @@ -0,0 +1,198 @@ +## Tinderbox + +The concept of a tinderbox originated with the [[Mozilla|http://www.mozilla.org]] project, where it is extensively used to continually monitor the state of the development tree on [[many platforms|http://tinderbox.mozilla.org/showbuilds.cgi?tree=SeaMonkey]] simultaneously. + +It consists of a server and one or more clients. The server maintains the uploaded logs of builds and generates from a database the results of those builds on a constant basis, so a developer can see almost immediately if they have broken a build on some platform by a check-in. It is worth looking at the [[Mozilla tinderbox|http://tinderbox.mozilla.org/showbuilds.cgi?tree=SeaMonkey]] and understand all it can do. It may motivate you to help complete setting up tinderbox on freedesktop.org. + +The tinderbox allows a developer to quickly: + +* see if checked in changes break a build on some platform. +* examine the log of the build for errors; logs are uploaded to the server about every 30 seconds during a build. +* attach explanitory comments to a build. + +If the tree did not build on a client, you'll see by the red of its box for a build, and if it's most recently completed build failed, the column will be "flaming": the tree is on fire. + +Tinderbox is a set of perl scripts, and runs on Linux, Unix, !OS/X, and Microsoft Windows. + + +### Etiquette + +Breaking the build is unfriendly. And the tinderbox comes with an obligation to not break your co-collaborator's builds on other platforms. + +Please perform significant check-ins early in the day whenever possible, and watch the tinderbox until you have "green" on all major platforms. It is unfriendly to do check-ins and leave town, or leave the source tree in an unbuildable state for any longer than absolutely necessary. Reverting changes that break builds is good practice if you can't get the problem straightened out in a timely fashion. + + +### Freedesktop.org tinderboxes + +New tinderboxes are easy to establish via [[the admin interface|http://tinderbox.anholt.net/tinderbox3/admin.pl]] and [[tinderbox.anholt.net|http://tinderbox.anholt.net]] is the current tinderbox being used by the monolithic Xorg distribution testing. The trees currently supported are + +* [[xorg|http://tinderbox.anholt.net/tinderbox3/showbuilds.pl?tree=xorg]] - the Xorg modular code base +* [[XMonolithic|http://tinderbox.anholt.net/tinderbox3/showbuilds.pl?tree=XMonolithic]] - the Xorg monolithic code base +* [[cairo|http://tinderbox.anholt.net/tinderbox3/showbuilds.pl?tree=cairo]] - the [[cairo|http://www.cairographics.org/]] cairo vector graphics library +* [[liboil|http://tinderbox.anholt.net/tinderbox3/showbuilds.pl?tree=liboil]] - the [[liboil|http://liboil/freedesktop.org/]] liboil optimized inner loops library. +* [[kaffe|http://tinderbox.anholt.net/tinderbox3/showbuilds.pl?tree=kaffe]] - the [[kaffe|http://www.kaffe.org/]] Java VM +* [[psas|http://tinderbox.anholt.net/tinderbox3/showbuilds.pl?tree=psas]] - [[Portland State Aerospace Society|http://psas.pdx.edu/]]'s open-source rocket flight computer + +Let [[EricAnholt]] know if you think a tinderbox would be useful for your project. + + +### CVS access to the tinderclient + +You can either use your freedesktop.org account and SSH or use anonymous CVS with: + + $ cvs -d :pserver:anoncvs@cvs.freedesktop.org:/cvs/sysadmin login + CVS password: <hit return> + $ cvs -d :pserver:anoncvs@cvs.freedesktop.org:/cvs/sysadmin co tinderclient + +Browse CVS with [[View CVS|http://cvs.freedesktop.org/sysadmin/]]. + + +### Required software: xorg + +* FreeBSD: + * p5-libwww + * ccache + * freetype2 + * fontconfig + * pkgconfig + * gnu-automake + * gnu-libtool + * libpng +* debian: + * build-essential + * bison + * flex + * zlib1g-dev + * libpam0g-dev + * libfreetype6-dev + * libpng12-dev + * automake1.8 + * autoconf + * pkg-config + * libtool + * ccache + * libwww-perl + * libfontconfig1-dev + * cvs + * netkit-rsh (for xsm) + +### Required software: XMonolithic + +* FreeBSD: + * p5-libwww + * ccache (recommended) +* (debian:) + * build-essential + * bison + * flex + * zlib1g-dev + * libpam0g-dev + * libexpat-dev + * libfreetype6-dev + * libpng12-dev + +### Required software: cairo + +* FreeBSD: + * p5-libwww + * ccache + * fontconfig + * freetype2 + * pkgconfig + * gnu-automake + * gnu-libtool + * libpng + * glitz (recommended) + * librsvg (recommended) + * poppler (recommended) + * svg2png (recommended) + * ghostscript-gnu (recommended) + +### Required software: liboil + +* FreeBSD: + * p5-libwww + * ccache + * pkgconfig + * gnu-automake + * gnu-libtool + * gtk-doc + +### Required software: kaffe + +* FreeBSD: + * p5-libwww + * gmake + * libart2 + * esound + * zip + * libgmp + * gtk20 + * jikes + * ccache (recommended) + +### Required software: psas + +* FreeBSD: + * gmake + * ccache (recommended) + +### Tinderclient Installation + +Installing a client is very easy. + +* find some machine you don't mind keeping busy with sufficient disk space. +* download the current tinderclient scripts from CVS. I make no guarantees about whether CVS is necessarily sane, though if you are going to work on the scripts themselves, you should work from the CVS version of the scripts. +* If using kaffe, comment the XMonolithic command line in run-client.sh and uncomment the kaffe one. +* choose a short machine id for the build (so you don't use too much column space) which is useful to identify the machine/OS version you are running it on. Please use the format name-architecture (for example, anholt-i386 --[[EricAnholt]]). +* run "run-client.sh machine-id >& /dev/null". By default, the tinderclient tee's its output to a tinderclient.log file and standard output, so once you are up and running, you probably don't want to have it blathering on the screen constantly. +* If you'd like to have your build use ccache or jikes if you have them installed, get [[EricAnholt]] to fix up your machine configuration. ccache cuts build times in approximately half. jikes cuts kaffe builds down even more. +* add an option to do a lndir'ed tree, to shorten the log of all the synthesized files. +* if installing on OS X/Darwin you will need to create a link from gnumake to gmake 'ln -s /usr/bin/gnumake /usr/bin/gmake' +* if tindering the xorg modular tree, you must copy xorg-macros.m4 from util/macros/ to /usr/share/aclocal, or your builds will all fail really really miserably. + +The script will create a directory of the tree's name in whatever directory you are in when you run "run-client", and do a CVS checkout and build of the module specified in the tinderbox itself in a subdirectory of that. Once a day, it is supposed to do a "clobber" build, where the entire directory is deleted and the files checked out fresh, and performs a "make World". Once the initial build is complete, the script we use (confusingly also called !XMonolithic) will do just do a cvs update and another make, rather than a "make -k World". + +Since CVS is so broken, the xorg and probably XMonolith trees now always clobber, and never cvs up. You probably want to keep a mirror: start keeping one with rsync, and bug [[EricAnholt]] to change your config; especially if you're running multiple clients. + +One way to run this is to place them in a detached screen: + + # screen -d -m ./run-client.sh somebody-i386 + +You can then review and re-attach to them as follows: + + # screen -list + There is a screen on: + 20464.pts-5.cl012 (Detached) + 1 Socket in /var/run/screen/S-root. + + # screen -r 20464.pts-5.cl012 + +Please update your tinderclient scripts regularly when there are changes. + +If the build succeeds (it did not detect any lines with "***" in them in the logs), then you get a "green" on that client's timeline. + + +### The To Do list + +There are a number of features not yet implemented in freedesktop's tinderbox: + +* logins +* Regression tests of XMonolithic +* by use of bonsai (not yet operational on freedesktop.org) you can quickly see what changes have recently been checked in. +* the blame column lets you quickly identify who likely broke the build by its identification of who recently checked in code. +* be used to do binary builds that may be uploaded for distribution. +* patches can be applied for testing. +* other tinderboxes also need establishment: e.g. for the modular build. +* the tinderbox client script can (potentially) be automatically updated to clients. + +People interested in helping set up all of this would be greatly appreciated; I've filed bugs in bugzilla against tinderbox on these topics to keep track of them. If you want to work on one of them, assign the bug to yourself so we know who is working on them. + + +### Tinderbox version. + +This version of tinderbox is based on the tinderbox3 work that Cliff White and Christian Reis have been doing on behalf of [[OSDL, the Open Source Development labs|http://www.osdl.org]] extending the orginal [[tinderbox3 work of John Kaiser|http://www.johnkeiser.com/mozilla/tbox3.html]]. Mozilla is still running the original version of tinderbox, and tinderbox 2 is confusingly in Mozilla's CVS, with the most recent documents all about tinderbox 2. It appears Mozilla may eventually convert to tinderbox3, completely skipping tinderbox 2. + +Our great thanks for all the help Cliff and Christian have provided and the funding that OSDL provided to them for working on Tinderbox 3. + +John Dennis was very helpful getting the client XMonolithic.pm client into better shape. diff --git a/Software/Tracker.mdwn b/Software/Tracker.mdwn new file mode 100644 index 00000000..0964e345 --- /dev/null +++ b/Software/Tracker.mdwn @@ -0,0 +1,2 @@ + +The latest info about Tracker can be found at [[http://projects.gnome.org/tracker/|http://projects.gnome.org/tracker/]]. diff --git a/Software/UimQt.mdwn b/Software/UimQt.mdwn new file mode 100644 index 00000000..8a1e110a --- /dev/null +++ b/Software/UimQt.mdwn @@ -0,0 +1,34 @@ +## UimQt + + +### Introduction + +This is the [[Qt input module plugin|http://immodule-qt.freedesktop.org]] for [[Uim|http://uim.freedesktop.org/]] + + +#### Downloads + +[[uim-qt-0.2.0.tar.gz|http://freedesktop.org/~kzk/uim-qt/uim-qt-0.2.0.tar.gz]] (correspond to qt-x11-immodule-unified-qt3.3.3-20040910) + +Or you can checkout the lastest revision from svn: + + svn co http://freedesktop.org:8080/svn/uim/trunk/qt/quiminputcontextplugin + +The repository can also be browsed [[online|http://freedesktop.org:8080/svn/uim/trunk/qt/quiminputcontextplugin]]. + + +#### Experimental Qt4 version + +This module works on Qt4-beta1 with qt-x11-immodule-qt4.0.0-tp1-20040822 patch. Very Very, experimental one. + +you can checkout the lastest revision from svn: + + svn co http://freedesktop.org:8080/svn/uim/trunk/qt/quiminputcontextplugin-qt4 + +The repository can also be browsed [[online|http://freedesktop.org:8080/svn/uim/trunk/qt/quiminputcontextplugin-qt4]]. + +---++++Acknoledgement ---+++++Package Maintainer + + * Hidetaka Iwai: Debian Package + * UTUMI Hiroshi: Mandrake rpm +-- Main.[[KazukiOhta]] - 17 Oct 2004 diff --git a/Software/VDPAU.mdwn b/Software/VDPAU.mdwn new file mode 100644 index 00000000..9afbb298 --- /dev/null +++ b/Software/VDPAU.mdwn @@ -0,0 +1,24 @@ + + +# VDPAU + +VDPAU is the Video Decode and Presentation API for UNIX. It provides an interface to video decode acceleration and presentation hardware present in modern GPUs. + + +## Features + +* Hardware decoding of MPEG-1, MPEG-2, MPEG-4 part 2, H.264, VC-1, and DivX 4 and 5 bitstreams on supported hardware, with a bitstream (VLD) level API. +* Video post-processing including advanced deinterlacing algorithms, inverse telecine, noise reduction, configurable color space conversion, and procamp adjustments. +* Sub-picture, on-screen display, and UI element compositing. +* Direct rendering timestamp-based presentation of final video frames, with detailed frame delivery reports. + +## Documentation + +Documentation for the API is stored in Doxygen comments in the VDPAU header files. You can also read the [[generated HTML version|ftp://download.nvidia.com/XFree86/vdpau/doxygen/html/index.html]]. + + +## Code + +The library used by applications that wish to use VDPAU is [[libvdpau|http://cgit.freedesktop.org/~aplattner/libvdpau/]]. This is a wrapper library that loads the appropriate implementation backend. There is also a tracing library that can be used to debug VDPAU applications. + +[[vdpauinfo|http://cgit.freedesktop.org/~aplattner/vdpauinfo]], a tool to query the capabilities of a VDPAU implementation, is also available. diff --git a/Software/X11.mdwn b/Software/X11.mdwn new file mode 100644 index 00000000..2a812dab --- /dev/null +++ b/Software/X11.mdwn @@ -0,0 +1,26 @@ + + +# Xlib - a C Language Library interface to the X Window System Protocol + + +## Introduction + +This is the libX11 library that is the C binding to the X protocol. It is the foundation of practically every X Window System program out there. It is now in the freedesktop [[CVS|http://cvs.freedesktop.org/xlibs/X11/]]. + + +## Mailing list + +All Xlib discussion is currently on [[xlibs@lists.freedesktop.org|http://lists.freedesktop.org/mailman/listinfo/xlibs]] mailing list. + +Also join us on #freedesktop on [[freenode|http://freenode.net]]. + + +## CVS + +Specification and implementation are in module X11 in [[CVS|http://cvs.freedesktop.org/xlibs]]. + + +## Documentation + + * [[Xlib To Do List|Software/XlibToDoList]] +-- Main.[[JimGettys|JimGettys]] - 12 Jan 2004 diff --git a/Software/XDamage.mdwn b/Software/XDamage.mdwn new file mode 100644 index 00000000..27e42a8e --- /dev/null +++ b/Software/XDamage.mdwn @@ -0,0 +1,38 @@ +## XDamage Extension + +The X Damage Extension allows applications to track modified regions of drawables. + +[[Protocol document from git repository|http://cgit.freedesktop.org/xorg/proto/damageproto/plain/damageproto.txt]] + + +### Goals + +* Minimize latency for using damage information +* Minimize bandwidth used by damage tracking + +### Basic Plan + +* Send simple 'window is damaged' events, optionally stop until application responds. +* Accumulate damage in server-side region objects +* Application can copy damage region to separate object and simultaneously erase the damage region +* Applications can also subtract rectangles from the damage region + +### CVS Access + +The main implementation is done on the "xserver" cvs tree, the modular tree. As part of an ongoing effort to merge the modular and monolithic camps, DAMAGE and XFIXES have been merged onto the monolithic tree. The name of the branch is ``DAMAGE-XFIXES``. To try this, use: + + $ cvs -d :pserver:anoncvs@cvs.freedesktop.org:/cvs/xorg login + + CVS password: <hit return> + + $ cvs -d :pserver:anoncvs@cvs.freedesktop.org:/cvs/xorg co -r DAMAGE-XFIXES xc + +The near term plan is to continue to add XeVIE and COMPOSITE to this branch and ultimately fold it to the head of the "xorg" code pool + +/skk + +-- [[KeithPackard]] - 09 Oct 2003 [[!img http:/png/glider.png] + +--- + + [[CategoryExtension]] diff --git a/Software/XEvIE.mdwn b/Software/XEvIE.mdwn new file mode 100644 index 00000000..666ca4ae --- /dev/null +++ b/Software/XEvIE.mdwn @@ -0,0 +1,30 @@ + + +# XEvIE - X Event Interception Extension + +XEvIE is a X extension providing functionalities to allow users intercept keyboard/mouse events. + + +## About XEvIE + +X Event Interception Extension (XEvIE) is designed for users who need to intercept all the Keyboard and Mouse events. The requirement for XEvIE is directly from GNOME Accessibility project. AT Accessibility API needs to have full keyboard/mouse control. XEvIE provides a set of API to allow AT Accessibility API to get and consume Keyboard/Mouse events. The current version of XEvIE works in single-client mode. The multiple-client support will be added in the future release. + +It has been [[suggested|http://lists.freedesktop.org/archives/xorg/2008-April/034760.html]] that this extension should not be used because it is broken and maintainerless. + + +## Documentation + + * [[1.0 XEvIE specification|http://www.freedesktop.org/~ajax/xevie/xevie-spec.txt]] + * [[1.1 XEvIE specification, includes multiclient and write channel locking definition|http://www.freedesktop.org/~ajax/xevie/xevie-spec.1.1.html]] + * [[New and Modified files|http://www.freedesktop.org/~ajax/xevie/xevie-files.txt]] + * [[Test program|http://www.freedesktop.org/~ajax/xevie/xevie-test.txt]] + +## History + + * XEvIE is integrated in HEAD and was shipped with X ORG 6.8. It is disabled by default. + * XEvIE has been removed from HEAD on Wed Oct 22: [[http://cgit.freedesktop.org/xorg/xserver/commit/?id=f4036f6ace5f770f0fe6a6e3dc3749051a81325a|http://cgit.freedesktop.org/xorg/xserver/commit/?id=f4036f6ace5f770f0fe6a6e3dc3749051a81325a]] + + +--- + + [[CategoryExtension|CategoryExtension]] diff --git a/Software/XKeyboardConfig.mdwn b/Software/XKeyboardConfig.mdwn new file mode 100644 index 00000000..858be7c1 --- /dev/null +++ b/Software/XKeyboardConfig.mdwn @@ -0,0 +1,86 @@ + + +# X Keyboard Configuration Database + +The non-arch keyboard configuration database for X Window. The goal is to provide the consistent, well-structured, frequently released open source of X keyboard configuration data for X Window System implementations (free, open source and commercial). The project is targeted to XKB-based systems. + + +# What is it for? + +There are many X Window implementations which have very poor support for non-standard keyboards, national layouts and options. + +Open Source X Window System implementations (xfree86, x.org) currently have non-synchronized XKB configuration databases: the bugs fixed in one repository are not reflected in the other, new configuration elements are added (in best case) separately and independently to both CVS trees - but usually only one tree gets them. Also, these implementations contain unbalanced and unstructured layout trees (very often one country/language have several layouts, each with its own set of variants). + +Commercial X Window System implementations cannot support large variety of national layouts - usually, because of lack of resources. So users from "exotic" countries feel offended and frustrated - their environments are not complete. + +The solution which would guarantee quality support for the keyboard configuration data is to have single repository which would serve as meta-project for X servers and OS distributions. X Keyboard Configuration Database is trying to be the one. + + +# License + +[[MIT License|http://www.opensource.org/licenses/mit-license.php]] + + +# Development + +For details on mailing lists, bug reporting, code repositories, and submission rules, see [[here|Software/XKeyboardConfig/Development]] + + +# Releases + + * [[0.1|http://xlibs.freedesktop.org/release/xkeyboard-config-0.1.tar.gz]] - 25 May 2004, first version. Only single-group layouts are included (tested for compatibility with the multiple layouts feature). Each language/country has no more than one layout and any number of variants. + * [[0.2|http://xlibs.freedesktop.org/release/xkeyboard-config-0.2.tar.gz]] - 12 Jun 2004, second version. HOWTO.transition is added, xkbcomp symlink is supported, Maori layout is added, small fix for Brasilian layout is applied. + * [[0.3|http://xlibs.freedesktop.org/release/xkeyboard-config-0.3.tar.gz]] - 23 Jul 2004, HEAVILY restructured layout names, compatibility rules are introduced, intltool problem resolved (sorry, with warnings). + * [[0.4|http://xlibs.freedesktop.org/release/xkeyboard-config-0.4.tar.gz]] - 28 Sep 2004, A lot of fixes. More univeral EURO handling. New urdu layout. Improved handling for indicators. + * [[0.5|http://xlibs.freedesktop.org/xkbdesc/xkeyboard-config-0.5.tar.gz]] - 02 Mar 2005, New layouts/models/options. Updated translations. Group names synchronization. + * [[0.6|http://xlibs.freedesktop.org/xkbdesc/xkeyboard-config-0.6.tar.gz]] - August 2005, Many improvements. + * [[0.7|http://xlibs.freedesktop.org/xkbdesc/xkeyboard-config-0.7.tar.bz2]] - December 2005, New layouts/models/options. Reogranized symbols/inet. + * [[0.8|http://xlibs.freedesktop.org/xkbdesc/xkeyboard-config-0.8.tar.bz2]] - March 2006, New layouts, fixes. + * [[0.9|http://xlibs.freedesktop.org/xkbdesc/xkeyboard-config-0.9.tar.bz2]] - October 2006, New layouts, fixes. + * [[1.0|http://xlibs.freedesktop.org/xkbdesc/xkeyboard-config-1.0.tar.bz2]] - July 2007, Around 70 bugs from freedesktop.org bugzilla were fixed. + * [[1.1|http://xlibs.freedesktop.org/xkbdesc/xkeyboard-config-1.1.tar.bz2]] - September 2007, Around 30 bugs from freedesktop.org bugzilla were fixed. First time-based release. + * [[1.2|http://xlibs.freedesktop.org/xkbdesc/xkeyboard-config-1.2.tar.bz2]] - January 2008, Around 40 bugs from freedesktop.org bugzilla were fixed. Updated translation schema. + * [[1.3|http://xlibs.freedesktop.org/xkbdesc/xkeyboard-config-1.3.tar.bz2]] - May 2008, Around 40 bugs from freedesktop.org bugzilla were fixed. Dropped old rulesets sgi and sun. Added a lot of metadata, related to countries and languages. + * [[1.4|http://xlibs.freedesktop.org/xkbdesc/xkeyboard-config-1.4.tar.bz2]] - September 2008, Around 30 bugs from freedesktop.org bugzilla were fixed. Added new ruleset evdev. + * [[1.5|http://xlibs.freedesktop.org/xkbdesc/xkeyboard-config-1.5.tar.bz2]] - January 2009, More than 40 bugs from freedesktop.org bugzilla were fixed. symbols/inet restructured. + * [[1.6|http://xlibs.freedesktop.org/xkbdesc/xkeyboard-config-1.6.tar.bz2]] - May 2009, Around 30 bugs from freedesktop.org bugzilla were fixed. Added terminate:* group. Dropped locale-specific models. + * [[1.7|http://xlibs.freedesktop.org/xkbdesc/xkeyboard-config-1.7.tar.bz2]] - September 2009, Around 30 bugs from freedesktop.org bugzilla were fixed. Restructured rules-generating scripts. + * [[1.8|http://xlibs.freedesktop.org/xkbdesc/xkeyboard-config-1.8.tar.bz2]] - January 2010, Around 10 bugs from freedesktop.org bugzilla were fixed. + * [[1.9|http://people.freedesktop.org/~svu/xkeyboard-config-1.9.tar.bz2]] - May 2010, Around 30 bugs from freedesktop.org bugzilla were fixed. Evdev model dropped. + * [[2.0|http://www.x.org/releases/individual/data/xkeyboard-config/xkeyboard-config-2.0.tar.bz2]] - September 2010, 17 bugs from freedesktop.org bugzilla were fixed. + * [[2.1|http://www.x.org/releases/individual/data/xkeyboard-config/xkeyboard-config-2.1.tar.bz2]] - January 2011, 13 bugs from freedesktop.org bugzilla were fixed. + * [[2.2|http://www.x.org/releases/individual/data/xkeyboard-config/xkeyboard-config-2.2.tar.bz2]] - April 2011, New structure of descriptions, massive changes in user-visible strings. Special release for GNOME 3 + * [[2.3|http://www.x.org/releases/individual/data/xkeyboard-config/xkeyboard-config-2.3.tar.bz2]] - May 2011, 18 bugs from freedesktop.org bugzilla were fixed. Descriptions from 2.2 are polished + * [[2.4|http://www.x.org/releases/individual/data/xkeyboard-config/xkeyboard-config-2.4.tar.bz2]] - September 2011, 9 bugs from freedesktop.org bugzilla were fixed. + * [[2.5|http://www.x.org/releases/individual/data/xkeyboard-config/xkeyboard-config-2.5.tar.bz2]] - January 2012, 15 bugs from freedesktop.org bugzilla were fixed. + * [[2.5.1|http://xorg.freedesktop.org/archive/individual/data/xkeyboard-config-2.5.1.tar.bz2]] - January 2012, translations updated (after urgent release 2.5) + * [[2.6|http://www.x.org/releases/individual/data/xkeyboard-config/xkeyboard-config-2.6.tar.bz2]] - May 2012, translations, minor fixes + * [[2.7|http://www.x.org/releases/individual/data/xkeyboard-config/xkeyboard-config-2.7.tar.bz2]] - Sep 2012, translations, minor fixes. *.dir files are gone. CTL+ALT type fixed + * [[2.8|http://www.x.org/releases/individual/data/xkeyboard-config/xkeyboard-config-2.8.tar.bz2]] - Jan 2013, translations, minor fixes, massive updates from Oracle +[[Release Schedule|Software/XKeyboardConfig/ReleaseSchedule]] + + +# Contributions to the project. Relations to X Window System implementations. + +We kindly ask and encourage people contributing layouts to XFree86 and X.Org repositories to send patches to X Keyboard Configuration Database. We would highly appreciate X implementations using our codebase in their distributions (there was preliminary agreement with X.Org implementation maintainers). + + +# Links + + * [[X Keyboard Extension|http://pascal.tsu.ru/en/xkb/]] (by Ivan U. Pascal) + * [[The XKB Configuration Guide|http://www.x.org/releases/X11R7.6/doc/xorg-docs/input/XKB-Config.html]] (by Kamil Toman, Ivan U. Pascal, XFree86 project) + * [[An Unreliable Guide to XKB Configuration|http://www.charvolant.org/~doug/xkb/]] (by Doug Palmer) + * [[X Window Keyboard-related forum|http://www.livejournal.com/community/xkbconfig/]] (in [[LiveJournal|http://www.livejournal.com]]) + * [[Compatibility between keyboard models|Software/XKeyboardConfig/ModelsCompatibility]] + * [[Custom Keyboard in Linux/X11|http://people.uleth.ca/~daniel.odonnell/Blog/custom-keyboard-in-linuxx11]] + +# Dreaming of XKB2 + +For many years, there are rumours, discussions and speculations about XKB2 - the new improved version of XKB. I collected [[some ideas|Software/XKeyboardConfig/XKB2Dreams]] that might one day be implemented within XKB2 + + +# Maintainers + + * [[Sergey V. Udaltsov|SergeyUdaltsov]] + * Ivan U. Pascal (comaintainer) +-- Main.[[SergeyUdaltsov|SergeyUdaltsov]] - 01 Apr 2013 diff --git a/Software/XKeyboardConfig/Development.mdwn b/Software/XKeyboardConfig/Development.mdwn new file mode 100644 index 00000000..08b2bf10 --- /dev/null +++ b/Software/XKeyboardConfig/Development.mdwn @@ -0,0 +1,41 @@ + + +# GIT + +The code can be browsed [[here|http://cgit.freedesktop.org/xkeyboard-config/]]. Or using anonymous GIT, according to the standard [[freedesktop.org GIT instructions|Infrastructure/git]]. The GIT URLs are + +git://anongit.freedesktop.org/git/xkeyboard-config + +[[ssh://git.freedesktop.org/git/xkeyboard-config|ssh://git.freedesktop.org/git/xkeyboard-config]] + + +# Mailing list + + * [[xkb@listserv.bat.ru|mailto:xkb@listserv.bat.ru]] (web interface at [[http://listserv.bat.ru/xkb/List.html|http://listserv.bat.ru/xkb/List.html]]). + +# Bugzilla + + * [[https://bugs.freedesktop.org/enter_bug.cgi?product=xkeyboard-config|https://bugs.freedesktop.org/enter_bug.cgi?product=xkeyboard-config]] + +# I18n + +The official translator of the project is [[Translation Project|http://www.translationproject.org]]. The translation domain status can be found [[here|http://www.translationproject.org/domain/xkeyboard-config.html]]. The up-to-date list of .po files is available [[here|http://translationproject.org/latest/xkeyboard-config/]]. + + +# Todo + + * Add compatibility rules for old broken layouts (to allow users to work with existing configurations) + * Provide more documentation on layouts submission + * Add more and more configuration elements as necessary + * Improve i18n (translation of base.xml file) + +# Submission rules + +There are certain rules in the project. These rules are applied to all contributed layouts/variants/models/option. These rules are simple to follow. The code which does not follow them is rejected (or the author is asked to fix the issues). The rules are listed [[here|Software/XKeyboardConfig/Rules]] + + +# XKB issues + +General XKB code issues which affect xkeyboard-config are listed [[here|Software/XKeyboardConfig/XkbIssues/]]. + +-- Main.[[SergeyUdaltsov|SergeyUdaltsov]] - 14 Sep 2008 diff --git a/Software/XKeyboardConfig/ModelsCompatibility.mdwn b/Software/XKeyboardConfig/ModelsCompatibility.mdwn new file mode 100644 index 00000000..eced17d9 --- /dev/null +++ b/Software/XKeyboardConfig/ModelsCompatibility.mdwn @@ -0,0 +1,153 @@ + + +# Real keyboard models vs xkeyboard-config models + +There are multiple models available in xkeyboard-config repository. But there are way more models in real life. This page is intended to be a reference on how to choose the model from the repository - for some real physical keyboard. +[[!table header="no" class="mointable" data=""" + **xkeyboard-config model** | **Real model** | **Manufacturer** | **Has geometry description** | **Comments** +a4_rfkb23 | [[A4Tech|A4Tech]] Wireless Desktop RFKB-23 | [[A4Tech|A4Tech]] | +a4techKB21 | [[A4Tech|A4Tech]] KB-21 | [[A4Tech|A4Tech]] | +a4techKBS8 | [[A4Tech|A4Tech]] KBS-8 | [[A4Tech|A4Tech]] | +abnt2 | Brazilian ABNT2 | ??? | + +acer_c300 | Acer C300 | Acer | +acer_ferrari4k | Acer Ferrari 4000 | Acer | +acer_tm_800 | Acer [[TravelMate|TravelMate]] 800 | Acer | +acpi | ACPI Standard | ??? | +airkey | Acer [[AirKey|AirKey]] V | Acer | +apple | Apple | Apple | +apple_laptop | Apple Laptop | Apple | +armada | Laptopnotebook Compaq (eg. Armada) Laptop Keyboard | Compaq | +azonaRF2300 | Azona RF2300 wireless Internet Keyboard | Azona | +benqx | BenQ X-Touch | BenQ | | All sorts of BenQ X-Touch keyboards (merged) + | BenQ X-Touch 730 | BenQ | + | BenQ X-Touch 800 | BenQ | +brother | Brother Internet Keyboard | Brother | +btc5090 | BTC 5090 | BTC | +btc5113rf | BTC 5113RF Multimedia | BTC | +btc5126t | BTC 5126T | BTC | +btc9000a | BTC 9000A | BTC | +btc9000 | BTC 9000 | BTC | +btc9001ah | BTC 9001AH | BTC | +btc9019u | BTC 9019U | BTC | +cherrybluea | Cherry Blue Line [[CyBo|CyBo]]@rd (alternate option) | Cherry | +cherryblueb | Cherry [[CyMotion|CyMotion]] Master XPress | Cherry | +cherryblue | Cherry Blue Line [[CyBo|CyBo]]@rd | Cherry | +cherrycyboard | Cherry [[CyBo|CyBo]]@rd USB-Hub | Cherry | +chicony9885 | Chicony KB-9885 | Cherry | +chicony | Chicony Internet Keyboard | Cherry | +compaqeak8 | Compaq Easy Access Keyboard | Compaq | +compaqik13 | Compaq Internet Keyboard (13 keys) | Compaq | +compaqik18 | Compaq Internet Keyboard (18 keys) | Compaq | +compaqik7 | Compaq Internet Keyboard (7 keys) | Compaq | +cymotionlinux | Cherry [[CyMotion|CyMotion]] Master Linux | Cherry | +dell101 | Dell 101-key PC | Dell | + +dell | Dell | Dell | + | Dell SK-8125 | Dell | + | Dell SK-8135 | Dell | +dellusbmm | Dell USB Multimedia Keybard | Dell | +dexxa | Dexxa Wireless Desktop Keyboard | Dexxa | +diamond | Diamond 9801 9802 series | Diamond | +dinovo | Logitech diNovo Keyboard | Logitech | +dtk2000 | DTK2000 | ??? | +emachines | Laptopnotebook eMachines m68xx | eMachines | +ennyah_dkb1008 | Ennyah DKB-1008 | Ennyah | +evdev | Evdev-managed keyboard | ??? | +everex | Everex STEPnote | Everex | + +flexpro | Keytronic [[FlexPro|FlexPro]] | Keytronic | + +geniuscomfy2 | Genius Comfy KB-21e-Scroll | Genius | +geniuscomfy | Genius Comfy KB-12e | Genius | +genius | Genius Comfy KB-16M Genius MM Keyboard KWD-910 | Genius | +geniuskb19e | Genius KB-19e NB | Genius | +gyration | Gyration | Gyration | +hhk | Happy Hacking Keyboard | Fujitsu | + +honeywell_euroboard | Honeywell Euroboard | Honeywell | +hp2501 | Hewlett-Packard SK-2501 Multimedia Keyboard | HP | +hp2505 | Hewlett-Packard SK-2505 Internet Keyboard | HP | +hp5181 | Hewlett-Packard 5181 Internet Keyboard | HP | +hp5185 | Hewlett-Packard 5185 Internet Keyboard | HP | + | Hewlett-Packard nx9020 | HP | +hp500fa | Hewlett-Packard Omnibook 500 FA | HP | +hp5xx | Hewlett-Packard Omnibook 5xx | HP | +hp6000 | Hewlett-Packard Omnibook 60006100 | HP | + +hpi6 | Hewlett-Packard Internet Keyboard | HP | +hpxe3gc | Hewlett-Packard Omnibook XE3 GC | HP | +hpxe3gf | Hewlett-Packard Omnibook XE3 GF | HP | +hpxt1000 | Hewlett-Packard Omnibook XT1000 | HP | +hpzt11xx | Hewlett-Packard Pavilion ZT11xx | HP | +inspiron | Dell Laptopnotebook Inspiron 6xxx8xxx | Dell | +ipaq | Compaq iPaq Keyboard | Compaq | +itouch | Logitech iTouch | Logitech | +jp106 | Japanese 106-key | ??? | + +kr106 | Korean 106-key | ??? | + +latitude | Dell Latitude series laptop | Dell | + +logitech_base | Logitech Generic Keyboard | Logitech | + | Logitech Cordless Desktop | Logitech | | + | Logitech Cordless Desktop iTouch | Logitech | + | Logitech Cordless Desktop Navigator | Logitech | + | Logitech Cordless Desktop Optical | Logitech | + | Logitech Ultra-X Keyboard | Logitech | +logiaccess | Logitech Access Keyboard | Logitech | +logicda | Logitech Cordless Desktop (alternate option) | Logitech | +logicfn | Logitech Cordless [[FreedomDesktop|FreedomDesktop]] Navigator | Logitech | +logicink | Logitech Internet Navigator Keyboard | Logitech | +logiex110 | Logitech Cordless Desktop EX110 | Logitech | + | Logitech Cordless Desktop LX-300 | Logitech | + | Logitech Internet 350 Keyboard | Logitech | + | Logitech Media Elite Keyboard | Logitech | +logink | Logitech Internet Keyboard | Logitech | +logiinkse | Logitech iTouch Internet Navigator Keyboard SE | Logitech | +logiinkseusb | Logitech iTouch Internet Navigator Keyboard SE (USB) | Logitech | +logiitc | Logitech iTouch Cordless Keyboard (model Y-RB6) | Logitech | +logitech_g15 | Logitech G15 extra keys via G15daemon | Logitech | +ltcd | Logitech Cordless Desktop | Logitech | | What's the difference to logicd +macbook78 | [[MacBookMacBook|MacBookMacBook]] Pro | Apple | + +macbook79 | [[MacBookMacBook|MacBookMacBook]] Pro (Intl) | Apple | + +macintosh | Macintosh | Apple | +(shared) +macintosh_old | Macintosh Old | Apple | +(shared) +microsoftinet | Microsoft Internet Keyboard | Microsoft | +microsoft | Microsoft Natural | Microsoft | +(shared) +microsoftmult | Microsoft Wireless Multimedia Keyboard 1.0A | Microsoft | +microsoftoffice | Microsoft Office Keyboard | Microsoft | +microsoftpro | Microsoft Natural Keyboard Pro / Microsoft Internet Keyboard Pro | Microsoft | +(shared) +microsoftprooem | Microsoft Natural Keyboard Pro OEM | Microsoft | + | [[ViewSonic|ViewSonic]] KU-306 Internet Keyboard | [[ViewSonic|ViewSonic]] | +microsoftprose | Microsoft Internet Keyboard Pro, Swedish | Microsoft | +(shared) +microsoftprousb | Microsoft Natural Keyboard Pro USB / Microsoft Internet Keyboard Pro | Microsoft | +(shared) +mx1998 | Memorex MX1998 | Memorex | +mx2500 | Memorex MX2500 EZ-Access Keyboard | Memorex | +mx2750 | Memorex MX2750 | Memorex | +omnikey101 | Northgate [[OmniKey|OmniKey]] 101 | Northgate | + +oretec | Oretec MCK-800 MMInternet keyboard | Oretec | +pc101 | Generic 101-key PC | ??? | + +pc102 | Generic 102-key (Intl) PC | ??? | + +pc104 | Generic 104-key PC | ??? | + +pc105 | Generic 105-key (Intl) PC | ??? | + +pc98 | PC-98xx Series | ??? | + +precision_m | Dell Laptopnotebook Precision M series | Dell | +presario | Laptopnotebook Compaq (eg. Presario) Internet Keyboard | Compaq | +propeller | Propeller Voyager (KTEZ-1000) | [[KeyTronic|KeyTronic]] | +qtronix | QTronix Scorpius 98N+ | QTronix | +rapidaccess2a | IBM Rapid Access II (alternate option) | IBM | +rapidaccess2 | IBM Rapid Access II | IBM | +rapidaccess | IBM Rapid Access | IBM | +samsung4500 | Samsung SDM 4500P | Samsung | +samsung4510 | Samsung SDM 4510P | Samsung | +scorpius | Advance Scorpius KI | QTronix | +silvercrest | SILVERCREST Multimedia Wireless Keyboard | Silvercrest | +sk1300 | SK-1300 | NEC | +sk2500 | SK-2500 | NEC | +sk6200 | SK-6200 | NEC | +sk7100 | SK-7100 | NEC | +sk8125 | Dell SK-8125 USB Multimedia Keybard | Dell | +sk8135 | Dell SK-8135 USB Multimedia Keybard | Dell | +sp_inet | Super Power Multimedia Keyboard | ??? | +sven | SVEN Ergonomic 2500 | Sven | +symplon | Symplon [[PaceBook|PaceBook]] (tablet PC) | Symplon | +thinkpad | IBM [[ThinkPad|ThinkPad]] 560Z600600EA22E | IBM | + +thinkpadintl | IBM [[ThinkPad|ThinkPad]] 560Z600600EA22E, Intl | IBM | +toshiba_s3000 | Toshiba Satellite S3000 | Toshiba | +trustda | Trust Direct Access Keyboard | Trust | +trust | Trust Wireless Keyboard Classic | Trust | +winbook | Winbook Model XP5 | ??? | + +yahoo | Yahoo! Internet Keyboard | Yahoo! | +"""]] diff --git a/Software/XKeyboardConfig/ReleaseSchedule.mdwn b/Software/XKeyboardConfig/ReleaseSchedule.mdwn new file mode 100644 index 00000000..197ea8e9 --- /dev/null +++ b/Software/XKeyboardConfig/ReleaseSchedule.mdwn @@ -0,0 +1,40 @@ + + +# The schedule of coming XKeyboardConfig releases +[[!table header="no" class="mointable" data=""" + **Date** | **Event** | **Comment** +25.09.2007 | Release 1.1 | First scheduled release. **Done.** +29.01.2008 | Release 1.2 | **Done.** +27.05.2008 | Release 1.3 | **Done.** +30.09.2008 | Release 1.4 | **Done.** +27.01.2009 | Release 1.5 | **Done.** +26.05.2009 | Release 1.6 | **Done.** +29.09.2009 | Release 1.7 | **Done.** +26.01.2010 | Release 1.8 | **Done.** +25.05.2010 | Release 1.9 | **Done.** +28.09.2010 | Release 2.0 | **Done.** +26.01.2011 | Release 2.1 | **Done.** +03.04.2011 | Release 2.2 | **Done.** Special release for GNOME 3 +31.05.2011 | Release 2.3 | **Done.** +27.09.2011 | Release 2.4 | **Done.** +19.01.2012 | Release 2.5 | **Done.** Urgent release, security issue +31.01.2012 | Release 2.5.1 | **Done.** Post-release with updated translations for 2.5 +29.05.2012 | Release 2.6 | **Done.** +25.09.2012 | Release 2.7 | **Done.** +29.01.2013 | Release 2.8 | **Done.** +14.05.2013 | Freeze for release 2.9 | +28.05.2013 | Release 2.9 | +"""]] + + +# Release schedule principles + +1. Releases are made every 4 months + +2. Two weeks before release, there is a freeze on _rules_ directory: + + 1. _rules/base.xml.in_ is stable for translators to work + 1. _rules/base_ is stable, since rules are the most sensitive part of the build +3. The release is performed on last Tuesday of the month. + +-- Main.[[SergeyUdaltsov|SergeyUdaltsov]] - 01 Apr 2013 diff --git a/Software/XKeyboardConfig/Rules.mdwn b/Software/XKeyboardConfig/Rules.mdwn new file mode 100644 index 00000000..32a7092e --- /dev/null +++ b/Software/XKeyboardConfig/Rules.mdwn @@ -0,0 +1,113 @@ + + +# General + +All the code contributions should be made through [[Bugzilla on freedesktop.org|https://bugs.freedesktop.org/]]. The component name is [[xkeyboard-config|https://bugs.freedesktop.org/enter_bug.cgi?product=xkeyboard-config]]. + +<a name="T"></a> +# Types + +There are no special rules for new types. They are going to be introduced very conservatively. + +<a name="G"></a> +# Geometries + +There are relatively few geometry descriptions that are currently available. People are very welcome to contribute them. The only recommendation is to have them visually pleasant and precise. + +<a name="M"></a> +# Models + +1. Most of PC keyboard models should be defined by the following actions: + +* adding new _xkb_symbols_ section to _symbols/inet_ +* extending _$inetkbds_ list in _rules/base.lists.part_ +* adding new _model_ section to _rules/base.xml.in_ (in _modelList_) +2. It is recommended to use **{v}{m}** pattern for the model name, where **{v}** is abbreviated vendor name. **{m}** is the model name. Recommended vendor abbreviations: + +* 'a4tech' - [[A4Tech|A4Tech]] +* 'acer' - Acer +* 'cherry' - Cherry +* 'chicony' - Chicony +* 'compaq' - Compaq +* 'dell' - Dell +* 'genius' - Genius +* 'logi' - Logitech +* 'microsoft' - Microsoft +* 'samsung' - Samsung +3. The name of _xkb_symbols_ section (in _symbols/inet_) should be same as the new element in the _$inetkbds_ list (in _base.lists.part_), same as _name_ element (in _base.xml.in_). + +4. The _vendor_ element in _base.xml.in_ has to be specified. + +5. While defining _xkb_symbols_, it is strongly recommended to include (where applicable) shared sections for the media and navigation keys: + +* acpi_common +* media_common +* media_acpi_common +* media_nav_acpi_common +* media_nav_common +* nav_common +* nav_acpi_common +These sections should be used even if not all of the keys specified in that section are present in the defined model. The syntax is standard: + + * include "inet(media_common)" +For example, if keys _prev/next/play/stop_ have the mapping as defined in _media_common_ (and other keys do not exist in the keyboard at all) - this is a good case for including entire _media_common_ anyway + +6. The key mappings have to be sorted alphabetically, by the keycode name. + +7. If your keyboard model mapping is entirely covered by some existing section _symbols/inet_ (some keycodes may be not actually used by your keyboard), do not create a new section consisting of a single _include_ statement. Instead, create an alias in _rules/base.m_s.part_ file and add it into _rules/base.xml.in_, as usual. + +<a name="LV"></a> +# Layouts, Variants + +1. Every layout/variant has to define a single group: group 1. Layouts with multiple groups are not accepted. + +2. Every layout/variant has to be defined for some particular country, it should go into the file _symbols/{cc}_ where _{cc}_ is 2-letter country code from [[ISO 3166-1 alpha 2|http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2]]. The language-based layout/file names are not accepted. If several countries are using the same layout (for example, several countries share the same language), it should be fully defined for one country only - and included by reference into the files for other countries + +3. Every layout/variant has to be registered in _rules/base.xml.in_. + +There is only one exception: default variants. These are the variants which are either marked by "default" keyword in the symbols file (it is recommended to put them first and name them _basic_), or used as default because of some rule in the _rules/base_ file (usually by modifying _rules/base.ml_s.part_ component). + +4. There are popular variant names which are used by many countries, so they should be considered as first candidates (where applicable) for new variants. They are: + +* 'dvorak' - for national variants of the Dvorak layout +* 'intl' - for variants suitable for multiple languages; usually - for the official state language(s) and some other frequently used foreign languages. +* 'mac' - for variants specific to Macintosh keyboards +* 'nodeadkeys' - for variants without dead keys (if the some other national variants are using them) +* 'phonetic' - for variants which are using phonetic resemblance (usually - based on standard Americal layout) +* 'sundeadkeys' - for variants with dead keys +* 'us' - for variants which are using standard American layout as a basis, adding some national characters +* 'winkeys' - for variants which are not standardized nationally but used in Microsoft Windows +5. Every layout/variant has to provide a full description. First - as the group name in the symbols file, second - as the translatable description in _rules/base.xml.in_. + +The general approach for the descriptions is to follow "<Language>" or <"Language> (<variation>)" convention, for example: "English" or "Russian (legacy)". The usual practice is to use the country name as variation name, for example: "French (Canada)". The language has to be chosen as the one that is most frequently used with that layout/variant. That language has to be put first into the languageList attribute in base.xml.in (if the variant record does not have own languageList, the parent layout's languages are used). + +Descriptions have to be put into base.xml.in with the underscore in the tag name: <_description>Romanian (Germany)</_description>. This is necessary for i18n. + +6. For the layouts/variants that are "exotic", it is recommended to use base.extras.xml.in instead of base.xml.in. The word "exotic" is used in statistical sense only. + +There is no formal definition of "exotic", because in most cases it is not possible to prove the actual number of users. There are several "usual suspects" for the "exotic" section: + +* The layouts for endangered/extinct languages/scripts. The statistics can be taken from [[http://www.ethnologue.com/|http://www.ethnologue.com/]]. The potential candidates are languages with <100K speakers. If the number of speakers is <10K, the language most probably belongs to "extras" +* The languages that are used most frequently with layouts made for other languages. If most of the texts using the language L1 are typed using layouts made for L2 (more popular), the own layout for L1 may be considered as exotic, even if the language L1 itself is popular. That is the a possible scenario for national minorities using the languages with the alphabet similar to the alphabet used by the language of the larger nation in the same country. +* The exotic layouts for popular languages. If some relatively small group of people are using some variant suitable for their needs. Typical examples: variants for programmers, for typography, for particular group of sciences, for sacred texts etc. +That's typical, but not the only possible scenarios for putting layout/variants into the "extras" section. + +The maintainer of xkeyboard-config typically questions the popularity of newly submitted layouts/variants. If no conclusive proof of number of users is provided, the layout can be put into the extras section (the maintainer reserves that right). + +Putting layout/variant into the extras section is just a representation of the fact that layout is not popular enough to be included into the main section. The GUI tools can use any approach to displaying (or not displaying) "extras" - this issue is out of scope of xkeyboard-config. + +It is recommended to put "exotic" variants into the end of the corresponding symbols file - after the delimiter line: + +// EXTRAS: + +7. The short description (shortDescription tag) is recommended for the indicators that use labels (as opposite to flags) for providing the user with the information about currently used layout/variant. This description is expected to contain the 2-letter [[ISO639-1 code|http://www.loc.gov/standards/iso639-2/php/code_list.php]] (in lowercase) of the primary language - or, if no ISO639-1 exists for that language, it can be 3-letter code from ISO639-2 or ISO639-3. That code is made translatable (please use <_shortDescription> in base.xml.in and base.extras.xml.in), so that localized GUI can display some abbreviations suitable for the current locale. If some variant does not provide own short description, the short description from the parent layout is expected to be used. + +8. For layouts/variants using more than 2 shift levels, it is highly recommended to include _level3(ralt_switch)_ symbols definition - for standard switching to levels 3 and 4 using Alt``Gr key. + +9. The authors are highly encouraged to use _include_ statements wherever possible - it makes the resulting code more compact and easier to manage. + +10. The key mappings have to be sorted alphabetically, by the keycode name. + +11. When you contribute model-specific layout/variant (for example, German for Macintosh), try to separate layout-specific mappings from the general ones, common to any national layout on that hardware. Usually, alphanumeric and punctuation key mappings are layout-specific, while navigation keys, functional keys, modifiers etc are model-specific. Consider putting model-specific keys mappings to the model-specific definitions (usually it is a section of _symbols/inet_ file). + +-- Main.[[SergeyUdaltsov|SergeyUdaltsov]] - 16 May 2011 diff --git a/Software/XKeyboardConfig/XKB2Dreams.mdwn b/Software/XKeyboardConfig/XKB2Dreams.mdwn new file mode 100644 index 00000000..86aca699 --- /dev/null +++ b/Software/XKeyboardConfig/XKB2Dreams.mdwn @@ -0,0 +1,118 @@ + + +# Random collection of ideas related to XKB2 + +**To editors**: Please do not use that list as bugzilla. Think about general changes, not particular bugs. Make sure the functionality you're asking is not possible currently. + +1. Break the limit of maximum number of groups (currently 4). Make it at least 5. (daniels: not a problem, though requires xi2.) + +2. Full support of network-transparent handling for XKB configuration specified as Rules, Models, Layouts, Variants, Options (RMLVO). That includes: + +2.1. Enumeration of all available configuration elements, separately R,M,L,V(L),O + +2.2. Getting (drums roll...) **translated** description for configuration element + +2.3. Getting (extensible?) meta-info for the configuration element. For models - vendors, for LV - language(s), country(s) + +2.4. Setting/getting current XKB configuration + +3. Specifying different action for key press and key release. There is a hack in bugzilla related to the group switching "on release" - that should be generalized. + +4. Standardize at least some option group names - could be useful for GUI. First candidates: _grp, lv3, lvl5, compose_, perhaps more + +50. Support for scenarios "multiple keypresses - one keysym" and "single keypress - multiple keysyms". + +97. Support for virtual devices (shouldn't need to use XTest for things like x2x/synergy/vnc, and virtual devices would be slicker for virtual-machine interfaces) + +99. XKB config syntax using XML. In particular, use (subset of) SVG for geometries + +128. In the geometry, allow to define an area for label placement for each key. Must be a rectangle, inside or outside the key, as it is on the physical keyboard. Useful for irregular polygons like L-shaped keys. Difficult to calculate for arbitrary polygons, more if they are curved (like if the key has the shape of a U, a moon, an irregular star...) --alvarezp + +133. When turning autorepeat off for an already repeating key, stop repeating it, or have a way to instruct the server to stop repeating keys. --alvarezp + + +# Comments + +**svu** (24.05.2010) + +#2 - basically putting base.xml on wire. + +#2.2 - should depend on the client locale. There are various options: client-side translation, server-side translation with explicit locale, server-side translation using some way (XLOCALE extension?) allowing to specify the locale for X session. + +#2.3 - ISO codes to be used + +#50 - separate discussion required. Can replace "Compose" functionality, can help various Input Methods + +There are also some ideas related to implementation - like dropping binary (xkm) format, using text-only representation. + +**svu** (27.05.2010) + +#98 (removed) _Good support for per-device layout management (Just because 1 keyboard plugged is in dvorak doesn't mean they all are)_ XKB always supported it. GUI tools usually don't. + +#100 (removed) _Support for pressing the Windows button as well as pressing Windows + L in the same keyboard layout/settings. Currently the Windows key can either be a normal key or a modifier but not both._ - related to the fact that you cannot have different actions on press and release. See #3 + +#129 (removed) _Allow the enumeration of arbitrary keyboards outside of the current configuration. It is a common mistake on some configurations that no geometry is configured, and the clients can't query XKB for 'pc(pc10[45])' to get a default. --alvarezp_ - this can be fixed with the existing framework of rules. IIRC if no geometru specified, pc105 is used by default. If it is not - it should be fixed. But there is always possibility to request arbitrary configuration from the server, see [[XkbGetKeyboardByName|XkbGetKeyboardByName]] (and if you want it in terms of RMLVO, see #2). + +#130 (removed) _Explicitly standardize the semantics of "model", particularly to be able to specify an exact model as described by the manufacturer. For example: External keyboards => exact model of the keyboard used to create the record; for laptops => exact model of the keyboard AND exact model of the laptop with original keyboard. For KVMs... --alvarezp_ - possible within the current framework. Feel free to open a bug, where we can discuss that. + +#131 (removed) _Explicitly standardize that geometries should always include outlines in multiples of two, the base and the top for each step up in the shape, even if they are equal (like in some netbooks), OR that if it is an even number, that the last one should be duplicated. Useful for identifying lateral sides of keys and painting accordingly. --alvarezp_ - I do not think this is fair requirement. It can be easily done with simple math (CMIIW) + +#132 (removed) _Allow oval shapes, being "circles" a particular case. --alvarezp_ - The ultimate goal would be to use some subset of SVG for geometry - just incorporate keycodes and indicators into it. #99 updated. + +#133 - could you please elaborate, what's the current behavior? + +**daniels** (27.5.2010) # #1 Easily done, but requires clients to be using Xi2 as well. + +#2 No problem, except I'm skeptical of the translation/extensible metadata thing - half the point of this was to remove stuff and make it smaller! + +#4 I don't think it's reasonable to put this in the spec. xk-c is the de facto standard in this area anyway, though I might cobble together a much more minimal dataset that you could reasonably expect would be present everywhere. + +#50 Single->multiple is easily doable, but multiple->single is _much_ more delicate (say you have 'o' and '/' generating 'ø', and a grab on '/': what happens when you press '/'?), and I'd rather leave it in the input method for the time being. + +#97 This is something for Xi rather than XKB, as XKB does not deal with sending events to clients, and any XTest replacement would need pointer motion anyway. + +#99 NNNNNNNNNNNNNNNNNNNNNNNNNOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOOO. I'd like to kill geom from XKB anyway; if it does exist, I don't think it has any particular business being on the wire. #128 is part of the reason why - it's ungodly complex, and the server has absolutely zero use for it. + +**alvarezp** (2010-05-27) + +#99 -- _I'd like to kill geom from XKB anyway --daniels_ -- Nonono, no killing. Geometries are central to my application, as it paints the current keyboard on screen whatever it is. #128 is just adding another field to the database, with whatever implications. + +#129 (removed by svu) _this can be fixed with the existing framework of rules. IIRC if no geometru specified, pc105 is used by default. If it is not - it should be fixed. But there is always possibility to request arbitrary configuration from the server, see [[XkbGetKeyboardByName|XkbGetKeyboardByName]] (and if you want it in terms of RMLVO, see #2)._ -- Thanks, will raise bugs for both, since pc105 is not a default, and [[XkbGetKeyboardByName|XkbGetKeyboardByName]] fails to load geometries outside of current configuration. + +#130 (removed by svu) _possible within the current framework. Feel free to open a bug, where we can discuss that._ -- Will be done, thanks. + +#131 (removed by svu) _I do not think this is fair requirement. It can be easily done with simple math (CMIIW)_ -- Yes, it can be done by making simple assumptions, and that's how I do it, but those assumptions are outside of the specification. That's why I ask. + +#132 (removed by svu) _Allow oval shapes -- The ultimate goal would be to use some subset of SVG for geometry - just incorporate keycodes and indicators into it. #99 updated._ -- Sounds really nice. It would just be needed to keep the semantics: bounding box, primary outline, approximation outline, detailed outline, to be able to detect the top of the key and drawing inside it, not just a meaningless shape. + +#133 - _could you please elaborate, what's the current behavior? --svu_ // [[http://web.archiveorange.com/archive/v/Ky751V5Yp70TRzlmvsit|http://web.archiveorange.com/archive/v/Ky751V5Yp70TRzlmvsit]] Daniel says it is not a bug as, according to XKB, actions only affect unpressed keys. + +**svu** (2010-05-31) + +#400 - _Support for applications to request a keyboard with keys xyz and for Xorg to bring up an on-screen keyboard when equivalent hardware keys are not available. Useful on smartphones for example where there may only be a number pad or a couple of buttons and a fold-out keyboard._ - Can be implemented externally to the server. Should be implemented externally. + +**daniels** (2010-06-01) + +(Much like top-posting, it seems that non-nested comments do not scale.) + +#99 - Sure, and it's a nice idea, but given how woefully incomplete our geometry database is, and how crap vendors are at actually putting anything useful ever into their HID strings, I don't think it's worth keeping in the server. I've nothing against exposing a model name that tries to be as useful as possible, but geometry is a _mess_ right now, and easily the most fragile part of the extremely fragile keymap handling code. I don't see any benefit to having it on the wire instead of in an external database, particularly if the latter can be useful to others. + +#129 - Regardless of any of the above, this should definitely be fixed. I saw the bug and will try to get around to it. + +#131 - This is exactly the kind of thing I'm talking about, BTW ... + +**svu** (2010-06-01) + +#99 - well, you seen the code, while I did not, so you definitely know better how it all organized. But the thing is that functionally the geometry is nearly transparent meta-info. All server is required to do is parse it and provide it when asked. It could be declared as "anything parseable by clients" (with mime type?) buffer. Actually, that is the reason I proposed SVG - from the server POV, the format of geometries does not really matter, the behavioristic parts of the code do not use geometry info, right? + +(Perhaps we really should reorganize the buffer into some threaded form) + +**daniels** (2010-06-10) + +#99 - How about just using an Xi property containing a boatload of SVG, then? :) + +**svu** (2010-06-16) + +#99 - That would make sense. Except that we need to settle some convention on using xkb-specific elements (keycodes and stuff) within SVG. Otherwise I am happy with it. + +Daniel, with this approach, do you see that in a future existing XKB would be implemented as compatibility layer over allmighty XInput? Mapping SVG to XKB geometry would be funny:) diff --git a/Software/XKeyboardConfig/XkbIssues.mdwn b/Software/XKeyboardConfig/XkbIssues.mdwn new file mode 100644 index 00000000..e001f026 --- /dev/null +++ b/Software/XKeyboardConfig/XkbIssues.mdwn @@ -0,0 +1,68 @@ + + +# XKB issues + +Basically, this list is a subset of the bugs related to the component 'Input/XKB' of the product 'xorg' in bugzilla.freedesktop.org (see [[full list|https://bugs.freedesktop.org/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&short_desc=&product=xorg&component=Input%2FXKB&long_desc_type=substring&long_desc=&bug_file_loc_type=allwordssubstr&bug_file_loc=&status_whiteboard_type=allwordssubstr&status_whiteboard=&keywords_type=allwords&keywords=&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&emailassigned_to1=1&emailtype1=substring&email1=&emailassigned_to2=1&emailreporter2=1&emailqa_contact2=1&emailcc2=1&emailtype2=substring&email2=&bugidtype=include&bug_id=&chfieldfrom=&chfieldto=Now&chfieldvalue=&cmdtype=doit&order=Reuse+same+sort+as+last+time&field0-0-0=noop&type0-0-0=noop&value0-0-0=]]) +## xkbcomp at X startup + + +### Issue Description + +xkbcomp at X startup is unnecessary performance penalty. Possible alternatives: + +1. Rewriting xkbcomp to make it more effecient (for example, by caching the configuration) +1. Using shared library directly from X server. That library would also be used by setxkbmap. + +### Status/Owner + + +### Bug(s) + +[[#15540|https://bugs.freedesktop.org/show_bug.cgi?id=15540]] +## XKM format should be deprecated + + +### Issue Description + +XKM as a binary format has some serious issues: + +1. Not readable +1. Some information is not presentable (see [[#4927|https://bugs.freedesktop.org/show_bug.cgi?id=4927]]) +1. _TBC_ (Daniel, feel free to express all your hatred here;) +Textual XKB format should be the only format of the persistant configuration data used by XKB. +### Status/Owner + + +### Bug(s) + +[[#4927|https://bugs.freedesktop.org/show_bug.cgi?id=4927]] +## xkbcomp needs :all syntax for rules + + +### Issue Description + +The following functionality is needed in xkbcomp: If some XKB option is using some symbols in group 1, they should be propagated to all groups present in the configuration. Something like + +! option = symbols + +og:abc = symfile(v):all + +// equal to og:abc = symfile(v):1 + symfile(v):2 + ... till the last group +### Status/Owner + + +### Bug(s) + +[[#14372|https://bugs.freedesktop.org/show_bug.cgi?id=14372]] +## setxkbmap is unable to explain the rules it applied + + +### Issue Description + +Sometimes setxkbmap makes non-trivial decisions regarding the way it applies the rules. Even using dozen of -v options does not help. What would be useful to have is some way to see the list of the rules applied to the input components (with references to line numbers in the rules file perhaps). +### Status/Owner + + +### Bug(s) + +[[#16975|https://bugs.freedesktop.org/show_bug.cgi?id=16975]] diff --git a/Software/XKeyboardConfig/package.zip b/Software/XKeyboardConfig/package.zip Binary files differnew file mode 100644 index 00000000..f6aa98a9 --- /dev/null +++ b/Software/XKeyboardConfig/package.zip diff --git a/Software/XTesting.mdwn b/Software/XTesting.mdwn new file mode 100644 index 00000000..40407641 --- /dev/null +++ b/Software/XTesting.mdwn @@ -0,0 +1,134 @@ + + +# X Testing Software + +This page provides infomation on various tools to aid the testing ( and to a degree, debugging ) of X Servers and Clients. + +Please add anything I've missed that you find useful. + + +## General Testing/Debugging Tools ( Not X specific ) + + +### gdb + +GNU interactive debugger. + +[[http://www.gnu.org/software/gdb/gdb.html|http://www.gnu.org/software/gdb/gdb.html]] + + +### gcov, gprof + +Code coverage and profiling. Part of the GCC compiler collection. + +[[http://gcc.gnu.org/|http://gcc.gnu.org/]] + + +### valgrind + +Valgrind is a GPL'd system for debugging and profiling x86-Linux ( and now powerpc ? ) programs. Very useful for trapping memory leaks. + +[[http://valgrind.kde.org/|http://valgrind.kde.org/]] + + +## X Server Testing + + +### rendercheck + +[[EricAnholt|EricAnholt]] 's program for testing server render acceleration correctness. In initial development, available from fd.o git "xapps/rendercheck/" + + +### Xtest suite + +Old MIT based Test Suite for testing conformance of ported servers. + +builds for me via xmkmf, . ./build.sh. Have no idea how to run it. + +[[ftp://ftp.xfree86.org/pub/XFree86/xtest/|ftp://ftp.xfree86.org/pub/XFree86/xtest/]] + +( also see [[http://www.opengroup.org/testing/testsuites/vsw5.htm|http://www.opengroup.org/testing/testsuites/vsw5.htm]] ) + +A slightly updated version of the old test suite with build instruction can be found here: [[http://wiki.x.org/wiki/XorgTesting|http://wiki.x.org/wiki/XorgTesting]] + + +### x11perf + +Tests performance of most ( non render ext ) X operations. + +Available packaged in most distributions. + + +### Misc + +I did some tests measuring blit speeds with kdrive on various ARM based handhelds. The results of which are available here; + +[[http://handhelds.org/~mallum/fullscreen/|http://handhelds.org/~mallum/fullscreen/]] + + +## X Client Testing + + +### Client X servers ( or X clients that are servers ) + + +#### Xephyr, Xnest + + * Both of these provide servers that run on an existing X server. Useful for window manager development or 'emulation' of a different sized display. Both are available in [[git|Infrastructure/git/Users]]. Xnest is mature and stable but lacks support for 'modern' X extensions ( such as render and composite ), whilst Xephyr supports these extensions but is a newer and less widely distributed application. + * [[Xnest|http://cgit.freedesktop.org/xorg/xserver/tree/hw/xnest]] + * [[Xephyr|http://cgit.freedesktop.org/xorg/xserver/tree/hw/kdrive/ephyr]] Xnest is also available packaged in most distributions. +See also [[Software/Xephyr|Software/Xephyr]] + + +### Server side resource leaks + + +#### xrestop + + * Provides realtime 'top' like statistics of each clients resource usage in the server. [[Software/xrestop|Software/xrestop]] + +### EWMH/ICCCM compliance + + +#### Window manager tools. + + * matchbox & metacity window manager source both contain various tools to generate 'dummy' windows with particular properties. + * [[http://matchbox.handhelds.org|http://matchbox.handhelds.org]] ( grab matchbox-tests ) [[http://ftp.gnome.org/pub/gnome/sources/metacity/|http://ftp.gnome.org/pub/gnome/sources/metacity/]] + +#### xprop + + * Command line tool to inspect window properties. Available packaged for most distributions. + +#### wininfo + + * New nice window inspection tool with GTK GUI and EWMH hint 'aware'. [[Software/wininfo|Software/wininfo]] + +### Protocol usage / events + + +#### xev + + * xev displays the contents on events recieved by its window. Available packaged for most distributions. + +#### xmon + + * xmon is an 'interactive X protocol monitor'. It acts as a proxy between a server and clients and provides configurable infomation on the traffic passing through it. Available packaged for most distributions. ( apt-get install xmon on Debian ) + +#### Also see + + * Keith Packards 'X Window System Network Performance' paper; [[http://freedesktop.org/~keithp/talks/usenix2003/html/net.html|http://freedesktop.org/~keithp/talks/usenix2003/html/net.html]] Kenton Lees 'Debugging X Input Events'; [[http://www.rahul.net/kenton/events.html|http://www.rahul.net/kenton/events.html]] + +### Automating Usage + + +#### Xnee + + * Xnee is a suite of programs that can record and replay X events. This allows user interaction to be recorded and played back. Xnee can be used as a monitor, to 'retype' a file and to distribute events. Xnee can record all data in the X11 protocol. [[http://www.sandklef.com/xnee/|http://www.sandklef.com/xnee/]] + +### Misc + + +#### matchbox-nest + + * 'matchbox nest' is a graphical wrapper around xnest. Its intended for embedded developers that want to simulate a target device ( with display, buttons ) on a desktop machine. [[http://matchbox.handhelds.org/sources/matchbox-nest/|http://matchbox.handhelds.org/sources/matchbox-nest/]] +-- [[MatthewAllum|MatthewAllum]] - 09 Jun 2004 diff --git a/Software/Xephyr.mdwn b/Software/Xephyr.mdwn new file mode 100644 index 00000000..dab7aa82 --- /dev/null +++ b/Software/Xephyr.mdwn @@ -0,0 +1,33 @@ + + +## Xephyr + +Xephyr is a kdrive based X Server which targets a window on a host X Server as its framebuffer. Unlike Xnest it supports modern X extensions ( even if host server doesn't ) such as Composite, Damage, randr etc (no GLX support now). It uses SHM Images and shadow framebuffer updates to provide good performance. It also has a visual debugging mode for observing screen updates. + +Possible uses include; + +* **Xnest replacement** - Window manager, Composite 'gadget', etc development tool. +* **Toolkit debugging** - rendundant toolkit paints can be observered easily via the debugging mode. +* **X Server internals development** - develop without the need for an extra machine / display. +* **[[Multiterminal with Xephyr|http://en.wikibooks.org/wiki/Multiterminal_with_Xephyr]]** - configuration is a single computer which supports multiple users at the same time + +### Screenshot + +Lots of Xephyr's in [[action|http://freedesktop.org/~mallum/xephyr-uber.png]]. + + +### Download + +Xephyr is available via [[git|Infrastructure/git/Users]] as part of the [[Xserver|http://cgit.freedesktop.org/xorg/xserver/tree/hw/kdrive/ephyr/]] module. + + +### More Infomation + +See the [[README|http://cgit.freedesktop.org/xorg/xserver/tree/hw/kdrive/ephyr/README]] + + +### Authors + +Xephyr was written by Matthew Allum. + +-- [[MatthewAllum|MatthewAllum]] - 10 Sep 2004 diff --git a/Software/Xft.mdwn b/Software/Xft.mdwn new file mode 100644 index 00000000..1ddd653e --- /dev/null +++ b/Software/Xft.mdwn @@ -0,0 +1,32 @@ + + +# Xft - the X Font library + + +## About Xft + + * The current version of Xft (2.0) provides a client-side font API for X applications. It uses [[FontConfig|http://www.fontconfig.org/]] to select fonts and the X protocol for rendering them. When available, Xft uses the Render extension to accelerate text drawing. When Render is not available, Xft uses the core protocol to draw client-side glyphs. This provides completely compatible support of client-side fonts for all X servers. Drawing anti-aliased text with the core protocol involves fetching pixels from the destination, merging in the glyphs and shipping them back. This can be a performance problem when the latency between client and server is high. Drawing non-AA text with the core protocol can be done by just sending the glyphs from the client to the server. This eliminates any latency effects and makes rendering speed depend only on bandwidth. Careful protocol selection can make the bandwidth scale linearly with the pixel size of the glyphs, so performance is acceptable, even with relatively large glyphs. When using legacy X servers (those without Render support) across a network, disabling anti-aliased text will improve text performance so that applications are reasonably usable even if completely dependent on client-side fonts. + +### The many faces of Xft + + * There are three very different libraries name Xft. The original 1.0 Xft library shipped with XFree86 4.0.2 and included a private configuration mechanism via the XftConfig file. For X servers without the Render extension, Xft 1.0 used core X fonts instead of client-side fonts. This was supposed to allow applications to code to a common API and run with all X servers. Early in the deployment of Xft 1.0, it became abundantly clear that another custom X-specific font configuration mechanism was a really bad idea. Both KDE and Pango ended up stealing pieces of Xft to configure fonts. KDE created a GUI Xft configuration tool by stealing the XftConfig parsing code, Pango stole most of Xft so that the XftConfig file could be shared between the Xft and FreeType2 backends. Fontconfig was designed to solve both of these problems. The other problem in Xft 1.0 was the use of core X fonts when the server wasn't blessed with the Render extension. This meant that applications couldn't count on client-side fonts when using the high-level Xft APIs. As client-side fonts provide significant value beyond anti-aliased glyphs, it again became obvious that this design was flawed. The Xft 1.0 API abstracted configuration details sufficient to permit a binary compatible version, Xft 1.1, to be developed which replaces the XftConfig configuration file with calls in to the Fontconfig library. Unfortunately, the Xft 1.0 API didn't sufficiently hide the rendering details making it impossible to provide for client-side fonts in servers without the Render extension. This means that Xft 1.1 shares font configuration, but isn't really usable on servers without Render. + +## Source Releases + +Xft source tarballs are released via the X.Org source archives, such as in [[http://xorg.freedesktop.org/releases/individual/lib/|http://xorg.freedesktop.org/releases/individual/lib/]] ([[mirrors|http://www.x.org/wiki/Releases/Download]]) + + +## Mailing List + +All Xft discussion is currently on [[xorg@lists.freedesktop.org|http://lists.freedesktop.org/mailman/listinfo/xorg]]. + + +## Git repository + +Specification and implementation are in module libXft in freedesktop's [[git repository|http://cgit.freedesktop.org/xorg/lib/libXft/]]. + + +## Documentation + + * [[Xft To Do List|Software/XftToDo]] +-- Main.[[JimGettys|JimGettys]] - 11 Feb 2004 diff --git a/Software/XftToDo.mdwn b/Software/XftToDo.mdwn new file mode 100644 index 00000000..cc9eb5dd --- /dev/null +++ b/Software/XftToDo.mdwn @@ -0,0 +1,15 @@ + + +## Xft To Do List + +A directory of [[Related Freedesktop.org To Do Projects|FreedesktopProjects]] is available. + +Work on [[Xft|Software/Xft]] is almost complete, but there are a few loose ends, as documented below. Contact Main.[[KeithPackard|KeithPackard]] about Fontconfig projects. +[[!table header="no" class="mointable" data=""" + **Project** | **Type** | **Description** | **Diff/Size** | **Comp.** + Extend Xt | code | Make it easy for Xt based apps to use Xft | easy/small | 0% + Update Xaw to use Xft2 | code | Update Xaw to use Xft2, to eliminate another source of ugly characters on your screen. | easy/small | 0% + Stamp out bitmap text | code | Pick your favorite toolkit application that still uses core fonts and update it: thousands to choose from (but not Qt or GTK apps). GTK and Qt already have Xft support | easy/small | 0% +"""]] + +-- Main.[[JimGettys|JimGettys]] - 11 Feb 2004 diff --git a/Software/XlibToDoList.mdwn b/Software/XlibToDoList.mdwn new file mode 100644 index 00000000..a07daf7f --- /dev/null +++ b/Software/XlibToDoList.mdwn @@ -0,0 +1,18 @@ + + +## Xlib To Do List + +A directory of [[Related Freedesktop.org To Do Projects|FreedesktopProjects]] is available. + +Xlib is the production [[Xlib|Software/X11]] binding to the X Window System protocol, but there are a few loose ends, as documented below. Contact Main.[[JimGettys|JimGettys]] about Xlib projects. Also see [[the XCB/XCL project|http://xcb.freedesktop.org/]] which is working on a possible replacement for Xlib and/or the core transport section of Xlib. +[[!table header="no" class="mointable" data=""" + **Project** | **Type** | **Description** | **Diff / Size** | **Comp.** + Locale | code | Redo locale support to use iconv - this would save 1/4 megabyte! | easy / small | 0% + Patches | review / code | Check all XFree86 patches since 4.3. | easy / small | 20% + K and R | code | Remove all K&R style function prototypes (after all patches have been checked) | easy / samll | 50% + Autotool | code | Help make sure the autotooled libraries build and work correctly on your favorite platforms | easy / small | 50% + Chuckit | code | Work on Xcb/Xcl to get them tested to the point the original transport code base can be chucked. It is nearly 20 years old, and could be done much better these days. Code is in CVS, though not the default version. Primarily, this needs extensive testing before being brought onto the head branch. | mod. / mod. | 25% + Lose | code | Make library report an event on connection failure, and allow applications to continue successfully in this case. | mod. / mod. | 50 % +"""]] + +-- Main.[[JimGettys|JimGettys]] - 12 Feb 2004 diff --git a/Software/burn.mdwn b/Software/burn.mdwn new file mode 100644 index 00000000..e6488f17 --- /dev/null +++ b/Software/burn.mdwn @@ -0,0 +1,7 @@ + + +## Libburn + +Libburn is an open source library suite for reading, mastering and writing optical discs. + +The Libburn webpage is at [[http://libburnia-project.org/wiki/Libburn|http://libburnia-project.org/wiki/Libburn]] diff --git a/Software/cppunit.mdwn b/Software/cppunit.mdwn new file mode 100644 index 00000000..7d456f5e --- /dev/null +++ b/Software/cppunit.mdwn @@ -0,0 +1,62 @@ +# cppunit test framework + +[[CppUnit]] is the C++ port of the famous JUnit framework for unit testing. Test output is in XML for automatic testing and GUI based for supervised tests. + +This is a continuation of the [[original cppunit project|http://cppunit.sourceforge.net/]]. + +[[!toc ]] + + +# Developers + + +## Getting the sources + +cppunit sources are stored in [[git|http://git-scm.com/]]. To get them, you can use: + + git clone git://anongit.freedesktop.org/git/libreoffice/cppunit/ + +or you can browse the code [[online|http://cgit.freedesktop.org/libreoffice/cppunit/]]. + +If you want to use release version you can fetch it from [[libreoffice mirror|http://dev-www.libreoffice.org/src/]]. + + +### Release Versions + +[[Cppunit 1.13.1|http://dev-www.libreoffice.org/src/cppunit-1.13.1.tar.gz]] MD5: fa9aa839145cdf860bf596532bb8af97 + +[[Cppunit 1.13.0|http://dev-www.libreoffice.org/src/cppunit-1.13.0.tar.gz]] MD5: f868f74647d29dbd793a16a0e5b48b88 + + +## Building it + + +### Dependencies + +Once the source has been checked out, cppunit can be built in usual manner: + + cd cppunit + ./autogen.sh + ./configure + make + make check # optional + make install + + +## Contributing + +Once you have done a change that you are happy with, and that builds with cppunit, contribute it back, we'll be happy to integrate it! Do: + + # commit your changes to your local repository + git commit -a + # create the patch + git format-patch origin/master + + +# Contact + +You can get in touch with us using multiple ways: + +1. using IRC server **irc.freenode.net** and joining channel **#libreoffice-dev** +1. using mailing list **[[libreoffice@lists.freedesktop.org|mailto:libreoffice@lists.freedesktop.org]]** +1. filling bugreport in [[Freedesktop bugzilla|http://bugs.freedesktop.org/]] diff --git a/Software/cups-pk-helper.mdwn b/Software/cups-pk-helper.mdwn new file mode 100644 index 00000000..5691924b --- /dev/null +++ b/Software/cups-pk-helper.mdwn @@ -0,0 +1,99 @@ + + +## cups-pk-helper + +cups-pk-helper is a [[PolicyKit|Software/PolicyKit]] helper to configure [[cups|http://www.cups.org/]] with fine-grained privileges. + +For example, it's possible to let users enable/disable printers without requiring a password, while still requiring a password for editing printer settings. + +To make it easy to integrate cups-pk-helper in [[system-config-printer|http://cyberelk.net/tim/software/system-config-printer/]], the D-Bus API is based to a large extent on the [[pycups|http://cyberelk.net/tim/software/pycups/]] one. + + +### Development + +The development occurs in git, in the [[cups-pk-helper|http://cgit.freedesktop.org/cups-pk-helper/]] repository. Bugs should be reported in [[Bugzilla|https://bugs.freedesktop.org/enter_bug.cgi?product=cups-pk-helper]]. + +Translations should be uploaded to [[Transifex|https://www.transifex.com/projects/p/cups-pk-helper/]]. + + +### Download + +Tarballs can be found at [[http://www.freedesktop.org/software/cups-pk-helper/releases/|http://www.freedesktop.org/software/cups-pk-helper/releases/]] + +* [[http://www.freedesktop.org/software/cups-pk-helper/releases/cups-pk-helper-0.2.4.tar.xz|http://www.freedesktop.org/software/cups-pk-helper/releases/cups-pk-helper-0.2.4.tar.xz]] + * Fix detection of CUPS version (Jürg Billeter, Vincent) +* [[http://www.freedesktop.org/software/cups-pk-helper/releases/cups-pk-helper-0.2.3.tar.xz|http://www.freedesktop.org/software/cups-pk-helper/releases/cups-pk-helper-0.2.3.tar.xz]] + * Fix security flaw in cupsGetFile/cupsPutFile wrappers (CVE-2012-4510) (Vincent) + * Escape printer/class names before putting them in URIs (Vincent) + * Be stricter when validating printer names (Vincent) + * Fix build with CUPS >= 1.6 (Jiri Popelka) + * New/updated translations: de, es, fi, ka, lv, pt_BR, sl, tr, zh_CN. +* [[http://www.freedesktop.org/software/cups-pk-helper/releases/cups-pk-helper-0.2.2.tar.xz|http://www.freedesktop.org/software/cups-pk-helper/releases/cups-pk-helper-0.2.2.tar.xz]] + * Add PrinterAddOption D-Bus method. (Marek Kasik) + * Set requesting-user-name tag in requests. (Marek Kasik) + * Code cleanups. (Vincent) + * Build fixes and improvements. (Vincent, Marek Kasik) + * New/updated translations: ja, nl, sk, zh_TW. +* [[http://www.freedesktop.org/software/cups-pk-helper/releases/cups-pk-helper-0.2.1.tar.bz2|http://www.freedesktop.org/software/cups-pk-helper/releases/cups-pk-helper-0.2.1.tar.bz2]] + * Do not pass ppd file if empty when adding a printer. (Tim Waugh) + * Accept NULL for ppd file as valid when adding a printer. (Vincent) + * Allow inactive/any users to authenticate. (Marek Kasik) + * New/udpated translations: gl, it, ko, zh_TW. +* [[http://www.freedesktop.org/software/cups-pk-helper/releases/cups-pk-helper-0.2.0.tar.bz2|http://www.freedesktop.org/software/cups-pk-helper/releases/cups-pk-helper-0.2.0.tar.bz2]] + * Port to GDBus. (Vincent) + * Stop using deprecated polkit API. (Vincent) + * Drop gthread handling. (Vincent) + * Add org.freedesktop.DBus.Deprecated annotation to [[JobCancel|JobCancel]]. (Vincent) + * Code cleanups. (Vincent) + * Build system improvements. (Vincent) + * New/udpated translations: hu. +* [[http://www.freedesktop.org/software/cups-pk-helper/releases/cups-pk-helper-0.1.3.tar.bz2|http://www.freedesktop.org/software/cups-pk-helper/releases/cups-pk-helper-0.1.3.tar.bz2]] + * Allow file request with NULL filename, to add raw printers. (Marek Kašík) + * Modernize build system a bit. (Vincent) + * New/udpated translations: eo, id, pl, sl, uk. +* [[http://www.freedesktop.org/software/cups-pk-helper/releases/cups-pk-helper-0.1.2.tar.bz2|http://www.freedesktop.org/software/cups-pk-helper/releases/cups-pk-helper-0.1.2.tar.bz2]] + * Add all-edit action to enable authenticating only once in tools (Marek Kašík) + * Build system improvements. (Vincent) + * New/udpated translations: fr, hu, it, pl, tr, uk. +* [[http://www.freedesktop.org/software/cups-pk-helper/releases/cups-pk-helper-0.1.1.tar.bz2|http://www.freedesktop.org/software/cups-pk-helper/releases/cups-pk-helper-0.1.1.tar.bz2]] + * Make the include/exclude schemes work when getting devices with cups 1.4 (Dominique Leuenberger) + * Fix confusion between IPP and HTTP status when getting/putting a file (Vincent) + * Clarify a string. (Vincent) + * Add some basic documentation. (Vincent) + * Build system improvements. (Vincent) + * First translations: cz (Mrs Jenkins), de (Andre Klapper), fr (Vincent). +* [[http://www.freedesktop.org/software/cups-pk-helper/releases/cups-pk-helper-0.1.0.tar.bz2|http://www.freedesktop.org/software/cups-pk-helper/releases/cups-pk-helper-0.1.0.tar.bz2]] + * Port to PolicyKit 1. (Marek Kasik, Vincent) + * Add DevicesGet method. (Marek Kasik, Vincent) + * Add JobCancelPurge method. (Marek Kasik) + * Support adding printer without device URI. (Tim Waugh) + * Add check for string length in validity checks. (Vincent) + * Improve performance of job-related methods. (Marek Kasik) + * Make sure to correctly handle all CUPS replies. (Vincent) + * Avoid timeout on job-related methods for invalid jobs. (Vincent) + * Always return a non-empty error string in case of failures. (Vincent) + * Remove GTK+/GIO requirements. (Vincent) + * Minor fixes and improvements in tests. (Vincent) + * Code cleanups. (Vincent) + * Build system improvements. (Vincent) +* [[http://www.freedesktop.org/software/cups-pk-helper/releases/cups-pk-helper-0.0.4.tar.bz2|http://www.freedesktop.org/software/cups-pk-helper/releases/cups-pk-helper-0.0.4.tar.bz2]] + * Remove bare send_interface lines in the DBus rules. + * Add job related functions. (Marek Kasik) + * Reconnect to the cups server if necessary. (Marek Kasik) + * Accept file: URI as local. (Marek Kasik) + * Change default policy for job-edit to yes (jobs are owned by the user). + * Add more checks for the new job-related functions. + * Code cleanups. +* [[http://www.freedesktop.org/software/cups-pk-helper/releases/cups-pk-helper-0.0.3.tar.bz2|http://www.freedesktop.org/software/cups-pk-helper/releases/cups-pk-helper-0.0.3.tar.bz2]] + * Make PrinterAddOptionDefault work for options with more than one value. + * Implement PrinterSetUsersAllowed/PrinterSetUsersDenied methods. + * Implement ServerGetSettings/ServerSetSettings methods. + * Implement ClassAddPrinter/ClassDeletePrinter/ClassDelete methods. + * Add more fine-grained policies, including local vs remote printers. + * Fix major bug that made it impossible to change many settings. + * Implement FileGet/FilePut methods. +* [[http://www.freedesktop.org/software/cups-pk-helper/releases/cups-pk-helper-0.0.2.tar.bz2|http://www.freedesktop.org/software/cups-pk-helper/releases/cups-pk-helper-0.0.2.tar.bz2]] + * Make the AcceptJobs method work. + * Add checks to arguments passed over dbus, for more security. +* [[http://www.freedesktop.org/software/cups-pk-helper/releases/cups-pk-helper-0.0.1.tar.bz2|http://www.freedesktop.org/software/cups-pk-helper/releases/cups-pk-helper-0.0.1.tar.bz2]] + * Initial release.
\ No newline at end of file diff --git a/Software/dbus-c++.mdwn b/Software/dbus-c++.mdwn new file mode 100644 index 00000000..4ca89553 --- /dev/null +++ b/Software/dbus-c++.mdwn @@ -0,0 +1,2 @@ + +All services are moved to [[SourceForge|SourceForge]] [[http://sourceforge.net/projects/dbus-cplusplus/|http://sourceforge.net/projects/dbus-cplusplus/]]. There's also a new wiki at [[http://sourceforge.net/apps/mediawiki/dbus-cplusplus/index.php?title=Main_Page|http://sourceforge.net/apps/mediawiki/dbus-cplusplus/index.php?title=Main_Page]] Please visit it and bookmark new website. diff --git a/Software/dbus-c++/documentation.mdwn b/Software/dbus-c++/documentation.mdwn new file mode 100644 index 00000000..7798e5b7 --- /dev/null +++ b/Software/dbus-c++/documentation.mdwn @@ -0,0 +1,12 @@ + +This page is a start of a dbus-c++ documentation. If more content is written here one may decide to write a more comprehensive documentation. Feel free to add new content. + + +## Introspect + + +### Basic type mappings + +**Hint:** Please someone with knowlegde should add that to a table. I'm going crazy with that Wiki. + +Variant ==> "v" Byte ==> "y" Bool ==> "b" Int16 ==> "n" UInt16 ==> "q" Int32 ==> "i" UInt32 ==> "u" Int64 ==> "x" UInt64 ==> "t" Double ==> "d" String ==> "s" Path ==> "o" Signature ==> "g" Invalid ==> "" diff --git a/Software/dbus-cpp.mdwn b/Software/dbus-cpp.mdwn new file mode 100644 index 00000000..de5aee00 --- /dev/null +++ b/Software/dbus-cpp.mdwn @@ -0,0 +1,30 @@ + + +## dbus-cpp + +dbus-cpp attempts to provide a C++ API for D-BUS. + +**Hint:** dbus-cpp is abandoned in favor of [[dbus-c++|Software/dbus-c++]] + + +### Mailinglist + +All dbus-cpp discussion is currently on [[dbus@lists.freedesktop.org|http://lists.freedesktop.org/mailman/listinfo/dbus/]]. + + +### CVS + +The [[CVS|GettingInvolved]] module for this software is "dbus". You can browse it with [[ViewCVS|http://cvs.freedesktop.org/dbus/dbus-cpp/]]. + +CVS commits can be monitored on the [[dbus-commit|http://freedesktop.org/mailman/listinfo/dbus-commit/]] mailing list. + + +### Bugs & Patches + +Please report bugs (and submit patches) through the freedesktop.org [[Bugzilla|https://bugs.freedesktop.org/]]. + + +### Docs + + +### Download diff --git a/Software/dbus.mdwn b/Software/dbus.mdwn new file mode 100644 index 00000000..659f6129 --- /dev/null +++ b/Software/dbus.mdwn @@ -0,0 +1,127 @@ +[[!table header="no" class="mointable" data=""" +**Contents** +[[!toc ]] +"""]] + + +# What is D-Bus? + +D-Bus is a message bus system, a simple way for applications to talk to one another. In addition to interprocess communication, D-Bus helps coordinate process lifecycle; it makes it simple and reliable to code a "single instance" application or daemon, and to launch applications and daemons on demand when their services are needed. + +D-Bus supplies both a system daemon (for events such as "new hardware device added" or "printer queue changed") and a per-user-login-session daemon (for general IPC needs among user applications). Also, the message bus is built on top of a general one-to-one message passing framework, which can be used by any two apps to communicate directly (without going through the message bus daemon). Currently the communicating applications are on one computer, or through unencrypted TCP/IP suitable for use behind a firewall with shared NFS home directories. (Help wanted with [[better remote transports|Software/DBusRemote]] - the transport mechanism is well-abstracted and extensible.) + +The D-Bus [[low-level API reference implementation|http://dbus.freedesktop.org/doc/api/html/index.html]] and [[protocol|http://dbus.freedesktop.org/doc/dbus-specification.html]] have been heavily tested in the real world over several years, and are now "set in stone." Future changes will either be compatible or versioned appropriately. + +The low-level libdbus reference implementation has no required dependencies; the bus daemon's only *required* dependency is an XML parser (expat). Higher-level bindings specific to particular frameworks (Qt, GLib, Java, C#, Python, etc.) add more dependencies, but can make more assumptions and are thus much simpler to use. The bindings evolve separately from the low-level libdbus, so some are more mature and ABI-stable than others; check the docs for the binding you plan to use. + +There are also some reimplementations of the D-Bus protocol for languages such as C#, Java, and Ruby. These do not use the libdbus reference implementation. + +It should be noted that the low-level implementation is not primarily designed for application authors to use. Rather, it is a basis for binding authors and a reference for reimplementations. If you are able to do so it is recommended that you use one of the higher level bindings or implementations. A list of these can be found on the [[bindings page|Software/DBusBindings]]. + +The [[list of projects using D-Bus|Software/DbusProjects]] is growing and they provide a wealth of examples of using the various APIs to learn from. + +D-Bus is very portable to any Linux or UNIX flavor, and a port to Windows is in progress. + +If you have any trouble with D-Bus or suggestions for improvement, bug reports and comments are very welcome. + +Get on D-Bus today! + + +# Mailing List + +All D-Bus discussion is currently on [[dbus@lists.freedesktop.org|http://lists.freedesktop.org/mailman/listinfo/dbus/]]. + + +# Reporting Bugs & Sending Patches + +Please report bugs (and submit patches) through the freedesktop.org [[Bugzilla|https://bugs.freedesktop.org/]]. + +Ideally, include test suite coverage with your patch; or if you report a bug, it's good to add a test that fails even if you don't have a patch otherwise. You can see test coverage stats in the GNOME build bot results, at [[http://build.gnome.org:8080/coverage/dbus/lcov/|http://build.gnome.org:8080/coverage/dbus/lcov/]] (note, coverage is understated since it counts the test code itself in the coverage, and the test suite does not test itself, in particular all the "test failed" codepaths are not covered). + +Patches to improve test coverage are very welcome, though D-Bus is already among the best-covered codebases around. + + +# Documentation + +Some stuff from the doc/ subdirectory is prebuilt and browsable here. If you're new to D-Bus, the tutorial is probably the best place to start (even though it is very incomplete, the basics are covered). + +Generic D-Bus protocol information: + +* [[D-Bus specification|http://dbus.freedesktop.org/doc/dbus-specification.html]] +* [[D-Bus Overview|http://packages.python.org/txdbus/dbus_overview.html]] from the txdbus documentation +* [[An introduction to the basics|IntroductionToDBus]] by Jeroen Vermeulen +* [[Introduction to D-Bus|http://doc.trolltech.com/4.2/intro-to-dbus.html]] from the Qt documentation +* [[FAQ|http://dbus.freedesktop.org/doc/dbus-faq.html]] +* Overview picture [[png|http://dbus.freedesktop.org/doc/diagram.png]] [[svg|http://dbus.freedesktop.org/doc/diagram.svg]] +* [[D-Bus tutorial (incomplete, has stuff on several bindings and reimplementations)|http://dbus.freedesktop.org/doc/dbus-tutorial.html]] +* [[Config file DTD|http://dbus.freedesktop.org/doc/busconfig.dtd]] +* If you are confused about some of the concepts in DBus, look at [[some analogies|Software/DBusAnalogy]] +* Some [[tools|Software/DbusTools]] for working with D-Bus. +Please note that the D-Bus spec is incomplete, especially in its description of the message bus daemon. The spec for the protocol itself is reasonably complete, though not always clear or precise. Your patches are welcome! In the meantime, you may need to supplement your reading of the spec with a reading of the reference implementation source code. + +Docs specific to the reference implementation: + +* [[API reference manual for the reference implementation (libdbus)|http://dbus.freedesktop.org/doc/api/html/index.html]] +* [[@todo items from reference implementation manual|http://dbus.freedesktop.org/doc/dbus/api/html/todo.html]] and high-level [[TODO|http://dbus.freedesktop.org/doc/TODO]] +* [[Browse reference implementation source|http://dbus.freedesktop.org/doc/dbus/api/html/files.html]] +* [[dbus-daemon(1)|http://dbus.freedesktop.org/doc/dbus-daemon.1.html]] (includes configuration file docs) +* [[dbus-send(1)|http://dbus.freedesktop.org/doc/dbus-send.1.html]] [[dbus-monitor(1)|http://dbus.freedesktop.org/doc/dbus-monitor.1.html]] [[dbus-launch(1)|http://dbus.freedesktop.org/doc/dbus-launch.1.html]] [[dbus-uuidgen(1)|http://dbus.freedesktop.org/doc/dbus-uuidgen.1.html]] +* [[HACKING|http://dbus.freedesktop.org/doc/HACKING]] [[AUTHORS|http://dbus.freedesktop.org/doc/AUTHORS]] +* [[NEWS|http://dbus.freedesktop.org/doc/NEWS]] [[ChangeLog|http://dbus.freedesktop.org/doc/ChangeLog]] [[README|http://dbus.freedesktop.org/doc/README]] +* [[Test plan|http://dbus.freedesktop.org/doc/dbus-test-plan.html]] +* [[Tarball|http://www.freedesktop.org/software/dbus/dbus-docs.tar.gz]] with most of the above docs. +Keep in mind that libdbus is a low-level library, intended to be the backend for a language binding and with extra complexity needed to implement dbus-daemon. You will save yourself a lot of pain if you use a higher-level wrapper or a reimplementation. Documentation of these is usually linked from the [[bindings page|Software/DBusBindings]]. + +Articles from around the web, including some tutorials: + +* [["Connect desktop apps using D-BUS" (IBM developerWorks)|http://www-128.ibm.com/developerworks/linux/library/l-dbus.html?ca=dgr-lnxw95D-BUS]] by Ross Burton (July 2004) +* [["Get on D-BUS" (Red Hat Magazine)|http://www.redhat.com/magazine/003jan05/features/dbus/]] by John Palmieri (January 2005) +* [["Get on the D-BUS" (Linux Journal)|http://www.linuxjournal.com/article/7744]] by Robert Love (January 2005) +* [["The DBus missing tutorial - DBus Activation"|http://raphael.slinckx.net/dbustutorial.php]] by Raphaël Slinckx (2005) +* [[D-Bus Low-Level API Tutorial|http://dbus.freedesktop.org/doc/dbus/libdbus-tutorial.html]] by Matthew Johnson (Nov 2005) +* [[Introduction To D-BUS|http://techbase.kde.org/Development/Tutorials/D-Bus/Introduction]] by Aaron Seigo & KDE community (2007) +* [["An Introduction to the D-Bus Language Binding for ooRexx"|http://wi.wu.ac.at/rgf/rexx/orx22/201112-DBus4ooRexx-article.pdf]] by Rony G. Flatscher (December 2011, Intro to D-Bus concepts followed by intro to the ooRexx bindings) + +# Download + + +## Reference Implementation (dbus-daemon and libdbus) + +Released versions of D-Bus can be downloaded from the [[releases directory on dbus.freedesktop.org|http://dbus.freedesktop.org/releases/dbus/]] and are available in all major Linux distributions. If in doubt, use your distribution's packages. + +The current **stable** branch is [[D-Bus 1.6.x|http://cgit.freedesktop.org/dbus/dbus/tree/NEWS?h=dbus-1.6]]. This is the recommended version for most purposes. + +The current **legacy** branches are [[D-Bus 1.2.x|http://cgit.freedesktop.org/dbus/dbus/tree/NEWS?h=dbus-1.2]] and [[D-Bus 1.4.x|http://cgit.freedesktop.org/dbus/dbus/tree/NEWS?h=dbus-1.4]]. These are still supported but only for security fixes: only use these versions when upgrading from older stable releases. Security support for 1.2.x will end when Debian 7.0 is released. + +The current **development** branch is [[D-Bus 1.7.x|http://cgit.freedesktop.org/dbus/dbus/tree/NEWS?h=master]], which will lead to a 1.8.x stable branch in future. + + +## Bindings and Independent Implementations + +Bindings and independent implementations are linked to from the [[Bindings Page|Software/DBusBindings]]. + +A binding wraps libdbus (and thus automatically gets e.g. new authentication mechanisms and other additions to libdbus), while a reimplementation codes the protocol from scratch (and thus avoids a dependency on the libdbus C library, but has to be kept in sync with new features). We are working on a hybrid approach where libdbus can be used to set up connections but bindings don't use the message queue or message marshaling from libdbus. + + +# Windows port + +The Windows port from the windbus and dbus4win projects has been merged into the freedesktop dbus development branch and the spec has been updated with windows specific stuff. Many thanks to the people who worked on the windows port (in alphabetic order): + +Marcus Brinkmann, Nguyễn Thái Ngọc Duy, Christian Ehrlicher, Peter Kümmel, Tor Lillqvist, Ralf Habacker, Frank Osterfeld, Marc Mutz, Romain Pokrzywka, Ole André Vadla Ravnås, Sebastian Sauer + +The windows port is knowing to work on Windows XP, Windows Vista and Windows 7, supported compiler/sdk are MSVC 2010, mingw-w32/w64(gcc) and cygwin(gcc). + +Everyone interested in having stable dbus on windows is invited to test the implementation, to reports bugs and/or to file patches. + + +# Grab the Source + +The core dbus code and the language bindings are under version control using Git. There is a [[nice tutorial for using git with freedesktop.org projects|http://freedesktop.org/wiki/Infrastructure/git]]. There is also [[another tutorial at IBM Developerworks site|http://www-128.ibm.com/developerworks/linux/library/l-git/]]. + +All components of dbus are in the dbus/ subdirectory. + +[[View the reference implementation in gitweb|http://cgit.freedesktop.org/dbus/dbus/]] + +Anonymous git for reference implementation: git://anongit.freedesktop.org/git/dbus/dbus + +Developer git for reference implementation: [[ssh://git.freedesktop.org/git/dbus/dbus|ssh://git.freedesktop.org/git/dbus/dbus]] diff --git a/Software/dbus/RunningClientsWithValgrind.mdwn b/Software/dbus/RunningClientsWithValgrind.mdwn new file mode 100644 index 00000000..d156412f --- /dev/null +++ b/Software/dbus/RunningClientsWithValgrind.mdwn @@ -0,0 +1,7 @@ + + +## Running D-Bus clients with Valgrind + +See README.valgrind in dbus source distributions. + +Latest version: <[[http://cgit.freedesktop.org/dbus/dbus/tree/README.valgrind>|http://cgit.freedesktop.org/dbus/dbus/tree/README.valgrind>]] diff --git a/Software/desktop-file-utils.mdwn b/Software/desktop-file-utils.mdwn new file mode 100644 index 00000000..b6f26f5a --- /dev/null +++ b/Software/desktop-file-utils.mdwn @@ -0,0 +1,173 @@ + + +## desktop-file-utils + +desktop-file-utils contains a few command line utilities for working with [[desktop entries|Specifications/desktop-entry-spec]]: + +* desktop-file-validate: validates a desktop file and prints warnings/errors about desktop entry specification violations. +* desktop-file-install: installs a desktop file to the applications directory, optionally munging it a bit in transit. +* update-desktop-database: updates the database containing a cache of MIME types handled by desktop files. +It requires [[GLib|http://download.gnome.org/sources/glib/]] to compile, because the implementation requires Unicode utilities and such. + + +### Development + +The development occurs in git, in the [[xdg/desktop-file-utils|http://cgit.freedesktop.org/xdg/desktop-file-utils/]] repository. Bugs should be reported in [[Bugzilla|https://bugs.freedesktop.org/enter_bug.cgi?product=desktop-file-utils]]. + + +### Download + +Tarballs can be found at [[http://www.freedesktop.org/software/desktop-file-utils/releases/|http://www.freedesktop.org/software/desktop-file-utils/releases/]] + +* [[http://www.freedesktop.org/software/desktop-file-utils/releases/desktop-file-utils-0.21.tar.xz|http://www.freedesktop.org/software/desktop-file-utils/releases/desktop-file-utils-0.21.tar.xz]] + * desktop-file-validate + * update to current version of menu specification (Vincent): + * only print hint if no main category is present, not an error + * make Science a main category + * add new registered categories: Adult, Feed, Humanities, Maps, Shooter, Spirituality, XFCE + * update related categories + * add TDE to list of registered OnlyShowIn + * accept and validate GNOME3/GSettings for AutostartCondition (Vincent) + * output hint if more than one main category is present (Vincent) + * output hint about suggested related categories (Vincent) + * misc + * do not require glib >= 2.28 for build (Vincent) +* [[http://www.freedesktop.org/software/desktop-file-utils/releases/desktop-file-utils-0.20.tar.xz|http://www.freedesktop.org/software/desktop-file-utils/releases/desktop-file-utils-0.20.tar.xz]] + * desktop-file-install + * fix list of locale strings without trailing slash (Matthias Clasen) + * desktop-file-validate + * add MATE and Razor to list of registered environments (Vincent) + * validate Desktop Actions (Giovanni Campagna, Vincent) +* [[http://www.freedesktop.org/software/desktop-file-utils/releases/desktop-file-utils-0.19.tar.xz|http://www.freedesktop.org/software/desktop-file-utils/releases/desktop-file-utils-0.19.tar.xz]] + * desktop-file-install + * respect order of edit options (Vincent) + * add --add-not-show-in/--remove-not-show-in options (Vincent) + * add options to set Name, [[GenericName|GenericName]], Comment, Icon keys (Vincent) + * add --set-key/--set-value options to set an arbitrary key (Vincent) + * remove localized keys when setting/removing a key (Vincent) + * copy translations when copying a key (Vincent) + * create a desktop-file-edit symlink to desktop-file-install to simply edit .desktop files (without having to pass --dir) (Vincent) + * look at RPM_BUILD_ROOT to know where to install desktop files + * minor UI improvements (Vincent) + * desktop-file-validate + * add Unity to list of registered environments (Vincent) + * deal with various zz-application/zz-winassoc-XXX mime types (Vincent) + * mark all zz-application/* MIME types as aliases (Vincent) + * add support for updated Keywords key (Vincent) + * update-desktop-database + * deal with various zz-application/zz-winassoc-XXX mime types (Vincent) + * mark all zz-application/* MIME types as aliases (Vincent) + * ignore desktop files with Hidden=true (Vincent) + * misc + * modernize build system a bit (Vincent) + * update man pages (Vincent) +* [[http://www.freedesktop.org/software/desktop-file-utils/releases/desktop-file-utils-0.18.tar.bz2|http://www.freedesktop.org/software/desktop-file-utils/releases/desktop-file-utils-0.18.tar.bz2]] + * desktop-file-validate + * accept x-scheme-handler/* mime types (Vincent) + * update-desktop-database + * sort mime types alphabetically in generated cache (Vincent) + * accept x-scheme-handler/* mime types (Vincent) + * misc + * improve build system (Vincent) + * minor documentation fixes (Vincent) +* [[http://www.freedesktop.org/software/desktop-file-utils/releases/desktop-file-utils-0.17.tar.bz2|http://www.freedesktop.org/software/desktop-file-utils/releases/desktop-file-utils-0.17.tar.bz2]] + * desktop-file-validate + * accept chemical/* mime types as valid types (Vincent) + * make icon names with an extension for Icon key a non-fatal error (Vincent) + * update-desktop-database + * accept chemical/* mime types as valid types (Vincent) + * ignore --verbose if --quiet is also passed (Vincent) + * make sure to always output lists in the keyfile we generate (Vincent) + * misc + * improve build system (Vincent) + * update documentation (Vincent) + * add man pages (Vincent) +* [[http://www.freedesktop.org/software/desktop-file-utils/releases/desktop-file-utils-0.16.tar.bz2|http://www.freedesktop.org/software/desktop-file-utils/releases/desktop-file-utils-0.16.tar.bz2]] + * desktop-file-install + * do not unlink the destination file if it's the same as the source file in desktop-file-install (Vincent) + * desktop-file-validate + * check that a main category is included in the Categories (Vincent) + * check that categories required by another one are present (Vincent) + * do not always show warnings about KDE specific uses (Vincent) + * check that the Comment does not look like the Name and the [[GenericName|GenericName]] (Vincent) + * display error about multiple keys with the same name earlier (Vincent) + * improve MIME type check to make sure that the MIME types are valid (Vincent) + * add LXDE in the list of registered [[OnlyShowIn|OnlyShowIn]] values (Vincent) + * add "warning" to error strings to make them easily greppable (Vincent) + * handle [[AutostartCondition|AutostartCondition]] key, as proposed for the autostart specification and used in GNOME (Vincent) + * accept empty Categories key as valid (Vincent) + * make new errors non-fatal to give some time to maintainers to fix their .desktop file after a release of desktop-file-utils (Vincent) + * plug leak (Vincent) + * code cleanups (Vincent) + * update-desktop-database + * improve MIME type check to make sure that the MIME types are valid (Vincent) + * improve error messages (Erik Hovland, Vincent) + * fix format string vulnerability warning (Vincent) + * misc + * use AM_SILENT_RULES (Vincent) + * improve build system (Vincent) +* [[http://www.freedesktop.org/software/desktop-file-utils/releases/desktop-file-utils-0.15.tar.gz|http://www.freedesktop.org/software/desktop-file-utils/releases/desktop-file-utils-0.15.tar.gz]] + * make the extension check for Icon key a warning instead of an error for now (Ray Strode) + * Fix a crash in update-desktop-database when there's no group (Vincent) + * Fix a crash in the validator happening for very small lines (Vincent) +* [[http://www.freedesktop.org/software/desktop-file-utils/releases/desktop-file-utils-0.14.tar.gz|http://www.freedesktop.org/software/desktop-file-utils/releases/desktop-file-utils-0.14.tar.gz]] + * update of the Emacs editing mode for .desktop files (Ville Skyttä) + * make desktop-file-install print an error when trying to install a non-existing desktop file, or a desktop file that can't be read (Vincent) + * make the validator check the content of the Icon key (Vincent) + * make the validator accept X-Foo as a valid environment (this was added to the spec) (Stanislav Brabec, Vincent) + * really handle the -m command line argument for desktop-file-install (Matthias Clasen) + * make desktop-file-install accept as one valid argument multiple categories/only-show-in/mime-types values. Now --add-category="GNOME;GTK" works as expected. (Vincent) + * make desktop-file-install validate the created desktop file before removing the original file, and unlink it if it's not valid (Vincent) + * code cleanups for desktop-file-install (Vincent) +* [[http://www.freedesktop.org/software/desktop-file-utils/releases/desktop-file-utils-0.13.tar.gz|http://www.freedesktop.org/software/desktop-file-utils/releases/desktop-file-utils-0.13.tar.gz]] + * rewrite validator, and update it for desktop entry specification 1.0. The validator should be stricter and report more useful messages. (Vincent) + * add --warn-kde and --no-warn-deprecated command line options to desktop-file-validate (Vincent) + * port desktop-file-install to GKeyFile (Vincent) + * don't require --vendor for desktop-file-install (Vincent) + * some general module cleanup (Vincent) +* [[http://www.freedesktop.org/software/desktop-file-utils/releases/desktop-file-utils-0.12.tar.gz|http://www.freedesktop.org/software/desktop-file-utils/releases/desktop-file-utils-0.12.tar.gz]] + * improves category validation code to not catch false positives (Vincent Fretin, Ville Skyttä, Ray Strode, Vincent Untz) + * make category validation code non-fatal (Ray) + * fix mem leaks and double frees (Pascal Terjan) +* [[http://www.freedesktop.org/software/desktop-file-utils/releases/desktop-file-utils-0.11.tar.gz|http://www.freedesktop.org/software/desktop-file-utils/releases/desktop-file-utils-0.11.tar.gz]] + * Validate desktop file categories (Emmet Hikory, Vincent Untz) + * Use GKeyFile instead of the old egg code in update-desktop-database (Vincent) + * Use GOption instead of popt (Vincent) + * Fix grammar problem in one of the strings (Moritz Barsnick) + * NULL terminate search patch in update-desktop-database (Mike Hearn) + * Fix language to encoding mapping to match spec (Ville Skyttä) +* [[http://www.freedesktop.org/software/desktop-file-utils/releases/desktop-file-utils-0.10.tar.gz|http://www.freedesktop.org/software/desktop-file-utils/releases/desktop-file-utils-0.10.tar.gz]] + * Remove all menus code (Mark [[McLoughlin|McLoughlin]]) + * Don't try and add key/value pairs to comments (Miloslav Trmac) +* [[http://www.freedesktop.org/software/desktop-file-utils/releases/desktop-file-utils-0.9.tar.gz|http://www.freedesktop.org/software/desktop-file-utils/releases/desktop-file-utils-0.9.tar.gz]] + * Many update-desktop-database improvements (Ray Strode, Dan Williams) + * Fix desktop-file-install --remove-only-show-in (Ray Strode) +* [[http://www.freedesktop.org/software/desktop-file-utils/releases/desktop-file-utils-0.8.tar.gz|http://www.freedesktop.org/software/desktop-file-utils/releases/desktop-file-utils-0.8.tar.gz]] + * Fix various leaks (Kjartan Maraas) + * Update with latest libegg code (Ray Strode) + * Menu method work (Mark [[McLoughlin|McLoughlin]], Dan Williams) + * Reload the menu when .desktop/.directory files change + * Respect [[NoDisplay|NoDisplay]] in .desktop/.directory files + * Remove empty submenus + * Report the last modification time of the tree + * Support setting the [[OnlyShowIn|OnlyShowIn]] name + * Add a reasonable default set of schemes +* [[http://www.freedesktop.org/software/desktop-file-utils/releases/desktop-file-utils-0.7.tar.gz|http://www.freedesktop.org/software/desktop-file-utils/releases/desktop-file-utils-0.7.tar.gz]] + * Add update-desktop-database (Ray Strode) + * Emacs editing mode for .desktop files (Ville Skyttä) + * Update to latest spec, improve error messages (Ville Skyttä) + * Warning fixes (Mark [[McLoughlin|McLoughlin]]) + * distcheck fixes (Jonathan Blandford) +* [[http://www.freedesktop.org/software/desktop-file-utils/releases/desktop-file-utils-0.6.tar.gz|http://www.freedesktop.org/software/desktop-file-utils/releases/desktop-file-utils-0.6.tar.gz]] + * Bring up to date with version 0.8 of the menu spec + * Don't crash when a .desktop file is a symlink to a non-existant file +* [[http://www.freedesktop.org/software/desktop-file-utils/releases/desktop-file-utils-0.5.tar.gz|http://www.freedesktop.org/software/desktop-file-utils/releases/desktop-file-utils-0.5.tar.gz]] + * Don't segfault with .desktop files which have a leading comment +* [[http://www.freedesktop.org/software/desktop-file-utils/releases/desktop-file-utils-0.4.tar.gz|http://www.freedesktop.org/software/desktop-file-utils/releases/desktop-file-utils-0.4.tar.gz]] + * Add support for "Desktop Action" sections +* [[http://www.freedesktop.org/software/desktop-file-utils/releases/desktop-file-utils-0.3.tar.gz|http://www.freedesktop.org/software/desktop-file-utils/releases/desktop-file-utils-0.3.tar.gz]] + * Create target dir of desktop-file-install if nonexistent; improve some error messages; fix [[OnlyShowIn|OnlyShowIn]] handling; add --print-available option to dump desktop files being considered by desktop-menu-tool; rename obsolete [KDE Desktop Entry] section if found; fix a crash; verify proper spelling of KDE and GNOME in [[OnlyShowIn|OnlyShowIn]]; add a --remove-key option; check that string lists end in a semicolon; add --copy-name-to-generic-name and vice versa; fix bug in --delete-original that made it not work +* [[http://www.freedesktop.org/software/desktop-file-utils/releases/desktop-file-utils-0.2.tar.gz|http://www.freedesktop.org/software/desktop-file-utils/releases/desktop-file-utils-0.2.tar.gz]] + * Adds desktop-menu-tool to parse vfolder menus and generate a symlink tree or just print them out. +* [[http://www.freedesktop.org/software/desktop-file-utils/releases/desktop-file-utils-0.1.tar.gz|http://www.freedesktop.org/software/desktop-file-utils/releases/desktop-file-utils-0.1.tar.gz]] + * Initial release. Contains desktop-file-validate and desktop-file-install.
\ No newline at end of file diff --git a/Software/dri.mdwn b/Software/dri.mdwn new file mode 100644 index 00000000..80733dea --- /dev/null +++ b/Software/dri.mdwn @@ -0,0 +1,4 @@ + +Please visit the DRI wiki at [[http://dri.freedesktop.org/wiki/|http://dri.freedesktop.org/wiki/]] + +Binary snapshots are available at [[http://dri.freedesktop.org/snapshots|http://dri.freedesktop.org/snapshots]] as convenience for testers. Please provide feedback! diff --git a/Software/dvfs.mdwn b/Software/dvfs.mdwn new file mode 100644 index 00000000..90ab0090 --- /dev/null +++ b/Software/dvfs.mdwn @@ -0,0 +1,254 @@ + + +## Desktop VFS + +Desktop VFS aims to provide a system allowing desktop-oriented applications, such as file managers and office applications among others, to have access to remote data storage facilities using a Virtual File System API. + +D-VFS is a new API which will be designed to simplify common tasks and make new operations available that existing APIs do not support at all. The primary target of D-VFS is the Desktop and the applications that run there, which means that the API will be ideal for those uses while possibly no so ideal for console or server applications. A [[FUSE|http://fuse.sourceforge.net]] module may be provided in the future to allow applications that do not natively use D-VFS to utilize D-VFS. D-VFS will utilize URIs for referencing files and folders. + +D-VFS is in the first stages of design. The requirements and api are being fleshed out at this location. Adding your comments to the design of D-VFS is very simple. First, get a freedesktop [[login|UserPreferences]]. Second, edit this page by hitting the icon. Once you have edited this page, you will be signed up for email notifications of any future edits on this page. + +Except where noted, the following was written by [[SeanMiddleditch|SeanMiddleditch]]. (If you make additions, edits, or comments, please identify your changes.) + + +## Requirements + +Desktop VFS is intended to be used primarily by desktop apps like office suites and by desktop file managers like Nautilus or Konqueror. These applications have a certain set of operations which they must perform in order to operate correctly. + +* Save and load documents +* Manipulate document metadata +* List files in a folder +* Move, copy, and delete documents +* Create, move, copy, and delete folders +In addition to the basic required operations, additional operations may be required by some applications in order to perform efficiently. + +* Seeking backward +* Seeking forward +* Request a portion of a file +* Append a file +There are certain qualities of the API which are required in order for most desktop applications to function properly, + +* Event-based (asynchronous) API +* Complete error reporting with user-oriented messages available +* Monitor progress of any operation +* Cancel any in-progress operation +* Resume operations with non-critical errors ("failed to make backup; save anyhow?") +* Threadsafe ([[AlexanderLarsson|AlexanderLarsson]] says being non-threadsafe is a real problem in gnome-vfs developers run into) +* Change notification for folders and documents +* Atomic operations when possible +* Query capabilities of backend/protocol +* Good versioning and API/ABI compatibility practices +There are additional features that, while not strictly necessary, can make using D-VFS more pleasant or increase the ease with which applications may be ported. + +* Push/pull (pseudo-synchronous) API +* FUSE backend +* Locking +Finally, there are esoteric features that are (currently) rarely used, but which may be useful in the future. These can be added to D-VFS after the first version ships if necessary. + +* Rollback and versioning +* Meta-data querying (search) +* Encryption and decryption +* Compression +One of the main purposes of D-VFS is to allow seamless access to files on remote file stores. Some of the more important protocols that D-VFS will support include WebDAV, SMB/CIFS, FTP, and SCP/SFTP. Protocols which may have (limited) support include plain HTTP and FTP. Some of the more esoteric or rare protocols will not likely be supported directly, although D-VFS will allow developers to supply their own backends to support new protocols. + + +## Rationalization + + +### Save and Load Interface + +The vast majority of applications do only two things to all files they access. They either open the file in read mode and sequentially read the entire file or they open the file in write mode and sequentially write out the entire file. + +As those are two of the most used, if not _the_ most used, operations that a VFS must perform, it makes sense that both of those operations be as simple as possible. It is also vital that those operations work appropriately for the needs a GUI application. + +The D-VFS will attempt to make asynchronous reads and writes of whole files as simple as possible. Higher layers will offer synchronous versions of these APIs for even easier development. + + +### Asynchronous Interface + +GUI applications need to remain responsive at all times to external events, such as user input events or windowing system commands. If you've ever seen an application window get "ghosted" while it was processing some data, then you've seen the outcome of having an application become unresponsive to events. + +Because D-VFS will offer seamless access to remote file systems where latency and bandwidth can often make simple operations take a long time, D-VFS may not cause the application to "block" or pause. In order to ensure that applications can continue processing important events while the operation is outstanding, D-VFS will be built around the concept of asynchronous operations. That essentially means callback-based programming. + +Don't worry, a pseudo-synchronous interface is also planned to ease development: see below. + + +### URIs + +D-VFS will use URIs to reference files and folders. This is the existing practice in gnome-vfs and KIOSlaves, as well as the practice for referencing files on most interesting remote protocols in common clients (including the web browser). + +While console users may be more comfortable with paths, note that D-VFS is intended for desktop users (where the URI reigns supreme), and that console users will have to 'mount' URIs anyway to access them, which will cause the URI to be mapped to whatever path the console user desires. + + +### Optional Features and Emulation + +Many of the features that D-VFS will support will not be implementable on certain protocols. FTP does not allow seeking, for example. + +If it is possible to provide a relatively efficient emulation of a feature, D-VFS will strive to do so. No protocol is required to implement any feature outside of the core set (save, load, list files, etc.). + +Applications may query whether a particular feature is available or not for any protocol. + +It is _highly_ recommended that application authors stick to the core feature set if at all possible to ensure maximum utility. When developers do need optional features, it is recommended that they disable any parts of their application that need the feature when its not available while allowing the rest of their application to function; it is better to have a mostly functioning app than a completely non-functioning app. + + +### Toolkit Integration + +Some features of D-VFS cannot be expressed in an easy to use API without a level of integration with the application's toolkit. Monitoring the D-BUS (note: not determined for sure we'll use D-BUS, but it seems overwhelmingly likely) and processing windowing system events during VFS operations are two examples of where the D-VFS must have integration with the toolkit. + +For this reason, the core D-VFS client-side API will be designed for toolkit developers, not applications developers. It is expected that application developers will use the toolkit-specific D-VFS wrappers when writing their applications. + +Thankfully, the number of applications that do not use an established toolkit are rare. The major toolkits inlude, but are not limited to: glib, Qt, and Gecko. A major application that uses its own toolkit is [[OpenOffice|OpenOffice]].org + + +### POSIX Compatibility + +D-VFS does not attempt to provide compatibility with the POSIX I/O API or to existing applications. Applications will need to be updated to use the D-VFS API if they wish to make full use of its capabilities. + +Modules for FUSE and similar technologies on non-Linux platforms will be entirely possible, in addition to module to existing user-space VFS systems like KIO and gnome-vfs. These should provide good migration paths and compatibility with applications that are uninterested in D-VFS. + + +### Pseudo-Synchronous API + +While it is mandatory for GUI applications that VFS operations be asynchronous, actually programming against an asynchronous API can be very difficult, especially in popular languages like C or C++. A pseudo-synchronous API can be provided which provides easier to use blocking functions, but which integrate with the application's main loop in order to ensure that important events are still processed while the application waits for the VFS. + +This API must be implemented at the toolkit layer. + + +### Change Notification + +Change notification allows applications to be notified when a file or folder they are interested in changes. A file manager would use these feature to refresh the file list of any windows it had open if a file is added or removed to any of the open folders. + +Applications can also make use of change notification to enhance the user experience. A word processor or text editor might watch for changes made to the file being edited and warn the user of such changes. + + +### Seeking and Partial Content + +Some applications can make use of, or even require, the ability to seek around a file (rewind and fast forward), or only need to access a small portion of a file. A thumbnailer used in a file manager is an example of such an application. + +Both seeking and partial content requests are not supportable on all interesting protocols. The current plan is to simply not provide these features on such file systems. It may be possible to provide some level of emulation at a later date. (Possibly before D-VFS 1.0.) + + +### Locking and Concurrent Access + +Where possible, D-VFS will attempt to make operations atomic. That means that the operation appears to happen as a single uninterruptable action. For example, when an application saves a document using the save document API, D-VFS will make the file change appear atomic when possible. While that works to ensure data integrity in the case of system failure, it doesn't not protect against concurrent edits, where two users may save the same file - whichever save completes second will overwrite the first one. + +Locking will allow an application to claim ownership of a file so that no other applications may modify the document. This can be used to protect against two users editing the same document at the same time. + +Neither atomic writes nor locking will be supported on all protocols. + + +## VFS Daemon + + +### Advantages + +The VFS daemon allows: + +* Connection sharing between processes +* Separation of application logic and security control (not letting applications access user passwords) +* Client-side asynchronous operation on synchronous protocols/APIs +* Language-neutral entry-point to the VFS +* Integration with current desktop keychain/password-cache +* Easier implementation of some feature emulations like change notification polling +The security advantages of a VFS daemon are interesting. If applications were responsible for querying the user for her password when authenticating to a remote share, two problems arise. First, the user must trust every application they run, or restrict all untrusted applications from accessing the VFS. Otherwise, the untrusted application could request her password and then send it to an attacker trojan-horse style. + +While it's true that any app can pretend to ask for a password, the second security advantage of a daemon can attempt to circumvent that problem. Secure X extensions under discussion would allow for a user to verify that any window is legitimate (by using a key-combination that only trusted applications may respond to, for example). Since all authentication must come from a trusted application, it is easiest for the daemon (or, more likely, another helper process) to do the authentication querying instead of each individual application. + + +### Disadvantages + +The main disadvantage of using a daemon is the theoretical performance degradation. For network filesystems, the performance impact will be marginally - most of the time will be spent waiting on the network. For local filesystem access, it is possible for the performance impact to be noticable. Whether this will be a true problem, or just a theoretical one, is yet to be seen. + +The daemon will be required. The complexity in making backends support both in-process and daemon operation would severely complicate the development of a backend. The only backend where in-process support makes a lot of sense is local file system operations, althought some of those still will _require_ a daemon or separate thread. + + +### Protocol Backends + +The system will be comprised of backends which implement protocols. A single backend may support more than one protocol. For example, a neon backend might support both dav: and davs:, while an SFTP backend might also implement support for SCP. It's possible that more than one backend might be installed that implements a particular protocol. + +The backends will provide a list of capabilities and entry points for using the backend. A very simple model would simply provide a vtable of function pointers. Whether a particular entry is set or not would indicate whether the capability is supported and would also provide the entry point to the backend. + +It is vital that backends be both backward and forward compatible. A backend written for D-VFS 1.1 should work under D-VFS 1.0; the only difference would be that some newer features found in 1.1 will simply be unavailable to application susing D-VFS 1.0. Likewise, a module written for 1.0 should work under D-VFS 1.1, although it will not be able to offer implementations of the new features found in 1.1. + +By doing this, we make it much, much easier for third party developers to build, distribute, and support custom protocol backends. This can be especially important for in-house development projects with oddball specialized protocols that need to be usable on a variety of machines in the organization. + + +## Licensing + +This is always a scary subject to approach, but it's worth mentioning in brief even at this point. The D-VFS is intended to be of maximum utility to both users and developers. It is important that any potentially restrictive licensing problems be avoided to ensure that the system is used by the widest range of software projects possible. Simply following suit with D-BUS' licensing or using the MIT license (like Xorg does) is probably the best bet all around. + + +## Discussion + + +### Mailinglist + +All previous D-VFS discussion has been on [[the main xdg mailing list|http://lists.freedesktop.org/mailman/listinfo/xdg]]. Please add specific vfs requirements or proposals on this Wiki. Discussion of more general interest should continue to be posted on [[xdg|http://lists.freedesktop.org/mailman/listinfo/xdg]] + + +### Mailing List Threads + +The mailing list threads which recently started this discussion are: + +* [[dvfs locking|http://lists.freedesktop.org/pipermail/xdg/2005-March/006076.html]] +* [[A virtual filesystem standard|http://lists.freedesktop.org/archives/xdg/2003-September/002322.html]] +* [[A virtual filesystem standard|http://lists.freedesktop.org/archives/xdg/2003-September/002340.html]] +* [[virtual filesystem ideas|http://lists.freedesktop.org/archives/xdg/2003-September/002398.html]] +* [[virtual filesystem ideas|http://lists.freedesktop.org/archives/xdg/2003-September/002400.html]] +* [[a common VFS - a different approach|http://lists.freedesktop.org/archives/xdg/2003-September/002406.html]] +* [[virtual filesystem ideas|http://lists.freedesktop.org/archives/xdg/2003-September/002423.html]] +* [[VFS ramblings|http://lists.freedesktop.org/archives/xdg/2003-September/002425.html]] +* [[Fwd: Re: virtual filesystem ideas|http://lists.freedesktop.org/archives/xdg/2003-September/002434.html]] +* [[A common VFS and a Common conf-system (Was: namespacing)|http://lists.freedesktop.org/archives/xdg/2005-February/005946.html]] +* [[A common VFS and a Common conf-system [Part II|http://lists.freedesktop.org/archives/xdg/2005-March/005957.html]]] +* [[A common VFS and a Common conf-system (Was: namespacing)|http://lists.freedesktop.org/archives/xdg/2005-March/005958.html]] +* [[A common VFS and a Common conf-system (Was: namespacing)|http://lists.freedesktop.org/archives/xdg/2005-March/005968.html]] +* [[A common VFS and a Common conf-system (Was: namespacing)|http://lists.freedesktop.org/archives/xdg/2005-March/005972.html]] + +### Interesting Links + +* [[http://developer.kde.org/documentation/library/3.4-api/kio/html/index.html|http://developer.kde.org/documentation/library/3.4-api/kio/html/index.html]] - KDE's IOSlaves developer documentation +* [[http://developer.gnome.org/doc/API/gnome-vfs/|http://developer.gnome.org/doc/API/gnome-vfs/]] - GNOME's gnome-vfs developer documentation +* [[http://live.gnome.org/GnomeVfsPlans|http://live.gnome.org/GnomeVfsPlans]] - Discussion on improving gnome-vfs +* [[http://www.scheinwelt.at/~norbertf/common-vfs/|http://www.scheinwelt.at/~norbertf/common-vfs/]] - Common/Shared VFS thoughts by [[NorbertFrese|NorbertFrese]] +* [[http://mail.gnome.org/archives/gtk-devel-list/2007-February/msg00062.html|http://mail.gnome.org/archives/gtk-devel-list/2007-February/msg00062.html]] - GVFS status report (The new Gnome-VFS replacement) +* [[http://www.scheinwelt.at/~norbertf/devel/fusi/|http://www.scheinwelt.at/~norbertf/devel/fusi/]] - libfusi - A desktop interface to manage FUSE-mounts. +* The [[Project Portland|http://portland.freedesktop.org/]] also has a [[VFS-Task|http://portland.freedesktop.org/wiki/TaskVFS]]. It aims to provide a generic interface to VFS-functions through scripts and a library interface (discontinued). + +### Comments + +Please append your comments here: + +([[BuliaByak|BuliaByak]]) Please consider adding support for accessing files within archives, such as zip, jar or tar.bz2. This is a very important feature that these days is almost standard in file managers (at least), so providing at the system level will be very beneficial. Any vfs-aware application will be able to edit and manipulate files in an archive transparently. If you don't do it, a file manager will only be able to use d-vfs for e.g. FTP, but will have to implement its own incompatible (and largely similar) vfs for working with archives. One vfs which claims to support archives is that in tcl/tk: [[http://wiki.tcl.tk/vfs|http://wiki.tcl.tk/vfs]]. Please also make it easy to add support for more archive formats. + +([[GeorgeStaikos|GeorgeStaikos]]) How do you plan to deal with complex issues like HTTP, where "sessions" are required with multiple concurrent slaves running? It also requires huge amounts of callbacks, user interaction, system-wide SSL integration, and much much more. Making this portable across desktops is painful at best, if sane. + +([[RobertWittams|RobertWittams]]) Is there a case for making authentication, cookie sharing, history, and cacheing work even between different HTTP stacks? I don't think that everyone will agree on one implementation of HTTP right now. But the state that browsers have could certainly be shared. Maybe this is even a separate project than DVFS, but it needs to be thought about because of the implications it has for authentication helpers. + +([[SeanMiddleditch|SeanMiddleditch]]) Cleaned up the document, including incorporating some of the comments (if you're wondering where they went). In regards to a shared HTTP implementation: I think web browsers and download are a somewhat separate topic, although they have a strong relationship to some things D-VFS will do. I think a shared HTTP implementation (possibly built on an existing implemetnation) is a great idea, but should be done separately from D-VFS. Once such an implementation exists, though, it would be great for D-VFS to support it so applications can seamlessly access content from URIs retrieved from the browser (and possibly needing cookies or whatnot to read). + +([[MortenSvantesson|MortenSvantesson]]) I can't see why you claim that FTP doesn't support seeking. Sending the commands ABOR and REST _offset_ seems enough like seeking to me and I've seen them used as such. Granted, _offset_ is not guaranteed by the RFC to be a byte offset, but I don't know of any implementations where it isn't. + +Since I'm a heavy user of AFS there are some issues I want to press: + +* Access rights are not covered yet. +* File managers have use of knowing quotas or more to the point: how much more can be stored. Gnome VFS has [[gnome_vfs_get_volume_free_space|http://developer.gnome.org/doc/API/gnome-vfs/gnome-vfs-gnome-vfs-utils.html#GNOME-VFS-GET-VOLUME-FREE-SPACE]] (but doesn't support AFS). +* AFS is accessed by the user through paths but need a special backend for support of quotas and access rights. How should this be handled? The problem might arise for users of other protocols—like SMB—as well. + +## CVS + +There is no CVS repository as there is no api or documentation. + + +## Bugs & Patches + +There is no Bugzilla as there is no api or documentation. + + +## Download + +There are no D-VFS downloads as there is no api, implementation, tests, samples, or documentation, but there are projects with a similar intend: + +The new Gnome-VFS replacement called **GVFS** is actively developed and might be used as a shared Desktop-VFS (to replace or back KIO): [[http://mail.gnome.org/archives/gtk-devel-list/2007-February/msg00062.html|http://mail.gnome.org/archives/gtk-devel-list/2007-February/msg00062.html]] + +An alternate approach is using FUSE: **libfusi** is an attempt to provide a desktop interface to manage FUSE mounts. [[http://www.scheinwelt.at/~norbertf/devel/fusi/|http://www.scheinwelt.at/~norbertf/devel/fusi/]] diff --git a/Software/eventuality.mdwn b/Software/eventuality.mdwn new file mode 100644 index 00000000..83c43d49 --- /dev/null +++ b/Software/eventuality.mdwn @@ -0,0 +1,4 @@ + +The project goal for Eventuality is to create a DBUS based framework for creating a flexible means of scheduling arbitrary "actions" to be performed by conforming apps. See our [[FAQ|Software/Eventuality/FAQ.txt]]. Also, before some real action happens, you may be interested in [[discussion|http://freedesktop.org/pipermail/xdg/2004-July/004239.html]] that happened on XDG list. + +-- Main.[[MaciejKatafiasz|MaciejKatafiasz]] - 08 Aug 2004 (updated by [[JimHodapp|JimHodapp]] 02 Sept 2004) diff --git a/Software/fontconfig.mdwn b/Software/fontconfig.mdwn new file mode 100644 index 00000000..2c1f3af6 --- /dev/null +++ b/Software/fontconfig.mdwn @@ -0,0 +1,48 @@ + + +## Fontconfig + +Fontconfig is a library for configuring and customizing font access. + + +### About Fontconfig + +Fontconfig can: + + * discover new fonts when installed automatically, removing a common source of configuration problems. + * perform font name substitution, so that appropriate alternative fonts can be selected if fonts are missing. + * identify the set of fonts required to completely cover a set of languages. + * have GUI configuration tools built as it uses an XML-based configuration file (though with autodiscovery, we believe this need is minimized). + * efficiently and quickly find the fonts you need among the set of fonts you have installed, even if you have installed thousands of fonts, while minimzing memory usage. + * be used in concert with the X Render Extension and [[FreeType|FreeType]] to implement high quality, anti-aliased and subpixel rendered text on a display. +Fontconfig does not: + + * render the fonts themselves (this is left to [[FreeType|FreeType]] or other rendering mechanisms) + * depend on the X Window System in any fashion, so that printer only applications do not have such dependencies + +### Releases + + * The current stable series is 2.10.0. All releases are available in the [[release|http://fontconfig.org/release]] directory. + +### Documentation + + * [[FontConfig User Documentation|http://fontconfig.org/fontconfig-user.html]] + * [[FontConfig Developer Documentation|http://fontconfig.org/fontconfig-devel/]] + * [[About Fontconfig|Software/fontconfig/About]] + * [[Fontconfig To Do List|Software/fontconfig/ToDo]] + +### Git Access + +The fontconfig [[git repository|http://cgit.freedesktop.org/fontconfig/]] is hosted at freedesktop.org. + + +### Mailing Lists + +The [[Fontconfig mailing list|http://lists.freedesktop.org/mailman/listinfo/fontconfig]] is used for all fontconfig related mail. + + +### Web fonts + +Microsoft has made the [[common web fonts|http://fontconfig.org/webfonts]] available free of charge; please read the license before downloading them. + +Redhat has made [[free fonts|https://www.redhat.com/promo/fonts/]] (GPL+exception) available: _Sans_ (a substitute for Arial, Albany, Helvetica, Nimbus Sans L, and Bitstream Vera Sans), _Serif_ (a substitute for Times New Roman, Thorndale, Nimbus Roman, and Bitstream Vera Serif) and _Mono_ (a substitute for Courier New, Cumberland, Courier, Nimbus Mono L, and Bitstream Vera Sans Mono). diff --git a/Software/fontconfig/About.mdwn b/Software/fontconfig/About.mdwn new file mode 100644 index 00000000..889d49a9 --- /dev/null +++ b/Software/fontconfig/About.mdwn @@ -0,0 +1,20 @@ + + +### About Fontconfig + + * Fontconfig can: + * discover new fonts when installed automatically, removing a common source of configuration problems. + * perform font name substitution, so that appropriate alternative fonts can be selected if fonts are missing. + * identify the set of fonts required to completely cover a set of languages. + * have GUI configuration tools built as it uses an XML-based configuration file (though with autodiscovery, we believe this need is minimized). + * efficiently and quickly find the fonts you need among the set of fonts you have installed, even if you have installed thousands of fonts, while minimzing memory usage. + * be used in concert with the X Render Extension and [[FreeType|FreeType]] to implement high quality, anti-aliased and subpixel rendered text on a display. Fontconfig does not: + * render the fonts themselves (this is left to [[FreeType|FreeType]] or other rendering mechanisms) + * depend on the X Window System in any fashion, so that printer only applications do not have such dependencies + +### About Xft + + * The current version of Xft (2.0) provides a client-side font API for X applications. It uses Fontconfig to select fonts and the X protocol for rendering them. When available, Xft uses the Render extension to accelerate text drawing. When Render is not available, Xft uses the core protocol to draw client-side glyphs. This provides completely compatible support of client-side fonts for all X servers. Drawing anti-aliased text with the core protocol involves fetching pixels from the destination, merging in the glyphs and shipping them back. This can be a performance problem when the latency between client and server is high. Drawing non-AA text with the core protocol can be done by just sending the glyphs from the client to the server. This eliminates any latency effects and makes rendering speed depend only on bandwidth. Careful protocol selection can make the bandwidth scale linearly with the pixel size of the glyphs, so performance is acceptable, even with relatively large glyphs. When using legacy X servers (those without Render support) across a network, disabling anti-aliased text will improve text performance so that applications are reasonably usable even if completely dependent on client-side fonts. + * The many faces of Xft + * There are three very different libraries name Xft. The original 1.0 Xft library shipped with XFree86 4.0.2 and included a private configuration mechanism via the [[XftConfig|XftConfig]] file. For X servers without the Render extension, Xft 1.0 used core X fonts instead of client-side fonts. This was supposed to allow applications to code to a common API and run with all X servers. Early in the deployment of Xft 1.0, it became abundantly clear that another custom X-specific font configuration mechanism was a really bad idea. Both KDE and Pango ended up stealing pieces of Xft to configure fonts. KDE created a GUI Xft configuration tool by stealing the [[XftConfig|XftConfig]] parsing code, Pango stole most of Xft so that the [[XftConfig|XftConfig]] file could be shared between the Xft and [[FreeType2|FreeType2]] backends. Fontconfig was designed to solve both of these problems. The other problem in Xft 1.0 was the use of core X fonts when the server wasn't blessed with the Render extension. This meant that applications couldn't count on client-side fonts when using the high-level Xft APIs. As client-side fonts provide significant value beyond anti-aliased glyphs, it again became obvious that this design was flawed. The Xft 1.0 API abstracted configuration details sufficient to permit a binary compatible version, Xft 1.1, to be developed which replaces the [[XftConfig|XftConfig]] configuration file with calls in to the Fontconfig library. Unfortunately, the Xft 1.0 API didn't sufficiently hide the rendering details making it impossible to provide for client-side fonts in servers without the Render extension. This means that Xft 1.1 shares font configuration, but isn't really usable on servers without Render. +-- [[KeithPackard|KeithPackard]] - 21 Sep 2003 diff --git a/Software/fontconfig/ToDo.mdwn b/Software/fontconfig/ToDo.mdwn new file mode 100644 index 00000000..b77be4fd --- /dev/null +++ b/Software/fontconfig/ToDo.mdwn @@ -0,0 +1,18 @@ + + +## Fontconfig To Do List + +A directory of [[related Freedesktop.org To Do Projects|FreedesktopProjects]] is available. + +[[Fontconfig|Software/fontconfig]] is a library with **NO** X Window System dependencies, for general use in discovering fonts that are present on the system for use with Freetype2 (or other font rasterizers). + +Work on Fontconfig is almost complete, but there are a few loose ends, as documented below. Contact Main.[[KeithPackard|KeithPackard]] about Fontconfig projects. +[[!table header="no" class="mointable" data=""" + **Subproject** | **Type** | **Description** | **Diff/Size** | **Comp.** + CSS2 Support | code | Fontconfig already supports almost perfect CSS2 name subsitution, but this needs completion and conformance with that standard: if you are matching bitmap fonts, italic is not falling back properly to some other family with italic. | easy / small | 0% + Font library | code / doc | Make the X system's font access library use Freetype2 and Fontconfig for core fonts. This will make font configuration between clients and servers uniform and much less error prone, and get rid of a pile of code to load bitmap fonts from the X server. This will simplify the X server (all implementations that use this library), the font server (if you are foolish enough to run one), and user's lives | mod. / small | 70% +TTF Conversion | code | Convert existing bitmap fonts to True Type format. Write a tool to get them out again. By converting bitmap fonts to True Type format and using Freetype2 to load them (Freetype also has the ability to load bitmap font formats), we save tons of files and disk space and removing the horrid Unicode mapping problem, and improve performance and footprint of the system. | mod. / mod | 70% + Application retrofit | code | Pick your favorite application that doesn't yet use fontconfig and fix it. Some examples are Ghostscript and Motif. | easy / easy | 80% +"""]] + +-- Main.[[JimGettys|JimGettys]] - 11 Feb 2004 diff --git a/Software/fprint.mdwn b/Software/fprint.mdwn new file mode 100644 index 00000000..ee871806 --- /dev/null +++ b/Software/fprint.mdwn @@ -0,0 +1,64 @@ + +[[!img http://www.reactivated.net/fprint/img/Fprint_logo.png] The fprint project aims to plug a gap in the Linux desktop: support for consumer fingerprint reader devices. + +Previously, Linux support for such devices has been scattered amongst different projects (many incomplete) and inconsistent in that application developers would have to implement support for each type of fingerprint reader separately. For more information on where we came from, see [[/Project history|Software/fprint/Project history]]. + +We're trying to change that by providing a central system to support all the fingerprint readers we can get our hands on. The software is open source and in the long term we're shooting for adoption by distributions, integration into common desktop environments, etc. + + +## Projects + + +### libfprint + +[[libfprint|Software/fprint/libfprint]] is the centre of our efforts. libfprint is the component which does the dirty work of talking to fingerprint reading devices, and processing fingerprint data. + +If you're a user, you probably aren't interested in libfprint, instead you want to find some software which _uses_ libfprint (see the integration project). + +If you're an application developer looking to add support for some kind of fingerprinting to your software, libfprint is exactly what you are looking for. It provides a simple API for you to enroll fingerprints and then identify users later on. + +* [[libfprint homepage|Software/fprint/libfprint]] + +### Integration + +The [[Integration|Software/fprint/Integration]] project details our efforts to integrate libfprint with existing applications, so that users can use their fingerprint reading hardware. + +* [[Integration homepage|Software/fprint/Integration]] + +### fprint_demo + +[[fprint_demo|Software/fprint/fprint_demo]] is a simple GUI application used to demonstrate and test libfprint's capabilities. + +* [[fprint_demo homepage|Software/fprint/fprint_demo]] + +### fprintd + +[[fprintd|Software/fprint/fprintd]] is a daemon that provides fingerprint scanning functionality over D-Bus. + +* [[fprintd homepage|Software/fprint/fprintd]] + +## News + +* 2008-11-23: Bastien Nocera has been doing a lot of work on [[fprintd|Software/fprint/fprintd]] and has put out a [[request for testing in Fedora|http://article.gmane.org/gmane.linux.redhat.fedora.desktop/4423]]. +* 2008-08-07: Wolfgang Ullrich announces a libfprint-based [[Qt fingerprint scanning GUI|http://darkblue.homeip.net/fingerprint/]] +* 2008-05-06: [[Academic project report published|http://www.reactivated.net/fprint/academic-project/fprint_report.pdf]] +* 2008-04-01: [[Portuguese article about fprint|http://www.vivaolinux.com.br/artigos/verArtigo.php?codigo=8044]] at Vivao Linux +* 2008-03-20: [[/libfprint v0.0.6|Software/fprint/libfprint v0.0.6]] released +* 2008-01-24: IRC Channel #fprint is now on at freenode (irc.freenode.org) +* 2007-12-07: [[/libfprint v0.0.5|Software/fprint/libfprint v0.0.5]] released +* 2007-11-22: [[We're featured in LWN!|http://lwn.net/Articles/258702/]] Also released [[/libfprint v0.0.4|Software/fprint/libfprint v0.0.4]] and [[/fprint_demo v0.4|Software/fprint/fprint_demo v0.4]]. +* 2007-11-19: More releases: [[/libfprint v0.0.3|Software/fprint/libfprint v0.0.3]], [[/pam_fprint v0.2|Software/fprint/pam_fprint v0.2]] and [[/fprint_demo v0.3|Software/fprint/fprint_demo v0.3]] +* 2007-11-18: [[/fprint_demo v0.2|Software/fprint/fprint_demo v0.2]] released. +* 2007-11-17: [[/libfprint v0.0.2|Software/fprint/libfprint v0.0.2]] and [[/fprint_demo v0.1|Software/fprint/fprint_demo v0.1]] released. +* 2007-11-15: [[/libfprint v0.0.1|Software/fprint/libfprint v0.0.1]] and [[/pam_fprint v0.1|Software/fprint/pam_fprint v0.1]] released. +* 2007-11-15: [[Project announced to the public|http://lists.reactivated.net/pipermail/fprint/2007-November/000002.html]] and also on [[my weblog|http://www.reactivated.net/weblog/archives/2007/11/announcing-fprint-project/]]. +* 2007-11-13: [[This poster|http://www.reactivated.net/fprint/academic-project/fprint_poster.pdf]] is on display in my university department and provides a brief introduction to the project and its goals. + +## Other content + +Most of the website content can be found under the appropriate subproject above. Here's some stuff that isn't so specific: + +* [[/Security notes|Software/fprint/Security notes]] +* [[/Project history|Software/fprint/Project history]] +* [[/Project needs|Software/fprint/Project needs]] - help us out! +* [[/Mailing list|Software/fprint/Mailing list]]
\ No newline at end of file diff --git a/Software/fprint/Download.mdwn b/Software/fprint/Download.mdwn new file mode 100644 index 00000000..1ef3cc30 --- /dev/null +++ b/Software/fprint/Download.mdwn @@ -0,0 +1,39 @@ + +You are advised to read the release notes for the version in question before using the software. + +**There is no guarantee of stability or forwards-compatibility between current and future releases. There is not much user documentation either.** + +If you need help, ask on the [[mailing list|Software/fprint/Mailing list]]. + + +## Source releases + +Source downloads can be found [[on freedesktop|http://people.freedesktop.org/~hadess/]]. Old source releases can be found [[on SourceForge|http://sourceforge.net/project/showfiles.php?group_id=208521]]. The [[Installation|Software/fprint/Installation]] page details how to install from source. + + +## Distributions + +The [[Installation|Software/fprint/Installation]] page includes some troubleshooting questions applicable to all distributions. + + +### Ubuntu + +The FPrint suite can be installed from the following PPA: [[https://launchpad.net/~fingerprint/+archive/fprint|https://launchpad.net/~fingerprint/+archive/fprint]] + + +### Gentoo + +Wolfram Schlich maintains fprint ebuilds in the wschlich-testing overlay. + +You can get it by invoking: + +* layman -a wschlich-testing +If you have no other overlays, add following line to your make.conf: + +* PORTDIR_OVERLAY="/usr/portage/local/layman/wschlich-testing" +Otherwise append "/usr/portage/local/layman/wschlich-testing" to PORTDIR_OVERLAY variable. + + +### SuSE + +Georges A.K. builds OpenSuSE packages at [[http://download.opensuse.org/repositories/home:/dgege/|http://download.opensuse.org/repositories/home:/dgege/]] diff --git a/Software/fprint/FAQ.mdwn b/Software/fprint/FAQ.mdwn new file mode 100644 index 00000000..22e0d64e --- /dev/null +++ b/Software/fprint/FAQ.mdwn @@ -0,0 +1,83 @@ + + +#### What is libfprint? + +libfprint is an open source software library designed to improve the usability of consumer fingerprint scanners on Linux. It aims to provide a simple API to the developer, hiding the nasty details of the hardware that the user is using. It also aims to support a lot of devices and have a nice internal API for drivers. + + +#### How does libfprint relate to other open source fingerprint projects? + +Most previous open source fingerprint projects have managed to retrieve images from the devices they support, but have stopped there. Examples include [[dpfp|http://dpfp.berlios.de]] and [[various Authentec driver projects|http://gkall.hobby.nl/authentec.html]]. Not only does libfprint act as replacement these projects by allowing applications to retrieve images from the devices, it goes a step further and actually processes the images to allow fingerprint verification, leading to functionality such as fingerprint-based login. + +libthinkfinger from [[ThinkFinger|http://thinkfinger.sourceforge.net/]] is the only other project that offers fingerprint verification capabilities for the devices it supports. libfprint can also act as a libthinkfinger replacement, as it supports these devices in the [[upekts|Software/fprint/libfprint/upekts]] driver which was based on [[ThinkFinger|ThinkFinger]] code anyway. + +Even though libfprint may have borrowed code (with permission) from other open source fingerprint projects, it is standalone and does not require other fingerprint libraries to be installed. + + +#### How well does it work on my hardware? + +See [[../libfprint/Driver quality|Software/fprint/libfprint/Driver quality]]. + + +#### Why does libfprint keep saying that my fingerprints do not match? + +See [[../libfprint/Imaging performance|Software/fprint/libfprint/Imaging performance]]. + + +#### Does libfprint require BioAPI? + +No. (more on this below) + + +#### Does libfprint require any special kernel drivers? + +No. libfprint has drivers internally, based in userspace, using [[libusb|http://www.libusb.org]] for device I/O. + + +#### Which devices does libfprint support? + +See [[supported devices|Software/fprint/libprint/Supported devices]] and [[unsupported devices|Software/fprint/libfprint/Unsupported devices]]. + + +#### Tell me more about the image processing code? + +libfprint includes [[NBIS|http://fingerprint.nist.gov/NBIS/index.html]] and uses it for the image processing (mindtct) and later comparison of new images against previously enrolled prints (bozorth3). bozorth3 is not available on NISTs server due to export control concerns, which I have found [[do not apply|Software/fprint/US export control]] to this project. + +This code is fast -- mindtct takes approx 0.15 seconds for a 384x289 image on my 2ghz dual core laptop [only using one core], and bozorth3 takes about 0.1 seconds to compare 2 of those prints. From my testing so far, it appears to be impressively accurate too - I have yet to find a false acceptance. + + +#### Why can't I get images from my fingerprint scanner? + +Chances are it is not an imaging device, and does image processing in hardware. Hardware driven by the [[upekts|Software/fprint/libfprint/upekts]] driver falls into this category. + + +#### Why no BioAPI? + +At first glance, [[BioAPI|http://www.bioapi.org/]] is a nice idea. It basically aims to standardize an API for access to biometric devices. + +There are a few reasons why BioAPI is not used in libfprint. + +* BioAPI is closed. There does not seem to be any way to provide input for API design, unless you are a member. +* BioAPI is not free. While a 6-year old version of the standard can be freely downloaded, the latest version must be purchased. +* BioAPI adoption seems to be very low. I only know of a single freely downloadable software product which uses BioAPI, and that one is closed source: UPEKs own Linux fingerprint drivers. +* BioAPI is vague and complex. It turns out that designing API's to drive biometric hardware in general is a hard problem, and I don't really agree with their approach on things. Actually, I don't feel that I have a complete understanding of it either, despite spending a long time looking at it. Another reason for avoidance. +* BioAPI doesn't do as much as people think. For example it has no image processing code, it just describes an API for how such code might be driven. +* libfprint started as a university project, with a core component being abstraction handling and library design. So at least in the context of the academic project, I had to "reimplement" the kind of thing BioAPI tries to achieve anyway. +I may be wrong, and BioAPI may be a good system. However, I believe libfprint's flexibility should make it possible and realistic for someone to slot in libfprint into the BioAPI chain. I would happily endorse and host such a project if someone is up for the challenge. + +Additionally, in some ways, it almost makes sense for libfprint to be separate. BioAPI looks at all kinds of biometric applications (including fingerprints), libfprint targets fingerprint scanners exclusively. BioAPI or equivalent almost feels well suited to be a natural 'parent' of libfprint, alongside potential projects like libirisscan, libfacerecognition, etc :) + + +#### Aren't fingerprints insecure? + +See [[../Security notes|Software/fprint/Security notes]] for discussion. Short answer: libfprint is secure enough for your average user, but overall libfprint is not secure, and neither is typing passwords into your computer. Did I mention you're reading this site over an unencrypted protocol? + + +#### How can I help? + +See [[Project needs|Project needs]]. + + +#### Where do I go for help? + +User support happens on the [[mailing list|Software/fprint/Mailing list]]. diff --git a/Software/fprint/Installation.mdwn b/Software/fprint/Installation.mdwn new file mode 100644 index 00000000..26e16acb --- /dev/null +++ b/Software/fprint/Installation.mdwn @@ -0,0 +1,64 @@ +## Installation using distribution packages + +The [[Download|Software/fprint/Download]] page contains links to distribution packages. + + +## Installation from sources + +At first, check if libfprint and pam_fprint packages available for your distro. + +**Follow this way only if there's no packages for your distro!** + +_You'll need gcc and some development packages installed._ + +Get libfprint sources. + +Unpack libfprint-version.tar.bz2 somewhere: + + tar -xjf libfprint-0.0.4.tar.bz2 + +Compile it: + + cd libfprint-0.0.4 + ./configure --prefix=/usr + make + sudo make install + +Last one command requires root privileges. + +Use same technique for pam_fprint and fprint_demo. + +_Note that libfprint is young project, and its API isn't stable so you can broke pam_fprint and fprint_demo when updating to new versions. Reinstall pam_fprint and fprint_demo immediatelly after libfprint update._ + + +## Troubleshooting + +**Q: During pam_fprint configure I've got something like:** + + checking for FPRINT... configure: error: Package requirements ("libfprint") were not met + +A: Probably, you've installed libfprint in /usr/local. Remove all libfprint's files from /usr/local and follow instruction in 2nd paragraph + +**Q: I've installed libfprint into /usr, but pam_fprint's configure still complains about missing libfprint!** + +A: Try to invoke following command before running configure: + + export PKG_CONFIG_PATH=/usr/lib/pkgconfig:$PKG_CONFIG_PATH + +**Q: Running pam_fprint_enroll and fprint_demo from user fails with message like following:** + + aes1610:error [dev_init] could not claim interface 0 + +A: You have no permissions to access /proc/bus/usb (/dev/bus/usb). Solution depends on distro. On Gentoo you should add your user to usb group. Same solution should be applicable for other distros. Invoke mount | grep usb, it should produce something like: + + anarsoul@anarsoul-laptop ~ $ mount | grep usb + usbfs on /proc/bus/usb type usbfs (rw,noexec,nosuid,devmode=0664,devgid=85) + +So, /proc/bus/usb belongs to group with gid 85. Now let's get group name: + + anarsoul@anarsoul-laptop ~ $ cat /etc/group | grep 85 | cut -f 1 -d: + usb + +Add your user to this group: + + sudo usermod -a -G usb your_user_name diff --git a/Software/fprint/Integration.mdwn b/Software/fprint/Integration.mdwn new file mode 100644 index 00000000..7ec93823 --- /dev/null +++ b/Software/fprint/Integration.mdwn @@ -0,0 +1,9 @@ + +To make [[libfprint|Software/fprint/libfprint]] useful, we need to integrate it into existing software. Projects to do that are tracked below. + + +## pam_fprint + +[[pam_fprint|Software/fprint/pam_fprint]] is a [[PAM module|http://www.kernel.org/pub/linux/libs/pam/whatispam.html]] _(Pluggable Authentication Module)_ that uses libfprint for authentication. In other words, it allows you to login to your Linux system in the normal way, except you scan your finger instead of typing a password. + +* [[More info on pam_fprint|Software/fprint/pam_fprint]]
\ No newline at end of file diff --git a/Software/fprint/fprint_demo.mdwn b/Software/fprint/fprint_demo.mdwn new file mode 100644 index 00000000..5f796220 --- /dev/null +++ b/Software/fprint/fprint_demo.mdwn @@ -0,0 +1,43 @@ + +`fprint_demo` is a simple GTK+ application to demonstrate and test libfprint's capabilities. It is written in C and licensed under the [[GNU GPL v2|http://www.gnu.org/licenses/old-licenses/gpl-2.0.html]]. + +It provides access to many of the features offered by the backing library, [[libfprint|Software/fprint/libfprint]]. + + +## Download + +See the [[Download|Software/fprint/Download]] page. + + +## Installation + +Some installation instructions can be found [[here|Software/fprint/Installation]] + + +## Development + +This software is developed using the [[git version control system|http://git.or.cz/]]. The [[git user manual|http://www.kernel.org/pub/software/scm/git/docs/user-manual.html]] is very useful for new users. + +* git clone git://github.com/dsd/fprint_demo.git +* [[View online at github|http://github.com/dsd/fprint_demo/tree/master]] +Contributions encouraged. Please submit patches on [[github|https://github.com/dsd/fprint_demo/issues]]. + + +## Screenshots from v0.4 + +[[[[!img Enrollment of the left middle finger]|http://www.reactivated.net/fprint/img/V.05_leftthumb.png]] [[[[!img Verification interface with minutiae]|http://www.reactivated.net/fprint/img/V.05minutiae.png]] + + +## Screenshots from v0.3 + +[[[[!img Verify interface with minutiae plotted on scan]|http://www.reactivated.net/fprint/img/Fprint_demo_v0.3_verify_with_minutiae.png]] + + +## Screenshots from v0.2 + +[[[[!img Enrollment interface]|http://www.reactivated.net/fprint/img/Fprint_demo_v0.2_enroll.png]] [[[[!img Successful verification scan]|http://www.reactivated.net/fprint/img/Fprint_demo_v0.2_verify.gif]] [[[[!img Successful verification scan, shown as binarized image]|http://www.reactivated.net/fprint/img/Fprint_demo_v0.2_verify_bin.gif]] + + +## Screenshots from v0.1 + +[[[[!img Successful verification scan]|http://www.reactivated.net/fprint/img/Fprint_demo_v0.1_verify_normal.gif]] [[[[!img Successful verification scan, shown as binarized image]|http://www.reactivated.net/fprint/img/Fprint_demo_v0.1_verify_binarized.gif]] diff --git a/Software/fprint/fprintd.mdwn b/Software/fprint/fprintd.mdwn new file mode 100644 index 00000000..21505d11 --- /dev/null +++ b/Software/fprint/fprintd.mdwn @@ -0,0 +1,13 @@ + +fprintd is a D-Bus daemon that offers [[libfprint|Software/fprint/libfprint]] functionality over the D-Bus interprocess communication bus. By adding this daemon layer above libfprint, we solve various problems related to multiple applications simulatenously competing for fingerprint readers. + +While it is not very nice to think of a daemon being necessary in this scenario, fprintd will be launched by D-Bus through the activation mechanism. This means it is launched only when needed, and additionally it will shut itself down after a period of inactivity. + + +## Development + +This software is developed using the [[git version control system|http://git.or.cz/]]. The [[git user manual|http://www.kernel.org/pub/software/scm/git/docs/user-manual.html]] is very useful for new users. + +* git://anongit.freedesktop.org/libfprint/fprintd +* [[View online|http://cgit.freedesktop.org/libfprint/fprintd/]] +Bug reports and (git formatted) patches should go to the [[FreeDesktop bugzilla|https://bugs.freedesktop.org/enter_bug.cgi?product=libfprint]]. diff --git a/Software/fprint/libfprint.mdwn b/Software/fprint/libfprint.mdwn new file mode 100644 index 00000000..2fa3b370 --- /dev/null +++ b/Software/fprint/libfprint.mdwn @@ -0,0 +1,69 @@ +libfprint is an open source software library designed to make it easy for application developers to add support for consumer fingerprint readers to their software. + + +### Features + +* Written in C +* Licensed as [[LGPL-2.1|http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html]] +* Depends on libusb for USB communication and glib +* Primarily developed for linux, but should be fairly portable +* **Offers a single API to application developers to access the entire range of supported devices** +* Supports imaging - downloading live fingerprint scans from the device +* Includes image processing/matching code +* Supports enrollment/verification - enrolling a print from a known user, and then later comparing a live scan to the enrolled print + +### Useful Links + +* [[FAQ|Software/fprint/FAQ]] +* [[Download|Software/fprint/Download]] +* [[Supported devices|Software/fprint/libfprint/Supported devices]] +* [[Unsupported devices|Software/fprint/libfprint/Unsupported devices]] +* [[Installation|Software/fprint/Installation]] +* [[Mailing list|Software/fprint/Mailing list]] - user support happens here +* [[U.S. Export Administration Regulations info|Software/fprint/US export control]] + +### Driver Info + +These drivers are included within libfprint, the corresponding pages are for information only. + +* [[/aes1610|Software/fprint/libfprint/aes1610]]: Authentec AES1610 +* [[/aes1660|Software/fprint/libfprint/aes1660]]: Authentec AES1660 +* [[/aes2501|Software/fprint/libfprint/aes2501]]: Authentec AES2501 +* [[/aes2550|Software/fprint/libfprint/aes2550]]: Authentec AES2550 and AES2810 +* [[/aes2660|Software/fprint/libfprint/aes2660]]: Authentec AES2660 and Eikon``Mini +* [[/aes4000|Software/fprint/libfprint/aes4000]]: Authentec AES4000 +* [[/fdu2000|Software/fprint/libfprint/fdu2000]]: Secu``Gen FDU 2000 +* [[/upeksonly|Software/fprint/libfprint/upeksonly]]: UPEK Touch``Strip sensor-only +* [[/upektc|Software/fprint/libfprint/upektc]]: UPEK Touch``Chip and Eikon``Touch 300 +* [[/upekts|Software/fprint/libfprint/upekts]]: UPEK Touch``Strip with biometric co-processor +* [[/uru4000|Software/fprint/libfprint/uru4000]]: Digital Persona U.are.U 4000/4000B/4500 +* [[/vcom5s|Software/fprint/libfprint/vcom5s]]: Veridicom 5thSense +The user-experience quality of these drivers is noted at [[/Driver quality|Software/fprint/libfprint/Driver quality]]. + + +### API documentation + +API documentation can be found here: [[http://www.reactivated.net/fprint/api/|http://www.reactivated.net/fprint/api/]] + +It is updated from the source code periodically. To generate your own documentation from the sources, install [[doxygen|http://www.stack.nl/~dimitri/doxygen/]] then, from a libfprint source tree: + + cd doc + make docs + +Documentation is then available under the html subdirectory. + + +### Development + +libfprint is developed using the [[git version control system|http://git.or.cz/]]. The [[git user manual|http://www.kernel.org/pub/software/scm/git/docs/user-manual.html]] is very useful for new users. + +* `git://anongit.freedesktop.org/libfprint/libfprint` +* [[View online|http://cgit.freedesktop.org/libfprint/libfprint/]] +Discussions about features, or questions should happen on the [[mailing list|Software/fprint/Mailing list]] + + +### Contributing + +Bug reports and (git formatted) patches should go to the [[FreeDesktop bugzilla|https://bugs.freedesktop.org/enter_bug.cgi?product=libfprint]]. + +See the HACKING file for some information on the code and its design, and TODO for some items that remain to be completed. diff --git a/Software/fprint/libfprint/aes1610.mdwn b/Software/fprint/libfprint/aes1610.mdwn new file mode 100644 index 00000000..7f382f08 --- /dev/null +++ b/Software/fprint/libfprint/aes1610.mdwn @@ -0,0 +1,34 @@ + + +## Introduction + +The `aes1610` driver supports devices based on the [[AuthenTec AES1610 chipset|http://www.authentec.com/products-pcsandperipherals-aes1610.html]]. + +aes1610 is part of [[libfprint|Software/fprint/libfprint]] and is developed by Anthony Bretaudeau. + + +## Supported devices + +This device can most commonly be found embedded in HP tablets and Asus or Lenovo laptops. Even when embedded in this way, these devices just sit on the regular USB bus. + + +## Driver history + +Anthony Bretaudeau wrote this driver based on bus traffic analysis and comparison with other Authentec drivers. + + +## Device operation + +This is a swipe-type device which is similar to the [[AES2501|Software/fprint/libfprint/aes2501]]. Each frame is 128x8 pixels in size. + + +## Security notes + +The fingerprint is always sent unencrypted over the USB bus. + + +## Imaging performance + +Image processing works well -- fingerprint image quality is good, the enhanced/binarized version is also good, and minutiae detection is accurate. However, this being a small sensor, a relatively small area of the finger is detected, and hence not that many minutiae. This results in low match scores, the threshold of which has been dropped to 15. + +Obtaining a good enrollment scan helps the matching performance a lot. It's usable but not brilliant -- false rejections are currently a little more common than we would like. diff --git a/Software/fprint/libfprint/aes1660.mdwn b/Software/fprint/libfprint/aes1660.mdwn new file mode 100644 index 00000000..b79421c6 --- /dev/null +++ b/Software/fprint/libfprint/aes1660.mdwn @@ -0,0 +1,34 @@ + + +## Introduction + +The `aes1660` driver supports devices based on the Authen``Tec AES1660 chipset. + +aes1660 is part of [[libfprint|Software/fprint/libfprint]] and is developed by Vasily Khoruzhick. + + +## Supported devices + +This device can most commonly be found embedded in some laptops, standalone USB device exists. + + +## Driver history + +Vasily Khoruzhick wrote this driver based on bus traffic analysis and comparison with other Authen``Tec drivers. Bus traffic logs were provided by Andreas Loos. aes1660 shares almost all code with [[aes2660|Software/fprint/libfprint/aes2660]] driver, they only differ in init sequences and image width. + + +## Device operation + +This is a swipe-type device which is similar to other Authen``Tec devices. Each frame is 128x8 pixels in size. + + +## Security notes + +The fingerprint is always sent unencrypted over the USB bus. Device can encrypt image, but it's not supported. According to traffic logs, control traffic (commands) is never encrypted. + + +## Imaging performance + +Image processing works well -- fingerprint image quality is good, the enhanced/binarized version is also good, and minutiae detection is accurate. However, this being a small sensor, a relatively small area of the finger is detected, and hence not that many minutiae. This results in low match scores, the threshold of which has been dropped to 25. + +Obtaining a good enrollment scan helps the matching performance a lot. It's usable but not brilliant -- false rejections are currently a little more common than we would like. diff --git a/Software/fprint/libfprint/aes2501.mdwn b/Software/fprint/libfprint/aes2501.mdwn new file mode 100644 index 00000000..2a4c5fc7 --- /dev/null +++ b/Software/fprint/libfprint/aes2501.mdwn @@ -0,0 +1,44 @@ + + +## Introduction + +[[!img Precise 100XS] + +The `aes2501` driver supports devices based on the [[AuthenTec AES2501 chipset|http://www.authentec.com/products-pcsandperipherals-aes2501b.html]]. + +aes2501 is part of [[libfprint|Software/fprint/libfprint]] and is developed/maintained by Daniel Drake. + + +## Supported devices + +This device can be found in some standalone devices, and also in laptops (commonly Lenovo). Even when embedded into laptops, these devices just sit on the regular USB bus. + + +## Driver history + +This driver was based on code from the [[AES2501 kernel driver project|http://home.gna.org/aes2501/index_en.html]], developed by Cyrille Bagard and Vasily Khoruzhick. The kernel driver project was a rewrite of Wittawat Yamwong's userspace driver project, corresponding with specifications for similar Authentec devices. + + +## Device operation + +These are swipe-type imaging devices. The device provides a series of 192x16 "frames" to the computer capturing a small area of the finger surface. It is up to the software to piece the frames together, eliminate overlap etc. + +libfprint includes a simple algorithm to join the frames which seems to work OK. It could do with tweaking to detect when the join is too dirty and hence reject the image. We should also add detection for non-centered finger, etc. + + +## Security notes + +The fingerprint is always sent unencrypted over the USB bus. + + +## Imaging performance + +[[!img Standardized "long" image from AES2501] + +For my own Precise 100XS, image quality is very good and imaging performance is very high as a result. Similar image quality has been achieved on the Lenovo 3000 N100 laptop. Scanning technique is easy to pick up: don't scan too fast, don't scan too slow, don't put too much pressure on the sensor. + +On a good "long" image, MINDTCT finds well over 50 minutiae - a good count. + +If you get a good long enrollment image, verification works very well. + +The current driver has hard-coded values for gain and sensitivity, and even though it works fine on the above mentioned devices, we have [[a bug report|:bug:2]] suggesting that this is not true everywhere. We need to investigate implementing automatic calibration in the driver. diff --git a/Software/fprint/libfprint/aes2550.mdwn b/Software/fprint/libfprint/aes2550.mdwn new file mode 100644 index 00000000..93827b5f --- /dev/null +++ b/Software/fprint/libfprint/aes2550.mdwn @@ -0,0 +1,36 @@ + + +## Introduction + +[[!img aes2550_device_2.jpg] + +The `aes2550` driver supports devices based on the [[AuthenTec|AuthenTec]] AES2550 and AES2810 chipsets. + +aes2550 is part of [[libfprint|Software/fprint/libfprint]] and is developed by Vasily Khoruzhick. + + +## Supported devices + +Driver supports AES2810 and AES2550 (which is cryptoless version of AES2810). These sensors can be found in some standalone USB devices, and also in laptops (commonly Lenovo). Even when embedded in this way, these devices just sit on the regular USB bus. + + +## Driver history + +In June, 2012 Greg Kerr from [[AuthenTec|AuthenTec]] [[announced|http://lists.freedesktop.org/archives/fprint/2012-June/000154.html]] that they are willing to support opensource development. Vasily Khoruzhick contacted [[AuthenTec|AuthenTec]] support and received external USB reader with AES2550 sensor and datasheets for AES2550 and AES2810 devices. Driver was written using those reader and datasheets. + + +## Device operation + +This is a swipe-type device which is similar to other [[AuthenTec|AuthenTec]] devices (AES1610, AES2501). Each frame is 192x8 pixels in size. + + +## Security notes + +The fingerprint is always sent unencrypted over the USB bus. Crypto engine which is present in AES2810 is not supported. + + +## Imaging performance + +For my AES2550 scanner image quality is brilliant and imaging perfomance is good. MINDTCT finds over 40 minutiae on image. + +Scanning technique is same as for other swipe sensors: don't scan too fast, don't scan too slow, don't put too much pressure on the sensor. diff --git a/Software/fprint/libfprint/aes2550/aes2550_device.jpg b/Software/fprint/libfprint/aes2550/aes2550_device.jpg Binary files differnew file mode 100644 index 00000000..d6e07efe --- /dev/null +++ b/Software/fprint/libfprint/aes2550/aes2550_device.jpg diff --git a/Software/fprint/libfprint/aes2550/aes2550_device_2.jpg b/Software/fprint/libfprint/aes2550/aes2550_device_2.jpg Binary files differnew file mode 100644 index 00000000..fd30728c --- /dev/null +++ b/Software/fprint/libfprint/aes2550/aes2550_device_2.jpg diff --git a/Software/fprint/libfprint/aes2660.mdwn b/Software/fprint/libfprint/aes2660.mdwn new file mode 100644 index 00000000..10f67e46 --- /dev/null +++ b/Software/fprint/libfprint/aes2660.mdwn @@ -0,0 +1,36 @@ + + +## Introduction + +[[!img eikon_mini_small.jpg] + +The `aes2660` driver supports devices based on the Authen``Tec AES2660 chipset. + +aes2660 is part of [[libfprint|Software/fprint/libfprint]] and is developed by Vasily Khoruzhick. + + +## Supported devices + +This device can most commonly be found embedded in some laptops, standalone USB device exists - [[EikonMini|http://www.authentec.com/Products/TouchChips/Eikonmini.aspx]] + + +## Driver history + +Vasily Khoruzhick wrote this driver based on bus traffic analysis and comparison with other Authen``Tec drivers. aes2660 shares almost all code with [[aes1660|Software/fprint/libfprint/aes1660]] driver, they only differ in init sequences and image width. + + +## Device operation + +This is a swipe-type device which is similar to other Authen``Tec devices. Each frame is 192x8 pixels in size. + + +## Security notes + +The fingerprint is always sent unencrypted over the USB bus. Device can encrypt image, but it's not supported. According to traffic logs, control traffic (commands) is never encrypted. + + +## Imaging performance + +For Eikon``Mini scanner image quality is brilliant and imaging perfomance is good. MINDTCT finds over 40 minutiae on image. + +Scanning technique is same as for other swipe sensors: don't scan too fast, don't scan too slow, don't put too much pressure on the sensor. diff --git a/Software/fprint/libfprint/aes2660/eikon_mini.jpg b/Software/fprint/libfprint/aes2660/eikon_mini.jpg Binary files differnew file mode 100644 index 00000000..0371eca3 --- /dev/null +++ b/Software/fprint/libfprint/aes2660/eikon_mini.jpg diff --git a/Software/fprint/libfprint/aes2660/eikon_mini_small.jpg b/Software/fprint/libfprint/aes2660/eikon_mini_small.jpg Binary files differnew file mode 100644 index 00000000..144af4ae --- /dev/null +++ b/Software/fprint/libfprint/aes2660/eikon_mini_small.jpg diff --git a/Software/fprint/libfprint/aes4000.mdwn b/Software/fprint/libfprint/aes4000.mdwn new file mode 100644 index 00000000..92a0cdd7 --- /dev/null +++ b/Software/fprint/libfprint/aes4000.mdwn @@ -0,0 +1,60 @@ + +[[!img Targus Defcon 1 Authenticator] +## Introduction + +The `aes4000` driver supports devices based on the [[Authentec AES4000|http://www.authentec.com/products-pcsandperipherals-aes4000.html]] chipset. + +aes4000 is part of [[libfprint|Software/fprint/libfprint]] and is developed/maintained by Daniel Drake. + + +## Supported devices + +Right now I only know of a single device that uses this chip, the Targus Defcon 1 Authenticator. + + +## Driver history + +It doesn't seem to be the case any more, but I downloaded full device specifications from Authentec's website a few years ago. This driver was written based on the specs and analysing bus traffic from the Windows driver. + + +## Device operation + +This is an imaging device, which uses complex sensory electronics to detect variations in the surface of your finger - it doesn't use optics. It then presents image data to the computer but makes no attempt to interpret it - all image processing must be done in software. libfprint handles this internally. + +The device offers many controls to customize the sensitivity of the fingerprint detection system, etc. Currently we just set these to sensible values and don't allow modification of them. + +When ready to scan, the driver arms the scan trigger and waits indefinitely for data. The device will send fingerprint data as soon as the calibration characteristics are met - i.e. when it detects a finger on the scanner. As such, finger detection and capture is a composite operation. + +Thanks to the device specifications (which are no longer available), the protocol is entirely understood, however there are some very technical details involved (capacitances of drive rings, etc!). + + +## Security notes + +The fingerprint is always sent unencrypted over the USB bus. + +There is some kind of challenge and authentication scheme offered by the device, which is mentioned in the specs. Currently, aes4000 does not use such functionality, and I'm not even sure that the specs explain it enough to make an implementation possible. + + +## Image info + +The image resolution is 64x64 pixels. 8 different darkness levels are presented in the image, but with the current calibration settings we only seem to either get 0 (no finger material detected) or 7 (full darkness finger material detected). + + +## Imaging performance + +Currently, the imaging performance of this driver is not brilliant. It generally detects 10-20 minutiae for a good scan, whereas other devices detect 40+. As a result of having less minutiae points, the matching algorithm returns lower scores, meaning that we have to lower the match score threshold to get good matching results. + +In comparison to other devices, extra care must be taken to get good scans, otherwise you'll be told that your fingerprints don't match when they actually do. Ensure that your finger is aligned straight with the device and that you press the same part of your finger onto the device each time. Make a conscious effort not to just scan the tip -- push your finger a little further forward than you might think necessary. Attempt to put your finger down fairly quickly - don't place it lightly and then increase pressure, because libfprint images your finger immediately and does not wait for you to increase the pressure. + +Sometimes, bad images are returned where there is no finger data there at all, just a little bit of noise (this is a bug). Also, the imaging performed by this driver can be improved which would avoid that bug and potentially improve imaging performance. + + +### Analysis of Windows driver traffic + +The first image captured from the device is low quality (but has a strong distinction between foreground and background, potentially useful for edge detection). After capturing that image, the driver reads a histogram from the device and tweaks various registers on the device to increase image quality. It then takes another sample of the finger, tweaks again, samples again, etc. Samples 1, 2 and 14 from a scan are shown below to illustrate this. + +[[!img http://www.reactivated.net/fprint/img/Aes4000_sample1.gif] [[!img http://www.reactivated.net/fprint/img/Aes4000_sample2.gif] [[!img http://www.reactivated.net/fprint/img/Aes4000_sample14.gif] + +It seems to calibrate based on the image data that is being returned, and the histogram after sample #1. This is done dynamically - the changes made to the registers vary on each scan. + +Right now, libfprint doesn't do the "sample #1" low quality scan, but dives right in and does a scan with registers configured like they were for sample #14 above. Of course, the register values should depend on finger pressure and image contrast and everything, but they currently do not. diff --git a/Software/fprint/libfprint/fdu2000.mdwn b/Software/fprint/libfprint/fdu2000.mdwn new file mode 100644 index 00000000..d68e68e1 --- /dev/null +++ b/Software/fprint/libfprint/fdu2000.mdwn @@ -0,0 +1,16 @@ + +This driver supports devices based on the [[SecuGen FDU2000 (aka SecuGen Hamster III) finger scanner|http://www.secugen.com/products/ph.htm]]. + +fdu2000 is part of [[libfprint|Software/fprint/libfprint]] and was originally written by Gustavo Chain, and is now maintained by Davidlohr Bueso. + +**Driver was not ported to asynchronous framework, so it's currently disabled in libfprint. If you're interested in this driver - drop a letter into [[mailing list|Software/fprint/Mailing list]] and we'll try to figure that out** + + +## Image info + +The image resolution obtained by this device is 260x300 pixels with a 500 dpi resolution. + + +## Image Performance + +The images obtained with this device are good (usually obtaining a score of 1 or 2 using the NFIQ algorithms). Due to this, the amount of minutiae is high (45+) allowing better/safer matching. diff --git a/Software/fprint/libfprint/upeksonly.mdwn b/Software/fprint/libfprint/upeksonly.mdwn new file mode 100644 index 00000000..ac554e31 --- /dev/null +++ b/Software/fprint/libfprint/upeksonly.mdwn @@ -0,0 +1,27 @@ + +The `upeksonly` driver supports devices based on the [[UPEK TouchStrip chipset|http://www.upek.com/solutions/pc_and_networking/chipsets_sensors.asp]] (sensor-only version). + +upeksonly is part of [[libfprint|Software/fprint/libfprint]] and is developed/maintained by Daniel Drake. + + +## Supported devices + +This driver supports fingerprint readers found embedded into many commercial laptops, including some System76 laptops and IBM/Lenovo [[ThinkPads|ThinkPads]]. The device sits on the USB bus with USB ID 147e:2016. + +The driver does **not** support the [[TouchStrip|TouchStrip]] variants which include a biometric co-processor. The co-processor variants have a different USB ID and are instead supported by the [[upekts|Software/fprint/libfprint/upekts]] driver. + + +## Driver history + +This driver was developed by Daniel Drake, based on bus traffic analysis of a pre-release of UPEK's BSAPI Linux SDK. The hardware was donated by [[System76|http://www.system76.com]] - thanks! + + +## Device operation + +[[!img Sample scanned image] + +Being a sensor-only device, this is an imaging device. The device repeatedly sends greyscale image rows of width 288 pixels, sampled at very high frequency. The high frequency means that there is a lot of bus traffic generated and there is a lot of similarity between one row and the next. As a result of this, most rows are discarded by the driver - only ones that differ significantly from the previous one are kept. The combination of high frequency row sampling and driver-level change detection allows the resultant fingerprint image to be smooth and proportional even when finger swipe speed is significantly altered during the scan. + +The hardware has finger-on-sensor detection which is used by this driver. I don't think there is any hardware-based finger removal detection, so the driver just looks for a significant number of blank lines before reporting finger removal. + +There is some fuzz in the image, which could potentially be eliminated by some post-processing algorithms. diff --git a/Software/fprint/libfprint/upektc.mdwn b/Software/fprint/libfprint/upektc.mdwn new file mode 100644 index 00000000..02fb1034 --- /dev/null +++ b/Software/fprint/libfprint/upektc.mdwn @@ -0,0 +1,33 @@ + +[[!img eikontouch300.jpg] + +The `upektc` driver supports devices based on the [[UPEK TouchChip chipset|http://www.upek.com/solutions/pc_and_networking/usb_readers.asp]] and [[EikonTouch 300|http://www.authentec.com/Products/TouchChips/USBReaders.aspx]]. + +upektc is part of [[libfprint|Software/fprint/libfprint]] and was developed by Jan-Michael Brummer. + + +## Supported Devices + +This driver supports the device found in the Samsung P35 laptop, also it supports standalone [[UPEK EikonTouch 300|http://www.authentec.com/Products/TouchChips/USBReaders.aspx]] device. + +This driver does **not** support the UPEK Touch``Strip found in a lot of other laptops. Such hardware is supported by the [[upekts|Software/fprint/libfprint/upekts]] driver instead. + + +## Driver history + +This driver is an adaption of the code found in [[Jan-Michael Brummer's UPEK TouchChip driver project|http://www.tabos.org/fpm/#FingerPrint]]. These efforts were based on bus traffic analysis from the UPEK Windows driver. Eikon``Touch 300 support was based on [[patch from Moganeshwaran Rajasegaran|https://bugs.freedesktop.org/show_bug.cgi?id=45197]] + + +## Device operation + +This is an imaging device that returns greyscale images with 208x288 pixels. + + +## Security notes + +Fingerprint image data is sent unencrypted over the USB bus. + + +## Other capabilities + +This hardware has the capability to store fingerprints on the device. libfprint/upektc does not currently offer access to this functionality, but this will change in future. LEDs present in Eikon``Touch 300 are not supported diff --git a/Software/fprint/libfprint/upektc/eikontouch300.jpg b/Software/fprint/libfprint/upektc/eikontouch300.jpg Binary files differnew file mode 100644 index 00000000..2cc4518f --- /dev/null +++ b/Software/fprint/libfprint/upektc/eikontouch300.jpg diff --git a/Software/fprint/libfprint/upekts.mdwn b/Software/fprint/libfprint/upekts.mdwn new file mode 100644 index 00000000..1915da8f --- /dev/null +++ b/Software/fprint/libfprint/upekts.mdwn @@ -0,0 +1,70 @@ + +[[!img UPEK Eikon Reader] + +The `upekts` driver supports devices based on the [[UPEK TouchStrip chipset|http://www.upek.com/solutions/pc_and_networking/chipsets_sensors.asp]]. These devices were originally engineered and manufactured by [[SGS Thomson Microelectronics|http://www.st.com]] but they [[split the business and formed UPEK|http://eu.st.com/stonline/products/support/touchip/]] in 2004. + +upekts is part of [[libfprint|Software/fprint/libfprint]] and is developed/maintained by Daniel Drake. + + +## Supported devices + +This driver supports devices found in IBM/Lenovo [[ThinkPad|ThinkPad]] laptops, and can also be found embedded into some Dell and Toshiba laptops (amongst other devices). It is also found in the standalone [[Eikon fingerprint reader|http://www.upek.com/solutions/eikon/default.asp]]. + +These devices, although often embedded into laptops, are actually USB devices sitting on the USB bus. + +The driver does not support the [[TouchStrip|TouchStrip]] fingerprint reader with USB ID's 147e:2016 found in some of the newer [[ThinkPads|ThinkPads]]. This version of the device is just a sensor (no biometric coprocessor) and is instead supported by the [[upeksonly|Software/fprint/libfprint/upeksonly]] driver. + +This driver does not support devices based on the UPEK [[TouchChip|TouchChip]] (0483:2015). Such hardware is supported by the [[upektc|Software/fprint/libfprint/upektc]] driver instead. + +This driver does not work with fingerprint readers integrated into Sony laptops, even though they have the usual 0483:2016 ID. See [[../Unsupported_devices|Software/fprint/libfprint/Unsupported_devices]] + + +## Driver history + +This driver was based on code from the [[thinkfinger project|http://thinkfinger.sourceforge.net/]], developed by Timo Hoenig. Timo's work was an adaption of [[Pavel Machek's reverse engineering efforts|http://lkml.org/lkml/2006/8/2/237]]. + +Pavel's efforts were based on bus traffic analysis of [[UPEK's own closed-source drivers|http://www.upek.com/support/downloads/drivers/linux.asp]]. + + +## Device operation + +After initial inspection of UPEK's BioAPI-based Linux driver software and analysis of the corresponding bus traffic, Pavel observed that these devices must do image processing in hardware. The enrollment process for a single finger is approximately as follows: + +1. Initialise enrollment mode +1. Swipe finger 3 times +1. Receive about 200 bytes of data from the device, save to a file +Then, later, the verification process of that single finger is approximately: + +1. Initialise verification mode +1. Upload previously-saved fingerprint data to device (approx 200 bytes) +1. Swipe finger once +The device then gives a "yes" or "no" answer to the computer, as to whether the finger matched or not. + +This mode of operation is _vastly_ in contrast to other supported devices, which typically just present images to the host computer and leave the problem of processing and matching fingerprints to the software. On the other hand, it made reverse engineering these devices relatively easy. + +The simplicity of the software-level driver code makes for other interesting applications too. For example, most [[ThinkPads|ThinkPads]] can use the fingerprint scanner as a power-on password. This wouldn't be realistic for a device that requires software to do image processing. + +Like UPEK's system and thinkfinger, `upekts` operates the device as detailed above. I have made a visible effort in upekts to understand the command format and command flow in more detail than thinkfinger goes into, and as such, the code flows in a more linear fashion. However, there are still a lot of unknowns. + + +## Security notes + +After enrollment, the fingerprint data mentioned above is stored on disk. The format of this data is unknown, but **I have demonstrated that the device does not record further information internally and that this data is enough to uniquely identify your fingerprint**. I did this by enrolling my finger on one device, saving the data to disk, then uploading that data to a second device and successfully verifying my finger on that one. + +In other words, we store data on disk that can probably be used somehow to reconstruct certain elements of your fingerprint. + +Bus traffic is not encrypted (not that we understand the data format anyway). + + +## Other capabilities + +I briefly tested an Eikon device under windows, and was very impressed at it's wide range of capabilities (which are not available on the UPEK Linux driver). I assume all these capabilities are also present on the other devices you can find the [[TouchStrip|TouchStrip]] in. + +* Early on, the Windows software asks you if you'd like to store the fingerprints in the device or on the computer. +* If you choose to store on the device, it informs you that you can store 21 fingerprints there. Just in case you have 21 fingers. It also gives you functionality to delete them all off the device at any time. +* **The device can operate as an imaging device!** The Windows software includes a 'tutorial' mode where you can scan your finger and view it on-screen to check your swiping technique. The image quality looks fantastic here. +* I'm not sure if "storing on the computer" is similar to what happens above (just saving a small 200ish bytes of data) or actually storing the images on disk and doing software-based fingerprint image processing/matching. +* There is some encryption feature where the data stored on-disk can optionally be encrypted, based on a key that the device gives you only after you have successfully scanned your finger against one stored in hardware (or something like that). Interesting. +* One drawback of the way that the UPEK-linux/thinkfinger/upekts operate the device is that they can only verify a specified single finger at any one time (you can't ask it to identify one-of-ten enrolled scans, for example). This limits our horizons with upekts. However, at various points, the Windows driver asked me to "scan any finger" and it accepted any of them. They had all been enrolled "in hardware". So, these devices DO support identification somehow. +* The windows software also offers you the ability to scroll with the sensor. +The above suggests that the Windows driver operates the device in a very different way from the way the Linux options operate. Indeed, the bus traffic is rather different, but it doesn't seem easy to immediately dig further and reverse-engineer this functionality: after a few commands, the bus traffic seems to become encrypted or scrambled. I guess this can become a future project :) diff --git a/Software/fprint/libfprint/uru4000.mdwn b/Software/fprint/libfprint/uru4000.mdwn new file mode 100644 index 00000000..7b8b6fd1 --- /dev/null +++ b/Software/fprint/libfprint/uru4000.mdwn @@ -0,0 +1,85 @@ + +[[!img Microsoft Fingerprint Scanner] + +The `uru4000` driver supports devices based on the [[DigitalPersona U.are.U 4000/4000B/4500 chipsets|http://www.digitalpersona.com/products/dpFingRead.php]]. + +uru4000 is part of [[libfprint|Software/fprint/libfprint]] and is developed/maintained by Daniel Drake and Timo Teräs. + + +## Supported devices + +This driver supports the fingerprint scanners found in Microsoft products. Additionally, it supports the standalone and "module" UrU4000/4000B devices that you can get from [[DigitalPersona|DigitalPersona]], however these are hard to get hold of and are generally only privately sold to companies. + +The Microsoft devices are identical to the "official" ones, but [[DigitalPersona|DigitalPersona]] lock down their proprietary SDKs on a software level to only work with the [[DigitalPersona|DigitalPersona]] devices (i.e. you must pay extra and buy direct for the luxury of using SDKs). The uru4000 driver supports both devices equally. + +The drivers supplied by Microsoft for the Microsoft devices are only available for 32-bit Windows. fprint and uru4000 work on both 32-bit and 64-bit systems. **Ironically, thanks to fprint, Linux is the only 64-bit OS that supports the Microsoft Fingerprint Reader products** (Windows x64 users are [[out of luck|http://forums.microsoft.com/TechNet/ShowPost.aspx?PostID=1542768&SiteID=17]]). + +While this driver is believed to support the original [[DigitalPersona|DigitalPersona]] UareU 4000 device that was in circulation several years ago (the 4000B predecessor), my own device is semi-broken so I'm not able to say that it works for sure. + +In mid-2007, Microsoft released a new revision of their fingerprint reader (USB ID 0453:00ca). This new revision includes some increased security where the device challenges the authenticity of the driver. Using the [[chinese wall|http://en.wikipedia.org/wiki/Clean_room_design]] method, we have successfully [[reverse engineered|http://www.reactivated.net/weblog/archives/2007/12/libfprint-v005-supports-new-ms-hardware/]] these new security measures for interoperability with the new devices. As a result, these devices are supported in libfprint from v0.0.5 onwards. + + +## Driver history + +Daniel Drake reverse engineered the device protocol and formed the [[libdpfp project|http://dpfp.berlios.de]]. uru4000 is based on code from libdpfp, and libdpfp has been obsoleted by libfprint as a result. + +Timo Teräs reverse engineered the encryption cipher and implemented uru4500 support. + + +## Device operation + +These devices are imaging devices: they simply present images of the user's fingerprint to the host computer. The hardware makes no attempt to enhance, process, or compare fingerprint images. + +It is up to the software to process the images and implement fingerprint matching/verification. libfprint handles this internally. + +The devices are capable of detecting when a finger has been placed on or removed from the sensor, and can also be asked to capture images at any time. + +The device is driven in a mode-based way: there are modes such as "wait for finger", "wait for finger removal", and "capture continuously". Capturing a fingerprint is therefore approximated to: set "wait for finger" mode, wait for interrupt, set "capture continuously" mode, wait for image, set "wait for finger removal" mode, ... + +The device protocol is mostly understood, but there are still some unknowns. The auxiliary image capture is not fully understood at this time. + + +## Security notes + +Fingerprint images are encrypted over the USB bus. The encryption scheme is not strong, so it is possible to decrypt the image from USB traces. All control messages are unencrypted. + +In 2006, Mikko Kiviharju wrote a paper about the security of these devices and presented it at Black Hat Europe 2006. His [[slides|http://www.blackhat.com/presentations/bh-europe-06/bh-eu-06-Kiviharju/bh-eu-06-kiviarju.pdf]] and [[research paper|http://www.blackhat.com/presentations/bh-europe-06/bh-eu-06-Kiviharju/bh-eu-06-kiviharju-resources.zip]] are available for download. + + +## Imaging performance + +uru4000 seems to perform very well with libfprint's image processing code. When scanning my index finger 5 times, each scan yielded a healthy count of 43.6 minutiae on average. + +Against an enrolled print of 49 minutiae, scanning the same finger again a further 3 times results in a bozorth match scores of 118, 145, and 145. Anything above 40 represents a match. Scanning the other fingers on the same hand yields scores of 8, 6, 6, and 16. + + +## Other capabilities + +The Microsoft devices have an oval shape red light panel around the sensor (separate from the bright red scanning lights that illuminate your finger). The brightness of this can be set by the driver, for scan feedback and interesting visual effects. This feature is not present on [[DigitalPersona|DigitalPersona]]'s own packaging of the device. libfprint currently does not support this feature. + +The devices have an alternative fingerprint illumination mode, much dimmer with light solely originating from the CCD area, and it only captures a small portion of the fingerprint. The Microsoft/DigitalPersona drivers capture an image in this mode immediately after every scan, this is why you see the device 'blink' when scanning your finger using their drivers. The purpose of this mode is not entirely understood. uru4000 currently does not support this feature. + +[[!img Default illumination] [[!img Alternative illumination] + + +## Image info and optical behaviour + +In the default illumination mode, the scanner sends a 384x289 image separated into 2 USB transactions (prepended by a 64 byte header). Each pixel is represented as 1 byte, so rendering it as standard greyscale data yields the following: + +[[!img http://www.reactivated.net/fprint/img/Uru4000_raw_scan.jpg] + +Some points to note: + +* You can see some of the scanner internals (or a reflection of them) in the top right of the image +* The raw image quality is impressive - the fingerprint ridges are shown in bright white on a near-black background. +* There are two vertical columns of black at the very left and very right of the image. These were a big help in figuring out the image format and dimensions. +* The sensor is one of the larger ones I have seen, and you can see it captures a big region of my finger. +However, the image is upside down, back to front, and we generally deal with images of negated colours, here's the same image flipped around and with the colours inverted: + +[[!img http://www.reactivated.net/fprint/img/Uru4000_flipped_negated.jpg] + +During earlier development, several people commented that the Windows API's and whatnot produce larger images which show more of the finger. This isn't entirely correct - the optical characteristics of the device result in your finger being distorted in the raw images, so the software simply stretches the image so that it has the correct proportions. uru4000 doesn't currently do this, but will integrate [[Paulo Marques' anti-distortion code|http://lists.berlios.de/pipermail/dpfp-dev/2007-May/000309.html]] at some point in the future. + +The image is also distorted in that there is a reflection of the [[[http://en.wikipedia.org/wiki/Charge-coupled_device|http://en.wikipedia.org/wiki/Charge-coupled_device]] CCD] itself in the underside of the glass, resulting in a white square towards the center of each scan. This can easily be seen in a raw scan where no finger is present: + +[[!img http://www.reactivated.net/fprint/img/Uru4000_raw_clear_sensor.jpg] diff --git a/Software/fprint/pam_fprint.mdwn b/Software/fprint/pam_fprint.mdwn new file mode 100644 index 00000000..14ebc612 --- /dev/null +++ b/Software/fprint/pam_fprint.mdwn @@ -0,0 +1,102 @@ +## Introduction + +pam_fprint is a simple PAM module which uses [[libfprint|Software/fprint/libfprint]]'s fingerprint processing and verification functionality for authentication. In other words, instead of seeing a password prompt, you're asked to scan your fingerprint. + +pam_fprint is a proof-of-concept, and also my-first-PAM-module. It has some deficiencies: + +* Can't be configured in any way. +* Finds the first enrolled fingerprint that can be verified on a device that is currently plugged in, and uses that one and only that one. +* Reads enrolled fingerprints from users home directories. + * It will only work when trying to authenticate your own user account (as you can read your own home directory), or in the system login prompt (which runs as root). + * You cannot authenticate yourself as another user, since you don't have access to read that user's home directory. +pam_fprint is an open source project, licensed under the [[GNU GPL v2|http://www.gnu.org/licenses/old-licenses/gpl-2.0.html]]. + + +## Download + +See the [[Download]] page. + + +## Development + +This software is developed using the [[git version control system|http://git.or.cz/]]. The [[git user manual|http://www.kernel.org/pub/software/scm/git/docs/user-manual.html]] is very useful for new users. + +* git://github.com/dsd/pam_fprint.git +* [[View online at github|http://github.com/dsd/pam_fprint/tree/master]] +Contributions encouraged. Please submit patches on the [[mailing list|Software/fprint/Mailing list]]. + + +## Installation + +Some installation instructions can be found [[here|Software/fprint/Installation]] + + +## Setup + + +### Enrolling your fingers + +Example below: + + + # pam_fprint_enroll --help + Usage: ./pam_fprint_enroll options + -h --help Display this usage information. + -f --enroll-finger index Enroll finger with index. + + Valid indexes are: + 1 - Left Thumb + 2 - Left Index Finger + 3 - Left Middle Finger + 4 - Left Ring Finger + 5 - Left Little Finger + 6 - Right Thumb + 7 - Right Index Finger + 8 - Right Middle Finger + 9 - Right Ring Finger + 10 - Right Little Finger + + # pam_fprint_enroll --enroll-finger 7 + This program will enroll your finger, unconditionally overwriting any selected print that was enrolled previously. + If you want to continue, press enter, otherwise hit Ctrl+C + + Found device claimed by Digital Persona U.are.U 4000/4000B driver + Opened device. It's now time to enroll your finger. + You will need to successfully scan your Right Index Finger 1 times to complete the process. + + Scan your finger now. + Enroll complete! + Enrollment completed! + +You only need to enroll one finger. pam_fprint will always ask you for the first one that it finds. + + +### Configuring PAM + +Here are two setups on my system: Gentoo Linux with PAM 0.99.9.0 + + +#### Fingerprint acceptance sufficient, fall back on password otherwise + +/etc/pam.d/system-auth has sections for "auth", "account", "password" and others. Modify the file so that it looks like this: + + auth required pam_env.so + auth sufficient pam_fprint.so + auth sufficient pam_unix.so try_first_pass likeauth nullok + auth required pam_deny.so + +On my system, that simply equated to inserting line 2. It says that authentication through pam_fprint is sufficient to grant access to the user, but if pam_fprint fails to authenticate them, it's no big deal: fall back on password (pam_unix). + +This is somewhat insecure in that someone can simply unplug the fingerprint reader and enter your password as normal, so password security is as critical as always and fingerprint login is just for the cool factor. + + +#### Fingerprint acceptance required, no password input + +Make the _auth_ section of /etc/pam.d/system-auth look like this: + + auth required pam_env.so + auth required pam_fprint.so + +and remove other auth entries. + +This setup requires successful fingerprint verification through libfprint before login can succeed. I would not recommend doing this at this point in time, because libfprint is alpha software, and if it breaks, you're in trouble! diff --git a/Software/gallium.mdwn b/Software/gallium.mdwn new file mode 100644 index 00000000..17acc6bd --- /dev/null +++ b/Software/gallium.mdwn @@ -0,0 +1,97 @@ + + +# Gallium3D Technical Overview + +Gallium3D is a new architecture for building 3D graphics drivers. Initially supporting Mesa and Linux graphics drivers, Gallium3D is designed to allow portability to all major operating systems and graphics interfaces. + +[[Additional slides, videos and examples are online|http://www.freedesktop.org/wiki/Software/gallium/GAOnlineWorkshop]] for learning the internals of the Gallium3D architecture are available. + +Compared to existing Linux graphics drivers, Gallium3D will: + +* Make drivers smaller and simpler. + * Current DRI drivers are rather complicated. They're large, contain duplicated code and are burdened with implementing many concepts tightly tied to the OpenGL 1.x/2.x API. +* Model modern graphics hardware. + * The new driver architecture is an abstraction of modern graphics hardware, rather than an OpenGL->hardware translator. The new driver interface will assume the presence of programmable vertex/fragment shaders and flexible memory objects. +* Support multiple graphics APIs. + * The reduced OpenGL 3.1+ APIs will be much smaller than OpenGL 1.x/2.x. We'd like a driver model that is API-neutral so that it's not tied to a specific graphics API. +* Support multiple operating systems. + * Gallium drivers have no OS-specific code (OS-specific code goes into the "winsys/screen" modules) so they're portable to Linux, Windows and other operating systems. +This document describes the software components of the Gallium3D architecture. The intended audience is graphics software developers. + + +## Building Gallium3D Reference Drivers + +Gallium3D is designed to support multiple API's, multiple GPU's, and Multiple OS and windowing systems. The following reference drivers are specific to certain environments. Here are the build instructions for each of the reference drivers: + +* [[OpenGL and OpenVG Gallium Softpipe Drivers for EGL/Linux Environment|http://www.freedesktop.org/wiki/Software/gallium/EGLReferenceDrivers]] + +## The Gallium3D Interface + +The public interface of a Gallium3D driver is described by the src/gallium/include/*.h header files. + +The pipe_context structure (in p_context.h) is an abstract base class with per-context methods for: + +* Setting rendering state (texture sampler state, blending state, rasterization state, vertex array info, drawing surfaces, etc.) +* Setting shader state, using the TGSI binary shader representation. +* Vertex array and indexed vertex array drawing. +The p_state.h file defines data structures for things such as: + +* Graphics state (blending, texture sampling, rasterization) +* Texture and surface resources +* Vertex array layout +The pipe_screen structure is an abstract base class with context-independent methods for: + +* Creating textures (and drawing surfaces) +* Getting "views" into textures +* Hardware queries (number of texture units, max texture size, etc). +* Creating generic memory buffers +* Mapping/unmapping buffers +* Fencing +By abstracting OS and window system services, pipe drivers are portable to other platforms (e.g. embedded devices). + +Additional [[Gallium3D interface|gallium_interface]] information. + + +## State Trackers + +The Mesa state tracker is the piece which interfaces core Mesa to the Gallium3D interface. It's responsible for translating Mesa state (blend modes, texture state, etc) and drawing commands (like glDrawArrays and glDrawPixels) into pipe objects and operations. + +Traditional fixed-function OpenGL components (such as lighting and texture combining) are implemented with shaders. OpenGL commands such as glDrawPixels are translated into textured quadrilateral rendering. Basically, any rendering operation that isn't directly supported by modern graphics hardware is translated into a hardware-friendly form. + +Future state trackers will be created for OpenGL 3.0 and OpenGL-ES 2.x. + + +## Ancillary Modules + +A number of ancillary modules are available to Gallium3D drivers: + +1. The [[Draw|Software/gallium_draw]] module provides point/line/polygon rendering services such as vertex transformation, polygon culling and clipping. It will be used by drivers for hardware which lacks vertex transformation (such as the i915/i945). It may also be instantiated and used directly by the state tracker to implement some API functionality that doesn't map well to hardware capabilities. + +2. The TGSI module provides a universal representation of shaders and CPU-based execution of shaders. All Mesa vertex/fragment programs and shaders are translated into the TGSI representation before being passed to the driver. In turn, the driver will convert the TGSI instructions into GPU-specific instructions. For hardware that lacks vertex or fragment shader support, the TGSI's executor can be used. The TGSI executor includes support for SSE code generation. Support for other processors (such as Cell) will be added in the future. + +3. The RTASM module provides support for Run-Time Assembly/Machine code generation. There are sub-modules for X86/SSE, PPC and Cell machine code generation. + +4. The CSO module provides support for Constant State Objects. CSOs help to filter out redundant state changes from getting sent to the driver. State changes can be expensive and we want to avoid them whenever possible. + +5. The util module has code for debugging, image manipulation, hashing, math and miscellaneous helper routines. + + +## Drivers + +As of fall 2011 there are approximately 10 gallium drivers in the source tree. Most are mature and work pretty well. + + +## Deprecated Drivers + +The Intel i965 driver, the Cell driver and the failover drivers were removed from the Mesa/gallium source tree in November 2011 since they were unmaintained. If someone is interested in reviving a driver the code can be recovered from git. + +See the [[Gallium status page|http://www.x.org/wiki/GalliumStatus]] for more information. + + +## References + +[[Gallum3D talk from XDS 2007|gallium3d-xds2007.pdf]] + +[[Cross-referenced source code|http://people.freedesktop.org/~jrfonseca/gallium/]] + +[[TGSI specification|tgsi-specification.pdf]] diff --git a/Software/gallium/GAOverview.pdf b/Software/gallium/GAOverview.pdf Binary files differnew file mode 100644 index 00000000..6e81eca2 --- /dev/null +++ b/Software/gallium/GAOverview.pdf diff --git a/Software/gallium/GalliumOverview.pdf b/Software/gallium/GalliumOverview.pdf Binary files differnew file mode 100644 index 00000000..44809adb --- /dev/null +++ b/Software/gallium/GalliumOverview.pdf diff --git a/Software/gallium/gallium3d-xds2007.pdf b/Software/gallium/gallium3d-xds2007.pdf Binary files differnew file mode 100644 index 00000000..8337473a --- /dev/null +++ b/Software/gallium/gallium3d-xds2007.pdf diff --git a/Software/gallium/tgsi-specification.pdf b/Software/gallium/tgsi-specification.pdf Binary files differnew file mode 100644 index 00000000..3d291b56 --- /dev/null +++ b/Software/gallium/tgsi-specification.pdf diff --git a/Software/gallium_draw.mdwn b/Software/gallium_draw.mdwn new file mode 100644 index 00000000..8ef1e4d0 --- /dev/null +++ b/Software/gallium_draw.mdwn @@ -0,0 +1,35 @@ + + +# The Gallium3D Draw Module + +[[Gallium3D|Software/gallium]] provides a helper module implementing the vertex fetch, vertex transformation and primitive assembly steps of the 3D pipeline. The interface of this module corresponds closely to the subset of the Gallium Driver Interface which is relevent to these steps in the pipeline. Specifically there are calls for: + +* Vertex shader constant state objects +* Vertex buffer binding +* Vertex element layout (vertex fetch) constant state objects +* Drawing indexed and non-indexed vertex arrays +* Rasterizer constant state objects. +The Draw module is effectively the part of softpipe which is concerned with vertex processing, split off into a separate module so that it can be reused by drivers for rasterization-only hardware. As such it is also instantiated by the i915simple driver. + +The Draw module's pipeline implements clipping, culling, two-sided lighting selection, converting wide lines/points into triangles, etc. The final stage of the pipeline may either pass the point/line/tri primitives to the device driver for rasterization, or it may build vertex and index buffers. The vertex/index buffers can be allocated from graphics memory and match hardware-specific formats. + +Finally, there are cases in the Mesa/OpenGL state_tracker where transformed vertices are needed, yet it is anticipated that using hardware transformation would reduce performance, usually because the setup costs or latency are prohibitive. For this reason the Mesa state_tracker also instantiates a private copy of the Draw module for implementing glRasterPos, and GL_SELECT/GL_FEEDBACK rendering modes. + + +## Code walk-through: glDrawElements + +glDrawElements basically maps to the pipe->draw_elements() method. Before it's called though, the state tracker code needs to tell the gallium context two things: + +1. The vertex format (which attributes, number of components and datatypes). This is described with the pipe_vertex_element type and calls to pipe->set_vertex_element(). + +2. The location of the vertex arrays in memory (in buffer objects). The Mesa vbo module puts the array data into VBOs and the state tracker tells the gallium context about the buffers with the pipe_vertex_buffer type and calls to pipe->set_vertex_buffer(). + +When pipe->draw_elements() is called that dispatches into the device driver. If you have full TnL hardware, you'll basically use the vertex format/buffer info to program the hardware and let it rip. + +For non-TnL hardware, the 'pipe/draw/' utility module comes into play. It does sw-based vertex transformation, primitive assembly, clipping, etc. emitting screen-coord points/lines/triangles at the end. + +The draw module transforms 4 vertices at a time (like we do "quads" of fragments) to allow SOA (or AOS) processing. + +There's also a vertex cache/buffer (32 verts) and primitive (point/line/tri) cache for efficient primitive assembly, etc. + +When the prim cache (or vertex cache) is full, we begin rendering a batch of primitives (points/lines/tris) by passing them through the "prim pipeline" which is a sequence of stages like clipping, front-back face determination, culling, glPolygonMode, glPolygonOffset, etc. The last stage of this pipeline (which actually renders the prim) is not in the 'draw' module. It's provided by the device driver (see sp_prim_setup.c or cell_render.c, for example). diff --git a/Software/glitz.mdwn b/Software/glitz.mdwn new file mode 100644 index 00000000..13edc2ac --- /dev/null +++ b/Software/glitz.mdwn @@ -0,0 +1,44 @@ +## glitz + +Glitz is an OpenGL image compositing library. Glitz provides Porter/Duff compositing of images and implicit mask generation for geometric primitives including trapezoids, triangles, and rectangles. + +The semantics of glitz are designed to precisely match the specification of the X Render extension. Glitz does not only implement X Render features like component alpha and image transformations, but also support for additional features like convolution filters and color gradients, which are not currently part of the X Render specification. + +The performance and capabilities of glitz are much dependent on graphics hardware. Glitz does not in any way handle software fall-backs when graphics hardware is insufficient. However, glitz will report if any requested operation cannot be carried out by graphics hardware, hence making a higher level software layer responsible for appropriate actions. + +Glitz can be used as a stand-alone layer above OpenGL but is also designed to act as a backend for [[cairo|http://cairographics.org/]], providing it with OpenGL accelerated output. + + +### Source Repository Access + + # Anonymous access: + $ git clone git://git.freedesktop.org/git/glitz + # Developer access: + $ git clone ssh+git://git.freedesktop.org/git/glitz + +The glitzinfo and rendertest modules might also be of interest: + + $ cvs -d:pserver:anoncvs@cvs.freedesktop.org:/cvs/cairo login + CVS password: <hit return> + $ cvs -d:pserver:anoncvs@cvs.freedesktop.org:/cvs/cairo co glitzinfo + $ cvs -d:pserver:anoncvs@cvs.freedesktop.org:/cvs/cairo co rendertest + +### Download + +Development snapshots of glitz are available for download [[here|http://cairographics.org/snapshots/]]. + + +### Examples + +Several test/demo [[applications|http://www.cs.umu.se/~c99drn]] are available. + + +### Screenshots + +* [[rendertest]] <-- (No link?) + +### Documentation + +The USENIX'04 freenix track [[paper|http://www.usenix.org/events/usenix04/tech/freenix/nilsson.html]]. + +-- Main.[[DavidReveman]] - 20 Jul 2004 diff --git a/Software/gtk-qt.mdwn b/Software/gtk-qt.mdwn new file mode 100644 index 00000000..16c7b2b2 --- /dev/null +++ b/Software/gtk-qt.mdwn @@ -0,0 +1,11 @@ + + +## GTK-Qt Theme Engine + +The GTK-Qt Theme Engine is a plugin for GTK that allows GTK applications to use Qt widget styles. + +Aimed primarily at KDE users, this plugin provides a way to unify the look and feel of the Linux desktop. + +**The website for the GTK-Qt Theme Engine has moved to [[http://gtk-qt.ecs.soton.ac.uk/|http://gtk-qt.ecs.soton.ac.uk/]]** + +([[old version of this page|http://freedesktop.org/wiki/Software_2fgtk_2dqt?action=recall&date=1152138333]]) diff --git a/Software/hal.mdwn b/Software/hal.mdwn new file mode 100644 index 00000000..b4bd0391 --- /dev/null +++ b/Software/hal.mdwn @@ -0,0 +1,94 @@ + + +# HAL - Hardware Abstraction Layer +[[!table header="no" class="mointable" data=""" + HAL [[is in maintenance mode|http://lists.freedesktop.org/archives/hal/2008-May/011560.html]] - no new features are added. All future development focuses on [[udisks|Software/udisks]], [[upower|http://upower.freedesktop.org/]] and other parts of the stack. See [[Software/DeviceKit|Software/DeviceKit]] for more information. +"""]] + +These pages attempt to provide a specification and an implementation of a hardware abstraction layer. + For a good background on what a HAL does, see the [["Making Hardware Just Work"|http://www.ometer.com/hardware.html]] article that motivated this work. + +[[Frequently Asked Questions|Software/HalFAQ]] + + +## Source Code + +* View latest code on-line: [[http://cgit.freedesktop.org/hal/tree/|http://cgit.freedesktop.org/hal/tree/]] +* View latest changelog/commitlog online: [[http://cgit.freedesktop.org/hal/log/|http://cgit.freedesktop.org/hal/log/]] +* Building development tree: [[HAL Build Instructions|Software/HalBuildInstructions]] +* Tarballs are available at [[http://hal.freedesktop.org/releases/|http://hal.freedesktop.org/releases/]] + +### GIT + +Git is now being used for HAL. There is a [[nice tutorial for using git with freedesktop.org projects|http://freedesktop.org/wiki/UsingGit]]. There is also another tutorial at [[IBM Developerworks site|http://www-128.ibm.com/developerworks/linux/library/l-git/]]. You can also take a look at [[http://cgit.freedesktop.org/hal/tree/HACKING|http://cgit.freedesktop.org/hal/tree/HACKING]]. + + +### hal-info + +hal-info is a small hal sub-package that provides the hardware data and quirks. These quirks are currently things like what mice support reporting battery status, what music players are supported and what cameras are detected. + +hal-info and hal should not be packaged together. When packaging hal, it should depend on hal-info, of any version. hal-info should also be checked out in the same level directory as hal if you intend to use ./run-hald.sh + +There are no official tarball releases yet, but you can get the latest code from [[git|http://cgit.freedesktop.org/hal-info/]] and release tar.gz from [[http://hal.freedesktop.org/releases/|http://hal.freedesktop.org/releases/]]. See [[here|http://hughsient.livejournal.com/6702.html]] for more information. + + +### Dependencies + + * Linux kernel 2.6.19 (or later) + * util-linux 2.15 (or later) + * udev 125 (or later) + * dbus 0.61 (or later) + * glib 2.6.0 (or later) + * expat 1.95.8 (or later) + * bash 2.0 (or later) + * hal-info 20070402 (or later) + +#### Optional Dependencies + + * libusb >= 0.1.10a + * pciutils >= 2.2.3 + * dmidecode >= 2.7 + * parted == 1.7.1, 1.8.0, 1.8.1, 1.8.2 or 1.86 + * cryptsetup-luks >= 1.0.1 + * libsmbios >= 0.13.4 + +## Bugs? + +* [[Guide to reporting HAL bugs|Software/HalTraces]] + +## Communicate + +* Mailing lists: + * [[!table header="no" class="mointable" data=""" +HAL Discussion | [[hal@lists.freedesktop.org|http://lists.freedesktop.org/mailman/listinfo/hal]] +HAL commit notification | [[hal-commit@lists.freedesktop.org|http://lists.freedesktop.org/mailman/listinfo/hal-commit]] +"""]] + +* IRC: + * [[#hal|http://freenode.net]] on freenode.net + +## HOWTOs + +* [[Guide to using powermanagement quirks to fix resume|http://people.freedesktop.org/~hughsient/quirk/quirk-suspend-index.html]] +* [[Guide to using keymap quirks to fix unknown scancodes|http://people.freedesktop.org/~hughsient/quirk/quirk-keymap-index.html]] + +## Documentation + +* [[Latest HAL specification|http://people.freedesktop.org/~david/hal-spec/hal-spec.html]] +* [["System Integration and GNOME|http://people.freedesktop.org/~david/talks/system-integration-and-gnome-guadec2006-davidz.odp]] by David Zeuthen (GUADEC June 2006) - ODF +* [["System Integration and GNOME|http://people.freedesktop.org/~david/talks/system-integration-and-gnome-guadec2006-davidz.pdf]] by David Zeuthen (GUADEC June 2006) - PDF +* [["HAL reverse engineered" (for OpenSolaris)|http://opensolaris.org/os/project/tamarack/hal_re.html]] by Artem Kachitchkine (April 2006) +* [["Adding encryption support to HAL: A user's experience with Fedora development" (Red Hat Magazine)|http://www.redhat.com/magazine/012oct05/features/hal/]] by W. Michael Petullo (October 2005) +* [["Desktop and Hardware Configuration" (Red Hat Magazine)|http://www.redhat.com/magazine/003jan05/features/hal/]] by David Zeuthen (January 2005) +* [["Making Hardware Just Work"|http://www.ometer.com/hardware.html]] by Havoc Pennington (July 2003) + +## External Resources + +* [[libhal++|http://projects.backtrace.info/index.php/Main/HAL]]: C++ wrapper for libhal and libhal-storage. As of now not supported by the HAL project/developers: bug reports/requests please to internalerror AT gmail.com (M.Derezynski) +* libhal++ has now been superceded by HAL/C++, a reimplementation of libhal and libhal-storage in C++. The project can be found at the same server, [[HAL/C++|http://projects.backtrace.info/index.php/Main/Halmm]] +* [[gnome-mount|http://www.linuxfromscratch.org/blfs/view/svn/gnome/gnome-mount.html]] + + +--- + + [[CategoryHardware|CategoryHardware]] diff --git a/Software/icon-slicer.mdwn b/Software/icon-slicer.mdwn new file mode 100644 index 00000000..8102c081 --- /dev/null +++ b/Software/icon-slicer.mdwn @@ -0,0 +1,40 @@ + + +## icon-slicer + +icon-slicer is a utility for generating icon themes and libXcursor cursor themes. + +The inputs to icon-slicer are conceptually: + + * 1 A set of multi-layer images, one for each size. 2 A XML theme description file +Each image contains all the cursors arranged in a grid; For cursors the layers are: + + * A layer with a dot for the hotspot of each cursor + * The main image or first animation frame for multi-frame animated cursors + * The second animation frame for multi-frame animated cursors + * ... +For icons, the layers are: + + * A layer with the images + * An optional layer with attachment points for emblems + * An optional layer with boxes for embedding text into icons. +In practice, since loading of multilayer images is not supported by standard image libraries, each layer is input as a separate image file. + +The theme description file contains, among other things, information about the source images to read, the location of each named cursor or icon within the grid, and a set of aliases from names to other names. + +Compiling icon slicer requires [[GTK+-2.x|ftp://ftp.gtk.org/pub/gtk/v2.2/]] (for gdk-pixbuf) and [[popt|ftp://ftp.rpm.org/pub/rpm/dist/rpm-4.2.x/]] to compile. + + +### CVS + +The [[CVS|GettingInvolved]] module for this spec is "icon-slicer". + + +### Documentation + +The [[README|http://freedesktop.org/software/icon-slicer/README]] file contains information about the file format, and command line invocation. + + +### Download + + * [[icon-slicer-0.3.tar.gz|http://freedesktop.org/software/icon-slicer/releases/icon-slicer-0.3.tar.gz]]: Initial release. diff --git a/Software/icon-theme.mdwn b/Software/icon-theme.mdwn new file mode 100644 index 00000000..7134b237 --- /dev/null +++ b/Software/icon-theme.mdwn @@ -0,0 +1,21 @@ + + +## default-icon-theme + +This has moved to [[http://icon-theme.freedesktop.org/wiki/HicolorTheme|http://icon-theme.freedesktop.org/wiki/HicolorTheme]] for now. This might change in the future. + +icon-theme contains the standard also references the default icon theme called hicolor. + + +### Git + +The [[Git|Infrastructure/git]] module for this code is [[xdg/default-icon-theme|http://cgit.freedesktop.org/xdg/default-icon-theme/]]. + + +### Download + + * [[hicolor-icon-theme-0.5.tar.gz|http://freedesktop.org/software/icon-theme/releases/hicolor-icon-theme-0.5.tar.gz]] + * [[hicolor-icon-theme-0.4.tar.gz|http://freedesktop.org/software/icon-theme/releases/hicolor-icon-theme-0.4.tar.gz]] + * [[hicolor-icon-theme-0.3.tar.gz|http://freedesktop.org/software/icon-theme/releases/hicolor-icon-theme-0.3.tar.gz]] + * [[hicolor-icon-theme-0.2.tar.gz|http://freedesktop.org/software/icon-theme/releases/hicolor-icon-theme-0.2.tar.gz]] + * [[default-icon-theme-0.1.tar.gz|http://freedesktop.org/software/icon-theme/releases/default-icon-theme-0.1.tar.gz]]
\ No newline at end of file diff --git a/Software/imbus.mdwn b/Software/imbus.mdwn new file mode 100644 index 00000000..d8f43ea9 --- /dev/null +++ b/Software/imbus.mdwn @@ -0,0 +1,5 @@ + + +## IMBUS + +IMBUS is a common tier-1 layer of IM frameworks for connecting IM engine containers which loads IM engine modules, and client libraries for applications. diff --git a/Software/immodule-qt.mdwn b/Software/immodule-qt.mdwn new file mode 100644 index 00000000..f6503780 --- /dev/null +++ b/Software/immodule-qt.mdwn @@ -0,0 +1,70 @@ + + +## immodule for Qt + +**immodule for Qt** is a modular, extensible input method subsystem for Qt. + +This project brings functionality similar to the immodule for GTK+ to the Qt library. The main goal of the project is to extend and enhance the input method support in the Qt library, in order to provide a modern and powerful multi-language input system. Our short term goal is to make Qt (especially Qt/X11) "up-to-date" with other X11-based toolkits such as GTK+. We are also focusing on what the input method API should be for future Qt versions. + + +### Status + +We are cooperating with Trolltech. They are looking into our patch for Qt3. They have indicated that including the patch in a Qt 3.3.x release is difficult due to their bugfix-only policy for minor version releases. However, the patch may become a recommended patch for distributions to include. + + +#### binary compatible version for Qt3 + +Our latest stable patch had been released on 10 Sep 2004. + + +#### advanced version for Qt4 + +We are separately working on designing an advanced framework for Qt4, which is not limited by the binary compatibility requirements of Qt3. + +We had released first experimental patch for Qt4 technical preview1 on 22 Aug 2004. Although some text widgets (`QTextEdit` and `Q3TextEdit`) is not developed well for running with the immodule patch, other features are working well with `QLineEdit`. + +Some features such as customizable input context to widget mapping has already been developed. However, some other features such as language tagging, preedit attributes and surrounding text support are still under development. + + +### Mailinglist + +[[immodule-qt@lists.freedesktop.org|http://lists.freedesktop.org/mailman/listinfo/immodule-qt]] + +This list is for both developers and users. Follow the above link for further information. We appreciate feedback from both those looking to develop with the framework, Qt application developers, as well as end users. + + +### Download + +* Download latest patches from [[Software/ImmoduleQtDownload|Software/ImmoduleQtDownload]]. Svn repository is also available. + +### How to install + +The 'Binary Compatible' patch is recommended for daily use. Some of Linux distros contain packages with the immodule patch included. [[Instructions for manual installation|Software/ImmoduleManualInstallation]] are also available. + + +### How to use + +See README.immodule included in the patch. + + +### Developers and contributors + +* Choe Hwanjin author of [[qimhangul|http://cvs.kldp.net/viewcvs/qimhangul/]] Korean input method +* Daisuke Kameda original author of the patch, project maintainer +* Hideki Hiura adviser, powerful endorser +* Karl Park, author of iiimqcf +* Kazuki Ohta a developer, an author of [[Software/UimQt|Software/UimQt]] +* Ken Deeter document writer, translator +* [[LiuCougar|LiuCougar]] a developer of SCIM project, focus on KDE/Qt support, author of [[skim|Software/ScimKDE]] and [[scim-qtimm|Software/ScimQtImm]] +* [[YamaKen|YamaKen]] main developer for recent months, a developer of [[Software/uim|Software/uim]] project + +### Links + +* [[About this project|http://www.kde.gr.jp/~daisuke/immodule_for_qt/pukiwiki/?cmd=read&page=ImmoduleForQtDocsForTrolltechPass2]] CAUTION: technical information is outdated +* [[old project page|http://www.kde.gr.jp/~daisuke/immodule_for_qt/pukiwiki/]] Sorry, some informations are described in Japanese. +* [[Software/ImmoduleQt4RequirementsDocument|Software/ImmoduleQt4RequirementsDocument]] Functional Requirements for a Input method subsystem +* [[IIIMF project|http://www.openi18n.org/modules.php?op=modload&name=Sections&file=index&req=viewarticle&artid=30&page=1]] has an immodule plugin named IIIMQCF +* [[Software/scim|Software/scim]] has a full-featured immodule plugin [[scim-qtimm|http://scim.freedesktop.org/Software/ScimQtImm]] +* [[Software/uim|Software/uim]] has a working immodule plugin [[UimQt|Software/UimQt]] +* [[Qt 4 Technical Preview|http://www.trolltech.com/products/qt/whatsnew.html]] +-- Main.[[YamaKen|YamaKen]] - 10 Sep 2004
\ No newline at end of file diff --git a/Software/ipcf.mdwn b/Software/ipcf.mdwn new file mode 100644 index 00000000..1c841066 --- /dev/null +++ b/Software/ipcf.mdwn @@ -0,0 +1,18 @@ + +IPCF - The [[InterPersonal|InterPersonal]] Communication Framework project + +The aim of this project is to provide a framework that unifies all forms of real time conversations, including, but not limited to, instant messaging, IRC and voice and video over IP. It aims to provide an interface to client applications allowing them to implement, in a minimal number of lines of code, real time communication over any implemented protocol. + +This diagram provides a good overview (corrections, modifications and ideas most welcome): [[http://farsight.sourceforge.net/convframework.dia|http://farsight.sourceforge.net/convframework.dia]] + +Core components are: + +Presence manager - signals when the methods of communication available for known people change. should this also manage account information? + +Conversation manager - provides a unified conversion api over dbus for all known protocol types, this includes text communication, state change requests, service access request (e.g. voicemail retrieval, retrieval of stored messages, call transfer, etc.). Should have a plugin system for supported protocols. + +Multimedia Manager - handles realtime multimedia handling. controlled by conversation manager, but will often need to be in the clients process to allow for embedding of video, etc. Should there be a way this can be out of process, say using XEmbed? + +The core units of communication is a Person or a Room. A Conversation can take place with a Person, a group of Persons, or everyone in a Room. For any given conversion there will be none, one or more methods available for holding that conversion. These methods can be identified by a protocol type, or by a set of capabilities. (e.g. IRC/[text,file transfer], MSN/[text/icons/file transfer/voice/video]) + +Open Questions: What about when there's multiple ways of fulfilling a given capability? (e.g. msn video conferencing/msn video conversations/msn webcam) The user should be able to specify, if she cares, or the the best available should be chosen if she doesn't. diff --git a/Software/jhbuild.mdwn b/Software/jhbuild.mdwn new file mode 100644 index 00000000..64fc80d5 --- /dev/null +++ b/Software/jhbuild.mdwn @@ -0,0 +1,146 @@ + + +# Introduction + +JHBuild is a program that can be used to pull a number of modules from a variety of sources (CVS, Subversion, Git, Bazaar, tarballs...) and build them in the correct order. Unlike some build scripts, JHBuild lets you specify what modules you want built and it will then go and build those modules plus dependencies. + +Although JHBuild was originally developed to build [[GNOME|http://www.gnome.org/]], it is now able to build a number of the modules in freedesktop.org CVS. Extending it to handle new modules is usually trivial (assuming the build infrastructure matches the other modules it handles). + +Uptodate [[JHBuild Documentation|http://library.gnome.org/devel/jhbuild/unstable/]] is available on [[GNOME Library|http://library.gnome.org]]. There is also useful contents in the [[Jhbuild|http://live.gnome.org/Jhbuild]] page of GNOME wiki. + + +# Installation + +To install JHBuild, you will need to check it out of Gnome git. I recommend checking it out into the directory where you will store the working copies of the modules you want to build. This can be done with the following commands: + + $ git clone git://git.gnome.org/jhbuild + +Jhbuild can be installed to `~/bin` (which should be in your path) with the following commands: + + $ cd jhbuild + $ ./autogen.sh + $ make + $ make install + +Before making use of JHBuild, you should make sure the required build tools are installed. + + +# Prerequisites + +To use JHBuild, you will need to install various build tools. These include: + +* [[Python|http://www.python.org/]] >= 2.0 with expat support (jhbuild needs the Python XML modules). +* [[autoconf|http://www.gnu.org/software/autoconf/]] 2.5x +* [[automake|http://www.gnu.org/software/automake/]] 1.4-p6, 1.7.x, 1.8.x and 1.9.x (these are parallel installable). +* [[libtool|http://www.gnu.org/software/libtool/]] >= 1.5 +* [[gettext|http://www.gnu.org/software/gettext/]] >= 0.10.40 +* [[pkgconfig|Software/pkgconfig]] + +Some packages won't require all of these tools, while others may have more prerequisites. + +On a Red Hat Linux 9 system, most of these prereqisites should be included with the distribution. The remaining packages can be found in Rawhide. I installed `automake-1.7.8`, `automake16-1.6.3`, `libtool-1.5` and `libtool-libs-1.5` RPMs from Rawhide over a fresh RH9 install to satisfy the prerequisites. + +Fedora Core 2 contains acceptable versions of the above tools. + +Slackware 12 contains acceptable versions of the above tools, with the exception of automake, only version 1.9.6 is included. + +_Feel free to add notes about other distros as needed -- [[JamesHenstridge]]_ + + +# The Configuration File + +JHBuild uses a configuration file to control what gets built. The configuration file is `~/.jhbuildrc`, and uses standard Python syntax. There are a few sample configuration files distributed with jhbuild. Below is a sample configuration file suitable for building [[cairo|http://www.cairographics.org/]] and [[dbus|Software/dbus]]: + + + # what to build? + moduleset = 'freedesktop' + modules = [ 'cairo', 'dbus' ] + + # if you have write access to the repository, you can change + # what cvsroot is used to check things out. The default is + # anonymous pserver access. + cvsroots['cairo.freedesktop.org'] = ':ext:james@cvs.freedesktop.org:/cvs/cairo' + + # where should working copies go? + checkoutroot = os.environ['HOME'] + '/cvs/freedesktop' + # in what prefix should things be installed? (must be writable) + prefix = os.environ['HOME'] + '/prefix' + + # extra arguments to pass to the autogen.sh script? + autogenargs = '--enable-maintainer-mode --disable-static' + + # use an alternative install program that preserves the + # mtime on header files if they haven't changed. Speeds + # up rebuilds. + os.environ['INSTALL'] = os.environ['HOME'] + '/bin/install-check' + +Here is a list of some of the variables that can be set in the `~/.jhbuildrc` file: + +* moduleset: the collection of modules containing the modules to be built. The 'freedesktop' module set includes the freedesktop.org modules, so should be sufficient. If you want to build some Gnome modules as well, set this to 'gnome-2.24'. This can also be the URL of a modules file, which makes it possible to maintain module sets outside of Gnome Subversion. +* modules: a list of the modules to build. The list of modules covered by the 'freedesktop' moduleset can be found in [[jhbuild/modulesets/freedesktop.modules|http://cvs.gnome.org/viewcvs/jhbuild/modulesets/freedesktop.modules?rev`HEAD&view`auto]]. +* skip: a list of modules to skip. Useful if you want to use the system version of some modules. +* cvsroots: a dictionary mapping CVS repository names to cvs roots. Used to override the default cvs roots. +* checkoutroot: where to store working copies of the modules that get checked out. +* prefix: where to install things. Must be writable by the user. +* autogenargs: arguments to pass to all `autogen.sh` scripts. `--disable-static` speeds up the build for many modules. +* module_autogenargs: a dictionary of additional `autogen.sh` arguments, keyed by module name. +* always_autogen: if set to `True`, then always run the `autogen.sh` script for a module before building. The default is to only run `autogen.sh` if the toplevel makefile for a module is not present. +* branches: a dictionary of branch names, keyed by module name. Useful if you are doing some development on a branch, and want jhbuild to build that branch instead of the default. + +# Checking Your Build Configuration + +You can check whether your jhbuild configuration is okay by running the `jhbuild sanitycheck` command. This is not guaranteed to find all possible problems, but can detect a number of common ones. + +Note that some errors the sanity check reports will only affect a subset of packages, so take the results with a grain of salt. + + +# Using JHBuild + +Once you have set up your JHBuild configuration file, you can start using it to build modules. To build the list of modules listed in the configuration file (plus the dependencies), use the ``build`` command: + + $ jhbuild build + +If an error occurs during the build, a menu will be displayed so you can decide what to do. Options include rerunning the build stage, ignoring the error and starting a shell. + +To build one or more modules not listed in the configuration file (plus their dependencies), use the ``build`` command, but with the module names as arguments: + + $ jhbuild build fontconfig Xft + +If you were part way through a jhbuild run and exited, you can restart the build at a particular module using the `--start-at` option: + + $ jhbuild build --start-at=Xft + +To build one or more modules without their dependencies, use the ``buildone`` command: + + $ jhbuild buildone cairo + +To see what modules would be built by the ``build`` command, use the ``list`` command: + + $ jhbuild list + +If you have the [[GraphViz|http://www.graphviz.org/]] software installed on your computer, you can generate a graph of the modules that jhbuild builds: + + $ jhbuild dot | dot -Tps > dependencies.ps + $ gv dependencies.ps + +You can run a completely non-interactive build, and have the results saved to a set of files, together with an HTML index page with the ``tinderbox`` command: + + $ jhbuild tinderbox -o outputdir + +Note that in this mode that if a package fails to build, no package that depends on it will be built either. The results of the build will be saved in `outputdir`. + + +# Extending Jhbuild + +JHBuild stores information about modules in simple XML files. The [[jhbuild/modulesets/freedesktop.modules|http://cvs.gnome.org/viewcvs/jhbuild/modulesets/freedesktop.modules?view=markup]] file describes the freedesktop.org modules that are currently supported. This list includes: + +* fontconfig +* the X libraries +* the X server +* cairo +* dbus +* startup-notification + +Patches to support additional modules are welcome, and should be filed as bugs at [[bugzilla.gnome.org|http://bugzilla.gnome.org/]] under the `jhbuild` product. + +-- [[JamesHenstridge]] - 03 Nov 2003 diff --git a/Software/kmscon.mdwn b/Software/kmscon.mdwn new file mode 100644 index 00000000..f7f8d06d --- /dev/null +++ b/Software/kmscon.mdwn @@ -0,0 +1,31 @@ + + +# KMS/DRM based System Console + +Overview + +* **`kmscon`** is a system console for linux. It does not depend on any graphics-server on your system (like _X.org_), but instead provides a raw console layer that can be used independently. It can replace the linux kernel console entirely but was designed to work well side-by-side, too. Even though initially targeted at providing internationalization to the system-console, it has grown into a fully modularized console layer including features like multi-head support, internationalized font rendering, XKB-compatible keyboard handling, hardware-accelerated graphics access and more. +Why the name? + +* `kmscon` uses the **Direct-Rendering-Manager** (DRM) of the linux kernel to access graphics devices. The API that performs mode-setting on displays/monitors is called **Kernel-Mode-Setting** (KMS). Hence its name `kmscon`. Today, `kmscon` can also make use of other graphics-APIs. But these were mainly introduced for backwards-compatibility. KMS/DRM is the way to go! +Mailing Lists: + +* [[General Development and Discussion|http://lists.freedesktop.org/mailman/listinfo/kmscon-devel]] +Bug Reports: + +* [[Existing Bug Reports|https://bugs.freedesktop.org/buglist.cgi?query_format=advanced&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&product=kmscon]] [[File a New Bug Report|https://bugs.freedesktop.org/enter_bug.cgi?product=kmscon]] +Download: + +* [[Tarball Releases|http://www.freedesktop.org/software/kmscon/releases/]] +Git: + +* [[developer repository (David Herrmann)|http://cgit.freedesktop.org/~dvdhrm/kmscon/]] [[old github repository|http://github.com/dvdhrm/kmscon]] +Documentation for Users: + +* TODO +Documentation for Developers: + +* TODO +Distribution Packages: + +* [[Arch Linux|https://www.archlinux.org/packages/community/x86_64/kmscon/]] [[(Wiki)|https://wiki.archlinux.org/index.php/KMSCON]]
\ No newline at end of file diff --git a/Software/libdlo.mdwn b/Software/libdlo.mdwn new file mode 100644 index 00000000..2f83c6d5 --- /dev/null +++ b/Software/libdlo.mdwn @@ -0,0 +1,7 @@ + +[[[[!img http://www.displaylink.com]|http://www.displaylink.com]] + + +# DisplayLink LGPL Library - libdlo + +The DisplayLink libdlo wiki has moved to [[http://libdlo.freedesktop.org/|http://libdlo.freedesktop.org/]]. Please bookmark [[http://www.displaylink.org|http://www.displaylink.org]] which will always redirect to the right page. diff --git a/Software/libexttextcat.mdwn b/Software/libexttextcat.mdwn new file mode 100644 index 00000000..05628f5c --- /dev/null +++ b/Software/libexttextcat.mdwn @@ -0,0 +1,53 @@ +# libexttextcat text categorization library + +Libexttextcat is an N-Gram-Based Text Categorization library primarily intended for language guessing. + +You can find it being used in libreoffice. + +[[!toc ]] + + +# Developers + + +## Getting the sources + +libexttextcat sources are stored in [[git|http://git-scm.com/]]. To get them, you can use: + + git clone git://anongit.freedesktop.org/git/libreoffice/libexttextcat/ + +or you can browse the code [[online|http://cgit.freedesktop.org/libreoffice/libexttextcat/]]. + +If you want to use release version you can fetch it from [[libreoffice mirror|http://dev-www.libreoffice.org/src/libexttextcat/]]. + + +## Building it + + +### Dependencies + +Once the source has been checked out, libexttextcat can be built in usual manner: + + cd libexttextcat + ./autogen.sh + ./configure + make + make check # optional + make install + +## Contributing + +Once you have done a change that you are happy with, and that builds with libexttextcat, contribute it back, we'll be happy to integrate it! Do: + + # commit your changes to your local repository + git commit -a + # create the patch + git format-patch origin/master + +# Contact + +You can get in touch with us using multiple ways: + +1. using IRC server **irc.freenode.net** and joining channel **#libreoffice-dev** +1. using mailinglist **[[libreoffice@lists.freedesktop.org|mailto:libreoffice@lists.freedesktop.org]]** +1. filling bugreport in [[Freedesktop bugzilla|http://bugs.freedesktop.org/]] diff --git a/Software/libjpeg.mdwn b/Software/libjpeg.mdwn new file mode 100644 index 00000000..074f84c8 --- /dev/null +++ b/Software/libjpeg.mdwn @@ -0,0 +1,1225 @@ + + +# libjpeg + +USING THE IJG JPEG LIBRARY + +Copyright (C) 1994-1998, Thomas G. Lane. This file is part of the Independent JPEG Group's software. For conditions of distribution and use, see the accompanying README file. + +This file describes how to use the IJG JPEG library within an application program. Read it if you want to write a program that uses the library. + +The file example.c provides heavily commented skeleton code for calling the JPEG library. Also see jpeglib.h (the include file to be used by application programs) for full details about data structures and function parameter lists. The library source code, of course, is the ultimate reference. + +Note that there have been *major* changes from the application interface presented by IJG version 4 and earlier versions. The old design had several inherent limitations, and it had accumulated a lot of cruft as we added features while trying to minimize application-interface changes. We have sacrificed backward compatibility in the version 5 rewrite, but we think the improvements justify this. + + +## TABLE OF CONTENTS + +Overview: * Functions provided by the library * Outline of typical usage Basic library usage: * Data formats * Compression details * Decompression details * Mechanics of usage: include files, linking, etc Advanced features: * Compression parameter selection * Decompression parameter selection * Special color spaces * Error handling * Compressed data handling (source and destination managers) * I/O suspension * Progressive JPEG support * Buffered-image mode * Abbreviated datastreams and multiple images * Special markers * Raw (downsampled) image data * Really raw data: DCT coefficients * Progress monitoring * Memory management * Memory usage * Library compile-time options * Portability considerations * Notes for MS-DOS implementors + +You should read at least the overview and basic usage sections before trying to program with the library. The sections on advanced features can be read if and when you need them. + + +## OVERVIEW + + +### Functions provided by the library + +The IJG JPEG library provides C code to read and write JPEG-compressed image files. The surrounding application program receives or supplies image data a scanline at a time, using a straightforward uncompressed image format. All details of color conversion and other preprocessing/postprocessing can be handled by the library. + +The library includes a substantial amount of code that is not covered by the JPEG standard but is necessary for typical applications of JPEG. These functions preprocess the image before JPEG compression or postprocess it after decompression. They include colorspace conversion, downsampling/upsampling, and color quantization. The application indirectly selects use of this code by specifying the format in which it wishes to supply or receive image data. For example, if colormapped output is requested, then the decompression library automatically invokes color quantization. + +A wide range of quality vs. speed tradeoffs are possible in JPEG processing, and even more so in decompression postprocessing. The decompression library provides multiple implementations that cover most of the useful tradeoffs, ranging from very-high-quality down to fast-preview operation. On the compression side we have generally not provided low-quality choices, since compression is normally less time-critical. It should be understood that the low-quality modes may not meet the JPEG standard's accuracy requirements; nonetheless, they are useful for viewers. + +A word about functions *not* provided by the library. We handle a subset of the ISO JPEG standard; most baseline, extended-sequential, and progressive JPEG processes are supported. (Our subset includes all features now in common use.) Unsupported ISO options include: + + * Hierarchical storage + * Lossless JPEG + * Arithmetic entropy coding (unsupported for legal reasons) + * DNL marker + * Nonintegral subsampling ratios +We support both 8- and 12-bit data precision, but this is a compile-time choice rather than a run-time choice; hence it is difficult to use both precisions in a single application. + +By itself, the library handles only interchange JPEG datastreams --- in particular the widely used JFIF file format. The library can be used by surrounding code to process interchange or abbreviated JPEG datastreams that are embedded in more complex file formats. (For example, this library is used by the free LIBTIFF library to support JPEG compression in TIFF.) + + +## Outline of typical usage + +The rough outline of a JPEG compression operation is: + +<code> + + * Allocate and initialize a JPEG compression object Specify the destination for the compressed data (eg, a file) Set parameters for compression, including image size & colorspace jpeg_start_compress(...); while (scan lines remain to be written) + * jpeg_write_scanlines(...); jpeg_finish_compress(...); Release the JPEG compression object +</code> + +A JPEG compression object holds parameters and working state for the JPEG library. We make creation/destruction of the object separate from starting or finishing compression of an image; the same object can be re-used for a series of image compression operations. This makes it easy to re-use the same parameter settings for a sequence of images. Re-use of a JPEG object also has important implications for processing abbreviated JPEG datastreams, as discussed later. + +The image data to be compressed is supplied to jpeg_write_scanlines() from in-memory buffers. If the application is doing file-to-file compression, reading image data from the source file is the application's responsibility. The library emits compressed data by calling a "data destination manager", which typically will write the data into a file; but the application can provide its own destination manager to do something else. + +Similarly, the rough outline of a JPEG decompression operation is: + +<code> + + * Allocate and initialize a JPEG decompression object Specify the source of the compressed data (eg, a file) Call jpeg_read_header() to obtain image info Set parameters for decompression jpeg_start_decompress(...); while (scan lines remain to be read) + * jpeg_read_scanlines(...); jpeg_finish_decompress(...); Release the JPEG decompression object +</code> + +This is comparable to the compression outline except that reading the datastream header is a separate step. This is helpful because information about the image's size, colorspace, etc is available when the application selects decompression parameters. For example, the application can choose an output scaling ratio that will fit the image into the available screen size. + +The decompression library obtains compressed data by calling a data source manager, which typically will read the data from a file; but other behaviors can be obtained with a custom source manager. Decompressed data is delivered into in-memory buffers passed to jpeg_read_scanlines(). + +It is possible to abort an incomplete compression or decompression operation by calling jpeg_abort(); or, if you do not need to retain the JPEG object, simply release it by calling jpeg_destroy(). + +JPEG compression and decompression objects are two separate struct types. However, they share some common fields, and certain routines such as jpeg_destroy() can work on either type of object. + +The JPEG library has no static variables: all state is in the compression or decompression object. Therefore it is possible to process multiple compression and decompression operations concurrently, using multiple JPEG objects. + +Both compression and decompression can be done in an incremental memory-to- memory fashion, if suitable source/destination managers are used. See the section on "I/O suspension" for more details. + + +## BASIC LIBRARY USAGE + + +### Data formats + +Before diving into procedural details, it is helpful to understand the image data format that the JPEG library expects or returns. + +The standard input image format is a rectangular array of pixels, with each pixel having the same number of "component" or "sample" values (color channels). You must specify how many components there are and the colorspace interpretation of the components. Most applications will use RGB data (three components per pixel) or grayscale data (one component per pixel). PLEASE NOTE THAT RGB DATA IS THREE SAMPLES PER PIXEL, GRAYSCALE ONLY ONE. A remarkable number of people manage to miss this, only to find that their programs don't work with grayscale JPEG files. + +There is no provision for colormapped input. JPEG files are always full-color or full grayscale (or sometimes another colorspace such as CMYK). You can feed in a colormapped image by expanding it to full-color format. However JPEG often doesn't work very well with source data that has been colormapped, because of dithering noise. This is discussed in more detail in the JPEG FAQ and the other references mentioned in the README file. + +Pixels are stored by scanlines, with each scanline running from left to right. The component values for each pixel are adjacent in the row; for example, R,G,B,R,G,B,R,G,B,... for 24-bit RGB color. Each scanline is an array of data type JSAMPLE --- which is typically "unsigned char", unless you've changed jmorecfg.h. (You can also change the RGB pixel layout, say to B,G,R order, by modifying jmorecfg.h. But see the restrictions listed in that file before doing so.) + +A 2-D array of pixels is formed by making a list of pointers to the starts of scanlines; so the scanlines need not be physically adjacent in memory. Even if you process just one scanline at a time, you must make a one-element pointer array to conform to this structure. Pointers to JSAMPLE rows are of type JSAMPROW, and the pointer to the pointer array is of type JSAMPARRAY. + +The library accepts or supplies one or more complete scanlines per call. It is not possible to process part of a row at a time. Scanlines are always processed top-to-bottom. You can process an entire image in one call if you have it all in memory, but usually it's simplest to process one scanline at a time. + +For best results, source data values should have the precision specified by BITS_IN_JSAMPLE (normally 8 bits). For instance, if you choose to compress data that's only 6 bits/channel, you should left-justify each value in a byte before passing it to the compressor. If you need to compress data that has more than 8 bits/channel, compile with BITS_IN_JSAMPLE = 12. (See "Library compile-time options", later.) + +The data format returned by the decompressor is the same in all details, except that colormapped output is supported. (Again, a JPEG file is never colormapped. But you can ask the decompressor to perform on-the-fly color quantization to deliver colormapped output.) If you request colormapped output then the returned data array contains a single JSAMPLE per pixel; its value is an index into a color map. The color map is represented as a 2-D JSAMPARRAY in which each row holds the values of one color component, that is, colormap[i][j] is the value of the i'th color component for pixel value (map index) j. Note that since the colormap indexes are stored in JSAMPLEs, the maximum number of colors is limited by the size of JSAMPLE (ie, at most 256 colors for an 8-bit JPEG library). + + +### Compression details + +Here we revisit the JPEG compression outline given in the overview. + +1. Allocate and initialize a JPEG compression object. + +A JPEG compression object is a "struct jpeg_compress_struct". (It also has a bunch of subsidiary structures which are allocated via malloc(), but the application doesn't control those directly.) This struct can be just a local variable in the calling routine, if a single routine is going to execute the whole JPEG compression sequence. Otherwise it can be static or allocated from malloc(). + +You will also need a structure representing a JPEG error handler. The part of this that the library cares about is a "struct jpeg_error_mgr". If you are providing your own error handler, you'll typically want to embed the jpeg_error_mgr struct in a larger structure; this is discussed later under "Error handling". For now we'll assume you are just using the default error handler. The default error handler will print JPEG error/warning messages on stderr, and it will call exit() if a fatal error occurs. + +You must initialize the error handler structure, store a pointer to it into the JPEG object's "err" field, and then call jpeg_create_compress() to initialize the rest of the JPEG object. + +Typical code for this step, if you are using the default error handler, is + +<code> + + * struct jpeg_compress_struct cinfo; struct jpeg_error_mgr jerr; + * .. cinfo.err = jpeg_std_error(&jerr); jpeg_create_compress(&cinfo); +</code> + +jpeg_create_compress allocates a small amount of memory, so it could fail if you are out of memory. In that case it will exit via the error handler; that's why the error handler must be initialized first. + +2. Specify the destination for the compressed data (eg, a file). + +As previously mentioned, the JPEG library delivers compressed data to a "data destination" module. The library includes one data destination module which knows how to write to a stdio stream. You can use your own destination module if you want to do something else, as discussed later. + +If you use the standard destination module, you must open the target stdio stream beforehand. Typical code for this step looks like: + +<code> + + * FILE * outfile; + * .. if ((outfile = fopen(filename, "wb")) == NULL) { + * fprintf(stderr, "can't open %s\n", filename); exit(1); } +jpeg_stdio_dest(&cinfo, outfile); + +</code> + +where the last line invokes the standard destination module. + +WARNING: it is critical that the binary compressed data be delivered to the output file unchanged. On non-Unix systems the stdio library may perform newline translation or otherwise corrupt binary data. To suppress this behavior, you may need to use a "b" option to fopen (as shown above), or use setmode() or another routine to put the stdio stream in binary mode. See cjpeg.c and djpeg.c for code that has been found to work on many systems. + +You can select the data destination after setting other parameters (step 3), if that's more convenient. You may not change the destination between calling jpeg_start_compress() and jpeg_finish_compress(). + +3. Set parameters for compression, including image size & colorspace. + +You must supply information about the source image by setting the following fields in the JPEG object (cinfo structure): + +<code> + + * image_width Width of image, in pixels image_height Height of image, in pixels input_components Number of color channels (samples per pixel) in_color_space Color space of source image +</code> + +The image dimensions are, hopefully, obvious. JPEG supports image dimensions of 1 to 64K pixels in either direction. The input color space is typically RGB or grayscale, and input_components is 3 or 1 accordingly. (See "Special color spaces", later, for more info.) The in_color_space field must be assigned one of the J_COLOR_SPACE enum constants, typically JCS_RGB or JCS_GRAYSCALE. + +JPEG has a large number of compression parameters that determine how the image is encoded. Most applications don't need or want to know about all these parameters. You can set all the parameters to reasonable defaults by calling jpeg_set_defaults(); then, if there are particular values you want to change, you can do so after that. The "Compression parameter selection" section tells about all the parameters. + +You must set in_color_space correctly before calling jpeg_set_defaults(), because the defaults depend on the source image colorspace. However the other three source image parameters need not be valid until you call jpeg_start_compress(). There's no harm in calling jpeg_set_defaults() more than once, if that happens to be convenient. + +Typical code for a 24-bit RGB source image is + +<code> + + * cinfo.image_width = Width; <span style="display:none">image width and height, in pixels</span> cinfo.image_height = Height; cinfo.input_components = 3; <span style="display:none"># of color components per pixel</span> cinfo.in_color_space = JCS_RGB; <span style="display:none">colorspace of input image</span> jpeg_set_defaults(&cinfo); <span style="display:none">Make optional parameter settings here</span> +</code> + +4. jpeg_start_compress(...); + +After you have established the data destination and set all the necessary source image info and other parameters, call jpeg_start_compress() to begin a compression cycle. This will initialize internal state, allocate working storage, and emit the first few bytes of the JPEG datastream header. + +Typical code: + +<code> + + * jpeg_start_compress(&cinfo, TRUE); +</code> + +The "TRUE" parameter ensures that a complete JPEG interchange datastream will be written. This is appropriate in most cases. If you think you might want to use an abbreviated datastream, read the section on abbreviated datastreams, below. + +Once you have called jpeg_start_compress(), you may not alter any JPEG parameters or other fields of the JPEG object until you have completed the compression cycle. + +5. while (scan lines remain to be written) + + * jpeg_write_scanlines(...); +Now write all the required image data by calling jpeg_write_scanlines() one or more times. You can pass one or more scanlines in each call, up to the total image height. In most applications it is convenient to pass just one or a few scanlines at a time. The expected format for the passed data is discussed under "Data formats", above. + +Image data should be written in top-to-bottom scanline order. The JPEG spec contains some weasel wording about how top and bottom are application-defined terms (a curious interpretation of the English language...) but if you want your files to be compatible with everyone else's, you WILL use top-to-bottom order. If the source data must be read in bottom-to-top order, you can use the JPEG library's virtual array mechanism to invert the data efficiently. Examples of this can be found in the sample application cjpeg. + +The library maintains a count of the number of scanlines written so far in the next_scanline field of the JPEG object. Usually you can just use this variable as the loop counter, so that the loop test looks like "while (cinfo.next_scanline < cinfo.image_height)". + +Code for this step depends heavily on the way that you store the source data. example.c shows the following code for the case of a full-size 2-D source array containing 3-byte RGB pixels: + +<code> + + * JSAMPROW row_pointer[1]; <span style="display:none">pointer to a single row</span> int row_stride; <span style="display:none">physical row width in buffer</span> row_stride = image_width * 3; <span style="display:none">JSAMPLEs per row in image_buffer</span> while (cinfo.next_scanline < cinfo.image_height) { + * row_pointer[0] = & image_buffer[cinfo.next_scanline * row_stride]; jpeg_write_scanlines(&cinfo, row_pointer, 1); } +</code> + +jpeg_write_scanlines() returns the number of scanlines actually written. This will normally be equal to the number passed in, so you can usually ignore the return value. It is different in just two cases: + + * If you try to write more scanlines than the declared image height, + * the additional scanlines are ignored. + * If you use a suspending data destination manager, output buffer overrun + * will cause the compressor to return before accepting all the passed lines. This feature is discussed under "I/O suspension", below. The normal stdio destination manager will NOT cause this to happen. +In any case, the return value is the same as the change in the value of next_scanline. + +6. jpeg_finish_compress(...); + +After all the image data has been written, call jpeg_finish_compress() to complete the compression cycle. This step is ESSENTIAL to ensure that the last bufferload of data is written to the data destination. jpeg_finish_compress() also releases working memory associated with the JPEG object. + +Typical code: + +<code> + + * jpeg_finish_compress(&cinfo); +</code> + +If using the stdio destination manager, don't forget to close the output stdio stream (if necessary) afterwards. + +If you have requested a multi-pass operating mode, such as Huffman code optimization, jpeg_finish_compress() will perform the additional passes using data buffered by the first pass. In this case jpeg_finish_compress() may take quite a while to complete. With the default compression parameters, this will not happen. + +It is an error to call jpeg_finish_compress() before writing the necessary total number of scanlines. If you wish to abort compression, call jpeg_abort() as discussed below. + +After completing a compression cycle, you may dispose of the JPEG object as discussed next, or you may use it to compress another image. In that case return to step 2, 3, or 4 as appropriate. If you do not change the destination manager, the new datastream will be written to the same target. If you do not change any JPEG parameters, the new datastream will be written with the same parameters as before. Note that you can change the input image dimensions freely between cycles, but if you change the input colorspace, you should call jpeg_set_defaults() to adjust for the new colorspace; and then you'll need to repeat all of step 3. + +7. Release the JPEG compression object. + +When you are done with a JPEG compression object, destroy it by calling jpeg_destroy_compress(). This will free all subsidiary memory (regardless of the previous state of the object). Or you can call jpeg_destroy(), which works for either compression or decompression objects --- this may be more convenient if you are sharing code between compression and decompression cases. (Actually, these routines are equivalent except for the declared type of the passed pointer. To avoid gripes from ANSI C compilers, jpeg_destroy() should be passed a j_common_ptr.) + +If you allocated the jpeg_compress_struct structure from malloc(), freeing it is your responsibility --- jpeg_destroy() won't. Ditto for the error handler structure. + +Typical code: <code> + + * jpeg_destroy_compress(&cinfo); +</code> + +8. Aborting. + +If you decide to abort a compression cycle before finishing, you can clean up in either of two ways: + +* If you don't need the JPEG object any more, just call + + * jpeg_destroy_compress() or jpeg_destroy() to release memory. This is legitimate at any point after calling jpeg_create_compress() --- in fact, it's safe even if jpeg_create_compress() fails. +* If you want to re-use the JPEG object, call jpeg_abort_compress(), or call + + * jpeg_abort() which works on both compression and decompression objects. This will return the object to an idle state, releasing any working memory. jpeg_abort() is allowed at any time after successful object creation. +Note that cleaning up the data destination, if required, is your responsibility; neither of these routines will call term_destination(). (See "Compressed data handling", below, for more about that.) + +jpeg_destroy() and jpeg_abort() are the only safe calls to make on a JPEG object that has reported an error by calling error_exit (see "Error handling" for more info). The internal state of such an object is likely to be out of whack. Either of these two routines will return the object to a known state. + + +### Decompression details + +Here we revisit the JPEG decompression outline given in the overview. + +1. Allocate and initialize a JPEG decompression object. + +This is just like initialization for compression, as discussed above, except that the object is a "struct jpeg_decompress_struct" and you call jpeg_create_decompress(). Error handling is exactly the same. + +Typical code: + +<code> + + * struct jpeg_decompress_struct cinfo; struct jpeg_error_mgr jerr; + * .. cinfo.err = jpeg_std_error(&jerr); jpeg_create_decompress(&cinfo); +</code> + +(Both here and in the IJG code, we usually use variable name "cinfo" for both compression and decompression objects.) + +2. Specify the source of the compressed data (eg, a file). + +As previously mentioned, the JPEG library reads compressed data from a "data source" module. The library includes one data source module which knows how to read from a stdio stream. You can use your own source module if you want to do something else, as discussed later. + +If you use the standard source module, you must open the source stdio stream beforehand. Typical code for this step looks like: + +<code> + + * FILE * infile; + * .. if ((infile = fopen(filename, "rb")) == NULL) { + * fprintf(stderr, "can't open %s\n", filename); exit(1); } +jpeg_stdio_src(&cinfo, infile); + +</code> + +where the last line invokes the standard source module. + +WARNING: it is critical that the binary compressed data be read unchanged. On non-Unix systems the stdio library may perform newline translation or otherwise corrupt binary data. To suppress this behavior, you may need to use a "b" option to fopen (as shown above), or use setmode() or another routine to put the stdio stream in binary mode. See cjpeg.c and djpeg.c for code that has been found to work on many systems. + +You may not change the data source between calling jpeg_read_header() and jpeg_finish_decompress(). If you wish to read a series of JPEG images from a single source file, you should repeat the jpeg_read_header() to jpeg_finish_decompress() sequence without reinitializing either the JPEG object or the data source module; this prevents buffered input data from being discarded. + +3. Call jpeg_read_header() to obtain image info. + +Typical code for this step is just + +<code> + + * jpeg_read_header(&cinfo, TRUE); +</code> + +This will read the source datastream header markers, up to the beginning of the compressed data proper. On return, the image dimensions and other info have been stored in the JPEG object. The application may wish to consult this information before selecting decompression parameters. + +More complex code is necessary if + + * A suspending data source is used --- in that case jpeg_read_header() + * may return before it has read all the header data. See "I/O suspension", below. The normal stdio source manager will NOT cause this to happen. + * Abbreviated JPEG files are to be processed --- see the section on + * abbreviated datastreams. Standard applications that deal only in interchange JPEG files need not be concerned with this case either. +It is permissible to stop at this point if you just wanted to find out the image dimensions and other header info for a JPEG file. In that case, call jpeg_destroy() when you are done with the JPEG object, or call jpeg_abort() to return it to an idle state before selecting a new data source and reading another header. + +4. Set parameters for decompression. + +jpeg_read_header() sets appropriate default decompression parameters based on the properties of the image (in particular, its colorspace). However, you may well want to alter these defaults before beginning the decompression. For example, the default is to produce full color output from a color file. If you want colormapped output you must ask for it. Other options allow the returned image to be scaled and allow various speed/quality tradeoffs to be selected. "Decompression parameter selection", below, gives details. + +If the defaults are appropriate, nothing need be done at this step. + +Note that all default values are set by each call to jpeg_read_header(). If you reuse a decompression object, you cannot expect your parameter settings to be preserved across cycles, as you can for compression. You must set desired parameter values each time. + +5. jpeg_start_decompress(...); + +Once the parameter values are satisfactory, call jpeg_start_decompress() to begin decompression. This will initialize internal state, allocate working memory, and prepare for returning data. + +Typical code is just + +<code> + + * jpeg_start_decompress(&cinfo); +</code> + +If you have requested a multi-pass operating mode, such as 2-pass color quantization, jpeg_start_decompress() will do everything needed before data output can begin. In this case jpeg_start_decompress() may take quite a while to complete. With a single-scan (non progressive) JPEG file and default decompression parameters, this will not happen; jpeg_start_decompress() will return quickly. + +After this call, the final output image dimensions, including any requested scaling, are available in the JPEG object; so is the selected colormap, if colormapped output has been requested. Useful fields include + +<code> + + * output_width image width and height, as scaled output_height out_color_components # of color components in out_color_space output_components # of color components returned per pixel colormap the selected colormap, if any actual_number_of_colors number of entries in colormap +</code> + +output_components is 1 (a colormap index) when quantizing colors; otherwise it equals out_color_components. It is the number of JSAMPLE values that will be emitted per pixel in the output arrays. + +Typically you will need to allocate data buffers to hold the incoming image. You will need output_width * output_components JSAMPLEs per scanline in your output buffer, and a total of output_height scanlines will be returned. + +Note: if you are using the JPEG library's internal memory manager to allocate data buffers (as djpeg does), then the manager's protocol requires that you request large buffers *before* calling jpeg_start_decompress(). This is a little tricky since the output_XXX fields are not normally valid then. You can make them valid by calling jpeg_calc_output_dimensions() after setting the relevant parameters (scaling, output color space, and quantization flag). + +6. while (scan lines remain to be read) + + * jpeg_read_scanlines(...); +Now you can read the decompressed image data by calling jpeg_read_scanlines() one or more times. At each call, you pass in the maximum number of scanlines to be read (ie, the height of your working buffer); jpeg_read_scanlines() will return up to that many lines. The return value is the number of lines actually read. The format of the returned data is discussed under "Data formats", above. Don't forget that grayscale and color JPEGs will return different data formats! + +Image data is returned in top-to-bottom scanline order. If you must write out the image in bottom-to-top order, you can use the JPEG library's virtual array mechanism to invert the data efficiently. Examples of this can be found in the sample application djpeg. + +The library maintains a count of the number of scanlines returned so far in the output_scanline field of the JPEG object. Usually you can just use this variable as the loop counter, so that the loop test looks like "while (cinfo.output_scanline < cinfo.output_height)". (Note that the test should NOT be against image_height, unless you never use scaling. The image_height field is the height of the original unscaled image.) The return value always equals the change in the value of output_scanline. + +If you don't use a suspending data source, it is safe to assume that jpeg_read_scanlines() reads at least one scanline per call, until the bottom of the image has been reached. + +If you use a buffer larger than one scanline, it is NOT safe to assume that jpeg_read_scanlines() fills it. (The current implementation returns only a few scanlines per call, no matter how large a buffer you pass.) So you must always provide a loop that calls jpeg_read_scanlines() repeatedly until the whole image has been read. + +7. jpeg_finish_decompress(...); + +After all the image data has been read, call jpeg_finish_decompress() to complete the decompression cycle. This causes working memory associated with the JPEG object to be released. + +Typical code: <code> + + * jpeg_finish_decompress(&cinfo); +</code> + +If using the stdio source manager, don't forget to close the source stdio stream if necessary. + +It is an error to call jpeg_finish_decompress() before reading the correct total number of scanlines. If you wish to abort decompression, call jpeg_abort() as discussed below. + +After completing a decompression cycle, you may dispose of the JPEG object as discussed next, or you may use it to decompress another image. In that case return to step 2 or 3 as appropriate. If you do not change the source manager, the next image will be read from the same source. + +8. Release the JPEG decompression object. + +When you are done with a JPEG decompression object, destroy it by calling jpeg_destroy_decompress() or jpeg_destroy(). The previous discussion of destroying compression objects applies here too. + +Typical code: + +<code> + + * jpeg_destroy_decompress(&cinfo); +</code> + +9. Aborting. + +You can abort a decompression cycle by calling jpeg_destroy_decompress() or jpeg_destroy() if you don't need the JPEG object any more, or jpeg_abort_decompress() or jpeg_abort() if you want to reuse the object. The previous discussion of aborting compression cycles applies here too. + + +### Mechanics of usage: include files, linking, etc + +Applications using the JPEG library should include the header file jpeglib.h to obtain declarations of data types and routines. Before including jpeglib.h, include system headers that define at least the typedefs FILE and size_t. On ANSI-conforming systems, including <stdio.h> is sufficient; on older Unix systems, you may need <sys/types.h> to define size_t. + +If the application needs to refer to individual JPEG library error codes, also include jerror.h to define those symbols. + +jpeglib.h indirectly includes the files jconfig.h and jmorecfg.h. If you are installing the JPEG header files in a system directory, you will want to install all four files: jpeglib.h, jerror.h, jconfig.h, jmorecfg.h. + +The most convenient way to include the JPEG code into your executable program is to prepare a library file ("libjpeg.a", or a corresponding name on non-Unix machines) and reference it at your link step. If you use only half of the library (only compression or only decompression), only that much code will be included from the library, unless your linker is hopelessly brain-damaged. The supplied makefiles build libjpeg.a automatically (see install.doc). + +While you can build the JPEG library as a shared library if the whim strikes you, we don't really recommend it. The trouble with shared libraries is that at some point you'll probably try to substitute a new version of the library without recompiling the calling applications. That generally doesn't work because the parameter struct declarations usually change with each new version. In other words, the library's API is *not* guaranteed binary compatible across versions; we only try to ensure source-code compatibility. (In hindsight, it might have been smarter to hide the parameter structs from applications and introduce a ton of access functions instead. Too late now, however.) + +On some systems your application may need to set up a signal handler to ensure that temporary files are deleted if the program is interrupted. This is most critical if you are on MS-DOS and use the jmemdos.c memory manager back end; it will try to grab extended memory for temp files, and that space will NOT be freed automatically. See cjpeg.c or djpeg.c for an example signal handler. + +It may be worth pointing out that the core JPEG library does not actually require the stdio library: only the default source/destination managers and error handler need it. You can use the library in a stdio-less environment if you replace those modules and use jmemnobs.c (or another memory manager of your own devising). More info about the minimum system library requirements may be found in jinclude.h. + + +## ADVANCED FEATURES + + +### Compression parameter selection + +This section describes all the optional parameters you can set for JPEG compression, as well as the "helper" routines provided to assist in this task. Proper setting of some parameters requires detailed understanding of the JPEG standard; if you don't know what a parameter is for, it's best not to mess with it! See REFERENCES in the README file for pointers to more info about JPEG. + +It's a good idea to call jpeg_set_defaults() first, even if you plan to set all the parameters; that way your code is more likely to work with future JPEG libraries that have additional parameters. For the same reason, we recommend you use a helper routine where one is provided, in preference to twiddling cinfo fields directly. + +The helper routines are: + +jpeg_set_defaults (j_compress_ptr cinfo) + + * This routine sets all JPEG parameters to reasonable defaults, using only the input image's color space (field in_color_space, which must already be set in cinfo). Many applications will only need to use this routine and perhaps jpeg_set_quality(). +jpeg_set_colorspace (j_compress_ptr cinfo, J_COLOR_SPACE colorspace) + + * Sets the JPEG file's colorspace (field jpeg_color_space) as specified, and sets other color-space-dependent parameters appropriately. See "Special color spaces", below, before using this. A large number of parameters, including all per-component parameters, are set by this routine; if you want to twiddle individual parameters you should call jpeg_set_colorspace() before rather than after. +jpeg_default_colorspace (j_compress_ptr cinfo) + + * Selects an appropriate JPEG colorspace based on cinfo->in_color_space, and calls jpeg_set_colorspace(). This is actually a subroutine of jpeg_set_defaults(). It's broken out in case you want to change just the colorspace-dependent JPEG parameters. +jpeg_set_quality (j_compress_ptr cinfo, int quality, boolean force_baseline) + + * Constructs JPEG quantization tables appropriate for the indicated quality setting. The quality value is expressed on the 0..100 scale recommended by IJG (cjpeg's "-quality" switch uses this routine). Note that the exact mapping from quality values to tables may change in future IJG releases as more is learned about DCT quantization. If the force_baseline parameter is TRUE, then the quantization table entries are constrained to the range 1..255 for full JPEG baseline compatibility. In the current implementation, this only makes a difference for quality settings below 25, and it effectively prevents very small/low quality files from being generated. The IJG decoder is capable of reading the non-baseline files generated at low quality settings when force_baseline is FALSE, but other decoders may not be. +jpeg_set_linear_quality (j_compress_ptr cinfo, int scale_factor, + + * boolean force_baseline) + * Same as jpeg_set_quality() except that the generated tables are the sample tables given in the JPEC spec section K.1, multiplied by the specified scale factor (which is expressed as a percentage; thus scale_factor = 100 reproduces the spec's tables). Note that larger scale factors give lower quality. This entry point is useful for conforming to the Adobe [[PostScript|PostScript]] DCT conventions, but we do not recommend linear scaling as a user-visible quality scale otherwise. force_baseline again constrains the computed table entries to 1..255. +int jpeg_quality_scaling (int quality) + + * Converts a value on the IJG-recommended quality scale to a linear scaling percentage. Note that this routine may change or go away in future releases --- IJG may choose to adopt a scaling method that can't be expressed as a simple scalar multiplier, in which case the premise of this routine collapses. Caveat user. +jpeg_add_quant_table (j_compress_ptr cinfo, int which_tbl, + + * const unsigned int *basic_table, int scale_factor, boolean force_baseline) + * Allows an arbitrary quantization table to be created. which_tbl indicates which table slot to fill. basic_table points to an array of 64 unsigned ints given in normal array order. These values are multiplied by scale_factor/100 and then clamped to the range 1..65535 (or to 1..255 if force_baseline is TRUE). CAUTION: prior to library version 6a, jpeg_add_quant_table expected the basic table to be given in JPEG zigzag order. If you need to write code that works with either older or newer versions of this routine, you must check the library version number. Something like "#if JPEG_LIB_VERSION >= 61" is the right test. +jpeg_simple_progression (j_compress_ptr cinfo) + + * Generates a default scan script for writing a progressive-JPEG file. This is the recommended method of creating a progressive file, unless you want to make a custom scan sequence. You must ensure that the JPEG color space is set correctly before calling this routine. +Compression parameters (cinfo fields) include: + +J_DCT_METHOD dct_method + + * Selects the algorithm used for the DCT step. Choices are: + * JDCT_ISLOW: slow but accurate integer algorithm JDCT_IFAST: faster, less accurate integer method JDCT_FLOAT: floating-point method JDCT_DEFAULT: default method (normally JDCT_ISLOW) JDCT_FASTEST: fastest method (normally JDCT_IFAST) The FLOAT method is very slightly more accurate than the ISLOW method, but may give different results on different machines due to varying roundoff behavior. The integer methods should give the same results on all machines. On machines with sufficiently fast FP hardware, the floating-point method may also be the fastest. The IFAST method is considerably less accurate than the other two; its use is not recommended if high quality is a concern. JDCT_DEFAULT and JDCT_FASTEST are macros configurable by each installation. +J_COLOR_SPACE jpeg_color_space int num_components + + * The JPEG color space and corresponding number of components; see "Special color spaces", below, for more info. We recommend using jpeg_set_color_space() if you want to change these. +boolean optimize_coding + + * TRUE causes the compressor to compute optimal Huffman coding tables for the image. This requires an extra pass over the data and therefore costs a good deal of space and time. The default is FALSE, which tells the compressor to use the supplied or default Huffman tables. In most cases optimal tables save only a few percent of file size compared to the default tables. Note that when this is TRUE, you need not supply Huffman tables at all, and any you do supply will be overwritten. +unsigned int restart_interval int restart_in_rows + + * To emit restart markers in the JPEG file, set one of these nonzero. Set restart_interval to specify the exact interval in MCU blocks. Set restart_in_rows to specify the interval in MCU rows. (If restart_in_rows is not 0, then restart_interval is set after the image width in MCUs is computed.) Defaults are zero (no restarts). One restart marker per MCU row is often a good choice. NOTE: the overhead of restart markers is higher in grayscale JPEG files than in color files, and MUCH higher in progressive JPEGs. If you use restarts, you may want to use larger intervals in those cases. +const jpeg_scan_info * scan_info int num_scans + + * By default, scan_info is NULL; this causes the compressor to write a single-scan sequential JPEG file. If not NULL, scan_info points to an array of scan definition records of length num_scans. The compressor will then write a JPEG file having one scan for each scan definition record. This is used to generate noninterleaved or progressive JPEG files. The library checks that the scan array defines a valid JPEG scan sequence. (jpeg_simple_progression creates a suitable scan definition array for progressive JPEG.) This is discussed further under "Progressive JPEG support". +int smoothing_factor + + * If non-zero, the input image is smoothed; the value should be 1 for minimal smoothing to 100 for maximum smoothing. Consult jcsample.c for details of the smoothing algorithm. The default is zero. +boolean write_JFIF_header + + * If TRUE, a JFIF APP0 marker is emitted. jpeg_set_defaults() and jpeg_set_colorspace() set this TRUE if a JFIF-legal JPEG color space (ie, YCbCr or grayscale) is selected, otherwise FALSE. +UINT8 JFIF_major_version UINT8 JFIF_minor_version + + * The version number to be written into the JFIF marker. jpeg_set_defaults() initializes the version to 1.01 (major=minor=1). You should set it to 1.02 (major=1, minor=2) if you plan to write any JFIF 1.02 extension markers. +UINT8 density_unit UINT16 X_density UINT16 Y_density + + * The resolution information to be written into the JFIF marker; not used otherwise. density_unit may be 0 for unknown, 1 for dots/inch, or 2 for dots/cm. The default values are 0,1,1 indicating square pixels of unknown size. +boolean write_Adobe_marker + + * If TRUE, an Adobe APP14 marker is emitted. jpeg_set_defaults() and jpeg_set_colorspace() set this TRUE if JPEG color space RGB, CMYK, or YCCK is selected, otherwise FALSE. It is generally a bad idea to set both write_JFIF_header and write_Adobe_marker. In fact, you probably shouldn't change the default settings at all --- the default behavior ensures that the JPEG file's color space can be recognized by the decoder. +JQUANT_TBL * quant_tbl_ptrs[NUM_QUANT_TBLS] + + * Pointers to coefficient quantization tables, one per table slot, or NULL if no table is defined for a slot. Usually these should be set via one of the above helper routines; jpeg_add_quant_table() is general enough to define any quantization table. The other routines will set up table slot 0 for luminance quality and table slot 1 for chrominance. +JHUFF_TBL * dc_huff_tbl_ptrs[NUM_HUFF_TBLS] JHUFF_TBL * ac_huff_tbl_ptrs[NUM_HUFF_TBLS] + + * Pointers to Huffman coding tables, one per table slot, or NULL if no table is defined for a slot. Slots 0 and 1 are filled with the JPEG sample tables by jpeg_set_defaults(). If you need to allocate more table structures, jpeg_alloc_huff_table() may be used. Note that optimal Huffman tables can be computed for an image by setting optimize_coding, as discussed above; there's seldom any need to mess with providing your own Huffman tables. +There are some additional cinfo fields which are not documented here because you currently can't change them; for example, you can't set arith_code TRUE because arithmetic coding is unsupported. + +Per-component parameters are stored in the struct cinfo.comp_info[i] for component number i. Note that components here refer to components of the JPEG color space, *not* the source image color space. A suitably large comp_info[] array is allocated by jpeg_set_defaults(); if you choose not to use that routine, it's up to you to allocate the array. + +int component_id + + * The one-byte identifier code to be recorded in the JPEG file for this component. For the standard color spaces, we recommend you leave the default values alone. +int h_samp_factor int v_samp_factor + + * Horizontal and vertical sampling factors for the component; must be 1..4 according to the JPEG standard. Note that larger sampling factors indicate a higher-resolution component; many people find this behavior quite unintuitive. The default values are 2,2 for luminance components and 1,1 for chrominance components, except for grayscale where 1,1 is used. +int quant_tbl_no + + * Quantization table number for component. The default value is 0 for luminance components and 1 for chrominance components. +int dc_tbl_no int ac_tbl_no + + * DC and AC entropy coding table numbers. The default values are 0 for luminance components and 1 for chrominance components. +int component_index + + * Must equal the component's index in comp_info[]. (Beginning in release v6, the compressor library will fill this in automatically; you don't have to.) + +### Decompression parameter selection + +Decompression parameter selection is somewhat simpler than compression parameter selection, since all of the JPEG internal parameters are recorded in the source file and need not be supplied by the application. (Unless you are working with abbreviated files, in which case see "Abbreviated datastreams", below.) Decompression parameters control the postprocessing done on the image to deliver it in a format suitable for the application's use. Many of the parameters control speed/quality tradeoffs, in which faster decompression may be obtained at the price of a poorer-quality image. The defaults select the highest quality (slowest) processing. + +The following fields in the JPEG object are set by jpeg_read_header() and may be useful to the application in choosing decompression parameters: + +JDIMENSION image_width Width and height of image JDIMENSION image_height int num_components Number of color components J_COLOR_SPACE jpeg_color_space Colorspace of image boolean saw_JFIF_marker TRUE if a JFIF APP0 marker was seen + + * UINT8 JFIF_major_version Version information from JFIF marker UINT8 JFIF_minor_version UINT8 density_unit Resolution data from JFIF marker UINT16 X_density UINT16 Y_density +boolean saw_Adobe_marker TRUE if an Adobe APP14 marker was seen + + * UINT8 Adobe_transform Color transform code from Adobe marker +The JPEG color space, unfortunately, is something of a guess since the JPEG standard proper does not provide a way to record it. In practice most files adhere to the JFIF or Adobe conventions, and the decoder will recognize these correctly. See "Special color spaces", below, for more info. + +The decompression parameters that determine the basic properties of the returned image are: + +J_COLOR_SPACE out_color_space + + * Output color space. jpeg_read_header() sets an appropriate default based on jpeg_color_space; typically it will be RGB or grayscale. The application can change this field to request output in a different colorspace. For example, set it to JCS_GRAYSCALE to get grayscale output from a color file. (This is useful for previewing: grayscale output is faster than full color since the color components need not be processed.) Note that not all possible color space transforms are currently implemented; you may need to extend jdcolor.c if you want an unusual conversion. +unsigned int scale_num, scale_denom + + * Scale the image by the fraction scale_num/scale_denom. Default is 1/1, or no scaling. Currently, the only supported scaling ratios are 1/1, 1/2, 1/4, and 1/8. (The library design allows for arbitrary scaling ratios but this is not likely to be implemented any time soon.) Smaller scaling ratios permit significantly faster decoding since fewer pixels need be processed and a simpler IDCT method can be used. +boolean quantize_colors + + * If set TRUE, colormapped output will be delivered. Default is FALSE, meaning that full-color output will be delivered. +The next three parameters are relevant only if quantize_colors is TRUE. + +int desired_number_of_colors + + * Maximum number of colors to use in generating a library-supplied color map (the actual number of colors is returned in a different field). Default 256. Ignored when the application supplies its own color map. +boolean two_pass_quantize + + * If TRUE, an extra pass over the image is made to select a custom color map for the image. This usually looks a lot better than the one-size- fits-all colormap that is used otherwise. Default is TRUE. Ignored when the application supplies its own color map. +J_DITHER_MODE dither_mode + + * Selects color dithering method. Supported values are: + * JDITHER_NONE no dithering: fast, very low quality JDITHER_ORDERED ordered dither: moderate speed and quality JDITHER_FS Floyd-Steinberg dither: slow, high quality Default is JDITHER_FS. (At present, ordered dither is implemented only in the single-pass, standard-colormap case. If you ask for ordered dither when two_pass_quantize is TRUE or when you supply an external color map, you'll get F-S dithering.) +When quantize_colors is TRUE, the target color map is described by the next two fields. colormap is set to NULL by jpeg_read_header(). The application can supply a color map by setting colormap non-NULL and setting actual_number_of_colors to the map size. Otherwise, jpeg_start_decompress() selects a suitable color map and sets these two fields itself. [Implementation restriction: at present, an externally supplied colormap is only accepted for 3-component output color spaces.] + +JSAMPARRAY colormap + + * The color map, represented as a 2-D pixel array of out_color_components rows and actual_number_of_colors columns. Ignored if not quantizing. CAUTION: if the JPEG library creates its own colormap, the storage pointed to by this field is released by jpeg_finish_decompress(). Copy the colormap somewhere else first, if you want to save it. +int actual_number_of_colors + + * The number of colors in the color map. +Additional decompression parameters that the application may set include: + +J_DCT_METHOD dct_method + + * Selects the algorithm used for the DCT step. Choices are the same as described above for compression. +boolean do_fancy_upsampling + + * If TRUE, do careful upsampling of chroma components. If FALSE, a faster but sloppier method is used. Default is TRUE. The visual impact of the sloppier method is often very small. +boolean do_block_smoothing + + * If TRUE, interblock smoothing is applied in early stages of decoding progressive JPEG files; if FALSE, not. Default is TRUE. Early progression stages look "fuzzy" with smoothing, "blocky" without. In any case, block smoothing ceases to be applied after the first few AC coefficients are known to full accuracy, so it is relevant only when using buffered-image mode for progressive images. +boolean enable_1pass_quant boolean enable_external_quant boolean enable_2pass_quant + + * These are significant only in buffered-image mode, which is described in its own section below. +The output image dimensions are given by the following fields. These are computed from the source image dimensions and the decompression parameters by jpeg_start_decompress(). You can also call jpeg_calc_output_dimensions() to obtain the values that will result from the current parameter settings. This can be useful if you are trying to pick a scaling ratio that will get close to a desired target size. It's also important if you are using the JPEG library's memory manager to allocate output buffer space, because you are supposed to request such buffers *before* jpeg_start_decompress(). + +JDIMENSION output_width Actual dimensions of output image. JDIMENSION output_height int out_color_components Number of color components in out_color_space. int output_components Number of color components returned. int rec_outbuf_height Recommended height of scanline buffer. + +When quantizing colors, output_components is 1, indicating a single color map index per pixel. Otherwise it equals out_color_components. The output arrays are required to be output_width * output_components JSAMPLEs wide. + +rec_outbuf_height is the recommended minimum height (in scanlines) of the buffer passed to jpeg_read_scanlines(). If the buffer is smaller, the library will still work, but time will be wasted due to unnecessary data copying. In high-quality modes, rec_outbuf_height is always 1, but some faster, lower-quality modes set it to larger values (typically 2 to 4). If you are going to ask for a high-speed processing mode, you may as well go to the trouble of honoring rec_outbuf_height so as to avoid data copying. (An output buffer larger than rec_outbuf_height lines is OK, but won't provide any material speed improvement over that height.) + + +### Special color spaces + +The JPEG standard itself is "color blind" and doesn't specify any particular color space. It is customary to convert color data to a luminance/chrominance color space before compressing, since this permits greater compression. The existing de-facto JPEG file format standards specify YCbCr or grayscale data (JFIF), or grayscale, RGB, YCbCr, CMYK, or YCCK (Adobe). For special applications such as multispectral images, other color spaces can be used, but it must be understood that such files will be unportable. + +The JPEG library can handle the most common colorspace conversions (namely RGB <=> YCbCr and CMYK <=> YCCK). It can also deal with data of an unknown color space, passing it through without conversion. If you deal extensively with an unusual color space, you can easily extend the library to understand additional color spaces and perform appropriate conversions. + +For compression, the source data's color space is specified by field in_color_space. This is transformed to the JPEG file's color space given by jpeg_color_space. jpeg_set_defaults() chooses a reasonable JPEG color space depending on in_color_space, but you can override this by calling jpeg_set_colorspace(). Of course you must select a supported transformation. jccolor.c currently supports the following transformations: + + * RGB => YCbCr RGB => GRAYSCALE YCbCr => GRAYSCALE CMYK => YCCK +plus the null transforms: GRAYSCALE => GRAYSCALE, RGB => RGB, YCbCr => YCbCr, CMYK => CMYK, YCCK => YCCK, and UNKNOWN => UNKNOWN. + +The de-facto file format standards (JFIF and Adobe) specify APPn markers that indicate the color space of the JPEG file. It is important to ensure that these are written correctly, or omitted if the JPEG file's color space is not one of the ones supported by the de-facto standards. jpeg_set_colorspace() will set the compression parameters to include or omit the APPn markers properly, so long as it is told the truth about the JPEG color space. For example, if you are writing some random 3-component color space without conversion, don't try to fake out the library by setting in_color_space and jpeg_color_space to JCS_YCbCr; use JCS_UNKNOWN. You may want to write an APPn marker of your own devising to identify the colorspace --- see "Special markers", below. + +When told that the color space is UNKNOWN, the library will default to using luminance-quality compression parameters for all color components. You may well want to change these parameters. See the source code for jpeg_set_colorspace(), in jcparam.c, for details. + +For decompression, the JPEG file's color space is given in jpeg_color_space, and this is transformed to the output color space out_color_space. jpeg_read_header's setting of jpeg_color_space can be relied on if the file conforms to JFIF or Adobe conventions, but otherwise it is no better than a guess. If you know the JPEG file's color space for certain, you can override jpeg_read_header's guess by setting jpeg_color_space. jpeg_read_header also selects a default output color space based on (its guess of) jpeg_color_space; set out_color_space to override this. Again, you must select a supported transformation. jdcolor.c currently supports + + * YCbCr => GRAYSCALE YCbCr => RGB GRAYSCALE => RGB YCCK => CMYK +as well as the null transforms. (Since GRAYSCALE=>RGB is provided, an application can force grayscale JPEGs to look like color JPEGs if it only wants to handle one case.) + +The two-pass color quantizer, jquant2.c, is specialized to handle RGB data (it weights distances appropriately for RGB colors). You'll need to modify the code if you want to use it for non-RGB output color spaces. Note that jquant2.c is used to map to an application-supplied colormap as well as for the normal two-pass colormap selection process. + +CAUTION: it appears that Adobe Photoshop writes inverted data in CMYK JPEG files: 0 represents 100% ink coverage, rather than 0% ink as you'd expect. This is arguably a bug in Photoshop, but if you need to work with Photoshop CMYK files, you will have to deal with it in your application. We cannot "fix" this in the library by inverting the data during the CMYK<=>YCCK transform, because that would break other applications, notably Ghostscript. Photoshop versions prior to 3.0 write EPS files containing JPEG-encoded CMYK data in the same inverted-YCCK representation used in bare JPEG files, but the surrounding [[PostScript|PostScript]] code performs an inversion using the PS image operator. I am told that Photoshop 3.0 will write uninverted YCCK in EPS/JPEG files, and will omit the PS-level inversion. (But the data polarity used in bare JPEG files will not change in 3.0.) In either case, the JPEG library must not invert the data itself, or else Ghostscript would read these EPS files incorrectly. + + +### Error handling + +When the default error handler is used, any error detected inside the JPEG routines will cause a message to be printed on stderr, followed by exit(). You can supply your own error handling routines to override this behavior and to control the treatment of nonfatal warnings and trace/debug messages. The file example.c illustrates the most common case, which is to have the application regain control after an error rather than exiting. + +The JPEG library never writes any message directly; it always goes through the error handling routines. Three classes of messages are recognized: + + * Fatal errors: the library cannot continue. + * Warnings: the library can continue, but the data is corrupt, and a + * damaged output image is likely to result. + * Trace/informational messages. These come with a trace level indicating + * the importance of the message; you can control the verbosity of the program by adjusting the maximum trace level that will be displayed. +You may, if you wish, simply replace the entire JPEG error handling module (jerror.c) with your own code. However, you can avoid code duplication by only replacing some of the routines depending on the behavior you need. This is accomplished by calling jpeg_std_error() as usual, but then overriding some of the method pointers in the jpeg_error_mgr struct, as illustrated by example.c. + +All of the error handling routines will receive a pointer to the JPEG object (a j_common_ptr which points to either a jpeg_compress_struct or a jpeg_decompress_struct; if you need to tell which, test the is_decompressor field). This struct includes a pointer to the error manager struct in its "err" field. Frequently, custom error handler routines will need to access additional data which is not known to the JPEG library or the standard error handler. The most convenient way to do this is to embed either the JPEG object or the jpeg_error_mgr struct in a larger structure that contains additional fields; then casting the passed pointer provides access to the additional fields. Again, see example.c for one way to do it. (Beginning with IJG version 6b, there is also a void pointer "client_data" in each JPEG object, which the application can also use to find related data. The library does not touch client_data at all.) + +The individual methods that you might wish to override are: + +error_exit (j_common_ptr cinfo) + + * Receives control for a fatal error. Information sufficient to generate the error message has been stored in cinfo->err; call output_message to display it. Control must NOT return to the caller; generally this routine will exit() or longjmp() somewhere. Typically you would override this routine to get rid of the exit() default behavior. Note that if you continue processing, you should clean up the JPEG object with jpeg_abort() or jpeg_destroy(). +output_message (j_common_ptr cinfo) + + * Actual output of any JPEG message. Override this to send messages somewhere other than stderr. Note that this method does not know how to generate a message, only where to send it. +format_message (j_common_ptr cinfo, char * buffer) + + * Constructs a readable error message string based on the error info stored in cinfo->err. This method is called by output_message. Few applications should need to override this method. One possible reason for doing so is to implement dynamic switching of error message language. +emit_message (j_common_ptr cinfo, int msg_level) + + * Decide whether or not to emit a warning or trace message; if so, calls output_message. The main reason for overriding this method would be to abort on warnings. msg_level is -1 for warnings, 0 and up for trace messages. +Only error_exit() and emit_message() are called from the rest of the JPEG library; the other two are internal to the error handler. + +The actual message texts are stored in an array of strings which is pointed to by the field err->jpeg_message_table. The messages are numbered from 0 to err->last_jpeg_message, and it is these code numbers that are used in the JPEG library code. You could replace the message texts (for instance, with messages in French or German) by changing the message table pointer. See jerror.h for the default texts. CAUTION: this table will almost certainly change or grow from one library version to the next. + +It may be useful for an application to add its own message texts that are handled by the same mechanism. The error handler supports a second "add-on" message table for this purpose. To define an addon table, set the pointer err->addon_message_table and the message numbers err->first_addon_message and err->last_addon_message. If you number the addon messages beginning at 1000 or so, you won't have to worry about conflicts with the library's built-in messages. See the sample applications cjpeg/djpeg for an example of using addon messages (the addon messages are defined in cderror.h). + +Actual invocation of the error handler is done via macros defined in jerror.h: + + * ERREXITn(...) for fatal errors WARNMSn(...) for corrupt-data warnings TRACEMSn(...) for trace and informational messages. +These macros store the message code and any additional parameters into the error handler struct, then invoke the error_exit() or emit_message() method. The variants of each macro are for varying numbers of additional parameters. The additional parameters are inserted into the generated message using standard printf() format codes. + +See jerror.h and jerror.c for further details. + + +### Compressed data handling (source and destination managers) + + + +--- + + + +The JPEG compression library sends its compressed data to a "destination manager" module. The default destination manager just writes the data to a stdio stream, but you can provide your own manager to do something else. Similarly, the decompression library calls a "source manager" to obtain the compressed data; you can provide your own source manager if you want the data to come from somewhere other than a stdio stream. + +In both cases, compressed data is processed a bufferload at a time: the destination or source manager provides a work buffer, and the library invokes the manager only when the buffer is filled or emptied. (You could define a one-character buffer to force the manager to be invoked for each byte, but that would be rather inefficient.) The buffer's size and location are controlled by the manager, not by the library. For example, if you desired to decompress a JPEG datastream that was all in memory, you could just make the buffer pointer and length point to the original data in memory. Then the buffer-reload procedure would be invoked only if the decompressor ran off the end of the datastream, which would indicate an erroneous datastream. + +The work buffer is defined as an array of datatype JOCTET, which is generally "char" or "unsigned char". On a machine where char is not exactly 8 bits wide, you must define JOCTET as a wider data type and then modify the data source and destination modules to transcribe the work arrays into 8-bit units on external storage. + +A data destination manager struct contains a pointer and count defining the next byte to write in the work buffer and the remaining free space: + + * JOCTET * next_output_byte; <span style="display:none">=> next byte to write in buffer</span> size_t free_in_buffer; <span style="display:none"># of byte spaces remaining in buffer</span> +The library increments the pointer and decrements the count until the buffer is filled. The manager's empty_output_buffer method must reset the pointer and count. The manager is expected to remember the buffer's starting address and total size in private fields not visible to the library. + +A data destination manager provides three methods: + +init_destination (j_compress_ptr cinfo) + + * Initialize destination. This is called by jpeg_start_compress() before any data is actually written. It must initialize next_output_byte and free_in_buffer. free_in_buffer must be initialized to a positive value. +empty_output_buffer (j_compress_ptr cinfo) + + * This is called whenever the buffer has filled (free_in_buffer reaches zero). In typical applications, it should write out the + * entire* buffer (use the saved start address and buffer length; ignore the current state of next_output_byte and free_in_buffer). Then reset the pointer & count to the start of the buffer, and return TRUE indicating that the buffer has been dumped. free_in_buffer must be set to a positive value when TRUE is returned. A FALSE return should only be used when I/O suspension is desired (this operating mode is discussed in the next section). +term_destination (j_compress_ptr cinfo) + + * Terminate destination --- called by jpeg_finish_compress() after all data has been written. In most applications, this must flush any data remaining in the buffer. Use either next_output_byte or free_in_buffer to determine how much data is in the buffer. +term_destination() is NOT called by jpeg_abort() or jpeg_destroy(). If you want the destination manager to be cleaned up during an abort, you must do it yourself. + +You will also need code to create a jpeg_destination_mgr struct, fill in its method pointers, and insert a pointer to the struct into the "dest" field of the JPEG compression object. This can be done in-line in your setup code if you like, but it's probably cleaner to provide a separate routine similar to the jpeg_stdio_dest() routine of the supplied destination manager. + +Decompression source managers follow a parallel design, but with some additional frammishes. The source manager struct contains a pointer and count defining the next byte to read from the work buffer and the number of bytes remaining: + + * const JOCTET * next_input_byte; <span style="display:none">=> next byte to read from buffer</span> size_t bytes_in_buffer; <span style="display:none"># of bytes remaining in buffer</span> +The library increments the pointer and decrements the count until the buffer is emptied. The manager's fill_input_buffer method must reset the pointer and count. In most applications, the manager must remember the buffer's starting address and total size in private fields not visible to the library. + +A data source manager provides five methods: + +init_source (j_decompress_ptr cinfo) + + * Initialize source. This is called by jpeg_read_header() before any data is actually read. Unlike init_destination(), it may leave bytes_in_buffer set to 0 (in which case a fill_input_buffer() call will occur immediately). +fill_input_buffer (j_decompress_ptr cinfo) + + * This is called whenever bytes_in_buffer has reached zero and more data is wanted. In typical applications, it should read fresh data into the buffer (ignoring the current state of next_input_byte and bytes_in_buffer), reset the pointer & count to the start of the buffer, and return TRUE indicating that the buffer has been reloaded. It is not necessary to fill the buffer entirely, only to obtain at least one more byte. bytes_in_buffer MUST be set to a positive value if TRUE is returned. A FALSE return should only be used when I/O suspension is desired (this mode is discussed in the next section). +skip_input_data (j_decompress_ptr cinfo, long num_bytes) + + * Skip num_bytes worth of data. The buffer pointer and count should be advanced over num_bytes input bytes, refilling the buffer as needed. This is used to skip over a potentially large amount of uninteresting data (such as an APPn marker). In some applications it may be possible to optimize away the reading of the skipped data, but it's not clear that being smart is worth much trouble; large skips are uncommon. bytes_in_buffer may be zero on return. A zero or negative skip count should be treated as a no-op. +resync_to_restart (j_decompress_ptr cinfo, int desired) + + * This routine is called only when the decompressor has failed to find a restart (RSTn) marker where one is expected. Its mission is to find a suitable point for resuming decompression. For most applications, we recommend that you just use the default resync procedure, jpeg_resync_to_restart(). However, if you are able to back up in the input data stream, or if you have a-priori knowledge about the likely location of restart markers, you may be able to do better. Read the read_restart_marker() and jpeg_resync_to_restart() routines in jdmarker.c if you think you'd like to implement your own resync procedure. +term_source (j_decompress_ptr cinfo) + + * Terminate source --- called by jpeg_finish_decompress() after all data has been read. Often a no-op. +For both fill_input_buffer() and skip_input_data(), there is no such thing as an EOF return. If the end of the file has been reached, the routine has a choice of exiting via ERREXIT() or inserting fake data into the buffer. In most cases, generating a warning message and inserting a fake EOI marker is the best course of action --- this will allow the decompressor to output however much of the image is there. In pathological cases, the decompressor may swallow the EOI and again demand data ... just keep feeding it fake EOIs. jdatasrc.c illustrates the recommended error recovery behavior. + +term_source() is NOT called by jpeg_abort() or jpeg_destroy(). If you want the source manager to be cleaned up during an abort, you must do it yourself. + +You will also need code to create a jpeg_source_mgr struct, fill in its method pointers, and insert a pointer to the struct into the "src" field of the JPEG decompression object. This can be done in-line in your setup code if you like, but it's probably cleaner to provide a separate routine similar to the jpeg_stdio_src() routine of the supplied source manager. + +For more information, consult the stdio source and destination managers in jdatasrc.c and jdatadst.c. + + +### I/O suspension + +Some applications need to use the JPEG library as an incremental memory-to- memory filter: when the compressed data buffer is filled or emptied, they want control to return to the outer loop, rather than expecting that the buffer can be emptied or reloaded within the data source/destination manager subroutine. The library supports this need by providing an "I/O suspension" mode, which we describe in this section. + +The I/O suspension mode is not a panacea: nothing is guaranteed about the maximum amount of time spent in any one call to the library, so it will not eliminate response-time problems in single-threaded applications. If you need guaranteed response time, we suggest you "bite the bullet" and implement a real multi-tasking capability. + +To use I/O suspension, cooperation is needed between the calling application and the data source or destination manager; you will always need a custom source/destination manager. (Please read the previous section if you haven't already.) The basic idea is that the empty_output_buffer() or fill_input_buffer() routine is a no-op, merely returning FALSE to indicate that it has done nothing. Upon seeing this, the JPEG library suspends operation and returns to its caller. The surrounding application is responsible for emptying or refilling the work buffer before calling the JPEG library again. + +Compression suspension: + +For compression suspension, use an empty_output_buffer() routine that returns FALSE; typically it will not do anything else. This will cause the compressor to return to the caller of jpeg_write_scanlines(), with the return value indicating that not all the supplied scanlines have been accepted. The application must make more room in the output buffer, adjust the output buffer pointer/count appropriately, and then call jpeg_write_scanlines() again, pointing to the first unconsumed scanline. + +When forced to suspend, the compressor will backtrack to a convenient stopping point (usually the start of the current MCU); it will regenerate some output data when restarted. Therefore, although empty_output_buffer() is only called when the buffer is filled, you should NOT write out the entire buffer after a suspension. Write only the data up to the current position of next_output_byte/free_in_buffer. The data beyond that point will be regenerated after resumption. + +Because of the backtracking behavior, a good-size output buffer is essential for efficiency; you don't want the compressor to suspend often. (In fact, an overly small buffer could lead to infinite looping, if a single MCU required more data than would fit in the buffer.) We recommend a buffer of at least several Kbytes. You may want to insert explicit code to ensure that you don't call jpeg_write_scanlines() unless there is a reasonable amount of space in the output buffer; in other words, flush the buffer before trying to compress more data. + +The compressor does not allow suspension while it is trying to write JPEG markers at the beginning and end of the file. This means that: + + * At the beginning of a compression operation, there must be enough free + * space in the output buffer to hold the header markers (typically 600 or so bytes). The recommended buffer size is bigger than this anyway, so this is not a problem as long as you start with an empty buffer. However, this restriction might catch you if you insert large special markers, such as a JFIF thumbnail image, without flushing the buffer afterwards. + * When you call jpeg_finish_compress(), there must be enough space in the + * output buffer to emit any buffered data and the final EOI marker. In the current implementation, half a dozen bytes should suffice for this, but for safety's sake we recommend ensuring that at least 100 bytes are free before calling jpeg_finish_compress(). +A more significant restriction is that jpeg_finish_compress() cannot suspend. This means you cannot use suspension with multi-pass operating modes, namely Huffman code optimization and multiple-scan output. Those modes write the whole file during jpeg_finish_compress(), which will certainly result in buffer overrun. (Note that this restriction applies only to compression, not decompression. The decompressor supports input suspension in all of its operating modes.) + +Decompression suspension: + +For decompression suspension, use a fill_input_buffer() routine that simply returns FALSE (except perhaps during error recovery, as discussed below). This will cause the decompressor to return to its caller with an indication that suspension has occurred. This can happen at four places: + + * jpeg_read_header(): will return JPEG_SUSPENDED. + * jpeg_start_decompress(): will return FALSE, rather than its usual TRUE. + * jpeg_read_scanlines(): will return the number of scanlines already + * completed (possibly 0). + * jpeg_finish_decompress(): will return FALSE, rather than its usual TRUE. +The surrounding application must recognize these cases, load more data into the input buffer, and repeat the call. In the case of jpeg_read_scanlines(), increment the passed pointers past any scanlines successfully read. + +Just as with compression, the decompressor will typically backtrack to a convenient restart point before suspending. When fill_input_buffer() is called, next_input_byte/bytes_in_buffer point to the current restart point, which is where the decompressor will backtrack to if FALSE is returned. The data beyond that position must NOT be discarded if you suspend; it needs to be re-read upon resumption. In most implementations, you'll need to shift this data down to the start of your work buffer and then load more data after it. Again, this behavior means that a several-Kbyte work buffer is essential for decent performance; furthermore, you should load a reasonable amount of new data before resuming decompression. (If you loaded, say, only one new byte each time around, you could waste a LOT of cycles.) + +The skip_input_data() source manager routine requires special care in a suspension scenario. This routine is NOT granted the ability to suspend the decompressor; it can decrement bytes_in_buffer to zero, but no more. If the requested skip distance exceeds the amount of data currently in the input buffer, then skip_input_data() must set bytes_in_buffer to zero and record the additional skip distance somewhere else. The decompressor will immediately call fill_input_buffer(), which should return FALSE, which will cause a suspension return. The surrounding application must then arrange to discard the recorded number of bytes before it resumes loading the input buffer. (Yes, this design is rather baroque, but it avoids complexity in the far more common case where a non-suspending source manager is used.) + +If the input data has been exhausted, we recommend that you emit a warning and insert dummy EOI markers just as a non-suspending data source manager would do. This can be handled either in the surrounding application logic or within fill_input_buffer(); the latter is probably more efficient. If fill_input_buffer() knows that no more data is available, it can set the pointer/count to point to a dummy EOI marker and then return TRUE just as though it had read more data in a non-suspending situation. + +The decompressor does not attempt to suspend within standard JPEG markers; instead it will backtrack to the start of the marker and reprocess the whole marker next time. Hence the input buffer must be large enough to hold the longest standard marker in the file. Standard JPEG markers should normally not exceed a few hundred bytes each (DHT tables are typically the longest). We recommend at least a 2K buffer for performance reasons, which is much larger than any correct marker is likely to be. For robustness against damaged marker length counts, you may wish to insert a test in your application for the case that the input buffer is completely full and yet the decoder has suspended without consuming any data --- otherwise, if this situation did occur, it would lead to an endless loop. (The library can't provide this test since it has no idea whether "the buffer is full", or even whether there is a fixed-size input buffer.) + +The input buffer would need to be 64K to allow for arbitrary COM or APPn markers, but these are handled specially: they are either saved into allocated memory, or skipped over by calling skip_input_data(). In the former case, suspension is handled correctly, and in the latter case, the problem of buffer overrun is placed on skip_input_data's shoulders, as explained above. Note that if you provide your own marker handling routine for large markers, you should consider how to deal with buffer overflow. + +Multiple-buffer management: + +In some applications it is desirable to store the compressed data in a linked list of buffer areas, so as to avoid data copying. This can be handled by having empty_output_buffer() or fill_input_buffer() set the pointer and count to reference the next available buffer; FALSE is returned only if no more buffers are available. Although seemingly straightforward, there is a pitfall in this approach: the backtrack that occurs when FALSE is returned could back up into an earlier buffer. For example, when fill_input_buffer() is called, the current pointer & count indicate the backtrack restart point. Since fill_input_buffer() will set the pointer and count to refer to a new buffer, the restart position must be saved somewhere else. Suppose a second call to fill_input_buffer() occurs in the same library call, and no additional input data is available, so fill_input_buffer must return FALSE. If the JPEG library has not moved the pointer/count forward in the current buffer, then *the correct restart point is the saved position in the prior buffer*. Prior buffers may be discarded only after the library establishes a restart point within a later buffer. Similar remarks apply for output into a chain of buffers. + +The library will never attempt to backtrack over a skip_input_data() call, so any skipped data can be permanently discarded. You still have to deal with the case of skipping not-yet-received data, however. + +It's much simpler to use only a single buffer; when fill_input_buffer() is called, move any unconsumed data (beyond the current pointer/count) down to the beginning of this buffer and then load new data into the remaining buffer space. This approach requires a little more data copying but is far easier to get right. + + +### Progressive JPEG support + +Progressive JPEG rearranges the stored data into a series of scans of increasing quality. In situations where a JPEG file is transmitted across a slow communications link, a decoder can generate a low-quality image very quickly from the first scan, then gradually improve the displayed quality as more scans are received. The final image after all scans are complete is identical to that of a regular (sequential) JPEG file of the same quality setting. Progressive JPEG files are often slightly smaller than equivalent sequential JPEG files, but the possibility of incremental display is the main reason for using progressive JPEG. + +The IJG encoder library generates progressive JPEG files when given a suitable "scan script" defining how to divide the data into scans. Creation of progressive JPEG files is otherwise transparent to the encoder. Progressive JPEG files can also be read transparently by the decoder library. If the decoding application simply uses the library as defined above, it will receive a final decoded image without any indication that the file was progressive. Of course, this approach does not allow incremental display. To perform incremental display, an application needs to use the decoder library's "buffered-image" mode, in which it receives a decoded image multiple times. + +Each displayed scan requires about as much work to decode as a full JPEG image of the same size, so the decoder must be fairly fast in relation to the data transmission rate in order to make incremental display useful. However, it is possible to skip displaying the image and simply add the incoming bits to the decoder's coefficient buffer. This is fast because only Huffman decoding need be done, not IDCT, upsampling, colorspace conversion, etc. The IJG decoder library allows the application to switch dynamically between displaying the image and simply absorbing the incoming bits. A properly coded application can automatically adapt the number of display passes to suit the time available as the image is received. Also, a final higher-quality display cycle can be performed from the buffered data after the end of the file is reached. + +Progressive compression: + +To create a progressive JPEG file (or a multiple-scan sequential JPEG file), set the scan_info cinfo field to point to an array of scan descriptors, and perform compression as usual. Instead of constructing your own scan list, you can call the jpeg_simple_progression() helper routine to create a recommended progression sequence; this method should be used by all applications that don't want to get involved in the nitty-gritty of progressive scan sequence design. (If you want to provide user control of scan sequences, you may wish to borrow the scan script reading code found in rdswitch.c, so that you can read scan script files just like cjpeg's.) When scan_info is not NULL, the compression library will store DCT'd data into a buffer array as jpeg_write_scanlines() is called, and will emit all the requested scans during jpeg_finish_compress(). This implies that multiple-scan output cannot be created with a suspending data destination manager, since jpeg_finish_compress() does not support suspension. We should also note that the compressor currently forces Huffman optimization mode when creating a progressive JPEG file, because the default Huffman tables are unsuitable for progressive files. + +Progressive decompression: + +When buffered-image mode is not used, the decoder library will read all of a multi-scan file during jpeg_start_decompress(), so that it can provide a final decoded image. (Here "multi-scan" means either progressive or multi-scan sequential.) This makes multi-scan files transparent to the decoding application. However, existing applications that used suspending input with version 5 of the IJG library will need to be modified to check for a suspension return from jpeg_start_decompress(). + +To perform incremental display, an application must use the library's buffered-image mode. This is described in the next section. + + +### Buffered-image mode + +In buffered-image mode, the library stores the partially decoded image in a coefficient buffer, from which it can be read out as many times as desired. This mode is typically used for incremental display of progressive JPEG files, but it can be used with any JPEG file. Each scan of a progressive JPEG file adds more data (more detail) to the buffered image. The application can display in lockstep with the source file (one display pass per input scan), or it can allow input processing to outrun display processing. By making input and display processing run independently, it is possible for the application to adapt progressive display to a wide range of data transmission rates. + +The basic control flow for buffered-image decoding is + +<code> + + * jpeg_create_decompress() set data source jpeg_read_header() set overall decompression parameters cinfo.buffered_image = TRUE; <span style="display:none">select buffered-image mode</span> jpeg_start_decompress() for (each output pass) { + * adjust output decompression parameters if required jpeg_start_output() <span style="display:none">start a new output pass</span> for (all scanlines in image) { + * jpeg_read_scanlines() display scanlines } +jpeg_finish_output() <span style="display:none">terminate output pass</span> +} jpeg_finish_decompress() jpeg_destroy_decompress() +</code> + +This differs from ordinary unbuffered decoding in that there is an additional level of looping. The application can choose how many output passes to make and how to display each pass. + +The simplest approach to displaying progressive images is to do one display pass for each scan appearing in the input file. In this case the outer loop condition is typically + + * while (! jpeg_input_complete(&cinfo)) +and the start-output call should read + + * jpeg_start_output(&cinfo, cinfo.input_scan_number); +The second parameter to jpeg_start_output() indicates which scan of the input file is to be displayed; the scans are numbered starting at 1 for this purpose. (You can use a loop counter starting at 1 if you like, but using the library's input scan counter is easier.) The library automatically reads data as necessary to complete each requested scan, and jpeg_finish_output() advances to the next scan or end-of-image marker (hence input_scan_number will be incremented by the time control arrives back at jpeg_start_output()). With this technique, data is read from the input file only as needed, and input and output processing run in lockstep. + +After reading the final scan and reaching the end of the input file, the buffered image remains available; it can be read additional times by repeating the jpeg_start_output()/jpeg_read_scanlines()/jpeg_finish_output() sequence. For example, a useful technique is to use fast one-pass color quantization for display passes made while the image is arriving, followed by a final display pass using two-pass quantization for highest quality. This is done by changing the library parameters before the final output pass. Changing parameters between passes is discussed in detail below. + +In general the last scan of a progressive file cannot be recognized as such until after it is read, so a post-input display pass is the best approach if you want special processing in the final pass. + +When done with the image, be sure to call jpeg_finish_decompress() to release the buffered image (or just use jpeg_destroy_decompress()). + +If input data arrives faster than it can be displayed, the application can cause the library to decode input data in advance of what's needed to produce output. This is done by calling the routine jpeg_consume_input(). The return value is one of the following: + + * JPEG_REACHED_SOS: reached an SOS marker (the start of a new scan) JPEG_REACHED_EOI: reached the EOI marker (end of image) JPEG_ROW_COMPLETED: completed reading one MCU row of compressed data JPEG_SCAN_COMPLETED: completed reading last MCU row of current scan JPEG_SUSPENDED: suspended before completing any of the above +(JPEG_SUSPENDED can occur only if a suspending data source is used.) This routine can be called at any time after initializing the JPEG object. It reads some additional data and returns when one of the indicated significant events occurs. (If called after the EOI marker is reached, it will immediately return JPEG_REACHED_EOI without attempting to read more data.) + +The library's output processing will automatically call jpeg_consume_input() whenever the output processing overtakes the input; thus, simple lockstep display requires no direct calls to jpeg_consume_input(). But by adding calls to jpeg_consume_input(), you can absorb data in advance of what is being displayed. This has two benefits: + + * You can limit buildup of unprocessed data in your input buffer. + * You can eliminate extra display passes by paying attention to the + * state of the library's input processing. +The first of these benefits only requires interspersing calls to jpeg_consume_input() with your display operations and any other processing you may be doing. To avoid wasting cycles due to backtracking, it's best to call jpeg_consume_input() only after a hundred or so new bytes have arrived. This is discussed further under "I/O suspension", above. (Note: the JPEG library currently is not thread-safe. You must not call jpeg_consume_input() from one thread of control if a different library routine is working on the same JPEG object in another thread.) + +When input arrives fast enough that more than one new scan is available before you start a new output pass, you may as well skip the output pass corresponding to the completed scan. This occurs for free if you pass cinfo.input_scan_number as the target scan number to jpeg_start_output(). The input_scan_number field is simply the index of the scan currently being consumed by the input processor. You can ensure that this is up-to-date by emptying the input buffer just before calling jpeg_start_output(): call jpeg_consume_input() repeatedly until it returns JPEG_SUSPENDED or JPEG_REACHED_EOI. + +The target scan number passed to jpeg_start_output() is saved in the cinfo.output_scan_number field. The library's output processing calls jpeg_consume_input() whenever the current input scan number and row within that scan is less than or equal to the current output scan number and row. Thus, input processing can "get ahead" of the output processing but is not allowed to "fall behind". You can achieve several different effects by manipulating this interlock rule. For example, if you pass a target scan number greater than the current input scan number, the output processor will wait until that scan starts to arrive before producing any output. (To avoid an infinite loop, the target scan number is automatically reset to the last scan number when the end of image is reached. Thus, if you specify a large target scan number, the library will just absorb the entire input file and then perform an output pass. This is effectively the same as what jpeg_start_decompress() does when you don't select buffered-image mode.) When you pass a target scan number equal to the current input scan number, the image is displayed no faster than the current input scan arrives. The final possibility is to pass a target scan number less than the current input scan number; this disables the input/output interlock and causes the output processor to simply display whatever it finds in the image buffer, without waiting for input. (However, the library will not accept a target scan number less than one, so you can't avoid waiting for the first scan.) + +When data is arriving faster than the output display processing can advance through the image, jpeg_consume_input() will store data into the buffered image beyond the point at which the output processing is reading data out again. If the input arrives fast enough, it may "wrap around" the buffer to the point where the input is more than one whole scan ahead of the output. If the output processing simply proceeds through its display pass without paying attention to the input, the effect seen on-screen is that the lower part of the image is one or more scans better in quality than the upper part. Then, when the next output scan is started, you have a choice of what target scan number to use. The recommended choice is to use the current input scan number at that time, which implies that you've skipped the output scans corresponding to the input scans that were completed while you processed the previous output scan. In this way, the decoder automatically adapts its speed to the arriving data, by skipping output scans as necessary to keep up with the arriving data. + +When using this strategy, you'll want to be sure that you perform a final output pass after receiving all the data; otherwise your last display may not be full quality across the whole screen. So the right outer loop logic is something like this: <code> + + * do { + * absorb any waiting input by calling jpeg_consume_input() final_pass = jpeg_input_complete(&cinfo); adjust output decompression parameters if required jpeg_start_output(&cinfo, cinfo.input_scan_number); + * .. jpeg_finish_output() } while (! final_pass); +</code> rather than quitting as soon as jpeg_input_complete() returns TRUE. This arrangement makes it simple to use higher-quality decoding parameters for the final pass. But if you don't want to use special parameters for the final pass, the right loop logic is like this: <code> + + * for (;;) { + * absorb any waiting input by calling jpeg_consume_input() jpeg_start_output(&cinfo, cinfo.input_scan_number); + * .. jpeg_finish_output() if (jpeg_input_complete(&cinfo) && + * cinfo.input_scan_number == cinfo.output_scan_number) + * break; } +</code> In this case you don't need to know in advance whether an output pass is to be the last one, so it's not necessary to have reached EOF before starting the final output pass; rather, what you want to test is whether the output pass was performed in sync with the final input scan. This form of the loop will avoid an extra output pass whenever the decoder is able (or nearly able) to keep up with the incoming data. + +When the data transmission speed is high, you might begin a display pass, then find that much or all of the file has arrived before you can complete the pass. (You can detect this by noting the JPEG_REACHED_EOI return code from jpeg_consume_input(), or equivalently by testing jpeg_input_complete().) In this situation you may wish to abort the current display pass and start a new one using the newly arrived information. To do so, just call jpeg_finish_output() and then start a new pass with jpeg_start_output(). + +A variant strategy is to abort and restart display if more than one complete scan arrives during an output pass; this can be detected by noting JPEG_REACHED_SOS returns and/or examining cinfo.input_scan_number. This idea should be employed with caution, however, since the display process might never get to the bottom of the image before being aborted, resulting in the lower part of the screen being several passes worse than the upper. In most cases it's probably best to abort an output pass only if the whole file has arrived and you want to begin the final output pass immediately. + +When receiving data across a communication link, we recommend always using the current input scan number for the output target scan number; if a higher-quality final pass is to be done, it should be started (aborting any incomplete output pass) as soon as the end of file is received. However, many other strategies are possible. For example, the application can examine the parameters of the current input scan and decide whether to display it or not. If the scan contains only chroma data, one might choose not to use it as the target scan, expecting that the scan will be small and will arrive quickly. To skip to the next scan, call jpeg_consume_input() until it returns JPEG_REACHED_SOS or JPEG_REACHED_EOI. Or just use the next higher number as the target scan for jpeg_start_output(); but that method doesn't let you inspect the next scan's parameters before deciding to display it. + +In buffered-image mode, jpeg_start_decompress() never performs input and thus never suspends. An application that uses input suspension with buffered-image mode must be prepared for suspension returns from these routines: * jpeg_start_output() performs input only if you request 2-pass quantization + + * and the target scan isn't fully read yet. (This is discussed below.) +* jpeg_read_scanlines(), as always, returns the number of scanlines that it + + * was able to produce before suspending. +* jpeg_finish_output() will read any markers following the target scan, + + * up to the end of the file or the SOS marker that begins another scan. (But it reads no input if jpeg_consume_input() has already reached the end of the file or a SOS marker beyond the target output scan.) +* jpeg_finish_decompress() will read until the end of file, and thus can + + * suspend if the end hasn't already been reached (as can be tested by calling jpeg_input_complete()). +jpeg_start_output(), jpeg_finish_output(), and jpeg_finish_decompress() all return TRUE if they completed their tasks, FALSE if they had to suspend. In the event of a FALSE return, the application must load more input data and repeat the call. Applications that use non-suspending data sources need not check the return values of these three routines. + +It is possible to change decoding parameters between output passes in the buffered-image mode. The decoder library currently supports only very limited changes of parameters. ONLY THE FOLLOWING parameter changes are allowed after jpeg_start_decompress() is called: * dct_method can be changed before each call to jpeg_start_output(). + + * For example, one could use a fast DCT method for early scans, changing to a higher quality method for the final scan. +* dither_mode can be changed before each call to jpeg_start_output(); + + * of course this has no impact if not using color quantization. Typically one would use ordered dither for initial passes, then switch to Floyd-Steinberg dither for the final pass. Caution: changing dither mode can cause more memory to be allocated by the library. Although the amount of memory involved is not large (a scanline or so), it may cause the initial max_memory_to_use specification to be exceeded, which in the worst case would result in an out-of-memory failure. +* do_block_smoothing can be changed before each call to jpeg_start_output(). + + * This setting is relevant only when decoding a progressive JPEG image. During the first DC-only scan, block smoothing provides a very "fuzzy" look instead of the very "blocky" look seen without it; which is better seems a matter of personal taste. But block smoothing is nearly always a win during later stages, especially when decoding a successive-approximation image: smoothing helps to hide the slight blockiness that otherwise shows up on smooth gradients until the lowest coefficient bits are sent. +* Color quantization mode can be changed under the rules described below. + + * You *cannot* change between full-color and quantized output (because that would alter the required I/O buffer sizes), but you can change which quantization method is used. +When generating color-quantized output, changing quantization method is a very useful way of switching between high-speed and high-quality display. The library allows you to change among its three quantization methods: 1. Single-pass quantization to a fixed color cube. + + * Selected by cinfo.two_pass_quantize = FALSE and cinfo.colormap = NULL. +2. Single-pass quantization to an application-supplied colormap. + + * Selected by setting cinfo.colormap to point to the colormap (the value of two_pass_quantize is ignored); also set cinfo.actual_number_of_colors. +3. Two-pass quantization to a colormap chosen specifically for the image. + + * Selected by cinfo.two_pass_quantize = TRUE and cinfo.colormap = NULL. (This is the default setting selected by jpeg_read_header, but it is probably NOT what you want for the first pass of progressive display!) +These methods offer successively better quality and lesser speed. However, only the first method is available for quantizing in non-RGB color spaces. + +IMPORTANT: because the different quantizer methods have very different working-storage requirements, the library requires you to indicate which one(s) you intend to use before you call jpeg_start_decompress(). (If we did not require this, the max_memory_to_use setting would be a complete fiction.) You do this by setting one or more of these three cinfo fields to TRUE: + + * enable_1pass_quant Fixed color cube colormap enable_external_quant Externally-supplied colormap enable_2pass_quant Two-pass custom colormap +All three are initialized FALSE by jpeg_read_header(). But jpeg_start_decompress() automatically sets TRUE the one selected by the current two_pass_quantize and colormap settings, so you only need to set the enable flags for any other quantization methods you plan to change to later. + +After setting the enable flags correctly at jpeg_start_decompress() time, you can change to any enabled quantization method by setting two_pass_quantize and colormap properly just before calling jpeg_start_output(). The following special rules apply: 1. You must explicitly set cinfo.colormap to NULL when switching to 1-pass + + * or 2-pass mode from a different mode, or when you want the 2-pass quantizer to be re-run to generate a new colormap. +2. To switch to an external colormap, or to change to a different external + + * colormap than was used on the prior pass, you must call jpeg_new_colormap() after setting cinfo.colormap. +NOTE: if you want to use the same colormap as was used in the prior pass, you should not do either of these things. This will save some nontrivial switchover costs. (These requirements exist because cinfo.colormap will always be non-NULL after completing a prior output pass, since both the 1-pass and 2-pass quantizers set it to point to their output colormaps. Thus you have to do one of these two things to notify the library that something has changed. Yup, it's a bit klugy, but it's necessary to do it this way for backwards compatibility.) + +Note that in buffered-image mode, the library generates any requested colormap during jpeg_start_output(), not during jpeg_start_decompress(). + +When using two-pass quantization, jpeg_start_output() makes a pass over the buffered image to determine the optimum color map; it therefore may take a significant amount of time, whereas ordinarily it does little work. The progress monitor hook is called during this pass, if defined. It is also important to realize that if the specified target scan number is greater than or equal to the current input scan number, jpeg_start_output() will attempt to consume input as it makes this pass. If you use a suspending data source, you need to check for a FALSE return from jpeg_start_output() under these conditions. The combination of 2-pass quantization and a not-yet-fully-read target scan is the only case in which jpeg_start_output() will consume input. + +Application authors who support buffered-image mode may be tempted to use it for all JPEG images, even single-scan ones. This will work, but it is inefficient: there is no need to create an image-sized coefficient buffer for single-scan images. Requesting buffered-image mode for such an image wastes memory. Worse, it can cost time on large images, since the buffered data has to be swapped out or written to a temporary file. If you are concerned about maximum performance on baseline JPEG files, you should use buffered-image mode only when the incoming file actually has multiple scans. This can be tested by calling jpeg_has_multiple_scans(), which will return a correct result at any time after jpeg_read_header() completes. + +It is also worth noting that when you use jpeg_consume_input() to let input processing get ahead of output processing, the resulting pattern of access to the coefficient buffer is quite nonsequential. It's best to use the memory manager jmemnobs.c if you can (ie, if you have enough real or virtual main memory). If not, at least make sure that max_memory_to_use is set as high as possible. If the JPEG memory manager has to use a temporary file, you will probably see a lot of disk traffic and poor performance. (This could be improved with additional work on the memory manager, but we haven't gotten around to it yet.) + +In some applications it may be convenient to use jpeg_consume_input() for all input processing, including reading the initial markers; that is, you may wish to call jpeg_consume_input() instead of jpeg_read_header() during startup. This works, but note that you must check for JPEG_REACHED_SOS and JPEG_REACHED_EOI return codes as the equivalent of jpeg_read_header's codes. Once the first SOS marker has been reached, you must call jpeg_start_decompress() before jpeg_consume_input() will consume more input; it'll just keep returning JPEG_REACHED_SOS until you do. If you read a tables-only file this way, jpeg_consume_input() will return JPEG_REACHED_EOI without ever returning JPEG_REACHED_SOS; be sure to check for this case. If this happens, the decompressor will not read any more input until you call jpeg_abort() to reset it. It is OK to call jpeg_consume_input() even when not using buffered-image mode, but in that case it's basically a no-op after the initial markers have been read: it will just return JPEG_SUSPENDED. + + +### Abbreviated datastreams and multiple images + +A JPEG compression or decompression object can be reused to process multiple images. This saves a small amount of time per image by eliminating the "create" and "destroy" operations, but that isn't the real purpose of the feature. Rather, reuse of an object provides support for abbreviated JPEG datastreams. Object reuse can also simplify processing a series of images in a single input or output file. This section explains these features. + +A JPEG file normally contains several hundred bytes worth of quantization and Huffman tables. In a situation where many images will be stored or transmitted with identical tables, this may represent an annoying overhead. The JPEG standard therefore permits tables to be omitted. The standard defines three classes of JPEG datastreams: + + * "Interchange" datastreams contain an image and all tables needed to decode + * the image. These are the usual kind of JPEG file. + * "Abbreviated image" datastreams contain an image, but are missing some or + * all of the tables needed to decode that image. + * "Abbreviated table specification" (henceforth "tables-only") datastreams + * contain only table specifications. +To decode an abbreviated image, it is necessary to load the missing table(s) into the decoder beforehand. This can be accomplished by reading a separate tables-only file. A variant scheme uses a series of images in which the first image is an interchange (complete) datastream, while subsequent ones are abbreviated and rely on the tables loaded by the first image. It is assumed that once the decoder has read a table, it will remember that table until a new definition for the same table number is encountered. + +It is the application designer's responsibility to figure out how to associate the correct tables with an abbreviated image. While abbreviated datastreams can be useful in a closed environment, their use is strongly discouraged in any situation where data exchange with other applications might be needed. Caveat designer. + +The JPEG library provides support for reading and writing any combination of tables-only datastreams and abbreviated images. In both compression and decompression objects, a quantization or Huffman table will be retained for the lifetime of the object, unless it is overwritten by a new table definition. + +To create abbreviated image datastreams, it is only necessary to tell the compressor not to emit some or all of the tables it is using. Each quantization and Huffman table struct contains a boolean field "sent_table", which normally is initialized to FALSE. For each table used by the image, the header-writing process emits the table and sets sent_table = TRUE unless it is already TRUE. (In normal usage, this prevents outputting the same table definition multiple times, as would otherwise occur because the chroma components typically share tables.) Thus, setting this field to TRUE before calling jpeg_start_compress() will prevent the table from being written at all. + +If you want to create a "pure" abbreviated image file containing no tables, just call "jpeg_suppress_tables(&cinfo, TRUE)" after constructing all the tables. If you want to emit some but not all tables, you'll need to set the individual sent_table fields directly. + +To create an abbreviated image, you must also call jpeg_start_compress() with a second parameter of FALSE, not TRUE. Otherwise jpeg_start_compress() will force all the sent_table fields to FALSE. (This is a safety feature to prevent abbreviated images from being created accidentally.) + +To create a tables-only file, perform the same parameter setup that you normally would, but instead of calling jpeg_start_compress() and so on, call jpeg_write_tables(&cinfo). This will write an abbreviated datastream containing only SOI, DQT and/or DHT markers, and EOI. All the quantization and Huffman tables that are currently defined in the compression object will be emitted unless their sent_tables flag is already TRUE, and then all the sent_tables flags will be set TRUE. + +A sure-fire way to create matching tables-only and abbreviated image files is to proceed as follows: <code> + + * create JPEG compression object set JPEG parameters set destination to tables-only file jpeg_write_tables(&cinfo); set destination to image file jpeg_start_compress(&cinfo, FALSE); write data... jpeg_finish_compress(&cinfo); +</code> + +Since the JPEG parameters are not altered between writing the table file and the abbreviated image file, the same tables are sure to be used. Of course, you can repeat the jpeg_start_compress() ... jpeg_finish_compress() sequence many times to produce many abbreviated image files matching the table file. + +You cannot suppress output of the computed Huffman tables when Huffman optimization is selected. (If you could, there'd be no way to decode the image...) Generally, you don't want to set optimize_coding = TRUE when you are trying to produce abbreviated files. + +In some cases you might want to compress an image using tables which are not stored in the application, but are defined in an interchange or tables-only file readable by the application. This can be done by setting up a JPEG decompression object to read the specification file, then copying the tables into your compression object. See jpeg_copy_critical_parameters() for an example of copying quantization tables. + +To read abbreviated image files, you simply need to load the proper tables into the decompression object before trying to read the abbreviated image. If the proper tables are stored in the application program, you can just allocate the table structs and fill in their contents directly. For example, to load a fixed quantization table into table slot "n": + +<code> + + * if (cinfo.quant_tbl_ptrs[n] == NULL) + * cinfo.quant_tbl_ptrs[n] = jpeg_alloc_quant_table((j_common_ptr) &cinfo); +quant_ptr = cinfo.quant_tbl_ptrs[n]; <span style="display:none">quant_ptr is JQUANT_TBL*</span> for (i = 0; i < 64; i++) { + + * <span style="display:none">Qtable[] is desired quantization table, in natural array order</span> quant_ptr->quantval[i] = Qtable[i]; } +</code> + +Code to load a fixed Huffman table is typically (for AC table "n"): + +<code> + + * if (cinfo.ac_huff_tbl_ptrs[n] == NULL) + * cinfo.ac_huff_tbl_ptrs[n] = jpeg_alloc_huff_table((j_common_ptr) &cinfo); +huff_ptr = cinfo.ac_huff_tbl_ptrs[n]; <span style="display:none">huff_ptr is JHUFF_TBL*</span> for (i = 1; i <= 16; i++) { + + * <span style="display:none">counts[i] is number of Huffman codes of length i bits, i=1..16</span> huff_ptr->bits[i] = counts[i]; } +for (i = 0; i < 256; i++) { + + * <span style="display:none">symbols[] is the list of Huffman symbols, in code-length order</span> huff_ptr->huffval[i] = symbols[i]; } +</code> + +(Note that trying to set cinfo.quant_tbl_ptrs[n] to point directly at a constant JQUANT_TBL object is not safe. If the incoming file happened to contain a quantization table definition, your master table would get overwritten! Instead allocate a working table copy and copy the master table into it, as illustrated above. Ditto for Huffman tables, of course.) + +You might want to read the tables from a tables-only file, rather than hard-wiring them into your application. The jpeg_read_header() call is sufficient to read a tables-only file. You must pass a second parameter of FALSE to indicate that you do not require an image to be present. Thus, the typical scenario is + +<code> + + * create JPEG decompression object set source to tables-only file jpeg_read_header(&cinfo, FALSE); set source to abbreviated image file jpeg_read_header(&cinfo, TRUE); set decompression parameters jpeg_start_decompress(&cinfo); read data... jpeg_finish_decompress(&cinfo); +</code> + +In some cases, you may want to read a file without knowing whether it contains an image or just tables. In that case, pass FALSE and check the return value from jpeg_read_header(): it will be JPEG_HEADER_OK if an image was found, JPEG_HEADER_TABLES_ONLY if only tables were found. (A third return value, JPEG_SUSPENDED, is possible when using a suspending data source manager.) Note that jpeg_read_header() will not complain if you read an abbreviated image for which you haven't loaded the missing tables; the missing-table check occurs later, in jpeg_start_decompress(). + +It is possible to read a series of images from a single source file by repeating the jpeg_read_header() ... jpeg_finish_decompress() sequence, without releasing/recreating the JPEG object or the data source module. (If you did reinitialize, any partial bufferload left in the data source buffer at the end of one image would be discarded, causing you to lose the start of the next image.) When you use this method, stored tables are automatically carried forward, so some of the images can be abbreviated images that depend on tables from earlier images. + +If you intend to write a series of images into a single destination file, you might want to make a specialized data destination module that doesn't flush the output buffer at term_destination() time. This would speed things up by some trifling amount. Of course, you'd need to remember to flush the buffer after the last image. You can make the later images be abbreviated ones by passing FALSE to jpeg_start_compress(). + + +### Special markers + +Some applications may need to insert or extract special data in the JPEG datastream. The JPEG standard provides marker types "COM" (comment) and "APP0" through "APP15" (application) to hold application-specific data. Unfortunately, the use of these markers is not specified by the standard. COM markers are fairly widely used to hold user-supplied text. The JFIF file format spec uses APP0 markers with specified initial strings to hold certain data. Adobe applications use APP14 markers beginning with the string "Adobe" for miscellaneous data. Other APPn markers are rarely seen, but might contain almost anything. + +If you wish to store user-supplied text, we recommend you use COM markers and place readable 7-bit ASCII text in them. Newline conventions are not standardized --- expect to find LF (Unix style), CR/LF (DOS style), or CR (Mac style). A robust COM reader should be able to cope with random binary garbage, including nulls, since some applications generate COM markers containing non-ASCII junk. (But yours should not be one of them.) + +For program-supplied data, use an APPn marker, and be sure to begin it with an identifying string so that you can tell whether the marker is actually yours. It's probably best to avoid using APP0 or APP14 for any private markers. (NOTE: the upcoming SPIFF standard will use APP8 markers; we recommend you not use APP8 markers for any private purposes, either.) + +Keep in mind that at most 65533 bytes can be put into one marker, but you can have as many markers as you like. + +By default, the IJG compression library will write a JFIF APP0 marker if the selected JPEG colorspace is grayscale or YCbCr, or an Adobe APP14 marker if the selected colorspace is RGB, CMYK, or YCCK. You can disable this, but we don't recommend it. The decompression library will recognize JFIF and Adobe markers and will set the JPEG colorspace properly when one is found. + +You can write special markers immediately following the datastream header by calling jpeg_write_marker() after jpeg_start_compress() and before the first call to jpeg_write_scanlines(). When you do this, the markers appear after the SOI and the JFIF APP0 and Adobe APP14 markers (if written), but before all else. Specify the marker type parameter as "JPEG_COM" for COM or "JPEG_APP0 + n" for APPn. (Actually, jpeg_write_marker will let you write any marker type, but we don't recommend writing any other kinds of marker.) For example, to write a user comment string pointed to by comment_text: + + * jpeg_write_marker(cinfo, JPEG_COM, comment_text, strlen(comment_text)); +If it's not convenient to store all the marker data in memory at once, you can instead call jpeg_write_m_header() followed by multiple calls to jpeg_write_m_byte(). If you do it this way, it's your responsibility to call jpeg_write_m_byte() exactly the number of times given in the length parameter to jpeg_write_m_header(). (This method lets you empty the output buffer partway through a marker, which might be important when using a suspending data destination module. In any case, if you are using a suspending destination, you should flush its buffer after inserting any special markers. See "I/O suspension".) + +Or, if you prefer to synthesize the marker byte sequence yourself, you can just cram it straight into the data destination module. + +If you are writing JFIF 1.02 extension markers (thumbnail images), don't forget to set cinfo.JFIF_minor_version = 2 so that the encoder will write the correct JFIF version number in the JFIF header marker. The library's default is to write version 1.01, but that's wrong if you insert any 1.02 extension markers. (We could probably get away with just defaulting to 1.02, but there used to be broken decoders that would complain about unknown minor version numbers. To reduce compatibility risks it's safest not to write 1.02 unless you are actually using 1.02 extensions.) + +When reading, two methods of handling special markers are available: 1. You can ask the library to save the contents of COM and/or APPn markers into memory, and then examine them at your leisure afterwards. 2. You can supply your own routine to process COM and/or APPn markers on-the-fly as they are read. The first method is simpler to use, especially if you are using a suspending data source; writing a marker processor that copes with input suspension is not easy (consider what happens if the marker is longer than your available input buffer). However, the second method conserves memory since the marker data need not be kept around after it's been processed. + +For either method, you'd normally set up marker handling after creating a decompression object and before calling jpeg_read_header(), because the markers of interest will typically be near the head of the file and so will be scanned by jpeg_read_header. Once you've established a marker handling method, it will be used for the life of that decompression object (potentially many datastreams), unless you change it. Marker handling is determined separately for COM markers and for each APPn marker code. + +To save the contents of special markers in memory, call + + * jpeg_save_markers(cinfo, marker_code, length_limit) +where marker_code is the marker type to save, JPEG_COM or JPEG_APP0+n. (To arrange to save all the special marker types, you need to call this routine 17 times, for COM and APP0-APP15.) If the incoming marker is longer than length_limit data bytes, only length_limit bytes will be saved; this parameter allows you to avoid chewing up memory when you only need to see the first few bytes of a potentially large marker. If you want to save all the data, set length_limit to 0xFFFF; that is enough since marker lengths are only 16 bits. As a special case, setting length_limit to 0 prevents that marker type from being saved at all. (That is the default behavior, in fact.) + +After jpeg_read_header() completes, you can examine the special markers by following the cinfo->marker_list pointer chain. All the special markers in the file appear in this list, in order of their occurrence in the file (but omitting any markers of types you didn't ask for). Both the original data length and the saved data length are recorded for each list entry; the latter will not exceed length_limit for the particular marker type. Note that these lengths exclude the marker length word, whereas the stored representation within the JPEG file includes it. (Hence the maximum data length is really only 65533.) + +It is possible that additional special markers appear in the file beyond the SOS marker at which jpeg_read_header stops; if so, the marker list will be extended during reading of the rest of the file. This is not expected to be common, however. If you are short on memory you may want to reset the length limit to zero for all marker types after finishing jpeg_read_header, to ensure that the max_memory_to_use setting cannot be exceeded due to addition of later markers. + +The marker list remains stored until you call jpeg_finish_decompress or jpeg_abort, at which point the memory is freed and the list is set to empty. (jpeg_destroy also releases the storage, of course.) + +Note that the library is internally interested in APP0 and APP14 markers; if you try to set a small nonzero length limit on these types, the library will silently force the length up to the minimum it wants. (But you can set a zero length limit to prevent them from being saved at all.) Also, in a 16-bit environment, the maximum length limit may be constrained to less than 65533 by malloc() limitations. It is therefore best not to assume that the effective length limit is exactly what you set it to be. + +If you want to supply your own marker-reading routine, you do it by calling jpeg_set_marker_processor(). A marker processor routine must have the signature + + * boolean jpeg_marker_parser_method (j_decompress_ptr cinfo) +Although the marker code is not explicitly passed, the routine can find it in cinfo->unread_marker. At the time of call, the marker proper has been read from the data source module. The processor routine is responsible for reading the marker length word and the remaining parameter bytes, if any. Return TRUE to indicate success. (FALSE should be returned only if you are using a suspending data source and it tells you to suspend. See the standard marker processors in jdmarker.c for appropriate coding methods if you need to use a suspending data source.) + +If you override the default APP0 or APP14 processors, it is up to you to recognize JFIF and Adobe markers if you want colorspace recognition to occur properly. We recommend copying and extending the default processors if you want to do that. (A better idea is to save these marker types for later examination by calling jpeg_save_markers(); that method doesn't interfere with the library's own processing of these markers.) + +jpeg_set_marker_processor() and jpeg_save_markers() are mutually exclusive --- if you call one it overrides any previous call to the other, for the particular marker type specified. + +A simple example of an external COM processor can be found in djpeg.c. Also, see jpegtran.c for an example of using jpeg_save_markers. + + +### Raw (downsampled) image data + +Some applications need to supply already-downsampled image data to the JPEG compressor, or to receive raw downsampled data from the decompressor. The library supports this requirement by allowing the application to write or read raw data, bypassing the normal preprocessing or postprocessing steps. The interface is different from the standard one and is somewhat harder to use. If your interest is merely in bypassing color conversion, we recommend that you use the standard interface and simply set jpeg_color_space = in_color_space (or jpeg_color_space = out_color_space for decompression). The mechanism described in this section is necessary only to supply or receive downsampled image data, in which not all components have the same dimensions. + +To compress raw data, you must supply the data in the colorspace to be used in the JPEG file (please read the earlier section on Special color spaces) and downsampled to the sampling factors specified in the JPEG parameters. You must supply the data in the format used internally by the JPEG library, namely a JSAMPIMAGE array. This is an array of pointers to two-dimensional arrays, each of type JSAMPARRAY. Each 2-D array holds the values for one color component. This structure is necessary since the components are of different sizes. If the image dimensions are not a multiple of the MCU size, you must also pad the data correctly (usually, this is done by replicating the last column and/or row). The data must be padded to a multiple of a DCT block in each component: that is, each downsampled row must contain a multiple of 8 valid samples, and there must be a multiple of 8 sample rows for each component. (For applications such as conversion of digital TV images, the standard image size is usually a multiple of the DCT block size, so that no padding need actually be done.) + +The procedure for compression of raw data is basically the same as normal compression, except that you call jpeg_write_raw_data() in place of jpeg_write_scanlines(). Before calling jpeg_start_compress(), you must do the following: + + * Set cinfo->raw_data_in to TRUE. (It is set FALSE by jpeg_set_defaults().) + * This notifies the library that you will be supplying raw data. + * Ensure jpeg_color_space is correct --- an explicit jpeg_set_colorspace() + * call is a good idea. Note that since color conversion is bypassed, in_color_space is ignored, except that jpeg_set_defaults() uses it to choose the default jpeg_color_space setting. + * Ensure the sampling factors, cinfo->comp_info[i].h_samp_factor and + * cinfo->comp_info[i].v_samp_factor, are correct. Since these indicate the dimensions of the data you are supplying, it's wise to set them explicitly, rather than assuming the library's defaults are what you want. +To pass raw data to the library, call jpeg_write_raw_data() in place of jpeg_write_scanlines(). The two routines work similarly except that jpeg_write_raw_data takes a JSAMPIMAGE data array rather than JSAMPARRAY. The scanlines count passed to and returned from jpeg_write_raw_data is measured in terms of the component with the largest v_samp_factor. + +jpeg_write_raw_data() processes one MCU row per call, which is to say v_samp_factor*DCTSIZE sample rows of each component. The passed num_lines value must be at least max_v_samp_factor*DCTSIZE, and the return value will be exactly that amount (or possibly some multiple of that amount, in future library versions). This is true even on the last call at the bottom of the image; don't forget to pad your data as necessary. + +The required dimensions of the supplied data can be computed for each component as + + * cinfo->comp_info[i].width_in_blocks*DCTSIZE samples per row cinfo->comp_info[i].height_in_blocks*DCTSIZE rows in image +after jpeg_start_compress() has initialized those fields. If the valid data is smaller than this, it must be padded appropriately. For some sampling factors and image sizes, additional dummy DCT blocks are inserted to make the image a multiple of the MCU dimensions. The library creates such dummy blocks itself; it does not read them from your supplied data. Therefore you need never pad by more than DCTSIZE samples. An example may help here. Assume 2h2v downsampling of YCbCr data, that is + + * cinfo->comp_info[0].h_samp_factor = 2 for Y cinfo->comp_info[0].v_samp_factor = 2 cinfo->comp_info[1].h_samp_factor = 1 for Cb cinfo->comp_info[1].v_samp_factor = 1 cinfo->comp_info[2].h_samp_factor = 1 for Cr cinfo->comp_info[2].v_samp_factor = 1 +and suppose that the nominal image dimensions (cinfo->image_width and cinfo->image_height) are 101x101 pixels. Then jpeg_start_compress() will compute downsampled_width = 101 and width_in_blocks = 13 for Y, downsampled_width = 51 and width_in_blocks = 7 for Cb and Cr (and the same for the height fields). You must pad the Y data to at least 13*8 = 104 columns and rows, the Cb/Cr data to at least 7*8 = 56 columns and rows. The MCU height is max_v_samp_factor = 2 DCT rows so you must pass at least 16 scanlines on each call to jpeg_write_raw_data(), which is to say 16 actual sample rows of Y and 8 each of Cb and Cr. A total of 7 MCU rows are needed, so you must pass a total of 7*16 = 112 "scanlines". The last DCT block row of Y data is dummy, so it doesn't matter what you pass for it in the data arrays, but the scanlines count must total up to 112 so that all of the Cb and Cr data gets passed. + +Output suspension is supported with raw-data compression: if the data destination module suspends, jpeg_write_raw_data() will return 0. In this case the same data rows must be passed again on the next call. + +Decompression with raw data output implies bypassing all postprocessing: you cannot ask for rescaling or color quantization, for instance. More seriously, you must deal with the color space and sampling factors present in the incoming file. If your application only handles, say, 2h1v YCbCr data, you must check for and fail on other color spaces or other sampling factors. The library will not convert to a different color space for you. + +To obtain raw data output, set cinfo->raw_data_out = TRUE before jpeg_start_decompress() (it is set FALSE by jpeg_read_header()). Be sure to verify that the color space and sampling factors are ones you can handle. Then call jpeg_read_raw_data() in place of jpeg_read_scanlines(). The decompression process is otherwise the same as usual. + +jpeg_read_raw_data() returns one MCU row per call, and thus you must pass a buffer of at least max_v_samp_factor*DCTSIZE scanlines (scanline counting is the same as for raw-data compression). The buffer you pass must be large enough to hold the actual data plus padding to DCT-block boundaries. As with compression, any entirely dummy DCT blocks are not processed so you need not allocate space for them, but the total scanline count includes them. The above example of computing buffer dimensions for raw-data compression is equally valid for decompression. + +Input suspension is supported with raw-data decompression: if the data source module suspends, jpeg_read_raw_data() will return 0. You can also use buffered-image mode to read raw data in multiple passes. + + +### Really raw data: DCT coefficients + +It is possible to read or write the contents of a JPEG file as raw DCT coefficients. This facility is mainly intended for use in lossless transcoding between different JPEG file formats. Other possible applications include lossless cropping of a JPEG image, lossless reassembly of a multi-strip or multi-tile TIFF/JPEG file into a single JPEG datastream, etc. + +To read the contents of a JPEG file as DCT coefficients, open the file and do jpeg_read_header() as usual. But instead of calling jpeg_start_decompress() and jpeg_read_scanlines(), call jpeg_read_coefficients(). This will read the entire image into a set of virtual coefficient-block arrays, one array per component. The return value is a pointer to an array of virtual-array descriptors. Each virtual array can be accessed directly using the JPEG memory manager's access_virt_barray method (see Memory management, below, and also read structure.doc's discussion of virtual array handling). Or, for simple transcoding to a different JPEG file format, the array list can just be handed directly to jpeg_write_coefficients(). + +Each block in the block arrays contains quantized coefficient values in normal array order (not JPEG zigzag order). The block arrays contain only DCT blocks containing real data; any entirely-dummy blocks added to fill out interleaved MCUs at the right or bottom edges of the image are discarded during reading and are not stored in the block arrays. (The size of each block array can be determined from the width_in_blocks and height_in_blocks fields of the component's comp_info entry.) This is also the data format expected by jpeg_write_coefficients(). + +When you are done using the virtual arrays, call jpeg_finish_decompress() to release the array storage and return the decompression object to an idle state; or just call jpeg_destroy() if you don't need to reuse the object. + +If you use a suspending data source, jpeg_read_coefficients() will return NULL if it is forced to suspend; a non-NULL return value indicates successful completion. You need not test for a NULL return value when using a non-suspending data source. + +It is also possible to call jpeg_read_coefficients() to obtain access to the decoder's coefficient arrays during a normal decode cycle in buffered-image mode. This frammish might be useful for progressively displaying an incoming image and then re-encoding it without loss. To do this, decode in buffered- image mode as discussed previously, then call jpeg_read_coefficients() after the last jpeg_finish_output() call. The arrays will be available for your use until you call jpeg_finish_decompress(). + +To write the contents of a JPEG file as DCT coefficients, you must provide the DCT coefficients stored in virtual block arrays. You can either pass block arrays read from an input JPEG file by jpeg_read_coefficients(), or allocate virtual arrays from the JPEG compression object and fill them yourself. In either case, jpeg_write_coefficients() is substituted for jpeg_start_compress() and jpeg_write_scanlines(). Thus the sequence is + + * Create compression object + * Set all compression parameters as necessary + * Request virtual arrays if needed + * jpeg_write_coefficients() + * jpeg_finish_compress() + * Destroy or re-use compression object +jpeg_write_coefficients() is passed a pointer to an array of virtual block array descriptors; the number of arrays is equal to cinfo.num_components. + +The virtual arrays need only have been requested, not realized, before jpeg_write_coefficients() is called. A side-effect of jpeg_write_coefficients() is to realize any virtual arrays that have been requested from the compression object's memory manager. Thus, when obtaining the virtual arrays from the compression object, you should fill the arrays after calling jpeg_write_coefficients(). The data is actually written out when you call jpeg_finish_compress(); jpeg_write_coefficients() only writes the file header. + +When writing raw DCT coefficients, it is crucial that the JPEG quantization tables and sampling factors match the way the data was encoded, or the resulting file will be invalid. For transcoding from an existing JPEG file, we recommend using jpeg_copy_critical_parameters(). This routine initializes all the compression parameters to default values (like jpeg_set_defaults()), then copies the critical information from a source decompression object. The decompression object should have just been used to read the entire JPEG input file --- that is, it should be awaiting jpeg_finish_decompress(). + +jpeg_write_coefficients() marks all tables stored in the compression object as needing to be written to the output file (thus, it acts like jpeg_start_compress(cinfo, TRUE)). This is for safety's sake, to avoid emitting abbreviated JPEG files by accident. If you really want to emit an abbreviated JPEG file, call jpeg_suppress_tables(), or set the tables' individual sent_table flags, between calling jpeg_write_coefficients() and jpeg_finish_compress(). + + +### Progress monitoring + +Some applications may need to regain control from the JPEG library every so often. The typical use of this feature is to produce a percent-done bar or other progress display. (For a simple example, see cjpeg.c or djpeg.c.) Although you do get control back frequently during the data-transferring pass (the jpeg_read_scanlines or jpeg_write_scanlines loop), any additional passes will occur inside jpeg_finish_compress or jpeg_start_decompress; those routines may take a long time to execute, and you don't get control back until they are done. + +You can define a progress-monitor routine which will be called periodically by the library. No guarantees are made about how often this call will occur, so we don't recommend you use it for mouse tracking or anything like that. At present, a call will occur once per MCU row, scanline, or sample row group, whichever unit is convenient for the current processing mode; so the wider the image, the longer the time between calls. During the data transferring pass, only one call occurs per call of jpeg_read_scanlines or jpeg_write_scanlines, so don't pass a large number of scanlines at once if you want fine resolution in the progress count. (If you really need to use the callback mechanism for time-critical tasks like mouse tracking, you could insert additional calls inside some of the library's inner loops.) + +To establish a progress-monitor callback, create a struct jpeg_progress_mgr, fill in its progress_monitor field with a pointer to your callback routine, and set cinfo->progress to point to the struct. The callback will be called whenever cinfo->progress is non-NULL. (This pointer is set to NULL by jpeg_create_compress or jpeg_create_decompress; the library will not change it thereafter. So if you allocate dynamic storage for the progress struct, make sure it will live as long as the JPEG object does. Allocating from the JPEG memory manager with lifetime JPOOL_PERMANENT will work nicely.) You can use the same callback routine for both compression and decompression. + +The jpeg_progress_mgr struct contains four fields which are set by the library: + + * long pass_counter; <span style="display:none">work units completed in this pass</span> long pass_limit; <span style="display:none">total number of work units in this pass</span> int completed_passes; <span style="display:none">passes completed so far</span> int total_passes; <span style="display:none">total number of passes expected</span> +During any one pass, pass_counter increases from 0 up to (not including) pass_limit; the step size is usually but not necessarily 1. The pass_limit value may change from one pass to another. The expected total number of passes is in total_passes, and the number of passes already completed is in completed_passes. Thus the fraction of work completed may be estimated as + + * completed_passes + (pass_counter/pass_limit) +--- + + + + * total_passes +ignoring the fact that the passes may not be equal amounts of work. + +When decompressing, pass_limit can even change within a pass, because it depends on the number of scans in the JPEG file, which isn't always known in advance. The computed fraction-of-work-done may jump suddenly (if the library discovers it has overestimated the number of scans) or even decrease (in the opposite case). It is not wise to put great faith in the work estimate. + +When using the decompressor's buffered-image mode, the progress monitor work estimate is likely to be completely unhelpful, because the library has no way to know how many output passes will be demanded of it. Currently, the library sets total_passes based on the assumption that there will be one more output pass if the input file end hasn't yet been read (jpeg_input_complete() isn't TRUE), but no more output passes if the file end has been reached when the output pass is started. This means that total_passes will rise as additional output passes are requested. If you have a way of determining the input file size, estimating progress based on the fraction of the file that's been read will probably be more useful than using the library's value. + + +### Memory management + +This section covers some key facts about the JPEG library's built-in memory manager. For more info, please read structure.doc's section about the memory manager, and consult the source code if necessary. + +All memory and temporary file allocation within the library is done via the memory manager. If necessary, you can replace the "back end" of the memory manager to control allocation yourself (for example, if you don't want the library to use malloc() and free() for some reason). + +Some data is allocated "permanently" and will not be freed until the JPEG object is destroyed. Most data is allocated "per image" and is freed by jpeg_finish_compress, jpeg_finish_decompress, or jpeg_abort. You can call the memory manager yourself to allocate structures that will automatically be freed at these times. Typical code for this is + + * ptr = (*cinfo->mem->alloc_small) ((j_common_ptr) cinfo, JPOOL_IMAGE, size); +Use JPOOL_PERMANENT to get storage that lasts as long as the JPEG object. Use alloc_large instead of alloc_small for anything bigger than a few Kbytes. There are also alloc_sarray and alloc_barray routines that automatically build 2-D sample or block arrays. + +The library's minimum space requirements to process an image depend on the image's width, but not on its height, because the library ordinarily works with "strip" buffers that are as wide as the image but just a few rows high. Some operating modes (eg, two-pass color quantization) require full-image buffers. Such buffers are treated as "virtual arrays": only the current strip need be in memory, and the rest can be swapped out to a temporary file. + +If you use the simplest memory manager back end (jmemnobs.c), then no temporary files are used; virtual arrays are simply malloc()'d. Images bigger than memory can be processed only if your system supports virtual memory. The other memory manager back ends support temporary files of various flavors and thus work in machines without virtual memory. They may also be useful on Unix machines if you need to process images that exceed available swap space. + +When using temporary files, the library will make the in-memory buffers for its virtual arrays just big enough to stay within a "maximum memory" setting. Your application can set this limit by setting cinfo->mem->max_memory_to_use after creating the JPEG object. (Of course, there is still a minimum size for the buffers, so the max-memory setting is effective only if it is bigger than the minimum space needed.) If you allocate any large structures yourself, you must allocate them before jpeg_start_compress() or jpeg_start_decompress() in order to have them counted against the max memory limit. Also keep in mind that space allocated with alloc_small() is ignored, on the assumption that it's too small to be worth worrying about; so a reasonable safety margin should be left when setting max_memory_to_use. + +If you use the jmemname.c or jmemdos.c memory manager back end, it is important to clean up the JPEG object properly to ensure that the temporary files get deleted. (This is especially crucial with jmemdos.c, where the "temporary files" may be extended-memory segments; if they are not freed, DOS will require a reboot to recover the memory.) Thus, with these memory managers, it's a good idea to provide a signal handler that will trap any early exit from your program. The handler should call either jpeg_abort() or jpeg_destroy() for any active JPEG objects. A handler is not needed with jmemnobs.c, and shouldn't be necessary with jmemansi.c or jmemmac.c either, since the C library is supposed to take care of deleting files made with tmpfile(). + + +### Memory usage + +Working memory requirements while performing compression or decompression depend on image dimensions, image characteristics (such as colorspace and JPEG process), and operating mode (application-selected options). + +As of v6b, the decompressor requires: + +1. About 24K in more-or-less-fixed-size data. This varies a bit depending + * on operating mode and image characteristics (particularly color vs. grayscale), but it doesn't depend on image dimensions. +1. Strip buffers (of size proportional to the image width) for IDCT and + * upsampling results. The worst case for commonly used sampling factors is about 34 bytes * width in pixels for a color image. A grayscale image only needs about 8 bytes per pixel column. +1. A full-image DCT coefficient buffer is needed to decode a multi-scan JPEG + * file (including progressive JPEGs), or whenever you select buffered-image mode. This takes 2 bytes/coefficient. At typical 2x2 sampling, that's 3 bytes per pixel for a color image. Worst case (1x1 sampling) requires 6 bytes/pixel. For grayscale, figure 2 bytes/pixel. +1. To perform 2-pass color quantization, the decompressor also needs a + * 128K color lookup table and a full-image pixel buffer (3 bytes/pixel). +This does not count any memory allocated by the application, such as a buffer to hold the final output image. + +The above figures are valid for 8-bit JPEG data precision and a machine with 32-bit ints. For 12-bit JPEG data, double the size of the strip buffers and quantization pixel buffer. The "fixed-size" data will be somewhat smaller with 16-bit ints, larger with 64-bit ints. Also, CMYK or other unusual color spaces will require different amounts of space. + +The full-image coefficient and pixel buffers, if needed at all, do not have to be fully RAM resident; you can have the library use temporary files instead when the total memory usage would exceed a limit you set. (But if your OS supports virtual memory, it's probably better to just use jmemnobs and let the OS do the swapping.) + +The compressor's memory requirements are similar, except that it has no need for color quantization. Also, it needs a full-image DCT coefficient buffer if Huffman-table optimization is asked for, even if progressive mode is not requested. + +If you need more detailed information about memory usage in a particular situation, you can enable the MEM_STATS code in jmemmgr.c. + + +### Library compile-time options + +A number of compile-time options are available by modifying jmorecfg.h. + +The JPEG standard provides for both the baseline 8-bit DCT process and a 12-bit DCT process. The IJG code supports 12-bit lossy JPEG if you define BITS_IN_JSAMPLE as 12 rather than 8. Note that this causes JSAMPLE to be larger than a char, so it affects the surrounding application's image data. The sample applications cjpeg and djpeg can support 12-bit mode only for PPM and GIF file formats; you must disable the other file formats to compile a 12-bit cjpeg or djpeg. (install.doc has more information about that.) At present, a 12-bit library can handle *only* 12-bit images, not both precisions. (If you need to include both 8- and 12-bit libraries in a single application, you could probably do it by defining NEED_SHORT_EXTERNAL_NAMES for just one of the copies. You'd have to access the 8-bit and 12-bit copies from separate application source files. This is untested ... if you try it, we'd like to hear whether it works!) + +Note that a 12-bit library always compresses in Huffman optimization mode, in order to generate valid Huffman tables. This is necessary because our default Huffman tables only cover 8-bit data. If you need to output 12-bit files in one pass, you'll have to supply suitable default Huffman tables. You may also want to supply your own DCT quantization tables; the existing quality-scaling code has been developed for 8-bit use, and probably doesn't generate especially good tables for 12-bit. + +The maximum number of components (color channels) in the image is determined by MAX_COMPONENTS. The JPEG standard allows up to 255 components, but we expect that few applications will need more than four or so. + +On machines with unusual data type sizes, you may be able to improve performance or reduce memory space by tweaking the various typedefs in jmorecfg.h. In particular, on some RISC CPUs, access to arrays of "short"s is quite slow; consider trading memory for speed by making JCOEF, INT16, and UINT16 be "int" or "unsigned int". UINT8 is also a candidate to become int. You probably don't want to make JSAMPLE be int unless you have lots of memory to burn. + +You can reduce the size of the library by compiling out various optional functions. To do this, undefine xxx_SUPPORTED symbols as necessary. + +You can also save a few K by not having text error messages in the library; the standard error message table occupies about 5Kb. This is particularly reasonable for embedded applications where there's no good way to display a message anyway. To do this, remove the creation of the message table (jpeg_std_message_table[]) from jerror.c, and alter format_message to do something reasonable without it. You could output the numeric value of the message code number, for example. If you do this, you can also save a couple more K by modifying the TRACEMSn() macros in jerror.h to expand to nothing; you don't need trace capability anyway, right? + + +### Portability considerations + +The JPEG library has been written to be extremely portable; the sample applications cjpeg and djpeg are slightly less so. This section summarizes the design goals in this area. (If you encounter any bugs that cause the library to be less portable than is claimed here, we'd appreciate hearing about them.) + +The code works fine on ANSI C, C++, and pre-ANSI C compilers, using any of the popular system include file setups, and some not-so-popular ones too. See install.doc for configuration procedures. + +The code is not dependent on the exact sizes of the C data types. As distributed, we make the assumptions that + + * char is at least 8 bits wide short is at least 16 bits wide int is at least 16 bits wide long is at least 32 bits wide +(These are the minimum requirements of the ANSI C standard.) Wider types will work fine, although memory may be used inefficiently if char is much larger than 8 bits or short is much bigger than 16 bits. The code should work equally well with 16- or 32-bit ints. + +In a system where these assumptions are not met, you may be able to make the code work by modifying the typedefs in jmorecfg.h. However, you will probably have difficulty if int is less than 16 bits wide, since references to plain int abound in the code. + +char can be either signed or unsigned, although the code runs faster if an unsigned char type is available. If char is wider than 8 bits, you will need to redefine JOCTET and/or provide custom data source/destination managers so that JOCTET represents exactly 8 bits of data on external storage. + +The JPEG library proper does not assume ASCII representation of characters. But some of the image file I/O modules in cjpeg/djpeg do have ASCII dependencies in file-header manipulation; so does cjpeg's select_file_type() routine. + +The JPEG library does not rely heavily on the C library. In particular, C stdio is used only by the data source/destination modules and the error handler, all of which are application-replaceable. (cjpeg/djpeg are more heavily dependent on stdio.) malloc and free are called only from the memory manager "back end" module, so you can use a different memory allocator by replacing that one file. + +The code generally assumes that C names must be unique in the first 15 characters. However, global function names can be made unique in the first 6 characters by defining NEED_SHORT_EXTERNAL_NAMES. + +More info about porting the code may be gleaned by reading jconfig.doc, jmorecfg.h, and jinclude.h. + + +### Notes for MS-DOS implementors + +The IJG code is designed to work efficiently in 80x86 "small" or "medium" memory models (i.e., data pointers are 16 bits unless explicitly declared "far"; code pointers can be either size). You may be able to use small model to compile cjpeg or djpeg by itself, but you will probably have to use medium model for any larger application. This won't make much difference in performance. You *will* take a noticeable performance hit if you use a large-data memory model (perhaps 10%-25%), and you should avoid "huge" model if at all possible. + +The JPEG library typically needs 2Kb-3Kb of stack space. It will also malloc about 20K-30K of near heap space while executing (and lots of far heap, but that doesn't count in this calculation). This figure will vary depending on selected operating mode, and to a lesser extent on image size. There is also about 5Kb-6Kb of constant data which will be allocated in the near data segment (about 4Kb of this is the error message table). Thus you have perhaps 20K available for other modules' static data and near heap space before you need to go to a larger memory model. The C library's static data will account for several K of this, but that still leaves a good deal for your needs. (If you are tight on space, you could reduce the sizes of the I/O buffers allocated by jdatasrc.c and jdatadst.c, say from 4K to 1K. Another possibility is to move the error message table to far memory; this should be doable with only localized hacking on jerror.c.) + +About 2K of the near heap space is "permanent" memory that will not be released until you destroy the JPEG object. This is only an issue if you save a JPEG object between compression or decompression operations. + +Far data space may also be a tight resource when you are dealing with large images. The most memory-intensive case is decompression with two-pass color quantization, or single-pass quantization to an externally supplied color map. This requires a 128Kb color lookup table plus strip buffers amounting to about 40 bytes per column for typical sampling ratios (eg, about 25600 bytes for a 640-pixel-wide image). You may not be able to process wide images if you have large data structures of your own. + +Of course, all of these concerns vanish if you use a 32-bit flat-memory-model compiler, such as DJGPP or Watcom C. We highly recommend flat model if you can use it; the JPEG library is significantly faster in flat model. diff --git a/Software/liblazy.mdwn b/Software/liblazy.mdwn new file mode 100644 index 00000000..114a4503 --- /dev/null +++ b/Software/liblazy.mdwn @@ -0,0 +1,16 @@ + + +# What is liblazy all about? + +Liblazy is a simple and easy to use library that provides convenient functions for sending messages over the D-Bus daemon, querying information from [[HAL|Software/hal]] or asking [[PolicyKit|PolicyKit]] for a privilege. Its features may grow as needed, though. + +Get [[liblazy 0.2|http://people.freedesktop.org/~homac/liblazy/liblazy-0.2.tar.bz2]] + +Older versions: + +* - [[liblazy 0.1|http://people.freedesktop.org/~homac/liblazy/liblazy-0.1.tar.bz2]] +The API documentation can be found [[here|http://people.freedesktop.org/~homac/liblazy/autodocs]] + +For latest and greatest source code, use the following command to checkout: + +` git clone git://anongit.freedesktop.org/git/liblazy ` diff --git a/Software/libopenraw.mdwn b/Software/libopenraw.mdwn new file mode 100644 index 00000000..5a304e68 --- /dev/null +++ b/Software/libopenraw.mdwn @@ -0,0 +1,76 @@ + +See [[http://libopenraw.freedesktop.org/|http://libopenraw.freedesktop.org/]] for up to date information. + + + +--- + + + +libopenraw is an ongoing project to provide a free software implementation for camera RAW files decoding. One of the main reason is that [[dcraw|http://www.cybercom.net/~dcoffin/dcraw/]] is not suited for easy integration into applications, and there is a need for an easy to use API to build free software digital image processing application. + +It also has the goal to address missing feature from [[dcraw|http://www.cybercom.net/~dcoffin/dcraw/]] like meta-data decoding and easy thumbnail extraction. + + +# Status + +This is currently a work in progress. The only code available is in git. Once a release will be made, it will be announced here. + + +# Planned feature + +* Support for as much file format as possible. NEF, CRW, CR2 and DNG obviously as they are the most common (well DNG not really but it is "standard"). +* Modular low level API that allow: + * Identify the file + * Parse the file + * Extract the meta-data and the previews + * Allow processing the RAW data in different way, including having them extracted for an application custom processor. +* High level API that allow: + * Provide and standard thumbnail - **Done** + * Preprocess the file using standard parameters + * Extract the metadata as EXIF (and XMP) + * Convert to a DNG file + +# Plans + +* Get a basic thumbnail extractor for CR2, CRW, DNG, NEF, ORF - **Done** +* Get a basic metadata extractor for CR2, CRW, DNG, NEF, ORF +* Get a basic RAW processor for CR2, CRW, DNG, NEF, ORF + +# Getting code from git + + * Anonymous git + * `git clone git://anongit.freedesktop.org/git/libopenraw.git` + * For developers (needs authorization). + * Get a username if you don't have one: See [[http://www.freedesktop.org/wiki/AccountRequests|http://www.freedesktop.org/wiki/AccountRequests]] for details. + * Check out the tree: `git clone git+ssh://git.freedesktop.org/git/libopenraw.git` + +# Links to documentation + +Given how manufacturer document these formats, we have to reverse-engineer or use documentation issued from reverse engineering. + + +## Implementation + +* [[dcraw|http://www.cybercom.net/~dcoffin/dcraw/]] the current reference implementation for RAW decoding. +* [[jrawio|http://www.tidalwave.it/infoglueDeliverLive/ViewPage.action?siteNodeId=180&languageId=1&contentId=206]] a Java library that implements RAW image decoding + +## File format + +* [[RAW file standards|http://www.rags-int-inc.com/PhotoTechStuff/RawStandards/]] try to match current standard with currently undocumented file formats and its [[summary|http://www.rags-int-inc.com/PhotoTechStuff/RawStandards/RawSummary.html]]. +* [[TIFF|http://partners.adobe.com/public/developer/tiff/index.html]] on which DNG and apparently other RAW format are based on. +* [[Adobe DNG|http://www.adobe.com/products/dng/main.html]] a "standard" format that Adobe tries to push. +* [[X3F Foveon|http://www.x3f.info/spp/v2_1/english.html#Format]], the Foveon partial documentation. +* [[MRW Minolta RAW|http://www.dalibor.cz/minolta/raw_file_format.htm]] +* [[RAWpository|http://www.glasslantern.com/RAWpository/]] archive of sample image data in RAW formats + +## Metadata + +TBD + +-- [[HubertFiguiere|HubertFiguiere]] + + +## Communication + +There is mailing list for developers available now. Visit [[http://lists.freedesktop.org/mailman/listinfo/libopenraw-dev|http://lists.freedesktop.org/mailman/listinfo/libopenraw-dev]] to subscribe diff --git a/Software/libspectre.mdwn b/Software/libspectre.mdwn new file mode 100644 index 00000000..8d4ea906 --- /dev/null +++ b/Software/libspectre.mdwn @@ -0,0 +1,53 @@ + + +## Latest news + +* 2012-08-08 [[libspectre 0.2.7|http://libspectre.freedesktop.org/releases/libspectre-0.2.7.tar.gz]] released! +* 2010-06-10 [[libspectre 0.2.6|http://libspectre.freedesktop.org/releases/libspectre-0.2.6.tar.gz]] released! +* 2010-04-18 [[libspectre 0.2.5|http://libspectre.freedesktop.org/releases/libspectre-0.2.5.tar.gz]] released! +* 2010-02-21 [[libspectre 0.2.4|http://libspectre.freedesktop.org/releases/libspectre-0.2.4.tar.gz]] released! +* 2009-10-18 [[libspectre 0.2.3|http://libspectre.freedesktop.org/releases/libspectre-0.2.3.tar.gz]] released! +* 2008-11-25 [[libspectre 0.2.2|http://libspectre.freedesktop.org/releases/libspectre-0.2.2.tar.gz]] released! +* 2008-08-10 [[libspectre 0.2.1|http://libspectre.freedesktop.org/releases/libspectre-0.2.1.tar.gz]] released! +* 2008-01-03 [[libspectre 0.2.0|http://libspectre.freedesktop.org/releases/libspectre-0.2.0.tar.gz]] released! +* 2007-12-16 [[libspectre 0.1.0|http://libspectre.freedesktop.org/releases/libspectre-0.1.0.tar.gz]] released! + +## What is libspectre + +libspectre is a small library for rendering Postscript documents. It provides a convenient easy to use API for handling and rendering Postscript documents. + +libspectre it's known to work on UNIX/Linux systems although supporting other platforms (win32, macos) is planned too. Any help on this is, of course, more than welcome :-) + +libspectre is free software and is available to be redistributed and/or modified under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version. + + +## Dependencies + +libspectre depends on libgs which is available at [[Ghostscript website|http://www.ghostscript.com]] + + +## Download + + +### Releases + +The latest release is [[libspectre 0.2.7|http://libspectre.freedesktop.org/releases/libspectre-0.2.7.tar.gz]]. + +Previous releases can be found in the [[release archive|http://libspectre.freedesktop.org/releases]]. + + +### In-Progress Development + +libspectre is maintained with the [[git|http://git.or.cz/]] version control system. You may browse the source online using the [[web|http://cgit.freedesktop.org/libspectre]]. + +You may also use git to clone a local copy of the libspectre source code. + + git clone git://anongit.freedesktop.org/git/libspectre + +## Documentation + +* [[API reference manual|http://libspectre.freedesktop.org/manual]] + +## Contact + +Use the [[freedesktop bugzilla|https://bugs.freedesktop.org/]] to report bugs or suggest enhancements. The product is libspectre. diff --git a/Software/libvisio.mdwn b/Software/libvisio.mdwn new file mode 100644 index 00000000..caf99351 --- /dev/null +++ b/Software/libvisio.mdwn @@ -0,0 +1,57 @@ +# libvisio import filter library + +Libvisio is library providing ability to interpret and import visio diagrams into various applications. You can find it being used in libreoffice. + +[[!toc ]] + + +# Developers + + +## Getting the sources + +libvisio sources are stored in [[git|http://git-scm.com/]]. To get them, you can use: + + git clone git://anongit.freedesktop.org/git/libreoffice/contrib/libvisio/ + +or you can browse the code [[online|http://cgit.freedesktop.org/libreoffice/contrib/libvisio/]]. + +If you want to use release version you can fetch it from [[libreoffice mirror|http://dev-www.libreoffice.org/src/]]. + + +## Building it + + +### Dependencies + +You will need these applications in order to compile libvisio: + + >=libwpd-0.9 + >=libwpg-0.2 + doxygen # optional for documentation building (--with-docs) + +Once the source has been checked out, libvisio can be built in usual manner: + + cd libvisio + ./autogen.sh + ./configure + make + make install + + +## Contributing + +Once you have done a change that you are happy with, and that builds with libvisio, contribute it back, we'll be happy to integrate it! Do: + + # commit your changes to your local repository + git commit -a + # create the patch + git format-patch origin/master + +# Contact + +You can get in touch with us using multiple ways: + +1. using IRC server **irc.freenode.net** and joining channel **#libreoffice-dev** +1. using mailinglist **[[libreoffice@lists.freedesktop.org|mailto:libreoffice@lists.freedesktop.org]]** +1. filling bugreport in [[Freedesktop bugzilla|http://bugs.freedesktop.org/]] diff --git a/Software/media-player-info.mdwn b/Software/media-player-info.mdwn new file mode 100644 index 00000000..0c2e21c4 --- /dev/null +++ b/Software/media-player-info.mdwn @@ -0,0 +1,51 @@ + + +# media-player-info + +media-player-info is a repository of data files describing media player capabilities, mostly of mass-storage devices. These files contain information about the directory layout to use to add music to these devices, the supported file formats and so on. + +These capabilities used to be provided by [[HAL|Software/hal]] in the 10-usb-music-players.fdi file, but HAL is now [[deprecated|http://lists.freedesktop.org/archives/hal/2008-May/011560.html]], so the information is being provided as a separate package. + + +## Download + +The latest release can be downloaded from the [[FreeDesktop.org software repository|http://www.freedesktop.org/software/media-player-info/]]. + +Development happens in [[git|GettingInvolved]]. There is a [[web interface|http://cgit.freedesktop.org/media-player-info/]] to the repository. + + +## Mailing List + +The [[DevKit-devel|http://lists.freedesktop.org/mailman/listinfo/devkit-devel]] mailing list is where everything happens. + + +## Helping Out + + +### New devices + +If you have access to a device that should be part of media-player-info, but isn't, [[report a bug|https://bugs.freedesktop.org/enter_bug.cgi?product=media-player-info]] (and set the Component to "New device"). + +You'll need to provide some information for this to be useful: + +* The UDev information - this can be obtained with udevadm: + * First run `udevadm monitor` and plug in your device. You should be able to determine the sysfs device path from this (something like `/devices/pci0000:00/0000:00:1d.7/usb2/2-3`). + * Then use `udevadm info` to get the UDev information, and attach this to your bug report. eg: `udevadm info --query=all --path=/devices/pci0000:00/0000:00:1d.7/usb2/2-3`. +* The maker of the product (eg: "Sony"). +* The name of the product (eg: "Walkman NWD-B105"). +* How the device can be accessed (generally "storage" - this means you can mount it) +* The formats it can deal with - both those it can record, if it is capable of recording, and those it can play. +* Any playlist formats it understands, and where those playlists should be placed on the device. +* Any information on the folder structures (eg: does music go in a "Music/" folder and audio books in "AudioBooks/"?). +* Whether the device needs to be ejected (rather than just unmounted). +* The maximum folder depth, if there is a limit. + +### Bugs + +If there is an error in media-player-info, [[report a bug|https://bugs.freedesktop.org/enter_bug.cgi?product=media-player-info]]. Please include the output of `udevadm info` where relevant (see above). + + + +--- + + [[CategoryHalReplacement|CategoryHalReplacement]] diff --git a/Software/pkg-config.mdwn b/Software/pkg-config.mdwn new file mode 100644 index 00000000..406058f0 --- /dev/null +++ b/Software/pkg-config.mdwn @@ -0,0 +1,21 @@ + + +# pkg-config + +pkg-config is a helper tool used when compiling applications and libraries. It helps you insert the correct compiler options on the command line so an application can use ` gcc -o test test.c `pkg-config --libs --cflags glib-2.0` ` for instance, rather than hard-coding values on where to find glib (or other libraries). It is language-agnostic, so it can be used for defining the location of documentation tools, for instance. + +The program is free software and licensed under the [[GPL|http://www.gnu.org/licenses/gpl.html]] version 2 or any later version (at your option). + +pkg-config works on multiple platforms: Linux and other UNIX-like operating systems, Mac OS X and Windows. It does not require anything but a reasonably well working C compiler and a C library, but can use an installed glib if that is present. (A copy of recent glib2 is shipped together with pkg-config versions since 0.27, and this is sufficient for pkg-config to compile and work properly.) + +The first implementation was written in shell, by James Henstridge. Later, it was rewritten in C by Havoc Pennington. It also grew an autoconf macro written by Tim Janik, later rewritten by Scott James Remnant. The current maintainers are [[Tollef Fog Heen <tfheen@err.no>|mailto:tfheen@err.no]] and [[Dan Nicholson <dbn.lists@gmail.com>|mailto:dbn.lists@gmail.com]]. + +The current release of pkg-config is version 0.27 and can be found in [[/releases|http://pkgconfig.freedesktop.org/releases/]]. + +pkg-config is available from the [[git|http://git-scm.com/]] repository at git://anongit.freedesktop.org/pkg-config + +Bugs can be filed in the [[Freedesktop.org bug tracker|https://bugs.freedesktop.org/enter_bug.cgi]] + +There is a mailing list for development and user questions at [[pkg-config@lists.freedesktop.org|mailto:pkg-config@lists.freedesktop.org]] [[(Archives)|http://lists.freedesktop.org/archives/pkg-config/]] [[(Subscribe)|http://lists.freedesktop.org/mailman/listinfo/pkg-config]] + +New and veteran users alike may find [[Dan Nicholson’s Guide to pkg-config|http://people.freedesktop.org/~dbn/pkg-config-guide.html]] informative, particularly [[the FAQ section|http://people.freedesktop.org/~dbn/pkg-config-guide.html#faq]] which provides examples of where the `Requires.private` field is appropriate. diff --git a/Software/pkg-config/CrossCompileProposal.mdwn b/Software/pkg-config/CrossCompileProposal.mdwn new file mode 100644 index 00000000..3dc709ae --- /dev/null +++ b/Software/pkg-config/CrossCompileProposal.mdwn @@ -0,0 +1,108 @@ + + +# Cross Compiling With pkg-config + +This document summarises the proposal for adding cross compilation support to `pkg-config`. Some people currently cross compile with `pkg-config`, but it requires knowledge of extra `pkg-config` specific environment variables. + +Related to cross compiling, it would also be nice if `pkg-config` supported bi-arch and multi-arch systems better. + + +## Current Support + +The `pkg-config` tool works with a collection of `.pc` files that describe available packages for linking. These files are located using the following rules: + +* searching directories listed in `$PKG_CONFIG_PATH` +* when `$PKG_CONFIG_LIBDIR` is specified, it will override the compiled in default directory (e.g. `/usr/lib/pkgconfig`) and the PKG_CONFIG_PATH. +Note that when specifying PKG_CONFIG_LIBDIR, pkg-config will completely ignore the content in PKG_CONFIG_PATH, even if the documentation states different things. + +In a cross compile situation, some `.pc` files on the system will be for the build machine and some will be for the target machine. In order to make sure that the build machine's `.pc` files are not found, both the `$PKG_CONFIG_PATH` and `$PKG_CONFIG_PATH` environment variables must be set to directories containing only target machine `.pc files. + +The same is true in a bi-arch/multi-arch setup. + + +## Proposed Changes + +The following changes are based on discussions with Wolfgang Wieser (most of the ideas are originally his). + + +### A new --host option + +In order for `pkg-config` to be smart about picking what `.pc` files to use, it needs to know the what it is targetting. The proposed solution to this is to add a `--host` option to the program with the following behaviour: + +* takes a string representation of the target machine as an argument +* defaults to a compiled in default determined when `pkg-config` was built. +The `PKG_PROG_PKG_CONFIG` autoconf macro would be modified to pass this argument to `pkg-config`. The code would be something like this: + + * [[!format txt """ +AC_REQUIRE([AC_CANONICAL_HOST]) +... find pkg-config ... +PKG_CHECK_EXISTS([pkg-config >= 0.XXX], + [pkgconfig_supports_host=true], + [pkgconfig_supports_host=false]) +if $pkgconfig_supports_host; then + PKG_CONFIG="$PKG_CONFIG --host $host" +fi +"""]] +(where `0.XXX` is the first version that supports the `--host` option). + + +#### Host Strings + +The `$host` string produced by autoconf comes from one of two places: + +* the result of `config.guess` +* if the user passes `--host` to `configure`, then that string is passed through `config.sub` to canonicalise it +These strings are of the form `CPU-VENDOR-OS` where `OS` is either `SYSTEM` or `KERNEL-SYSTEM`. + +Not all of the information in this string is relevant, so we will need to do some canonicalisation too: + +* On a i686 Linux system, `config.guess` outputs `i686-pc-linux-gnu`. On an i586, we get `i586-pc-linux-gnu` even if the two systems have an identical set of libraries installed. +* Some vendors might insert their name into the host string of some executables they produce. For instance `config.guess` outputs `x86_64-unknown-linux-gnu` on AMD64 machines, yet some programs on Fedora are configured as `x86_64-redhat-linux-gnu`. +So the canonicalisation would need to be some combination of: + +* canonicalise compatible architectures +* drop vendor +* drop `SYSTEM` when `KERNEL` is given? + +### Identifying Host Type for .pc Files + +Two possible ways of identifying what host type a particular `.pc` file is for are: + +* place `.pc` files in host type specific subdirectories. `pkg-config` then searches these host-specific subdirectories before the base directories when processing the search path. +* add a `Host:` header to `.pc` files giving the host type they are for. +I favour the first solution. + +This leaves the question of what to do with `.pc` files for which we can't determine the architecture. There are a few things to consider here: + +1. **Treat them as belonging to the default host type**. This is almost definitely the right choice for things in the default search path. Would break current cross-compile practices to do this for stuff in `$PKG_CONFIG_PATH` (this might be acceptable). +1. **Files in `/usr/share/pkgconfig`**. Newer versions of `pkg-config` add this directory to the default search path. For the multi-arch case, these files should be used in all cases. For cross-compile, perhaps these should be ignored. +The most compatible solution seems to be to always include files in the base dirs of `$PKG_CONFIG_PATH`, but use different default search paths for different host types. + + +### Default Search Path + +A lot of multi-arch and cross-compile problems can be avoided by being a bit smarter about the default search path. With the help of the `--host` option, it should finally be possible to do this. For instance, on an AMD64 bi-arch box, the following would be the appropriate: + + * [[!table header="no" class="mointable" data=""" + **host type** | **default path** + `x86_64-linux` | `/usr/lib64/pkgconfig`, `/usr/share/pkgconfig` + `i386-linux` | `/usr/lib/pkgconfig`, `/usr/share/pkgconfig` + _other_ | _nothing_ +"""]] + +This would generally do the right thing when configuring packages for the two architectures the machine supports, and when cross compiling to another system the default search path would not interfere. + +This could either be configured as a table compiled into the `pkg-config` executable, or as an external config file (given `pkg-config` doesn't have a config file currently, it might be better to compile it in). + + +### Package Changes + +For the most part, packages that only search for installed `pkg-config` packages would not need any major modifications -- they would just need to regenerate their configure script with the updated macros so that `--host` gets passed through to `pkg-config`. + +For packages that want to install `.pc` files, they will need to be modified in order to install the `.pc` files in the right host-specific subdirectory. It should be possible to wrap the logic for determining the subdirectory inside an autoconf macro (it would probably need to ask `pkg-config` what the canonical form of the host string is). + + +## References + +* [[LSB multi-arch ideas|http://www.linuxbase.org/futures/ideas/multiarch/]] (not standardised) +* [[Debian multi-arch status|http://people.debian.org/~taggart/multiarch/]]
\ No newline at end of file diff --git a/Software/pkgconfig.mdwn b/Software/pkgconfig.mdwn new file mode 100644 index 00000000..2eaf52b9 --- /dev/null +++ b/Software/pkgconfig.mdwn @@ -0,0 +1,7 @@ + + +## pkg-config + +pkg-config is a system for managing library compile/link flags that works with automake and autoconf. It replaces the ubiquitous *-config scripts you may have seen with a single tool. There's nothing desktop-specific or desktop-related about pkg-config, despite it being on freedesktop.org. + +The pkg-config web page has been moved to [[http://pkgconfig.freedesktop.org/wiki/|http://pkgconfig.freedesktop.org/wiki/]]. diff --git a/Software/pyxdg.mdwn b/Software/pyxdg.mdwn new file mode 100644 index 00000000..fa72324d --- /dev/null +++ b/Software/pyxdg.mdwn @@ -0,0 +1,139 @@ + + +## PyXDG + +PyXDG is a python library to access freedesktop.org standards. Currently supported are: + +* Base Directory Specification Version 0.6 +* Menu Specification Version 1.0 +* Desktop Entry Specification Version 1.0 +* Icon Theme Specification Version 0.8 +* Recent File Spec 0.2 +* Shared-MIME-Database Specification 0.13 +[[Documentation on ReadTheDocs|http://pyxdg.readthedocs.org/en/latest/index.html]] + + +### Development + +Development takes place in [[a git repository|http://cgit.freedesktop.org/xdg/pyxdg/]], with a [[Github mirror|https://github.com/takluyver/pyxdg]]. Freedesktop.org hosts the [[bug tracker|https://bugs.freedesktop.org/buglist.cgi?product=PyXDG&component=PyXDG&resolution=---&list_id=97030]]. + +[[[[!img http://travis-ci.org/#!/takluyver/pyxdg]|http://travis-ci.org/#!/takluyver/pyxdg]] + + +### Download + +* [[pyxdg-0.25.tar.gz|http://people.freedesktop.org/~takluyver/pyxdg-0.25.tar.gz]] ([[pgp|http://people.freedesktop.org/~takluyver/pyxdg-0.25.tar.gz.asc]]; December 2012) + * Add support for $XDG_RUNTIME_DIR, Debian bug #656338. + * Allow desktop entry files that are not encoded in UTF-8, Debian bug #693855. + * Mime: Add support for subclasses and aliases. +* [[pyxdg-0.24.tar.gz|http://people.freedesktop.org/~takluyver/pyxdg-0.24.tar.gz]] ([[pgp|http://people.freedesktop.org/~takluyver/pyxdg-0.24.tar.gz.asc]]; October 2012) + * Update allowed [[DesktopEntry|DesktopEntry]] categories following changes to the specification. + * Fix removal of empty submenu, freedesktop bug #54747. + * Documentation is now available on RTD: [[http://pyxdg.readthedocs.org/|http://pyxdg.readthedocs.org/]] + * A few more tests, and some code cleanup. + * Fix failure to parse some menu files when kde-config is missing, freedesktop bug #56426. +* [[pyxdg-0.23.tar.gz|http://people.freedesktop.org/~takluyver/pyxdg-0.23.tar.gz]] ([[pgp|http://people.freedesktop.org/~takluyver/pyxdg-0.23.tar.gz.asc]]; July 2012) + * Fix a test for non-UTF-8 locales. +* [[pyxdg-0.22.tar.gz|http://people.freedesktop.org/~takluyver/pyxdg-0.22.tar.gz]] ([[pgp|http://people.freedesktop.org/~takluyver/pyxdg-0.22.tar.gz.asc]]; July 2012) + * Better unicode handling in several modules. + * Fix for sorting non-ASCII menu entries, [[freedesktop bug #52492|https://bugs.freedesktop.org/show_bug.cgi?id=52492]]. + * More tests. +* [[pyxdg-0.21.tar.gz|http://people.freedesktop.org/~takluyver/pyxdg-0.21.tar.gz]] ([[pgp|http://people.freedesktop.org/~takluyver/pyxdg-0.21.tar.gz.asc]]; July 2012) + * Tests can now be run conveniently using nosetests, and cover more of the code. + * BaseDirectory: New `save_cache_path()` function, [[freedesktop bug #26458|https://bugs.freedesktop.org/show_bug.cgi?id=26458]]. + * Config: Default icon theme is 'hicolor', not 'highcolor', [[freedesktop bug #29294|https://bugs.freedesktop.org/show_bug.cgi?id=29294]]. + * Menu: Obsolete `Rule.compile()` method removed. + * DesktopEntry: Corrected spelling of `checkCategories()` method, [[freedesktop bug #24974|https://bugs.freedesktop.org/show_bug.cgi?id=24974]]. + * DesktopEntry: Consider `Actions` and `Keywords` keys standard. + * DesktopEntry: Accept non-ASCII Keywords. + * DesktopEntry: Update list of environments valid for `OnlyShowIn`. + * Mime: Fix `get_type_by_contents()` in Python 3. + * RecentFiles: Minor bug fixes. +* [[pyxdg-0.20.tar.gz|http://people.freedesktop.org/~takluyver/pyxdg-0.20.tar.gz]] (June 2012) + * Compatible with Python 3; requires Python 2.6 or later + * Clean up accidental GPL license notice in Menu.py + * Add test scripts for xdg.Mime, xdg.Locale and xdg.RecentFiles + * Fixes for icon theme validation + * Fix exception in xdg.Mime + * Replace invalid string exceptions + * Fall back to default base directories if $XDG* environment variables are set but empty. + * Remove use of deprecated os.popen3 in Menu.py + * Correct URLs in README +* [[pyxdg-0.19.tar.gz|http://www.freedesktop.org/~lanius/pyxdg-0.19.tar.gz]] + * `IniFile.py`: add support for trusted desktop files (thanks to karl mikaelsson) + * `DesktopEntry.py`: Support spec version 1.0, Debian bug #563660 + * `MimeType.py`: Fix parsing of in memory data, Debian bug #563718 + * `DesktopEntry.py`: Fix constructor, Debian bug #551297, #562951, #562952 +* [[pyxdg-0.18.tar.gz|http://www.freedesktop.org/~lanius/pyxdg-0.18.tar.gz]] + * `DesktopEntry.py`: Add getMimeTypes() method, correctly returning strings + * `DesktopEntry.py`: Deprecated getMimeType() returning list of regex (AdamB) + * `Menu.py`: Add support for XDG_MENU_PREFIX (Piotr Lewandowski) + * `Mime.py`: Add get_type_by_contents() (Tony Houghton) +* [[pyxdg-0.17.tar.gz|http://www.freedesktop.org/~lanius/pyxdg-0.17.tar.gz]] + * Bugfixes around +* [[pyxdg-0.16.tar.gz|http://www.freedesktop.org/~lanius/pyxdg-0.16.tar.gz]] + * Bugfixes around +* [[pyxdg-0.15.tar.gz|http://www.freedesktop.org/~lanius/pyxdg-0.15.tar.gz]] + * `Menu.py`: Bugfixes, support for `TryExec` + * `MenuEditor.py`: Bugfixes, pretty output for applications.menu + * `IconTheme.py`: Performance improvements, Bugfixes +* [[pyxdg-0.14.tar.gz|http://www.freedesktop.org/~lanius/pyxdg-0.14.tar.gz]] + * `Menu.py`, `MenuEditor.py`: Bugfixes +* [[pyxdg-0.13.tar.gz|http://www.freedesktop.org/~lanius/pyxdg-0.13.tar.gz]] + * `Menu.py`, `MenuEditor.py`: Bugfixes... + * `Config.py`: Add root_mode +* [[pyxdg-0.12.tar.gz|http://www.freedesktop.org/~lanius/pyxdg-0.12.tar.gz]] + * `MenuEditor.py`: New in this release, use to edit Menus + * `Menu.py`, `IniFile.py`, `DesktopEntry.py`: Lot of bugfixing... + * `BaseDirectory.py`: Add xdg_cache_home + * `IconTheme.py`, `Config.py`: More caching stuff, make cachetime configurable + * thx to Travis Watkins <[[alleykat@gmail.com|mailto:alleykat@gmail.com]]> and Matt Kynaston <[[mattkyn@gmail.com|mailto:mattkyn@gmail.com]]> for their help +* [[pyxdg-0.11.tar.gz|http://www.freedesktop.org/~lanius/pyxdg-0.11.tar.gz]] + * `Config.py`: Module to configure Basic Settings, currently available: + * Locale, `IconTheme`, `IconSize`, `WindowManager` + * `Locale.py`: Internal Module to support Locales + * `Mime.py`: Implementation of the Mime Specification + * `Menu.py`: Now supports `LegacyDirs` + * `RecentFiles.py`:Implementation of the Recent Files Specification + * A lot of bugfixes, thx to Travis Watkins <[[alleykat@gmail.com|mailto:alleykat@gmail.com]]> +* [[pyxdg-0.10.tar.gz|http://www.freedesktop.org/~lanius/pyxdg-0.10.tar.gz]] + * various bugfixes + * validate against menu-spec-1.0.draft-1 +* [[pyxdg-0.9.tar.gz|http://www.freedesktop.org/~lanius/pyxdg-0.9.tar.gz]] + * various bugfixes + * various performance improvements + * validate against menu-spec-0.91 + * thx to Matt Kynaston <[[mattkyn@gmail.com|mailto:mattkyn@gmail.com]]> for some suggestions +* [[pyxdg-0.8.tar.gz|http://www.freedesktop.org/~lanius/pyxdg-0.8.tar.gz]] + * `xdg/IconTheme.py` (getIconPath): The "hicolor" theme has to be used as the fallback. + * `xdg/IniFile.py` ([[IniFile|IniFile]].getList): Fixed bug in splitting up strings. + * Don't read .desktop-* files, only .desktop + * Add . to the literal `FileExtensions` so that the checks work. + * thx to + * Martin Grimme ([[martin@pycage.de|mailto:martin@pycage.de]]) + * Ross Burton ([[ross@burtonini.com|mailto:ross@burtonini.com]]) +* pyxdg-0.7.tar.gz + * add 'import codecs' to `IniFile`, needed by write support + * Fix parsing of lists with only one entry +* pyxdg-0.6.tar.gz + * Performance Improvements +* pyxdg-0.5.tar.gz + * License change to LGPL + * Support for write operations in `IniFile` + * Support for menu-spec-0.7 + * Validates `OnlyShowIn` and Categories + * Performance improvements (e.g. 5 times faster in menu parsing) + * A lot of bugfixes (e.g. `IconTheme` parsing) + * Python 2.3 support +* pyxdg-0.4.tar.gz + * Bugfix release +* pyxdg-0.3.tar.gz + * Basedir Spec updated to version 0.6 + * First part of separating Desktop Entry backend in `IniFile` + * added getPath(...) function to `Menu.py` + * Complete Icon Theme Spec implementation, including cache and validation +* pyxdg-0.2.tar.gz + * Rewrite of Menu Spec code + * Use Basedir Spec code from ROX +* pyxdg-0.1.tar.gz + * Initial release.
\ No newline at end of file diff --git a/Software/sbox2.mdwn b/Software/sbox2.mdwn new file mode 100644 index 00000000..0eec3373 --- /dev/null +++ b/Software/sbox2.mdwn @@ -0,0 +1,5 @@ + + +## Scratchbox 2 + +[[New Home of SB2 at gitorius|http://maemo.gitorious.org/scratchbox2]] diff --git a/Software/scim.mdwn b/Software/scim.mdwn new file mode 100644 index 00000000..e3efde29 --- /dev/null +++ b/Software/scim.mdwn @@ -0,0 +1,109 @@ + +[[http://www.freedesktop.org/software/scim/scim_logo_new02_50.png|http://www.freedesktop.org/software/scim/scim_logo_new02_50.png]] + + +## This site is un-maintained + +Please refer to our [[new site|http://www.scim-im.org]]. + + +### Introduction + +If you don't know what SCIM is, please read [[the introduction|Software/ScimIntroduction]]. + + +### What's New + +You can find the news of SCIM and related projects on [[the news page|Software/ScimNews]]. + + +### Support Language List + +You can find what language support and some more info from SCIM on [[the supported language list|Software/ScimSupportLanguage]]. + + +### Mailing List + +All discussion about SCIM is currently on [[scim@lists.freedesktop.org|http://lists.freedesktop.org/mailman/listinfo/scim]]. + +Please send your questions, bug reports, suggestions or ideas to this list. If you are sending questions or [[bug reports|http://sourceforge.net/tracker/?group_id=108454&atid=650539]], please read [[these guidelines|Software/ScimReportBug]]. + + +### Bugs Tracking System + +You can report bugs at [[SF's bug tracking system|http://sourceforge.net/tracker/?group_id=108454&atid=650539]]. Please select appropriate category (component) and group (version), and supply [[as much information as possible|Software/ScimReportBug]]. If you are not sure which component the bug you encounter belongs to, just select the default "none". In addition, please follow [[these guidelines|Software/ScimReportBug]]. + + +### Download + +You can download SCIM source and binary packages from [[download page|Software/ScimDownload]]. If you want to try out the latest SCIM code, please see the [[SCIM's CVS page|http://savannah.nongnu.org/cvs/?group=scim]]. You can also browse the source code [[online|http://savannah.nongnu.org/cgi-bin/viewcvs/scim/]]. + +The _module_name_ can be `scim-lib`, `scim-tables`, `scim-chinese`, `scim-uim`, `scim-m17n` or `skim`. + + +### Screen Shots + +Some [[screenshots|Software/ScimScreenShots]] of of SCIM. + + +### Install + +If you want to install SCIM from source code, you may read the [[install page|Software/ScimInstall]]. + + +### Roadmap + +Roadmap (future plan) for SCIM can be found [[here|Software/ScimRoadmap]]. + + +### Start using SCIM + + * [[SCIM User's Manual in Simplified Chinese|http://freedesktop.org/~suzhe/manual/zh_CN/user-manual.html]] + * [[Linux Internationalization HOWTO|http://home.no.net/david/i18n.php]] - mainly about input method (written by David Oftedal) + * [[Internationalization in Mandrakelinux 10.1|http://www.h4.dion.ne.jp/~apricots/mandrake/miniguide.html]] - a mini guide of SCIM and UIM (by Yukiko BANDO) + * [[SCIM/skim German manual for SuSE Linux 9.1|http://www.chinaboard.de/skim]] - Chinese under !SuSE Linux 9.1 with skim (by Jan Hefti) + +### Developer documents + + * [[API Reference|http://freedesktop.org/~suzhe/manual/api/index.html]] (Generated by Doxygen) + +### Sub Projects + + * [[skim|Software/ScimKDE]] - An input method based on SCIM library and KDE/QT. + * [[scim-chinese|Software/ScimChinese]] - Currently contains a Smart Pinyin IMEngine for Simplified Chinese. + * [[scim-tables|Software/ScimTables]] - Contains many table based input methods. + * [[scim-uim|Software/ScimUim]] - A wrapper to use uim as an IMEngine of SCIM. + * [[scim-m17n|Software/ScimM17N]] - A wrapper to use m17n library as an IMEngine of SCIM. + * [[scim-qtimm|Software/ScimQtImm]] - Qt-immodule support for scim. + * [[scim-hangul|Software/ScimHangul]] - A Hangul !IMEngine which is ported from imhangul project. + * [[scim-python|Software/ScimPython]] - A python language binding for SCIM. + +### Ideas for SCIM + +Please write down here what you want to see in a future version of SCIM on [[the ideas page|Software/ScimIdeas]]. Any idea to improve usability or just give it a nice look and feel? + + +### Howto Contribute + +We are always welcome and appreciate any contributes, including but not limited to bug fix patch, art design (including logo, icons etc) and translation. If you would like to give a hand, please say so in our [[mailing list|http://freedesktop.org/mailman/listinfo/scim]]. Following, you would find some guidelines for contribution. + + * [[How to Translate SCIM to My Language?|Software/ScimHowtoTranslate]] + * [[How to create a new IME on Linux in about 15 minutes with SCIM and m17n?|Software/ScimSupportLanguageNewM17n]] + * [[How to create a new IME in about 15 minutes with SCIM and scim-tables?|Software/ScimSupportLanguageNewTable]] + +### Links + +Some [[links|Software/ScimLinks]] about SCIM or releted projects/articles. + + +### Developers and contributors + + * [[JamesSu|JamesSu]]: Core developer, project maintainer + * [[JanHefti|JanHefti]]: Doc writer and German translator + * [[KitaeKim|KitaeKim]]: Art designer and Korean translator + * [[LiuCougar|LiuCougar]]: Developer focused on KDE/Qt related support + * [[YukikoBando|YukikoBando]]: Japanese translator +-- [[LiuCougar|LiuCougar]] - 11 Oct 2004 + + + diff --git a/Software/shared-mime-info.mdwn b/Software/shared-mime-info.mdwn new file mode 100644 index 00000000..cecd768c --- /dev/null +++ b/Software/shared-mime-info.mdwn @@ -0,0 +1,69 @@ + +The shared-mime-info package contains the core database of common types and the *update-mime-database* command used to extend it. It requires glib2 to be installed for building the update command. Additionally, it uses intltool for translations, though this is only a dependency for the maintainers. This database is translated at [[Transifex|http://www.transifex.net/projects/p/shared-mime-info/]]. + +See the [[Shared MIME Info Specification|Specifications/shared-mime-info-spec]] for more information about the database. + + +# git + +The [[git|GettingInvolved]] module for this spec is "shared-mime-info", in the "mime" repository. See [[web interface|http://cgit.freedesktop.org/xdg/shared-mime-info/]] for details + + +# Obtain + + +## Sources + + * [[shared-mime-info-1.1.tar.xz|http://freedesktop.org/~hadess/shared-mime-info-1.1.tar.xz]]. + * [[shared-mime-info-1.0.tar.xz|http://freedesktop.org/~hadess/shared-mime-info-1.0.tar.xz]]. + * [[shared-mime-info-0.91.tar.xz|http://freedesktop.org/~hadess/shared-mime-info-0.91.tar.xz]]. + * [[shared-mime-info-0.90.tar.bz2|http://freedesktop.org/~hadess/shared-mime-info-0.90.tar.bz2]]. + * [[shared-mime-info-0.80.tar.bz2|http://freedesktop.org/~hadess/shared-mime-info-0.80.tar.bz2]]. + * [[shared-mime-info-0.71.tar.bz2|http://freedesktop.org/~hadess/shared-mime-info-0.71.tar.bz2]]. + * [[shared-mime-info-0.70.tar.bz2|http://freedesktop.org/~hadess/shared-mime-info-0.70.tar.bz2]]. + * [[shared-mime-info-0.60.tar.bz2|http://freedesktop.org/~hadess/shared-mime-info-0.60.tar.bz2]]. + * [[shared-mime-info-0.51.tar.bz2|http://freedesktop.org/~hadess/shared-mime-info-0.51.tar.bz2]]. + * [[shared-mime-info-0.50.tar.bz2|http://freedesktop.org/~hadess/shared-mime-info-0.50.tar.bz2]]. + * [[shared-mime-info-0.40.tar.bz2|http://freedesktop.org/~hadess/shared-mime-info-0.40.tar.bz2]]. + * [[shared-mime-info-0.30.tar.bz2|http://freedesktop.org/~hadess/shared-mime-info-0.30.tar.bz2]]. + * [[shared-mime-info-0.23.tar.bz2|http://freedesktop.org/~hadess/shared-mime-info-0.23.tar.bz2]]. + * [[shared-mime-info-0.22.tar.bz2|http://freedesktop.org/~hadess/shared-mime-info-0.22.tar.bz2]]. + * [[shared-mime-info-0.21.tar.bz2|http://freedesktop.org/~hadess/shared-mime-info-0.21.tar.bz2]]. + * [[shared-mime-info-0.20.tar.bz2|http://freedesktop.org/~hadess/shared-mime-info-0.20.tar.bz2]]. + * [[shared-mime-info-0.19.tar.gz|http://freedesktop.org/~hadess/shared-mime-info-0.19.tar.gz]]. + * [[shared-mime-info-0.18.tar.gz|http://freedesktop.org/~hadess/shared-mime-info-0.18.tar.gz]]. + * [[shared-mime-info-0.17.tar.gz|http://freedesktop.org/~hadess/shared-mime-info-0.17.tar.gz]]. + * [[shared-mime-info-0.16.tar.gz|http://freedesktop.org/~hadess/shared-mime-info-0.16.tar.gz]]. + * [[shared-mime-info-0.15.tar.gz|http://freedesktop.org/software/shared-mime-info/shared-mime-info-0.15.tar.gz]]. + * [[shared-mime-info-0.14.tar.gz|http://freedesktop.org/software/shared-mime-info/shared-mime-info-0.14.tar.gz]]. + * [[shared-mime-info-0.13.tar.gz|http://freedesktop.org/software/shared-mime-info/shared-mime-info-0.13.tar.gz]]. + * [[shared-mime-info-0.12.tar.gz|http://freedesktop.org/software/shared-mime-info/releases/shared-mime-info-0.12.tar.gz]]. GPG signature: [[tar.gz.sig|http://freedesktop.org/software/shared-mime-info/releases/shared-mime-info-0.12.tar.gz.sig]]. + +## Distribution-specific packages + + * Debian: packaged as [[shared-mime-info|http://packages.debian.org/shared-mime-info]]. + * FreeBSD: packaged in [[FreeBSD ports|http://www.freebsd.org/ports/misc.html]]. + * Gentoo Linux: [[package|http://packages.gentoo.org/packages/?category=x11-misc;name=shared-mime-info]]. + * OpenBSD: packaged in [[OpenBSD ports|http://www.openbsd.org/cgi-bin/cvsweb/ports/misc/shared-mime-info/]]. + * Slackware: [[unofficial packages|http://home.att.net/~psantoro/]] + * Arch Linux: [[package|http://www.archlinux.org/packages/shared-mime-info/]] in the "extra" repository. + * Lunar Linux: in the [[moonbase module|http://modules.lunar-linux.org/index.php?option=module&module=shared-mime-info]]. + +### RPMs + + * [[Mandriva RPMs in Cooker|http://wiki.mandriva.com/]] (choose a mirror, then go to media/main/release). + * [[PLD Linux Distribution official packages|ftp://ftp.i686.ac.pld-linux.org/dists/ac/PLD/i686/PLD/RPMS/]] + * SuSE RPMs: [[packman.links2linux.de|http://packman.links2linux.de/?action=311]]. + * Fedora RPMs: [[Fedora official packages|http://koji.fedoraproject.org/koji/packageinfo?packageID=408]]. + +# Bug tracker + + * [[Bugzilla|https://bugs.freedesktop.org/buglist.cgi?query_format=specific&order=relevance+desc&bug_status=__open__&product=shared-mime-info&content=]] + + + + + + + + diff --git a/Software/startup-notification.mdwn b/Software/startup-notification.mdwn new file mode 100644 index 00000000..b6d880ed --- /dev/null +++ b/Software/startup-notification.mdwn @@ -0,0 +1,47 @@ + + +## startup-notification + +startup-notification contains a reference implementation of the startup notification protocol. The reference implementation is mostly under an X Window System style license, and has no special dependencies. + +This library does not yet make ABI guarantees, but may at some point in the future. + + +### Git + +The [[git|GettingInvolved]] project for this spec is "startup-notification". + +You can check out the code by cloning git://anongit.freedesktop.org/git/ or [[browse the repository online|http://cgit.freedesktop.org/startup-notification/]]. + + +### Download + +* [[startup-notification-0.12.tar.gz|http://www.freedesktop.org/software/startup-notification/releases/startup-notification-0.12.tar.gz]] + * Revert a change that breaks the ABI (Julien Cristau) +* [[startup-notification-0.11.tar.gz|http://www.freedesktop.org/software/startup-notification/releases/startup-notification-0.11.tar.gz]] + * Replace Xlib backend by x11-xcb (Julien Danjou) + * Support APPLICATION_ID key (Colin Walters) +* [[startup-notification-0.10.tar.gz|http://www.freedesktop.org/software/startup-notification/releases/startup-notification-0.10.tar.gz]] + * Add XCB backend (Julien Danjou) +* [[startup-notification-0.9.tar.bz2|http://www.freedesktop.org/software/startup-notification/releases/startup-notification-0.9.tar.bz2]] + * Plug some leaks (Vincent Untz, Aivars Kalvans) + * Fix compilation on sun machines (Laszlo Peter) +* [[startup-notification-0.8.tar.gz|http://www.freedesktop.org/software/startup-notification/releases/startup-notification-0.8.tar.gz]] + * Support new focus stealing prevention stuff (Elijah Newren) + * Use automake 1.7 (Mark [[McLoughlin|McLoughlin]]) +* [[startup-notification-0.7.tar.gz|http://www.freedesktop.org/software/startup-notification/releases/startup-notification-0.7.tar.gz]] + * Implement timestamp support (Elijah Newren) +* [[startup-notification-0.6.tar.gz|http://www.freedesktop.org/software/startup-notification/releases/startup-notification-0.6.tar.gz]] + * Fix some fairly serious memory leaks (Tommi Leino) + * Cygwin build fix (Masahiro Sakai) +* [[startup-notification-0.5.tar.gz|http://www.freedesktop.org/software/startup-notification/releases/startup-notification-0.5.tar.gz]] + * Fix use of uninitialized memory when closing down a display (Joe Marcus Clarke) + * Make xmessage handling use per-display instead of global variables, + * fixing total hosage on multihead X servers + * set _NET_STARTUP_ID as a UTF-8 string + * fix a crash caused by zero-length message data + * include startup-notification.txt specification in the distribution +* [[startup-notification-0.4.tar.gz|http://www.freedesktop.org/software/startup-notification/releases/startup-notification-0.4.tar.gz]] + * Some API extensions that proved useful. +* [[startup-notification-0.3.tar.gz|http://www.freedesktop.org/software/startup-notification/releases/startup-notification-0.3.tar.gz]] + * Initial package.
\ No newline at end of file diff --git a/Software/sysconfig.mdwn b/Software/sysconfig.mdwn new file mode 100644 index 00000000..9f1ae633 --- /dev/null +++ b/Software/sysconfig.mdwn @@ -0,0 +1,44 @@ +## sysadmin project + + +### Modules + +* There are two modules right now. +* tinderclient - these are the client scripts for running tinderboxes. +* tinderbox3 - these are the server cgi-bin scripts for tinderbox. + +### Released Packages + +[[The tinderbox client scripts|http://freedesktop.org/~jg/tinderclient/]]. + + +### CVS + +You can either use your freedesktop.org account and SSH or use anonymous CVS with: + + $ cvs -d :pserver:anoncvs@cvs.freedesktop.org:/cvs/sysadmin login + CVS password: <hit return> + $ cvs -d :pserver:anoncvs@cvs.freedesktop.org:/cvs/sysadmin co <module> + +Browse CVS with [[View CVS|http://cvs.freedesktop.org/sysadmin/]]. +### Bugzilla + +Each module has space in the [[freedesktop.org bugzilla|https://bugs.freedesktop.org/index.cgi]]. + + +### Projects + +Information about fd.o's tinderboxes can be found in the [[TinderboxWiki|Software/TinderboxWiki]]. + + +### Mailing List + +Discussion about these libraries should occur on the [[Release Wrangler's mailing list|http://www.freedesktop.org/mailman/listinfo/release-wranglers]]. + + +### State of the sysadmin projects + +* The initial version of the tinderbox server is installed. +* The initial version of the tinderbox script is also available. Lots of additional features could/should be added. + +-- Main.[[JimGettys]] - 09 Mar 2004 diff --git a/Software/systemd.mdwn b/Software/systemd.mdwn new file mode 100644 index 00000000..49d90aa5 --- /dev/null +++ b/Software/systemd.mdwn @@ -0,0 +1,83 @@ +[[!img screenshot.png]] + +# systemd System and Service Manager + +What is this? + +* `systemd` is a system and service manager for Linux, compatible with SysV and LSB init scripts. `systemd` provides aggressive parallelization capabilities, uses socket and D-Bus activation for starting services, offers on-demand starting of daemons, keeps track of processes using Linux control groups, supports snapshotting and restoring of the system state, maintains mount and automount points and implements an elaborate transactional dependency-based service control logic. It can work as a drop-in replacement for sysvinit. See [[Lennart's blog story|http://0pointer.de/blog/projects/systemd.html]] for a longer introduction, and the [[three|http://0pointer.de/blog/projects/systemd-update.html]] [[status|http://0pointer.de/blog/projects/systemd-update-2.html]] [[updates|http://0pointer.de/blog/projects/systemd-update-3.html]] since then. Also see the [[Wikipedia article|http://en.wikipedia.org/wiki/Systemd]]. If you are wondering whether systemd is for you, please have a look [[at this comparison of init systems by one of the creators of systemd|http://0pointer.de/blog/projects/why.html]]. + +License: + +* This program is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. + +Spelling: + +* Yes, it is written **systemd**, not **system D** or **System D**, or even **SystemD**. And it isn't **system d** either. Why? Because it's a system daemon, and under Unix/Linux those are in lower case, and get suffixed with a lower case **d**. And since systemd manages the system, it's called systemd. It's that simple. But then again, if all that appears too simple to you, call it (but never spell it!) **System Five Hundred** since **D** is the roman numeral for 500 (this also clarifies the relation to System V, right?). The only situation where we find it OK to use an uppercase letter in the name (but don't like it either) is if you start a sentence with **systemd**. On high holidays you may also spell it _sÿstëmd_. But then again, _[[Système D|https://secure.wikimedia.org/wikipedia/en/wiki/System_D]]_ is not an acceptable spelling and something completely different (though kinda fitting). + +Plus: + +* [[Follow us on Google+|https://plus.google.com/104232583922197692623]] [[Join our Community on Google+|https://plus.google.com/u/0/communities/114587707547576757881]] + +Hackfests and Sprints: + +* [[systemd Hackfest|https://plus.google.com/events/cnklef88b85tb6tgf6ue3hn32lg]] on **Thu, February 21** and **Fri, February 22 2013** in **Brno**, Czech Republic, colocated with the [[Red Hat Developer Conference 2013|https://plus.google.com/events/c6ugufll8imrv18574ljmmldf9s]] Or [[organize your own|http://www.freedesktop.org/wiki/Software/systemd/hackfests]]! + +Mailing Lists: + +* [[General Development and Discussion Mailing List|http://lists.freedesktop.org/mailman/listinfo/systemd-devel]] [[Commits Mailing List|http://lists.freedesktop.org/mailman/listinfo/systemd-commits]] [[Bugzilla Mailing List|http://lists.freedesktop.org/mailman/listinfo/systemd-bugs]] + +Bug Reports: + +* [[Existing Bug Reports|https://bugs.freedesktop.org/buglist.cgi?query_format=advanced&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&product=systemd]] [[File a New Bug Report|https://bugs.freedesktop.org/enter_bug.cgi?product=systemd]] Also check out various distributions bugtrackers: [[Fedora|https://bugzilla.redhat.com/buglist.cgi?list_id=565273&classification=Fedora&query_format=advanced&bug_status=NEW&bug_status=ASSIGNED&bug_status=MODIFIED&bug_status=ON_DEV&bug_status=ON_QA&bug_status=VERIFIED&bug_status=RELEASE_PENDING&bug_status=POST&component=systemd&product=Fedora]], [[Debian|http://bugs.debian.org/cgi-bin/pkgreport.cgi?ordering=normal;archive=0;src=systemd]], [[openSUSE|https://bugzilla.novell.com/buglist.cgi?short_desc=systemd&field0-0-0=product&type0-0-1=substring&field0-0-1=component&classification=openSUSE&value0-0-2=systemd&query_based_on=systemd&query_format=advanced&type0-0-3=substring&field0-0-3=status_whiteboard&value0-0-3=systemd&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=NEEDINFO&bug_status=REOPENED&short_desc_type=allwordssubstr&field0-0-2=short_desc&value0-0-1=systemd&type0-0-0=substring&value0-0-0=systemd&type0-0-2=substring&known_name=systemd]], [[Mageia|https://bugs.mageia.org/buglist.cgi?field0-0-0=cf_rpmpkg&query_format=advanced&bug_status=NEW&bug_status=UNCONFIRMED&bug_status=ASSIGNED&bug_status=REOPENED&type0-0-0=substring&value0-0-0=systemd&component=RPM%20Packages&product=Mageia]], [[Gentoo|https://bugs.gentoo.org/buglist.cgi?quicksearch=systemd]] + +IRC: + +* [[#systemd on irc.freenode.org|irc://irc.freenode.org/systemd]] + +Download: + +* [[http://www.freedesktop.org/software/systemd/|http://www.freedesktop.org/software/systemd/]] + +And, most importantly, Git: + +* git://anongit.freedesktop.org/systemd/systemd [[ssh://git.freedesktop.org/git/systemd/systemd|ssh://git.freedesktop.org/git/systemd/systemd]] + +Git Web Frontend: + +* [[http://cgit.freedesktop.org/systemd/|http://cgit.freedesktop.org/systemd/]] And the package repositories of the various distributions: [[Fedora|http://pkgs.fedoraproject.org/cgit/systemd.git/tree/]], [[OpenSUSE|https://build.opensuse.org/package/files?package=systemd&project=Base%3ASystem]], [[Mageia|http://svnweb.mageia.org/packages/cauldron/systemd/current/]] + +Continuous Integration: + +* [[Jenkins|http://systemd.getpantheon.com:8080/jenkins/]] + +Publications: + +* [[Article in The H|http://www.h-online.com/open/features/Control-Centre-The-systemd-Linux-init-system-1565543.html]] [[Article in The H, Part 2|http://www.h-online.com/open/features/Booting-up-Tools-and-tips-for-systemd-1570630.html]] [[Bê-á-bá do systemd #1|https://www.ibm.com/developerworks/mydeveloperworks/blogs/752a690f-8e93-4948-b7a3-c060117e8665/entry/systemd_parte_1]], [[#2|https://www.ibm.com/developerworks/mydeveloperworks/blogs/752a690f-8e93-4948-b7a3-c060117e8665/entry/systemd_parte_2]], [[#3|https://www.ibm.com/developerworks/mydeveloperworks/blogs/752a690f-8e93-4948-b7a3-c060117e8665/entry/systemd_parte_3]], [[#4|https://www.ibm.com/developerworks/mydeveloperworks/blogs/752a690f-8e93-4948-b7a3-c060117e8665/entry/systemd_parte_4]], [[#5|https://www.ibm.com/developerworks/mydeveloperworks/blogs/752a690f-8e93-4948-b7a3-c060117e8665/entry/systemd_parte_5]], [[#6|https://www.ibm.com/developerworks/mydeveloperworks/blogs/752a690f-8e93-4948-b7a3-c060117e8665/entry/systemd_parte_6]] (Brazilian Portuguese) [[Évolutions techniques de systemd (French)|https://linuxfr.org/news/%C3%A9volutions-techniques-de-systemd]] + +Manuals and Documentation for Users and Administrators: + +* [[Manual Pages|http://www.freedesktop.org/software/systemd/man/]] [[Tips And Tricks|http://www.freedesktop.org/wiki/Software/systemd/TipsAndTricks]] [[Frequently Asked Questions|http://www.freedesktop.org/wiki/Software/systemd/FrequentlyAskedQuestions]] [[Debugging systemd Problems|http://freedesktop.org/wiki/Software/systemd/Debugging]] [[Incompatibilities with SysV/LSB|http://www.freedesktop.org/wiki/Software/systemd/Incompatibilities]] [[Booting Without /usr is Broken|http://freedesktop.org/wiki/Software/systemd/separate-usr-is-broken]] [[Predictable Network Interface Names|http://www.freedesktop.org/wiki/Software/systemd/PredictableNetworkInterfaceNames]] [[API File Systems|http://www.freedesktop.org/wiki/Software/systemd/APIFileSystems]] [[Running Services After the Network is up|http://www.freedesktop.org/wiki/Software/systemd/NetworkTarget]] [[My Service Can't Get Realtime!|http://www.freedesktop.org/wiki/Software/systemd/MyServiceCantGetRealtime]] [[The 30 Biggest Myths about systemd|http://0pointer.de/blog/projects/the-biggest-myths.html]] + +Videos for Users and Administrators: + +* [[Presentation about the journal at Devconf 2013|https://www.youtube.com/watch?v=i4CACB7paLc]] [[Presentation about recent developments at Devconf 2013|https://www.youtube.com/watch?v=_rrpjYD373A]] [[Presentation about systemd at FOSDEM 2013|http://video.fosdem.org/2013/maintracks/Janson/systemd,_Two_Years_Later.webm]] (Audio is bad 0:29 - 06:12, please seek ahead), [[(Slides)|http://0pointer.de/public/systemd-fosdem2013.pdf]] [[Presentation about systemd at FOSS.in 2012|https://www.youtube.com/watch?v=_2aa34Uzr3c]] [[Presentation about systemd at OSEC Barcamp 2012|https://www.youtube.com/watch?v=9UnEV9SPuw8]] [[Presentation about systemd at FOSDEM 2011|https://www.youtube.com/watch?v=TyMLi8QF6sw]] [[Presentation about systemd at linux.conf.au 2011|http://linuxconfau.blip.tv/file/4696791/]], [[(Slides)|http://0pointer.de/public/systemd-lca2011.pdf]] [[Interview about systemd at golem.de (German)|http://video.golem.de/oss/4823/interview-mit-lennart-poettering-entwickler-systemd.html]] + +The systemd for Administrators Blog Series: + +* [[#1: Verifying Bootup|http://0pointer.de/blog/projects/systemd-for-admins-1.html]] [[#2: Which Service Owns Which Processes?|http://0pointer.de/blog/projects/systemd-for-admins-2.html]] [[#3: How Do I Convert A SysV Init Script Into A systemd Service File?|http://0pointer.de/blog/projects/systemd-for-admins-3.html]] [[#4: Killing Services|http://0pointer.de/blog/projects/systemd-for-admins-4.html]] [[#5: The Three Levels of "Off"|http://0pointer.de/blog/projects/three-levels-of-off]] [[#6: Changing Roots|http://0pointer.de/blog/projects/changing-roots.html]] [[#7: The Blame Game|http://0pointer.de/blog/projects/blame-game.html]] [[#8: The New Configuration Files|http://0pointer.de/blog/projects/the-new-configuration-files]] [[#9: On /etc/sysconfig and /etc/default|http://0pointer.de/blog/projects/on-etc-sysinit.html]] [[#10: Instantiated Services|http://0pointer.de/blog/projects/instances.html]] [[#11: Converting inetd Services|http://0pointer.de/blog/projects/inetd.html]] [[#12: Securing Your Services|http://0pointer.de/blog/projects/security.html]] [[#13: Log and Service Status|http://0pointer.de/blog/projects/systemctl-journal.html]] [[#14: The Self-Explanatory Boot|http://0pointer.de/blog/projects/self-documented-boot.html]] [[#15: Watchdogs|http://0pointer.de/blog/projects/watchdog.html]] [[#16: Gettys on Serial Consoles (and Elsewhere)|http://0pointer.de/blog/projects/serial-console.html]] [[#17: Using the Journal|http://0pointer.de/blog/projects/journalctl.html]] [[#18: Managing Resources|http://0pointer.de/blog/projects/resources.html]] [[#19: Detecting Virtualization|http://0pointer.de/blog/projects/detect-virt.html]] [[#20: Socket Activated Internet Services and OS Containers|http://0pointer.de/blog/projects/socket-activated-containers.html]] Also available: **[[a Russian translation|http://wiki.opennet.ru/Systemd_%D0%B4%D0%BB%D1%8F_%D0%B0%D0%B4%D0%BC%D0%B8%D0%BD%D0%B8%D1%81%D1%82%D1%80%D0%B0%D1%82%D0%BE%D1%80%D0%BE%D0%B2]]; [[another, more complete Russian translation as PDF|http://www2.kangran.su/~nnz/pub/s4a/s4a_latest.pdf]]; [[a Vietnamese translation|http://archlinuxvn.org/doc/systemd/#lp]]** + +Documentation for Developers: + +* [[Presets|http://freedesktop.org/wiki/Software/systemd/Preset]] [[systemd Optimizations|http://freedesktop.org/wiki/Software/systemd/Optimizations]] [[Interface Stability Promise|http://www.freedesktop.org/wiki/Software/systemd/InterfaceStabilityPromise]] [[Interface Portability and Stability Chart|http://www.freedesktop.org/wiki/Software/systemd/InterfacePortabilityAndStabilityChart]] [[libudev Library interface|http://www.freedesktop.org/software/systemd/libudev/]] [[GUdev Library interface|http://www.freedesktop.org/software/systemd/gudev/]] [[Writing Password Agents|http://www.freedesktop.org/wiki/Software/systemd/PasswordAgents]] [[PID1's Bus APIs|http://www.freedesktop.org/wiki/Software/systemd/dbus]] [[On hostnamed|http://www.freedesktop.org/wiki/Software/systemd/hostnamed]] [[On timedated|http://www.freedesktop.org/wiki/Software/systemd/timedated]] [[On localed|http://www.freedesktop.org/wiki/Software/systemd/localed]] [[On logind|http://www.freedesktop.org/wiki/Software/systemd/logind]] [[Multi-Seat on Linux|http://www.freedesktop.org/wiki/Software/systemd/multiseat]] [[Writing Display Managers|http://www.freedesktop.org/wiki/Software/systemd/writing-display-managers]] [[Writing Desktop Environments|http://www.freedesktop.org/wiki/Software/systemd/writing-desktop-environments]] [[Inhibitor Locks|http://www.freedesktop.org/wiki/Software/systemd/inhibit]] [[Cooperating in the cgroupfs trees|http://www.freedesktop.org/wiki/Software/systemd/PaxControlGroups]] [[Writing syslog Daemons Which Cooperate Nicely With systemd|http://www.freedesktop.org/wiki/Software/systemd/syslog]] [[systemd and Storage Daemons for the Root File System|http://www.freedesktop.org/wiki/Software/systemd/RootStorageDaemons]] [[The Case for the /usr Merge|http://www.freedesktop.org/wiki/Software/systemd/TheCaseForTheUsrMerge]] [[The Container Interface of systemd|http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface]] [[The initrd Interface of systemd|http://www.freedesktop.org/wiki/Software/systemd/InitrdInterface]] [[The Boot Loader Interface of systemd|http://www.freedesktop.org/wiki/Software/systemd/BootLoaderInterface]] [[Implementing Offline System Updates|http://www.freedesktop.org/wiki/Software/systemd/SystemUpdates]] [[Generators|http://www.freedesktop.org/wiki/Software/systemd/Generators]] [[Minimal Builds|http://freedesktop.org/wiki/Software/systemd/MinimalBuilds]] [[Journal Export Format|http://www.freedesktop.org/wiki/Software/systemd/export]] [[Journal JSON Format|http://www.freedesktop.org/wiki/Software/systemd/json]] [[Journal File Format|http://www.freedesktop.org/wiki/Software/systemd/journal-files]] [[Control Groups vs. Control Groups|http://0pointer.de/blog/projects/cgroups-vs-cgroups.html]] [[On /etc/os-release|http://0pointer.de/blog/projects/os-release.html]] [[Journal Message Catalogs|http://www.freedesktop.org/wiki/Software/systemd/catalog]] [[Testing systemd during Development in Virtualization|http://www.freedesktop.org/wiki/Software/systemd/VirtualizedTesting]] + +The systemd for Developers Series: + +* [[#1: Socket Activation|http://0pointer.de/blog/projects/socket-activation.html]] [[#2: Socket Activation, Part 2|http://0pointer.de/blog/projects/socket-activation2.html]] [[#3: Logging to the Journal|http://0pointer.de/blog/projects/journal-submit.html]] + +Related Packages: + +* [[PHP Bindings for the Journal APIs|https://github.com/systemd/php-systemd]] [[Node.JS Bindings for the Journal APIs|http://fourkitchens.com/blog/2012/09/25/nodejs-extension-systemd]] [[Lua Bindings for the Journal APIs|https://github.com/philips/luvit-systemd-journal]] [[Node.JS Support for systemd Socket Activation|https://npmjs.org/package/systemd]] [[Experimental Qt bindings|https://github.com/ndr/libsystemd-qt]] _Note that [[Python support|http://www.freedesktop.org/software/systemd/python-systemd/index.html]] for the Journal is included in systemd's tarball._ + +Packages: + +* [[Fedora|https://admin.fedoraproject.org/community/?package=systemd#package_maintenance]] [[OpenSUSE|https://build.opensuse.org/package/show?package=systemd&project=Base%3ASystem]] [[(Instructions)|http://en.opensuse.org/SDB:Systemd]] [[Debian|http://packages.debian.org/systemd]] [[(Wiki)|http://wiki.debian.org/systemd]] [[Gentoo|http://packages.gentoo.org/package/sys-apps/systemd]] [[(Wiki)|http://wiki.gentoo.org/wiki/Systemd]] [[ArchLinux|https://wiki.archlinux.org/index.php/Systemd]] [[Ubuntu|https://wiki.ubuntu.com/systemd]] diff --git a/Software/systemd/APIFileSystems.mdwn b/Software/systemd/APIFileSystems.mdwn new file mode 100644 index 00000000..df235d85 --- /dev/null +++ b/Software/systemd/APIFileSystems.mdwn @@ -0,0 +1,49 @@ + +[[Back to systemd|http://www.freedesktop.org/wiki/Software/systemd/]] + + +# API File Systems + +_So you are seeing all kinds of weird file systems in the output of mount(8) that are not listed in `/etc/fstab`, and you wonder what those are, how you can get rid of them, or at least change their mount options._ + +The Linux kernel provides a number of different ways for userspace to communicate with it. For many facilities there are system calls, others are hidden behind Netlink interfaces, and even others are exposed via virtual file systems such as `/proc` or `/sys`. These file systems are programming interfaces, they are not actually backed by real, persistent storage. They simply use the file system interface of the kernel as interface to various unrelated mechanisms. Similarly, there are file systems that userspace uses for its own API purposes, to store shared memory segments, shared temporary files or sockets. In this article we want to discuss all these kind of _API file systems_. More specifically, here's a list of these file systems typical Linux systems currently have: + +* `/sys` for exposing kernel devices, drivers and other kernel information to userspace +* `/proc` for exposing kernel settings, processes and other kernel information to userspace +* `/dev` for exposing kernel device nodes to userspace +* `/run` as location for userspace sockets and files +* `/tmp` as location for volatile, temporary userspace file system objects (X) +* `/sys/fs/cgroup` (and file systems below that) for exposing the kernel control group hierarchy +* `/sys/kernel/security`, `/sys/kernel/debug` (X), `/sys/kernel/config` (X) for exposing special purpose kernel objects to userspace +* `/sys/fs/selinux` for exposing SELinux security data to userspace +* `/dev/shm` as location for userspace shared memory objects +* `/dev/pts` for exposing kernel pseudo TTY device nodes to userspace +* `/proc/sys/fs/binfmt_misc` for registering additional binary formats in the kernel (X) +* `/dev/mqueue` for exposing mqueue IPC objects to userspace (X) +* `/dev/hugepages` as a userspace API for allocating "huge" memory pages (X) +* `/sys/fs/fuse/connections` for exposing kernel FUSE connections to userspace (X) +* `/sys/firmware/efi/efivars` for exposing firmware variables to userspace +All these _API file systems_ are mounted during very early boot-up of systemd and are generally not listed in `/etc/fstab`. Depending on the used kernel configuration some of these API file systems might not be available and others might exist instead. As these interfaces are important for kernel-to-userspace and userspace-to-userspace communication they are mounted automatically and without configuration or interference by the user. Disabling or changing their parameters might hence result in applications breaking as they can no longer access the interfaces they need. + +Even though the default settings of these file systems should normally be suitable for most setups, in some cases it might make sense to change the mount options, or possibly even disable some of these file systems. + +Even though normally none of these API file systems are listed in `/etc/fstab` they may be added there. If so, any options specified therein will be applied to that specific API file system. Hence: to alter the mount options or other parameters of these file systems, simply add them to `/etc/fstab` with the appropriate settings and you are done. Using this technique it is possible to change the source, type of a file system in addition to simply changing mount options. That is useful to turn `/tmp` to a true file system backed by a physical disk. + +It is possible to disable the automatic mounting of some (but not all) of these file systems, if that is required. These are marked with (X) in the list above. You may disable them simply by masking them: + + +[[!format txt """ +systemctl mask dev-hugepages.mount +"""]] +This has the effect that the huge memory page API FS is not mounted by default, starting with the next boot. See [[Three Levels of Off|http://0pointer.de/blog/projects/three-levels-of-off.html]] for more information on masking. + +The systemd service [[systemd-remount-fs.service|http://www.freedesktop.org/software/systemd/man/systemd-remount-fs.service.html]] is responsible for applying mount parameters from `/etc/fstab` to the actual mounts. + + +## Why are you telling me all this? I just want to get rid of the tmpfs backed /tmp! + +You have three options: + +1. Disable any mounting on `/tmp` so that it resides on the same physical file system as the root directory. For that, execute `systemctl mask tmp.mount` +1. Mount a different, physical file system to `/tmp`. For that, simply create an entry for it in `/etc/fstab` as you would do for any other file system. +1. Keep `/tmp` but increase/decrease the size of it. For that, also just create an entry for it in `/etc/fstab` as you would do for any other `tmpfs` file system, and use the right `size=` option.
\ No newline at end of file diff --git a/Software/systemd/BootLoaderInterface.mdwn b/Software/systemd/BootLoaderInterface.mdwn new file mode 100644 index 00000000..74e4be22 --- /dev/null +++ b/Software/systemd/BootLoaderInterface.mdwn @@ -0,0 +1,14 @@ + +[[Back to systemd|http://www.freedesktop.org/wiki/Software/systemd/]] + + +# Boot Loader Interface + +systemd can interface with the boot loader to receive performance data and other information. This is only supported on EFI systems. Data is transferred from the boot loader to systemd in EFI variables. All EFI variables use the vendor UUID `4a67b082-0a4c-41cf-b6c7-440b29bb8c4f`. + +* The EFI Variable **LoaderTimeInitUSec** contains the timestamp in microseconds when the loader was initialized. This value is the time spent in the firmware for initialization, it is formatted as numeric, decimal string, in UTF-16. +* The EFI Variable **LoaderTimeExecUSec** contains the timestamp in microseconds when the loader finished its work and is about to execute the kernel. The time spent in the loader is the difference between `LoaderTimeExecUSec` and `LoaderTimeInitUSec`. This value is formatted the same way as `LoaderTimeInitUSec`. +* The EFI variable **LoaderDevicePartUUID** contains the partition GUID of the ESP the boot loader was run from formatted as UTF16 string, in normal GUID syntax. +If `LoaderTimeInitUSec` and `LoaderTimeExecUSec` are set, `systemd-analyze` will include them in its boot-time analysis. If `LoaderDevicePartUUID` is set, systemd will mount the ESP that was used for the boot to /boot, but only if that directory is empty otherwise, and only if no other file systems are mounted there via user mount units or `/etc/fstab`. + +This interface is currently implemented by [[Gummiboot|http://freedesktop.org/wiki/Software/gummiboot]]. diff --git a/Software/systemd/ContainerInterface.mdwn b/Software/systemd/ContainerInterface.mdwn new file mode 100644 index 00000000..320bfdd7 --- /dev/null +++ b/Software/systemd/ContainerInterface.mdwn @@ -0,0 +1,23 @@ + +[[Back to systemd|http://www.freedesktop.org/wiki/Software/systemd/]] + + +# Container Interface + +systemd has a number of interfaces for interaction with container managers when systemd is used within the container. If you write a container solution, please consider supporting the following interfaces: + +* To allow systemd (and other code) to identify that it is executed within a container, please set the "container=" environment variable for PID 1 in the container to a short lowercase string identifying your implementation. With this in place the ConditionVirtualization= setting in unit files will work properly. Example: "container=lxc-libvirt" +* systemd has special support for allowing container managers to initialize the UUID for /etc/machine-id to some manager supplied value. This is only enabled if /etc/machine-id is empty (i.e. not yet set) at boot time of the container. The container manager should set "container_uuid=" to the container UUID it wants to set. (This is similar to the effect of qemu's -uuid switch). Note that you should pass only a UUID here that is actually unique (i.e. only one running container should have a specific UUID), and gets changed when a container gets duplicated. Also note that systemd will try to persistently store the UUID in /etc/machine-id (if writable) when this option is used, hence you should always pass the same UUID here. Keeping the externally used UUID for a container and the internal one in sync is hopefully useful to minimize surprise for the administrator. +* If the container manager wants to influence the hostname for a machine it should just set it before invoking systemd in the container, and systemd will leave it unmodified (that is unless there's an explicit hostname configured in /etc/hostname which overrides whatever is pre-initialized by the container manager) +* Make sure to pre-mount /sys, and /proc, /sys/fs/selinux before invoking systemd, and mount /proc/sys and the entirety of /sys and /sys/fs/selinux read-only in order to avoid that the container can alter the host kernel's configuration settings. systemd and various tools (such as the selinux) have been modified to detect whether these file systems are read-only, and will behave accordingly. +* Consider syncing /etc/localtime from the host file system into the container. Make it a relative symlink to the containers's zoneinfo dir, as usual. Tools rely on being able to determine the timezone setting from the symlink value, and by making it relative it looks nice even if people list the containers' /etc from the host. +* Pre-mount /dev as (container private) tmpfs for the container and bind mount some suitable TTY to /dev/console. Also, make sure to create device nodes for /dev/null, /dev/zero, /dev/full, /dev/random, /dev/urandom, /dev/tty, /dev/ptmx in /dev. It is not necessary to create /dev/fd or /dev/stdout, as systemd will do that on its own. Make sure to drop CAP_MKNOD from the capability bounding set to ensure that the container is not able to get access to any other device. +* udev is not available in containers (and refuses to start), and hence device dependencies are unavailable. The udev unit files will check for CAP_SYS_MKNOD, and skip udev if that is not available. Hence, make sure to drop this capability entirely for the container. +* If systemd detects it is run in a container it will spawn a single shell on /dev/console, and not care about VTs or multiple gettys on VTs +* Make the container journal available in the host, by automatically symlinking the container journal directory into the host journal directory. More precisely, link /var/log/journal/<container-machine-id> of the container into the same dir of the host. Administrators can then automatically browse all container journals (correctly interleaved) by issuing "journalctl -m". The container machine ID you can determine from /etc/machine-id in the container. +* If the container manager wants to cleanly shutdown the container, it might be a good idea to send SIGRTMIN+3 to its init process. systemd will then do a clean shutdown. Note however, that only systemd understands SIGRTMIN+3 like this, this might confuse other init systems. +* To support [[Socket Activated Containers|http://0pointer.de/blog/projects/socket-activated-containers.html]] the container manager should be capable of being run as a systemd service. It will then receive the sockets starting with FD 3, the number of passed FDs in $LISTEN_FDS and its PID as $LISTEN_PID. It should take these and pass them on to the container's init process, also setting $LISTEN_FDS and $LISTEN_PID (basically, it can just leave the FDs and $LISTEN_FDS untouched, but it needs to set $LISTEN_PID to for the container init process). That's all that's necessary to make socket activation work. The protocol to hand sockets from systemd to services is hence the same as from a container manager to a container systemd. For further details see the [[explanations of sd_listen_fds(1)|http://0pointer.de/public/systemd-man/sd_listen_fds.html]] and [[the blog story for service developers|http://0pointer.de/blog/projects/socket-activation.html]]. +* Container managers should stay away from the "name=systemd" cgroup hierarchy. That's private property of systemd, and no other code should interfere with it. +If you write software that wants to detect whether it is run in a container, please check /proc/1/environ and look for the container= environment variable. Do not assume the environment variable is inherited down the process tree. It generally is not. Hence check the environment block of PID 1, not your own. + +Note that it is our intention to make systemd systems work flawlessly and out-of-the-box in containers. In fact we are interested to ensure that the same OS image can be booted on a bare system, in a VM and in a container, and behave correctly each time. If you notice that some component in systemd does not work in a container as it should please contact us. diff --git a/Software/systemd/Debugging.mdwn b/Software/systemd/Debugging.mdwn new file mode 100644 index 00000000..f3accbd0 --- /dev/null +++ b/Software/systemd/Debugging.mdwn @@ -0,0 +1,179 @@ +[[!table header="no" class="mointable" data=""" + +[[!toc ]] +"""]] + +[[Back to systemd|http://www.freedesktop.org/wiki/Software/systemd/]] + + +# Diagnosing Boot Problems + +If your machine gets stuck during boot, first check if the hang happens before or after control passes to systemd. + +Try to boot without `rhgb` and `quiet` on the kernel command line. If you see some messages like these: + + * Welcome to Fedora _VERSION_ (_codename_)!" + * Starting _name_... + * [ OK ] Started _name_. +then systemd is running. (See an actual [[screenshot|f17boot.png]].) + +Debugging always gets easier if you can get a shell. If you do not get a login prompt, try switching to a different virtual terminal using CTRL+ALT+F_<number>_. Problems with X server startup may manifest themselves as a missing login on tty1, but other VTs working. + +If the boot stops without presenting you with a login on any virtual console, let it retry for _up to 5 minutes_ before declaring it definitely stuck. There is a chance that a service that has trouble starting will be killed after this timeout and the boot will continue normally. Another possibility is that a device for an important mountpoint will fail to appear and you will be presented with _emergency mode_. + + +## If You Get No Shell + +If you get neither a normal login nor the emergency mode shell, you will need to do additional steps to get debugging information out of the machine. + + * Try CTRL+ALT+DEL to reboot. + * If it does not reboot, mention it in your bugreport. Meanwhile force the reboot with [[SysRq|http://fedoraproject.org/wiki/QA/Sysrq]] or hard reset. + * When booting the next time, you will have to add some kernel command line arguments depending on which of the debugging strategies you choose from the following options. + +### Debug Logging to a Serial Console + +If you have a hardware serial console available or if you are debugging in a virtual machine (e.g. using virt-manager you can switch your view to a serial console in the menu View -> Text Consoles), you can ask systemd to log lots of useful debugging information to it by booting with: +[[!format txt """ +systemd.log_level=debug systemd.log_target=console console=ttyS0,38400 +"""]] + +### Booting into Rescue or Emergency Targets + +To boot directly into rescue target add `systemd.unit=rescue.target` or just `1` to the kernel command line. This target is useful if the problem occurs somewhere after the basic system is brought up, during the starting of "normal" services. If this is the case, you should be able to disable the bad service from here. If the rescue target will not boot either, the more minimal emergency target might. + +To boot directly into emergency shell add `systemd.unit=emergency.target` or `emergency` to the kernel command line. Note that in the emergency shell you will have to remount the root filesystem read-write by yourself before editing any files: +[[!format txt """ +mount -o remount,rw / +"""]] +Common issues that can be resolved in the emergency shell are bad lines in **/etc/fstab**. After fixing **/etc/fstab**, run `systemctl daemon-reload` to let systemd refresh its view of it. + +If not even the emergency target works, you can boot directly into a shell with `init=/bin/sh`. This may be necessary in case systemd itself or some libraries it depends on are damaged by filesystem corruption. You may need to reinstall working versions of the affected packages. + +If `init=/bin/sh` does not work, you must boot from another medium. + + +### Early Debug Shell + +You can enable shell access to be available very early in the startup process to fall back on and diagnose systemd related boot up issues with various systemctl commands. Enable it using: +[[!format txt """ +systemctl enable debug-shell.service +"""]] +**Tip**: If your version of systemd is not new enough to have debug-shell.service, you can download the unit file from [[systemd git|http://cgit.freedesktop.org/systemd/systemd/plain/units/debug-shell.service.in]]. Substitute `/bin/bash` for `@sushell@` in the file. + +**Tip**: If you find yourself in a situation where you cannot use systemctl (e.g. when setting this up from a different booted system), you can enable the service manually: +[[!format txt """ +cd $PATH_TO_YOUR_ROOT_FS/etc/systemd/system +mkdir -p sysinit.target.wants +ln -s /lib/systemd/system/debug-shell.service sysinit.target.wants/ +"""]] +Once enabled, the next time you boot you will be able to switch to tty9 using CTRL+ALT+F9 and have a root shell there available from an early point in the booting process. You can use the shell for checking the status of services, reading logs, looking for stuck jobs with `systemctl list-jobs`, etc. + +**Warning:** Use this shell only for debugging! Do not forget to disable systemd-debug-shell.service after you've finished debugging your boot problems. Leaving the root shell always available would be a security risk. + + +### verify prerequisites + +A (at least partly) populated `/dev` is required. Depending on your setup (e.g. on embedded systems), check that the Linux kernel config options `CONFIG_DEVTMPFS` and `CONFIG_DEVTMPFS_MOUNT` are set. Also support for cgroups and fanotify is recommended for a flawless operation, so check that the Linux kernel config options `CONFIG_CGROUPS` and `CONFIG_FANOTIFY` are set. The message "Failed to get D-Bus connection: No connection to service manager." during various `systemctl` operations is an indicator that these are missing. + + +## If You Can Get a Shell + +When you have systemd running to the extent that it can provide you with a shell, please use it to extract useful information for debugging. Boot with these parameters on the kernel command line: +[[!format txt """ +systemd.log_level=debug systemd.log_target=kmsg log_buf_len=1M +"""]] +in order to increase the verbosity of systemd, to let systemd write its logs to the kernel log buffer, and to increase the size of the kernel log buffer. After reaching the shell, save the log: +[[!format txt """ +dmesg > dmesg.txt +"""]] +When reporting a bug, attach the **dmesg.txt** file. + +To check for possibly stuck jobs use: +[[!format txt """ +systemctl list-jobs +"""]] +The jobs that are listed as "running" are the ones that must complete before the "waiting" ones will be allowed to start executing. + + +# Diagnosing Shutdown Problems + +Just like with boot problems, when you encounter a hang during shutting down, make sure you wait _at least 5 minutes_ to distinguish a permanent hang from a broken service that's just timing out. Then it's worth testing whether the system reacts to CTRL+ALT+DEL in any way. + +If shutdown (whether it be to reboot or power-off) of your system gets stuck, first test if the kernel itself is able to reboot or power-off the machine forcedly using one of these commands: +[[!format txt """ +sync && reboot -f +sync && poweroff -f +"""]] +If either one of the commands does not work, it is a kernel bug, not systemd. + + +## Shutdown Completes Eventually + +If normal reboot or poweroff work, but take a suspiciously long time, then + + * boot with the debug options: + +[[!format txt """ +systemd.log_level=debug systemd.log_target=kmsg log_buf_len=1M enforcing=0 +"""]] + * save the following script as **/lib/systemd/system-shutdown/debug.sh** and make it executable: + +[[!format txt """ +#!/bin/sh +mount -o remount,rw / +dmesg > /shutdown-log.txt +mount -o remount,ro / +"""]] + * reboot +Look for timeouts logged in the resulting file **shutdown-log.txt** and/or attach it to a bugreport. + + +## Shutdown Never Finishes + +If normal reboot or poweroff never finish even after waiting a few minutes, the above method to create the shutdown log will not help and the log must be obtained using other methods. Two options that are useful for debugging boot problems can be used also for shutdown problems: + + * use a [[serial console|Software/systemd/Debugging]] + * use a [[debug shell|Software/systemd/Debugging]] - not only is it available from early boot, it also stays active until late shutdown. + +# Status and Logs of Services + +When the start of a service fails, systemctl will give you a generic error message: +[[!format txt """ +# systemctl start foo.service +Job failed. See system journal and 'systemctl status' for details. +"""]] +The service may have printed its own error message, but you do not see it, because services run by systemd are not related to your login session and their outputs are not connected to your terminal. That does not mean the output is lost though. By default the stdout, stderr of services are directed to the systemd _journal_ and the logs that services produce via `syslog(3)` go there too. systemd also stores the exit code of failed services. Let's check: +[[!format txt """ +# systemctl status foo.service +foo.service - mmm service + Loaded: loaded (/etc/systemd/system/foo.service; static) + Active: failed (Result: exit-code) since Fri, 11 May 2012 20:26:23 +0200; 4s ago + Process: 1329 ExecStart=/usr/local/bin/foo (code=exited, status=1/FAILURE) + CGroup: name=systemd:/system/foo.service + +May 11 20:26:23 scratch foo[1329]: Failed to parse config +"""]] +In this example the service ran as a process with PID 1329 and exited with error code 1. If you run systemctl status as root or as a user from the `adm` group, you will get a few lines from the journal that the service wrote. In the example the service produced just one error message. + +To list the journal, use the `journalctl` command. + +If you have a syslog service (such as rsyslog) running, the journal will also forward the messages to it, so you'll find them in **/var/log/messages** (depending on rsyslog's configuration). + + +# Reporting systemd Bugs + +Be prepared to include some information (logs) about your system as well. These should be complete (no snippets please), not in an archive, uncompressed, with MIME type set as text/plain. + +Please report bugs to your distribution's bug tracker first. If you are sure that you are encountering an upstream bug, then first check [[for existing bug reports|https://bugs.freedesktop.org/buglist.cgi?query_format=advanced&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&product=systemd]], and if your issue is not listed [[file a new bug|https://bugs.freedesktop.org/enter_bug.cgi?product=systemd]]. + + +## Information to Attach to a Bug Report + +Whenever possible, the following should be mentioned and attached to your bug report: + + * The exact kernel command-line used if not default. Typically from the bootloader configuration file (e.g. **/boot/grub2/grub.cfg**) or from **/proc/cmdline** + * A copy of the file **/var/log/messages** + * The output of the dmesg command: `dmesg > dmesg.txt` + * ideally after booting with `systemd.log_level=debug systemd.log_target=kmsg log_buf_len=1M` + * The output of a systemd dump: `systemctl dump > systemd-dump.txt` + * The output of `/usr/bin/systemd --test --system --log-level=debug > systemd-test.txt 2>&1`
\ No newline at end of file diff --git a/Software/systemd/Debugging/f17boot.png b/Software/systemd/Debugging/f17boot.png Binary files differnew file mode 100644 index 00000000..8415b812 --- /dev/null +++ b/Software/systemd/Debugging/f17boot.png diff --git a/Software/systemd/FrequentlyAskedQuestions.mdwn b/Software/systemd/FrequentlyAskedQuestions.mdwn new file mode 100644 index 00000000..2fbcd8d3 --- /dev/null +++ b/Software/systemd/FrequentlyAskedQuestions.mdwn @@ -0,0 +1,111 @@ + +[[Back to systemd|http://www.freedesktop.org/wiki/Software/systemd/]] + + +# Frequently Asked Questions + +Also check out the [[Tips & Tricks|http://www.freedesktop.org/wiki/Software/systemd/TipsAndTricks]]! + +**Q: How do I change the current runlevel?** + +A: In systemd runlevels are exposed via "target units". You can change them like this: + + +[[!format txt """ +# systemctl isolate runlevel5.target +"""]] +Note however, that the concept of runlevels is a bit out of date, and it is usually nicer to use modern names for this. e.g.: + + +[[!format txt """ +# systemctl isolate graphical.target +"""]] +This will only change the current runlevel, and has no effect on the next boot. + +**Q: How do I change the default runlevel to boot into?** + +A: The symlink /etc/systemd/system/default.target controls where we boot into by default. Link it to the target unit of your choice. For example, like this: + + +[[!format txt """ +# ln -sf /usr/lib/systemd/system/multi-user.target /etc/systemd/system/default.target +"""]] +or + + +[[!format txt """ +# ln -sf /usr/lib/systemd/system/graphical.target /etc/systemd/system/default.target +"""]] +**Q: How do I figure out the current runlevel?** + +A: Note that there might be more than one target active at the same time. So the question regarding _the_ runlevel might not always make sense. Here's how you would figure out all targets that are currently active: + + +[[!format txt """ +$ systemctl list-units --type=target +"""]] +If you are just interested in a single number, you can use the venerable _runlevel_ command, but again, its output might be misleading. + +**Q: I want to change a service file, but rpm keeps overwriting it in /usr/lib/systemd/system all the time, how should I handle this?** + +A: The recommended way is to copy the service file from /usr/lib/systemd/system to /etc/systemd/system and edit it there. The latter directory takes precedence over the former, and rpm will never overwrite it. If you want to use the distributed service file again you can simply delete (or rename) the service file in /etc/systemd/system again. + +**Q: My service foo.service as distributed by my operating system vendor is only started when (a connection comes in or some hardware is plugged in). I want to have it started always on boot, too. What should I do?** + +A: Simply place a symlink from that service file in the multi-user.target.wants/ directory (which is where you should symlink everything you want to run in the old runlevel 3, i.e. the normal boot-up without graphical UI. It is pulled in by graphical.target too, so will be started for graphical boot-ups, too): + + +[[!format txt """ +# ln -sf /usr/lib/systemd/system/foobar.service /etc/systemd/system/multi-user.target.wants/foobar.service +# systemctl daemon-reload +"""]] +**Q: I want to enable another getty, how would I do that?** + +A: Simply instantiate a new getty service for the port of your choice (internally, this places another symlink for instantiating another serial getty in the getty.target.wants/ directory). + + +[[!format txt """ +# systemctl enable serial-getty@ttyS2.service +# systemctl start serial-getty@ttyS2.service +"""]] +Note that gettys on the virtual console are started on demand. You can control how many you get via the NAutoVTs= setting in [[logind.conf(7)|http://www.freedesktop.org/software/systemd/man/logind.html]]. Also see [[this blog story|http://0pointer.de/blog/projects/serial-console.html]]. + +**Q: How to I figure out which service a process belongs to?** + +A: You may either use ps for that: + + +[[!format txt """ +$ alias psc='ps xawf -eo pid,user,cgroup,args' +$ psc +... +"""]] +Or you can even check /proc/$PID/cgroup directly. Also see [[this blog story|http://0pointer.de/blog/projects/systemd-for-admins-2.html]]. + +**Q: Why don't you use inotify to reload the unit files automatically on change?** + +A: Unfortunately that would be a racy operation. For an explanation why and how we tried to improve the situation, see [[the bugzilla report about this|https://bugzilla.redhat.com/show_bug.cgi?id=615527]]. + +**Q: I have a native systemd service file and a SysV init script installed which share the same basename, e.g. /usr/lib/systemd/system/foobar.service vs. /etc/init.d/foobar -- which one wins?** + +A: If both files are available the native unit file always takes precedence and the SysV init script is ignored, regardless whether either is enabled or disabled. Note that a SysV service that is enabled but overridden by a native service does not have the effect that the native service would be enabled, too. Enabling of native and SysV services is completely independent. Or in other words: you cannot enable a native service by enabling a SysV service by the same name, and if a SysV service is enabled but the respective native service is not, this will not have the effect that the SysV script is executed. + +**Q: How can I use journalctl to display full (= not truncated) messages even if less is not used?** + +A: Use: + + +[[!format txt """ +# journalctl --full +"""]] +**Q: Whenever my service tries to acquire RT scheduling for one of its threads this is refused with EPERM even though my service is running with full privileges. This works fine on my non-systemd system!** + +A: By default, systemd places all systemd daemons in their own cgroup in the "cpu" hierarchy. Unfortunately, due to a kernel limitation, this has the effect of disallowing RT entirely for the service. See [[My Service Can't Get Realtime!|http://www.freedesktop.org/wiki/Software/systemd/MyServiceCantGetRealtime]] for a longer discussion and what to do about this. + +**Q: My service is ordered after `network.target` but at boot it is still called before the network is up. What's going on?** + +A: That's a long story, and that's why we have a wiki page of its own about this: [[Running Services After the Network is up|http://www.freedesktop.org/wiki/Software/systemd/NetworkTarget]] + +**Q: My systemd system always comes up with `/tmp` as a tiny `tmpfs`. How do I get rid of this?** + +A: That's also a long story, please have a look on [[API File Systems|http://www.freedesktop.org/wiki/Software/systemd/APIFileSystems]] diff --git a/Software/systemd/Generators.mdwn b/Software/systemd/Generators.mdwn new file mode 100644 index 00000000..99b3e5cb --- /dev/null +++ b/Software/systemd/Generators.mdwn @@ -0,0 +1,40 @@ + +[[Back to systemd|http://www.freedesktop.org/wiki/Software/systemd/]] + + +# Generators + +_This describes generators as implemented in systemd 183 and newer. Generators have been available before but with slightly less powerful semantics._ + +Generators are small binaries that live in /lib/systemd/system-generators. systemd will execute those binaries very early at bootup and at configuration reload time -- before the unit files are loaded. The generators can dynamically generate/symlink unit files into special runtime directories (i.e. into the tmpfs that is /run), and extend or override existing definitions freely. Their main purpose is to convert configuration files that are not native unit files dynamically into native unit files. + +Generators are not a magic wand. Not all problems are best solved with generators. However they are a valuable tool to dynamically extend the dependency tree of systemd. + +Generators are invoked with three arguments, all of them paths to runtime directories where generator tools can place their unit files or symlinks. + +1. **Normal:** argv[1] may be used to override unit files in /usr, but not those in /etc. This means that unit files placed in this directory take precedence over vendor unit configuration but not over native user/administrator unit configuration. +1. **Early:** argv[2] may be used to override unit files in /usr and in /etc. This means that unit files placed in this directory take precedence over all configuration, regardless if vendor or user/administrator. +1. **Late:** argv[3] may be used to extend the unit file tree but not override any other unit files. Any native configuration files regardless if supplied by the vendor or user/administrator take precedence over the generated ones placed in this directory. +Examples: + +1. systemd-fstab-generator converts /etc/fstab into native mount units. It uses argv[1] as location to place the generated unit files in order to allow the user to override fstab with his own native unit files, but also to ensure that /etc/fstab overrides any vendor default from /usr. +1. Similar, systemd-cryptsetup-generator converts /etc/crypttab to native service units. It also uses argv[1]. +1. systemd-system-update-generator temporarily redirects default.target to system-update.target if a system update is scheduled. Since this needs to override the default user configuration for default.target it uses argv[2]. (For details about this logic, see [[Implementing Offline System Updates|http://www.freedesktop.org/wiki/Software/systemd/SystemUpdates]]). +Regarding overriding semantics: there are two rules we try to follow when thinking about the overriding semantics: + +1. User configuration should override vendor configuration. This (mostly) means that stuff from /etc should override stuff from /usr. +1. Native configuration should override non-native configuration. This (mostly) means that stuff you generate should never override native unit files for the same purpose. +Of these two rules the first rule is probably the more important one and breaks the second one sometimes. Hence, when deciding whether to user argv[1], argv[2], or argv[3] your default choice should probably be argv[1]. + +A couple of notes: + +1. All generators are executed in parallel. That means all executables in /lib/systemd/system-generators are run at the very same time and need to be able to cope with this parallelism. +1. Since generators are run very early at boot they cannot rely on any external services. They may not talk to any other process. That includes simple things such as logging to syslog. However, they can rely on the most basic kernel functionality to be available, including mounted /sys, /proc, /dev. +1. Units written by generators are removed when configuration is reloaded. That means the lifetime of the generated units is closely bound to the reload cycles of systemd itself. +1. Generators should only be used to generate unit files, not any other kind of configuration. Due to the lifecycle logic mentioned above generators are not really the best fit to generate dynamic configuration for other services. If you need to generate dynamic configuration for other services do so in normal services you order before the service in question. +1. Since syslog is not available (see above) write log messages to /dev/kmsg instead. +1. It is a good idea to use the [[SourcePath|SourcePath]]= directive in generated unit files to specify the source configuration file you are generating the unit from. This makes things more easily understood by the user and also has the benefit that systemd can warn the user about configuration files that changed on disk but have not been read yet by systemd. +1. Generators may write out dynamic unit files or just hook unit files into other units with the usual .wants/ or .requires/ symlinks. Often it is nicer to simply instantiate a template unit file from /usr with a generator instead of writing out entirely dynamic unit files. Of course this works only if a single parameter is to be used. +1. If you are careful you can implement generators in shell scripts. We do recommend C code however, since generators delay are executed synchronously and hence delay the entire boot if they are slow. +1. Instead of heading off now and writing all kind of generators for legacy configuration file formats, please think twice! It's often a better idea to just deprecate old stuff instead of keeping it artificially alive. +Or in short: **Don't do IPC from generators. Don't use syslog. Use /dev/kmsg for logging. Use [[SourcePath|SourcePath]]=. Don't write out non-unit configuration files from generators.** Thank you! diff --git a/Software/systemd/Incompatibilities.mdwn b/Software/systemd/Incompatibilities.mdwn new file mode 100644 index 00000000..4e4a5a17 --- /dev/null +++ b/Software/systemd/Incompatibilities.mdwn @@ -0,0 +1,22 @@ + +[[Back to systemd|http://www.freedesktop.org/wiki/Software/systemd/]] + + +# Compatibility with SysV + +systemd provides a fair degree of compatibility with the behavior exposed by the SysV init system as implemented by many distributions. Compatibility is provided both for the user experience and the SysV scripting APIs. However, there are some areas where compatibility is limited due to technical reasons or design decisions of systemd and the distributions. All of the following applies to SysV init scripts handled by systemd, however a number of them matter only on specific distributions. Many of the incompatibilities are specific to distribution-specific extensions of LSB/SysV init. + +* If your distribution removes SysV init scripts in favor of systemd unit files typing "/etc/init.d/foobar start" to start a service will not work, since the script will not be available. Use the more correct "/sbin/service foobar start" instead, and your command will be forwarded to systemd. Note that invoking the init script directly has always been suboptimal since too much of the caller's execution context (environment block, umask, resource limits, audit trails, ...) ended up being inherited by the service, and invocation via "/sbin/service" used to clean this up at least partially. Invocation via /sbin/service works on both SysV and systemd systems. Also, LSB only standardizes invocation via "/sbin/service" anyway. (Note that some distributions ship both systemd unit files and SysV scripts for the services. For these invoking the init scripts will work as expected and the request be forwarded to systemd in any case.) +* LSB header dependency information matters. The SysV implementations on many distributions did not use the dependency information encoded in LSB init script headers, or used them only in very limited ways. Due to that they are often incorrect or incomplete. systemd however fully interprets these headers and follows them closely at runtime (and not at installation time like some implementations). +* Timeouts apply to all init script operations in systemd. While on SysV systems a hanging init script could freeze the system on systemd all init script operations are subject to a timeout of 5min. +* Services are executed in completely clean execution contexts, no context of the invoking user session is inherited. Not even $HOME or similar are set. Init scripts depending on these will not work correctly. +* Services cannot read from stdin, as this will be connected to /dev/null. That means interactive init scripts are not supported (i.e. Debian's X-Interactive in the LSB header is not supported either.) Thankfully most distributions do not support interaction in init scripts anyway. If you need interaction to ask disk or SSL passphrases please consider using the minimal password querying framework systemd supports. ([[details|http://www.freedesktop.org/wiki/Software/systemd/PasswordAgents]], [[manual page|http://0pointer.de/public/systemd-man/systemd-ask-password.html]]) +* Additional verbs for init scripts are not supported. If your init script traditionally supported additional verbs for your init script simply move them to an auxiliary script. +* Additional parameters to the standard verbs (i.e. to "start", "stop" and "status") are not supported. This was an extension of SysV that never was standardized officially, and is not supported in systemd. +* systemd only stops running services. On traditional SysV a K link installed for shutdown was executed when going down regardless whether the service was started before or not. systemd is more strict here and does not stop service that weren't started in the first place. +* Runlevels are supported in a limited fashion only. SysV runlevels are mapped to systemd target units, however not all systemd target units map back to SysV runlevels. This is due to the fact that systemd targets are a lot more flexible and expressive than SysV runlevels. That means that checks for the current runlevel (with /sbin/runlevel or so) may well return "N" (i.e. unknown runlevel) during normal operation. Scripts that rely on explicit runlevel checks are incompatible with many setups. Avoid runlevel checks like these. +* Tools like /sbin/chkconfig might return misleading information when used to list enablement status of services. First of all, the tool will only see SysV services, not native units. Secondly, it will only show runlevel-related information (which does not fully map to systemd targets). Finally, the information shown might be overridden by a native unit file. +* By default runlevels 2,3,4 are all aliases for "multi-user.target". If a service is enabled in one of these runlevels, they'll be enabled in all of these. This is only a default however, and users can easily override the mappings, and split them up into individual runlevels if they want. However, we recommend moving on from runlevels and using the much more expressive target units of systemd. +* Early boot runlevels as they are used by some distributions are no longer supported. i.e. "fake", distribution-specific runlevels such as "S" or "b" cannot be used with systemd. +* By default, System V services are not permitted to acquire realtime scheduling, even with root privileges. See [[MyServiceCantGetRealtime|MyServiceCantGetRealtime]] for details, and what to do about it. +Note that there are some areas where systemd currently provides a certain amount of compatibility where we expect this compatibility to be removed eventually. For example, systemd currently provides compatibility with the special non-standardized "boot" and "S" runlevels covering early boot which are used on Suse and Debian systems. We expect to remove this eventually, to keep compatibility kludges out of early boot. Support for SysV init scripts in the normal runlevels (2-5) is expected to stay for a long time however. diff --git a/Software/systemd/InitrdInterface.mdwn b/Software/systemd/InitrdInterface.mdwn new file mode 100644 index 00000000..f36440ba --- /dev/null +++ b/Software/systemd/InitrdInterface.mdwn @@ -0,0 +1,27 @@ + +[[Back to systemd|http://www.freedesktop.org/wiki/Software/systemd/]] + + +# The initrd Interface of systemd + +systemd supports both initrd and initrd-less boots. If an initrd is used it is a good idea to pass a few bits of runtime information from the initrd to systemd in order to avoid duplicate work and to provide performance data to the administrator. In this page we attempt to roughly describe the interfaces that exist between the initrd and systemd. These interfaces are currently used by dracut and the [[ArchLinux|ArchLinux]] initrds. + +* The initrd should mount /run as a tmpfs and pass it pre-mounted when jumping into the main system when executing systemd. The mount options should be mode=755,nodev +* It's highly recommended that the initrd also mounts /usr (if split off) as appropriate and passes it pre-mounted to the main system, to avoid the problems described in [[Booting without /usr is Broken|http://freedesktop.org/wiki/Software/systemd/separate-usr-is-broken]]. +* In the $RD_TIMESTAMP environment variable the initrd shall pass the monotonic and realtime timestamp when execution of the initrd began. This is then used by systemd to estimate the time that is spent in the kernel initialization, the initrd initialization and the main system initialization at boot. The monotonic and realtime timestamps shall be formatted as ASCII values of usecs, separated by a space character. The /lib/systemd/systemd-timestamp tool will generate a properly formatted timestamp for you, consider adding it to your initrd. +* If the file /run/initramfs/root-fsck exists systemd will skip the root file system check. It is recommended that the initrd completes the root fsck before mounting the root file system, using this file to inform systemd not to repeat the step. The initrd should write the exit code of the fsck process into the file, in order to inform the main OS about the result of the file system check. +* If the executable /run/initramfs/shutdown exists systemd will jump back into the initrd on shutdown. /run/initramfs should be a usable initrd environment to which systemd will pivot back and the "shutdown" executable in it should be able to detach all complex storage that for example was needed to mount the root file system. It's the job of the initrd to set up this directory and executable in the right way so that this works correctly. +* Storage daemons run from the initrd should follow the [[the guide on systemd and Storage Daemons for the Root File System|http://www.freedesktop.org/wiki/Software/systemd/RootStorageDaemons]] to survive properly from the boot initrd all the way to the point where systemd jumps back into the initrd for shutdown. +One last clarification: we use the term _initrd_ very generically here describing any kind of early boot file system, regardless whether that might be implemented as an actual ramdisk, ramfs or tmpfs. We recommend using _initrd_ in this sense as a term that is unrelated to the actual backing technologies used. + +Oh, and one last question before closing: instead of implementing these features in your own distro's initrd, may I suggest just using Dracut instead? It's all already implemented there! + + +## Using systemd inside an initrd + +It is also possible and recommended to implement the initrd itself based on systemd. Here are a few terse notes: + +* Provide /etc/initrd-release in the initrd image. The idea is that it follows the same format as the usual /etc/os-release but describes the initial RAM disk implementation rather than the OS. systemd uses the existence of this file as a flag whether to run in initial RAM disk mode, or not. +* When run in initrd mode, systemd and its components will read a couple of additional command line arguments, which are generally prefixed with rd. +* To transition into the main system image invoke "systemctl switch-root". +* The switch-root operation will result in a killing spree of all running processes. Some processes might need to be excluded from that, see [[the guide on systemd and Storage Daemons for the Root File System|http://www.freedesktop.org/wiki/Software/systemd/RootStorageDaemons]].
\ No newline at end of file diff --git a/Software/systemd/InterfacePortabilityAndStabilityChart.mdwn b/Software/systemd/InterfacePortabilityAndStabilityChart.mdwn new file mode 100644 index 00000000..5878971c --- /dev/null +++ b/Software/systemd/InterfacePortabilityAndStabilityChart.mdwn @@ -0,0 +1,98 @@ + +[[Back to systemd|http://www.freedesktop.org/wiki/Software/systemd/]] + + +# Interface Portability And Stability Chart + +systemd provides a number of APIs to applications. Below you'll find a table detailing which APIs are considered stable and how portable they are. + +This list is intended to be useful for distribution and OS developers who are interested to maintain a certain level of compatibility with the new interfaces systemd introduced, without relying on systemd itself. + +In general it is our intention to cooperate with interfaces, not with code with other distributions and OSes. That means, that the interfaces where this applies are best reimplemented in a compatible fashion on those other operating systems. To make this easy we provide detailed interface documentation where necessary. That said, it's all Open Source, hence you have the option to a) fork our code and maintain portable versions of the parts you are interested in independently for your OS, or b) build systemd for your distro, but leave out all components but the ones you are interested in and run them without the core of systemd involved. We will try not to make this any more difficult than necessary, but we do not officially support using systemd code this way and will not accept patches for making this easier. + +Many of these interfaces are already being used by applications and 3rd party code. If you are interested in compatibility with these applications, please consider supporting these interfaces in your distribution, where possible. + + +## General Portability of systemd and its Components + +**Portability to OSes:** systemd is not portable to non-Linux systems. It makes use of a large number of Linux-specific interfaces, including many that are used by its very core. We do not consider it feasible to port systemd to other Unixes (let alone non-Unix operating systems) and will not accept patches for systemd implementing any such portability (but hey, it's git, so it's as easy as it can get to maintain your own fork...). APIs that are supposed to be used as drop-in .c files are exempted from this: it is important to us that these compile nicely on non-Linux and even non-Unix platforms, even if they might just become NOPs. + +**Portability to Architectures:** It is important to us that systemd is portable to little endian as well as big endian systems. We will make sure to provide portability with all important architectures and hardware Linux runs on and are happy to accept patches for this. + +**Portability to Distributions:** It is important to us that systemd is portable to all important Linux distributions. However, the goal is to unify many of the needless differences between the distributions, and hence will not accept patches for certain distribution-specific compatibility. Compatibility with the distribution's legacy should be maintained in the distribution's packaging, and not in the systemd source tree. + +**Compatibility with Specific Versions of Other packages:** We generally avoid adding compatibility kludges to systemd that work around bugs in certain versions of other software systemd interfaces with. We strongly encourage fixing bugs where they are, and if that's not systemd we rather not try to fix it there. (There are very few exceptions to this rule possible, and you need an exceptionally strong case for it). + + +## General Portability of systemd's APIs + +systemd's APIs are available everywhere where systemd is available. Some of the APIs we have defined are supposed to be generic enough to be implementable independently of systemd, thus allowing compatibility with systems systemd itself is not compatible with, i.e. other OSes, and distributions that are unwilling to fully adopt systemd. + +A number of systemd's APIs expose Linux or systemd-specific features that cannot sensibly be implemented elsewhere. Please consult the table below for information about which ones these are. + +Note that not all of these interfaces are our invention (but most), we just adopted them in systemd to make them more prominently implemented. For example, we adopted many Debian facilities in systemd to push it into the other distributions as well. + + + +--- + + + +And now, here's the list of (hopefully) all APIs that we have introduced with systemd: +[[!table header="no" class="mointable" data=""" +**API** | **Type** | **Covered by [[Interface Stability Promise|http://www.freedesktop.org/wiki/Software/systemd/InterfaceStabilityPromise]]** | **Fully documented** | **Known External Consumers** | **Reimplementable Independently** | **Known Other Implementations** | **systemd Implementation portable to other OSes or non-systemd distributions +[[hostnamed|http://www.freedesktop.org/wiki/Software/systemd/hostnamed]] | D-Bus | yes | yes | GNOME | yes | [[Ubuntu|https://launchpad.net/ubuntu/+source/ubuntu-system-service]], [[Gentoo|http://www.gentoo.org/proj/en/desktop/gnome/openrc-settingsd.xml]] | partially +[[localed|http://www.freedesktop.org/wiki/Software/systemd/localed]] | D-Bus | yes | yes | GNOME | yes | [[Ubuntu|https://launchpad.net/ubuntu/+source/ubuntu-system-service]], [[Gentoo|http://www.gentoo.org/proj/en/desktop/gnome/openrc-settingsd.xml]] | partially +[[timedated|http://www.freedesktop.org/wiki/Software/systemd/timedated]] | D-Bus | yes | yes | GNOME | yes | [[Gentoo|http://www.gentoo.org/proj/en/desktop/gnome/openrc-settingsd.xml]] | partially +[[initrd interface|http://www.freedesktop.org/wiki/Software/systemd/InitrdInterface]] | Environment, flag files | yes | yes | dracut, [[ArchLinux|ArchLinux]] | yes | [[ArchLinux|ArchLinux]] | no +[[Container interface|http://www.freedesktop.org/wiki/Software/systemd/ContainerInterface]] | Environment, Mounts | yes | yes | libvirt/LXC | yes | - | no +[[Boot Loader interface|http://www.freedesktop.org/wiki/Software/systemd/BootLoaderInterface]] | EFI variables | yes | yes | gummiboot | yes | - | no +[[Service bus API|http://www.freedesktop.org/wiki/Software/systemd/dbus]] | D-Bus | yes | yes | system-config-services | no | - | no +[[logind|http://www.freedesktop.org/wiki/Software/systemd/logind]] | D-Bus | yes | yes | GNOME | no | - | no +[[sd-login.h API|http://0pointer.de/public/systemd-man/sd-login.html]] | C Library | yes | yes | GNOME, [[PolicyKit|PolicyKit]], ... | no | - | no +[[sd-daemon.h API|http://0pointer.de/public/systemd-man/sd-daemon.html]] | C Library or Drop-in | yes | yes | numerous | yes | - | yes +[[sd-id128.h API|http://0pointer.de/public/systemd-man/sd-id128.html]] | C Library | yes | yes | - | yes | - | no +[[sd-journal.h API|http://0pointer.de/public/systemd-man/sd-journal.html]] | C Library | yes | yes | - | maybe | - | no +[[sd-readahead.h API|http://0pointer.de/public/systemd-man/sd-readahead.html]] | C Drop-in | yes | yes | - | yes | - | yes +[[$XDG_RUNTIME_DIR|http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html]] | Environment | yes | yes | glib, GNOME | yes | - | no +[[$LISTEN_FDS/$LISTEN_PID FD Passing|http://0pointer.de/public/systemd-man/sd_listen_fds.html]] | Environment | yes | yes | numerous (via sd-daemon.h) | yes | - | no +[[$NOTIFY_SOCKET Daemon Notifications|http://0pointer.de/public/systemd-man/sd_notify.html]] | Environment | yes | yes | a few, including udev | yes | - | no +[[argv[0][0]='@' Logic|http://www.freedesktop.org/wiki/Software/systemd/RootStorageDaemons]] | /proc marking | yes | yes | mdadm | yes | - | no +[[Unit file format|http://0pointer.de/public/systemd-man/systemd.unit.html]] | File format | yes | yes | numerous | no | - | no +[[Journal File Format|http://www.freedesktop.org/wiki/Software/systemd/journal-files]] | File format | yes | yes | - | maybe | - | no +[[Journal Export Format|http://www.freedesktop.org/wiki/Software/systemd/export]] | File format | yes | yes | - | yes | - | no +[[Cooperation in cgroup tree|http://www.freedesktop.org/wiki/Software/systemd/PaxControlGroups]] | Treaty | yes | yes | libvirt | yes | libvirt | no +[[Password Agents|http://www.freedesktop.org/wiki/Software/systemd/PasswordAgents]] | Socket+Files | yes | yes | - | yes | - | no +[[udev multi-seat properties|http://www.freedesktop.org/wiki/Software/systemd/multiseat]] | udev Property | yes | yes | X11, gdm | no | - | no +udev session switch ACL properties | udev Property | no | no | - | no | - | no +[[CLI of systemctl,...|http://0pointer.de/public/systemd-man/systemctl.html]] | CLI | yes | yes | numerous | no | - | no +[[/etc/tmpfiles.d|http://0pointer.de/public/systemd-man/tmpfiles.d.html]] | File format | yes | yes | numerous | yes | [[ArchLinux|ArchLinux]] | partially +[[/etc/machine-id|http://0pointer.de/public/systemd-man/machine-id.html]] | File format | yes | yes | D-Bus | yes | - | no +[[/etc/binfmt.d|http://0pointer.de/public/systemd-man/binfmt.d.html]] | File format | yes | yes | numerous | yes | - | partially +[[/etc/hostname|http://0pointer.de/public/systemd-man/hostname.html]] | File format | yes | yes | numerous (it's a Debian thing) | yes | Debian, [[ArchLinux|ArchLinux]] | no +[[/etc/locale.conf|http://0pointer.de/public/systemd-man/locale.conf.html]] | File format | yes | yes | - | yes | [[ArchLinux|ArchLinux]] | partially +[[/etc/machine-info|http://0pointer.de/public/systemd-man/machine-info.html]] | File format | yes | yes | - | yes | - | partially +[[/etc/modules-load.d|http://0pointer.de/public/systemd-man/modules-load.d.html]] | File format | yes | yes | numerous | yes | - | partially +[[/etc/os-release|http://0pointer.de/public/systemd-man/os-release.html]] | File format | yes | yes | some | yes | Fedora, OpenSUSE, [[ArchLinux|ArchLinux]], Angstrom, Frugalware, others... | no +[[/etc/sysctl.d|http://0pointer.de/public/systemd-man/sysctl.d.html]] | File format | yes | yes | some (it's a Debian thing) | yes | procps/Debian, [[ArchLinux|ArchLinux]] | partially +[[/etc/timezone|http://0pointer.de/public/systemd-man/timezone.html]] | File format | yes | yes | numerous (it's a Debian thing) | yes | Debian | partially +[[/etc/vconsole.conf|http://0pointer.de/public/systemd-man/vconsole.conf.html]] | File format | yes | yes | - | yes | [[ArchLinux|ArchLinux]] | partially +/run | File hierarchy change | yes | yes | numerous | yes | OpenSUSE, Debian, [[ArchLinux|ArchLinux]] | no +[[Generators|http://www.freedesktop.org/wiki/Software/systemd/Generators]] | Subprocess | yes | yes | - | no | - | no +[[System Updates|http://freedesktop.org/wiki/Software/systemd/SystemUpdates]] | System Mode | yes | yes | - | no | - | no +[[Presets|http://freedesktop.org/wiki/Software/systemd/Preset]] | File format | yes | yes | - | no | - | no +Udev rules | File format | yes | yes | numerous | no | no | partially +"""]] + + +### Explanations + +Items for which "systemd implementation portable to other OSes" is "partially" means that it is possible to run the respective tools that are included in the systemd tarball outside of systemd. Note however that this is not officially supported, so you are more or less on your own if you do this. If you are opting for this solution simply build systemd as you normally would but drop all files except those which you are interested in. + +Of course, it is our intention to eventually document all interfaces we defined. If we haven't documented them for now, this is usually because we want the flexibility to still change things, or don't want 3rd party applications to make use of these interfaces already. That said, our sources are quite readable and open source, so feel free to spelunk around in the sources if you want to know more. + +If you decide to reimplement one of the APIs for which "Reimplementable independently" is "no", then we won't stop you, but you are on your own. + +This is not an attempt to comprehensively list all users of these APIs. We are just listing the most obvious/prominent ones which come to our mind. + +Of course, one last thing I can't make myself not ask you before we finish here, and before you start reimplementing these APIs in your distribution: are you sure it's time well spent if you work on reimplementing all this code instead of just spending it on adopting systemd on your distro as well? diff --git a/Software/systemd/InterfaceStabilityPromise.mdwn b/Software/systemd/InterfaceStabilityPromise.mdwn new file mode 100644 index 00000000..1c5c1d2d --- /dev/null +++ b/Software/systemd/InterfaceStabilityPromise.mdwn @@ -0,0 +1,24 @@ + +[[Back to systemd|http://www.freedesktop.org/wiki/Software/systemd/]] + +systemd provides various interfaces developers and programs might rely on. Starting with version 26 (the first version released with Fedora 15) we promise to keep a number of them stable and compatible for the future. The stable interfaces are: + +* The unit configuration file format. Unit files written now will stay compatible with future versions of systemd. Extensions to the file format will happen in a way that existing files remain compatible. +* The command line interface of systemctl, loginctl, journalctl. We will make sure that scripts invoking these commands will continue to work with future versions of systemd. Note however that the output generated by these commands is generally not included in the promise, unless it is documented in the man page. Example: the output of "systemctl status" is not stable, but the one of "systemctl show" is, because the former is intended to be human readable and the latter computer readable, and this is documented in the man page. +* The protocol spoken on the socket referred to by $NOTIFY_SOCKET, as documented in sd_notify(3). +* Some of the "special" unit names and their semantics. To be precise the ones that are necessary for normal services, and not those required only for early boot and late shutdown, with very few exceptions. To list them here: basic.target, shutdown.target, socket.target, bluetooth.target, syslog.target, network.target, getty.target, graphical.target, multi-user.target, rescue.target, emergency.target, mail-transfer-agent.target, poweroff.target, reboot.target, halt.target, runlevel[1-5].target, smartcard.target. +* For a more comprehensive and authoritative list, consult the [[Interface Portability And Stability Chart|http://www.freedesktop.org/wiki/Software/systemd/InterfacePortabilityAndStabilityChart]] +The following interfaces will not necessarily be kept stable for now, but we will eventually make a stability promise for these interfaces too. In the meantime we will however try to keep breakage of these interfaces at a minimum: + +* The D-Bus interfaces of the main service daemon (!) [ An additional restriction applies here: functionality we consider legacy might not be available based on compile-time options, such as SysV support, libwrap support and similar. Apps should not assume properties and methods related to this functionality are unconditionally available in the D-Bus interfaces. ] +* The set of states of the various state machines used in systemd, e.g. the high-level unit states inactive, active, deactivating, and so on, as well (and in particular) the low-level per-unit states. +* All "special" units that aren't listed above. +The following interfaces are considered private to systemd, and are not and will not be covered by any stability promise: + +* Undocumented switches to systemd, systemctl and otherwise +* The internal protocols used on the various sockets such as the sockets /run/systemd/shutdown, /run/systemd/private. +One of the main goals of systemd is to unify basic Linux configurations and service behaviors across all distributions. For facilities systemd provides a replacement for the various distribution specific configuration flavors, the current #ifdef TARGET_XXX style compatibility will eventually be removed from the systemd code in the future. In such case, there will be releases with warnings added, and later the entire code be removed. Distributions are expected to convert over time their individual configurations to the systemd Linux version, or they will need to carry and maintain these as patches in their package if they still decide to stay different. + +What does this mean for you? When developing with systemd, don't use any of the latter interfaces, or we will tell your mom, and she won't love you anymore. You are welcome to use the other interfaces listed here, but if you use any of the second kind (i.e. those where we don't yet make a stability promise), then make sure to subscribe to our mailing list, where we will announce API changes, and be prepared to update your program eventually. + +Note that this is a promise, not an eternal guarantee. These are our intentions, but if in the future there are very good reasons to change or get rid of an interface we have listed above as stable, then we might take the liberty to do so, despite this promise. However, if we do this, then we'll do our best to provide a smooth and reasonably long transition phase. diff --git a/Software/systemd/MinimalBuilds.mdwn b/Software/systemd/MinimalBuilds.mdwn new file mode 100644 index 00000000..f0c69acd --- /dev/null +++ b/Software/systemd/MinimalBuilds.mdwn @@ -0,0 +1,15 @@ + +[[Back to systemd|http://www.freedesktop.org/wiki/Software/systemd/]] + + +# Minimal Builds + +systemd includes a variety of components. The core components are always built (which includes systemd itself, as well as udevd and journald). Many of the other components can be disabled at compile time with configure switches. + +For some uses the configure switches do not provide sufficient modularity. For example, they cannot be used to build only the man pages, or to build only the tmpfiles tool, only detect-virt or only udevd. If such modularity is required that goes beyond what we support in the configure script we can suggest you two options: + +1. Build systemd as usual, but pick only the built files you need from the result of "make install DESTDIR=<directory>", by using the file listing functionality of your packaging software. For example: if all you want is the tmpfiles tool, then build systemd normally, and list only /usr/bin/systemd-tmpfiles in the .spec file for your RPM package. This is simple to do, allows you to pick exactly what you need, but requires a larger number of build dependencies (but not runtime dependencies). +1. If you want to reduce the build time dependencies (though only dbus and libcap are needed as build time deps) and you know the specific component you are interested in doesn't need it, then create a dummy .pc file for that dependency (i.e. basically empty), and configure systemd with PKG_CONFIG_PATH set to the path of these dummy .pc files. Then, build only the few bits you need with "make foobar", where foobar is the file you need. +We are open to merging patches for the build system that make more "fringe" components of systemd optional. However, please be aware that in order to keep the complexity of our build system small and its readability high, and to make our lives easier, we will not accept patches that make the minimal core components optional, i.e. systemd itself, journald and udevd. + +Note that the .pc file trick mentioned above currently doesn't work for libcap, since libcap doesn't provide a .pc file. We invite you to go ahead and post a patch to libcap upstream to get this corrected. We'll happily change our build system to look for that .pc file then. (a .pc file has been sent to upstream by Bryan Kadzban. It is also available at [[http://kdzbn.homelinux.net/libcap-add-pkg-config.patch|http://kdzbn.homelinux.net/libcap-add-pkg-config.patch]]) diff --git a/Software/systemd/MyServiceCantGetRealtime.mdwn b/Software/systemd/MyServiceCantGetRealtime.mdwn new file mode 100644 index 00000000..09b0761c --- /dev/null +++ b/Software/systemd/MyServiceCantGetRealtime.mdwn @@ -0,0 +1,28 @@ + +[[Back to systemd|http://www.freedesktop.org/wiki/Software/systemd/]] + + +# My Service Can't Get Realtime! + +_So, you have a service that requires real-time scheduling. When you run this service on your systemd system it is unable to acquire real-time scheduling, even though it is full root and has all possible privileges. And now you are wondering what is going on and what you can do about it?_ + + +## What is Going on? + +By default systemd places all system services into their own control groups in the "cpu" hierarchy. This has the benefit that the CPU usage of services with many worker threads or processes (think: Apache with all its gazillion CGIs and stuff) gets roughly the same amount of CPU as a service with very few worker threads (think: MySQL). Instead of evening out CPU _per process_ this will cause CPU to be evened out _per service_. + +Now, the "cpu" cgroup controller of the Linux kernel has one major shortcoming: if a cgroup is created it needs an explicit, absolute RT time budget assigned, or otherwise RT is not available to any process in the group, and an attempt to acquire it will fail with EPERM. systemd will not assign any RT time budgets to the "cpu" cgroups it creates, simply because there is no feasible way to do that, since the budget needs to be specified in absolute time units and comes from a fixed pool. Or in other words: we'd love to assign a budget, but there are no sane values we could use. Thus, in its default configuration RT scheduling is simply not available for any system services. + + +## Working Around the Issue + +Of course, that's quite a limitation, so here's how you work around this: + +* One option is to simply globally turn off that systemd creates a "cpu" cgroup for each of the system services. For that, edit `/etc/systemd/system.conf` and set `DefaultControllers=` to the empty string, then reboot. (An alternative is to disable the "cpu" controller in your kernel, entirely. systemd will not attempt to make use of controllers that aren't available in the kernel.) +* Another option is to turn this off for the specific service only. For that, edit your service file, and add `ControlGroup=cpu:/` to its `[Service]` section. This overrides the default logic for this one service only, and places all its processes back in the root cgroup of the "cpu" hierarchy, which has the full RT budget assigned. +* A third option is to simply assign your service a realtime budget. For that use `ControlGroupAttribute=cpu.rt_runtime_us 500000` in its `[Service]` or suchlike. See [[the kernel documentation|http://www.kernel.org/doc/Documentation/scheduler/sched-design-CFS.txt]] for details. +The latter two options are not available for System V services. A possible solution is to write a small wrapper service file that simply calls the SysV script's start verb in `ExecStart=` and the stop verb in `ExecStop=`. (It also needs to set `RemainAfterExit=1` and `Type=forking`!) + +Note that this all only applies to services. By default, user applications run in the root cgroup of the "cpu" hierarchy, which avoids these problems for normal user applications. + +In the long run we hope that the kernel is fixed to not require an RT budget to be assigned for any cgroup created before a process can acquire RT (i.e. a process' RT budget should be derived from the nearest ancestor cgroup which has a budget assigned, rather than unconditionally its own uninitialized budget.) Ideally, we'd also like to create a per-user cgroup by default, so that users with many processes get roughly the same amount of CPU as users with very few. diff --git a/Software/systemd/NetworkTarget.mdwn b/Software/systemd/NetworkTarget.mdwn new file mode 100644 index 00000000..84a313cb --- /dev/null +++ b/Software/systemd/NetworkTarget.mdwn @@ -0,0 +1,54 @@ + +[[Back to systemd|http://www.freedesktop.org/wiki/Software/systemd/]] + + +# Running Services After the Network is up + +_So you have configured your service to run after `network.target` but it still gets run before your network is up? And now you are wondering why that is and what you can do about it?_ + +The `network.target` unit is the systemd counterpart of LSB's `$network` facility. However as this facility is defined [[only very unprecisely|http://refspecs.linuxbase.org/LSB_3.1.1/LSB-Core-generic/LSB-Core-generic/facilname.html]] people tend to have different ideas what it is supposed to mean. Here are a couple of ideas people came up with so far: + +* All "configured" network interfaces are up and an IP address has been assigned to each +* All discovered local hardware interfaces that have a link beat have an IP address assigned, independently whether there is actually any explicit local configuration for them +* The network has been set up precisely to the level that a DNS server is reachable +* Similar, but some specific site-specific server is reachable +* Similar, but "the Internet" is reachable +* All "configured" ethernet devices are up, but all "configured" PPP links which are supposed to also start at boot don't have to be yet +* A certain "profile" is enabled and some condition of the above holds. If another "profile" is enabled a different condition would have to be checked +* Based on the location of the system a different set of configuration should be up or checked for +* At least one global IPv4 address is configured +* At least one global IPv6 address is configured +* At least one global IPv4 or IPv6 address is configured +And so on and so on. All these are valid approaches to the question "When is the network up?", but none of them would be useful to be good as generic default. + +Modern networking tends to be highly dynamic: machines are moved between networks, network configuration changes, hardware is added and removed, virtual networks are set up, reconfigured and shut down again. Network connectivity is not unconditionally and continuously available, and a machine is connected to different networks at different times. This is particularly true for mobile hardware such as handsets, tablets and laptops, but also for embedded and servers. Software that is written under the assumption that network connectivity is available continuously and never changes is hence not up-to-date with modern standards. Well-written software should be able to handle dynamic configuration changes. It should react to changing network configuration and make the best of it. If it cannot reach a server it must retry. If network configuration connectivity is lost it must react. Reacting to local network configuration changes in daemon code is not particularly hard. In fact many well-known network-facing services running on Linux have been doing this for decades. A service written like this is robust, can be started at any time, and will always do the best of the circumstances it is running in. + +`network.target` is a mechanism that is required only to deal with software that assumes continuous network is available (i.e. of the simple non-well-written kind). Which facet of it it requires is undefined. An IMAP server might just require a certain IP to be assigned so that it can listen on it. OTOH a network file system client might need DNS up, and the service to contact up, as well. For `network.target` what precisely is required is not obvious and can be different things depending on local configuration. + +A robust system boots up independently of external services. More specifically, if a network DHCP server does not react this should not slow down boot on most setups, but only for those where network connectivity is strictly needed (for example, because the host actually boots from the network). + +In systemd `network.target` by default does not have much meaning. If a service orders itself after it this will have little effect, by default. It is up to the admin to actually fill `network.target` with sense, i.e. order a service before it that waits until the "network is up" based on the policy the admin chooses, based on the needs of the software that shall be ordered after it and its configuration. By defaulting to the empty meaning we hence provide a speedy boot that is not slowed down by external factors for the majority of cases, but by allowing `network.target` to be defined by the administrator as he likes any policy is implementable instead. + + +## Cut the crap! How do I make network.target work for me? + +Well, that depends on your setup and the services you plan to run after it (see above). If you use NetworkManager one option is to enable `NetworkManager-wait-online.service`: + + +[[!format txt """ +systemctl enable NetworkManager-wait-online.service +"""]] +This will ensure that all configured network devices are up and have an IP address assigned before boot continues. This service will time out after 90s. Enabling this service might considerably delay your boot even if the timeout is not reached. + +Alternatively, you can write your own service file wrapping any other program or script you like and simply order it before `network.target` (with Before=). Your service also needs to pull in `network.target` (with Wants=), to indicate that it implements this target. + + +## What does this mean for me, a Developer? + +If you are a developer, instead of wondering what to do about `network.target`, please just fix your program to be friendly to dynamically changing network configuration. That way you will make your users happy because things just start to work, and you will get fewer bug reports as your stuff is just rock solid. You also make the boot faster for your users, as they don't have to delay arbitrary services for the network anymore (which is particularly annoying for folks with slow address assignment replies from a DHCP server). + +Here are a couple of possible approaches: + +* Watch [[rtnetlink|https://www.kernel.org/doc/man-pages/online/pages/man7/rtnetlink.7.html]] and react properly to network configuration changes as they happen. This is usually the nicest solution, but not always the easiest. +* If you write a server: listen on 0.0.0.0 and 127.0.0.1 only. These pseudo-addresses are unconditionally available. If you always bind to these addresses you will have code that doesn't have to react to network changes, as all you listen on is catch-all and private addresses. +* If you write a server: if you want to listen on other, explicitly configured addresses, consider using the [[IP_FREEBIND sockopt|https://www.kernel.org/doc/man-pages/online/pages/man7/ip.7.html]] functionality of the Linux kernel. This allows your code to bind to an address even if it is not actually (yet or ever) configured locally. This also makes your code robust towards network configuration changes.
\ No newline at end of file diff --git a/Software/systemd/OSUpgrade.mdwn b/Software/systemd/OSUpgrade.mdwn new file mode 100644 index 00000000..41c0e1b2 --- /dev/null +++ b/Software/systemd/OSUpgrade.mdwn @@ -0,0 +1,2 @@ + +Please continue to [[this page|http://freedesktop.org/wiki/Software/systemd/SystemUpdates]]. diff --git a/Software/systemd/Optimizations.mdwn b/Software/systemd/Optimizations.mdwn new file mode 100644 index 00000000..82a6fe9e --- /dev/null +++ b/Software/systemd/Optimizations.mdwn @@ -0,0 +1,52 @@ + +[[Back to systemd|http://www.freedesktop.org/wiki/Software/systemd/]] + + +# systemd Optimizations + +_So you are working on a Linux distribution or appliance and need very fast boot-ups?_ + +systemd can already offer boot times of < 1s for the Core OS (userspace only, i.e. only the bits controlled by systemd) and < 2s for a complete up-to-date desktop environments on simpler (but modern, i.e. SSDs) laptops if configured properly (examples: [[http://git.fenrus.org/tmp/bootchart-20120512-1036.svg|http://git.fenrus.org/tmp/bootchart-20120512-1036.svg]]). In this page we want to suggest a couple of ideas how to achieve that, and if the resulting boot times do not suffice where we believe room for improvements are that we'd like to see implemented sooner or later. If you are interested in investing engineering manpower in systemd to get to even shorter boot times, this list hopefully includes a few good suggestions to start with. + +Of course, before optimizing you should instrument the boot to generate profiling data, so make sure you know your way around with systemd-bootchart, systemd-analyze and pytimechart! Optimizations without profiling are premature optimizations! + +Note that systemd's fast performance is a side effect of its design but wasn't the primary design goal. As it stands now systemd (and Fedora using it) has been optimized very little and still has a lot of room for improvements. There are still many low hanging fruits to pick! + +We are very interested in merging optimization work into systemd upstream. Note however that we are careful not to merge work that would drastically limit the general purpose usefulness or reliability of our code, or that would make systemd harder to maintain. So in case you work on optimizations for systemd, try to keep your stuff mainlineable. If in doubt, ask us. + +The distributions have adopted systemd to varying levels. While there are many compatibility scripts in the boot process on Debian for example, Fedora has much less (but still too many). For better performance consider disabling these scripts, or using a different distribution. + +It is our intention to optimize the upstream distributions by default (in particular Fedora) so that these optimizations won't be necessary. However, this will take some time, especially since making these changes is often not trivial when the general purpose usefulness cannot be compromised. + +What you can optimize (locally) without writing any code: + +1. Make sure not to use any fake block device storage technology such as LVM (as installed by default by various distributions, including Fedora) they result in the systemd-udev-settle.service unit to be pulled in. Settling device enumeration is slow, racy and mostly obsolete. Since LVM (still) hasn't been updated to handle Linux' event based design properly, settling device enumeration is still required for it, but it will slow down boot substantially. On Fedora, use "systemctl mask fedora-wait-storage.service fedora-storage-init-late.service fedora-storage-init.service" to get rid of all those storage technologies. Of course, don't try this if you actually installed your system with LVM. (The only fake block device storage technology that currently handles this all properly and doesn't require settling device enumerations is LUKS disk encryption.) +1. Consider bypassing the initrd, if you use one. On Fedora, make sure to install the OS on a plain disk without encryption, and without LVM/RAID/... (encrypted /home is fine) when doing this. Then, simply edit grub.conf and remove the initrd from your configuration, and change the root= kernel command line parameter so that it uses kernel device names instead of UUIDs, i.e. "root=sda5" or what is appropriate for your system. Also specify the root FS type with "rootfstype=ext4" (or as appropriate). Note that using kernel devices names is not really that nice if you have multiple hard disks, but if you are doing this for a laptop (i.e. with a single hdd), this should be fine. Note that you shouldn't need to rebuild your kernel in order to bypass the initrd. Distribution kernels (at least Fedora's) work fine with and without initrd, and systemd supports both ways to be started. +1. Consider disabling SELinux and auditing. We recommend leaving SELinux on, for security reasons, but truth be told you can save 100ms of your boot if you disable it. Use selinux=0 on the kernel cmdline. +1. Consider disabling Plymouth. If userspace boots in less than 1s, a boot splash is hardly useful, hence consider passing plymouth.enable=0 on the kernel command line. Plymouth is generally quite fast, but currently still forces settling device enumerations for graphics cards, which is slow. Disabling plymouth removes this bit of the boot. +1. Consider uninstalling syslog. The journal is used anyway on newer systemd systems, and is usually more than sufficient for desktops, and embedded, and even many servers. Just uninstall all syslog implementations and remember that "journalctl" will get you a pixel perfect copy of the classic /var/log/messages message log. To make journal logs persistent (i.e. so that they aren't lost at boot) make sure to run "mkdir -p /var/log/journal". +1. Consider masking a couple of redundant distribution boot scripts, that artificially slow down the boot. For example, on Fedora it's a good idea to mask fedora-autoswap.service fedora-configure.service fedora-loadmodules.service fedora-readonly.service. Also remove all LVM/RAID/FCOE/iSCSI related packages which slow down the boot substantially even if no storage of the specific kind is used (and if these RPMs can't be removed because some important packages require them, at least mask the respective services). +1. Console output is slow. So if you measure your boot times and ship your system, make sure to use "quiet" on the command line and disable systemd debug logging (if you enabled it before). +1. Consider removing cron from your system and use systemd timer units instead. Timer units currently have no support for calendar times (i.e. cannot be used to spawn things "at 6 am every Monday", but can do "run this every 7 days"), but for the usual /etc/cron.daily/, /etc/cron.weekly/, ... should be good enough, if the time of day of the execution doesn't matter (just add four small service and timer units for supporting these dirs. Eventually we might support these out of the box, but until then, just write your own scriplets for this). +1. If you work on an appliance, consider disabling readahead collection in the shipped devices, but leave readahead replay enabled. +1. If you work on an appliance, make sure to build all drivers you need into the kernel, since module loading is slow. If you build a distribution at least built all the stuff 90% of all people need into your kernel, i.e. at least USB, AHCI and HDA! +1. If it works, use libahci.ignore_sss=1 when booting. +1. Use a modern desktop that doesn't pull in ConsoleKit anymore. For example GNOME 3.4. +1. Get rid of a local MTA, if you are building a desktop or appliance. I.e. on Fedora remove the sendmail RPMs which are (still!) installed by default. +1. If you build an appliance, don't forget that various components of systemd are optional and may be disabled during build time, see "./configure --help" for details. For example, get rid of the virtual console setup if you never have local console users (this is a major source of slowness, actually). In addition, if you never have local users at all, consider disabling logind. And there are more components that are frequently unnecessary on appliances. +1. This goes without saying: the boot-up gets faster if you started less stuff at boot. So run "systemctl" and check if there's stuff you don't need and disable it, or even remove its package. +1. Don't use debug kernels. Debug kernels are slow. Fedora exclusively uses debug kernels during the development phase of each release. If you care about boot performance, either recompile these kernels with debugging turned off or wait for the final distribution release. It's a drastic difference. That also means that if you publish boot performance data of a Fedora pre-release distribution you are doing something wrong. ;-) +So much about the basics of how to get a quick boot. Now, here's an incomprehensive list of things we'd like to see improved in systemd (and elsewhere) over short or long and need a bit of hacking (sometimes more, and sometimes less): + +1. Get rid of systemd-cgroups-agent. Currently, whenever a systemd cgroup runs empty a tool "systemd-cgroups-agent" is invoked by the kernel which then notifies systemd about it. The need for this tool should really go away, which will save a number of forked processes at boot, and should make things faster (especially shutdown). This requires introduction of a new kernel interface to get notifications for cgroups running empty, for example via fanotify() on cgroupfs. +1. Make use of EXT4_IOC_MOVE_EXT in systemd's readahead implementation. This allows reordering/defragmentation of the files needed for boot. According to the data from [[http://e4rat.sourceforge.net/|http://e4rat.sourceforge.net/]] this might shorten the boot time to 40%. Implementation is not trivial, but given that we already support btrfs defragmentation and example code for this exists (e4rat as linked) should be fairly straightforward. +1. Compress readahead pack files with XZ or so. Since boot these days tends to be clearly IO bound (and not CPU bound) it might make sense to reduce the IO load for the pack file by compressing it. Since we already have a dependency on XZ we'd recommend using XZ for this. +1. Update the readahead logic to also precache directories (in addition to files). +1. Improve a couple of algorithms in the unit dependency graph calculation logic, as well as unit file loading. For example, right now when loading units we match them up with a subset of the other loaded units in order to add automatic dependencies between them where appropriate. Usually the set of units matched up is small, but the complexity is currently O(n^2), and this could be optimized. Since unit file loading and calculations in the dependency graphs is the only major, synchronous, computation-intensive bit of PID 1, and is executed before any services are started this should bring relevant improvements, especially on systems with big dependency graphs. +1. Add socket activation to X. Due to the special socket allocation semantics of X this is useful only for display :0. This should allow parallelization of X startup with its clients. +1. The usual housekeeping: get rid of shell-based services (i.e. SysV init scripts), replace them with unit files. Don't make use of Type=forking and ordering dependencies if possible, use socket activation with Type=simple instead. This allows drastically better parallelized start-up for your services. Also, if you cannot use socket activation, at least consider patching your services to support Type=notify in place of Type=forking. Consider making seldom used services activated on-demand (for example, printer services), and start frequently used services already at boot instead of delaying them until they are used. +1. Consider making use of systemd for the session as well, the way Tizen is doing this. This still needs some love in systemd upstream to be a smooth ride, but we definitely would like to go this way sooner or later, even for the normal desktops. +1. Add an option for service units to temporarily bump the CPU and IO priority of the startup code of important services. Note however, that we assume that this will not bring much and hence recommend looking into this only very late. Since boot-up tends to be IO bound, solutions such as readahead are probably more interesting than prioritizing service startup IO. Also, this would probably always require a certain amount of manual configuration since determining automatically which services are important is hard (if not impossible), because we cannot track properly which services other services wait for. +1. Same as the previous item, but temporarily lower the CPU/IO priority of the startups part of unimportant leaf services. This is probably more useful than 11 as it is easier to determine which processes don't matter. +1. Add a kernel sockopt for AF_UNIX to increase the maximum datagram queue length for SOCK_DGRAM sockets. This would allow us to queue substantially more logging datagrams in the syslog and journal sockets, and thus move the point where syslog/journal clients have to block before their message writes finish much later in the boot process. The current kernel default is rather low with 10. (As a temporary hack it is possible to increase /proc/sys/net/unix/max_dgram_qlen globally, but this has implications beyond systemd, and should probably be avoided.) The kernel patch to make this work is most likely trivial. In general, this should allow us to improve the level of parallelization between clients and servers for AF_UNIX sockets of type SOCK_DGRAM or SOCK_SEQPACKET. +Again: the list above contains things we'd like to see in systemd anyway. We didn't do much profiling for these features, but we have enough indication to assume that these bits will bring some improvements. But yeah, if you work on this, keep your profiling tools ready at all times. diff --git a/Software/systemd/Optimizations/bootchart b/Software/systemd/Optimizations/bootchart new file mode 100644 index 00000000..b1d01e56 --- /dev/null +++ b/Software/systemd/Optimizations/bootchart @@ -0,0 +1,5451 @@ +<?xml version="1.0" standalone="no"?> +<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> +<svg width="2255px" height="4180px" version="1.1" xmlns="http://www.w3.org/2000/svg"> + +<!-- This file is a bootchart SVG file. It is best rendered in a browser --> +<!-- such as Chrome/Chromium, firefox. Other applications that render --> +<!-- these files properly but much more slow are ImageMagick, gimp, --> +<!-- inkscape, etc.. To display the files on your system, just point --> +<!-- your browser to file:///var/log/ and click. This bootchart was --> + +<!-- generated by bootchart version 197, running with options: --> +<!-- hz="25.000000" n="500" --> +<!-- x="100.000000" y="20.000000" --> +<!-- rel="0" f="1" --> +<!-- p="0" e="0" --> +<!-- o="/var/log" i="/sbin/init" --> + +<defs> + <style type="text/css"> + <![CDATA[ + rect { stroke-width: 1; } + rect.cpu { fill: rgb(64,64,240); stroke-width: 0; fill-opacity: 0.7; } + rect.wait { fill: rgb(240,240,0); stroke-width: 0; fill-opacity: 0.7; } + rect.bi { fill: rgb(240,128,128); stroke-width: 0; fill-opacity: 0.7; } + rect.bo { fill: rgb(192,64,64); stroke-width: 0; fill-opacity: 0.7; } + rect.ps { fill: rgb(192,192,192); stroke: rgb(128,128,128); fill-opacity: 0.7; } + rect.krnl { fill: rgb(240,240,0); stroke: rgb(128,128,128); fill-opacity: 0.7; } + rect.box { fill: rgb(240,240,240); stroke: rgb(192,192,192); } + rect.clrw { stroke-width: 0; fill-opacity: 0.7;} + line { stroke: rgb(64,64,64); stroke-width: 1; } +// line.sec1 { } + line.sec5 { stroke-width: 2; } + line.sec01 { stroke: rgb(224,224,224); stroke-width: 1; } + line.dot { stroke-dasharray: 2 4; } + line.idle { stroke: rgb(64,64,64); stroke-dasharray: 10 6; stroke-opacity: 0.7; } + .run { font-size: 8; font-style: italic; } + text { font-family: Verdana, Helvetica; font-size: 10; } + text.sec { font-size: 8; } + text.t1 { font-size: 24; } + text.t2 { font-size: 12; } + text.idle { font-size: 18; } + ]]> + </style> +</defs> + +<g transform="translate(10,400)"> +<!-- IO utilization graph - In --> +<text class="t2" x="5" y="-15">IO utilization - read</text> +<rect class="box" x="0.000" y="0" width="2095.495" height="100.000" /> + <line class="sec5" x1="0.000" y1="0" x2="0.000" y2="100.000" /> + <text class="sec" x="0.000" y="-5.000" >0.0s</text> + <line class="sec01" x1="10.000" y1="0" x2="10.000" y2="100.000" /> + <line class="sec01" x1="20.000" y1="0" x2="20.000" y2="100.000" /> + <line class="sec01" x1="30.000" y1="0" x2="30.000" y2="100.000" /> + <line class="sec01" x1="40.000" y1="0" x2="40.000" y2="100.000" /> + <line class="sec01" x1="50.000" y1="0" x2="50.000" y2="100.000" /> + <line class="sec01" x1="60.000" y1="0" x2="60.000" y2="100.000" /> + <line class="sec01" x1="70.000" y1="0" x2="70.000" y2="100.000" /> + <line class="sec01" x1="80.000" y1="0" x2="80.000" y2="100.000" /> + <line class="sec01" x1="90.000" y1="0" x2="90.000" y2="100.000" /> + <line class="sec1" x1="100.000" y1="0" x2="100.000" y2="100.000" /> + <text class="sec" x="100.000" y="-5.000" >1.0s</text> + <line class="sec01" x1="110.000" y1="0" x2="110.000" y2="100.000" /> + <line class="sec01" x1="120.000" y1="0" x2="120.000" y2="100.000" /> + <line class="sec01" x1="130.000" y1="0" x2="130.000" y2="100.000" /> + <line class="sec01" x1="140.000" y1="0" x2="140.000" y2="100.000" /> + <line class="sec01" x1="150.000" y1="0" x2="150.000" y2="100.000" /> + <line class="sec01" x1="160.000" y1="0" x2="160.000" y2="100.000" /> + <line class="sec01" x1="170.000" y1="0" x2="170.000" y2="100.000" /> + <line class="sec01" x1="180.000" y1="0" x2="180.000" y2="100.000" /> + <line class="sec01" x1="190.000" y1="0" x2="190.000" y2="100.000" /> + <line class="sec1" x1="200.000" y1="0" x2="200.000" y2="100.000" /> + <text class="sec" x="200.000" y="-5.000" >2.0s</text> + <line class="sec01" x1="210.000" y1="0" x2="210.000" y2="100.000" /> + <line class="sec01" x1="220.000" y1="0" x2="220.000" y2="100.000" /> + <line class="sec01" x1="230.000" y1="0" x2="230.000" y2="100.000" /> + <line class="sec01" x1="240.000" y1="0" x2="240.000" y2="100.000" /> + <line class="sec01" x1="250.000" y1="0" x2="250.000" y2="100.000" /> + <line class="sec01" x1="260.000" y1="0" x2="260.000" y2="100.000" /> + <line class="sec01" x1="270.000" y1="0" x2="270.000" y2="100.000" /> + <line class="sec01" x1="280.000" y1="0" x2="280.000" y2="100.000" /> + <line class="sec01" x1="290.000" y1="0" x2="290.000" y2="100.000" /> + <line class="sec1" x1="300.000" y1="0" x2="300.000" y2="100.000" /> + <text class="sec" x="300.000" y="-5.000" >3.0s</text> + <line class="sec01" x1="310.000" y1="0" x2="310.000" y2="100.000" /> + <line class="sec01" x1="320.000" y1="0" x2="320.000" y2="100.000" /> + <line class="sec01" x1="330.000" y1="0" x2="330.000" y2="100.000" /> + <line class="sec01" x1="340.000" y1="0" x2="340.000" y2="100.000" /> + <line class="sec01" x1="350.000" y1="0" x2="350.000" y2="100.000" /> + <line class="sec01" x1="360.000" y1="0" x2="360.000" y2="100.000" /> + <line class="sec01" x1="370.000" y1="0" x2="370.000" y2="100.000" /> + <line class="sec01" x1="380.000" y1="0" x2="380.000" y2="100.000" /> + <line class="sec01" x1="390.000" y1="0" x2="390.000" y2="100.000" /> + <line class="sec1" x1="400.000" y1="0" x2="400.000" y2="100.000" /> + <text class="sec" x="400.000" y="-5.000" >4.0s</text> + <line class="sec01" x1="410.000" y1="0" x2="410.000" y2="100.000" /> + <line class="sec01" x1="420.000" y1="0" x2="420.000" y2="100.000" /> + <line class="sec01" x1="430.000" y1="0" x2="430.000" y2="100.000" /> + <line class="sec01" x1="440.000" y1="0" x2="440.000" y2="100.000" /> + <line class="sec01" x1="450.000" y1="0" x2="450.000" y2="100.000" /> + <line class="sec01" x1="460.000" y1="0" x2="460.000" y2="100.000" /> + <line class="sec01" x1="470.000" y1="0" x2="470.000" y2="100.000" /> + <line class="sec01" x1="480.000" y1="0" x2="480.000" y2="100.000" /> + <line class="sec01" x1="490.000" y1="0" x2="490.000" y2="100.000" /> + <line class="sec5" x1="500.000" y1="0" x2="500.000" y2="100.000" /> + <text class="sec" x="500.000" y="-5.000" >5.0s</text> + <line class="sec01" x1="510.000" y1="0" x2="510.000" y2="100.000" /> + <line class="sec01" x1="520.000" y1="0" x2="520.000" y2="100.000" /> + <line class="sec01" x1="530.000" y1="0" x2="530.000" y2="100.000" /> + <line class="sec01" x1="540.000" y1="0" x2="540.000" y2="100.000" /> + <line class="sec01" x1="550.000" y1="0" x2="550.000" y2="100.000" /> + <line class="sec01" x1="560.000" y1="0" x2="560.000" y2="100.000" /> + <line class="sec01" x1="570.000" y1="0" x2="570.000" y2="100.000" /> + <line class="sec01" x1="580.000" y1="0" x2="580.000" y2="100.000" /> + <line class="sec01" x1="590.000" y1="0" x2="590.000" y2="100.000" /> + <line class="sec1" x1="600.000" y1="0" x2="600.000" y2="100.000" /> + <text class="sec" x="600.000" y="-5.000" >6.0s</text> + <line class="sec01" x1="610.000" y1="0" x2="610.000" y2="100.000" /> + <line class="sec01" x1="620.000" y1="0" x2="620.000" y2="100.000" /> + <line class="sec01" x1="630.000" y1="0" x2="630.000" y2="100.000" /> + <line class="sec01" x1="640.000" y1="0" x2="640.000" y2="100.000" /> + <line class="sec01" x1="650.000" y1="0" x2="650.000" y2="100.000" /> + <line class="sec01" x1="660.000" y1="0" x2="660.000" y2="100.000" /> + <line class="sec01" x1="670.000" y1="0" x2="670.000" y2="100.000" /> + <line class="sec01" x1="680.000" y1="0" x2="680.000" y2="100.000" /> + <line class="sec01" x1="690.000" y1="0" x2="690.000" y2="100.000" /> + <line class="sec1" x1="700.000" y1="0" x2="700.000" y2="100.000" /> + <text class="sec" x="700.000" y="-5.000" >7.0s</text> + <line class="sec01" x1="710.000" y1="0" x2="710.000" y2="100.000" /> + <line class="sec01" x1="720.000" y1="0" x2="720.000" y2="100.000" /> + <line class="sec01" x1="730.000" y1="0" x2="730.000" y2="100.000" /> + <line class="sec01" x1="740.000" y1="0" x2="740.000" y2="100.000" /> + <line class="sec01" x1="750.000" y1="0" x2="750.000" y2="100.000" /> + <line class="sec01" x1="760.000" y1="0" x2="760.000" y2="100.000" /> + <line class="sec01" x1="770.000" y1="0" x2="770.000" y2="100.000" /> + <line class="sec01" x1="780.000" y1="0" x2="780.000" y2="100.000" /> + <line class="sec01" x1="790.000" y1="0" x2="790.000" y2="100.000" /> + <line class="sec1" x1="800.000" y1="0" x2="800.000" y2="100.000" /> + <text class="sec" x="800.000" y="-5.000" >8.0s</text> + <line class="sec01" x1="810.000" y1="0" x2="810.000" y2="100.000" /> + <line class="sec01" x1="820.000" y1="0" x2="820.000" y2="100.000" /> + <line class="sec01" x1="830.000" y1="0" x2="830.000" y2="100.000" /> + <line class="sec01" x1="840.000" y1="0" x2="840.000" y2="100.000" /> + <line class="sec01" x1="850.000" y1="0" x2="850.000" y2="100.000" /> + <line class="sec01" x1="860.000" y1="0" x2="860.000" y2="100.000" /> + <line class="sec01" x1="870.000" y1="0" x2="870.000" y2="100.000" /> + <line class="sec01" x1="880.000" y1="0" x2="880.000" y2="100.000" /> + <line class="sec01" x1="890.000" y1="0" x2="890.000" y2="100.000" /> + <line class="sec1" x1="900.000" y1="0" x2="900.000" y2="100.000" /> + <text class="sec" x="900.000" y="-5.000" >9.0s</text> + <line class="sec01" x1="910.000" y1="0" x2="910.000" y2="100.000" /> + <line class="sec01" x1="920.000" y1="0" x2="920.000" y2="100.000" /> + <line class="sec01" x1="930.000" y1="0" x2="930.000" y2="100.000" /> + <line class="sec01" x1="940.000" y1="0" x2="940.000" y2="100.000" /> + <line class="sec01" x1="950.000" y1="0" x2="950.000" y2="100.000" /> + <line class="sec01" x1="960.000" y1="0" x2="960.000" y2="100.000" /> + <line class="sec01" x1="970.000" y1="0" x2="970.000" y2="100.000" /> + <line class="sec01" x1="980.000" y1="0" x2="980.000" y2="100.000" /> + <line class="sec01" x1="990.000" y1="0" x2="990.000" y2="100.000" /> + <line class="sec5" x1="1000.000" y1="0" x2="1000.000" y2="100.000" /> + <text class="sec" x="1000.000" y="-5.000" >10.0s</text> + <line class="sec01" x1="1010.000" y1="0" x2="1010.000" y2="100.000" /> + <line class="sec01" x1="1020.000" y1="0" x2="1020.000" y2="100.000" /> + <line class="sec01" x1="1030.000" y1="0" x2="1030.000" y2="100.000" /> + <line class="sec01" x1="1040.000" y1="0" x2="1040.000" y2="100.000" /> + <line class="sec01" x1="1050.000" y1="0" x2="1050.000" y2="100.000" /> + <line class="sec01" x1="1060.000" y1="0" x2="1060.000" y2="100.000" /> + <line class="sec01" x1="1070.000" y1="0" x2="1070.000" y2="100.000" /> + <line class="sec01" x1="1080.000" y1="0" x2="1080.000" y2="100.000" /> + <line class="sec01" x1="1090.000" y1="0" x2="1090.000" y2="100.000" /> + <line class="sec1" x1="1100.000" y1="0" x2="1100.000" y2="100.000" /> + <text class="sec" x="1100.000" y="-5.000" >11.0s</text> + <line class="sec01" x1="1110.000" y1="0" x2="1110.000" y2="100.000" /> + <line class="sec01" x1="1120.000" y1="0" x2="1120.000" y2="100.000" /> + <line class="sec01" x1="1130.000" y1="0" x2="1130.000" y2="100.000" /> + <line class="sec01" x1="1140.000" y1="0" x2="1140.000" y2="100.000" /> + <line class="sec01" x1="1150.000" y1="0" x2="1150.000" y2="100.000" /> + <line class="sec01" x1="1160.000" y1="0" x2="1160.000" y2="100.000" /> + <line class="sec01" x1="1170.000" y1="0" x2="1170.000" y2="100.000" /> + <line class="sec01" x1="1180.000" y1="0" x2="1180.000" y2="100.000" /> + <line class="sec01" x1="1190.000" y1="0" x2="1190.000" y2="100.000" /> + <line class="sec1" x1="1200.000" y1="0" x2="1200.000" y2="100.000" /> + <text class="sec" x="1200.000" y="-5.000" >12.0s</text> + <line class="sec01" x1="1210.000" y1="0" x2="1210.000" y2="100.000" /> + <line class="sec01" x1="1220.000" y1="0" x2="1220.000" y2="100.000" /> + <line class="sec01" x1="1230.000" y1="0" x2="1230.000" y2="100.000" /> + <line class="sec01" x1="1240.000" y1="0" x2="1240.000" y2="100.000" /> + <line class="sec01" x1="1250.000" y1="0" x2="1250.000" y2="100.000" /> + <line class="sec01" x1="1260.000" y1="0" x2="1260.000" y2="100.000" /> + <line class="sec01" x1="1270.000" y1="0" x2="1270.000" y2="100.000" /> + <line class="sec01" x1="1280.000" y1="0" x2="1280.000" y2="100.000" /> + <line class="sec01" x1="1290.000" y1="0" x2="1290.000" y2="100.000" /> + <line class="sec1" x1="1300.000" y1="0" x2="1300.000" y2="100.000" /> + <text class="sec" x="1300.000" y="-5.000" >13.0s</text> + <line class="sec01" x1="1310.000" y1="0" x2="1310.000" y2="100.000" /> + <line class="sec01" x1="1320.000" y1="0" x2="1320.000" y2="100.000" /> + <line class="sec01" x1="1330.000" y1="0" x2="1330.000" y2="100.000" /> + <line class="sec01" x1="1340.000" y1="0" x2="1340.000" y2="100.000" /> + <line class="sec01" x1="1350.000" y1="0" x2="1350.000" y2="100.000" /> + <line class="sec01" x1="1360.000" y1="0" x2="1360.000" y2="100.000" /> + <line class="sec01" x1="1370.000" y1="0" x2="1370.000" y2="100.000" /> + <line class="sec01" x1="1380.000" y1="0" x2="1380.000" y2="100.000" /> + <line class="sec01" x1="1390.000" y1="0" x2="1390.000" y2="100.000" /> + <line class="sec1" x1="1400.000" y1="0" x2="1400.000" y2="100.000" /> + <text class="sec" x="1400.000" y="-5.000" >14.0s</text> + <line class="sec01" x1="1410.000" y1="0" x2="1410.000" y2="100.000" /> + <line class="sec01" x1="1420.000" y1="0" x2="1420.000" y2="100.000" /> + <line class="sec01" x1="1430.000" y1="0" x2="1430.000" y2="100.000" /> + <line class="sec01" x1="1440.000" y1="0" x2="1440.000" y2="100.000" /> + <line class="sec01" x1="1450.000" y1="0" x2="1450.000" y2="100.000" /> + <line class="sec01" x1="1460.000" y1="0" x2="1460.000" y2="100.000" /> + <line class="sec01" x1="1470.000" y1="0" x2="1470.000" y2="100.000" /> + <line class="sec01" x1="1480.000" y1="0" x2="1480.000" y2="100.000" /> + <line class="sec01" x1="1490.000" y1="0" x2="1490.000" y2="100.000" /> + <line class="sec5" x1="1500.000" y1="0" x2="1500.000" y2="100.000" /> + <text class="sec" x="1500.000" y="-5.000" >15.0s</text> + <line class="sec01" x1="1510.000" y1="0" x2="1510.000" y2="100.000" /> + <line class="sec01" x1="1520.000" y1="0" x2="1520.000" y2="100.000" /> + <line class="sec01" x1="1530.000" y1="0" x2="1530.000" y2="100.000" /> + <line class="sec01" x1="1540.000" y1="0" x2="1540.000" y2="100.000" /> + <line class="sec01" x1="1550.000" y1="0" x2="1550.000" y2="100.000" /> + <line class="sec01" x1="1560.000" y1="0" x2="1560.000" y2="100.000" /> + <line class="sec01" x1="1570.000" y1="0" x2="1570.000" y2="100.000" /> + <line class="sec01" x1="1580.000" y1="0" x2="1580.000" y2="100.000" /> + <line class="sec01" x1="1590.000" y1="0" x2="1590.000" y2="100.000" /> + <line class="sec1" x1="1600.000" y1="0" x2="1600.000" y2="100.000" /> + <text class="sec" x="1600.000" y="-5.000" >16.0s</text> + <line class="sec01" x1="1610.000" y1="0" x2="1610.000" y2="100.000" /> + <line class="sec01" x1="1620.000" y1="0" x2="1620.000" y2="100.000" /> + <line class="sec01" x1="1630.000" y1="0" x2="1630.000" y2="100.000" /> + <line class="sec01" x1="1640.000" y1="0" x2="1640.000" y2="100.000" /> + <line class="sec01" x1="1650.000" y1="0" x2="1650.000" y2="100.000" /> + <line class="sec01" x1="1660.000" y1="0" x2="1660.000" y2="100.000" /> + <line class="sec01" x1="1670.000" y1="0" x2="1670.000" y2="100.000" /> + <line class="sec01" x1="1680.000" y1="0" x2="1680.000" y2="100.000" /> + <line class="sec01" x1="1690.000" y1="0" x2="1690.000" y2="100.000" /> + <line class="sec1" x1="1700.000" y1="0" x2="1700.000" y2="100.000" /> + <text class="sec" x="1700.000" y="-5.000" >17.0s</text> + <line class="sec01" x1="1710.000" y1="0" x2="1710.000" y2="100.000" /> + <line class="sec01" x1="1720.000" y1="0" x2="1720.000" y2="100.000" /> + <line class="sec01" x1="1730.000" y1="0" x2="1730.000" y2="100.000" /> + <line class="sec01" x1="1740.000" y1="0" x2="1740.000" y2="100.000" /> + <line class="sec01" x1="1750.000" y1="0" x2="1750.000" y2="100.000" /> + <line class="sec01" x1="1760.000" y1="0" x2="1760.000" y2="100.000" /> + <line class="sec01" x1="1770.000" y1="0" x2="1770.000" y2="100.000" /> + <line class="sec01" x1="1780.000" y1="0" x2="1780.000" y2="100.000" /> + <line class="sec01" x1="1790.000" y1="0" x2="1790.000" y2="100.000" /> + <line class="sec1" x1="1800.000" y1="0" x2="1800.000" y2="100.000" /> + <text class="sec" x="1800.000" y="-5.000" >18.0s</text> + <line class="sec01" x1="1810.000" y1="0" x2="1810.000" y2="100.000" /> + <line class="sec01" x1="1820.000" y1="0" x2="1820.000" y2="100.000" /> + <line class="sec01" x1="1830.000" y1="0" x2="1830.000" y2="100.000" /> + <line class="sec01" x1="1840.000" y1="0" x2="1840.000" y2="100.000" /> + <line class="sec01" x1="1850.000" y1="0" x2="1850.000" y2="100.000" /> + <line class="sec01" x1="1860.000" y1="0" x2="1860.000" y2="100.000" /> + <line class="sec01" x1="1870.000" y1="0" x2="1870.000" y2="100.000" /> + <line class="sec01" x1="1880.000" y1="0" x2="1880.000" y2="100.000" /> + <line class="sec01" x1="1890.000" y1="0" x2="1890.000" y2="100.000" /> + <line class="sec1" x1="1900.000" y1="0" x2="1900.000" y2="100.000" /> + <text class="sec" x="1900.000" y="-5.000" >19.0s</text> + <line class="sec01" x1="1910.000" y1="0" x2="1910.000" y2="100.000" /> + <line class="sec01" x1="1920.000" y1="0" x2="1920.000" y2="100.000" /> + <line class="sec01" x1="1930.000" y1="0" x2="1930.000" y2="100.000" /> + <line class="sec01" x1="1940.000" y1="0" x2="1940.000" y2="100.000" /> + <line class="sec01" x1="1950.000" y1="0" x2="1950.000" y2="100.000" /> + <line class="sec01" x1="1960.000" y1="0" x2="1960.000" y2="100.000" /> + <line class="sec01" x1="1970.000" y1="0" x2="1970.000" y2="100.000" /> + <line class="sec01" x1="1980.000" y1="0" x2="1980.000" y2="100.000" /> + <line class="sec01" x1="1990.000" y1="0" x2="1990.000" y2="100.000" /> + <line class="sec5" x1="2000.000" y1="0" x2="2000.000" y2="100.000" /> + <text class="sec" x="2000.000" y="-5.000" >20.0s</text> + <line class="sec01" x1="2010.000" y1="0" x2="2010.000" y2="100.000" /> + <line class="sec01" x1="2020.000" y1="0" x2="2020.000" y2="100.000" /> + <line class="sec01" x1="2030.000" y1="0" x2="2030.000" y2="100.000" /> + <line class="sec01" x1="2040.000" y1="0" x2="2040.000" y2="100.000" /> + <line class="sec01" x1="2050.000" y1="0" x2="2050.000" y2="100.000" /> + <line class="sec01" x1="2060.000" y1="0" x2="2060.000" y2="100.000" /> + <line class="sec01" x1="2070.000" y1="0" x2="2070.000" y2="100.000" /> + <line class="sec01" x1="2080.000" y1="0" x2="2080.000" y2="100.000" /> + <line class="sec01" x1="2090.000" y1="0" x2="2090.000" y2="100.000" /> +<rect class="bi" x="89.905" y="41.918" width="4.008" height="58.082" /> +<rect class="bi" x="93.913" y="49.012" width="4.011" height="50.988" /> +<rect class="bi" x="97.924" y="50.364" width="4.026" height="49.636" /> +<rect class="bi" x="101.950" y="47.542" width="4.010" height="52.458" /> +<rect class="bi" x="105.960" y="43.518" width="4.008" height="56.482" /> +<rect class="bi" x="109.967" y="65.576" width="4.011" height="34.424" /> +<rect class="bi" x="113.978" y="60.952" width="4.008" height="39.048" /> +<rect class="bi" x="117.986" y="53.355" width="4.007" height="46.645" /> +<rect class="bi" x="121.993" y="39.844" width="4.007" height="60.156" /> +<rect class="bi" x="126.000" y="24.681" width="4.006" height="75.319" /> +<rect class="bi" x="130.006" y="8.843" width="4.007" height="91.157" /> +<rect class="bi" x="134.013" y="13.872" width="4.123" height="86.128" /> +<rect class="bi" x="138.135" y="7.236" width="4.006" height="92.764" /> +<rect class="bi" x="142.141" y="17.250" width="4.002" height="82.750" /> +<rect class="bi" x="146.144" y="29.710" width="4.009" height="70.290" /> +<rect class="bi" x="150.152" y="35.565" width="4.010" height="64.435" /> +<rect class="bi" x="154.163" y="32.953" width="4.008" height="67.047" /> +<rect class="bi" x="158.170" y="40.865" width="4.007" height="59.135" /> +<rect class="bi" x="162.177" y="41.345" width="4.008" height="58.655" /> +<rect class="bi" x="166.186" y="17.580" width="4.006" height="82.420" /> +<rect class="bi" x="170.191" y="11.680" width="4.007" height="88.320" /> +<rect class="bi" x="174.198" y="11.094" width="4.016" height="88.906" /> +<rect class="bi" x="178.214" y="21.979" width="4.024" height="78.021" /> +<rect class="bi" x="182.238" y="1.576" width="4.006" height="98.424" /> +<rect class="bi" x="186.244" y="0.000" width="4.006" height="100.000" /> + <text class="sec" x="195.250" y="15.000">108.41mb/sec</text> +<rect class="bi" x="190.250" y="21.498" width="4.006" height="78.502" /> +<rect class="bi" x="194.256" y="20.312" width="4.006" height="79.688" /> +<rect class="bi" x="198.262" y="1.726" width="4.006" height="98.274" /> +<rect class="bi" x="202.268" y="13.316" width="4.007" height="86.684" /> +<rect class="bi" x="206.275" y="33.704" width="4.006" height="66.296" /> +<rect class="bi" x="210.280" y="32.067" width="4.006" height="67.933" /> +<rect class="bi" x="214.286" y="31.347" width="4.007" height="68.653" /> +<rect class="bi" x="218.294" y="33.854" width="4.007" height="66.146" /> +<rect class="bi" x="222.300" y="59.451" width="4.009" height="40.549" /> +<rect class="bi" x="226.310" y="48.371" width="4.007" height="51.629" /> +<rect class="bi" x="230.317" y="17.775" width="4.010" height="82.225" /> +<rect class="bi" x="234.327" y="32.563" width="4.008" height="67.437" /> +<rect class="bi" x="238.335" y="29.995" width="4.009" height="70.005" /> +<rect class="bi" x="242.344" y="40.129" width="4.006" height="59.871" /> +<rect class="bi" x="246.350" y="20.537" width="4.008" height="79.463" /> +<rect class="bi" x="250.358" y="31.617" width="4.006" height="68.383" /> +<rect class="bi" x="254.363" y="54.091" width="4.006" height="45.909" /> +<rect class="bi" x="258.369" y="43.462" width="4.008" height="56.538" /> +<rect class="bi" x="262.377" y="46.149" width="4.009" height="53.851" /> +<rect class="bi" x="266.386" y="39.754" width="4.007" height="60.246" /> +<rect class="bi" x="270.393" y="60.051" width="4.007" height="39.949" /> +<rect class="bi" x="274.400" y="53.536" width="4.007" height="46.464" /> +<rect class="bi" x="278.406" y="58.805" width="4.008" height="41.195" /> +<rect class="bi" x="282.414" y="54.451" width="4.007" height="45.549" /> +<rect class="bi" x="286.422" y="49.602" width="4.006" height="50.398" /> +<rect class="bi" x="290.428" y="56.223" width="4.006" height="43.777" /> +<rect class="bi" x="294.434" y="61.222" width="4.007" height="38.778" /> +<rect class="bi" x="298.441" y="67.738" width="4.006" height="32.262" /> +<rect class="bi" x="302.446" y="73.172" width="4.007" height="26.828" /> +<rect class="bi" x="306.453" y="88.005" width="4.006" height="11.995" /> +<rect class="bi" x="310.459" y="97.073" width="4.009" height="2.927" /> +<rect class="bi" x="314.468" y="99.490" width="4.008" height="0.510" /> +<rect class="bi" x="318.476" y="99.490" width="4.007" height="0.510" /> +<rect class="bi" x="322.483" y="99.099" width="4.008" height="0.901" /> +<rect class="bi" x="326.491" y="99.460" width="4.009" height="0.540" /> +<rect class="bi" x="330.500" y="99.084" width="4.006" height="0.916" /> +<rect class="bi" x="334.506" y="99.084" width="4.008" height="0.916" /> +<rect class="bi" x="338.513" y="98.033" width="4.008" height="1.967" /> +<rect class="bi" x="342.521" y="96.217" width="4.008" height="3.783" /> +<rect class="bi" x="346.529" y="95.267" width="4.008" height="4.733" /> +<rect class="bi" x="350.538" y="95.237" width="4.010" height="4.763" /> +<rect class="bi" x="354.547" y="95.748" width="4.008" height="4.252" /> +<rect class="bi" x="358.555" y="95.748" width="4.007" height="4.252" /> +<rect class="bi" x="362.562" y="96.708" width="4.007" height="3.292" /> +<rect class="bi" x="366.569" y="97.774" width="4.007" height="2.226" /> +<rect class="bi" x="370.576" y="99.084" width="4.008" height="0.916" /> +<rect class="bi" x="374.584" y="99.114" width="4.006" height="0.886" /> +<rect class="bi" x="378.590" y="99.129" width="4.006" height="0.871" /> +<rect class="bi" x="382.596" y="99.129" width="4.007" height="0.871" /> +<rect class="bi" x="386.603" y="99.219" width="4.007" height="0.781" /> +<rect class="bi" x="422.684" y="99.895" width="4.012" height="0.105" /> +<rect class="bi" x="426.696" y="99.895" width="4.006" height="0.105" /> +<rect class="bi" x="430.702" y="99.895" width="4.006" height="0.105" /> +<rect class="bi" x="434.708" y="99.895" width="4.014" height="0.105" /> +<rect class="bi" x="438.722" y="99.895" width="4.008" height="0.105" /> +<rect class="bi" x="490.819" y="97.748" width="4.006" height="2.252" /> +<rect class="bi" x="494.825" y="76.925" width="4.006" height="23.075" /> +<rect class="bi" x="498.831" y="74.118" width="4.006" height="25.882" /> +<rect class="bi" x="502.838" y="73.412" width="4.006" height="26.588" /> +<rect class="bi" x="506.844" y="73.337" width="4.006" height="26.663" /> +<rect class="bi" x="510.850" y="72.046" width="4.008" height="27.954" /> +<rect class="bi" x="514.858" y="74.223" width="4.006" height="25.777" /> +<rect class="bi" x="518.864" y="93.184" width="4.006" height="6.816" /> +<rect class="bi" x="522.870" y="91.923" width="4.006" height="8.077" /> +<rect class="bi" x="526.876" y="92.629" width="4.007" height="7.371" /> +<rect class="bi" x="530.883" y="92.674" width="4.006" height="7.326" /> +<rect class="bi" x="534.889" y="93.965" width="4.006" height="6.035" /> +<rect class="bi" x="538.895" y="93.980" width="4.007" height="6.020" /> +<rect class="bi" x="542.902" y="95.887" width="4.009" height="4.113" /> +<rect class="bi" x="586.981" y="98.003" width="4.009" height="1.997" /> +<rect class="bi" x="590.990" y="97.523" width="4.008" height="2.477" /> +<rect class="bi" x="594.998" y="97.042" width="4.010" height="2.958" /> +<rect class="bi" x="599.008" y="97.042" width="4.006" height="2.958" /> +<rect class="bi" x="603.014" y="97.042" width="4.007" height="2.958" /> +<rect class="bi" x="607.021" y="96.562" width="4.009" height="3.438" /> +<rect class="bi" x="611.030" y="98.078" width="4.007" height="1.922" /> +<rect class="bi" x="615.037" y="96.637" width="4.009" height="3.363" /> +<rect class="bi" x="619.046" y="96.637" width="4.008" height="3.363" /> +<rect class="bi" x="623.054" y="96.637" width="4.007" height="3.363" /> +<rect class="bi" x="627.061" y="96.622" width="4.007" height="3.378" /> +<rect class="bi" x="631.068" y="97.103" width="4.007" height="2.897" /> +<rect class="bi" x="635.075" y="97.553" width="4.009" height="2.447" /> +<rect class="bi" x="639.084" y="98.994" width="4.006" height="1.006" /> +<rect class="bi" x="643.090" y="98.829" width="4.007" height="1.171" /> +<rect class="bi" x="647.097" y="98.829" width="4.007" height="1.171" /> +<rect class="bi" x="651.104" y="98.844" width="4.007" height="1.156" /> +<rect class="bi" x="655.111" y="98.844" width="4.006" height="1.156" /> +<rect class="bi" x="659.117" y="98.874" width="4.008" height="1.126" /> +<rect class="bi" x="663.125" y="99.354" width="4.008" height="0.646" /> +<rect class="bi" x="871.585" y="99.099" width="4.006" height="0.901" /> +<rect class="bi" x="875.591" y="96.607" width="4.006" height="3.393" /> +<rect class="bi" x="879.598" y="85.257" width="4.007" height="14.743" /> +<rect class="bi" x="883.605" y="74.824" width="4.006" height="25.176" /> +<rect class="bi" x="887.611" y="74.824" width="4.006" height="25.176" /> +<rect class="bi" x="891.617" y="74.824" width="4.009" height="25.176" /> +<rect class="bi" x="895.626" y="75.724" width="4.006" height="24.276" /> +<rect class="bi" x="899.632" y="78.216" width="4.006" height="21.784" /> +<rect class="bi" x="903.639" y="89.566" width="4.006" height="10.434" /> +<rect class="bi" x="1027.938" y="96.652" width="4.009" height="3.348" /> +<rect class="bi" x="1031.947" y="96.277" width="4.008" height="3.723" /> +<rect class="bi" x="1035.955" y="92.599" width="4.008" height="7.401" /> +<rect class="bi" x="1039.963" y="86.413" width="4.006" height="13.587" /> +<rect class="bi" x="1043.969" y="80.333" width="4.007" height="19.667" /> +<rect class="bi" x="1047.976" y="76.670" width="4.007" height="23.330" /> +<rect class="bi" x="1051.984" y="79.162" width="4.006" height="20.838" /> +<rect class="bi" x="1055.990" y="78.231" width="4.011" height="21.769" /> +<rect class="bi" x="1060.001" y="80.589" width="4.007" height="19.411" /> +<rect class="bi" x="1064.008" y="85.993" width="4.006" height="14.007" /> +<rect class="bi" x="1068.014" y="92.073" width="4.006" height="7.927" /> +<rect class="bi" x="1072.020" y="95.796" width="4.007" height="4.204" /> +<rect class="bi" x="1076.027" y="96.592" width="4.013" height="3.408" /> +<rect class="bi" x="1080.040" y="97.898" width="4.008" height="2.102" /> +<rect class="bi" x="1084.048" y="99.219" width="4.010" height="0.781" /> +<rect class="bi" x="1385.094" y="99.745" width="4.015" height="0.255" /> +<rect class="bi" x="1389.109" y="99.745" width="4.014" height="0.255" /> +<rect class="bi" x="1393.124" y="99.745" width="4.014" height="0.255" /> +<rect class="bi" x="1397.138" y="99.745" width="4.013" height="0.255" /> +<rect class="bi" x="1401.151" y="99.745" width="4.014" height="0.255" /> +<rect class="bi" x="1405.165" y="99.745" width="4.014" height="0.255" /> +<rect class="bi" x="1565.720" y="99.745" width="4.015" height="0.255" /> +<rect class="bi" x="1569.735" y="99.745" width="4.015" height="0.255" /> +<rect class="bi" x="1573.750" y="99.745" width="4.014" height="0.255" /> +<rect class="bi" x="1577.764" y="99.745" width="4.014" height="0.255" /> +<rect class="bi" x="1581.779" y="99.745" width="4.015" height="0.255" /> +<rect class="bi" x="1585.793" y="99.745" width="4.014" height="0.255" /> +<rect class="bi" x="1633.964" y="98.364" width="4.014" height="1.636" /> +<rect class="bi" x="1637.979" y="98.364" width="4.014" height="1.636" /> +<rect class="bi" x="1641.993" y="98.364" width="4.015" height="1.636" /> +<rect class="bi" x="1646.007" y="98.364" width="4.008" height="1.636" /> +<rect class="bi" x="1650.015" y="98.364" width="4.014" height="1.636" /> +<rect class="bi" x="1654.030" y="98.364" width="4.016" height="1.636" /> +<rect class="bi" x="1666.075" y="99.159" width="4.015" height="0.841" /> +<rect class="bi" x="1670.089" y="92.313" width="4.015" height="7.687" /> +<rect class="bi" x="1674.104" y="90.227" width="4.014" height="9.773" /> +<rect class="bi" x="1678.118" y="88.605" width="4.008" height="11.395" /> +<rect class="bi" x="1682.126" y="82.840" width="4.007" height="17.160" /> +<rect class="bi" x="1686.133" y="79.898" width="4.007" height="20.102" /> +<rect class="bi" x="1690.140" y="76.985" width="4.009" height="23.015" /> +<rect class="bi" x="1694.150" y="79.703" width="4.009" height="20.297" /> +<rect class="bi" x="1698.159" y="77.886" width="4.007" height="22.114" /> +<rect class="bi" x="1702.166" y="76.115" width="4.007" height="23.885" /> +<rect class="bi" x="1706.173" y="77.661" width="4.013" height="22.339" /> +<rect class="bi" x="1710.186" y="71.851" width="4.007" height="28.149" /> +<rect class="bi" x="1714.193" y="72.947" width="4.007" height="27.053" /> +<rect class="bi" x="1718.200" y="76.220" width="4.007" height="23.780" /> +<rect class="bi" x="1722.208" y="72.992" width="4.013" height="27.008" /> +<rect class="bi" x="1726.220" y="69.374" width="4.009" height="30.626" /> +<rect class="bi" x="1730.230" y="73.097" width="4.006" height="26.903" /> +<rect class="bi" x="1734.236" y="81.850" width="4.007" height="18.150" /> +<rect class="bi" x="1738.243" y="84.507" width="4.015" height="15.493" /> +<rect class="bi" x="1742.258" y="85.363" width="4.012" height="14.637" /> +<rect class="bi" x="1746.270" y="92.494" width="4.014" height="7.506" /> +<rect class="bi" x="1750.284" y="99.505" width="4.015" height="0.495" /> +<rect class="bi" x="1846.625" y="97.673" width="4.014" height="2.327" /> +<rect class="bi" x="1850.640" y="97.673" width="4.014" height="2.327" /> +<rect class="bi" x="1854.654" y="97.673" width="4.014" height="2.327" /> +<rect class="bi" x="1858.668" y="97.673" width="4.011" height="2.327" /> +<rect class="bi" x="1862.679" y="97.673" width="4.014" height="2.327" /> +<rect class="bi" x="1866.693" y="97.673" width="4.014" height="2.327" /> +</g> + +<g transform="translate(10,540.000)"> +<!-- IO utilization graph - out --> +<text class="t2" x="5" y="-15">IO utilization - write</text> +<rect class="box" x="0.000" y="0" width="2095.495" height="100.000" /> + <line class="sec5" x1="0.000" y1="0" x2="0.000" y2="100.000" /> + <text class="sec" x="0.000" y="-5.000" >0.0s</text> + <line class="sec01" x1="10.000" y1="0" x2="10.000" y2="100.000" /> + <line class="sec01" x1="20.000" y1="0" x2="20.000" y2="100.000" /> + <line class="sec01" x1="30.000" y1="0" x2="30.000" y2="100.000" /> + <line class="sec01" x1="40.000" y1="0" x2="40.000" y2="100.000" /> + <line class="sec01" x1="50.000" y1="0" x2="50.000" y2="100.000" /> + <line class="sec01" x1="60.000" y1="0" x2="60.000" y2="100.000" /> + <line class="sec01" x1="70.000" y1="0" x2="70.000" y2="100.000" /> + <line class="sec01" x1="80.000" y1="0" x2="80.000" y2="100.000" /> + <line class="sec01" x1="90.000" y1="0" x2="90.000" y2="100.000" /> + <line class="sec1" x1="100.000" y1="0" x2="100.000" y2="100.000" /> + <text class="sec" x="100.000" y="-5.000" >1.0s</text> + <line class="sec01" x1="110.000" y1="0" x2="110.000" y2="100.000" /> + <line class="sec01" x1="120.000" y1="0" x2="120.000" y2="100.000" /> + <line class="sec01" x1="130.000" y1="0" x2="130.000" y2="100.000" /> + <line class="sec01" x1="140.000" y1="0" x2="140.000" y2="100.000" /> + <line class="sec01" x1="150.000" y1="0" x2="150.000" y2="100.000" /> + <line class="sec01" x1="160.000" y1="0" x2="160.000" y2="100.000" /> + <line class="sec01" x1="170.000" y1="0" x2="170.000" y2="100.000" /> + <line class="sec01" x1="180.000" y1="0" x2="180.000" y2="100.000" /> + <line class="sec01" x1="190.000" y1="0" x2="190.000" y2="100.000" /> + <line class="sec1" x1="200.000" y1="0" x2="200.000" y2="100.000" /> + <text class="sec" x="200.000" y="-5.000" >2.0s</text> + <line class="sec01" x1="210.000" y1="0" x2="210.000" y2="100.000" /> + <line class="sec01" x1="220.000" y1="0" x2="220.000" y2="100.000" /> + <line class="sec01" x1="230.000" y1="0" x2="230.000" y2="100.000" /> + <line class="sec01" x1="240.000" y1="0" x2="240.000" y2="100.000" /> + <line class="sec01" x1="250.000" y1="0" x2="250.000" y2="100.000" /> + <line class="sec01" x1="260.000" y1="0" x2="260.000" y2="100.000" /> + <line class="sec01" x1="270.000" y1="0" x2="270.000" y2="100.000" /> + <line class="sec01" x1="280.000" y1="0" x2="280.000" y2="100.000" /> + <line class="sec01" x1="290.000" y1="0" x2="290.000" y2="100.000" /> + <line class="sec1" x1="300.000" y1="0" x2="300.000" y2="100.000" /> + <text class="sec" x="300.000" y="-5.000" >3.0s</text> + <line class="sec01" x1="310.000" y1="0" x2="310.000" y2="100.000" /> + <line class="sec01" x1="320.000" y1="0" x2="320.000" y2="100.000" /> + <line class="sec01" x1="330.000" y1="0" x2="330.000" y2="100.000" /> + <line class="sec01" x1="340.000" y1="0" x2="340.000" y2="100.000" /> + <line class="sec01" x1="350.000" y1="0" x2="350.000" y2="100.000" /> + <line class="sec01" x1="360.000" y1="0" x2="360.000" y2="100.000" /> + <line class="sec01" x1="370.000" y1="0" x2="370.000" y2="100.000" /> + <line class="sec01" x1="380.000" y1="0" x2="380.000" y2="100.000" /> + <line class="sec01" x1="390.000" y1="0" x2="390.000" y2="100.000" /> + <line class="sec1" x1="400.000" y1="0" x2="400.000" y2="100.000" /> + <text class="sec" x="400.000" y="-5.000" >4.0s</text> + <line class="sec01" x1="410.000" y1="0" x2="410.000" y2="100.000" /> + <line class="sec01" x1="420.000" y1="0" x2="420.000" y2="100.000" /> + <line class="sec01" x1="430.000" y1="0" x2="430.000" y2="100.000" /> + <line class="sec01" x1="440.000" y1="0" x2="440.000" y2="100.000" /> + <line class="sec01" x1="450.000" y1="0" x2="450.000" y2="100.000" /> + <line class="sec01" x1="460.000" y1="0" x2="460.000" y2="100.000" /> + <line class="sec01" x1="470.000" y1="0" x2="470.000" y2="100.000" /> + <line class="sec01" x1="480.000" y1="0" x2="480.000" y2="100.000" /> + <line class="sec01" x1="490.000" y1="0" x2="490.000" y2="100.000" /> + <line class="sec5" x1="500.000" y1="0" x2="500.000" y2="100.000" /> + <text class="sec" x="500.000" y="-5.000" >5.0s</text> + <line class="sec01" x1="510.000" y1="0" x2="510.000" y2="100.000" /> + <line class="sec01" x1="520.000" y1="0" x2="520.000" y2="100.000" /> + <line class="sec01" x1="530.000" y1="0" x2="530.000" y2="100.000" /> + <line class="sec01" x1="540.000" y1="0" x2="540.000" y2="100.000" /> + <line class="sec01" x1="550.000" y1="0" x2="550.000" y2="100.000" /> + <line class="sec01" x1="560.000" y1="0" x2="560.000" y2="100.000" /> + <line class="sec01" x1="570.000" y1="0" x2="570.000" y2="100.000" /> + <line class="sec01" x1="580.000" y1="0" x2="580.000" y2="100.000" /> + <line class="sec01" x1="590.000" y1="0" x2="590.000" y2="100.000" /> + <line class="sec1" x1="600.000" y1="0" x2="600.000" y2="100.000" /> + <text class="sec" x="600.000" y="-5.000" >6.0s</text> + <line class="sec01" x1="610.000" y1="0" x2="610.000" y2="100.000" /> + <line class="sec01" x1="620.000" y1="0" x2="620.000" y2="100.000" /> + <line class="sec01" x1="630.000" y1="0" x2="630.000" y2="100.000" /> + <line class="sec01" x1="640.000" y1="0" x2="640.000" y2="100.000" /> + <line class="sec01" x1="650.000" y1="0" x2="650.000" y2="100.000" /> + <line class="sec01" x1="660.000" y1="0" x2="660.000" y2="100.000" /> + <line class="sec01" x1="670.000" y1="0" x2="670.000" y2="100.000" /> + <line class="sec01" x1="680.000" y1="0" x2="680.000" y2="100.000" /> + <line class="sec01" x1="690.000" y1="0" x2="690.000" y2="100.000" /> + <line class="sec1" x1="700.000" y1="0" x2="700.000" y2="100.000" /> + <text class="sec" x="700.000" y="-5.000" >7.0s</text> + <line class="sec01" x1="710.000" y1="0" x2="710.000" y2="100.000" /> + <line class="sec01" x1="720.000" y1="0" x2="720.000" y2="100.000" /> + <line class="sec01" x1="730.000" y1="0" x2="730.000" y2="100.000" /> + <line class="sec01" x1="740.000" y1="0" x2="740.000" y2="100.000" /> + <line class="sec01" x1="750.000" y1="0" x2="750.000" y2="100.000" /> + <line class="sec01" x1="760.000" y1="0" x2="760.000" y2="100.000" /> + <line class="sec01" x1="770.000" y1="0" x2="770.000" y2="100.000" /> + <line class="sec01" x1="780.000" y1="0" x2="780.000" y2="100.000" /> + <line class="sec01" x1="790.000" y1="0" x2="790.000" y2="100.000" /> + <line class="sec1" x1="800.000" y1="0" x2="800.000" y2="100.000" /> + <text class="sec" x="800.000" y="-5.000" >8.0s</text> + <line class="sec01" x1="810.000" y1="0" x2="810.000" y2="100.000" /> + <line class="sec01" x1="820.000" y1="0" x2="820.000" y2="100.000" /> + <line class="sec01" x1="830.000" y1="0" x2="830.000" y2="100.000" /> + <line class="sec01" x1="840.000" y1="0" x2="840.000" y2="100.000" /> + <line class="sec01" x1="850.000" y1="0" x2="850.000" y2="100.000" /> + <line class="sec01" x1="860.000" y1="0" x2="860.000" y2="100.000" /> + <line class="sec01" x1="870.000" y1="0" x2="870.000" y2="100.000" /> + <line class="sec01" x1="880.000" y1="0" x2="880.000" y2="100.000" /> + <line class="sec01" x1="890.000" y1="0" x2="890.000" y2="100.000" /> + <line class="sec1" x1="900.000" y1="0" x2="900.000" y2="100.000" /> + <text class="sec" x="900.000" y="-5.000" >9.0s</text> + <line class="sec01" x1="910.000" y1="0" x2="910.000" y2="100.000" /> + <line class="sec01" x1="920.000" y1="0" x2="920.000" y2="100.000" /> + <line class="sec01" x1="930.000" y1="0" x2="930.000" y2="100.000" /> + <line class="sec01" x1="940.000" y1="0" x2="940.000" y2="100.000" /> + <line class="sec01" x1="950.000" y1="0" x2="950.000" y2="100.000" /> + <line class="sec01" x1="960.000" y1="0" x2="960.000" y2="100.000" /> + <line class="sec01" x1="970.000" y1="0" x2="970.000" y2="100.000" /> + <line class="sec01" x1="980.000" y1="0" x2="980.000" y2="100.000" /> + <line class="sec01" x1="990.000" y1="0" x2="990.000" y2="100.000" /> + <line class="sec5" x1="1000.000" y1="0" x2="1000.000" y2="100.000" /> + <text class="sec" x="1000.000" y="-5.000" >10.0s</text> + <line class="sec01" x1="1010.000" y1="0" x2="1010.000" y2="100.000" /> + <line class="sec01" x1="1020.000" y1="0" x2="1020.000" y2="100.000" /> + <line class="sec01" x1="1030.000" y1="0" x2="1030.000" y2="100.000" /> + <line class="sec01" x1="1040.000" y1="0" x2="1040.000" y2="100.000" /> + <line class="sec01" x1="1050.000" y1="0" x2="1050.000" y2="100.000" /> + <line class="sec01" x1="1060.000" y1="0" x2="1060.000" y2="100.000" /> + <line class="sec01" x1="1070.000" y1="0" x2="1070.000" y2="100.000" /> + <line class="sec01" x1="1080.000" y1="0" x2="1080.000" y2="100.000" /> + <line class="sec01" x1="1090.000" y1="0" x2="1090.000" y2="100.000" /> + <line class="sec1" x1="1100.000" y1="0" x2="1100.000" y2="100.000" /> + <text class="sec" x="1100.000" y="-5.000" >11.0s</text> + <line class="sec01" x1="1110.000" y1="0" x2="1110.000" y2="100.000" /> + <line class="sec01" x1="1120.000" y1="0" x2="1120.000" y2="100.000" /> + <line class="sec01" x1="1130.000" y1="0" x2="1130.000" y2="100.000" /> + <line class="sec01" x1="1140.000" y1="0" x2="1140.000" y2="100.000" /> + <line class="sec01" x1="1150.000" y1="0" x2="1150.000" y2="100.000" /> + <line class="sec01" x1="1160.000" y1="0" x2="1160.000" y2="100.000" /> + <line class="sec01" x1="1170.000" y1="0" x2="1170.000" y2="100.000" /> + <line class="sec01" x1="1180.000" y1="0" x2="1180.000" y2="100.000" /> + <line class="sec01" x1="1190.000" y1="0" x2="1190.000" y2="100.000" /> + <line class="sec1" x1="1200.000" y1="0" x2="1200.000" y2="100.000" /> + <text class="sec" x="1200.000" y="-5.000" >12.0s</text> + <line class="sec01" x1="1210.000" y1="0" x2="1210.000" y2="100.000" /> + <line class="sec01" x1="1220.000" y1="0" x2="1220.000" y2="100.000" /> + <line class="sec01" x1="1230.000" y1="0" x2="1230.000" y2="100.000" /> + <line class="sec01" x1="1240.000" y1="0" x2="1240.000" y2="100.000" /> + <line class="sec01" x1="1250.000" y1="0" x2="1250.000" y2="100.000" /> + <line class="sec01" x1="1260.000" y1="0" x2="1260.000" y2="100.000" /> + <line class="sec01" x1="1270.000" y1="0" x2="1270.000" y2="100.000" /> + <line class="sec01" x1="1280.000" y1="0" x2="1280.000" y2="100.000" /> + <line class="sec01" x1="1290.000" y1="0" x2="1290.000" y2="100.000" /> + <line class="sec1" x1="1300.000" y1="0" x2="1300.000" y2="100.000" /> + <text class="sec" x="1300.000" y="-5.000" >13.0s</text> + <line class="sec01" x1="1310.000" y1="0" x2="1310.000" y2="100.000" /> + <line class="sec01" x1="1320.000" y1="0" x2="1320.000" y2="100.000" /> + <line class="sec01" x1="1330.000" y1="0" x2="1330.000" y2="100.000" /> + <line class="sec01" x1="1340.000" y1="0" x2="1340.000" y2="100.000" /> + <line class="sec01" x1="1350.000" y1="0" x2="1350.000" y2="100.000" /> + <line class="sec01" x1="1360.000" y1="0" x2="1360.000" y2="100.000" /> + <line class="sec01" x1="1370.000" y1="0" x2="1370.000" y2="100.000" /> + <line class="sec01" x1="1380.000" y1="0" x2="1380.000" y2="100.000" /> + <line class="sec01" x1="1390.000" y1="0" x2="1390.000" y2="100.000" /> + <line class="sec1" x1="1400.000" y1="0" x2="1400.000" y2="100.000" /> + <text class="sec" x="1400.000" y="-5.000" >14.0s</text> + <line class="sec01" x1="1410.000" y1="0" x2="1410.000" y2="100.000" /> + <line class="sec01" x1="1420.000" y1="0" x2="1420.000" y2="100.000" /> + <line class="sec01" x1="1430.000" y1="0" x2="1430.000" y2="100.000" /> + <line class="sec01" x1="1440.000" y1="0" x2="1440.000" y2="100.000" /> + <line class="sec01" x1="1450.000" y1="0" x2="1450.000" y2="100.000" /> + <line class="sec01" x1="1460.000" y1="0" x2="1460.000" y2="100.000" /> + <line class="sec01" x1="1470.000" y1="0" x2="1470.000" y2="100.000" /> + <line class="sec01" x1="1480.000" y1="0" x2="1480.000" y2="100.000" /> + <line class="sec01" x1="1490.000" y1="0" x2="1490.000" y2="100.000" /> + <line class="sec5" x1="1500.000" y1="0" x2="1500.000" y2="100.000" /> + <text class="sec" x="1500.000" y="-5.000" >15.0s</text> + <line class="sec01" x1="1510.000" y1="0" x2="1510.000" y2="100.000" /> + <line class="sec01" x1="1520.000" y1="0" x2="1520.000" y2="100.000" /> + <line class="sec01" x1="1530.000" y1="0" x2="1530.000" y2="100.000" /> + <line class="sec01" x1="1540.000" y1="0" x2="1540.000" y2="100.000" /> + <line class="sec01" x1="1550.000" y1="0" x2="1550.000" y2="100.000" /> + <line class="sec01" x1="1560.000" y1="0" x2="1560.000" y2="100.000" /> + <line class="sec01" x1="1570.000" y1="0" x2="1570.000" y2="100.000" /> + <line class="sec01" x1="1580.000" y1="0" x2="1580.000" y2="100.000" /> + <line class="sec01" x1="1590.000" y1="0" x2="1590.000" y2="100.000" /> + <line class="sec1" x1="1600.000" y1="0" x2="1600.000" y2="100.000" /> + <text class="sec" x="1600.000" y="-5.000" >16.0s</text> + <line class="sec01" x1="1610.000" y1="0" x2="1610.000" y2="100.000" /> + <line class="sec01" x1="1620.000" y1="0" x2="1620.000" y2="100.000" /> + <line class="sec01" x1="1630.000" y1="0" x2="1630.000" y2="100.000" /> + <line class="sec01" x1="1640.000" y1="0" x2="1640.000" y2="100.000" /> + <line class="sec01" x1="1650.000" y1="0" x2="1650.000" y2="100.000" /> + <line class="sec01" x1="1660.000" y1="0" x2="1660.000" y2="100.000" /> + <line class="sec01" x1="1670.000" y1="0" x2="1670.000" y2="100.000" /> + <line class="sec01" x1="1680.000" y1="0" x2="1680.000" y2="100.000" /> + <line class="sec01" x1="1690.000" y1="0" x2="1690.000" y2="100.000" /> + <line class="sec1" x1="1700.000" y1="0" x2="1700.000" y2="100.000" /> + <text class="sec" x="1700.000" y="-5.000" >17.0s</text> + <line class="sec01" x1="1710.000" y1="0" x2="1710.000" y2="100.000" /> + <line class="sec01" x1="1720.000" y1="0" x2="1720.000" y2="100.000" /> + <line class="sec01" x1="1730.000" y1="0" x2="1730.000" y2="100.000" /> + <line class="sec01" x1="1740.000" y1="0" x2="1740.000" y2="100.000" /> + <line class="sec01" x1="1750.000" y1="0" x2="1750.000" y2="100.000" /> + <line class="sec01" x1="1760.000" y1="0" x2="1760.000" y2="100.000" /> + <line class="sec01" x1="1770.000" y1="0" x2="1770.000" y2="100.000" /> + <line class="sec01" x1="1780.000" y1="0" x2="1780.000" y2="100.000" /> + <line class="sec01" x1="1790.000" y1="0" x2="1790.000" y2="100.000" /> + <line class="sec1" x1="1800.000" y1="0" x2="1800.000" y2="100.000" /> + <text class="sec" x="1800.000" y="-5.000" >18.0s</text> + <line class="sec01" x1="1810.000" y1="0" x2="1810.000" y2="100.000" /> + <line class="sec01" x1="1820.000" y1="0" x2="1820.000" y2="100.000" /> + <line class="sec01" x1="1830.000" y1="0" x2="1830.000" y2="100.000" /> + <line class="sec01" x1="1840.000" y1="0" x2="1840.000" y2="100.000" /> + <line class="sec01" x1="1850.000" y1="0" x2="1850.000" y2="100.000" /> + <line class="sec01" x1="1860.000" y1="0" x2="1860.000" y2="100.000" /> + <line class="sec01" x1="1870.000" y1="0" x2="1870.000" y2="100.000" /> + <line class="sec01" x1="1880.000" y1="0" x2="1880.000" y2="100.000" /> + <line class="sec01" x1="1890.000" y1="0" x2="1890.000" y2="100.000" /> + <line class="sec1" x1="1900.000" y1="0" x2="1900.000" y2="100.000" /> + <text class="sec" x="1900.000" y="-5.000" >19.0s</text> + <line class="sec01" x1="1910.000" y1="0" x2="1910.000" y2="100.000" /> + <line class="sec01" x1="1920.000" y1="0" x2="1920.000" y2="100.000" /> + <line class="sec01" x1="1930.000" y1="0" x2="1930.000" y2="100.000" /> + <line class="sec01" x1="1940.000" y1="0" x2="1940.000" y2="100.000" /> + <line class="sec01" x1="1950.000" y1="0" x2="1950.000" y2="100.000" /> + <line class="sec01" x1="1960.000" y1="0" x2="1960.000" y2="100.000" /> + <line class="sec01" x1="1970.000" y1="0" x2="1970.000" y2="100.000" /> + <line class="sec01" x1="1980.000" y1="0" x2="1980.000" y2="100.000" /> + <line class="sec01" x1="1990.000" y1="0" x2="1990.000" y2="100.000" /> + <line class="sec5" x1="2000.000" y1="0" x2="2000.000" y2="100.000" /> + <text class="sec" x="2000.000" y="-5.000" >20.0s</text> + <line class="sec01" x1="2010.000" y1="0" x2="2010.000" y2="100.000" /> + <line class="sec01" x1="2020.000" y1="0" x2="2020.000" y2="100.000" /> + <line class="sec01" x1="2030.000" y1="0" x2="2030.000" y2="100.000" /> + <line class="sec01" x1="2040.000" y1="0" x2="2040.000" y2="100.000" /> + <line class="sec01" x1="2050.000" y1="0" x2="2050.000" y2="100.000" /> + <line class="sec01" x1="2060.000" y1="0" x2="2060.000" y2="100.000" /> + <line class="sec01" x1="2070.000" y1="0" x2="2070.000" y2="100.000" /> + <line class="sec01" x1="2080.000" y1="0" x2="2080.000" y2="100.000" /> + <line class="sec01" x1="2090.000" y1="0" x2="2090.000" y2="100.000" /> +<rect class="bo" x="166.186" y="99.610" width="4.006" height="0.390" /> +<rect class="bo" x="170.191" y="99.610" width="4.007" height="0.390" /> +<rect class="bo" x="174.198" y="99.610" width="4.016" height="0.390" /> +<rect class="bo" x="178.214" y="99.610" width="4.024" height="0.390" /> +<rect class="bo" x="182.238" y="99.610" width="4.006" height="0.390" /> +<rect class="bo" x="186.244" y="99.610" width="4.006" height="0.390" /> +<rect class="bo" x="330.500" y="99.550" width="4.006" height="0.450" /> +<rect class="bo" x="334.506" y="99.550" width="4.008" height="0.450" /> +<rect class="bo" x="338.513" y="99.550" width="4.008" height="0.450" /> +<rect class="bo" x="342.521" y="99.520" width="4.008" height="0.480" /> +<rect class="bo" x="346.529" y="99.505" width="4.008" height="0.495" /> +<rect class="bo" x="350.538" y="99.505" width="4.010" height="0.495" /> +<rect class="bo" x="462.766" y="99.369" width="4.010" height="0.631" /> +<rect class="bo" x="466.776" y="99.369" width="4.008" height="0.631" /> +<rect class="bo" x="470.784" y="99.084" width="4.008" height="0.916" /> +<rect class="bo" x="474.792" y="99.084" width="4.007" height="0.916" /> +<rect class="bo" x="478.799" y="99.084" width="4.009" height="0.916" /> +<rect class="bo" x="482.808" y="99.084" width="4.006" height="0.916" /> +<rect class="bo" x="486.814" y="99.715" width="4.006" height="0.285" /> +<rect class="bo" x="490.819" y="99.264" width="4.006" height="0.736" /> +<rect class="bo" x="494.825" y="99.550" width="4.006" height="0.450" /> +<rect class="bo" x="498.831" y="99.550" width="4.006" height="0.450" /> +<rect class="bo" x="502.838" y="99.550" width="4.006" height="0.450" /> +<rect class="bo" x="506.844" y="98.574" width="4.006" height="1.426" /> +<rect class="bo" x="510.850" y="98.574" width="4.008" height="1.426" /> +<rect class="bo" x="514.858" y="99.024" width="4.006" height="0.976" /> +<rect class="bo" x="518.864" y="99.024" width="4.006" height="0.976" /> +<rect class="bo" x="522.870" y="99.024" width="4.006" height="0.976" /> +<rect class="bo" x="526.876" y="99.024" width="4.007" height="0.976" /> +<rect class="bo" x="631.068" y="61.522" width="4.007" height="38.478" /> +<rect class="bo" x="635.075" y="61.522" width="4.009" height="38.478" /> +<rect class="bo" x="639.084" y="61.522" width="4.006" height="38.478" /> +<rect class="bo" x="643.090" y="60.952" width="4.007" height="39.048" /> +<rect class="bo" x="647.097" y="60.952" width="4.007" height="39.048" /> +<rect class="bo" x="651.104" y="60.952" width="4.007" height="39.048" /> +<rect class="bo" x="655.111" y="99.430" width="4.006" height="0.570" /> +<rect class="bo" x="659.117" y="99.430" width="4.008" height="0.570" /> +<rect class="bo" x="663.125" y="99.430" width="4.008" height="0.570" /> +<rect class="bo" x="1156.298" y="99.535" width="4.014" height="0.465" /> +<rect class="bo" x="1160.312" y="99.535" width="4.009" height="0.465" /> +<rect class="bo" x="1164.322" y="99.520" width="4.015" height="0.480" /> +<rect class="bo" x="1168.336" y="99.520" width="4.014" height="0.480" /> +<rect class="bo" x="1172.351" y="99.520" width="4.014" height="0.480" /> +<rect class="bo" x="1176.365" y="99.520" width="4.014" height="0.480" /> +<rect class="bo" x="1192.422" y="99.475" width="4.014" height="0.525" /> +<rect class="bo" x="1196.436" y="99.475" width="4.014" height="0.525" /> +<rect class="bo" x="1200.451" y="99.475" width="4.010" height="0.525" /> +<rect class="bo" x="1204.461" y="99.475" width="4.006" height="0.525" /> +<rect class="bo" x="1208.467" y="99.475" width="4.014" height="0.525" /> +<rect class="bo" x="1212.482" y="99.475" width="4.014" height="0.525" /> +<rect class="bo" x="1666.075" y="99.655" width="4.015" height="0.345" /> +<rect class="bo" x="1670.089" y="99.655" width="4.015" height="0.345" /> +<rect class="bo" x="1674.104" y="99.655" width="4.014" height="0.345" /> +<rect class="bo" x="1678.118" y="99.655" width="4.008" height="0.345" /> +<rect class="bo" x="1682.126" y="99.655" width="4.007" height="0.345" /> +<rect class="bo" x="1686.133" y="99.655" width="4.007" height="0.345" /> +</g> + +<g transform="translate(10,680.000)"> +<!-- CPU utilization graph --> +<text class="t2" x="5" y="-15">CPU utilization</text> +<rect class="box" x="0.000" y="0" width="2095.495" height="100.000" /> + <line class="sec5" x1="0.000" y1="0" x2="0.000" y2="100.000" /> + <text class="sec" x="0.000" y="-5.000" >0.0s</text> + <line class="sec01" x1="10.000" y1="0" x2="10.000" y2="100.000" /> + <line class="sec01" x1="20.000" y1="0" x2="20.000" y2="100.000" /> + <line class="sec01" x1="30.000" y1="0" x2="30.000" y2="100.000" /> + <line class="sec01" x1="40.000" y1="0" x2="40.000" y2="100.000" /> + <line class="sec01" x1="50.000" y1="0" x2="50.000" y2="100.000" /> + <line class="sec01" x1="60.000" y1="0" x2="60.000" y2="100.000" /> + <line class="sec01" x1="70.000" y1="0" x2="70.000" y2="100.000" /> + <line class="sec01" x1="80.000" y1="0" x2="80.000" y2="100.000" /> + <line class="sec01" x1="90.000" y1="0" x2="90.000" y2="100.000" /> + <line class="sec1" x1="100.000" y1="0" x2="100.000" y2="100.000" /> + <text class="sec" x="100.000" y="-5.000" >1.0s</text> + <line class="sec01" x1="110.000" y1="0" x2="110.000" y2="100.000" /> + <line class="sec01" x1="120.000" y1="0" x2="120.000" y2="100.000" /> + <line class="sec01" x1="130.000" y1="0" x2="130.000" y2="100.000" /> + <line class="sec01" x1="140.000" y1="0" x2="140.000" y2="100.000" /> + <line class="sec01" x1="150.000" y1="0" x2="150.000" y2="100.000" /> + <line class="sec01" x1="160.000" y1="0" x2="160.000" y2="100.000" /> + <line class="sec01" x1="170.000" y1="0" x2="170.000" y2="100.000" /> + <line class="sec01" x1="180.000" y1="0" x2="180.000" y2="100.000" /> + <line class="sec01" x1="190.000" y1="0" x2="190.000" y2="100.000" /> + <line class="sec1" x1="200.000" y1="0" x2="200.000" y2="100.000" /> + <text class="sec" x="200.000" y="-5.000" >2.0s</text> + <line class="sec01" x1="210.000" y1="0" x2="210.000" y2="100.000" /> + <line class="sec01" x1="220.000" y1="0" x2="220.000" y2="100.000" /> + <line class="sec01" x1="230.000" y1="0" x2="230.000" y2="100.000" /> + <line class="sec01" x1="240.000" y1="0" x2="240.000" y2="100.000" /> + <line class="sec01" x1="250.000" y1="0" x2="250.000" y2="100.000" /> + <line class="sec01" x1="260.000" y1="0" x2="260.000" y2="100.000" /> + <line class="sec01" x1="270.000" y1="0" x2="270.000" y2="100.000" /> + <line class="sec01" x1="280.000" y1="0" x2="280.000" y2="100.000" /> + <line class="sec01" x1="290.000" y1="0" x2="290.000" y2="100.000" /> + <line class="sec1" x1="300.000" y1="0" x2="300.000" y2="100.000" /> + <text class="sec" x="300.000" y="-5.000" >3.0s</text> + <line class="sec01" x1="310.000" y1="0" x2="310.000" y2="100.000" /> + <line class="sec01" x1="320.000" y1="0" x2="320.000" y2="100.000" /> + <line class="sec01" x1="330.000" y1="0" x2="330.000" y2="100.000" /> + <line class="sec01" x1="340.000" y1="0" x2="340.000" y2="100.000" /> + <line class="sec01" x1="350.000" y1="0" x2="350.000" y2="100.000" /> + <line class="sec01" x1="360.000" y1="0" x2="360.000" y2="100.000" /> + <line class="sec01" x1="370.000" y1="0" x2="370.000" y2="100.000" /> + <line class="sec01" x1="380.000" y1="0" x2="380.000" y2="100.000" /> + <line class="sec01" x1="390.000" y1="0" x2="390.000" y2="100.000" /> + <line class="sec1" x1="400.000" y1="0" x2="400.000" y2="100.000" /> + <text class="sec" x="400.000" y="-5.000" >4.0s</text> + <line class="sec01" x1="410.000" y1="0" x2="410.000" y2="100.000" /> + <line class="sec01" x1="420.000" y1="0" x2="420.000" y2="100.000" /> + <line class="sec01" x1="430.000" y1="0" x2="430.000" y2="100.000" /> + <line class="sec01" x1="440.000" y1="0" x2="440.000" y2="100.000" /> + <line class="sec01" x1="450.000" y1="0" x2="450.000" y2="100.000" /> + <line class="sec01" x1="460.000" y1="0" x2="460.000" y2="100.000" /> + <line class="sec01" x1="470.000" y1="0" x2="470.000" y2="100.000" /> + <line class="sec01" x1="480.000" y1="0" x2="480.000" y2="100.000" /> + <line class="sec01" x1="490.000" y1="0" x2="490.000" y2="100.000" /> + <line class="sec5" x1="500.000" y1="0" x2="500.000" y2="100.000" /> + <text class="sec" x="500.000" y="-5.000" >5.0s</text> + <line class="sec01" x1="510.000" y1="0" x2="510.000" y2="100.000" /> + <line class="sec01" x1="520.000" y1="0" x2="520.000" y2="100.000" /> + <line class="sec01" x1="530.000" y1="0" x2="530.000" y2="100.000" /> + <line class="sec01" x1="540.000" y1="0" x2="540.000" y2="100.000" /> + <line class="sec01" x1="550.000" y1="0" x2="550.000" y2="100.000" /> + <line class="sec01" x1="560.000" y1="0" x2="560.000" y2="100.000" /> + <line class="sec01" x1="570.000" y1="0" x2="570.000" y2="100.000" /> + <line class="sec01" x1="580.000" y1="0" x2="580.000" y2="100.000" /> + <line class="sec01" x1="590.000" y1="0" x2="590.000" y2="100.000" /> + <line class="sec1" x1="600.000" y1="0" x2="600.000" y2="100.000" /> + <text class="sec" x="600.000" y="-5.000" >6.0s</text> + <line class="sec01" x1="610.000" y1="0" x2="610.000" y2="100.000" /> + <line class="sec01" x1="620.000" y1="0" x2="620.000" y2="100.000" /> + <line class="sec01" x1="630.000" y1="0" x2="630.000" y2="100.000" /> + <line class="sec01" x1="640.000" y1="0" x2="640.000" y2="100.000" /> + <line class="sec01" x1="650.000" y1="0" x2="650.000" y2="100.000" /> + <line class="sec01" x1="660.000" y1="0" x2="660.000" y2="100.000" /> + <line class="sec01" x1="670.000" y1="0" x2="670.000" y2="100.000" /> + <line class="sec01" x1="680.000" y1="0" x2="680.000" y2="100.000" /> + <line class="sec01" x1="690.000" y1="0" x2="690.000" y2="100.000" /> + <line class="sec1" x1="700.000" y1="0" x2="700.000" y2="100.000" /> + <text class="sec" x="700.000" y="-5.000" >7.0s</text> + <line class="sec01" x1="710.000" y1="0" x2="710.000" y2="100.000" /> + <line class="sec01" x1="720.000" y1="0" x2="720.000" y2="100.000" /> + <line class="sec01" x1="730.000" y1="0" x2="730.000" y2="100.000" /> + <line class="sec01" x1="740.000" y1="0" x2="740.000" y2="100.000" /> + <line class="sec01" x1="750.000" y1="0" x2="750.000" y2="100.000" /> + <line class="sec01" x1="760.000" y1="0" x2="760.000" y2="100.000" /> + <line class="sec01" x1="770.000" y1="0" x2="770.000" y2="100.000" /> + <line class="sec01" x1="780.000" y1="0" x2="780.000" y2="100.000" /> + <line class="sec01" x1="790.000" y1="0" x2="790.000" y2="100.000" /> + <line class="sec1" x1="800.000" y1="0" x2="800.000" y2="100.000" /> + <text class="sec" x="800.000" y="-5.000" >8.0s</text> + <line class="sec01" x1="810.000" y1="0" x2="810.000" y2="100.000" /> + <line class="sec01" x1="820.000" y1="0" x2="820.000" y2="100.000" /> + <line class="sec01" x1="830.000" y1="0" x2="830.000" y2="100.000" /> + <line class="sec01" x1="840.000" y1="0" x2="840.000" y2="100.000" /> + <line class="sec01" x1="850.000" y1="0" x2="850.000" y2="100.000" /> + <line class="sec01" x1="860.000" y1="0" x2="860.000" y2="100.000" /> + <line class="sec01" x1="870.000" y1="0" x2="870.000" y2="100.000" /> + <line class="sec01" x1="880.000" y1="0" x2="880.000" y2="100.000" /> + <line class="sec01" x1="890.000" y1="0" x2="890.000" y2="100.000" /> + <line class="sec1" x1="900.000" y1="0" x2="900.000" y2="100.000" /> + <text class="sec" x="900.000" y="-5.000" >9.0s</text> + <line class="sec01" x1="910.000" y1="0" x2="910.000" y2="100.000" /> + <line class="sec01" x1="920.000" y1="0" x2="920.000" y2="100.000" /> + <line class="sec01" x1="930.000" y1="0" x2="930.000" y2="100.000" /> + <line class="sec01" x1="940.000" y1="0" x2="940.000" y2="100.000" /> + <line class="sec01" x1="950.000" y1="0" x2="950.000" y2="100.000" /> + <line class="sec01" x1="960.000" y1="0" x2="960.000" y2="100.000" /> + <line class="sec01" x1="970.000" y1="0" x2="970.000" y2="100.000" /> + <line class="sec01" x1="980.000" y1="0" x2="980.000" y2="100.000" /> + <line class="sec01" x1="990.000" y1="0" x2="990.000" y2="100.000" /> + <line class="sec5" x1="1000.000" y1="0" x2="1000.000" y2="100.000" /> + <text class="sec" x="1000.000" y="-5.000" >10.0s</text> + <line class="sec01" x1="1010.000" y1="0" x2="1010.000" y2="100.000" /> + <line class="sec01" x1="1020.000" y1="0" x2="1020.000" y2="100.000" /> + <line class="sec01" x1="1030.000" y1="0" x2="1030.000" y2="100.000" /> + <line class="sec01" x1="1040.000" y1="0" x2="1040.000" y2="100.000" /> + <line class="sec01" x1="1050.000" y1="0" x2="1050.000" y2="100.000" /> + <line class="sec01" x1="1060.000" y1="0" x2="1060.000" y2="100.000" /> + <line class="sec01" x1="1070.000" y1="0" x2="1070.000" y2="100.000" /> + <line class="sec01" x1="1080.000" y1="0" x2="1080.000" y2="100.000" /> + <line class="sec01" x1="1090.000" y1="0" x2="1090.000" y2="100.000" /> + <line class="sec1" x1="1100.000" y1="0" x2="1100.000" y2="100.000" /> + <text class="sec" x="1100.000" y="-5.000" >11.0s</text> + <line class="sec01" x1="1110.000" y1="0" x2="1110.000" y2="100.000" /> + <line class="sec01" x1="1120.000" y1="0" x2="1120.000" y2="100.000" /> + <line class="sec01" x1="1130.000" y1="0" x2="1130.000" y2="100.000" /> + <line class="sec01" x1="1140.000" y1="0" x2="1140.000" y2="100.000" /> + <line class="sec01" x1="1150.000" y1="0" x2="1150.000" y2="100.000" /> + <line class="sec01" x1="1160.000" y1="0" x2="1160.000" y2="100.000" /> + <line class="sec01" x1="1170.000" y1="0" x2="1170.000" y2="100.000" /> + <line class="sec01" x1="1180.000" y1="0" x2="1180.000" y2="100.000" /> + <line class="sec01" x1="1190.000" y1="0" x2="1190.000" y2="100.000" /> + <line class="sec1" x1="1200.000" y1="0" x2="1200.000" y2="100.000" /> + <text class="sec" x="1200.000" y="-5.000" >12.0s</text> + <line class="sec01" x1="1210.000" y1="0" x2="1210.000" y2="100.000" /> + <line class="sec01" x1="1220.000" y1="0" x2="1220.000" y2="100.000" /> + <line class="sec01" x1="1230.000" y1="0" x2="1230.000" y2="100.000" /> + <line class="sec01" x1="1240.000" y1="0" x2="1240.000" y2="100.000" /> + <line class="sec01" x1="1250.000" y1="0" x2="1250.000" y2="100.000" /> + <line class="sec01" x1="1260.000" y1="0" x2="1260.000" y2="100.000" /> + <line class="sec01" x1="1270.000" y1="0" x2="1270.000" y2="100.000" /> + <line class="sec01" x1="1280.000" y1="0" x2="1280.000" y2="100.000" /> + <line class="sec01" x1="1290.000" y1="0" x2="1290.000" y2="100.000" /> + <line class="sec1" x1="1300.000" y1="0" x2="1300.000" y2="100.000" /> + <text class="sec" x="1300.000" y="-5.000" >13.0s</text> + <line class="sec01" x1="1310.000" y1="0" x2="1310.000" y2="100.000" /> + <line class="sec01" x1="1320.000" y1="0" x2="1320.000" y2="100.000" /> + <line class="sec01" x1="1330.000" y1="0" x2="1330.000" y2="100.000" /> + <line class="sec01" x1="1340.000" y1="0" x2="1340.000" y2="100.000" /> + <line class="sec01" x1="1350.000" y1="0" x2="1350.000" y2="100.000" /> + <line class="sec01" x1="1360.000" y1="0" x2="1360.000" y2="100.000" /> + <line class="sec01" x1="1370.000" y1="0" x2="1370.000" y2="100.000" /> + <line class="sec01" x1="1380.000" y1="0" x2="1380.000" y2="100.000" /> + <line class="sec01" x1="1390.000" y1="0" x2="1390.000" y2="100.000" /> + <line class="sec1" x1="1400.000" y1="0" x2="1400.000" y2="100.000" /> + <text class="sec" x="1400.000" y="-5.000" >14.0s</text> + <line class="sec01" x1="1410.000" y1="0" x2="1410.000" y2="100.000" /> + <line class="sec01" x1="1420.000" y1="0" x2="1420.000" y2="100.000" /> + <line class="sec01" x1="1430.000" y1="0" x2="1430.000" y2="100.000" /> + <line class="sec01" x1="1440.000" y1="0" x2="1440.000" y2="100.000" /> + <line class="sec01" x1="1450.000" y1="0" x2="1450.000" y2="100.000" /> + <line class="sec01" x1="1460.000" y1="0" x2="1460.000" y2="100.000" /> + <line class="sec01" x1="1470.000" y1="0" x2="1470.000" y2="100.000" /> + <line class="sec01" x1="1480.000" y1="0" x2="1480.000" y2="100.000" /> + <line class="sec01" x1="1490.000" y1="0" x2="1490.000" y2="100.000" /> + <line class="sec5" x1="1500.000" y1="0" x2="1500.000" y2="100.000" /> + <text class="sec" x="1500.000" y="-5.000" >15.0s</text> + <line class="sec01" x1="1510.000" y1="0" x2="1510.000" y2="100.000" /> + <line class="sec01" x1="1520.000" y1="0" x2="1520.000" y2="100.000" /> + <line class="sec01" x1="1530.000" y1="0" x2="1530.000" y2="100.000" /> + <line class="sec01" x1="1540.000" y1="0" x2="1540.000" y2="100.000" /> + <line class="sec01" x1="1550.000" y1="0" x2="1550.000" y2="100.000" /> + <line class="sec01" x1="1560.000" y1="0" x2="1560.000" y2="100.000" /> + <line class="sec01" x1="1570.000" y1="0" x2="1570.000" y2="100.000" /> + <line class="sec01" x1="1580.000" y1="0" x2="1580.000" y2="100.000" /> + <line class="sec01" x1="1590.000" y1="0" x2="1590.000" y2="100.000" /> + <line class="sec1" x1="1600.000" y1="0" x2="1600.000" y2="100.000" /> + <text class="sec" x="1600.000" y="-5.000" >16.0s</text> + <line class="sec01" x1="1610.000" y1="0" x2="1610.000" y2="100.000" /> + <line class="sec01" x1="1620.000" y1="0" x2="1620.000" y2="100.000" /> + <line class="sec01" x1="1630.000" y1="0" x2="1630.000" y2="100.000" /> + <line class="sec01" x1="1640.000" y1="0" x2="1640.000" y2="100.000" /> + <line class="sec01" x1="1650.000" y1="0" x2="1650.000" y2="100.000" /> + <line class="sec01" x1="1660.000" y1="0" x2="1660.000" y2="100.000" /> + <line class="sec01" x1="1670.000" y1="0" x2="1670.000" y2="100.000" /> + <line class="sec01" x1="1680.000" y1="0" x2="1680.000" y2="100.000" /> + <line class="sec01" x1="1690.000" y1="0" x2="1690.000" y2="100.000" /> + <line class="sec1" x1="1700.000" y1="0" x2="1700.000" y2="100.000" /> + <text class="sec" x="1700.000" y="-5.000" >17.0s</text> + <line class="sec01" x1="1710.000" y1="0" x2="1710.000" y2="100.000" /> + <line class="sec01" x1="1720.000" y1="0" x2="1720.000" y2="100.000" /> + <line class="sec01" x1="1730.000" y1="0" x2="1730.000" y2="100.000" /> + <line class="sec01" x1="1740.000" y1="0" x2="1740.000" y2="100.000" /> + <line class="sec01" x1="1750.000" y1="0" x2="1750.000" y2="100.000" /> + <line class="sec01" x1="1760.000" y1="0" x2="1760.000" y2="100.000" /> + <line class="sec01" x1="1770.000" y1="0" x2="1770.000" y2="100.000" /> + <line class="sec01" x1="1780.000" y1="0" x2="1780.000" y2="100.000" /> + <line class="sec01" x1="1790.000" y1="0" x2="1790.000" y2="100.000" /> + <line class="sec1" x1="1800.000" y1="0" x2="1800.000" y2="100.000" /> + <text class="sec" x="1800.000" y="-5.000" >18.0s</text> + <line class="sec01" x1="1810.000" y1="0" x2="1810.000" y2="100.000" /> + <line class="sec01" x1="1820.000" y1="0" x2="1820.000" y2="100.000" /> + <line class="sec01" x1="1830.000" y1="0" x2="1830.000" y2="100.000" /> + <line class="sec01" x1="1840.000" y1="0" x2="1840.000" y2="100.000" /> + <line class="sec01" x1="1850.000" y1="0" x2="1850.000" y2="100.000" /> + <line class="sec01" x1="1860.000" y1="0" x2="1860.000" y2="100.000" /> + <line class="sec01" x1="1870.000" y1="0" x2="1870.000" y2="100.000" /> + <line class="sec01" x1="1880.000" y1="0" x2="1880.000" y2="100.000" /> + <line class="sec01" x1="1890.000" y1="0" x2="1890.000" y2="100.000" /> + <line class="sec1" x1="1900.000" y1="0" x2="1900.000" y2="100.000" /> + <text class="sec" x="1900.000" y="-5.000" >19.0s</text> + <line class="sec01" x1="1910.000" y1="0" x2="1910.000" y2="100.000" /> + <line class="sec01" x1="1920.000" y1="0" x2="1920.000" y2="100.000" /> + <line class="sec01" x1="1930.000" y1="0" x2="1930.000" y2="100.000" /> + <line class="sec01" x1="1940.000" y1="0" x2="1940.000" y2="100.000" /> + <line class="sec01" x1="1950.000" y1="0" x2="1950.000" y2="100.000" /> + <line class="sec01" x1="1960.000" y1="0" x2="1960.000" y2="100.000" /> + <line class="sec01" x1="1970.000" y1="0" x2="1970.000" y2="100.000" /> + <line class="sec01" x1="1980.000" y1="0" x2="1980.000" y2="100.000" /> + <line class="sec01" x1="1990.000" y1="0" x2="1990.000" y2="100.000" /> + <line class="sec5" x1="2000.000" y1="0" x2="2000.000" y2="100.000" /> + <text class="sec" x="2000.000" y="-5.000" >20.0s</text> + <line class="sec01" x1="2010.000" y1="0" x2="2010.000" y2="100.000" /> + <line class="sec01" x1="2020.000" y1="0" x2="2020.000" y2="100.000" /> + <line class="sec01" x1="2030.000" y1="0" x2="2030.000" y2="100.000" /> + <line class="sec01" x1="2040.000" y1="0" x2="2040.000" y2="100.000" /> + <line class="sec01" x1="2050.000" y1="0" x2="2050.000" y2="100.000" /> + <line class="sec01" x1="2060.000" y1="0" x2="2060.000" y2="100.000" /> + <line class="sec01" x1="2070.000" y1="0" x2="2070.000" y2="100.000" /> + <line class="sec01" x1="2080.000" y1="0" x2="2080.000" y2="100.000" /> + <line class="sec01" x1="2090.000" y1="0" x2="2090.000" y2="100.000" /> +<rect class="cpu" x="97.924" y="0.000" width="4.026" height="100.000" /> +<rect class="cpu" x="101.950" y="78.109" width="4.010" height="21.891" /> +<rect class="cpu" x="105.960" y="83.052" width="4.008" height="16.948" /> +<rect class="cpu" x="109.967" y="90.168" width="4.011" height="9.832" /> +<rect class="cpu" x="113.978" y="89.277" width="4.008" height="10.723" /> +<rect class="cpu" x="117.986" y="87.908" width="4.007" height="12.092" /> +<rect class="cpu" x="121.993" y="85.840" width="4.007" height="14.160" /> +<rect class="cpu" x="126.000" y="76.900" width="4.006" height="23.100" /> +<rect class="cpu" x="130.006" y="42.254" width="4.007" height="57.746" /> +<rect class="cpu" x="134.013" y="33.440" width="4.123" height="66.560" /> +<rect class="cpu" x="138.135" y="8.795" width="4.006" height="91.205" /> +<rect class="cpu" x="142.141" y="20.960" width="4.002" height="79.040" /> +<rect class="cpu" x="146.144" y="38.413" width="4.009" height="61.587" /> +<rect class="cpu" x="150.152" y="66.494" width="4.010" height="33.506" /> +<rect class="cpu" x="154.163" y="50.972" width="4.008" height="49.028" /> +<rect class="cpu" x="158.170" y="63.138" width="4.007" height="36.862" /> +<rect class="cpu" x="162.177" y="93.954" width="4.008" height="6.046" /> +<rect class="cpu" x="166.186" y="33.640" width="4.006" height="66.360" /> +<rect class="cpu" x="170.191" y="76.053" width="4.007" height="23.947" /> +<rect class="cpu" x="174.198" y="74.150" width="4.016" height="25.850" /> +<rect class="cpu" x="178.214" y="62.596" width="4.024" height="37.404" /> +<rect class="cpu" x="182.238" y="70.163" width="4.006" height="29.837" /> +<rect class="cpu" x="186.244" y="78.065" width="4.006" height="21.935" /> +<rect class="cpu" x="190.250" y="51.182" width="4.006" height="48.818" /> +<rect class="cpu" x="194.256" y="46.806" width="4.006" height="53.194" /> +<rect class="cpu" x="198.262" y="60.575" width="4.006" height="39.425" /> +<rect class="cpu" x="202.268" y="63.356" width="4.007" height="36.644" /> +<rect class="cpu" x="206.275" y="46.308" width="4.006" height="53.692" /> +<rect class="cpu" x="210.280" y="87.379" width="4.006" height="12.621" /> +<rect class="cpu" x="214.286" y="74.130" width="4.007" height="25.870" /> +<rect class="cpu" x="218.294" y="86.362" width="4.007" height="13.638" /> +<rect class="cpu" x="222.300" y="89.474" width="4.009" height="10.526" /> +<rect class="cpu" x="226.310" y="90.608" width="4.007" height="9.392" /> +<rect class="cpu" x="230.317" y="90.011" width="4.010" height="9.989" /> +<rect class="cpu" x="234.327" y="92.838" width="4.008" height="7.162" /> +<rect class="cpu" x="238.335" y="65.081" width="4.009" height="34.919" /> +<rect class="cpu" x="242.344" y="40.393" width="4.006" height="59.607" /> +<rect class="cpu" x="246.350" y="91.234" width="4.008" height="8.766" /> +<rect class="cpu" x="250.358" y="64.759" width="4.006" height="35.241" /> +<rect class="cpu" x="254.363" y="80.742" width="4.006" height="19.258" /> +<rect class="cpu" x="258.369" y="68.215" width="4.008" height="31.785" /> +<rect class="cpu" x="262.377" y="79.697" width="4.009" height="20.303" /> +<rect class="cpu" x="266.386" y="77.217" width="4.007" height="22.783" /> +<rect class="cpu" x="270.393" y="77.844" width="4.007" height="22.156" /> +<rect class="cpu" x="274.400" y="76.902" width="4.007" height="23.098" /> +<rect class="cpu" x="278.406" y="57.170" width="4.008" height="42.830" /> +<rect class="cpu" x="282.414" y="74.608" width="4.007" height="25.392" /> +<rect class="cpu" x="286.422" y="73.987" width="4.006" height="26.013" /> +<rect class="cpu" x="290.428" y="68.557" width="4.006" height="31.443" /> +<rect class="cpu" x="294.434" y="74.798" width="4.007" height="25.202" /> +<rect class="cpu" x="298.441" y="89.027" width="4.006" height="10.973" /> +<rect class="cpu" x="302.446" y="76.828" width="4.007" height="23.172" /> +<rect class="cpu" x="306.453" y="63.324" width="4.006" height="36.676" /> +<rect class="cpu" x="310.459" y="73.275" width="4.009" height="26.725" /> +<rect class="cpu" x="314.468" y="63.934" width="4.008" height="36.066" /> +<rect class="cpu" x="318.476" y="58.961" width="4.007" height="41.039" /> +<rect class="cpu" x="322.483" y="75.594" width="4.008" height="24.406" /> +<rect class="cpu" x="326.491" y="57.158" width="4.009" height="42.842" /> +<rect class="cpu" x="330.500" y="63.634" width="4.006" height="36.366" /> +<rect class="cpu" x="334.506" y="61.129" width="4.008" height="38.871" /> +<rect class="cpu" x="338.513" y="64.351" width="4.008" height="35.649" /> +<rect class="cpu" x="342.521" y="57.881" width="4.008" height="42.119" /> +<rect class="cpu" x="346.529" y="67.088" width="4.008" height="32.912" /> +<rect class="cpu" x="350.538" y="83.564" width="4.010" height="16.436" /> +<rect class="cpu" x="354.547" y="78.112" width="4.008" height="21.888" /> +<rect class="cpu" x="358.555" y="68.175" width="4.007" height="31.825" /> +<rect class="cpu" x="362.562" y="61.461" width="4.007" height="38.539" /> +<rect class="cpu" x="366.569" y="50.136" width="4.007" height="49.864" /> +<rect class="cpu" x="370.576" y="64.806" width="4.008" height="35.194" /> +<rect class="cpu" x="374.584" y="58.330" width="4.006" height="41.670" /> +<rect class="cpu" x="378.590" y="26.899" width="4.006" height="73.101" /> +<rect class="cpu" x="382.596" y="37.659" width="4.007" height="62.341" /> +<rect class="cpu" x="386.603" y="68.350" width="4.007" height="31.650" /> +<rect class="cpu" x="390.610" y="40.835" width="4.006" height="59.165" /> +<rect class="cpu" x="394.616" y="81.427" width="4.008" height="18.573" /> +<rect class="cpu" x="398.624" y="62.502" width="4.021" height="37.498" /> +<rect class="cpu" x="402.645" y="40.100" width="4.011" height="59.900" /> +<rect class="cpu" x="406.656" y="55.501" width="4.007" height="44.499" /> +<rect class="cpu" x="410.663" y="68.301" width="4.007" height="31.699" /> +<rect class="cpu" x="414.670" y="71.567" width="4.007" height="28.433" /> +<rect class="cpu" x="418.677" y="77.687" width="4.007" height="22.313" /> +<rect class="cpu" x="422.684" y="76.649" width="4.012" height="23.351" /> +<rect class="cpu" x="426.696" y="53.077" width="4.006" height="46.923" /> +<rect class="cpu" x="430.702" y="44.936" width="4.006" height="55.064" /> +<rect class="cpu" x="434.708" y="79.176" width="4.014" height="20.824" /> +<rect class="cpu" x="438.722" y="79.709" width="4.008" height="20.291" /> +<rect class="cpu" x="442.730" y="56.746" width="4.010" height="43.254" /> +<rect class="cpu" x="446.740" y="89.048" width="4.005" height="10.952" /> +<rect class="cpu" x="450.745" y="86.893" width="4.007" height="13.107" /> +<rect class="cpu" x="454.752" y="85.828" width="4.007" height="14.172" /> +<rect class="cpu" x="458.759" y="79.416" width="4.007" height="20.584" /> +<rect class="cpu" x="462.766" y="78.250" width="4.010" height="21.750" /> +<rect class="cpu" x="466.776" y="91.741" width="4.008" height="8.259" /> +<rect class="cpu" x="470.784" y="64.970" width="4.008" height="35.030" /> +<rect class="cpu" x="474.792" y="56.160" width="4.007" height="43.840" /> +<rect class="cpu" x="478.799" y="77.079" width="4.009" height="22.921" /> +<rect class="cpu" x="482.808" y="63.634" width="4.006" height="36.366" /> +<rect class="cpu" x="486.814" y="32.388" width="4.006" height="67.612" /> +<rect class="cpu" x="490.819" y="27.124" width="4.006" height="72.876" /> +<rect class="cpu" x="494.825" y="30.978" width="4.006" height="69.022" /> +<rect class="cpu" x="498.831" y="38.140" width="4.006" height="61.860" /> +<rect class="cpu" x="502.838" y="27.785" width="4.006" height="72.215" /> +<rect class="cpu" x="506.844" y="41.514" width="4.006" height="58.486" /> +<rect class="cpu" x="510.850" y="9.801" width="4.008" height="90.199" /> +<rect class="cpu" x="514.858" y="4.732" width="4.006" height="95.268" /> +<rect class="cpu" x="518.864" y="1.713" width="4.006" height="98.287" /> +<rect class="cpu" x="522.870" y="3.152" width="4.006" height="96.848" /> +<rect class="cpu" x="526.876" y="9.861" width="4.007" height="90.139" /> +<rect class="cpu" x="530.883" y="14.594" width="4.006" height="85.406" /> +<rect class="cpu" x="534.889" y="14.796" width="4.006" height="85.204" /> +<rect class="cpu" x="538.895" y="22.812" width="4.007" height="77.188" /> +<rect class="cpu" x="542.902" y="34.688" width="4.009" height="65.312" /> +<rect class="cpu" x="546.911" y="34.245" width="4.006" height="65.755" /> +<rect class="cpu" x="550.917" y="31.222" width="4.006" height="68.778" /> +<rect class="cpu" x="554.922" y="61.055" width="4.007" height="38.945" /> +<rect class="cpu" x="558.930" y="17.786" width="4.006" height="82.214" /> +<rect class="cpu" x="562.936" y="6.743" width="4.006" height="93.257" /> +<rect class="cpu" x="566.943" y="37.990" width="4.006" height="62.010" /> +<rect class="cpu" x="570.949" y="47.286" width="4.007" height="52.714" /> +<rect class="cpu" x="574.956" y="71.887" width="4.010" height="28.113" /> +<rect class="cpu" x="578.966" y="48.610" width="4.007" height="51.390" /> +<rect class="cpu" x="582.973" y="68.984" width="4.008" height="31.016" /> +<rect class="cpu" x="586.981" y="67.231" width="4.009" height="32.769" /> +<rect class="cpu" x="590.990" y="62.765" width="4.008" height="37.235" /> +<rect class="cpu" x="594.998" y="68.997" width="4.010" height="31.003" /> +<rect class="cpu" x="599.008" y="59.355" width="4.006" height="40.645" /> +<rect class="cpu" x="603.014" y="67.621" width="4.007" height="32.379" /> +<rect class="cpu" x="607.021" y="62.323" width="4.009" height="37.677" /> +<rect class="cpu" x="611.030" y="52.683" width="4.007" height="47.317" /> +<rect class="cpu" x="615.037" y="43.224" width="4.009" height="56.776" /> +<rect class="cpu" x="619.046" y="65.256" width="4.008" height="34.744" /> +<rect class="cpu" x="623.054" y="62.670" width="4.007" height="37.330" /> +<rect class="cpu" x="627.061" y="63.208" width="4.007" height="36.792" /> +<rect class="cpu" x="631.068" y="68.525" width="4.007" height="31.475" /> +<rect class="cpu" x="635.075" y="69.046" width="4.009" height="30.954" /> +<rect class="cpu" x="639.084" y="56.745" width="4.006" height="43.255" /> +<rect class="cpu" x="643.090" y="35.973" width="4.007" height="64.027" /> +<rect class="cpu" x="647.097" y="16.535" width="4.007" height="83.465" /> +<rect class="cpu" x="651.104" y="17.882" width="4.007" height="82.118" /> +<rect class="cpu" x="655.111" y="26.618" width="4.006" height="73.382" /> +<rect class="cpu" x="659.117" y="71.334" width="4.008" height="28.666" /> +<rect class="cpu" x="663.125" y="75.344" width="4.008" height="24.656" /> +<rect class="cpu" x="667.133" y="77.741" width="4.012" height="22.259" /> +<rect class="cpu" x="671.145" y="73.371" width="4.006" height="26.629" /> +<rect class="cpu" x="675.152" y="76.882" width="4.009" height="23.118" /> +<rect class="cpu" x="679.161" y="76.829" width="4.011" height="23.171" /> +<rect class="cpu" x="683.171" y="68.438" width="4.009" height="31.562" /> +<rect class="cpu" x="687.180" y="80.900" width="4.009" height="19.100" /> +<rect class="cpu" x="691.189" y="77.656" width="4.010" height="22.344" /> +<rect class="cpu" x="695.200" y="71.970" width="4.007" height="28.030" /> +<rect class="cpu" x="699.207" y="75.987" width="4.010" height="24.013" /> +<rect class="cpu" x="703.216" y="75.397" width="4.009" height="24.603" /> +<rect class="cpu" x="707.226" y="70.027" width="4.009" height="29.973" /> +<rect class="cpu" x="711.235" y="81.386" width="4.010" height="18.614" /> +<rect class="cpu" x="715.245" y="75.283" width="4.014" height="24.717" /> +<rect class="cpu" x="719.258" y="64.338" width="4.007" height="35.662" /> +<rect class="cpu" x="723.265" y="80.391" width="4.008" height="19.609" /> +<rect class="cpu" x="727.273" y="76.363" width="4.014" height="23.637" /> +<rect class="cpu" x="731.286" y="68.575" width="4.009" height="31.425" /> +<rect class="cpu" x="735.295" y="68.869" width="4.009" height="31.131" /> +<rect class="cpu" x="739.304" y="73.125" width="4.006" height="26.875" /> +<rect class="cpu" x="743.310" y="66.567" width="4.013" height="33.433" /> +<rect class="cpu" x="747.323" y="74.419" width="4.007" height="25.581" /> +<rect class="cpu" x="751.330" y="72.052" width="4.010" height="27.948" /> +<rect class="cpu" x="755.340" y="78.318" width="4.010" height="21.682" /> +<rect class="cpu" x="759.350" y="75.253" width="4.009" height="24.747" /> +<rect class="cpu" x="763.359" y="76.963" width="4.008" height="23.037" /> +<rect class="cpu" x="767.367" y="81.465" width="4.014" height="18.535" /> +<rect class="cpu" x="771.381" y="61.540" width="4.009" height="38.460" /> +<rect class="cpu" x="775.390" y="75.496" width="4.006" height="24.504" /> +<rect class="cpu" x="779.396" y="78.328" width="4.010" height="21.672" /> +<rect class="cpu" x="783.406" y="72.462" width="4.009" height="27.538" /> +<rect class="cpu" x="787.415" y="72.411" width="4.007" height="27.589" /> +<rect class="cpu" x="791.422" y="76.206" width="4.006" height="23.794" /> +<rect class="cpu" x="795.428" y="74.888" width="4.008" height="25.112" /> +<rect class="cpu" x="799.436" y="53.953" width="4.008" height="46.047" /> +<rect class="cpu" x="803.444" y="61.961" width="4.011" height="38.039" /> +<rect class="cpu" x="807.454" y="64.269" width="4.006" height="35.731" /> +<rect class="cpu" x="811.460" y="72.937" width="4.010" height="27.063" /> +<rect class="cpu" x="815.470" y="69.950" width="4.007" height="30.050" /> +<rect class="cpu" x="819.477" y="74.869" width="4.006" height="25.131" /> +<rect class="cpu" x="823.483" y="66.615" width="4.008" height="33.385" /> +<rect class="cpu" x="827.492" y="76.136" width="4.009" height="23.864" /> +<rect class="cpu" x="831.500" y="71.134" width="4.010" height="28.866" /> +<rect class="cpu" x="835.510" y="74.988" width="4.007" height="25.012" /> +<rect class="cpu" x="839.517" y="68.091" width="4.011" height="31.909" /> +<rect class="cpu" x="843.528" y="75.130" width="4.010" height="24.870" /> +<rect class="cpu" x="847.538" y="68.929" width="4.006" height="31.071" /> +<rect class="cpu" x="851.544" y="75.243" width="4.007" height="24.757" /> +<rect class="cpu" x="855.550" y="70.768" width="4.006" height="29.232" /> +<rect class="cpu" x="859.557" y="70.811" width="4.006" height="29.189" /> +<rect class="cpu" x="863.563" y="74.160" width="4.007" height="25.840" /> +<rect class="cpu" x="867.570" y="73.088" width="4.015" height="26.912" /> +<rect class="cpu" x="871.585" y="65.689" width="4.006" height="34.311" /> +<rect class="cpu" x="875.591" y="64.404" width="4.006" height="35.596" /> +<rect class="cpu" x="879.598" y="73.368" width="4.007" height="26.632" /> +<rect class="cpu" x="883.605" y="71.680" width="4.006" height="28.320" /> +<rect class="cpu" x="887.611" y="75.236" width="4.006" height="24.764" /> +<rect class="cpu" x="891.617" y="75.149" width="4.009" height="24.851" /> +<rect class="cpu" x="895.626" y="78.949" width="4.006" height="21.051" /> +<rect class="cpu" x="899.632" y="66.736" width="4.006" height="33.264" /> +<rect class="cpu" x="903.639" y="69.945" width="4.006" height="30.055" /> +<rect class="cpu" x="907.644" y="70.352" width="4.006" height="29.648" /> +<rect class="cpu" x="911.650" y="63.272" width="4.006" height="36.728" /> +<rect class="cpu" x="915.656" y="68.679" width="4.007" height="31.321" /> +<rect class="cpu" x="919.664" y="81.802" width="4.007" height="18.198" /> +<rect class="cpu" x="923.671" y="83.033" width="4.008" height="16.967" /> +<rect class="cpu" x="927.678" y="88.805" width="4.011" height="11.195" /> +<rect class="cpu" x="931.689" y="92.422" width="4.008" height="7.578" /> +<rect class="cpu" x="935.697" y="90.949" width="4.009" height="9.051" /> +<rect class="cpu" x="939.706" y="92.159" width="4.010" height="7.841" /> +<rect class="cpu" x="943.717" y="89.965" width="4.008" height="10.035" /> +<rect class="cpu" x="947.725" y="90.145" width="4.008" height="9.855" /> +<rect class="cpu" x="951.733" y="82.831" width="4.006" height="17.169" /> +<rect class="cpu" x="955.739" y="79.150" width="4.008" height="20.850" /> +<rect class="cpu" x="959.747" y="84.193" width="4.011" height="15.807" /> +<rect class="cpu" x="963.758" y="81.818" width="4.008" height="18.182" /> +<rect class="cpu" x="967.766" y="81.116" width="4.007" height="18.884" /> +<rect class="cpu" x="971.773" y="82.053" width="4.010" height="17.947" /> +<rect class="cpu" x="975.783" y="78.683" width="4.014" height="21.317" /> +<rect class="cpu" x="979.797" y="80.391" width="4.009" height="19.609" /> +<rect class="cpu" x="983.805" y="83.260" width="4.009" height="16.740" /> +<rect class="cpu" x="987.814" y="81.797" width="4.014" height="18.203" /> +<rect class="cpu" x="991.828" y="82.949" width="4.010" height="17.051" /> +<rect class="cpu" x="995.837" y="79.737" width="4.014" height="20.263" /> +<rect class="cpu" x="999.852" y="80.148" width="4.015" height="19.852" /> +<rect class="cpu" x="1003.866" y="81.757" width="4.010" height="18.243" /> +<rect class="cpu" x="1007.876" y="92.475" width="4.014" height="7.525" /> +<rect class="cpu" x="1011.890" y="91.054" width="4.009" height="8.946" /> +<rect class="cpu" x="1015.900" y="85.929" width="4.014" height="14.071" /> +<rect class="cpu" x="1019.914" y="88.669" width="4.014" height="11.331" /> +<rect class="cpu" x="1023.928" y="90.373" width="4.010" height="9.627" /> +<rect class="cpu" x="1027.938" y="80.307" width="4.009" height="19.693" /> +<rect class="cpu" x="1031.947" y="83.661" width="4.008" height="16.339" /> +<rect class="cpu" x="1035.955" y="88.881" width="4.008" height="11.119" /> +<rect class="cpu" x="1039.963" y="50.421" width="4.006" height="49.579" /> +<rect class="cpu" x="1043.969" y="51.216" width="4.007" height="48.784" /> +<rect class="cpu" x="1047.976" y="56.843" width="4.007" height="43.157" /> +<rect class="cpu" x="1051.984" y="69.291" width="4.006" height="30.709" /> +<rect class="cpu" x="1055.990" y="62.053" width="4.011" height="37.947" /> +<rect class="cpu" x="1060.001" y="60.367" width="4.007" height="39.633" /> +<rect class="cpu" x="1064.008" y="47.912" width="4.006" height="52.088" /> +<rect class="cpu" x="1068.014" y="62.747" width="4.006" height="37.253" /> +<rect class="cpu" x="1072.020" y="66.074" width="4.007" height="33.926" /> +<rect class="cpu" x="1076.027" y="65.888" width="4.013" height="34.112" /> +<rect class="cpu" x="1080.040" y="84.201" width="4.008" height="15.799" /> +<rect class="cpu" x="1084.048" y="81.365" width="4.010" height="18.635" /> +<rect class="cpu" x="1088.058" y="86.406" width="4.014" height="13.594" /> +<rect class="cpu" x="1092.072" y="98.533" width="4.014" height="1.467" /> +<rect class="cpu" x="1096.086" y="97.516" width="4.014" height="2.484" /> +<rect class="cpu" x="1100.101" y="98.582" width="4.010" height="1.418" /> +<rect class="cpu" x="1104.111" y="98.397" width="4.014" height="1.603" /> +<rect class="cpu" x="1108.125" y="97.409" width="4.015" height="2.591" /> +<rect class="cpu" x="1112.140" y="98.599" width="4.014" height="1.401" /> +<rect class="cpu" x="1116.154" y="98.573" width="4.014" height="1.427" /> +<rect class="cpu" x="1120.169" y="99.190" width="4.014" height="0.810" /> +<rect class="cpu" x="1124.183" y="94.883" width="4.014" height="5.117" /> +<rect class="cpu" x="1128.197" y="97.943" width="4.015" height="2.057" /> +<rect class="cpu" x="1132.212" y="98.838" width="4.014" height="1.162" /> +<rect class="cpu" x="1136.226" y="98.340" width="4.014" height="1.660" /> +<rect class="cpu" x="1140.240" y="99.120" width="4.014" height="0.880" /> +<rect class="cpu" x="1144.255" y="99.475" width="4.014" height="0.525" /> +<rect class="cpu" x="1148.269" y="99.493" width="4.014" height="0.507" /> +<rect class="cpu" x="1152.283" y="99.040" width="4.014" height="0.960" /> +<rect class="cpu" x="1156.298" y="98.778" width="4.014" height="1.222" /> +<rect class="cpu" x="1160.312" y="98.418" width="4.009" height="1.582" /> +<rect class="cpu" x="1164.322" y="98.406" width="4.015" height="1.594" /> +<rect class="cpu" x="1168.336" y="98.073" width="4.014" height="1.927" /> +<rect class="cpu" x="1172.351" y="98.358" width="4.014" height="1.642" /> +<rect class="cpu" x="1176.365" y="97.609" width="4.014" height="2.391" /> +<rect class="cpu" x="1180.379" y="98.395" width="4.015" height="1.605" /> +<rect class="cpu" x="1184.394" y="94.854" width="4.014" height="5.146" /> +<rect class="cpu" x="1188.408" y="98.488" width="4.014" height="1.512" /> +<rect class="cpu" x="1192.422" y="98.282" width="4.014" height="1.718" /> +<rect class="cpu" x="1196.436" y="98.720" width="4.014" height="1.280" /> +<rect class="cpu" x="1200.451" y="96.190" width="4.010" height="3.810" /> +<rect class="cpu" x="1204.461" y="73.761" width="4.006" height="26.239" /> +<rect class="cpu" x="1208.467" y="96.962" width="4.014" height="3.038" /> +<rect class="cpu" x="1212.482" y="98.502" width="4.014" height="1.498" /> +<rect class="cpu" x="1216.495" y="98.489" width="4.014" height="1.511" /> +<rect class="cpu" x="1220.510" y="98.555" width="4.014" height="1.445" /> +<rect class="cpu" x="1224.524" y="98.215" width="4.014" height="1.785" /> +<rect class="cpu" x="1228.539" y="98.444" width="4.009" height="1.556" /> +<rect class="cpu" x="1232.548" y="98.466" width="4.015" height="1.534" /> +<rect class="cpu" x="1236.563" y="98.478" width="4.015" height="1.522" /> +<rect class="cpu" x="1240.577" y="98.440" width="4.014" height="1.560" /> +<rect class="cpu" x="1244.592" y="91.768" width="4.014" height="8.232" /> +<rect class="cpu" x="1248.606" y="98.390" width="4.010" height="1.610" /> +<rect class="cpu" x="1252.615" y="98.221" width="4.015" height="1.779" /> +<rect class="cpu" x="1256.630" y="98.553" width="4.016" height="1.447" /> +<rect class="cpu" x="1260.646" y="98.496" width="4.014" height="1.504" /> +<rect class="cpu" x="1264.660" y="98.422" width="4.015" height="1.578" /> +<rect class="cpu" x="1268.675" y="98.423" width="4.010" height="1.577" /> +<rect class="cpu" x="1272.684" y="98.379" width="4.014" height="1.621" /> +<rect class="cpu" x="1276.699" y="98.279" width="4.015" height="1.721" /> +<rect class="cpu" x="1280.713" y="98.414" width="4.014" height="1.586" /> +<rect class="cpu" x="1284.728" y="98.357" width="4.021" height="1.643" /> +<rect class="cpu" x="1288.749" y="98.514" width="4.014" height="1.486" /> +<rect class="cpu" x="1292.763" y="98.624" width="4.014" height="1.376" /> +<rect class="cpu" x="1296.777" y="98.235" width="4.015" height="1.765" /> +<rect class="cpu" x="1300.792" y="98.367" width="4.015" height="1.633" /> +<rect class="cpu" x="1304.806" y="94.764" width="4.014" height="5.236" /> +<rect class="cpu" x="1308.821" y="98.294" width="4.014" height="1.706" /> +<rect class="cpu" x="1312.835" y="98.479" width="4.014" height="1.521" /> +<rect class="cpu" x="1316.850" y="98.583" width="4.015" height="1.417" /> +<rect class="cpu" x="1320.864" y="98.405" width="4.015" height="1.595" /> +<rect class="cpu" x="1324.879" y="98.264" width="4.014" height="1.736" /> +<rect class="cpu" x="1328.893" y="98.407" width="4.015" height="1.593" /> +<rect class="cpu" x="1332.908" y="98.499" width="4.015" height="1.501" /> +<rect class="cpu" x="1336.922" y="98.302" width="4.014" height="1.698" /> +<rect class="cpu" x="1340.937" y="98.679" width="4.015" height="1.321" /> +<rect class="cpu" x="1344.952" y="98.428" width="4.015" height="1.572" /> +<rect class="cpu" x="1348.966" y="98.310" width="4.015" height="1.690" /> +<rect class="cpu" x="1352.981" y="98.451" width="4.015" height="1.549" /> +<rect class="cpu" x="1356.995" y="98.550" width="4.012" height="1.450" /> +<rect class="cpu" x="1361.007" y="98.395" width="4.014" height="1.605" /> +<rect class="cpu" x="1365.021" y="94.772" width="4.014" height="5.228" /> +<rect class="cpu" x="1369.035" y="98.516" width="4.015" height="1.484" /> +<rect class="cpu" x="1373.050" y="94.865" width="4.015" height="5.135" /> +<rect class="cpu" x="1377.065" y="98.064" width="4.015" height="1.936" /> +<rect class="cpu" x="1381.080" y="98.541" width="4.015" height="1.459" /> +<rect class="cpu" x="1385.094" y="98.473" width="4.015" height="1.527" /> +<rect class="cpu" x="1389.109" y="98.554" width="4.014" height="1.446" /> +<rect class="cpu" x="1393.124" y="98.370" width="4.014" height="1.630" /> +<rect class="cpu" x="1397.138" y="94.040" width="4.013" height="5.960" /> +<rect class="cpu" x="1401.151" y="99.370" width="4.014" height="0.630" /> +<rect class="cpu" x="1405.165" y="99.458" width="4.014" height="0.542" /> +<rect class="cpu" x="1409.180" y="98.416" width="4.015" height="1.584" /> +<rect class="cpu" x="1413.194" y="98.516" width="4.014" height="1.484" /> +<rect class="cpu" x="1417.208" y="98.837" width="4.014" height="1.163" /> +<rect class="cpu" x="1421.222" y="98.845" width="4.014" height="1.155" /> +<rect class="cpu" x="1425.237" y="95.592" width="4.014" height="4.408" /> +<rect class="cpu" x="1429.251" y="98.520" width="4.015" height="1.480" /> +<rect class="cpu" x="1433.265" y="98.472" width="4.014" height="1.528" /> +<rect class="cpu" x="1437.280" y="99.201" width="4.014" height="0.799" /> +<rect class="cpu" x="1441.294" y="98.915" width="4.014" height="1.085" /> +<rect class="cpu" x="1445.309" y="98.342" width="4.014" height="1.658" /> +<rect class="cpu" x="1449.323" y="98.283" width="4.015" height="1.717" /> +<rect class="cpu" x="1453.338" y="98.645" width="4.014" height="1.355" /> +<rect class="cpu" x="1457.352" y="98.522" width="4.014" height="1.478" /> +<rect class="cpu" x="1461.366" y="98.367" width="4.009" height="1.633" /> +<rect class="cpu" x="1465.375" y="98.454" width="4.015" height="1.546" /> +<rect class="cpu" x="1469.390" y="98.273" width="4.014" height="1.727" /> +<rect class="cpu" x="1473.403" y="98.410" width="4.014" height="1.590" /> +<rect class="cpu" x="1477.418" y="97.347" width="4.015" height="2.653" /> +<rect class="cpu" x="1481.432" y="98.557" width="4.014" height="1.443" /> +<rect class="cpu" x="1485.446" y="95.364" width="4.009" height="4.636" /> +<rect class="cpu" x="1489.456" y="98.436" width="4.015" height="1.564" /> +<rect class="cpu" x="1493.470" y="98.376" width="4.014" height="1.624" /> +<rect class="cpu" x="1497.485" y="94.165" width="4.010" height="5.835" /> +<rect class="cpu" x="1501.495" y="98.610" width="4.014" height="1.390" /> +<rect class="cpu" x="1505.509" y="98.421" width="4.010" height="1.579" /> +<rect class="cpu" x="1509.519" y="98.465" width="4.015" height="1.535" /> +<rect class="cpu" x="1513.534" y="98.444" width="4.015" height="1.556" /> +<rect class="cpu" x="1517.548" y="98.399" width="4.014" height="1.601" /> +<rect class="cpu" x="1521.563" y="98.456" width="4.014" height="1.544" /> +<rect class="cpu" x="1525.577" y="98.575" width="4.014" height="1.425" /> +<rect class="cpu" x="1529.591" y="98.364" width="4.014" height="1.636" /> +<rect class="cpu" x="1533.605" y="98.620" width="4.015" height="1.380" /> +<rect class="cpu" x="1537.620" y="98.227" width="4.015" height="1.773" /> +<rect class="cpu" x="1541.635" y="98.457" width="4.014" height="1.543" /> +<rect class="cpu" x="1545.649" y="94.820" width="4.014" height="5.180" /> +<rect class="cpu" x="1549.663" y="98.570" width="4.014" height="1.430" /> +<rect class="cpu" x="1553.678" y="98.481" width="4.014" height="1.519" /> +<rect class="cpu" x="1557.692" y="98.637" width="4.014" height="1.363" /> +<rect class="cpu" x="1561.706" y="98.348" width="4.014" height="1.652" /> +<rect class="cpu" x="1565.720" y="98.248" width="4.015" height="1.752" /> +<rect class="cpu" x="1569.735" y="98.496" width="4.015" height="1.504" /> +<rect class="cpu" x="1573.750" y="98.515" width="4.014" height="1.485" /> +<rect class="cpu" x="1577.764" y="95.077" width="4.014" height="4.923" /> +<rect class="cpu" x="1581.779" y="98.590" width="4.015" height="1.410" /> +<rect class="cpu" x="1585.793" y="98.436" width="4.014" height="1.564" /> +<rect class="cpu" x="1589.807" y="98.401" width="4.014" height="1.599" /> +<rect class="cpu" x="1593.821" y="98.296" width="4.015" height="1.704" /> +<rect class="cpu" x="1597.836" y="98.681" width="4.014" height="1.319" /> +<rect class="cpu" x="1601.850" y="98.374" width="4.015" height="1.626" /> +<rect class="cpu" x="1605.865" y="95.040" width="4.015" height="4.960" /> +<rect class="cpu" x="1609.879" y="98.447" width="4.015" height="1.553" /> +<rect class="cpu" x="1613.894" y="98.356" width="4.012" height="1.644" /> +<rect class="cpu" x="1617.906" y="98.428" width="4.015" height="1.572" /> +<rect class="cpu" x="1621.921" y="98.408" width="4.015" height="1.592" /> +<rect class="cpu" x="1625.935" y="98.588" width="4.015" height="1.412" /> +<rect class="cpu" x="1629.950" y="98.591" width="4.015" height="1.409" /> +<rect class="cpu" x="1633.964" y="98.432" width="4.014" height="1.568" /> +<rect class="cpu" x="1637.979" y="98.403" width="4.014" height="1.597" /> +<rect class="cpu" x="1641.993" y="98.436" width="4.015" height="1.564" /> +<rect class="cpu" x="1646.007" y="96.619" width="4.008" height="3.381" /> +<rect class="cpu" x="1650.015" y="92.720" width="4.014" height="7.280" /> +<rect class="cpu" x="1654.030" y="98.327" width="4.016" height="1.673" /> +<rect class="cpu" x="1658.046" y="98.462" width="4.015" height="1.538" /> +<rect class="cpu" x="1662.060" y="98.370" width="4.015" height="1.630" /> +<rect class="cpu" x="1666.075" y="94.919" width="4.015" height="5.081" /> +<rect class="cpu" x="1670.089" y="98.467" width="4.015" height="1.533" /> +<rect class="cpu" x="1674.104" y="97.275" width="4.014" height="2.725" /> +<rect class="cpu" x="1678.118" y="81.573" width="4.008" height="18.427" /> +<rect class="cpu" x="1682.126" y="73.702" width="4.007" height="26.298" /> +<rect class="cpu" x="1686.133" y="81.637" width="4.007" height="18.363" /> +<rect class="cpu" x="1690.140" y="78.756" width="4.009" height="21.244" /> +<rect class="cpu" x="1694.150" y="87.621" width="4.009" height="12.379" /> +<rect class="cpu" x="1698.159" y="85.664" width="4.007" height="14.336" /> +<rect class="cpu" x="1702.166" y="86.341" width="4.007" height="13.659" /> +<rect class="cpu" x="1706.173" y="85.495" width="4.013" height="14.505" /> +<rect class="cpu" x="1710.186" y="85.801" width="4.007" height="14.199" /> +<rect class="cpu" x="1714.193" y="85.891" width="4.007" height="14.109" /> +<rect class="cpu" x="1718.200" y="85.101" width="4.007" height="14.899" /> +<rect class="cpu" x="1722.208" y="90.708" width="4.013" height="9.292" /> +<rect class="cpu" x="1726.220" y="81.154" width="4.009" height="18.846" /> +<rect class="cpu" x="1730.230" y="78.064" width="4.006" height="21.936" /> +<rect class="cpu" x="1734.236" y="82.516" width="4.007" height="17.484" /> +<rect class="cpu" x="1738.243" y="79.054" width="4.015" height="20.946" /> +<rect class="cpu" x="1742.258" y="91.014" width="4.012" height="8.986" /> +<rect class="cpu" x="1746.270" y="98.136" width="4.014" height="1.864" /> +<rect class="cpu" x="1750.284" y="98.344" width="4.015" height="1.656" /> +<rect class="cpu" x="1754.299" y="98.390" width="4.014" height="1.610" /> +<rect class="cpu" x="1758.313" y="98.311" width="4.015" height="1.689" /> +<rect class="cpu" x="1762.327" y="98.263" width="4.011" height="1.737" /> +<rect class="cpu" x="1766.338" y="98.658" width="4.014" height="1.342" /> +<rect class="cpu" x="1770.352" y="98.426" width="4.014" height="1.574" /> +<rect class="cpu" x="1774.367" y="98.380" width="4.014" height="1.620" /> +<rect class="cpu" x="1778.381" y="98.255" width="4.014" height="1.745" /> +<rect class="cpu" x="1782.395" y="98.163" width="4.014" height="1.837" /> +<rect class="cpu" x="1786.409" y="94.932" width="4.014" height="5.068" /> +<rect class="cpu" x="1790.424" y="98.453" width="4.015" height="1.547" /> +<rect class="cpu" x="1794.438" y="98.546" width="4.014" height="1.454" /> +<rect class="cpu" x="1798.453" y="98.541" width="4.014" height="1.459" /> +<rect class="cpu" x="1802.467" y="98.386" width="4.014" height="1.614" /> +<rect class="cpu" x="1806.482" y="98.320" width="4.014" height="1.680" /> +<rect class="cpu" x="1810.496" y="98.514" width="4.014" height="1.486" /> +<rect class="cpu" x="1814.510" y="98.432" width="4.014" height="1.568" /> +<rect class="cpu" x="1818.525" y="98.278" width="4.014" height="1.722" /> +<rect class="cpu" x="1822.539" y="98.613" width="4.015" height="1.387" /> +<rect class="cpu" x="1826.553" y="98.376" width="4.014" height="1.624" /> +<rect class="cpu" x="1830.567" y="98.340" width="4.015" height="1.660" /> +<rect class="cpu" x="1834.582" y="98.442" width="4.014" height="1.558" /> +<rect class="cpu" x="1838.596" y="98.500" width="4.014" height="1.500" /> +<rect class="cpu" x="1842.611" y="98.349" width="4.014" height="1.651" /> +<rect class="cpu" x="1846.625" y="95.567" width="4.014" height="4.433" /> +<rect class="cpu" x="1850.640" y="97.873" width="4.014" height="2.127" /> +<rect class="cpu" x="1854.654" y="98.336" width="4.014" height="1.664" /> +<rect class="cpu" x="1858.668" y="78.370" width="4.011" height="21.630" /> +<rect class="cpu" x="1862.679" y="98.543" width="4.014" height="1.457" /> +<rect class="cpu" x="1866.693" y="98.415" width="4.014" height="1.585" /> +<rect class="cpu" x="1870.707" y="98.556" width="4.015" height="1.444" /> +<rect class="cpu" x="1874.722" y="97.817" width="4.014" height="2.183" /> +<rect class="cpu" x="1878.736" y="98.179" width="4.015" height="1.821" /> +<rect class="cpu" x="1882.751" y="98.053" width="4.014" height="1.947" /> +<rect class="cpu" x="1886.765" y="98.430" width="4.014" height="1.570" /> +<rect class="cpu" x="1890.779" y="98.527" width="4.012" height="1.473" /> +<rect class="cpu" x="1894.791" y="98.465" width="4.014" height="1.535" /> +<rect class="cpu" x="1898.806" y="98.389" width="4.014" height="1.611" /> +<rect class="cpu" x="1902.820" y="98.207" width="4.014" height="1.793" /> +<rect class="cpu" x="1906.834" y="94.865" width="4.014" height="5.135" /> +<rect class="cpu" x="1910.849" y="98.334" width="4.011" height="1.666" /> +<rect class="cpu" x="1914.860" y="98.441" width="4.014" height="1.559" /> +<rect class="cpu" x="1918.874" y="98.537" width="4.014" height="1.463" /> +<rect class="cpu" x="1922.888" y="98.400" width="4.015" height="1.600" /> +<rect class="cpu" x="1926.903" y="98.312" width="4.015" height="1.688" /> +<rect class="cpu" x="1930.918" y="98.370" width="4.014" height="1.630" /> +<rect class="cpu" x="1934.932" y="98.626" width="4.014" height="1.374" /> +<rect class="cpu" x="1938.946" y="98.366" width="4.014" height="1.634" /> +<rect class="cpu" x="1942.960" y="98.549" width="4.014" height="1.451" /> +<rect class="cpu" x="1946.975" y="98.391" width="4.014" height="1.609" /> +<rect class="cpu" x="1950.989" y="98.444" width="4.015" height="1.556" /> +<rect class="cpu" x="1955.003" y="98.435" width="4.014" height="1.565" /> +<rect class="cpu" x="1959.018" y="98.387" width="4.015" height="1.613" /> +<rect class="cpu" x="1963.032" y="98.529" width="4.015" height="1.471" /> +<rect class="cpu" x="1967.047" y="94.938" width="4.015" height="5.062" /> +<rect class="cpu" x="1971.061" y="98.371" width="4.013" height="1.629" /> +<rect class="cpu" x="1975.074" y="98.238" width="4.015" height="1.762" /> +<rect class="cpu" x="1979.089" y="97.386" width="4.014" height="2.614" /> +<rect class="cpu" x="1983.103" y="98.534" width="4.014" height="1.466" /> +<rect class="cpu" x="1987.117" y="98.402" width="4.015" height="1.598" /> +<rect class="cpu" x="1991.132" y="98.712" width="4.014" height="1.288" /> +<rect class="cpu" x="1995.146" y="98.514" width="4.014" height="1.486" /> +<rect class="cpu" x="1999.160" y="94.875" width="4.014" height="5.125" /> +<rect class="cpu" x="2003.174" y="98.561" width="4.014" height="1.439" /> +<rect class="cpu" x="2007.188" y="98.891" width="4.014" height="1.109" /> +<rect class="cpu" x="2011.203" y="98.805" width="4.014" height="1.195" /> +<rect class="cpu" x="2015.216" y="98.933" width="4.014" height="1.067" /> +<rect class="cpu" x="2019.231" y="98.649" width="4.014" height="1.351" /> +<rect class="cpu" x="2023.245" y="98.325" width="4.014" height="1.675" /> +<rect class="cpu" x="2027.259" y="94.761" width="4.014" height="5.239" /> +<rect class="cpu" x="2031.273" y="98.610" width="4.015" height="1.390" /> +<rect class="cpu" x="2035.288" y="98.100" width="4.014" height="1.900" /> +<rect class="cpu" x="2039.302" y="97.929" width="4.015" height="2.071" /> +<rect class="cpu" x="2043.317" y="97.856" width="4.014" height="2.144" /> +<rect class="cpu" x="2047.331" y="98.330" width="4.014" height="1.670" /> +<rect class="cpu" x="2051.345" y="98.547" width="4.014" height="1.453" /> +<rect class="cpu" x="2055.359" y="98.515" width="4.014" height="1.485" /> +<rect class="cpu" x="2059.373" y="98.347" width="4.014" height="1.653" /> +<rect class="cpu" x="2063.388" y="98.530" width="4.014" height="1.470" /> +<rect class="cpu" x="2067.402" y="98.122" width="4.014" height="1.878" /> +<rect class="cpu" x="2071.416" y="98.086" width="4.015" height="1.914" /> +<rect class="cpu" x="2075.431" y="98.608" width="4.014" height="1.392" /> +<rect class="cpu" x="2079.445" y="97.884" width="4.010" height="2.116" /> +<rect class="cpu" x="2083.455" y="98.348" width="4.015" height="1.652" /> +<rect class="cpu" x="2087.469" y="94.602" width="4.011" height="5.398" /> +<rect class="cpu" x="2091.480" y="98.507" width="4.015" height="1.493" /> +</g> + +<g transform="translate(10,820.000)"> +<!-- Wait time aggregation box --> +<text class="t2" x="5" y="-15">CPU wait</text> +<rect class="box" x="0.000" y="0" width="2095.495" height="100.000" /> + <line class="sec5" x1="0.000" y1="0" x2="0.000" y2="100.000" /> + <text class="sec" x="0.000" y="-5.000" >0.0s</text> + <line class="sec01" x1="10.000" y1="0" x2="10.000" y2="100.000" /> + <line class="sec01" x1="20.000" y1="0" x2="20.000" y2="100.000" /> + <line class="sec01" x1="30.000" y1="0" x2="30.000" y2="100.000" /> + <line class="sec01" x1="40.000" y1="0" x2="40.000" y2="100.000" /> + <line class="sec01" x1="50.000" y1="0" x2="50.000" y2="100.000" /> + <line class="sec01" x1="60.000" y1="0" x2="60.000" y2="100.000" /> + <line class="sec01" x1="70.000" y1="0" x2="70.000" y2="100.000" /> + <line class="sec01" x1="80.000" y1="0" x2="80.000" y2="100.000" /> + <line class="sec01" x1="90.000" y1="0" x2="90.000" y2="100.000" /> + <line class="sec1" x1="100.000" y1="0" x2="100.000" y2="100.000" /> + <text class="sec" x="100.000" y="-5.000" >1.0s</text> + <line class="sec01" x1="110.000" y1="0" x2="110.000" y2="100.000" /> + <line class="sec01" x1="120.000" y1="0" x2="120.000" y2="100.000" /> + <line class="sec01" x1="130.000" y1="0" x2="130.000" y2="100.000" /> + <line class="sec01" x1="140.000" y1="0" x2="140.000" y2="100.000" /> + <line class="sec01" x1="150.000" y1="0" x2="150.000" y2="100.000" /> + <line class="sec01" x1="160.000" y1="0" x2="160.000" y2="100.000" /> + <line class="sec01" x1="170.000" y1="0" x2="170.000" y2="100.000" /> + <line class="sec01" x1="180.000" y1="0" x2="180.000" y2="100.000" /> + <line class="sec01" x1="190.000" y1="0" x2="190.000" y2="100.000" /> + <line class="sec1" x1="200.000" y1="0" x2="200.000" y2="100.000" /> + <text class="sec" x="200.000" y="-5.000" >2.0s</text> + <line class="sec01" x1="210.000" y1="0" x2="210.000" y2="100.000" /> + <line class="sec01" x1="220.000" y1="0" x2="220.000" y2="100.000" /> + <line class="sec01" x1="230.000" y1="0" x2="230.000" y2="100.000" /> + <line class="sec01" x1="240.000" y1="0" x2="240.000" y2="100.000" /> + <line class="sec01" x1="250.000" y1="0" x2="250.000" y2="100.000" /> + <line class="sec01" x1="260.000" y1="0" x2="260.000" y2="100.000" /> + <line class="sec01" x1="270.000" y1="0" x2="270.000" y2="100.000" /> + <line class="sec01" x1="280.000" y1="0" x2="280.000" y2="100.000" /> + <line class="sec01" x1="290.000" y1="0" x2="290.000" y2="100.000" /> + <line class="sec1" x1="300.000" y1="0" x2="300.000" y2="100.000" /> + <text class="sec" x="300.000" y="-5.000" >3.0s</text> + <line class="sec01" x1="310.000" y1="0" x2="310.000" y2="100.000" /> + <line class="sec01" x1="320.000" y1="0" x2="320.000" y2="100.000" /> + <line class="sec01" x1="330.000" y1="0" x2="330.000" y2="100.000" /> + <line class="sec01" x1="340.000" y1="0" x2="340.000" y2="100.000" /> + <line class="sec01" x1="350.000" y1="0" x2="350.000" y2="100.000" /> + <line class="sec01" x1="360.000" y1="0" x2="360.000" y2="100.000" /> + <line class="sec01" x1="370.000" y1="0" x2="370.000" y2="100.000" /> + <line class="sec01" x1="380.000" y1="0" x2="380.000" y2="100.000" /> + <line class="sec01" x1="390.000" y1="0" x2="390.000" y2="100.000" /> + <line class="sec1" x1="400.000" y1="0" x2="400.000" y2="100.000" /> + <text class="sec" x="400.000" y="-5.000" >4.0s</text> + <line class="sec01" x1="410.000" y1="0" x2="410.000" y2="100.000" /> + <line class="sec01" x1="420.000" y1="0" x2="420.000" y2="100.000" /> + <line class="sec01" x1="430.000" y1="0" x2="430.000" y2="100.000" /> + <line class="sec01" x1="440.000" y1="0" x2="440.000" y2="100.000" /> + <line class="sec01" x1="450.000" y1="0" x2="450.000" y2="100.000" /> + <line class="sec01" x1="460.000" y1="0" x2="460.000" y2="100.000" /> + <line class="sec01" x1="470.000" y1="0" x2="470.000" y2="100.000" /> + <line class="sec01" x1="480.000" y1="0" x2="480.000" y2="100.000" /> + <line class="sec01" x1="490.000" y1="0" x2="490.000" y2="100.000" /> + <line class="sec5" x1="500.000" y1="0" x2="500.000" y2="100.000" /> + <text class="sec" x="500.000" y="-5.000" >5.0s</text> + <line class="sec01" x1="510.000" y1="0" x2="510.000" y2="100.000" /> + <line class="sec01" x1="520.000" y1="0" x2="520.000" y2="100.000" /> + <line class="sec01" x1="530.000" y1="0" x2="530.000" y2="100.000" /> + <line class="sec01" x1="540.000" y1="0" x2="540.000" y2="100.000" /> + <line class="sec01" x1="550.000" y1="0" x2="550.000" y2="100.000" /> + <line class="sec01" x1="560.000" y1="0" x2="560.000" y2="100.000" /> + <line class="sec01" x1="570.000" y1="0" x2="570.000" y2="100.000" /> + <line class="sec01" x1="580.000" y1="0" x2="580.000" y2="100.000" /> + <line class="sec01" x1="590.000" y1="0" x2="590.000" y2="100.000" /> + <line class="sec1" x1="600.000" y1="0" x2="600.000" y2="100.000" /> + <text class="sec" x="600.000" y="-5.000" >6.0s</text> + <line class="sec01" x1="610.000" y1="0" x2="610.000" y2="100.000" /> + <line class="sec01" x1="620.000" y1="0" x2="620.000" y2="100.000" /> + <line class="sec01" x1="630.000" y1="0" x2="630.000" y2="100.000" /> + <line class="sec01" x1="640.000" y1="0" x2="640.000" y2="100.000" /> + <line class="sec01" x1="650.000" y1="0" x2="650.000" y2="100.000" /> + <line class="sec01" x1="660.000" y1="0" x2="660.000" y2="100.000" /> + <line class="sec01" x1="670.000" y1="0" x2="670.000" y2="100.000" /> + <line class="sec01" x1="680.000" y1="0" x2="680.000" y2="100.000" /> + <line class="sec01" x1="690.000" y1="0" x2="690.000" y2="100.000" /> + <line class="sec1" x1="700.000" y1="0" x2="700.000" y2="100.000" /> + <text class="sec" x="700.000" y="-5.000" >7.0s</text> + <line class="sec01" x1="710.000" y1="0" x2="710.000" y2="100.000" /> + <line class="sec01" x1="720.000" y1="0" x2="720.000" y2="100.000" /> + <line class="sec01" x1="730.000" y1="0" x2="730.000" y2="100.000" /> + <line class="sec01" x1="740.000" y1="0" x2="740.000" y2="100.000" /> + <line class="sec01" x1="750.000" y1="0" x2="750.000" y2="100.000" /> + <line class="sec01" x1="760.000" y1="0" x2="760.000" y2="100.000" /> + <line class="sec01" x1="770.000" y1="0" x2="770.000" y2="100.000" /> + <line class="sec01" x1="780.000" y1="0" x2="780.000" y2="100.000" /> + <line class="sec01" x1="790.000" y1="0" x2="790.000" y2="100.000" /> + <line class="sec1" x1="800.000" y1="0" x2="800.000" y2="100.000" /> + <text class="sec" x="800.000" y="-5.000" >8.0s</text> + <line class="sec01" x1="810.000" y1="0" x2="810.000" y2="100.000" /> + <line class="sec01" x1="820.000" y1="0" x2="820.000" y2="100.000" /> + <line class="sec01" x1="830.000" y1="0" x2="830.000" y2="100.000" /> + <line class="sec01" x1="840.000" y1="0" x2="840.000" y2="100.000" /> + <line class="sec01" x1="850.000" y1="0" x2="850.000" y2="100.000" /> + <line class="sec01" x1="860.000" y1="0" x2="860.000" y2="100.000" /> + <line class="sec01" x1="870.000" y1="0" x2="870.000" y2="100.000" /> + <line class="sec01" x1="880.000" y1="0" x2="880.000" y2="100.000" /> + <line class="sec01" x1="890.000" y1="0" x2="890.000" y2="100.000" /> + <line class="sec1" x1="900.000" y1="0" x2="900.000" y2="100.000" /> + <text class="sec" x="900.000" y="-5.000" >9.0s</text> + <line class="sec01" x1="910.000" y1="0" x2="910.000" y2="100.000" /> + <line class="sec01" x1="920.000" y1="0" x2="920.000" y2="100.000" /> + <line class="sec01" x1="930.000" y1="0" x2="930.000" y2="100.000" /> + <line class="sec01" x1="940.000" y1="0" x2="940.000" y2="100.000" /> + <line class="sec01" x1="950.000" y1="0" x2="950.000" y2="100.000" /> + <line class="sec01" x1="960.000" y1="0" x2="960.000" y2="100.000" /> + <line class="sec01" x1="970.000" y1="0" x2="970.000" y2="100.000" /> + <line class="sec01" x1="980.000" y1="0" x2="980.000" y2="100.000" /> + <line class="sec01" x1="990.000" y1="0" x2="990.000" y2="100.000" /> + <line class="sec5" x1="1000.000" y1="0" x2="1000.000" y2="100.000" /> + <text class="sec" x="1000.000" y="-5.000" >10.0s</text> + <line class="sec01" x1="1010.000" y1="0" x2="1010.000" y2="100.000" /> + <line class="sec01" x1="1020.000" y1="0" x2="1020.000" y2="100.000" /> + <line class="sec01" x1="1030.000" y1="0" x2="1030.000" y2="100.000" /> + <line class="sec01" x1="1040.000" y1="0" x2="1040.000" y2="100.000" /> + <line class="sec01" x1="1050.000" y1="0" x2="1050.000" y2="100.000" /> + <line class="sec01" x1="1060.000" y1="0" x2="1060.000" y2="100.000" /> + <line class="sec01" x1="1070.000" y1="0" x2="1070.000" y2="100.000" /> + <line class="sec01" x1="1080.000" y1="0" x2="1080.000" y2="100.000" /> + <line class="sec01" x1="1090.000" y1="0" x2="1090.000" y2="100.000" /> + <line class="sec1" x1="1100.000" y1="0" x2="1100.000" y2="100.000" /> + <text class="sec" x="1100.000" y="-5.000" >11.0s</text> + <line class="sec01" x1="1110.000" y1="0" x2="1110.000" y2="100.000" /> + <line class="sec01" x1="1120.000" y1="0" x2="1120.000" y2="100.000" /> + <line class="sec01" x1="1130.000" y1="0" x2="1130.000" y2="100.000" /> + <line class="sec01" x1="1140.000" y1="0" x2="1140.000" y2="100.000" /> + <line class="sec01" x1="1150.000" y1="0" x2="1150.000" y2="100.000" /> + <line class="sec01" x1="1160.000" y1="0" x2="1160.000" y2="100.000" /> + <line class="sec01" x1="1170.000" y1="0" x2="1170.000" y2="100.000" /> + <line class="sec01" x1="1180.000" y1="0" x2="1180.000" y2="100.000" /> + <line class="sec01" x1="1190.000" y1="0" x2="1190.000" y2="100.000" /> + <line class="sec1" x1="1200.000" y1="0" x2="1200.000" y2="100.000" /> + <text class="sec" x="1200.000" y="-5.000" >12.0s</text> + <line class="sec01" x1="1210.000" y1="0" x2="1210.000" y2="100.000" /> + <line class="sec01" x1="1220.000" y1="0" x2="1220.000" y2="100.000" /> + <line class="sec01" x1="1230.000" y1="0" x2="1230.000" y2="100.000" /> + <line class="sec01" x1="1240.000" y1="0" x2="1240.000" y2="100.000" /> + <line class="sec01" x1="1250.000" y1="0" x2="1250.000" y2="100.000" /> + <line class="sec01" x1="1260.000" y1="0" x2="1260.000" y2="100.000" /> + <line class="sec01" x1="1270.000" y1="0" x2="1270.000" y2="100.000" /> + <line class="sec01" x1="1280.000" y1="0" x2="1280.000" y2="100.000" /> + <line class="sec01" x1="1290.000" y1="0" x2="1290.000" y2="100.000" /> + <line class="sec1" x1="1300.000" y1="0" x2="1300.000" y2="100.000" /> + <text class="sec" x="1300.000" y="-5.000" >13.0s</text> + <line class="sec01" x1="1310.000" y1="0" x2="1310.000" y2="100.000" /> + <line class="sec01" x1="1320.000" y1="0" x2="1320.000" y2="100.000" /> + <line class="sec01" x1="1330.000" y1="0" x2="1330.000" y2="100.000" /> + <line class="sec01" x1="1340.000" y1="0" x2="1340.000" y2="100.000" /> + <line class="sec01" x1="1350.000" y1="0" x2="1350.000" y2="100.000" /> + <line class="sec01" x1="1360.000" y1="0" x2="1360.000" y2="100.000" /> + <line class="sec01" x1="1370.000" y1="0" x2="1370.000" y2="100.000" /> + <line class="sec01" x1="1380.000" y1="0" x2="1380.000" y2="100.000" /> + <line class="sec01" x1="1390.000" y1="0" x2="1390.000" y2="100.000" /> + <line class="sec1" x1="1400.000" y1="0" x2="1400.000" y2="100.000" /> + <text class="sec" x="1400.000" y="-5.000" >14.0s</text> + <line class="sec01" x1="1410.000" y1="0" x2="1410.000" y2="100.000" /> + <line class="sec01" x1="1420.000" y1="0" x2="1420.000" y2="100.000" /> + <line class="sec01" x1="1430.000" y1="0" x2="1430.000" y2="100.000" /> + <line class="sec01" x1="1440.000" y1="0" x2="1440.000" y2="100.000" /> + <line class="sec01" x1="1450.000" y1="0" x2="1450.000" y2="100.000" /> + <line class="sec01" x1="1460.000" y1="0" x2="1460.000" y2="100.000" /> + <line class="sec01" x1="1470.000" y1="0" x2="1470.000" y2="100.000" /> + <line class="sec01" x1="1480.000" y1="0" x2="1480.000" y2="100.000" /> + <line class="sec01" x1="1490.000" y1="0" x2="1490.000" y2="100.000" /> + <line class="sec5" x1="1500.000" y1="0" x2="1500.000" y2="100.000" /> + <text class="sec" x="1500.000" y="-5.000" >15.0s</text> + <line class="sec01" x1="1510.000" y1="0" x2="1510.000" y2="100.000" /> + <line class="sec01" x1="1520.000" y1="0" x2="1520.000" y2="100.000" /> + <line class="sec01" x1="1530.000" y1="0" x2="1530.000" y2="100.000" /> + <line class="sec01" x1="1540.000" y1="0" x2="1540.000" y2="100.000" /> + <line class="sec01" x1="1550.000" y1="0" x2="1550.000" y2="100.000" /> + <line class="sec01" x1="1560.000" y1="0" x2="1560.000" y2="100.000" /> + <line class="sec01" x1="1570.000" y1="0" x2="1570.000" y2="100.000" /> + <line class="sec01" x1="1580.000" y1="0" x2="1580.000" y2="100.000" /> + <line class="sec01" x1="1590.000" y1="0" x2="1590.000" y2="100.000" /> + <line class="sec1" x1="1600.000" y1="0" x2="1600.000" y2="100.000" /> + <text class="sec" x="1600.000" y="-5.000" >16.0s</text> + <line class="sec01" x1="1610.000" y1="0" x2="1610.000" y2="100.000" /> + <line class="sec01" x1="1620.000" y1="0" x2="1620.000" y2="100.000" /> + <line class="sec01" x1="1630.000" y1="0" x2="1630.000" y2="100.000" /> + <line class="sec01" x1="1640.000" y1="0" x2="1640.000" y2="100.000" /> + <line class="sec01" x1="1650.000" y1="0" x2="1650.000" y2="100.000" /> + <line class="sec01" x1="1660.000" y1="0" x2="1660.000" y2="100.000" /> + <line class="sec01" x1="1670.000" y1="0" x2="1670.000" y2="100.000" /> + <line class="sec01" x1="1680.000" y1="0" x2="1680.000" y2="100.000" /> + <line class="sec01" x1="1690.000" y1="0" x2="1690.000" y2="100.000" /> + <line class="sec1" x1="1700.000" y1="0" x2="1700.000" y2="100.000" /> + <text class="sec" x="1700.000" y="-5.000" >17.0s</text> + <line class="sec01" x1="1710.000" y1="0" x2="1710.000" y2="100.000" /> + <line class="sec01" x1="1720.000" y1="0" x2="1720.000" y2="100.000" /> + <line class="sec01" x1="1730.000" y1="0" x2="1730.000" y2="100.000" /> + <line class="sec01" x1="1740.000" y1="0" x2="1740.000" y2="100.000" /> + <line class="sec01" x1="1750.000" y1="0" x2="1750.000" y2="100.000" /> + <line class="sec01" x1="1760.000" y1="0" x2="1760.000" y2="100.000" /> + <line class="sec01" x1="1770.000" y1="0" x2="1770.000" y2="100.000" /> + <line class="sec01" x1="1780.000" y1="0" x2="1780.000" y2="100.000" /> + <line class="sec01" x1="1790.000" y1="0" x2="1790.000" y2="100.000" /> + <line class="sec1" x1="1800.000" y1="0" x2="1800.000" y2="100.000" /> + <text class="sec" x="1800.000" y="-5.000" >18.0s</text> + <line class="sec01" x1="1810.000" y1="0" x2="1810.000" y2="100.000" /> + <line class="sec01" x1="1820.000" y1="0" x2="1820.000" y2="100.000" /> + <line class="sec01" x1="1830.000" y1="0" x2="1830.000" y2="100.000" /> + <line class="sec01" x1="1840.000" y1="0" x2="1840.000" y2="100.000" /> + <line class="sec01" x1="1850.000" y1="0" x2="1850.000" y2="100.000" /> + <line class="sec01" x1="1860.000" y1="0" x2="1860.000" y2="100.000" /> + <line class="sec01" x1="1870.000" y1="0" x2="1870.000" y2="100.000" /> + <line class="sec01" x1="1880.000" y1="0" x2="1880.000" y2="100.000" /> + <line class="sec01" x1="1890.000" y1="0" x2="1890.000" y2="100.000" /> + <line class="sec1" x1="1900.000" y1="0" x2="1900.000" y2="100.000" /> + <text class="sec" x="1900.000" y="-5.000" >19.0s</text> + <line class="sec01" x1="1910.000" y1="0" x2="1910.000" y2="100.000" /> + <line class="sec01" x1="1920.000" y1="0" x2="1920.000" y2="100.000" /> + <line class="sec01" x1="1930.000" y1="0" x2="1930.000" y2="100.000" /> + <line class="sec01" x1="1940.000" y1="0" x2="1940.000" y2="100.000" /> + <line class="sec01" x1="1950.000" y1="0" x2="1950.000" y2="100.000" /> + <line class="sec01" x1="1960.000" y1="0" x2="1960.000" y2="100.000" /> + <line class="sec01" x1="1970.000" y1="0" x2="1970.000" y2="100.000" /> + <line class="sec01" x1="1980.000" y1="0" x2="1980.000" y2="100.000" /> + <line class="sec01" x1="1990.000" y1="0" x2="1990.000" y2="100.000" /> + <line class="sec5" x1="2000.000" y1="0" x2="2000.000" y2="100.000" /> + <text class="sec" x="2000.000" y="-5.000" >20.0s</text> + <line class="sec01" x1="2010.000" y1="0" x2="2010.000" y2="100.000" /> + <line class="sec01" x1="2020.000" y1="0" x2="2020.000" y2="100.000" /> + <line class="sec01" x1="2030.000" y1="0" x2="2030.000" y2="100.000" /> + <line class="sec01" x1="2040.000" y1="0" x2="2040.000" y2="100.000" /> + <line class="sec01" x1="2050.000" y1="0" x2="2050.000" y2="100.000" /> + <line class="sec01" x1="2060.000" y1="0" x2="2060.000" y2="100.000" /> + <line class="sec01" x1="2070.000" y1="0" x2="2070.000" y2="100.000" /> + <line class="sec01" x1="2080.000" y1="0" x2="2080.000" y2="100.000" /> + <line class="sec01" x1="2090.000" y1="0" x2="2090.000" y2="100.000" /> +<rect class="wait" x="97.924" y="35.287" width="4.026" height="64.713" /> +<rect class="wait" x="101.950" y="99.313" width="4.010" height="0.687" /> +<rect class="wait" x="105.960" y="95.969" width="4.008" height="4.031" /> +<rect class="wait" x="109.967" y="99.281" width="4.011" height="0.719" /> +<rect class="wait" x="113.978" y="98.865" width="4.008" height="1.135" /> +<rect class="wait" x="117.986" y="97.146" width="4.007" height="2.854" /> +<rect class="wait" x="121.993" y="97.527" width="4.007" height="2.473" /> +<rect class="wait" x="126.000" y="98.849" width="4.006" height="1.151" /> +<rect class="wait" x="130.006" y="72.789" width="4.007" height="27.211" /> +<rect class="wait" x="134.013" y="44.321" width="4.123" height="55.679" /> +<rect class="wait" x="138.135" y="0.000" width="4.006" height="100.000" /> +<rect class="wait" x="142.141" y="0.000" width="4.002" height="100.000" /> +<rect class="wait" x="146.144" y="60.048" width="4.009" height="39.952" /> +<rect class="wait" x="150.152" y="85.620" width="4.010" height="14.380" /> +<rect class="wait" x="154.163" y="64.446" width="4.008" height="35.554" /> +<rect class="wait" x="158.170" y="79.586" width="4.007" height="20.414" /> +<rect class="wait" x="162.177" y="99.687" width="4.008" height="0.313" /> +<rect class="wait" x="166.186" y="0.000" width="4.006" height="100.000" /> +<rect class="wait" x="170.191" y="95.342" width="4.007" height="4.658" /> +<rect class="wait" x="174.198" y="96.040" width="4.016" height="3.960" /> +<rect class="wait" x="178.214" y="90.508" width="4.024" height="9.492" /> +<rect class="wait" x="182.238" y="87.492" width="4.006" height="12.508" /> +<rect class="wait" x="186.244" y="48.996" width="4.006" height="51.004" /> +<rect class="wait" x="190.250" y="42.892" width="4.006" height="57.108" /> +<rect class="wait" x="194.256" y="45.278" width="4.006" height="54.722" /> +<rect class="wait" x="198.262" y="96.878" width="4.006" height="3.122" /> +<rect class="wait" x="202.268" y="84.519" width="4.007" height="15.481" /> +<rect class="wait" x="206.275" y="86.499" width="4.006" height="13.501" /> +<rect class="wait" x="210.280" y="99.412" width="4.006" height="0.588" /> +<rect class="wait" x="214.286" y="76.048" width="4.007" height="23.952" /> +<rect class="wait" x="218.294" y="98.646" width="4.007" height="1.354" /> +<rect class="wait" x="222.300" y="97.733" width="4.009" height="2.267" /> +<rect class="wait" x="226.310" y="98.072" width="4.007" height="1.928" /> +<rect class="wait" x="230.317" y="98.401" width="4.010" height="1.599" /> +<rect class="wait" x="234.327" y="98.132" width="4.008" height="1.868" /> +<rect class="wait" x="238.335" y="71.501" width="4.009" height="28.499" /> +<rect class="wait" x="242.344" y="73.880" width="4.006" height="26.120" /> +<rect class="wait" x="246.350" y="97.772" width="4.008" height="2.228" /> +<rect class="wait" x="250.358" y="17.290" width="4.006" height="82.710" /> +<rect class="wait" x="254.363" y="66.613" width="4.006" height="33.387" /> +<rect class="wait" x="258.369" y="55.174" width="4.008" height="44.826" /> +<rect class="wait" x="262.377" y="95.515" width="4.009" height="4.485" /> +<rect class="wait" x="266.386" y="72.351" width="4.007" height="27.649" /> +<rect class="wait" x="270.393" y="65.568" width="4.007" height="34.432" /> +<rect class="wait" x="274.400" y="66.708" width="4.007" height="33.292" /> +<rect class="wait" x="278.406" y="70.063" width="4.008" height="29.937" /> +<rect class="wait" x="282.414" y="83.990" width="4.007" height="16.010" /> +<rect class="wait" x="286.422" y="97.803" width="4.006" height="2.197" /> +<rect class="wait" x="290.428" y="98.908" width="4.006" height="1.092" /> +<rect class="wait" x="294.434" y="91.964" width="4.007" height="8.036" /> +<rect class="wait" x="298.441" y="92.414" width="4.006" height="7.586" /> +<rect class="wait" x="302.446" y="65.910" width="4.007" height="34.090" /> +<rect class="wait" x="306.453" y="70.559" width="4.006" height="29.441" /> +<rect class="wait" x="310.459" y="87.371" width="4.009" height="12.629" /> +<rect class="wait" x="314.468" y="80.394" width="4.008" height="19.606" /> +<rect class="wait" x="318.476" y="98.045" width="4.007" height="1.955" /> +<rect class="wait" x="322.483" y="96.899" width="4.008" height="3.101" /> +<rect class="wait" x="326.491" y="96.786" width="4.009" height="3.214" /> +<rect class="wait" x="330.500" y="99.442" width="4.006" height="0.558" /> +<rect class="wait" x="334.506" y="98.643" width="4.008" height="1.357" /> +<rect class="wait" x="338.513" y="93.216" width="4.008" height="6.784" /> +<rect class="wait" x="342.521" y="98.599" width="4.008" height="1.401" /> +<rect class="wait" x="346.529" y="99.746" width="4.008" height="0.254" /> +<rect class="wait" x="350.538" y="98.681" width="4.010" height="1.319" /> +<rect class="wait" x="354.547" y="96.609" width="4.008" height="3.391" /> +<rect class="wait" x="358.555" y="96.693" width="4.007" height="3.307" /> +<rect class="wait" x="362.562" y="96.296" width="4.007" height="3.704" /> +<rect class="wait" x="366.569" y="95.250" width="4.007" height="4.750" /> +<rect class="wait" x="370.576" y="98.147" width="4.008" height="1.853" /> +<rect class="wait" x="374.584" y="93.078" width="4.006" height="6.922" /> +<rect class="wait" x="378.590" y="54.833" width="4.006" height="45.167" /> +<rect class="wait" x="382.596" y="74.017" width="4.007" height="25.983" /> +<rect class="wait" x="386.603" y="93.137" width="4.007" height="6.863" /> +<rect class="wait" x="390.610" y="64.356" width="4.006" height="35.644" /> +<rect class="wait" x="394.616" y="70.402" width="4.008" height="29.598" /> +<rect class="wait" x="398.624" y="70.441" width="4.021" height="29.559" /> +<rect class="wait" x="402.645" y="84.670" width="4.011" height="15.330" /> +<rect class="wait" x="406.656" y="92.338" width="4.007" height="7.662" /> +<rect class="wait" x="410.663" y="99.699" width="4.007" height="0.301" /> +<rect class="wait" x="414.670" y="99.781" width="4.007" height="0.219" /> +<rect class="wait" x="418.677" y="73.888" width="4.007" height="26.112" /> +<rect class="wait" x="422.684" y="66.013" width="4.012" height="33.987" /> +<rect class="wait" x="426.696" y="88.433" width="4.006" height="11.567" /> +<rect class="wait" x="430.702" y="86.232" width="4.006" height="13.768" /> +<rect class="wait" x="434.708" y="96.975" width="4.014" height="3.025" /> +<rect class="wait" x="438.722" y="81.770" width="4.008" height="18.230" /> +<rect class="wait" x="442.730" y="59.203" width="4.010" height="40.797" /> +<rect class="wait" x="446.740" y="98.131" width="4.005" height="1.869" /> +<rect class="wait" x="450.745" y="99.548" width="4.007" height="0.452" /> +<rect class="wait" x="454.752" y="99.831" width="4.007" height="0.169" /> +<rect class="wait" x="458.759" y="97.237" width="4.007" height="2.763" /> +<rect class="wait" x="462.766" y="97.616" width="4.010" height="2.384" /> +<rect class="wait" x="466.776" y="97.964" width="4.008" height="2.036" /> +<rect class="wait" x="470.784" y="98.535" width="4.008" height="1.465" /> +<rect class="wait" x="474.792" y="93.757" width="4.007" height="6.243" /> +<rect class="wait" x="478.799" y="99.366" width="4.009" height="0.634" /> +<rect class="wait" x="482.808" y="98.020" width="4.006" height="1.980" /> +<rect class="wait" x="486.814" y="71.959" width="4.006" height="28.041" /> +<rect class="wait" x="490.819" y="92.153" width="4.006" height="7.847" /> +<rect class="wait" x="494.825" y="97.526" width="4.006" height="2.474" /> +<rect class="wait" x="498.831" y="95.805" width="4.006" height="4.195" /> +<rect class="wait" x="502.838" y="66.251" width="4.006" height="33.749" /> +<rect class="wait" x="506.844" y="79.103" width="4.006" height="20.897" /> +<rect class="wait" x="510.850" y="25.741" width="4.008" height="74.259" /> +<rect class="wait" x="514.858" y="0.000" width="4.006" height="100.000" /> +<rect class="wait" x="518.864" y="35.210" width="4.006" height="64.790" /> +<rect class="wait" x="522.870" y="45.007" width="4.006" height="54.993" /> +<rect class="wait" x="526.876" y="67.319" width="4.007" height="32.681" /> +<rect class="wait" x="530.883" y="61.615" width="4.006" height="38.385" /> +<rect class="wait" x="534.889" y="90.239" width="4.006" height="9.761" /> +<rect class="wait" x="538.895" y="79.897" width="4.007" height="20.103" /> +<rect class="wait" x="542.902" y="82.986" width="4.009" height="17.014" /> +<rect class="wait" x="546.911" y="77.031" width="4.006" height="22.969" /> +<rect class="wait" x="550.917" y="67.200" width="4.006" height="32.800" /> +<rect class="wait" x="554.922" y="70.221" width="4.007" height="29.779" /> +<rect class="wait" x="558.930" y="36.243" width="4.006" height="63.757" /> +<rect class="wait" x="562.936" y="63.419" width="4.006" height="36.581" /> +<rect class="wait" x="566.943" y="91.735" width="4.006" height="8.265" /> +<rect class="wait" x="570.949" y="94.487" width="4.007" height="5.513" /> +<rect class="wait" x="574.956" y="96.669" width="4.010" height="3.331" /> +<rect class="wait" x="578.966" y="83.197" width="4.007" height="16.803" /> +<rect class="wait" x="582.973" y="99.586" width="4.008" height="0.414" /> +<rect class="wait" x="586.981" y="98.671" width="4.009" height="1.329" /> +<rect class="wait" x="590.990" y="99.485" width="4.008" height="0.515" /> +<rect class="wait" x="594.998" y="99.038" width="4.010" height="0.962" /> +<rect class="wait" x="599.008" y="95.761" width="4.006" height="4.239" /> +<rect class="wait" x="603.014" y="97.110" width="4.007" height="2.890" /> +<rect class="wait" x="607.021" y="99.154" width="4.009" height="0.846" /> +<rect class="wait" x="611.030" y="94.601" width="4.007" height="5.399" /> +<rect class="wait" x="615.037" y="87.395" width="4.009" height="12.605" /> +<rect class="wait" x="619.046" y="98.024" width="4.008" height="1.976" /> +<rect class="wait" x="623.054" y="97.652" width="4.007" height="2.348" /> +<rect class="wait" x="627.061" y="98.979" width="4.007" height="1.021" /> +<rect class="wait" x="631.068" y="99.691" width="4.007" height="0.309" /> +<rect class="wait" x="635.075" y="97.175" width="4.009" height="2.825" /> +<rect class="wait" x="639.084" y="97.114" width="4.006" height="2.886" /> +<rect class="wait" x="643.090" y="78.679" width="4.007" height="21.321" /> +<rect class="wait" x="647.097" y="88.335" width="4.007" height="11.665" /> +<rect class="wait" x="651.104" y="92.725" width="4.007" height="7.275" /> +<rect class="wait" x="655.111" y="76.093" width="4.006" height="23.907" /> +<rect class="wait" x="659.117" y="99.656" width="4.008" height="0.344" /> +<rect class="wait" x="663.125" y="95.998" width="4.008" height="4.002" /> +<rect class="wait" x="667.133" y="99.785" width="4.012" height="0.215" /> +<rect class="wait" x="671.145" y="96.582" width="4.006" height="3.418" /> +<rect class="wait" x="679.161" y="99.863" width="4.011" height="0.137" /> +<rect class="wait" x="683.171" y="99.849" width="4.009" height="0.151" /> +<rect class="wait" x="687.180" y="99.894" width="4.009" height="0.106" /> +<rect class="wait" x="691.189" y="99.716" width="4.010" height="0.284" /> +<rect class="wait" x="695.200" y="91.653" width="4.007" height="8.347" /> +<rect class="wait" x="699.207" y="91.163" width="4.010" height="8.837" /> +<rect class="wait" x="703.216" y="97.795" width="4.009" height="2.205" /> +<rect class="wait" x="707.226" y="99.798" width="4.009" height="0.202" /> +<rect class="wait" x="711.235" y="97.987" width="4.010" height="2.013" /> +<rect class="wait" x="715.245" y="98.040" width="4.014" height="1.960" /> +<rect class="wait" x="719.258" y="88.477" width="4.007" height="11.523" /> +<rect class="wait" x="723.265" y="98.033" width="4.008" height="1.967" /> +<rect class="wait" x="731.286" y="96.728" width="4.009" height="3.272" /> +<rect class="wait" x="735.295" y="92.921" width="4.009" height="7.079" /> +<rect class="wait" x="739.304" y="97.250" width="4.006" height="2.750" /> +<rect class="wait" x="743.310" y="95.696" width="4.013" height="4.304" /> +<rect class="wait" x="747.323" y="96.132" width="4.007" height="3.868" /> +<rect class="wait" x="751.330" y="99.863" width="4.010" height="0.137" /> +<rect class="wait" x="755.340" y="99.592" width="4.010" height="0.408" /> +<rect class="wait" x="759.350" y="97.391" width="4.009" height="2.609" /> +<rect class="wait" x="763.359" y="99.763" width="4.008" height="0.237" /> +<rect class="wait" x="767.367" y="99.684" width="4.014" height="0.316" /> +<rect class="wait" x="771.381" y="68.038" width="4.009" height="31.962" /> +<rect class="wait" x="775.390" y="90.474" width="4.006" height="9.526" /> +<rect class="wait" x="779.396" y="99.690" width="4.010" height="0.310" /> +<rect class="wait" x="783.406" y="99.498" width="4.009" height="0.502" /> +<rect class="wait" x="787.415" y="99.527" width="4.007" height="0.473" /> +<rect class="wait" x="791.422" y="92.078" width="4.006" height="7.922" /> +<rect class="wait" x="795.428" y="99.286" width="4.008" height="0.714" /> +<rect class="wait" x="799.436" y="95.148" width="4.008" height="4.852" /> +<rect class="wait" x="803.444" y="89.909" width="4.011" height="10.091" /> +<rect class="wait" x="807.454" y="90.589" width="4.006" height="9.411" /> +<rect class="wait" x="811.460" y="98.096" width="4.010" height="1.904" /> +<rect class="wait" x="815.470" y="93.869" width="4.007" height="6.131" /> +<rect class="wait" x="819.477" y="92.757" width="4.006" height="7.243" /> +<rect class="wait" x="823.483" y="95.321" width="4.008" height="4.679" /> +<rect class="wait" x="827.492" y="98.183" width="4.009" height="1.817" /> +<rect class="wait" x="831.500" y="93.348" width="4.010" height="6.652" /> +<rect class="wait" x="835.510" y="99.736" width="4.007" height="0.264" /> +<rect class="wait" x="839.517" y="99.228" width="4.011" height="0.772" /> +<rect class="wait" x="843.528" y="98.762" width="4.010" height="1.238" /> +<rect class="wait" x="847.538" y="91.809" width="4.006" height="8.191" /> +<rect class="wait" x="863.563" y="92.811" width="4.007" height="7.189" /> +<rect class="wait" x="867.570" y="66.221" width="4.015" height="33.779" /> +<rect class="wait" x="871.585" y="73.347" width="4.006" height="26.653" /> +<rect class="wait" x="875.591" y="98.334" width="4.006" height="1.666" /> +<rect class="wait" x="883.605" y="98.750" width="4.006" height="1.250" /> +<rect class="wait" x="887.611" y="99.351" width="4.006" height="0.649" /> +<rect class="wait" x="891.617" y="98.860" width="4.009" height="1.140" /> +<rect class="wait" x="895.626" y="99.046" width="4.006" height="0.954" /> +<rect class="wait" x="899.632" y="99.267" width="4.006" height="0.733" /> +<rect class="wait" x="903.639" y="99.233" width="4.006" height="0.767" /> +<rect class="wait" x="907.644" y="96.718" width="4.006" height="3.282" /> +<rect class="wait" x="911.650" y="99.116" width="4.006" height="0.884" /> +<rect class="wait" x="915.656" y="98.000" width="4.007" height="2.000" /> +<rect class="wait" x="919.664" y="96.977" width="4.007" height="3.023" /> +<rect class="wait" x="923.671" y="98.710" width="4.008" height="1.290" /> +<rect class="wait" x="939.706" y="99.875" width="4.010" height="0.125" /> +<rect class="wait" x="943.717" y="99.844" width="4.008" height="0.156" /> +<rect class="wait" x="947.725" y="99.858" width="4.008" height="0.142" /> +<rect class="wait" x="951.733" y="99.877" width="4.006" height="0.123" /> +<rect class="wait" x="955.739" y="99.877" width="4.008" height="0.123" /> +<rect class="wait" x="963.758" y="98.504" width="4.008" height="1.496" /> +<rect class="wait" x="967.766" y="96.968" width="4.007" height="3.032" /> +<rect class="wait" x="971.773" y="99.761" width="4.010" height="0.239" /> +<rect class="wait" x="975.783" y="99.806" width="4.014" height="0.194" /> +<rect class="wait" x="979.797" y="99.876" width="4.009" height="0.124" /> +<rect class="wait" x="983.805" y="99.851" width="4.009" height="0.149" /> +<rect class="wait" x="987.814" y="99.893" width="4.014" height="0.107" /> +<rect class="wait" x="991.828" y="99.743" width="4.010" height="0.257" /> +<rect class="wait" x="995.837" y="99.891" width="4.014" height="0.109" /> +<rect class="wait" x="999.852" y="99.859" width="4.015" height="0.141" /> +<rect class="wait" x="1003.866" y="97.983" width="4.010" height="2.017" /> +<rect class="wait" x="1007.876" y="99.870" width="4.014" height="0.130" /> +<rect class="wait" x="1011.890" y="99.874" width="4.009" height="0.126" /> +<rect class="wait" x="1015.900" y="99.871" width="4.014" height="0.129" /> +<rect class="wait" x="1023.928" y="99.713" width="4.010" height="0.287" /> +<rect class="wait" x="1027.938" y="99.896" width="4.009" height="0.104" /> +<rect class="wait" x="1031.947" y="96.764" width="4.008" height="3.236" /> +<rect class="wait" x="1035.955" y="97.678" width="4.008" height="2.322" /> +<rect class="wait" x="1039.963" y="98.479" width="4.006" height="1.521" /> +<rect class="wait" x="1043.969" y="96.901" width="4.007" height="3.099" /> +<rect class="wait" x="1047.976" y="98.249" width="4.007" height="1.751" /> +<rect class="wait" x="1051.984" y="99.694" width="4.006" height="0.306" /> +<rect class="wait" x="1055.990" y="99.420" width="4.011" height="0.580" /> +<rect class="wait" x="1060.001" y="99.462" width="4.007" height="0.538" /> +<rect class="wait" x="1064.008" y="96.707" width="4.006" height="3.293" /> +<rect class="wait" x="1068.014" y="98.276" width="4.006" height="1.724" /> +<rect class="wait" x="1072.020" y="98.731" width="4.007" height="1.269" /> +<rect class="wait" x="1076.027" y="99.399" width="4.013" height="0.601" /> +<rect class="wait" x="1080.040" y="98.579" width="4.008" height="1.421" /> +<rect class="wait" x="1084.048" y="99.040" width="4.010" height="0.960" /> +<rect class="wait" x="1088.058" y="98.633" width="4.014" height="1.367" /> +<rect class="wait" x="1108.125" y="99.869" width="4.015" height="0.131" /> +<rect class="wait" x="1124.183" y="99.155" width="4.014" height="0.845" /> +<rect class="wait" x="1184.394" y="99.779" width="4.014" height="0.221" /> +<rect class="wait" x="1192.422" y="99.891" width="4.014" height="0.109" /> +<rect class="wait" x="1200.451" y="98.339" width="4.010" height="1.661" /> +<rect class="wait" x="1204.461" y="98.286" width="4.006" height="1.714" /> +<rect class="wait" x="1224.524" y="99.832" width="4.014" height="0.168" /> +<rect class="wait" x="1244.592" y="98.479" width="4.014" height="1.521" /> +<rect class="wait" x="1284.728" y="99.879" width="4.021" height="0.121" /> +<rect class="wait" x="1304.806" y="99.803" width="4.014" height="0.197" /> +<rect class="wait" x="1336.922" y="99.885" width="4.014" height="0.115" /> +<rect class="wait" x="1365.021" y="99.807" width="4.014" height="0.193" /> +<rect class="wait" x="1373.050" y="99.651" width="4.015" height="0.349" /> +<rect class="wait" x="1393.124" y="99.885" width="4.014" height="0.115" /> +<rect class="wait" x="1397.138" y="99.469" width="4.013" height="0.531" /> +<rect class="wait" x="1449.323" y="99.861" width="4.015" height="0.139" /> +<rect class="wait" x="1477.418" y="99.627" width="4.015" height="0.373" /> +<rect class="wait" x="1485.446" y="99.895" width="4.009" height="0.105" /> +<rect class="wait" x="1497.485" y="96.493" width="4.010" height="3.507" /> +<rect class="wait" x="1545.649" y="99.651" width="4.014" height="0.349" /> +<rect class="wait" x="1577.764" y="99.589" width="4.014" height="0.411" /> +<rect class="wait" x="1605.865" y="99.836" width="4.015" height="0.164" /> +<rect class="wait" x="1646.007" y="99.213" width="4.008" height="0.787" /> +<rect class="wait" x="1650.015" y="97.707" width="4.014" height="2.293" /> +<rect class="wait" x="1654.030" y="99.737" width="4.016" height="0.263" /> +<rect class="wait" x="1666.075" y="99.586" width="4.015" height="0.414" /> +<rect class="wait" x="1674.104" y="99.630" width="4.014" height="0.370" /> +<rect class="wait" x="1678.118" y="97.148" width="4.008" height="2.852" /> +<rect class="wait" x="1682.126" y="97.175" width="4.007" height="2.825" /> +<rect class="wait" x="1686.133" y="99.370" width="4.007" height="0.630" /> +<rect class="wait" x="1694.150" y="99.877" width="4.009" height="0.123" /> +<rect class="wait" x="1702.166" y="99.840" width="4.007" height="0.160" /> +<rect class="wait" x="1706.173" y="99.859" width="4.013" height="0.141" /> +<rect class="wait" x="1710.186" y="99.892" width="4.007" height="0.108" /> +<rect class="wait" x="1714.193" y="99.870" width="4.007" height="0.130" /> +<rect class="wait" x="1722.208" y="99.823" width="4.013" height="0.177" /> +<rect class="wait" x="1726.220" y="99.846" width="4.009" height="0.154" /> +<rect class="wait" x="1730.230" y="99.859" width="4.006" height="0.141" /> +<rect class="wait" x="1734.236" y="99.771" width="4.007" height="0.229" /> +<rect class="wait" x="1738.243" y="99.498" width="4.015" height="0.502" /> +<rect class="wait" x="1742.258" y="98.645" width="4.012" height="1.355" /> +<rect class="wait" x="1762.327" y="99.861" width="4.011" height="0.139" /> +<rect class="wait" x="1786.409" y="98.787" width="4.014" height="1.213" /> +<rect class="wait" x="1790.424" y="99.896" width="4.015" height="0.104" /> +<rect class="wait" x="1818.525" y="99.818" width="4.014" height="0.182" /> +<rect class="wait" x="1846.625" y="98.847" width="4.014" height="1.153" /> +<rect class="wait" x="1850.640" y="99.854" width="4.014" height="0.146" /> +<rect class="wait" x="1858.668" y="91.411" width="4.011" height="8.589" /> +<rect class="wait" x="1874.722" y="99.895" width="4.014" height="0.105" /> +<rect class="wait" x="1878.736" y="99.775" width="4.015" height="0.225" /> +<rect class="wait" x="1906.834" y="99.642" width="4.014" height="0.358" /> +<rect class="wait" x="1967.047" y="99.780" width="4.015" height="0.220" /> +<rect class="wait" x="1979.089" y="99.760" width="4.014" height="0.240" /> +<rect class="wait" x="1999.160" y="99.201" width="4.014" height="0.799" /> +<rect class="wait" x="2007.188" y="99.875" width="4.014" height="0.125" /> +<rect class="wait" x="2027.259" y="99.190" width="4.014" height="0.810" /> +<rect class="wait" x="2087.469" y="98.647" width="4.011" height="1.353" /> +</g> + +<g transform="translate(10,960.000)"> +<!-- initcall --> +<text class="t2" x="5" y="-15">Kernel init threads</text> +<rect class="box" x="0.000" y="0" width="2095.495" height="920.000" /> + <line class="sec5" x1="0.000" y1="0" x2="0.000" y2="920.000" /> + <text class="sec" x="0.000" y="-5.000" >0.0s</text> + <line class="sec01" x1="10.000" y1="0" x2="10.000" y2="920.000" /> + <line class="sec01" x1="20.000" y1="0" x2="20.000" y2="920.000" /> + <line class="sec01" x1="30.000" y1="0" x2="30.000" y2="920.000" /> + <line class="sec01" x1="40.000" y1="0" x2="40.000" y2="920.000" /> + <line class="sec01" x1="50.000" y1="0" x2="50.000" y2="920.000" /> + <line class="sec01" x1="60.000" y1="0" x2="60.000" y2="920.000" /> + <line class="sec01" x1="70.000" y1="0" x2="70.000" y2="920.000" /> + <line class="sec01" x1="80.000" y1="0" x2="80.000" y2="920.000" /> + <line class="sec01" x1="90.000" y1="0" x2="90.000" y2="920.000" /> + <line class="sec1" x1="100.000" y1="0" x2="100.000" y2="920.000" /> + <text class="sec" x="100.000" y="-5.000" >1.0s</text> + <line class="sec01" x1="110.000" y1="0" x2="110.000" y2="920.000" /> + <line class="sec01" x1="120.000" y1="0" x2="120.000" y2="920.000" /> + <line class="sec01" x1="130.000" y1="0" x2="130.000" y2="920.000" /> + <line class="sec01" x1="140.000" y1="0" x2="140.000" y2="920.000" /> + <line class="sec01" x1="150.000" y1="0" x2="150.000" y2="920.000" /> + <line class="sec01" x1="160.000" y1="0" x2="160.000" y2="920.000" /> + <line class="sec01" x1="170.000" y1="0" x2="170.000" y2="920.000" /> + <line class="sec01" x1="180.000" y1="0" x2="180.000" y2="920.000" /> + <line class="sec01" x1="190.000" y1="0" x2="190.000" y2="920.000" /> + <line class="sec1" x1="200.000" y1="0" x2="200.000" y2="920.000" /> + <text class="sec" x="200.000" y="-5.000" >2.0s</text> + <line class="sec01" x1="210.000" y1="0" x2="210.000" y2="920.000" /> + <line class="sec01" x1="220.000" y1="0" x2="220.000" y2="920.000" /> + <line class="sec01" x1="230.000" y1="0" x2="230.000" y2="920.000" /> + <line class="sec01" x1="240.000" y1="0" x2="240.000" y2="920.000" /> + <line class="sec01" x1="250.000" y1="0" x2="250.000" y2="920.000" /> + <line class="sec01" x1="260.000" y1="0" x2="260.000" y2="920.000" /> + <line class="sec01" x1="270.000" y1="0" x2="270.000" y2="920.000" /> + <line class="sec01" x1="280.000" y1="0" x2="280.000" y2="920.000" /> + <line class="sec01" x1="290.000" y1="0" x2="290.000" y2="920.000" /> + <line class="sec1" x1="300.000" y1="0" x2="300.000" y2="920.000" /> + <text class="sec" x="300.000" y="-5.000" >3.0s</text> + <line class="sec01" x1="310.000" y1="0" x2="310.000" y2="920.000" /> + <line class="sec01" x1="320.000" y1="0" x2="320.000" y2="920.000" /> + <line class="sec01" x1="330.000" y1="0" x2="330.000" y2="920.000" /> + <line class="sec01" x1="340.000" y1="0" x2="340.000" y2="920.000" /> + <line class="sec01" x1="350.000" y1="0" x2="350.000" y2="920.000" /> + <line class="sec01" x1="360.000" y1="0" x2="360.000" y2="920.000" /> + <line class="sec01" x1="370.000" y1="0" x2="370.000" y2="920.000" /> + <line class="sec01" x1="380.000" y1="0" x2="380.000" y2="920.000" /> + <line class="sec01" x1="390.000" y1="0" x2="390.000" y2="920.000" /> + <line class="sec1" x1="400.000" y1="0" x2="400.000" y2="920.000" /> + <text class="sec" x="400.000" y="-5.000" >4.0s</text> + <line class="sec01" x1="410.000" y1="0" x2="410.000" y2="920.000" /> + <line class="sec01" x1="420.000" y1="0" x2="420.000" y2="920.000" /> + <line class="sec01" x1="430.000" y1="0" x2="430.000" y2="920.000" /> + <line class="sec01" x1="440.000" y1="0" x2="440.000" y2="920.000" /> + <line class="sec01" x1="450.000" y1="0" x2="450.000" y2="920.000" /> + <line class="sec01" x1="460.000" y1="0" x2="460.000" y2="920.000" /> + <line class="sec01" x1="470.000" y1="0" x2="470.000" y2="920.000" /> + <line class="sec01" x1="480.000" y1="0" x2="480.000" y2="920.000" /> + <line class="sec01" x1="490.000" y1="0" x2="490.000" y2="920.000" /> + <line class="sec5" x1="500.000" y1="0" x2="500.000" y2="920.000" /> + <text class="sec" x="500.000" y="-5.000" >5.0s</text> + <line class="sec01" x1="510.000" y1="0" x2="510.000" y2="920.000" /> + <line class="sec01" x1="520.000" y1="0" x2="520.000" y2="920.000" /> + <line class="sec01" x1="530.000" y1="0" x2="530.000" y2="920.000" /> + <line class="sec01" x1="540.000" y1="0" x2="540.000" y2="920.000" /> + <line class="sec01" x1="550.000" y1="0" x2="550.000" y2="920.000" /> + <line class="sec01" x1="560.000" y1="0" x2="560.000" y2="920.000" /> + <line class="sec01" x1="570.000" y1="0" x2="570.000" y2="920.000" /> + <line class="sec01" x1="580.000" y1="0" x2="580.000" y2="920.000" /> + <line class="sec01" x1="590.000" y1="0" x2="590.000" y2="920.000" /> + <line class="sec1" x1="600.000" y1="0" x2="600.000" y2="920.000" /> + <text class="sec" x="600.000" y="-5.000" >6.0s</text> + <line class="sec01" x1="610.000" y1="0" x2="610.000" y2="920.000" /> + <line class="sec01" x1="620.000" y1="0" x2="620.000" y2="920.000" /> + <line class="sec01" x1="630.000" y1="0" x2="630.000" y2="920.000" /> + <line class="sec01" x1="640.000" y1="0" x2="640.000" y2="920.000" /> + <line class="sec01" x1="650.000" y1="0" x2="650.000" y2="920.000" /> + <line class="sec01" x1="660.000" y1="0" x2="660.000" y2="920.000" /> + <line class="sec01" x1="670.000" y1="0" x2="670.000" y2="920.000" /> + <line class="sec01" x1="680.000" y1="0" x2="680.000" y2="920.000" /> + <line class="sec01" x1="690.000" y1="0" x2="690.000" y2="920.000" /> + <line class="sec1" x1="700.000" y1="0" x2="700.000" y2="920.000" /> + <text class="sec" x="700.000" y="-5.000" >7.0s</text> + <line class="sec01" x1="710.000" y1="0" x2="710.000" y2="920.000" /> + <line class="sec01" x1="720.000" y1="0" x2="720.000" y2="920.000" /> + <line class="sec01" x1="730.000" y1="0" x2="730.000" y2="920.000" /> + <line class="sec01" x1="740.000" y1="0" x2="740.000" y2="920.000" /> + <line class="sec01" x1="750.000" y1="0" x2="750.000" y2="920.000" /> + <line class="sec01" x1="760.000" y1="0" x2="760.000" y2="920.000" /> + <line class="sec01" x1="770.000" y1="0" x2="770.000" y2="920.000" /> + <line class="sec01" x1="780.000" y1="0" x2="780.000" y2="920.000" /> + <line class="sec01" x1="790.000" y1="0" x2="790.000" y2="920.000" /> + <line class="sec1" x1="800.000" y1="0" x2="800.000" y2="920.000" /> + <text class="sec" x="800.000" y="-5.000" >8.0s</text> + <line class="sec01" x1="810.000" y1="0" x2="810.000" y2="920.000" /> + <line class="sec01" x1="820.000" y1="0" x2="820.000" y2="920.000" /> + <line class="sec01" x1="830.000" y1="0" x2="830.000" y2="920.000" /> + <line class="sec01" x1="840.000" y1="0" x2="840.000" y2="920.000" /> + <line class="sec01" x1="850.000" y1="0" x2="850.000" y2="920.000" /> + <line class="sec01" x1="860.000" y1="0" x2="860.000" y2="920.000" /> + <line class="sec01" x1="870.000" y1="0" x2="870.000" y2="920.000" /> + <line class="sec01" x1="880.000" y1="0" x2="880.000" y2="920.000" /> + <line class="sec01" x1="890.000" y1="0" x2="890.000" y2="920.000" /> + <line class="sec1" x1="900.000" y1="0" x2="900.000" y2="920.000" /> + <text class="sec" x="900.000" y="-5.000" >9.0s</text> + <line class="sec01" x1="910.000" y1="0" x2="910.000" y2="920.000" /> + <line class="sec01" x1="920.000" y1="0" x2="920.000" y2="920.000" /> + <line class="sec01" x1="930.000" y1="0" x2="930.000" y2="920.000" /> + <line class="sec01" x1="940.000" y1="0" x2="940.000" y2="920.000" /> + <line class="sec01" x1="950.000" y1="0" x2="950.000" y2="920.000" /> + <line class="sec01" x1="960.000" y1="0" x2="960.000" y2="920.000" /> + <line class="sec01" x1="970.000" y1="0" x2="970.000" y2="920.000" /> + <line class="sec01" x1="980.000" y1="0" x2="980.000" y2="920.000" /> + <line class="sec01" x1="990.000" y1="0" x2="990.000" y2="920.000" /> + <line class="sec5" x1="1000.000" y1="0" x2="1000.000" y2="920.000" /> + <text class="sec" x="1000.000" y="-5.000" >10.0s</text> + <line class="sec01" x1="1010.000" y1="0" x2="1010.000" y2="920.000" /> + <line class="sec01" x1="1020.000" y1="0" x2="1020.000" y2="920.000" /> + <line class="sec01" x1="1030.000" y1="0" x2="1030.000" y2="920.000" /> + <line class="sec01" x1="1040.000" y1="0" x2="1040.000" y2="920.000" /> + <line class="sec01" x1="1050.000" y1="0" x2="1050.000" y2="920.000" /> + <line class="sec01" x1="1060.000" y1="0" x2="1060.000" y2="920.000" /> + <line class="sec01" x1="1070.000" y1="0" x2="1070.000" y2="920.000" /> + <line class="sec01" x1="1080.000" y1="0" x2="1080.000" y2="920.000" /> + <line class="sec01" x1="1090.000" y1="0" x2="1090.000" y2="920.000" /> + <line class="sec1" x1="1100.000" y1="0" x2="1100.000" y2="920.000" /> + <text class="sec" x="1100.000" y="-5.000" >11.0s</text> + <line class="sec01" x1="1110.000" y1="0" x2="1110.000" y2="920.000" /> + <line class="sec01" x1="1120.000" y1="0" x2="1120.000" y2="920.000" /> + <line class="sec01" x1="1130.000" y1="0" x2="1130.000" y2="920.000" /> + <line class="sec01" x1="1140.000" y1="0" x2="1140.000" y2="920.000" /> + <line class="sec01" x1="1150.000" y1="0" x2="1150.000" y2="920.000" /> + <line class="sec01" x1="1160.000" y1="0" x2="1160.000" y2="920.000" /> + <line class="sec01" x1="1170.000" y1="0" x2="1170.000" y2="920.000" /> + <line class="sec01" x1="1180.000" y1="0" x2="1180.000" y2="920.000" /> + <line class="sec01" x1="1190.000" y1="0" x2="1190.000" y2="920.000" /> + <line class="sec1" x1="1200.000" y1="0" x2="1200.000" y2="920.000" /> + <text class="sec" x="1200.000" y="-5.000" >12.0s</text> + <line class="sec01" x1="1210.000" y1="0" x2="1210.000" y2="920.000" /> + <line class="sec01" x1="1220.000" y1="0" x2="1220.000" y2="920.000" /> + <line class="sec01" x1="1230.000" y1="0" x2="1230.000" y2="920.000" /> + <line class="sec01" x1="1240.000" y1="0" x2="1240.000" y2="920.000" /> + <line class="sec01" x1="1250.000" y1="0" x2="1250.000" y2="920.000" /> + <line class="sec01" x1="1260.000" y1="0" x2="1260.000" y2="920.000" /> + <line class="sec01" x1="1270.000" y1="0" x2="1270.000" y2="920.000" /> + <line class="sec01" x1="1280.000" y1="0" x2="1280.000" y2="920.000" /> + <line class="sec01" x1="1290.000" y1="0" x2="1290.000" y2="920.000" /> + <line class="sec1" x1="1300.000" y1="0" x2="1300.000" y2="920.000" /> + <text class="sec" x="1300.000" y="-5.000" >13.0s</text> + <line class="sec01" x1="1310.000" y1="0" x2="1310.000" y2="920.000" /> + <line class="sec01" x1="1320.000" y1="0" x2="1320.000" y2="920.000" /> + <line class="sec01" x1="1330.000" y1="0" x2="1330.000" y2="920.000" /> + <line class="sec01" x1="1340.000" y1="0" x2="1340.000" y2="920.000" /> + <line class="sec01" x1="1350.000" y1="0" x2="1350.000" y2="920.000" /> + <line class="sec01" x1="1360.000" y1="0" x2="1360.000" y2="920.000" /> + <line class="sec01" x1="1370.000" y1="0" x2="1370.000" y2="920.000" /> + <line class="sec01" x1="1380.000" y1="0" x2="1380.000" y2="920.000" /> + <line class="sec01" x1="1390.000" y1="0" x2="1390.000" y2="920.000" /> + <line class="sec1" x1="1400.000" y1="0" x2="1400.000" y2="920.000" /> + <text class="sec" x="1400.000" y="-5.000" >14.0s</text> + <line class="sec01" x1="1410.000" y1="0" x2="1410.000" y2="920.000" /> + <line class="sec01" x1="1420.000" y1="0" x2="1420.000" y2="920.000" /> + <line class="sec01" x1="1430.000" y1="0" x2="1430.000" y2="920.000" /> + <line class="sec01" x1="1440.000" y1="0" x2="1440.000" y2="920.000" /> + <line class="sec01" x1="1450.000" y1="0" x2="1450.000" y2="920.000" /> + <line class="sec01" x1="1460.000" y1="0" x2="1460.000" y2="920.000" /> + <line class="sec01" x1="1470.000" y1="0" x2="1470.000" y2="920.000" /> + <line class="sec01" x1="1480.000" y1="0" x2="1480.000" y2="920.000" /> + <line class="sec01" x1="1490.000" y1="0" x2="1490.000" y2="920.000" /> + <line class="sec5" x1="1500.000" y1="0" x2="1500.000" y2="920.000" /> + <text class="sec" x="1500.000" y="-5.000" >15.0s</text> + <line class="sec01" x1="1510.000" y1="0" x2="1510.000" y2="920.000" /> + <line class="sec01" x1="1520.000" y1="0" x2="1520.000" y2="920.000" /> + <line class="sec01" x1="1530.000" y1="0" x2="1530.000" y2="920.000" /> + <line class="sec01" x1="1540.000" y1="0" x2="1540.000" y2="920.000" /> + <line class="sec01" x1="1550.000" y1="0" x2="1550.000" y2="920.000" /> + <line class="sec01" x1="1560.000" y1="0" x2="1560.000" y2="920.000" /> + <line class="sec01" x1="1570.000" y1="0" x2="1570.000" y2="920.000" /> + <line class="sec01" x1="1580.000" y1="0" x2="1580.000" y2="920.000" /> + <line class="sec01" x1="1590.000" y1="0" x2="1590.000" y2="920.000" /> + <line class="sec1" x1="1600.000" y1="0" x2="1600.000" y2="920.000" /> + <text class="sec" x="1600.000" y="-5.000" >16.0s</text> + <line class="sec01" x1="1610.000" y1="0" x2="1610.000" y2="920.000" /> + <line class="sec01" x1="1620.000" y1="0" x2="1620.000" y2="920.000" /> + <line class="sec01" x1="1630.000" y1="0" x2="1630.000" y2="920.000" /> + <line class="sec01" x1="1640.000" y1="0" x2="1640.000" y2="920.000" /> + <line class="sec01" x1="1650.000" y1="0" x2="1650.000" y2="920.000" /> + <line class="sec01" x1="1660.000" y1="0" x2="1660.000" y2="920.000" /> + <line class="sec01" x1="1670.000" y1="0" x2="1670.000" y2="920.000" /> + <line class="sec01" x1="1680.000" y1="0" x2="1680.000" y2="920.000" /> + <line class="sec01" x1="1690.000" y1="0" x2="1690.000" y2="920.000" /> + <line class="sec1" x1="1700.000" y1="0" x2="1700.000" y2="920.000" /> + <text class="sec" x="1700.000" y="-5.000" >17.0s</text> + <line class="sec01" x1="1710.000" y1="0" x2="1710.000" y2="920.000" /> + <line class="sec01" x1="1720.000" y1="0" x2="1720.000" y2="920.000" /> + <line class="sec01" x1="1730.000" y1="0" x2="1730.000" y2="920.000" /> + <line class="sec01" x1="1740.000" y1="0" x2="1740.000" y2="920.000" /> + <line class="sec01" x1="1750.000" y1="0" x2="1750.000" y2="920.000" /> + <line class="sec01" x1="1760.000" y1="0" x2="1760.000" y2="920.000" /> + <line class="sec01" x1="1770.000" y1="0" x2="1770.000" y2="920.000" /> + <line class="sec01" x1="1780.000" y1="0" x2="1780.000" y2="920.000" /> + <line class="sec01" x1="1790.000" y1="0" x2="1790.000" y2="920.000" /> + <line class="sec1" x1="1800.000" y1="0" x2="1800.000" y2="920.000" /> + <text class="sec" x="1800.000" y="-5.000" >18.0s</text> + <line class="sec01" x1="1810.000" y1="0" x2="1810.000" y2="920.000" /> + <line class="sec01" x1="1820.000" y1="0" x2="1820.000" y2="920.000" /> + <line class="sec01" x1="1830.000" y1="0" x2="1830.000" y2="920.000" /> + <line class="sec01" x1="1840.000" y1="0" x2="1840.000" y2="920.000" /> + <line class="sec01" x1="1850.000" y1="0" x2="1850.000" y2="920.000" /> + <line class="sec01" x1="1860.000" y1="0" x2="1860.000" y2="920.000" /> + <line class="sec01" x1="1870.000" y1="0" x2="1870.000" y2="920.000" /> + <line class="sec01" x1="1880.000" y1="0" x2="1880.000" y2="920.000" /> + <line class="sec01" x1="1890.000" y1="0" x2="1890.000" y2="920.000" /> + <line class="sec1" x1="1900.000" y1="0" x2="1900.000" y2="920.000" /> + <text class="sec" x="1900.000" y="-5.000" >19.0s</text> + <line class="sec01" x1="1910.000" y1="0" x2="1910.000" y2="920.000" /> + <line class="sec01" x1="1920.000" y1="0" x2="1920.000" y2="920.000" /> + <line class="sec01" x1="1930.000" y1="0" x2="1930.000" y2="920.000" /> + <line class="sec01" x1="1940.000" y1="0" x2="1940.000" y2="920.000" /> + <line class="sec01" x1="1950.000" y1="0" x2="1950.000" y2="920.000" /> + <line class="sec01" x1="1960.000" y1="0" x2="1960.000" y2="920.000" /> + <line class="sec01" x1="1970.000" y1="0" x2="1970.000" y2="920.000" /> + <line class="sec01" x1="1980.000" y1="0" x2="1980.000" y2="920.000" /> + <line class="sec01" x1="1990.000" y1="0" x2="1990.000" y2="920.000" /> + <line class="sec5" x1="2000.000" y1="0" x2="2000.000" y2="920.000" /> + <text class="sec" x="2000.000" y="-5.000" >20.0s</text> + <line class="sec01" x1="2010.000" y1="0" x2="2010.000" y2="920.000" /> + <line class="sec01" x1="2020.000" y1="0" x2="2020.000" y2="920.000" /> + <line class="sec01" x1="2030.000" y1="0" x2="2030.000" y2="920.000" /> + <line class="sec01" x1="2040.000" y1="0" x2="2040.000" y2="920.000" /> + <line class="sec01" x1="2050.000" y1="0" x2="2050.000" y2="920.000" /> + <line class="sec01" x1="2060.000" y1="0" x2="2060.000" y2="920.000" /> + <line class="sec01" x1="2070.000" y1="0" x2="2070.000" y2="920.000" /> + <line class="sec01" x1="2080.000" y1="0" x2="2080.000" y2="920.000" /> + <line class="sec01" x1="2090.000" y1="0" x2="2090.000" y2="920.000" /> +<!-- thread="trace_init_flags_sys_exit" time="0.034" elapsed="0" result="0" --> +<!-- thread="trace_init_flags_sys_enter" time="0.034" elapsed="0" result="0" --> +<!-- thread="init_hw_perf_events" time="0.034" elapsed="0" result="0" --> +<!-- thread="register_trigger_all_cpu_backtrace" time="0.034" elapsed="0" result="0" --> +<!-- thread="spawn_ksoftirqd" time="0.034" elapsed="0" result="0" --> +<!-- thread="init_workqueues" time="0.034" elapsed="0" result="0" --> +<!-- thread="migration_init" time="0.034" elapsed="0" result="0" --> +<!-- thread="cpu_stop_init" time="0.034" elapsed="0" result="0" --> +<!-- thread="rcu_scheduler_really_started" time="0.034" elapsed="0" result="0" --> +<!-- thread="rcu_spawn_gp_kthread" time="0.034" elapsed="0" result="0" --> +<!-- thread="relay_init" time="0.034" elapsed="0" result="0" --> +<!-- thread="tracer_alloc_buffers" time="0.034" elapsed="0" result="0" --> +<!-- thread="init_events" time="0.034" elapsed="0" result="0" --> +<!-- thread="init_trace_printk" time="0.034" elapsed="0" result="0" --> +<!-- thread="init_ftrace_syscalls" time="0.035" elapsed="0" result="0" --> +<!-- thread="jump_label_init_module" time="0.035" elapsed="0" result="0" --> +<!-- thread="dynamic_debug_init" time="0.035" elapsed="976" result="0" --> +<!-- thread="ipc_ns_init" time="0.078" elapsed="0" result="0" --> +<!-- thread="init_mmap_min_addr" time="0.078" elapsed="0" result="0" --> +<!-- thread="init_cpufreq_transition_notifier_list" time="0.078" elapsed="0" result="0" --> +<!-- thread="net_ns_init" time="0.078" elapsed="0" result="0" --> +<!-- thread="e820_mark_nvs_memory" time="0.078" elapsed="0" result="0" --> +<!-- thread="cpufreq_tsc" time="0.078" elapsed="0" result="0" --> +<!-- thread="reboot_init" time="0.078" elapsed="0" result="0" --> +<!-- thread="init_lapic_sysfs" time="0.078" elapsed="0" result="0" --> +<!-- thread="cpu_hotplug_pm_sync_init" time="0.078" elapsed="0" result="0" --> +<!-- thread="alloc_frozen_cpus" time="0.078" elapsed="0" result="0" --> +<!-- thread="ksysfs_init" time="0.078" elapsed="0" result="0" --> +<!-- thread="pm_init" time="0.078" elapsed="0" result="0" --> +<!-- thread="pm_disk_init" time="0.078" elapsed="0" result="0" --> +<!-- thread="swsusp_header_init" time="0.078" elapsed="0" result="0" --> +<!-- thread="init_jiffies_clocksource" time="0.078" elapsed="0" result="0" --> +<!-- thread="ftrace_mod_cmd_init" time="0.078" elapsed="0" result="0" --> +<!-- thread="init_function_trace" time="0.078" elapsed="0" result="0" --> +<!-- thread="init_wakeup_tracer" time="0.078" elapsed="0" result="0" --> +<!-- thread="init_graph_trace" time="0.078" elapsed="0" result="0" --> +<!-- thread="event_trace_enable" time="0.079" elapsed="976" result="0" --> +<!-- thread="init_zero_pfn" time="0.079" elapsed="0" result="0" --> +<!-- thread="memory_failure_init" time="0.079" elapsed="0" result="0" --> +<!-- thread="fsnotify_init" time="0.079" elapsed="0" result="0" --> +<!-- thread="filelock_init" time="0.079" elapsed="0" result="0" --> +<!-- thread="init_script_binfmt" time="0.079" elapsed="0" result="0" --> +<!-- thread="init_elf_binfmt" time="0.079" elapsed="0" result="0" --> +<!-- thread="init_compat_elf_binfmt" time="0.079" elapsed="0" result="0" --> +<!-- thread="debugfs_init" time="0.079" elapsed="0" result="0" --> +<!-- thread="securityfs_init" time="0.079" elapsed="0" result="0" --> +<!-- thread="prandom_init" time="0.079" elapsed="0" result="0" --> +<!-- thread="test_atomic64" time="0.079" elapsed="0" result="0" --> +<!-- thread="sfi_sysfs_init" time="0.079" elapsed="0" result="0" --> +<!-- thread="virtio_init" time="0.079" elapsed="0" result="0" --> +<!-- thread="__gnttab_init" time="0.079" elapsed="0" result="-19" --> +<!-- thread="early_resume_init" time="0.079" elapsed="0" result="0" --> +<!-- thread="cpufreq_core_init" time="0.079" elapsed="0" result="0" --> +<!-- thread="cpuidle_init" time="0.079" elapsed="0" result="0" --> +<!-- thread="bsp_pm_check_init" time="0.079" elapsed="0" result="0" --> +<!-- thread="sock_init" time="0.079" elapsed="0" result="0" --> +<!-- thread="net_inuse_init" time="0.079" elapsed="0" result="0" --> +<!-- thread="netpoll_init" time="0.079" elapsed="0" result="0" --> +<!-- thread="netlink_proto_init" time="0.079" elapsed="0" result="0" --> +<!-- thread="bdi_class_init" time="0.079" elapsed="0" result="0" --> +<!-- thread="kobject_uevent_init" time="0.079" elapsed="0" result="0" --> +<!-- thread="pcibus_class_init" time="0.079" elapsed="0" result="0" --> +<!-- thread="pci_driver_init" time="0.079" elapsed="0" result="0" --> +<!-- thread="backlight_class_init" time="0.079" elapsed="0" result="0" --> +<!-- thread="xenbus_init" time="0.079" elapsed="0" result="-19" --> +<!-- thread="tty_class_init" time="0.079" elapsed="0" result="0" --> +<!-- thread="vtconsole_class_init" time="0.079" elapsed="0" result="0" --> +<!-- thread="wakeup_sources_debugfs_init" time="0.079" elapsed="0" result="0" --> +<!-- thread="register_node_type" time="0.079" elapsed="0" result="0" --> +<!-- thread="regmap_initcall" time="0.079" elapsed="0" result="0" --> +<!-- thread="amd_postcore_init" time="0.079" elapsed="0" result="0" --> +<!-- thread="set_real_mode_permissions" time="0.079" elapsed="0" result="0" --> +<!-- thread="arch_kdebugfs_init" time="0.079" elapsed="0" result="0" --> +<!-- thread="mtrr_if_init" time="0.079" elapsed="0" result="0" --> +<!-- thread="ffh_cstate_init" time="0.079" elapsed="0" result="0" --> +<!-- thread="activate_jump_labels" time="0.079" elapsed="0" result="0" --> +<!-- thread="acpi_pci_init" time="0.079" elapsed="0" result="0" --> +<!-- thread="dma_bus_init" time="0.079" elapsed="0" result="0" --> +<!-- thread="dma_channel_table_init" time="0.079" elapsed="0" result="0" --> +<!-- thread="setup_vcpu_hotplug_event" time="0.079" elapsed="0" result="-19" --> +<!-- thread="register_xen_pci_notifier" time="0.079" elapsed="0" result="0" --> +<!-- thread="xen_pcpu_init" time="0.079" elapsed="0" result="-19" --> +<!-- thread="dmi_id_init" time="0.079" elapsed="0" result="0" --> +<!-- thread="pci_arch_init" time="0.079" elapsed="0" result="0" --> +<!-- thread="topology_init" time="0.079" elapsed="0" result="0" --> +<!-- thread="mtrr_init_finialize" time="0.079" elapsed="0" result="0" --> +<!-- thread="init_vdso" time="0.079" elapsed="0" result="0" --> +<!-- thread="sysenter_setup" time="0.079" elapsed="0" result="0" --> +<!-- thread="param_sysfs_init" time="0.080" elapsed="976" result="0" --> +<!-- thread="pm_sysrq_init" time="0.080" elapsed="0" result="0" --> +<!-- thread="default_bdi_init" time="0.080" elapsed="0" result="0" --> +<!-- thread="mem_cgroup_init" time="0.080" elapsed="0" result="0" --> +<!-- thread="init_bio" time="0.080" elapsed="0" result="0" --> +<!-- thread="fsnotify_notification_init" time="0.080" elapsed="0" result="0" --> +<!-- thread="cryptomgr_init" time="0.080" elapsed="0" result="0" --> +<!-- thread="cryptd_init" time="0.080" elapsed="0" result="0" --> +<!-- thread="blk_settings_init" time="0.080" elapsed="0" result="0" --> +<!-- thread="blk_ioc_init" time="0.080" elapsed="0" result="0" --> +<!-- thread="blk_softirq_init" time="0.080" elapsed="0" result="0" --> +<!-- thread="blk_iopoll_setup" time="0.080" elapsed="0" result="0" --> +<!-- thread="genhd_device_init" time="0.080" elapsed="0" result="0" --> +<!-- thread="blk_dev_integrity_init" time="0.080" elapsed="0" result="0" --> +<!-- thread="pci_slot_init" time="0.080" elapsed="0" result="0" --> +<!-- thread="fbmem_init" time="0.080" elapsed="0" result="0" --> +<!-- thread="acpi_init" time="0.126" elapsed="43945" result="0" --> + <rect class="krnl" x="8.182" y="0.000" width="4.394" height="20.000" /> + <text x="13.182" y="15.000">acpi_init <tspan class="run">0.044s</tspan></text> +<!-- thread="dock_init" time="0.126" elapsed="976" result="0" --> +<!-- thread="acpi_pci_root_init" time="0.137" elapsed="9765" result="0" --> + <rect class="krnl" x="12.704" y="20.000" width="0.976" height="20.000" /> + <text x="17.704" y="35.000">acpi_pci_root_init <tspan class="run">0.010s</tspan></text> +<!-- thread="acpi_pci_link_init" time="0.137" elapsed="976" result="0" --> +<!-- thread="pnp_init" time="0.137" elapsed="0" result="0" --> +<!-- thread="xen_setup_shutdown_event" time="0.137" elapsed="0" result="-19" --> +<!-- thread="balloon_init" time="0.137" elapsed="0" result="-19" --> +<!-- thread="xenbus_probe_backend_init" time="0.137" elapsed="0" result="0" --> +<!-- thread="xenbus_probe_frontend_init" time="0.137" elapsed="0" result="0" --> +<!-- thread="xen_acpi_pad_init" time="0.137" elapsed="0" result="-19" --> +<!-- thread="balloon_init" time="0.137" elapsed="0" result="-19" --> +<!-- thread="xen_selfballoon_init" time="0.137" elapsed="0" result="-19" --> +<!-- thread="misc_init" time="0.137" elapsed="0" result="0" --> +<!-- thread="vga_arb_device_init" time="0.137" elapsed="0" result="0" --> +<!-- thread="cn_init" time="0.137" elapsed="0" result="0" --> +<!-- thread="init_scsi" time="0.137" elapsed="0" result="0" --> +<!-- thread="ata_init" time="0.137" elapsed="0" result="0" --> +<!-- thread="phy_init" time="0.137" elapsed="0" result="0" --> +<!-- thread="init_pcmcia_cs" time="0.137" elapsed="0" result="0" --> +<!-- thread="usb_init" time="0.137" elapsed="0" result="0" --> +<!-- thread="serio_init" time="0.137" elapsed="0" result="0" --> +<!-- thread="input_init" time="0.137" elapsed="0" result="0" --> +<!-- thread="rtc_init" time="0.137" elapsed="0" result="0" --> +<!-- thread="power_supply_class_init" time="0.137" elapsed="0" result="0" --> +<!-- thread="hwmon_init" time="0.137" elapsed="0" result="0" --> +<!-- thread="watchdog_init" time="0.137" elapsed="0" result="0" --> +<!-- thread="md_init" time="0.137" elapsed="0" result="0" --> +<!-- thread="leds_init" time="0.137" elapsed="0" result="0" --> +<!-- thread="iommu_init" time="0.137" elapsed="0" result="0" --> +<!-- thread="pci_subsys_init" time="0.139" elapsed="1953" result="0" --> + <rect class="krnl" x="13.736" y="40.000" width="0.195" height="20.000" /> + <text x="18.736" y="55.000">pci_subsys_init <tspan class="run">0.002s</tspan></text> +<!-- thread="proto_init" time="0.139" elapsed="0" result="0" --> +<!-- thread="net_dev_init" time="0.139" elapsed="0" result="0" --> +<!-- thread="neigh_init" time="0.139" elapsed="0" result="0" --> +<!-- thread="fib_rules_init" time="0.139" elapsed="0" result="0" --> +<!-- thread="pktsched_init" time="0.139" elapsed="0" result="0" --> +<!-- thread="tc_filter_init" time="0.139" elapsed="0" result="0" --> +<!-- thread="tc_action_init" time="0.139" elapsed="0" result="0" --> +<!-- thread="genl_init" time="0.139" elapsed="0" result="0" --> +<!-- thread="cipso_v4_init" time="0.139" elapsed="0" result="0" --> +<!-- thread="wireless_nlevent_init" time="0.139" elapsed="0" result="0" --> +<!-- thread="netlbl_init" time="0.139" elapsed="0" result="0" --> +<!-- thread="xen_p2m_debugfs" time="0.139" elapsed="0" result="0" --> +<!-- thread="hpet_late_init" time="0.141" elapsed="1953" result="0" --> + <rect class="krnl" x="13.952" y="60.000" width="0.195" height="20.000" /> + <text x="18.952" y="75.000">hpet_late_init <tspan class="run">0.002s</tspan></text> +<!-- thread="init_amd_nbs" time="0.141" elapsed="0" result="0" --> +<!-- thread="clocksource_done_booting" time="0.142" elapsed="3" result="0" --> +<!-- thread="ftrace_init_debugfs" time="0.142" elapsed="22" result="0" --> +<!-- thread="tracer_init_debugfs" time="0.142" elapsed="71" result="0" --> +<!-- thread="init_trace_printk_function_export" time="0.142" elapsed="1" result="0" --> +<!-- thread="event_trace_init" time="0.146" elapsed="3919" result="0" --> + <rect class="krnl" x="14.172" y="80.000" width="0.392" height="20.000" /> + <text x="19.172" y="95.000">event_trace_init <tspan class="run">0.004s</tspan></text> +<!-- thread="init_kprobe_trace" time="0.146" elapsed="3" result="0" --> +<!-- thread="init_uprobe_trace" time="0.146" elapsed="2" result="0" --> +<!-- thread="init_pipe_fs" time="0.146" elapsed="17" result="0" --> +<!-- thread="eventpoll_init" time="0.146" elapsed="7" result="0" --> +<!-- thread="anon_inode_init" time="0.146" elapsed="10" result="0" --> +<!-- thread="blk_scsi_ioctl_init" time="0.146" elapsed="1" result="0" --> +<!-- thread="dynamic_debug_init_debugfs" time="0.146" elapsed="3" result="0" --> +<!-- thread="acpi_event_init" time="0.146" elapsed="7" result="0" --> +<!-- thread="pnp_system_init" time="0.146" elapsed="10" result="0" --> +<!-- thread="pnpacpi_init" time="0.147" elapsed="1000" result="0" --> + <rect class="krnl" x="14.578" y="100.000" width="0.100" height="20.000" /> + <text x="19.578" y="115.000">pnpacpi_init <tspan class="run">0.001s</tspan></text> +<!-- thread="chr_dev_init" time="0.148" elapsed="1603" result="0" --> + <rect class="krnl" x="14.682" y="120.000" width="0.160" height="20.000" /> + <text x="19.682" y="135.000">chr_dev_init <tspan class="run">0.002s</tspan></text> +<!-- thread="firmware_class_init" time="0.148" elapsed="5" result="0" --> +<!-- thread="init_pcmcia_bus" time="0.148" elapsed="6" result="0" --> +<!-- thread="thermal_init" time="0.148" elapsed="6" result="0" --> +<!-- thread="thermal_gov_fair_share_init" time="0.148" elapsed="1" result="0" --> +<!-- thread="thermal_gov_step_wise_init" time="0.148" elapsed="0" result="0" --> +<!-- thread="cpufreq_gov_performance_init" time="0.148" elapsed="1" result="0" --> +<!-- thread="cpufreq_gov_dbs_init" time="0.148" elapsed="1" result="0" --> +<!-- thread="init_acpi_pm_clocksource" time="0.153" elapsed="4418" result="0" --> + <rect class="krnl" x="14.860" y="140.000" width="0.442" height="20.000" /> + <text x="19.860" y="155.000">init_acpi_pm_clocksource <tspan class="run">0.004s</tspan></text> +<!-- thread="pcibios_assign_resources" time="0.153" elapsed="151" result="0" --> +<!-- thread="sysctl_core_init" time="0.153" elapsed="9" result="0" --> +<!-- thread="inet_init" time="0.154" elapsed="506" result="0" --> +<!-- thread="ipv4_offload_init" time="0.154" elapsed="1" result="0" --> +<!-- thread="af_unix_init" time="0.154" elapsed="5" result="0" --> +<!-- thread="ipv6_offload_init" time="0.154" elapsed="1" result="0" --> +<!-- thread="pci_apply_final_quirks" time="0.154" elapsed="599" result="0" --> +<!-- thread="populate_rootfs" time="0.154" elapsed="32" result="0" --> +<!-- thread="pci_iommu_init" time="0.154" elapsed="6" result="0" --> +<!-- thread="ir_dev_scope_init" time="0.154" elapsed="0" result="1" --> +<!-- thread="i8259A_init_ops" time="0.154" elapsed="1" result="0" --> +<!-- thread="vsyscall_init" time="0.154" elapsed="6" result="0" --> +<!-- thread="sbf_init" time="0.154" elapsed="1" result="0" --> +<!-- thread="init_tsc_clocksource" time="0.154" elapsed="6" result="0" --> +<!-- thread="add_rtc_cmos" time="0.154" elapsed="2" result="0" --> +<!-- thread="i8237A_init_ops" time="0.154" elapsed="8" result="0" --> +<!-- thread="cache_sysfs_init" time="0.155" elapsed="75" result="0" --> +<!-- thread="intel_uncore_init" time="0.155" elapsed="23" result="0" --> +<!-- thread="thermal_throttle_init_device" time="0.155" elapsed="9" result="0" --> +<!-- thread="amd_ibs_init" time="0.155" elapsed="1" result="-19" --> +<!-- thread="msr_init" time="0.155" elapsed="108" result="0" --> +<!-- thread="cpuid_init" time="0.155" elapsed="72" result="0" --> +<!-- thread="ioapic_init_ops" time="0.155" elapsed="1" result="0" --> +<!-- thread="add_pcspkr" time="0.155" elapsed="11" result="0" --> +<!-- thread="start_periodic_check_for_corruption" time="0.155" elapsed="0" result="0" --> +<!-- thread="audit_classes_init" time="0.155" elapsed="4" result="0" --> +<!-- thread="aes_init" time="0.155" elapsed="53" result="0" --> +<!-- thread="aesni_init" time="0.156" elapsed="585" result="0" --> +<!-- thread="ia32_binfmt_init" time="0.156" elapsed="3" result="0" --> +<!-- thread="proc_execdomains_init" time="0.156" elapsed="3" result="0" --> +<!-- thread="ioresources_init" time="0.156" elapsed="4" result="0" --> +<!-- thread="uid_cache_init" time="0.156" elapsed="3" result="0" --> +<!-- thread="init_posix_timers" time="0.156" elapsed="6" result="0" --> +<!-- thread="init_posix_cpu_timers" time="0.156" elapsed="1" result="0" --> +<!-- thread="proc_schedstat_init" time="0.156" elapsed="2" result="0" --> +<!-- thread="init_sched_debug_procfs" time="0.156" elapsed="1" result="0" --> +<!-- thread="snapshot_device_init" time="0.156" elapsed="24" result="0" --> +<!-- thread="create_proc_profile" time="0.156" elapsed="0" result="0" --> +<!-- thread="timekeeping_init_ops" time="0.156" elapsed="0" result="0" --> +<!-- thread="init_clocksource_sysfs" time="0.156" elapsed="19" result="0" --> +<!-- thread="init_timer_list_procfs" time="0.156" elapsed="2" result="0" --> +<!-- thread="alarmtimer_init" time="0.156" elapsed="16" result="0" --> +<!-- thread="init_tstats_procfs" time="0.156" elapsed="2" result="0" --> +<!-- thread="futex_init" time="0.156" elapsed="4" result="0" --> +<!-- thread="proc_dma_init" time="0.156" elapsed="1" result="0" --> +<!-- thread="proc_modules_init" time="0.156" elapsed="1" result="0" --> +<!-- thread="module_verify_init" time="0.156" elapsed="9" result="0" --> +<!-- thread="kallsyms_init" time="0.156" elapsed="1" result="0" --> +<!-- thread="crash_save_vmcoreinfo_init" time="0.156" elapsed="14" result="0" --> +<!-- thread="crash_notes_memory_init" time="0.156" elapsed="2" result="0" --> +<!-- thread="pid_namespaces_init" time="0.156" elapsed="5" result="0" --> +<!-- thread="audit_init" time="0.156" elapsed="9" result="0" --> +<!-- thread="audit_watch_init" time="0.156" elapsed="1" result="0" --> +<!-- thread="audit_tree_init" time="0.156" elapsed="1" result="0" --> +<!-- thread="init_kprobes" time="0.177" elapsed="20843" result="0" --> + <rect class="krnl" x="15.632" y="160.000" width="2.084" height="20.000" /> + <text x="20.632" y="175.000">init_kprobes <tspan class="run">0.021s</tspan></text> +<!-- thread="irq_pm_init_ops" time="0.177" elapsed="0" result="0" --> +<!-- thread="utsname_sysctl_init" time="0.177" elapsed="7" result="0" --> +<!-- thread="init_tracepoints" time="0.177" elapsed="0" result="0" --> +<!-- thread="init_lstats_procfs" time="0.177" elapsed="2" result="0" --> +<!-- thread="stack_trace_init" time="0.177" elapsed="13" result="0" --> +<!-- thread="init_blk_tracer" time="0.177" elapsed="2" result="0" --> +<!-- thread="perf_event_sysfs_init" time="0.177" elapsed="59" result="0" --> +<!-- thread="init_uprobes" time="0.177" elapsed="3" result="0" --> +<!-- thread="init_per_zone_wmark_min" time="0.177" elapsed="122" result="0" --> +<!-- thread="kswapd_init" time="0.177" elapsed="29" result="0" --> +<!-- thread="extfrag_debug_init" time="0.177" elapsed="4" result="0" --> +<!-- thread="setup_vmstat" time="0.177" elapsed="7" result="0" --> +<!-- thread="mm_sysfs_init" time="0.178" elapsed="2" result="0" --> +<!-- thread="slab_proc_init" time="0.178" elapsed="2" result="0" --> +<!-- thread="proc_vmalloc_init" time="0.178" elapsed="1" result="0" --> +<!-- thread="procswaps_init" time="0.178" elapsed="1" result="0" --> +<!-- thread="init_frontswap" time="0.178" elapsed="7" result="0" --> +<!-- thread="hugetlb_init" time="0.178" elapsed="12" result="0" --> +<!-- thread="mmu_notifier_init" time="0.178" elapsed="3" result="0" --> +<!-- thread="ksm_init" time="0.178" elapsed="27" result="0" --> +<!-- thread="slab_sysfs_init" time="0.178" elapsed="695" result="0" --> +<!-- thread="hugepage_init" time="0.178" elapsed="135" result="0" --> +<!-- thread="init_cleancache" time="0.178" elapsed="5" result="0" --> +<!-- thread="fcntl_init" time="0.178" elapsed="3" result="0" --> +<!-- thread="proc_filesystems_init" time="0.178" elapsed="14" result="0" --> +<!-- thread="dio_init" time="0.179" elapsed="26" result="0" --> +<!-- thread="fsnotify_mark_init" time="0.179" elapsed="19" result="0" --> +<!-- thread="dnotify_init" time="0.179" elapsed="4" result="0" --> +<!-- thread="inotify_user_setup" time="0.179" elapsed="6" result="0" --> +<!-- thread="fanotify_user_setup" time="0.179" elapsed="4" result="0" --> +<!-- thread="aio_setup" time="0.179" elapsed="7" result="0" --> +<!-- thread="proc_locks_init" time="0.179" elapsed="2" result="0" --> +<!-- thread="init_sys32_ioctl" time="0.179" elapsed="72" result="0" --> +<!-- thread="init_mbcache" time="0.179" elapsed="0" result="0" --> +<!-- thread="dquot_init" time="0.179" elapsed="31" result="0" --> +<!-- thread="init_v2_quota_format" time="0.179" elapsed="0" result="0" --> +<!-- thread="quota_init" time="0.179" elapsed="4" result="0" --> +<!-- thread="proc_cmdline_init" time="0.179" elapsed="2" result="0" --> +<!-- thread="proc_consoles_init" time="0.179" elapsed="1" result="0" --> +<!-- thread="proc_cpuinfo_init" time="0.179" elapsed="1" result="0" --> +<!-- thread="proc_devices_init" time="0.179" elapsed="1" result="0" --> +<!-- thread="proc_interrupts_init" time="0.179" elapsed="1" result="0" --> +<!-- thread="proc_loadavg_init" time="0.179" elapsed="1" result="0" --> +<!-- thread="proc_meminfo_init" time="0.179" elapsed="1" result="0" --> +<!-- thread="proc_stat_init" time="0.179" elapsed="1" result="0" --> +<!-- thread="proc_uptime_init" time="0.179" elapsed="1" result="0" --> +<!-- thread="proc_version_init" time="0.179" elapsed="3" result="0" --> +<!-- thread="proc_softirqs_init" time="0.179" elapsed="1" result="0" --> +<!-- thread="proc_kcore_init" time="0.179" elapsed="7" result="0" --> +<!-- thread="vmcore_init" time="0.179" elapsed="1" result="0" --> +<!-- thread="proc_kmsg_init" time="0.179" elapsed="1" result="0" --> +<!-- thread="proc_page_init" time="0.179" elapsed="2" result="0" --> +<!-- thread="configfs_init" time="0.179" elapsed="23" result="0" --> +<!-- thread="init_devpts_fs" time="0.179" elapsed="18" result="0" --> +<!-- thread="ext4_init_fs" time="0.179" elapsed="111" result="0" --> +<!-- thread="journal_init" time="0.179" elapsed="36" result="0" --> +<!-- thread="init_ramfs_fs" time="0.179" elapsed="1" result="0" --> +<!-- thread="init_hugetlbfs_fs" time="0.179" elapsed="39" result="0" --> +<!-- thread="init_iso9660_fs" time="0.179" elapsed="22" result="0" --> +<!-- thread="init_nls_cp437" time="0.179" elapsed="0" result="0" --> +<!-- thread="init_nls_ascii" time="0.179" elapsed="0" result="0" --> +<!-- thread="init_autofs4_fs" time="0.179" elapsed="30" result="0" --> +<!-- thread="init_pstore_fs" time="0.179" elapsed="1" result="0" --> +<!-- thread="ipc_init" time="0.179" elapsed="5" result="0" --> +<!-- thread="ipc_sysctl_init" time="0.179" elapsed="5" result="0" --> +<!-- thread="init_mqueue_fs" time="0.179" elapsed="37" result="0" --> +<!-- thread="key_proc_init" time="0.179" elapsed="2" result="0" --> +<!-- thread="selinux_nf_ip_init" time="0.179" elapsed="111" result="0" --> +<!-- thread="init_sel_fs" time="0.179" elapsed="45" result="0" --> +<!-- thread="selnl_init" time="0.179" elapsed="4" result="0" --> +<!-- thread="sel_netif_init" time="0.179" elapsed="3" result="0" --> +<!-- thread="sel_netnode_init" time="0.179" elapsed="2" result="0" --> +<!-- thread="sel_netport_init" time="0.180" elapsed="2" result="0" --> +<!-- thread="aurule_init" time="0.180" elapsed="0" result="0" --> +<!-- thread="crypto_wq_init" time="0.180" elapsed="24" result="0" --> +<!-- thread="crypto_algapi_init" time="0.180" elapsed="4" result="0" --> +<!-- thread="skcipher_module_init" time="0.180" elapsed="0" result="0" --> +<!-- thread="chainiv_module_init" time="0.180" elapsed="1" result="0" --> +<!-- thread="eseqiv_module_init" time="0.180" elapsed="0" result="0" --> +<!-- thread="seqiv_module_init" time="0.180" elapsed="0" result="0" --> +<!-- thread="hmac_module_init" time="0.180" elapsed="1" result="0" --> +<!-- thread="md5_mod_init" time="0.180" elapsed="42" result="0" --> +<!-- thread="sha1_generic_mod_init" time="0.180" elapsed="38" result="0" --> +<!-- thread="sha256_generic_mod_init" time="0.180" elapsed="73" result="0" --> +<!-- thread="crypto_ecb_module_init" time="0.180" elapsed="1" result="0" --> +<!-- thread="crypto_cbc_module_init" time="0.180" elapsed="0" result="0" --> +<!-- thread="crypto_module_init" time="0.180" elapsed="0" result="0" --> +<!-- thread="crypto_module_init" time="0.180" elapsed="0" result="0" --> +<!-- thread="crypto_ctr_module_init" time="0.180" elapsed="1" result="0" --> +<!-- thread="aes_init" time="0.180" elapsed="41" result="0" --> +<!-- thread="crc32c_mod_init" time="0.180" elapsed="43" result="0" --> +<!-- thread="krng_mod_init" time="0.180" elapsed="29" result="0" --> +<!-- thread="af_alg_init" time="0.180" elapsed="2" result="0" --> +<!-- thread="algif_hash_init" time="0.180" elapsed="0" result="0" --> +<!-- thread="algif_skcipher_init" time="0.180" elapsed="0" result="0" --> +<!-- thread="asymmetric_key_init" time="0.180" elapsed="2" result="0" --> +<!-- thread="x509_key_init" time="0.180" elapsed="2" result="0" --> +<!-- thread="proc_genhd_init" time="0.180" elapsed="3" result="0" --> +<!-- thread="bsg_init" time="0.180" elapsed="24" result="0" --> +<!-- thread="throtl_init" time="0.180" elapsed="22" result="0" --> +<!-- thread="noop_init" time="0.180" elapsed="2" result="0" --> +<!-- thread="deadline_init" time="0.180" elapsed="2" result="0" --> +<!-- thread="cfq_init" time="0.180" elapsed="6" result="0" --> +<!-- thread="test_kstrtox_init" time="0.180" elapsed="24" result="-22" --> +<!-- thread="btree_module_init" time="0.180" elapsed="4" result="0" --> +<!-- thread="percpu_counter_startup" time="0.180" elapsed="1" result="0" --> +<!-- thread="pci_proc_init" time="0.180" elapsed="20" result="0" --> +<!-- thread="pcie_portdrv_init" time="0.180" elapsed="162" result="0" --> +<!-- thread="aer_service_init" time="0.180" elapsed="4" result="0" --> +<!-- thread="pcie_pme_service_init" time="0.180" elapsed="3" result="0" --> +<!-- thread="ioapic_init" time="0.180" elapsed="5" result="0" --> +<!-- thread="pci_hotplug_init" time="0.180" elapsed="2" result="0" --> +<!-- thread="pcied_init" time="0.180" elapsed="13" result="0" --> +<!-- thread="acpiphp_init" time="0.180" elapsed="166" result="0" --> +<!-- thread="pci_stub_init" time="0.181" elapsed="8" result="0" --> +<!-- thread="fb_console_init" time="0.181" elapsed="11" result="0" --> +<!-- thread="xenfb_init" time="0.181" elapsed="1" result="-19" --> +<!-- thread="vesafb_init" time="0.181" elapsed="28" result="-19" --> +<!-- thread="efifb_init" time="0.181" elapsed="835" result="0" --> +<!-- thread="intel_idle_init" time="0.181" elapsed="14" result="0" --> +<!-- thread="acpi_reserve_resources" time="0.181" elapsed="2" result="0" --> +<!-- thread="irqrouter_init_ops" time="0.181" elapsed="1" result="0" --> +<!-- thread="acpi_ac_init" time="0.182" elapsed="643" result="0" --> +<!-- thread="acpi_button_driver_init" time="0.183" elapsed="514" result="0" --> +<!-- thread="acpi_fan_driver_init" time="0.183" elapsed="8" result="0" --> +<!-- thread="acpi_pci_slot_init" time="0.183" elapsed="46" result="0" --> +<!-- thread="acpi_processor_init" time="0.185" elapsed="1786" result="0" --> + <rect class="krnl" x="18.277" y="180.000" width="0.179" height="20.000" /> + <text x="23.277" y="195.000">acpi_processor_init <tspan class="run">0.002s</tspan></text> +<!-- thread="acpi_container_init" time="0.186" elapsed="1027" result="0" --> + <rect class="krnl" x="18.459" y="200.000" width="0.103" height="20.000" /> + <text x="23.459" y="215.000">acpi_container_init <tspan class="run">0.001s</tspan></text> +<!-- thread="acpi_thermal_init" time="0.187" elapsed="1249" result="0" --> + <rect class="krnl" x="18.566" y="220.000" width="0.125" height="20.000" /> + <text x="23.566" y="235.000">acpi_thermal_init <tspan class="run">0.001s</tspan></text> +<!-- thread="acpi_battery_init" time="0.187" elapsed="3" result="0" --> +<!-- thread="acpi_hed_driver_init" time="0.187" elapsed="16" result="0" --> +<!-- thread="bgrt_init" time="0.187" elapsed="0" result="-19" --> +<!-- thread="erst_init" time="0.187" elapsed="2" result="0" --> +<!-- thread="ghes_init" time="0.187" elapsed="1" result="-22" --> +<!-- thread="virtio_pci_driver_init" time="0.187" elapsed="25" result="0" --> +<!-- thread="xenbus_probe_initcall" time="0.187" elapsed="0" result="-19" --> +<!-- thread="xenbus_init" time="0.187" elapsed="0" result="-19" --> +<!-- thread="xenbus_backend_init" time="0.187" elapsed="0" result="-19" --> +<!-- thread="hypervisor_subsys_init" time="0.187" elapsed="0" result="-19" --> +<!-- thread="hyper_sysfs_init" time="0.187" elapsed="0" result="-19" --> +<!-- thread="platform_pci_module_init" time="0.187" elapsed="6" result="0" --> +<!-- thread="xen_tmem_init" time="0.187" elapsed="0" result="0" --> +<!-- thread="pty_init" time="0.187" elapsed="69" result="0" --> +<!-- thread="sysrq_init" time="0.187" elapsed="3" result="0" --> +<!-- thread="xen_hvc_init" time="0.187" elapsed="0" result="-19" --> +<!-- thread="serial8250_init" time="0.187" elapsed="297" result="0" --> +<!-- thread="serial_pci_driver_init" time="0.208" elapsed="19990" result="0" --> + <rect class="krnl" x="18.794" y="240.000" width="1.999" height="20.000" /> + <text x="23.794" y="255.000">serial_pci_driver_init <tspan class="run">0.020s</tspan></text> +<!-- thread="init_kgdboc" time="0.208" elapsed="1" result="0" --> +<!-- thread="rand_initialize" time="0.208" elapsed="35" result="0" --> +<!-- thread="init" time="0.208" elapsed="27" result="0" --> +<!-- thread="raw_init" time="0.208" elapsed="100" result="0" --> +<!-- thread="hpet_init" time="0.208" elapsed="103" result="0" --> +<!-- thread="nvram_init" time="0.208" elapsed="26" result="0" --> +<!-- thread="agp_init" time="0.208" elapsed="2" result="0" --> +<!-- thread="agp_amd64_mod_init" time="0.208" elapsed="15" result="-19" --> +<!-- thread="agp_intel_init" time="0.208" elapsed="8" result="0" --> +<!-- thread="agp_sis_init" time="0.208" elapsed="6" result="0" --> +<!-- thread="agp_via_init" time="0.208" elapsed="6" result="0" --> +<!-- thread="cn_proc_init" time="0.208" elapsed="25" result="0" --> +<!-- thread="topology_sysfs_init" time="0.208" elapsed="10" result="0" --> +<!-- thread="loop_init" time="0.209" elapsed="727" result="0" --> +<!-- thread="init_kgdbts" time="0.209" elapsed="0" result="0" --> +<!-- thread="mac_hid_init" time="0.209" elapsed="27" result="0" --> +<!-- thread="scsi_dh_init" time="0.209" elapsed="0" result="0" --> +<!-- thread="init_sd" time="0.209" elapsed="28" result="0" --> +<!-- thread="init_sr" time="0.209" elapsed="3" result="0" --> +<!-- thread="init_sg" time="0.209" elapsed="9" result="0" --> +<!-- thread="1_acpi_battery_init_async" time="0.218" elapsed="30408" result="0" --> + <rect class="krnl" x="18.764" y="260.000" width="3.041" height="20.000" /> + <text x="23.764" y="275.000">1_acpi_battery_init_async <tspan class="run">0.030s</tspan></text> +<!-- thread="ahci_pci_driver_init" time="0.224" elapsed="14541" result="0" --> + <rect class="krnl" x="20.963" y="280.000" width="1.454" height="20.000" /> + <text x="25.963" y="295.000">ahci_pci_driver_init <tspan class="run">0.015s</tspan></text> +<!-- thread="piix_init" time="0.224" elapsed="18" result="0" --> +<!-- thread="net_olddevs_init" time="0.224" elapsed="3" result="0" --> +<!-- thread="fixed_mdio_bus_init" time="0.224" elapsed="28" result="0" --> +<!-- thread="cdrom_init" time="0.224" elapsed="6" result="0" --> +<!-- thread="nonstatic_sysfs_init" time="0.224" elapsed="2" result="0" --> +<!-- thread="mon_init" time="0.224" elapsed="56" result="0" --> +<!-- thread="ehci_hcd_init" time="0.224" elapsed="2" result="0" --> +<!-- thread="ehci_pci_init" time="0.244" elapsed="18952" result="0" --> + <rect class="krnl" x="22.479" y="300.000" width="1.895" height="20.000" /> + <text x="27.479" y="315.000">ehci_pci_init <tspan class="run">0.019s</tspan></text> +<!-- thread="ohci_hcd_mod_init" time="0.244" elapsed="7" result="0" --> +<!-- thread="uhci_hcd_init" time="0.244" elapsed="12" result="0" --> +<!-- thread="xhci_hcd_init" time="0.255" elapsed="10478" result="0" --> + <rect class="krnl" x="24.403" y="320.000" width="1.048" height="20.000" /> + <text x="29.403" y="335.000">xhci_hcd_init <tspan class="run">0.010s</tspan></text> +<!-- thread="usb_serial_init" time="0.255" elapsed="80" result="0" --> +<!-- thread="kgdbdbgp_start_thread" time="0.255" elapsed="0" result="0" --> +<!-- thread="i8042_init" time="0.258" elapsed="3233" result="0" --> + <rect class="krnl" x="25.469" y="340.000" width="0.323" height="20.000" /> + <text x="30.469" y="355.000">i8042_init <tspan class="run">0.003s</tspan></text> +<!-- thread="serport_init" time="0.258" elapsed="0" result="0" --> +<!-- thread="mousedev_init" time="0.258" elapsed="35" result="0" --> +<!-- thread="evdev_init" time="0.258" elapsed="71" result="0" --> +<!-- thread="atkbd_init" time="0.258" elapsed="7" result="0" --> +<!-- thread="psmouse_init" time="0.258" elapsed="46" result="0" --> +<!-- thread="xenkbd_init" time="0.258" elapsed="0" result="-19" --> +<!-- thread="cmos_init" time="0.258" elapsed="171" result="0" --> +<!-- thread="dm_init" time="0.258" elapsed="115" result="0" --> +<!-- thread="dm_snapshot_init" time="0.258" elapsed="24" result="0" --> +<!-- thread="dm_mirror_init" time="0.258" elapsed="1" result="0" --> +<!-- thread="dm_dirty_log_init" time="0.258" elapsed="1" result="0" --> +<!-- thread="dm_zero_init" time="0.258" elapsed="0" result="0" --> +<!-- thread="cpufreq_gov_powersave_init" time="0.258" elapsed="0" result="0" --> +<!-- thread="cpufreq_gov_userspace_init" time="0.258" elapsed="0" result="0" --> +<!-- thread="cpufreq_gov_dbs_init" time="0.259" elapsed="0" result="0" --> +<!-- thread="init_ladder" time="0.259" elapsed="49" result="0" --> +<!-- thread="init_menu" time="0.259" elapsed="75" result="0" --> +<!-- thread="dmi_sysfs_init" time="0.259" elapsed="320" result="0" --> +<!-- thread="efivars_init" time="0.282" elapsed="22841" result="0" --> + <rect class="krnl" x="25.952" y="360.000" width="2.284" height="20.000" /> + <text x="30.952" y="375.000">efivars_init <tspan class="run">0.023s</tspan></text> +<!-- thread="hid_init" time="0.282" elapsed="17" result="0" --> +<!-- thread="hid_init" time="0.282" elapsed="5" result="0" --> +<!-- thread="a4_init" time="0.282" elapsed="4" result="0" --> +<!-- thread="apple_init" time="0.282" elapsed="6" result="0" --> +<!-- thread="belkin_init" time="0.282" elapsed="5" result="0" --> +<!-- thread="ch_init" time="0.282" elapsed="4" result="0" --> +<!-- thread="ch_init" time="0.282" elapsed="4" result="0" --> +<!-- thread="cp_init" time="0.282" elapsed="5" result="0" --> +<!-- thread="ez_init" time="0.282" elapsed="4" result="0" --> +<!-- thread="ks_init" time="0.282" elapsed="4" result="0" --> +<!-- thread="lg_init" time="0.282" elapsed="4" result="0" --> +<!-- thread="ms_init" time="0.283" elapsed="5" result="0" --> +<!-- thread="mr_init" time="0.283" elapsed="4" result="0" --> +<!-- thread="ntrig_init" time="0.283" elapsed="5" result="0" --> +<!-- thread="hid_init" time="0.283" elapsed="9" result="0" --> +<!-- thread="staging_init" time="0.283" elapsed="0" result="0" --> +<!-- thread="sock_diag_init" time="0.283" elapsed="9" result="0" --> +<!-- thread="flow_cache_init_global" time="0.283" elapsed="16" result="0" --> +<!-- thread="init_net_drop_monitor" time="0.283" elapsed="13" result="0" --> +<!-- thread="blackhole_module_init" time="0.283" elapsed="1" result="0" --> +<!-- thread="init_cgroup_cls" time="0.283" elapsed="0" result="0" --> +<!-- thread="xt_init" time="0.283" elapsed="2" result="0" --> +<!-- thread="tcpudp_mt_init" time="0.283" elapsed="1" result="0" --> +<!-- thread="sysctl_ipv4_init" time="0.283" elapsed="31" result="0" --> +<!-- thread="init_syncookies" time="0.283" elapsed="13" result="0" --> +<!-- thread="ipv4_netfilter_init" time="0.283" elapsed="0" result="0" --> +<!-- thread="ip_tables_init" time="0.283" elapsed="7" result="0" --> +<!-- thread="iptable_filter_init" time="0.283" elapsed="28" result="0" --> +<!-- thread="reject_tg_init" time="0.283" elapsed="2" result="0" --> +<!-- thread="cubictcp_register" time="0.283" elapsed="2" result="0" --> +<!-- thread="tcp_memcontrol_init" time="0.283" elapsed="1" result="0" --> +<!-- thread="xfrm_user_init" time="0.283" elapsed="4" result="0" --> +<!-- thread="inet6_init" time="0.283" elapsed="195" result="0" --> +<!-- thread="mip6_init" time="0.283" elapsed="2" result="0" --> +<!-- thread="packet_init" time="0.283" elapsed="4" result="0" --> +<!-- thread="dcbnl_init" time="0.283" elapsed="0" result="0" --> +<!-- thread="mcheck_init_device" time="0.283" elapsed="99" result="0" --> +<!-- thread="tboot_late_init" time="0.283" elapsed="1" result="0" --> +<!-- thread="mcheck_debugfs_init" time="0.283" elapsed="4" result="0" --> +<!-- thread="severities_debugfs_init" time="0.283" elapsed="2" result="0" --> +<!-- thread="threshold_init_device" time="0.283" elapsed="1" result="0" --> +<!-- thread="hpet_insert_resource" time="0.283" elapsed="2" result="0" --> +<!-- thread="update_mp_table" time="0.283" elapsed="1" result="0" --> +<!-- thread="lapic_insert_resource" time="0.283" elapsed="1" result="0" --> +<!-- thread="io_apic_bug_finalize" time="0.283" elapsed="1" result="0" --> +<!-- thread="print_ICs" time="0.283" elapsed="0" result="0" --> +<!-- thread="check_early_ioremap_leak" time="0.283" elapsed="1" result="0" --> +<!-- thread="pat_memtype_list_init" time="0.283" elapsed="2" result="0" --> +<!-- thread="init_oops_id" time="0.283" elapsed="2" result="0" --> +<!-- thread="printk_late_init" time="0.283" elapsed="2" result="0" --> +<!-- thread="sched_init_debug" time="0.283" elapsed="2" result="0" --> +<!-- thread="pm_qos_power_init" time="0.283" elapsed="74" result="0" --> +<!-- thread="pm_debugfs_init" time="0.283" elapsed="2" result="0" --> +<!-- thread="software_resume" time="0.283" elapsed="3" result="-2" --> +<!-- thread="load_module_signing_keys" time="0.284" elapsed="818" result="0" --> +<!-- thread="load_uefi_certs" time="0.284" elapsed="1" result="0" --> +<!-- thread="debugfs_kprobe_init" time="0.284" elapsed="5" result="0" --> +<!-- thread="taskstats_init" time="0.284" elapsed="4" result="0" --> +<!-- thread="clear_boot_tracer" time="0.284" elapsed="0" result="0" --> +<!-- thread="kdb_ftrace_register" time="0.284" elapsed="2" result="0" --> +<!-- thread="max_swapfiles_check" time="0.284" elapsed="0" result="0" --> +<!-- thread="set_recommended_min_free_kbytes" time="0.284" elapsed="123" result="0" --> +<!-- thread="prandom_reseed" time="0.284" elapsed="16" result="0" --> +<!-- thread="pci_resource_alignment_sysfs_init" time="0.284" elapsed="2" result="0" --> +<!-- thread="pci_sysfs_init" time="0.285" elapsed="250" result="0" --> +<!-- thread="boot_wait_for_devices" time="0.285" elapsed="1" result="0" --> +<!-- thread="random_int_secret_init" time="0.285" elapsed="7" result="0" --> +<!-- thread="deferred_probe_initcall" time="0.285" elapsed="178" result="0" --> +<!-- thread="late_resume_init" time="0.285" elapsed="66" result="0" --> +<!-- thread="rtc_hctosys" time="0.285" elapsed="62" result="0" --> +<!-- thread="powernowk8_init" time="0.285" elapsed="0" result="-19" --> +<!-- thread="acpi_cpufreq_init" time="0.291" elapsed="5483" result="0" --> + <rect class="krnl" x="28.514" y="380.000" width="0.548" height="20.000" /> + <text x="33.514" y="395.000">acpi_cpufreq_init <tspan class="run">0.005s</tspan></text> +<!-- thread="pcc_cpufreq_init" time="0.291" elapsed="3" result="-19" --> +<!-- thread="cpufreq_p4_init" time="0.291" elapsed="0" result="-16" --> +<!-- thread="firmware_memmap_init" time="0.291" elapsed="24" result="0" --> +<!-- thread="pci_mmcfg_late_insert_resources" time="0.291" elapsed="2" result="0" --> +<!-- thread="net_secret_init" time="0.291" elapsed="7" result="0" --> +<!-- thread="tcp_congestion_default" time="0.291" elapsed="1" result="0" --> +<!-- thread="tcp_fastopen_init" time="0.291" elapsed="5" result="0" --> +<!-- thread="initialize_hashrnd" time="0.291" elapsed="2" result="0" --> +<!-- thread="2_async_port_probe" time="0.534" elapsed="302727" result="0" --> + <rect class="krnl" x="23.134" y="400.000" width="30.273" height="20.000" /> + <text x="28.134" y="415.000">2_async_port_probe <tspan class="run">0.303s</tspan></text> +<!-- thread="8_sd_probe_async" time="0.539" elapsed="5161" result="0" --> + <rect class="krnl" x="53.357" y="420.000" width="0.516" height="20.000" /> + <text x="58.357" y="435.000">8_sd_probe_async <tspan class="run">0.005s</tspan></text> +<!-- thread="3_async_port_probe" time="0.549" elapsed="317251" result="0" --> + <rect class="krnl" x="23.172" y="440.000" width="31.725" height="20.000" /> + <text x="28.172" y="455.000">3_async_port_probe <tspan class="run">0.317s</tspan></text> +<!-- thread="4_async_port_probe" time="0.549" elapsed="317273" result="0" --> + <rect class="krnl" x="23.174" y="460.000" width="31.727" height="20.000" /> + <text x="28.174" y="475.000">4_async_port_probe <tspan class="run">0.317s</tspan></text> +<!-- thread="5_async_port_probe" time="0.549" elapsed="317270" result="0" --> + <rect class="krnl" x="23.178" y="480.000" width="31.727" height="20.000" /> + <text x="28.178" y="495.000">5_async_port_probe <tspan class="run">0.317s</tspan></text> +<!-- thread="6_async_port_probe" time="0.549" elapsed="317286" result="0" --> + <rect class="krnl" x="23.181" y="500.000" width="31.729" height="20.000" /> + <text x="28.181" y="515.000">6_async_port_probe <tspan class="run">0.317s</tspan></text> +<!-- thread="7_async_port_probe" time="0.549" elapsed="317302" result="0" --> + <rect class="krnl" x="23.184" y="520.000" width="31.730" height="20.000" /> + <text x="28.184" y="535.000">7_async_port_probe <tspan class="run">0.317s</tspan></text> +<!-- thread="i2c_init" time="1.358" elapsed="26" result="0" --> +<!-- thread="media_devnode_init" time="1.361" elapsed="28" result="0" --> +<!-- thread="videodev_init" time="1.367" elapsed="14" result="0" --> +<!-- thread="acpi_video_init" time="1.367" elapsed="8" result="0" --> +<!-- thread="acpi_wmi_init" time="1.382" elapsed="262" result="0" --> +<!-- thread="init_soundcore" time="1.389" elapsed="7" result="0" --> +<!-- thread="drm_core_init" time="1.389" elapsed="10" result="0" --> +<!-- thread="rfkill_init" time="1.389" elapsed="15433" result="0" --> + <rect class="krnl" x="137.394" y="540.000" width="1.543" height="20.000" /> + <text x="142.394" y="555.000">rfkill_init <tspan class="run">0.015s</tspan></text> +<!-- thread="uvc_init" time="1.394" elapsed="15032" result="0" --> + <rect class="krnl" x="137.878" y="560.000" width="1.503" height="20.000" /> + <text x="142.878" y="575.000">uvc_init <tspan class="run">0.015s</tspan></text> +<!-- thread="alsa_sound_init" time="1.395" elapsed="2058" result="0" --> + <rect class="krnl" x="139.309" y="580.000" width="0.206" height="20.000" /> + <text x="144.309" y="595.000">alsa_sound_init <tspan class="run">0.002s</tspan></text> +<!-- thread="alsa_timer_init" time="1.405" elapsed="456" result="0" --> +<!-- thread="velocity_init_module" time="1.407" elapsed="10505" result="0" --> + <rect class="krnl" x="139.666" y="600.000" width="1.050" height="20.000" /> + <text x="144.666" y="615.000">velocity_init_module <tspan class="run">0.011s</tspan></text> +<!-- thread="snd_mem_init" time="1.407" elapsed="4" result="0" --> +<!-- thread="mei_driver_init" time="1.413" elapsed="19762" result="0" --> + <rect class="krnl" x="139.308" y="620.000" width="1.976" height="20.000" /> + <text x="144.308" y="635.000">mei_driver_init <tspan class="run">0.020s</tspan></text> +<!-- thread="cfg80211_init" time="1.417" elapsed="96" result="0" --> +<!-- thread="iwl_drv_init" time="1.421" elapsed="629" result="0" --> +<!-- thread="thinkpad_acpi_module_init" time="1.422" elapsed="23232" result="0" --> + <rect class="krnl" x="139.891" y="640.000" width="2.323" height="20.000" /> + <text x="144.891" y="655.000">thinkpad_acpi_module_init <tspan class="run">0.023s</tspan></text> +<!-- thread="microcode_init" time="1.426" elapsed="3104" result="0" --> + <rect class="krnl" x="142.261" y="660.000" width="0.310" height="20.000" /> + <text x="147.261" y="675.000">microcode_init <tspan class="run">0.003s</tspan></text> +<!-- thread="ghash_pclmulqdqni_mod_init" time="1.435" elapsed="7202" result="0" --> + <rect class="krnl" x="142.765" y="680.000" width="0.720" height="20.000" /> + <text x="147.765" y="695.000">ghash_pclmulqdqni_mod_init <tspan class="run">0.007s</tspan></text> +<!-- thread="crc32c_intel_mod_init" time="1.440" elapsed="1288" result="0" --> + <rect class="krnl" x="143.833" y="700.000" width="0.129" height="20.000" /> + <text x="148.833" y="715.000">crc32c_intel_mod_init <tspan class="run">0.001s</tspan></text> +<!-- thread="alsa_pcm_init" time="1.446" elapsed="4" result="0" --> +<!-- thread="irqfd_module_init" time="1.459" elapsed="25" result="0" --> +<!-- thread="alsa_seq_device_init" time="1.461" elapsed="2" result="0" --> +<!-- thread="vmx_init" time="1.474" elapsed="259" result="0" --> +<!-- thread="alsa_seq_init" time="1.477" elapsed="146" result="0" --> +<!-- thread="coretemp_init" time="1.479" elapsed="81" result="0" --> +<!-- thread="alsa_hwdep_init" time="1.480" elapsed="3" result="0" --> +<!-- thread="ieee80211_init" time="1.486" elapsed="68" result="0" --> +<!-- thread="arc4_init" time="1.504" elapsed="509" result="0" --> +<!-- thread="iwl_init" time="1.505" elapsed="14492" result="0" --> + <rect class="krnl" x="149.075" y="720.000" width="1.449" height="20.000" /> + <text x="154.075" y="735.000">iwl_init <tspan class="run">0.014s</tspan></text> +<!-- thread="wdm_driver_init" time="1.572" elapsed="2875" result="0" --> + <rect class="krnl" x="156.902" y="740.000" width="0.287" height="20.000" /> + <text x="161.902" y="755.000">wdm_driver_init <tspan class="run">0.003s</tspan></text> +<!-- thread="usbnet_init" time="1.574" elapsed="12" result="0" --> +<!-- thread="acm_init" time="1.580" elapsed="12692" result="0" --> + <rect class="krnl" x="156.707" y="760.000" width="1.269" height="20.000" /> + <text x="161.707" y="775.000">acm_init <tspan class="run">0.013s</tspan></text> +<!-- thread="cdc_ncm_driver_init" time="1.600" elapsed="23053" result="0" --> + <rect class="krnl" x="157.713" y="780.000" width="2.305" height="20.000" /> + <text x="162.713" y="795.000">cdc_ncm_driver_init <tspan class="run">0.023s</tspan></text> +<!-- thread="cdc_mbim_driver_init" time="1.602" elapsed="21" result="0" --> +<!-- thread="e1000_init_module" time="1.615" elapsed="216550" result="0" --> + <rect class="krnl" x="139.886" y="800.000" width="21.655" height="20.000" /> + <text x="144.886" y="815.000">e1000_init_module <tspan class="run">0.217s</tspan></text> +<!-- thread="lpc_ich_init" time="1.615" elapsed="208130" result="0" --> + <rect class="krnl" x="140.736" y="820.000" width="20.813" height="20.000" /> + <text x="145.736" y="835.000">lpc_ich_init <tspan class="run">0.208s</tspan></text> +<!-- thread="i2c_i801_init" time="1.616" elapsed="193635" result="0" --> + <rect class="krnl" x="142.197" y="840.000" width="19.363" height="20.000" /> + <text x="147.197" y="855.000">i2c_i801_init <tspan class="run">0.194s</tspan></text> +<!-- thread="iTCO_vendor_init_module" time="1.619" elapsed="1" result="0" --> +<!-- thread="iTCO_wdt_init_module" time="1.622" elapsed="132" result="0" --> +<!-- thread="bt_init" time="2.083" elapsed="21" result="0" --> +<!-- thread="bnep_init" time="2.087" elapsed="7" result="0" --> +<!-- thread="i915_init" time="2.436" elapsed="987336" result="0" --> + <rect class="krnl" x="144.834" y="860.000" width="98.734" height="20.000" /> + <text x="149.834" y="875.000">i915_init <tspan class="run">0.987s</tspan></text> +<!-- thread="patch_conexant_init" time="2.448" elapsed="0" result="0" --> +<!-- thread="patch_hdmi_init" time="2.451" elapsed="0" result="0" --> +<!-- thread="azx_driver_init" time="2.464" elapsed="913170" result="0" --> + <rect class="krnl" x="155.066" y="880.000" width="91.317" height="20.000" /> + <text x="160.066" y="895.000">azx_driver_init <tspan class="run">0.913s</tspan></text> +<!-- thread="fuse_init" time="4.330" elapsed="131" result="0" --> +<!-- thread="alsa_rawmidi_init" time="4.446" elapsed="0" result="0" --> +<!-- thread="snd_usb_audio_init" time="4.508" elapsed="54841" result="0" --> + <rect class="krnl" x="445.286" y="900.000" width="5.484" height="20.000" /> + <text x="450.286" y="915.000">snd_usb_audio_init <tspan class="run">0.055s</tspan></text> +</g> + +<g transform="translate(10,1920.000)"> +<!-- Process graph --> +<text class="t2" x="5" y="-15">Processes</text> +<rect class="box" x="0.000" y="0" width="2095.495" height="2180.000" /> + <line class="sec5" x1="0.000" y1="0" x2="0.000" y2="2180.000" /> + <text class="sec" x="0.000" y="-5.000" >0.0s</text> + <line class="sec01" x1="10.000" y1="0" x2="10.000" y2="2180.000" /> + <line class="sec01" x1="20.000" y1="0" x2="20.000" y2="2180.000" /> + <line class="sec01" x1="30.000" y1="0" x2="30.000" y2="2180.000" /> + <line class="sec01" x1="40.000" y1="0" x2="40.000" y2="2180.000" /> + <line class="sec01" x1="50.000" y1="0" x2="50.000" y2="2180.000" /> + <line class="sec01" x1="60.000" y1="0" x2="60.000" y2="2180.000" /> + <line class="sec01" x1="70.000" y1="0" x2="70.000" y2="2180.000" /> + <line class="sec01" x1="80.000" y1="0" x2="80.000" y2="2180.000" /> + <line class="sec01" x1="90.000" y1="0" x2="90.000" y2="2180.000" /> + <line class="sec1" x1="100.000" y1="0" x2="100.000" y2="2180.000" /> + <text class="sec" x="100.000" y="-5.000" >1.0s</text> + <line class="sec01" x1="110.000" y1="0" x2="110.000" y2="2180.000" /> + <line class="sec01" x1="120.000" y1="0" x2="120.000" y2="2180.000" /> + <line class="sec01" x1="130.000" y1="0" x2="130.000" y2="2180.000" /> + <line class="sec01" x1="140.000" y1="0" x2="140.000" y2="2180.000" /> + <line class="sec01" x1="150.000" y1="0" x2="150.000" y2="2180.000" /> + <line class="sec01" x1="160.000" y1="0" x2="160.000" y2="2180.000" /> + <line class="sec01" x1="170.000" y1="0" x2="170.000" y2="2180.000" /> + <line class="sec01" x1="180.000" y1="0" x2="180.000" y2="2180.000" /> + <line class="sec01" x1="190.000" y1="0" x2="190.000" y2="2180.000" /> + <line class="sec1" x1="200.000" y1="0" x2="200.000" y2="2180.000" /> + <text class="sec" x="200.000" y="-5.000" >2.0s</text> + <line class="sec01" x1="210.000" y1="0" x2="210.000" y2="2180.000" /> + <line class="sec01" x1="220.000" y1="0" x2="220.000" y2="2180.000" /> + <line class="sec01" x1="230.000" y1="0" x2="230.000" y2="2180.000" /> + <line class="sec01" x1="240.000" y1="0" x2="240.000" y2="2180.000" /> + <line class="sec01" x1="250.000" y1="0" x2="250.000" y2="2180.000" /> + <line class="sec01" x1="260.000" y1="0" x2="260.000" y2="2180.000" /> + <line class="sec01" x1="270.000" y1="0" x2="270.000" y2="2180.000" /> + <line class="sec01" x1="280.000" y1="0" x2="280.000" y2="2180.000" /> + <line class="sec01" x1="290.000" y1="0" x2="290.000" y2="2180.000" /> + <line class="sec1" x1="300.000" y1="0" x2="300.000" y2="2180.000" /> + <text class="sec" x="300.000" y="-5.000" >3.0s</text> + <line class="sec01" x1="310.000" y1="0" x2="310.000" y2="2180.000" /> + <line class="sec01" x1="320.000" y1="0" x2="320.000" y2="2180.000" /> + <line class="sec01" x1="330.000" y1="0" x2="330.000" y2="2180.000" /> + <line class="sec01" x1="340.000" y1="0" x2="340.000" y2="2180.000" /> + <line class="sec01" x1="350.000" y1="0" x2="350.000" y2="2180.000" /> + <line class="sec01" x1="360.000" y1="0" x2="360.000" y2="2180.000" /> + <line class="sec01" x1="370.000" y1="0" x2="370.000" y2="2180.000" /> + <line class="sec01" x1="380.000" y1="0" x2="380.000" y2="2180.000" /> + <line class="sec01" x1="390.000" y1="0" x2="390.000" y2="2180.000" /> + <line class="sec1" x1="400.000" y1="0" x2="400.000" y2="2180.000" /> + <text class="sec" x="400.000" y="-5.000" >4.0s</text> + <line class="sec01" x1="410.000" y1="0" x2="410.000" y2="2180.000" /> + <line class="sec01" x1="420.000" y1="0" x2="420.000" y2="2180.000" /> + <line class="sec01" x1="430.000" y1="0" x2="430.000" y2="2180.000" /> + <line class="sec01" x1="440.000" y1="0" x2="440.000" y2="2180.000" /> + <line class="sec01" x1="450.000" y1="0" x2="450.000" y2="2180.000" /> + <line class="sec01" x1="460.000" y1="0" x2="460.000" y2="2180.000" /> + <line class="sec01" x1="470.000" y1="0" x2="470.000" y2="2180.000" /> + <line class="sec01" x1="480.000" y1="0" x2="480.000" y2="2180.000" /> + <line class="sec01" x1="490.000" y1="0" x2="490.000" y2="2180.000" /> + <line class="sec5" x1="500.000" y1="0" x2="500.000" y2="2180.000" /> + <text class="sec" x="500.000" y="-5.000" >5.0s</text> + <line class="sec01" x1="510.000" y1="0" x2="510.000" y2="2180.000" /> + <line class="sec01" x1="520.000" y1="0" x2="520.000" y2="2180.000" /> + <line class="sec01" x1="530.000" y1="0" x2="530.000" y2="2180.000" /> + <line class="sec01" x1="540.000" y1="0" x2="540.000" y2="2180.000" /> + <line class="sec01" x1="550.000" y1="0" x2="550.000" y2="2180.000" /> + <line class="sec01" x1="560.000" y1="0" x2="560.000" y2="2180.000" /> + <line class="sec01" x1="570.000" y1="0" x2="570.000" y2="2180.000" /> + <line class="sec01" x1="580.000" y1="0" x2="580.000" y2="2180.000" /> + <line class="sec01" x1="590.000" y1="0" x2="590.000" y2="2180.000" /> + <line class="sec1" x1="600.000" y1="0" x2="600.000" y2="2180.000" /> + <text class="sec" x="600.000" y="-5.000" >6.0s</text> + <line class="sec01" x1="610.000" y1="0" x2="610.000" y2="2180.000" /> + <line class="sec01" x1="620.000" y1="0" x2="620.000" y2="2180.000" /> + <line class="sec01" x1="630.000" y1="0" x2="630.000" y2="2180.000" /> + <line class="sec01" x1="640.000" y1="0" x2="640.000" y2="2180.000" /> + <line class="sec01" x1="650.000" y1="0" x2="650.000" y2="2180.000" /> + <line class="sec01" x1="660.000" y1="0" x2="660.000" y2="2180.000" /> + <line class="sec01" x1="670.000" y1="0" x2="670.000" y2="2180.000" /> + <line class="sec01" x1="680.000" y1="0" x2="680.000" y2="2180.000" /> + <line class="sec01" x1="690.000" y1="0" x2="690.000" y2="2180.000" /> + <line class="sec1" x1="700.000" y1="0" x2="700.000" y2="2180.000" /> + <text class="sec" x="700.000" y="-5.000" >7.0s</text> + <line class="sec01" x1="710.000" y1="0" x2="710.000" y2="2180.000" /> + <line class="sec01" x1="720.000" y1="0" x2="720.000" y2="2180.000" /> + <line class="sec01" x1="730.000" y1="0" x2="730.000" y2="2180.000" /> + <line class="sec01" x1="740.000" y1="0" x2="740.000" y2="2180.000" /> + <line class="sec01" x1="750.000" y1="0" x2="750.000" y2="2180.000" /> + <line class="sec01" x1="760.000" y1="0" x2="760.000" y2="2180.000" /> + <line class="sec01" x1="770.000" y1="0" x2="770.000" y2="2180.000" /> + <line class="sec01" x1="780.000" y1="0" x2="780.000" y2="2180.000" /> + <line class="sec01" x1="790.000" y1="0" x2="790.000" y2="2180.000" /> + <line class="sec1" x1="800.000" y1="0" x2="800.000" y2="2180.000" /> + <text class="sec" x="800.000" y="-5.000" >8.0s</text> + <line class="sec01" x1="810.000" y1="0" x2="810.000" y2="2180.000" /> + <line class="sec01" x1="820.000" y1="0" x2="820.000" y2="2180.000" /> + <line class="sec01" x1="830.000" y1="0" x2="830.000" y2="2180.000" /> + <line class="sec01" x1="840.000" y1="0" x2="840.000" y2="2180.000" /> + <line class="sec01" x1="850.000" y1="0" x2="850.000" y2="2180.000" /> + <line class="sec01" x1="860.000" y1="0" x2="860.000" y2="2180.000" /> + <line class="sec01" x1="870.000" y1="0" x2="870.000" y2="2180.000" /> + <line class="sec01" x1="880.000" y1="0" x2="880.000" y2="2180.000" /> + <line class="sec01" x1="890.000" y1="0" x2="890.000" y2="2180.000" /> + <line class="sec1" x1="900.000" y1="0" x2="900.000" y2="2180.000" /> + <text class="sec" x="900.000" y="-5.000" >9.0s</text> + <line class="sec01" x1="910.000" y1="0" x2="910.000" y2="2180.000" /> + <line class="sec01" x1="920.000" y1="0" x2="920.000" y2="2180.000" /> + <line class="sec01" x1="930.000" y1="0" x2="930.000" y2="2180.000" /> + <line class="sec01" x1="940.000" y1="0" x2="940.000" y2="2180.000" /> + <line class="sec01" x1="950.000" y1="0" x2="950.000" y2="2180.000" /> + <line class="sec01" x1="960.000" y1="0" x2="960.000" y2="2180.000" /> + <line class="sec01" x1="970.000" y1="0" x2="970.000" y2="2180.000" /> + <line class="sec01" x1="980.000" y1="0" x2="980.000" y2="2180.000" /> + <line class="sec01" x1="990.000" y1="0" x2="990.000" y2="2180.000" /> + <line class="sec5" x1="1000.000" y1="0" x2="1000.000" y2="2180.000" /> + <text class="sec" x="1000.000" y="-5.000" >10.0s</text> + <line class="sec01" x1="1010.000" y1="0" x2="1010.000" y2="2180.000" /> + <line class="sec01" x1="1020.000" y1="0" x2="1020.000" y2="2180.000" /> + <line class="sec01" x1="1030.000" y1="0" x2="1030.000" y2="2180.000" /> + <line class="sec01" x1="1040.000" y1="0" x2="1040.000" y2="2180.000" /> + <line class="sec01" x1="1050.000" y1="0" x2="1050.000" y2="2180.000" /> + <line class="sec01" x1="1060.000" y1="0" x2="1060.000" y2="2180.000" /> + <line class="sec01" x1="1070.000" y1="0" x2="1070.000" y2="2180.000" /> + <line class="sec01" x1="1080.000" y1="0" x2="1080.000" y2="2180.000" /> + <line class="sec01" x1="1090.000" y1="0" x2="1090.000" y2="2180.000" /> + <line class="sec1" x1="1100.000" y1="0" x2="1100.000" y2="2180.000" /> + <text class="sec" x="1100.000" y="-5.000" >11.0s</text> + <line class="sec01" x1="1110.000" y1="0" x2="1110.000" y2="2180.000" /> + <line class="sec01" x1="1120.000" y1="0" x2="1120.000" y2="2180.000" /> + <line class="sec01" x1="1130.000" y1="0" x2="1130.000" y2="2180.000" /> + <line class="sec01" x1="1140.000" y1="0" x2="1140.000" y2="2180.000" /> + <line class="sec01" x1="1150.000" y1="0" x2="1150.000" y2="2180.000" /> + <line class="sec01" x1="1160.000" y1="0" x2="1160.000" y2="2180.000" /> + <line class="sec01" x1="1170.000" y1="0" x2="1170.000" y2="2180.000" /> + <line class="sec01" x1="1180.000" y1="0" x2="1180.000" y2="2180.000" /> + <line class="sec01" x1="1190.000" y1="0" x2="1190.000" y2="2180.000" /> + <line class="sec1" x1="1200.000" y1="0" x2="1200.000" y2="2180.000" /> + <text class="sec" x="1200.000" y="-5.000" >12.0s</text> + <line class="sec01" x1="1210.000" y1="0" x2="1210.000" y2="2180.000" /> + <line class="sec01" x1="1220.000" y1="0" x2="1220.000" y2="2180.000" /> + <line class="sec01" x1="1230.000" y1="0" x2="1230.000" y2="2180.000" /> + <line class="sec01" x1="1240.000" y1="0" x2="1240.000" y2="2180.000" /> + <line class="sec01" x1="1250.000" y1="0" x2="1250.000" y2="2180.000" /> + <line class="sec01" x1="1260.000" y1="0" x2="1260.000" y2="2180.000" /> + <line class="sec01" x1="1270.000" y1="0" x2="1270.000" y2="2180.000" /> + <line class="sec01" x1="1280.000" y1="0" x2="1280.000" y2="2180.000" /> + <line class="sec01" x1="1290.000" y1="0" x2="1290.000" y2="2180.000" /> + <line class="sec1" x1="1300.000" y1="0" x2="1300.000" y2="2180.000" /> + <text class="sec" x="1300.000" y="-5.000" >13.0s</text> + <line class="sec01" x1="1310.000" y1="0" x2="1310.000" y2="2180.000" /> + <line class="sec01" x1="1320.000" y1="0" x2="1320.000" y2="2180.000" /> + <line class="sec01" x1="1330.000" y1="0" x2="1330.000" y2="2180.000" /> + <line class="sec01" x1="1340.000" y1="0" x2="1340.000" y2="2180.000" /> + <line class="sec01" x1="1350.000" y1="0" x2="1350.000" y2="2180.000" /> + <line class="sec01" x1="1360.000" y1="0" x2="1360.000" y2="2180.000" /> + <line class="sec01" x1="1370.000" y1="0" x2="1370.000" y2="2180.000" /> + <line class="sec01" x1="1380.000" y1="0" x2="1380.000" y2="2180.000" /> + <line class="sec01" x1="1390.000" y1="0" x2="1390.000" y2="2180.000" /> + <line class="sec1" x1="1400.000" y1="0" x2="1400.000" y2="2180.000" /> + <text class="sec" x="1400.000" y="-5.000" >14.0s</text> + <line class="sec01" x1="1410.000" y1="0" x2="1410.000" y2="2180.000" /> + <line class="sec01" x1="1420.000" y1="0" x2="1420.000" y2="2180.000" /> + <line class="sec01" x1="1430.000" y1="0" x2="1430.000" y2="2180.000" /> + <line class="sec01" x1="1440.000" y1="0" x2="1440.000" y2="2180.000" /> + <line class="sec01" x1="1450.000" y1="0" x2="1450.000" y2="2180.000" /> + <line class="sec01" x1="1460.000" y1="0" x2="1460.000" y2="2180.000" /> + <line class="sec01" x1="1470.000" y1="0" x2="1470.000" y2="2180.000" /> + <line class="sec01" x1="1480.000" y1="0" x2="1480.000" y2="2180.000" /> + <line class="sec01" x1="1490.000" y1="0" x2="1490.000" y2="2180.000" /> + <line class="sec5" x1="1500.000" y1="0" x2="1500.000" y2="2180.000" /> + <text class="sec" x="1500.000" y="-5.000" >15.0s</text> + <line class="sec01" x1="1510.000" y1="0" x2="1510.000" y2="2180.000" /> + <line class="sec01" x1="1520.000" y1="0" x2="1520.000" y2="2180.000" /> + <line class="sec01" x1="1530.000" y1="0" x2="1530.000" y2="2180.000" /> + <line class="sec01" x1="1540.000" y1="0" x2="1540.000" y2="2180.000" /> + <line class="sec01" x1="1550.000" y1="0" x2="1550.000" y2="2180.000" /> + <line class="sec01" x1="1560.000" y1="0" x2="1560.000" y2="2180.000" /> + <line class="sec01" x1="1570.000" y1="0" x2="1570.000" y2="2180.000" /> + <line class="sec01" x1="1580.000" y1="0" x2="1580.000" y2="2180.000" /> + <line class="sec01" x1="1590.000" y1="0" x2="1590.000" y2="2180.000" /> + <line class="sec1" x1="1600.000" y1="0" x2="1600.000" y2="2180.000" /> + <text class="sec" x="1600.000" y="-5.000" >16.0s</text> + <line class="sec01" x1="1610.000" y1="0" x2="1610.000" y2="2180.000" /> + <line class="sec01" x1="1620.000" y1="0" x2="1620.000" y2="2180.000" /> + <line class="sec01" x1="1630.000" y1="0" x2="1630.000" y2="2180.000" /> + <line class="sec01" x1="1640.000" y1="0" x2="1640.000" y2="2180.000" /> + <line class="sec01" x1="1650.000" y1="0" x2="1650.000" y2="2180.000" /> + <line class="sec01" x1="1660.000" y1="0" x2="1660.000" y2="2180.000" /> + <line class="sec01" x1="1670.000" y1="0" x2="1670.000" y2="2180.000" /> + <line class="sec01" x1="1680.000" y1="0" x2="1680.000" y2="2180.000" /> + <line class="sec01" x1="1690.000" y1="0" x2="1690.000" y2="2180.000" /> + <line class="sec1" x1="1700.000" y1="0" x2="1700.000" y2="2180.000" /> + <text class="sec" x="1700.000" y="-5.000" >17.0s</text> + <line class="sec01" x1="1710.000" y1="0" x2="1710.000" y2="2180.000" /> + <line class="sec01" x1="1720.000" y1="0" x2="1720.000" y2="2180.000" /> + <line class="sec01" x1="1730.000" y1="0" x2="1730.000" y2="2180.000" /> + <line class="sec01" x1="1740.000" y1="0" x2="1740.000" y2="2180.000" /> + <line class="sec01" x1="1750.000" y1="0" x2="1750.000" y2="2180.000" /> + <line class="sec01" x1="1760.000" y1="0" x2="1760.000" y2="2180.000" /> + <line class="sec01" x1="1770.000" y1="0" x2="1770.000" y2="2180.000" /> + <line class="sec01" x1="1780.000" y1="0" x2="1780.000" y2="2180.000" /> + <line class="sec01" x1="1790.000" y1="0" x2="1790.000" y2="2180.000" /> + <line class="sec1" x1="1800.000" y1="0" x2="1800.000" y2="2180.000" /> + <text class="sec" x="1800.000" y="-5.000" >18.0s</text> + <line class="sec01" x1="1810.000" y1="0" x2="1810.000" y2="2180.000" /> + <line class="sec01" x1="1820.000" y1="0" x2="1820.000" y2="2180.000" /> + <line class="sec01" x1="1830.000" y1="0" x2="1830.000" y2="2180.000" /> + <line class="sec01" x1="1840.000" y1="0" x2="1840.000" y2="2180.000" /> + <line class="sec01" x1="1850.000" y1="0" x2="1850.000" y2="2180.000" /> + <line class="sec01" x1="1860.000" y1="0" x2="1860.000" y2="2180.000" /> + <line class="sec01" x1="1870.000" y1="0" x2="1870.000" y2="2180.000" /> + <line class="sec01" x1="1880.000" y1="0" x2="1880.000" y2="2180.000" /> + <line class="sec01" x1="1890.000" y1="0" x2="1890.000" y2="2180.000" /> + <line class="sec1" x1="1900.000" y1="0" x2="1900.000" y2="2180.000" /> + <text class="sec" x="1900.000" y="-5.000" >19.0s</text> + <line class="sec01" x1="1910.000" y1="0" x2="1910.000" y2="2180.000" /> + <line class="sec01" x1="1920.000" y1="0" x2="1920.000" y2="2180.000" /> + <line class="sec01" x1="1930.000" y1="0" x2="1930.000" y2="2180.000" /> + <line class="sec01" x1="1940.000" y1="0" x2="1940.000" y2="2180.000" /> + <line class="sec01" x1="1950.000" y1="0" x2="1950.000" y2="2180.000" /> + <line class="sec01" x1="1960.000" y1="0" x2="1960.000" y2="2180.000" /> + <line class="sec01" x1="1970.000" y1="0" x2="1970.000" y2="2180.000" /> + <line class="sec01" x1="1980.000" y1="0" x2="1980.000" y2="2180.000" /> + <line class="sec01" x1="1990.000" y1="0" x2="1990.000" y2="2180.000" /> + <line class="sec5" x1="2000.000" y1="0" x2="2000.000" y2="2180.000" /> + <text class="sec" x="2000.000" y="-5.000" >20.0s</text> + <line class="sec01" x1="2010.000" y1="0" x2="2010.000" y2="2180.000" /> + <line class="sec01" x1="2020.000" y1="0" x2="2020.000" y2="2180.000" /> + <line class="sec01" x1="2030.000" y1="0" x2="2030.000" y2="2180.000" /> + <line class="sec01" x1="2040.000" y1="0" x2="2040.000" y2="2180.000" /> + <line class="sec01" x1="2050.000" y1="0" x2="2050.000" y2="2180.000" /> + <line class="sec01" x1="2060.000" y1="0" x2="2060.000" y2="2180.000" /> + <line class="sec01" x1="2070.000" y1="0" x2="2070.000" y2="2180.000" /> + <line class="sec01" x1="2080.000" y1="0" x2="2080.000" y2="2180.000" /> + <line class="sec01" x1="2090.000" y1="0" x2="2090.000" y2="2180.000" /> +<!-- systemd [1] ppid=0 runtime=0.359s --> + <rect class="ps" x="101.950" y="0.000" width="1993.545" height="20.000" /> + <rect class="wait" x="101.950" y="0.000" width="4.010" height="16.179" /> + <rect class="cpu" x="101.950" y="0.000" width="4.010" height="20.000" /> + <rect class="wait" x="105.960" y="0.000" width="4.008" height="0.084" /> + <rect class="cpu" x="105.960" y="16.863" width="4.008" height="3.137" /> + <rect class="wait" x="109.967" y="0.000" width="4.011" height="0.546" /> + <rect class="cpu" x="109.967" y="13.777" width="4.011" height="6.223" /> + <rect class="wait" x="113.978" y="0.000" width="4.008" height="0.504" /> + <rect class="cpu" x="113.978" y="13.778" width="4.008" height="6.222" /> + <rect class="wait" x="117.986" y="0.000" width="4.007" height="0.000" /> + <rect class="cpu" x="117.986" y="17.504" width="4.007" height="2.496" /> + <rect class="wait" x="178.214" y="0.000" width="4.024" height="0.032" /> + <rect class="cpu" x="178.214" y="15.927" width="4.024" height="4.073" /> + <text x="106.950" y="14.000">systemd [1] <tspan class="run">0.359s</tspan></text> + +<!-- kthreadd [2] ppid=1 runtime=0.001s --> + <rect class="ps" x="101.950" y="20.000" width="1993.545" height="20.000" /> + <text x="106.950" y="34.000">kthreadd [2] <tspan class="run">0.001s</tspan></text> + <line class="dot" x1="101.950" y1="30.000" x2="101.950" y2="30.000" /> + +<!-- ksoftirqd/0 [3] ppid=2 runtime=0.002s --> + <rect class="ps" x="101.950" y="40.000" width="1993.545" height="20.000" /> + <text x="106.950" y="54.000">ksoftirqd/0 [3] <tspan class="run">0.002s</tspan></text> + <line class="dot" x1="101.950" y1="50.000" x2="101.950" y2="50.000" /> + +<!-- kworker/0:0 [4] ppid=2 runtime=0.000s --> +<!-- kworker/0:0H [5] ppid=2 runtime=0.000s --> +<!-- kworker/u:0 [6] ppid=2 runtime=0.000s --> +<!-- kworker/u:0H [7] ppid=2 runtime=0.000s --> +<!-- migration/0 [8] ppid=2 runtime=0.282s --> + <rect class="ps" x="101.950" y="60.000" width="1993.545" height="20.000" /> + <rect class="wait" x="186.244" y="60.000" width="4.006" height="0.000" /> + <rect class="cpu" x="186.244" y="67.141" width="4.006" height="12.859" /> + <rect class="wait" x="194.256" y="60.000" width="4.006" height="0.000" /> + <rect class="cpu" x="194.256" y="67.312" width="4.006" height="12.688" /> + <rect class="wait" x="238.335" y="60.000" width="4.009" height="0.000" /> + <rect class="cpu" x="238.335" y="73.734" width="4.009" height="6.266" /> + <rect class="wait" x="250.358" y="60.000" width="4.006" height="0.000" /> + <rect class="cpu" x="250.358" y="67.088" width="4.006" height="12.912" /> + <rect class="wait" x="258.369" y="60.000" width="4.008" height="0.000" /> + <rect class="cpu" x="258.369" y="68.339" width="4.008" height="11.661" /> + <rect class="wait" x="298.441" y="60.000" width="4.006" height="0.000" /> + <rect class="cpu" x="298.441" y="76.473" width="4.006" height="3.527" /> + <rect class="wait" x="398.624" y="60.000" width="4.021" height="0.000" /> + <rect class="cpu" x="398.624" y="69.021" width="4.021" height="10.979" /> + <rect class="wait" x="418.677" y="60.000" width="4.007" height="0.000" /> + <rect class="cpu" x="418.677" y="69.616" width="4.007" height="10.384" /> + <rect class="wait" x="426.696" y="60.000" width="4.006" height="0.000" /> + <rect class="cpu" x="426.696" y="76.530" width="4.006" height="3.470" /> + <rect class="wait" x="643.090" y="60.000" width="4.007" height="0.000" /> + <rect class="cpu" x="643.090" y="74.371" width="4.007" height="5.629" /> + <rect class="wait" x="695.200" y="60.000" width="4.007" height="0.000" /> + <rect class="cpu" x="695.200" y="76.848" width="4.007" height="3.152" /> + <rect class="wait" x="699.207" y="60.000" width="4.010" height="0.000" /> + <rect class="cpu" x="699.207" y="76.809" width="4.010" height="3.191" /> + <rect class="wait" x="735.295" y="60.000" width="4.009" height="0.000" /> + <rect class="cpu" x="735.295" y="77.327" width="4.009" height="2.673" /> + <rect class="wait" x="771.381" y="60.000" width="4.009" height="0.000" /> + <rect class="cpu" x="771.381" y="76.682" width="4.009" height="3.318" /> + <rect class="wait" x="775.390" y="60.000" width="4.006" height="0.000" /> + <rect class="cpu" x="775.390" y="76.970" width="4.006" height="3.030" /> + <rect class="wait" x="791.422" y="60.000" width="4.006" height="0.000" /> + <rect class="cpu" x="791.422" y="77.218" width="4.006" height="2.782" /> + <rect class="wait" x="803.444" y="60.000" width="4.011" height="0.000" /> + <rect class="cpu" x="803.444" y="77.355" width="4.011" height="2.645" /> + <rect class="wait" x="807.454" y="60.000" width="4.006" height="0.000" /> + <rect class="cpu" x="807.454" y="77.123" width="4.006" height="2.877" /> + <rect class="wait" x="815.470" y="60.000" width="4.007" height="0.000" /> + <rect class="cpu" x="815.470" y="77.892" width="4.007" height="2.108" /> + <rect class="wait" x="819.477" y="60.000" width="4.006" height="0.000" /> + <rect class="cpu" x="819.477" y="77.574" width="4.006" height="2.426" /> + <rect class="wait" x="831.500" y="60.000" width="4.010" height="0.000" /> + <rect class="cpu" x="831.500" y="77.894" width="4.010" height="2.106" /> + <rect class="wait" x="847.538" y="60.000" width="4.006" height="0.000" /> + <rect class="cpu" x="847.538" y="77.395" width="4.006" height="2.605" /> + <rect class="wait" x="867.570" y="60.000" width="4.015" height="0.000" /> + <rect class="cpu" x="867.570" y="72.567" width="4.015" height="7.433" /> + <rect class="wait" x="871.585" y="60.000" width="4.006" height="0.000" /> + <rect class="cpu" x="871.585" y="72.220" width="4.006" height="7.780" /> + <text x="106.950" y="74.000">migration/0 [8] <tspan class="run">0.282s</tspan></text> + <line class="dot" x1="101.950" y1="70.000" x2="101.950" y2="70.000" /> + +<!-- rcu_bh [9] ppid=2 runtime=0.000s --> +<!-- rcu_sched [10] ppid=2 runtime=0.036s --> + <rect class="ps" x="101.950" y="80.000" width="1993.545" height="20.000" /> + <rect class="wait" x="138.135" y="80.000" width="4.006" height="0.029" /> + <rect class="cpu" x="138.135" y="95.843" width="4.006" height="4.157" /> + <rect class="wait" x="142.141" y="80.000" width="4.002" height="4.105" /> + <rect class="cpu" x="142.141" y="99.760" width="4.002" height="0.240" /> + <rect class="wait" x="542.902" y="80.000" width="4.009" height="3.645" /> + <rect class="cpu" x="542.902" y="99.986" width="4.009" height="0.014" /> + <text x="106.950" y="94.000">rcu_sched [10] <tspan class="run">0.036s</tspan></text> + <line class="dot" x1="101.950" y1="90.000" x2="101.950" y2="90.000" /> + +<!-- watchdog/0 [11] ppid=2 runtime=0.000s --> +<!-- watchdog/1 [12] ppid=2 runtime=0.000s --> +<!-- ksoftirqd/1 [13] ppid=2 runtime=0.001s --> + <rect class="ps" x="101.950" y="100.000" width="1993.545" height="20.000" /> + <rect class="wait" x="502.838" y="100.000" width="4.006" height="4.585" /> + <rect class="cpu" x="502.838" y="119.998" width="4.006" height="0.002" /> + <text x="106.950" y="114.000">ksoftirqd/1 [13] <tspan class="run">0.001s</tspan></text> + <line class="dot" x1="101.950" y1="110.000" x2="101.950" y2="110.000" /> + +<!-- migration/1 [14] ppid=2 runtime=0.203s --> + <rect class="ps" x="101.950" y="120.000" width="1993.545" height="20.000" /> + <rect class="wait" x="166.186" y="120.000" width="4.006" height="0.000" /> + <rect class="cpu" x="166.186" y="120.000" width="4.006" height="20.000" /> + <rect class="wait" x="190.250" y="120.000" width="4.006" height="0.000" /> + <rect class="cpu" x="190.250" y="130.943" width="4.006" height="9.057" /> + <rect class="wait" x="250.358" y="120.000" width="4.006" height="0.000" /> + <rect class="cpu" x="250.358" y="126.924" width="4.006" height="13.076" /> + <rect class="wait" x="254.363" y="120.000" width="4.006" height="0.000" /> + <rect class="cpu" x="254.363" y="126.783" width="4.006" height="13.217" /> + <rect class="wait" x="422.684" y="120.000" width="4.012" height="0.000" /> + <rect class="cpu" x="422.684" y="126.483" width="4.012" height="13.517" /> + <rect class="wait" x="578.966" y="120.000" width="4.007" height="0.000" /> + <rect class="cpu" x="578.966" y="135.673" width="4.007" height="4.327" /> + <rect class="wait" x="719.258" y="120.000" width="4.007" height="0.000" /> + <rect class="cpu" x="719.258" y="137.000" width="4.007" height="3.000" /> + <text x="106.950" y="134.000">migration/1 [14] <tspan class="run">0.203s</tspan></text> + <line class="dot" x1="101.950" y1="130.000" x2="101.950" y2="130.000" /> + +<!-- kworker/1:0 [15] ppid=2 runtime=0.000s --> +<!-- kworker/1:0H [16] ppid=2 runtime=0.000s --> +<!-- watchdog/2 [17] ppid=2 runtime=0.000s --> +<!-- ksoftirqd/2 [18] ppid=2 runtime=0.004s --> + <rect class="ps" x="101.950" y="140.000" width="1993.545" height="20.000" /> + <text x="106.950" y="154.000">ksoftirqd/2 [18] <tspan class="run">0.004s</tspan></text> + <line class="dot" x1="101.950" y1="150.000" x2="101.950" y2="150.000" /> + +<!-- migration/2 [19] ppid=2 runtime=0.173s --> + <rect class="ps" x="101.950" y="160.000" width="1993.545" height="20.000" /> + <rect class="wait" x="158.170" y="160.000" width="4.007" height="0.000" /> + <rect class="cpu" x="158.170" y="175.985" width="4.007" height="4.015" /> + <rect class="wait" x="182.238" y="160.000" width="4.006" height="0.000" /> + <rect class="cpu" x="182.238" y="175.734" width="4.006" height="4.266" /> + <rect class="wait" x="266.386" y="160.000" width="4.007" height="0.000" /> + <rect class="cpu" x="266.386" y="170.162" width="4.007" height="9.838" /> + <rect class="wait" x="274.400" y="160.000" width="4.007" height="0.000" /> + <rect class="cpu" x="274.400" y="167.132" width="4.007" height="12.868" /> + <rect class="wait" x="282.414" y="160.000" width="4.007" height="0.000" /> + <rect class="cpu" x="282.414" y="175.870" width="4.007" height="4.130" /> + <rect class="wait" x="294.434" y="160.000" width="4.007" height="0.000" /> + <rect class="cpu" x="294.434" y="177.006" width="4.007" height="2.994" /> + <rect class="wait" x="302.446" y="160.000" width="4.007" height="0.000" /> + <rect class="cpu" x="302.446" y="166.622" width="4.007" height="13.378" /> + <rect class="wait" x="314.468" y="160.000" width="4.008" height="0.000" /> + <rect class="cpu" x="314.468" y="173.384" width="4.008" height="6.616" /> + <rect class="wait" x="394.616" y="160.000" width="4.008" height="0.000" /> + <rect class="cpu" x="394.616" y="168.184" width="4.008" height="11.816" /> + <rect class="wait" x="554.922" y="160.000" width="4.007" height="0.000" /> + <rect class="cpu" x="554.922" y="170.714" width="4.007" height="9.286" /> + <rect class="wait" x="867.570" y="160.000" width="4.015" height="0.000" /> + <rect class="cpu" x="867.570" y="174.866" width="4.015" height="5.134" /> + <text x="106.950" y="174.000">migration/2 [19] <tspan class="run">0.173s</tspan></text> + <line class="dot" x1="101.950" y1="170.000" x2="101.950" y2="170.000" /> + +<!-- kworker/2:0 [20] ppid=2 runtime=0.001s --> +<!-- kworker/2:0H [21] ppid=2 runtime=0.000s --> +<!-- watchdog/3 [22] ppid=2 runtime=0.000s --> +<!-- ksoftirqd/3 [23] ppid=2 runtime=0.002s --> + <rect class="ps" x="101.950" y="180.000" width="1993.545" height="20.000" /> + <text x="106.950" y="194.000">ksoftirqd/3 [23] <tspan class="run">0.002s</tspan></text> + <line class="dot" x1="101.950" y1="190.000" x2="101.950" y2="190.000" /> + +<!-- migration/3 [24] ppid=2 runtime=0.084s --> + <rect class="ps" x="101.950" y="200.000" width="1993.545" height="20.000" /> + <rect class="wait" x="214.286" y="200.000" width="4.007" height="0.000" /> + <rect class="cpu" x="214.286" y="207.943" width="4.007" height="12.057" /> + <rect class="wait" x="270.393" y="200.000" width="4.007" height="0.000" /> + <rect class="cpu" x="270.393" y="206.458" width="4.007" height="13.542" /> + <rect class="wait" x="278.406" y="200.000" width="4.008" height="0.000" /> + <rect class="cpu" x="278.406" y="208.355" width="4.008" height="11.645" /> + <rect class="wait" x="282.414" y="200.000" width="4.007" height="0.000" /> + <rect class="cpu" x="282.414" y="215.911" width="4.007" height="4.089" /> + <text x="106.950" y="214.000">migration/3 [24] <tspan class="run">0.084s</tspan></text> + <line class="dot" x1="101.950" y1="210.000" x2="101.950" y2="210.000" /> + +<!-- kworker/3:0 [25] ppid=2 runtime=0.000s --> +<!-- kworker/3:0H [26] ppid=2 runtime=0.000s --> +<!-- cpuset [27] ppid=2 runtime=0.000s --> +<!-- khelper [28] ppid=2 runtime=0.000s --> +<!-- kdevtmpfs [29] ppid=2 runtime=0.002s --> + <rect class="ps" x="101.950" y="220.000" width="1993.545" height="20.000" /> + <text x="106.950" y="234.000">kdevtmpfs [29] <tspan class="run">0.002s</tspan></text> + <line class="dot" x1="101.950" y1="230.000" x2="101.950" y2="230.000" /> + +<!-- netns [30] ppid=2 runtime=0.000s --> +<!-- bdi-default [31] ppid=2 runtime=0.000s --> +<!-- kintegrityd [32] ppid=2 runtime=0.000s --> +<!-- kblockd [33] ppid=2 runtime=0.000s --> +<!-- kworker/0:1 [34] ppid=2 runtime=0.045s --> + <rect class="ps" x="101.950" y="240.000" width="1993.545" height="20.000" /> + <rect class="wait" x="186.244" y="240.000" width="4.006" height="13.499" /> + <rect class="cpu" x="186.244" y="259.986" width="4.006" height="0.014" /> + <rect class="wait" x="190.250" y="240.000" width="4.006" height="13.382" /> + <rect class="cpu" x="190.250" y="259.996" width="4.006" height="0.004" /> + <rect class="wait" x="194.256" y="240.000" width="4.006" height="13.003" /> + <rect class="cpu" x="194.256" y="259.984" width="4.006" height="0.016" /> + <rect class="wait" x="238.335" y="240.000" width="4.009" height="6.588" /> + <rect class="cpu" x="238.335" y="259.979" width="4.009" height="0.021" /> + <rect class="wait" x="250.358" y="240.000" width="4.006" height="13.314" /> + <rect class="cpu" x="250.358" y="259.985" width="4.006" height="0.015" /> + <rect class="wait" x="258.369" y="240.000" width="4.008" height="11.950" /> + <rect class="cpu" x="258.369" y="259.990" width="4.008" height="0.010" /> + <rect class="wait" x="378.590" y="240.000" width="4.006" height="0.001" /> + <rect class="cpu" x="378.590" y="256.446" width="4.006" height="3.554" /> + <rect class="wait" x="382.596" y="240.000" width="4.007" height="0.000" /> + <rect class="cpu" x="382.596" y="255.739" width="4.007" height="4.261" /> + <rect class="wait" x="398.624" y="240.000" width="4.021" height="11.393" /> + <rect class="cpu" x="398.624" y="259.206" width="4.021" height="0.794" /> + <rect class="wait" x="418.677" y="240.000" width="4.007" height="10.423" /> + <rect class="cpu" x="418.677" y="259.984" width="4.007" height="0.016" /> + <rect class="wait" x="426.696" y="240.000" width="4.006" height="4.496" /> + <rect class="cpu" x="426.696" y="259.966" width="4.006" height="0.034" /> + <rect class="wait" x="486.814" y="240.000" width="4.006" height="2.003" /> + <rect class="cpu" x="486.814" y="259.987" width="4.006" height="0.013" /> + <rect class="wait" x="643.090" y="240.000" width="4.007" height="6.150" /> + <rect class="cpu" x="643.090" y="259.980" width="4.007" height="0.020" /> + <rect class="wait" x="695.200" y="240.000" width="4.007" height="3.288" /> + <rect class="cpu" x="695.200" y="259.955" width="4.007" height="0.045" /> + <rect class="wait" x="699.207" y="240.000" width="4.010" height="3.321" /> + <rect class="cpu" x="699.207" y="259.979" width="4.010" height="0.021" /> + <rect class="wait" x="735.295" y="240.000" width="4.009" height="2.776" /> + <rect class="cpu" x="735.295" y="259.951" width="4.009" height="0.049" /> + <rect class="wait" x="747.323" y="240.000" width="4.007" height="3.033" /> + <rect class="cpu" x="747.323" y="259.982" width="4.007" height="0.018" /> + <rect class="wait" x="771.381" y="240.000" width="4.009" height="3.471" /> + <rect class="cpu" x="771.381" y="259.959" width="4.009" height="0.041" /> + <rect class="wait" x="775.390" y="240.000" width="4.006" height="3.171" /> + <rect class="cpu" x="775.390" y="259.973" width="4.006" height="0.027" /> + <rect class="wait" x="791.422" y="240.000" width="4.006" height="2.909" /> + <rect class="cpu" x="791.422" y="259.974" width="4.006" height="0.026" /> + <rect class="wait" x="803.444" y="240.000" width="4.011" height="5.184" /> + <rect class="cpu" x="803.444" y="259.867" width="4.011" height="0.133" /> + <rect class="wait" x="807.454" y="240.000" width="4.006" height="3.012" /> + <rect class="cpu" x="807.454" y="259.903" width="4.006" height="0.097" /> + <rect class="wait" x="815.470" y="240.000" width="4.007" height="2.179" /> + <rect class="cpu" x="815.470" y="259.865" width="4.007" height="0.135" /> + <rect class="wait" x="819.477" y="240.000" width="4.006" height="2.546" /> + <rect class="cpu" x="819.477" y="259.950" width="4.006" height="0.050" /> + <rect class="wait" x="831.500" y="240.000" width="4.010" height="2.191" /> + <rect class="cpu" x="831.500" y="259.820" width="4.010" height="0.180" /> + <rect class="wait" x="847.538" y="240.000" width="4.006" height="2.720" /> + <rect class="cpu" x="847.538" y="259.964" width="4.006" height="0.036" /> + <rect class="wait" x="867.570" y="240.000" width="4.015" height="7.563" /> + <rect class="cpu" x="867.570" y="259.965" width="4.015" height="0.035" /> + <rect class="wait" x="871.585" y="240.000" width="4.006" height="7.916" /> + <rect class="cpu" x="871.585" y="259.981" width="4.006" height="0.019" /> + <rect class="wait" x="1031.947" y="240.000" width="4.008" height="2.495" /> + <rect class="cpu" x="1031.947" y="259.985" width="4.008" height="0.015" /> + <text x="106.950" y="254.000">kworker/0:1 [34] <tspan class="run">0.045s</tspan></text> + <line class="dot" x1="101.950" y1="250.000" x2="101.950" y2="250.000" /> + +<!-- ata_sff [35] ppid=2 runtime=0.000s --> +<!-- khubd [36] ppid=2 runtime=0.008s --> + <rect class="ps" x="101.950" y="260.000" width="1993.545" height="20.000" /> + <text x="106.950" y="274.000">khubd [36] <tspan class="run">0.008s</tspan></text> + <line class="dot" x1="101.950" y1="270.000" x2="101.950" y2="270.000" /> + +<!-- md [37] ppid=2 runtime=0.000s --> +<!-- kworker/u:1 [44] ppid=2 runtime=0.000s --> +<!-- kswapd0 [62] ppid=2 runtime=0.000s --> +<!-- ksmd [63] ppid=2 runtime=0.000s --> +<!-- khugepaged [64] ppid=2 runtime=0.001s --> + <rect class="ps" x="101.950" y="280.000" width="1993.545" height="20.000" /> + <text x="106.950" y="294.000">khugepaged [64] <tspan class="run">0.001s</tspan></text> + <line class="dot" x1="101.950" y1="290.000" x2="101.950" y2="290.000" /> + +<!-- fsnotify_mark [65] ppid=2 runtime=0.000s --> +<!-- crypto [66] ppid=2 runtime=0.000s --> +<!-- kthrotld [74] ppid=2 runtime=0.000s --> +<!-- scsi_eh_0 [76] ppid=2 runtime=0.000s --> +<!-- scsi_eh_1 [77] ppid=2 runtime=0.010s --> + <rect class="ps" x="101.950" y="300.000" width="1993.545" height="20.000" /> + <rect class="wait" x="142.141" y="300.000" width="4.002" height="0.471" /> + <rect class="cpu" x="142.141" y="315.290" width="4.002" height="4.710" /> + <text x="106.950" y="314.000">scsi_eh_1 [77] <tspan class="run">0.010s</tspan></text> + <line class="dot" x1="101.950" y1="310.000" x2="101.950" y2="310.000" /> + +<!-- scsi_eh_2 [78] ppid=2 runtime=0.000s --> +<!-- scsi_eh_3 [79] ppid=2 runtime=0.000s --> +<!-- scsi_eh_4 [80] ppid=2 runtime=0.000s --> +<!-- scsi_eh_5 [81] ppid=2 runtime=0.000s --> +<!-- kworker/u:2 [82] ppid=2 runtime=0.000s --> +<!-- kworker/u:3 [83] ppid=2 runtime=0.000s --> +<!-- kworker/u:4 [84] ppid=2 runtime=0.010s --> + <rect class="ps" x="101.950" y="320.000" width="1993.545" height="20.000" /> + <rect class="wait" x="242.344" y="320.000" width="4.006" height="3.275" /> + <rect class="cpu" x="242.344" y="339.998" width="4.006" height="0.002" /> + <text x="106.950" y="334.000">kworker/u:4 [84] <tspan class="run">0.010s</tspan></text> + <line class="dot" x1="101.950" y1="330.000" x2="101.950" y2="330.000" /> + +<!-- systemd-cgroups [296] ppid=84 runtime=0.000s --> +<!-- systemd-cgroups [347] ppid=84 runtime=0.000s --> +<!-- systemd-cgroups [653] ppid=84 runtime=0.000s --> + <line class="dot" x1="101.950" y1="330.000" x2="101.950" y2="340.000" /> +<!-- kworker/u:5 [85] ppid=2 runtime=0.011s --> + <rect class="ps" x="101.950" y="340.000" width="1993.545" height="20.000" /> + <rect class="wait" x="242.344" y="340.000" width="4.006" height="0.005" /> + <rect class="cpu" x="242.344" y="356.154" width="4.006" height="3.846" /> + <text x="106.950" y="354.000">kworker/u:5 [85] <tspan class="run">0.011s</tspan></text> + <line class="dot" x1="101.950" y1="350.000" x2="101.950" y2="350.000" /> + +<!-- systemd-cgroups [110] ppid=85 runtime=0.000s --> +<!-- systemd-cgroups [111] ppid=85 runtime=0.000s --> +<!-- systemd-cgroups [113] ppid=85 runtime=0.000s --> +<!-- systemd-cgroups [117] ppid=85 runtime=0.000s --> +<!-- systemd-cgroups [149] ppid=85 runtime=0.007s --> + <rect class="ps" x="138.135" y="360.000" width="8.008" height="20.000" /> + <text x="151.144" y="374.000">systemd-cgroups [149] <tspan class="run">0.007s</tspan></text> + <line class="dot" x1="138.135" y1="370.000" x2="101.950" y2="370.000" /> + +<!-- systemd-cgroups [152] ppid=85 runtime=0.000s --> +<!-- systemd-cgroups [159] ppid=85 runtime=0.000s --> +<!-- systemd-cgroups [160] ppid=85 runtime=0.000s --> +<!-- systemd-cgroups [174] ppid=85 runtime=0.000s --> +<!-- systemd-cgroups [207] ppid=85 runtime=0.000s --> +<!-- systemd-cgroups [221] ppid=85 runtime=0.000s --> +<!-- systemd-cgroups [228] ppid=85 runtime=0.000s --> +<!-- systemd-cgroups [229] ppid=85 runtime=0.000s --> +<!-- systemd-cgroups [238] ppid=85 runtime=0.000s --> +<!-- systemd-cgroups [251] ppid=85 runtime=0.000s --> +<!-- systemd-cgroups [280] ppid=85 runtime=0.000s --> + <line class="dot" x1="101.950" y1="370.000" x2="101.950" y2="360.000" /> +<!-- kworker/u:6 [86] ppid=2 runtime=0.000s --> +<!-- kpsmoused [87] ppid=2 runtime=0.000s --> +<!-- kworker/0:2 [88] ppid=2 runtime=0.001s --> +<!-- deferwq [89] ppid=2 runtime=0.000s --> +<!-- kworker/u:7 [90] ppid=2 runtime=0.000s --> +<!-- kworker/1:1 [91] ppid=2 runtime=0.001s --> + <rect class="ps" x="101.950" y="380.000" width="1993.545" height="20.000" /> + <rect class="wait" x="138.135" y="380.000" width="4.006" height="4.031" /> + <rect class="cpu" x="138.135" y="399.928" width="4.006" height="0.072" /> + <text x="106.950" y="394.000">kworker/1:1 [91] <tspan class="run">0.001s</tspan></text> + <line class="dot" x1="101.950" y1="390.000" x2="101.950" y2="390.000" /> + +<!-- kworker/2:1 [92] ppid=2 runtime=0.113s --> + <rect class="ps" x="101.950" y="400.000" width="1993.545" height="20.000" /> + <rect class="wait" x="142.141" y="400.000" width="4.002" height="4.112" /> + <rect class="cpu" x="142.141" y="419.732" width="4.002" height="0.268" /> + <rect class="wait" x="146.144" y="400.000" width="4.009" height="0.003" /> + <rect class="cpu" x="146.144" y="416.355" width="4.009" height="3.645" /> + <rect class="wait" x="154.163" y="400.000" width="4.008" height="0.044" /> + <rect class="cpu" x="154.163" y="416.768" width="4.008" height="3.232" /> + <rect class="wait" x="182.238" y="400.000" width="4.006" height="4.286" /> + <rect class="cpu" x="182.238" y="419.986" width="4.006" height="0.014" /> + <rect class="wait" x="266.386" y="400.000" width="4.007" height="9.856" /> + <rect class="cpu" x="266.386" y="419.736" width="4.007" height="0.264" /> + <rect class="wait" x="274.400" y="400.000" width="4.007" height="12.927" /> + <rect class="cpu" x="274.400" y="419.996" width="4.007" height="0.004" /> + <rect class="wait" x="282.414" y="400.000" width="4.007" height="4.186" /> + <rect class="cpu" x="282.414" y="419.982" width="4.007" height="0.018" /> + <rect class="wait" x="294.434" y="400.000" width="4.007" height="3.034" /> + <rect class="cpu" x="294.434" y="419.991" width="4.007" height="0.009" /> + <rect class="wait" x="302.446" y="400.000" width="4.007" height="13.418" /> + <rect class="cpu" x="302.446" y="419.997" width="4.007" height="0.003" /> + <rect class="wait" x="314.468" y="400.000" width="4.008" height="6.690" /> + <rect class="cpu" x="314.468" y="419.182" width="4.008" height="0.818" /> + <rect class="wait" x="378.590" y="400.000" width="4.006" height="2.246" /> + <rect class="cpu" x="378.590" y="419.972" width="4.006" height="0.028" /> + <rect class="wait" x="390.610" y="400.000" width="4.006" height="13.151" /> + <rect class="cpu" x="390.610" y="410.570" width="4.006" height="9.430" /> + <rect class="wait" x="394.616" y="400.000" width="4.008" height="11.836" /> + <rect class="cpu" x="394.616" y="419.999" width="4.008" height="0.001" /> + <rect class="wait" x="546.911" y="400.000" width="4.006" height="0.000" /> + <rect class="cpu" x="546.911" y="410.176" width="4.006" height="9.824" /> + <rect class="wait" x="550.917" y="400.000" width="4.006" height="13.492" /> + <rect class="cpu" x="550.917" y="407.361" width="4.006" height="12.639" /> + <rect class="wait" x="554.922" y="400.000" width="4.007" height="11.302" /> + <rect class="cpu" x="554.922" y="419.985" width="4.007" height="0.015" /> + <rect class="wait" x="578.966" y="400.000" width="4.007" height="2.728" /> + <rect class="cpu" x="578.966" y="419.952" width="4.007" height="0.048" /> + <rect class="wait" x="719.258" y="400.000" width="4.007" height="2.010" /> + <rect class="cpu" x="719.258" y="419.989" width="4.007" height="0.011" /> + <rect class="wait" x="759.350" y="400.000" width="4.009" height="2.016" /> + <rect class="cpu" x="759.350" y="419.991" width="4.009" height="0.009" /> + <rect class="wait" x="867.570" y="400.000" width="4.015" height="5.188" /> + <rect class="cpu" x="867.570" y="419.982" width="4.015" height="0.018" /> + <rect class="wait" x="919.664" y="400.000" width="4.007" height="2.016" /> + <rect class="cpu" x="919.664" y="419.977" width="4.007" height="0.023" /> + <text x="106.950" y="414.000">kworker/2:1 [92] <tspan class="run">0.113s</tspan></text> + <line class="dot" x1="101.950" y1="410.000" x2="101.950" y2="410.000" /> + +<!-- kworker/3:1 [93] ppid=2 runtime=0.106s --> + <rect class="ps" x="101.950" y="420.000" width="1993.545" height="20.000" /> + <rect class="wait" x="138.135" y="420.000" width="4.006" height="5.374" /> + <rect class="cpu" x="138.135" y="435.145" width="4.006" height="4.855" /> + <rect class="wait" x="142.141" y="420.000" width="4.002" height="4.336" /> + <rect class="cpu" x="142.141" y="439.594" width="4.002" height="0.406" /> + <rect class="wait" x="146.144" y="420.000" width="4.009" height="0.025" /> + <rect class="cpu" x="146.144" y="432.660" width="4.009" height="7.340" /> + <rect class="wait" x="182.238" y="420.000" width="4.006" height="2.518" /> + <rect class="cpu" x="182.238" y="439.964" width="4.006" height="0.036" /> + <rect class="wait" x="210.280" y="420.000" width="4.006" height="0.001" /> + <rect class="cpu" x="210.280" y="437.384" width="4.006" height="2.616" /> + <rect class="wait" x="214.286" y="420.000" width="4.007" height="16.584" /> + <rect class="cpu" x="214.286" y="438.024" width="4.007" height="1.976" /> + <rect class="wait" x="270.393" y="420.000" width="4.007" height="13.615" /> + <rect class="cpu" x="270.393" y="439.990" width="4.007" height="0.010" /> + <rect class="wait" x="278.406" y="420.000" width="4.008" height="11.688" /> + <rect class="cpu" x="278.406" y="439.462" width="4.008" height="0.538" /> + <rect class="wait" x="282.414" y="420.000" width="4.007" height="4.112" /> + <rect class="cpu" x="282.414" y="439.988" width="4.007" height="0.012" /> + <rect class="wait" x="306.453" y="420.000" width="4.006" height="11.390" /> + <rect class="cpu" x="306.453" y="427.923" width="4.006" height="12.077" /> + <rect class="wait" x="310.459" y="420.000" width="4.009" height="0.005" /> + <rect class="cpu" x="310.459" y="429.946" width="4.009" height="10.054" /> + <rect class="wait" x="314.468" y="420.000" width="4.008" height="2.143" /> + <rect class="cpu" x="314.468" y="439.974" width="4.008" height="0.026" /> + <rect class="wait" x="382.596" y="420.000" width="4.007" height="3.109" /> + <rect class="cpu" x="382.596" y="439.981" width="4.007" height="0.019" /> + <text x="106.950" y="434.000">kworker/3:1 [93] <tspan class="run">0.106s</tspan></text> + <line class="dot" x1="101.950" y1="430.000" x2="101.950" y2="430.000" /> + +<!-- kworker/u:8 [94] ppid=2 runtime=0.000s --> +<!-- kworker/0:1H [95] ppid=2 runtime=0.062s --> + <rect class="ps" x="101.950" y="440.000" width="1993.545" height="20.000" /> + <rect class="wait" x="134.013" y="440.000" width="4.123" height="0.929" /> + <rect class="cpu" x="134.013" y="456.410" width="4.123" height="3.590" /> + <rect class="wait" x="186.244" y="440.000" width="4.006" height="13.497" /> + <rect class="cpu" x="186.244" y="459.997" width="4.006" height="0.003" /> + <rect class="wait" x="190.250" y="440.000" width="4.006" height="0.000" /> + <rect class="cpu" x="190.250" y="446.588" width="4.006" height="13.412" /> + <rect class="wait" x="194.256" y="440.000" width="4.006" height="12.999" /> + <rect class="cpu" x="194.256" y="459.997" width="4.006" height="0.003" /> + <rect class="wait" x="206.275" y="440.000" width="4.006" height="0.005" /> + <rect class="cpu" x="206.275" y="457.371" width="4.006" height="2.629" /> + <rect class="wait" x="238.335" y="440.000" width="4.009" height="6.569" /> + <rect class="cpu" x="238.335" y="459.982" width="4.009" height="0.018" /> + <rect class="wait" x="250.358" y="440.000" width="4.006" height="13.314" /> + <rect class="cpu" x="250.358" y="459.994" width="4.006" height="0.006" /> + <rect class="wait" x="258.369" y="440.000" width="4.008" height="11.954" /> + <rect class="cpu" x="258.369" y="459.996" width="4.008" height="0.004" /> + <rect class="wait" x="298.441" y="440.000" width="4.006" height="3.614" /> + <rect class="cpu" x="298.441" y="457.824" width="4.006" height="2.176" /> + <text x="106.950" y="454.000">kworker/0:1H [95] <tspan class="run">0.062s</tspan></text> + <line class="dot" x1="101.950" y1="450.000" x2="101.950" y2="450.000" /> + +<!-- jbd2/sda2-8 [96] ppid=2 runtime=0.003s --> + <rect class="ps" x="101.950" y="460.000" width="1993.545" height="20.000" /> + <text x="106.950" y="474.000">jbd2/sda2-8 [96] <tspan class="run">0.003s</tspan></text> + <line class="dot" x1="101.950" y1="470.000" x2="101.950" y2="470.000" /> + +<!-- ext4-dio-unwrit [97] ppid=2 runtime=0.000s --> +<!-- kworker/3:2 [109] ppid=2 runtime=0.000s --> +<!-- kauditd [114] ppid=2 runtime=0.000s --> +<!-- kworker/1:2 [120] ppid=2 runtime=0.031s --> + <rect class="ps" x="134.013" y="480.000" width="1961.482" height="20.000" /> + <rect class="wait" x="166.186" y="480.000" width="4.006" height="20.000" /> + <rect class="cpu" x="166.186" y="499.992" width="4.006" height="0.008" /> + <rect class="wait" x="190.250" y="480.000" width="4.006" height="9.124" /> + <rect class="cpu" x="190.250" y="499.986" width="4.006" height="0.014" /> + <rect class="wait" x="250.358" y="480.000" width="4.006" height="13.100" /> + <rect class="cpu" x="250.358" y="499.998" width="4.006" height="0.002" /> + <rect class="wait" x="254.363" y="480.000" width="4.006" height="13.279" /> + <rect class="cpu" x="254.363" y="499.995" width="4.006" height="0.005" /> + <rect class="wait" x="422.684" y="480.000" width="4.012" height="13.598" /> + <rect class="cpu" x="422.684" y="499.992" width="4.012" height="0.008" /> + <rect class="wait" x="502.838" y="480.000" width="4.006" height="0.031" /> + <rect class="cpu" x="502.838" y="495.462" width="4.006" height="4.538" /> + <rect class="wait" x="514.858" y="480.000" width="4.006" height="3.162" /> + <rect class="cpu" x="514.858" y="499.988" width="4.006" height="0.012" /> + <rect class="wait" x="522.870" y="480.000" width="4.006" height="2.515" /> + <rect class="cpu" x="522.870" y="499.974" width="4.006" height="0.026" /> + <rect class="wait" x="578.966" y="480.000" width="4.007" height="5.913" /> + <rect class="cpu" x="578.966" y="499.982" width="4.007" height="0.018" /> + <rect class="wait" x="719.258" y="480.000" width="4.007" height="3.061" /> + <rect class="cpu" x="719.258" y="499.987" width="4.007" height="0.013" /> + <rect class="wait" x="743.310" y="480.000" width="4.013" height="2.987" /> + <rect class="cpu" x="743.310" y="499.989" width="4.013" height="0.011" /> + <text x="139.013" y="494.000">kworker/1:2 [120] <tspan class="run">0.031s</tspan></text> + <line class="dot" x1="134.013" y1="490.000" x2="101.950" y2="490.000" /> + +<!-- kworker/2:2 [155] ppid=2 runtime=0.001s --> +<!-- irq/48-mei [156] ppid=2 runtime=0.000s --> +<!-- ktpacpid [158] ppid=2 runtime=0.000s --> +<!-- kworker/2:1H [173] ppid=2 runtime=0.000s --> +<!-- cfg80211 [179] ppid=2 runtime=0.000s --> +<!-- cryptomgr_test [184] ppid=2 runtime=0.000s --> +<!-- kworker/1:3 [198] ppid=2 runtime=0.000s --> +<!-- kvm-irqfd-clean [200] ppid=2 runtime=0.000s --> +<!-- kworker/1:1H [205] ppid=2 runtime=0.000s --> +<!-- iwlwifi [208] ppid=2 runtime=0.000s --> +<!-- kworker/3:1H [250] ppid=2 runtime=0.000s --> +<!-- hd-audio0 [288] ppid=2 runtime=0.000s --> +<!-- jbd2/sda4-8 [349] ppid=2 runtime=0.000s --> +<!-- ext4-dio-unwrit [350] ppid=2 runtime=0.000s --> +<!-- flush-8:0 [592] ppid=2 runtime=0.000s --> + <line class="dot" x1="101.950" y1="490.000" x2="101.950" y2="40.000" /> +<!-- systemd-bootcha [98] ppid=1 runtime=1.021s --> + <rect class="ps" x="101.950" y="500.000" width="1993.545" height="20.000" /> + <rect class="wait" x="590.990" y="500.000" width="4.008" height="0.010" /> + <rect class="cpu" x="590.990" y="517.983" width="4.008" height="2.017" /> + <rect class="wait" x="594.998" y="500.000" width="4.010" height="0.013" /> + <rect class="cpu" x="594.998" y="517.946" width="4.010" height="2.054" /> + <text x="106.950" y="514.000">systemd-bootcha [98] <tspan class="run">1.021s</tspan></text> + <line class="dot" x1="101.950" y1="510.000" x2="101.950" y2="510.000" /> + +<!-- systemd-readahe [104] ppid=1 runtime=0.309s --> + <rect class="ps" x="117.986" y="520.000" width="1086.475" height="20.000" /> + <rect class="wait" x="117.986" y="520.000" width="4.007" height="0.041" /> + <rect class="cpu" x="117.986" y="537.927" width="4.007" height="2.073" /> + <rect class="wait" x="134.013" y="520.000" width="4.123" height="2.594" /> + <rect class="cpu" x="134.013" y="539.288" width="4.123" height="0.712" /> + <rect class="wait" x="138.135" y="520.000" width="4.006" height="2.536" /> + <rect class="cpu" x="138.135" y="538.624" width="4.006" height="1.376" /> + <rect class="wait" x="146.144" y="520.000" width="4.009" height="1.168" /> + <rect class="cpu" x="146.144" y="537.872" width="4.009" height="2.128" /> + <rect class="wait" x="202.268" y="520.000" width="4.007" height="2.118" /> + <rect class="cpu" x="202.268" y="538.636" width="4.007" height="1.364" /> + <rect class="wait" x="326.491" y="520.000" width="4.009" height="0.033" /> + <rect class="cpu" x="326.491" y="530.678" width="4.009" height="9.322" /> + <rect class="wait" x="330.500" y="520.000" width="4.006" height="0.118" /> + <rect class="cpu" x="330.500" y="533.617" width="4.006" height="6.383" /> + <rect class="wait" x="342.521" y="520.000" width="4.008" height="0.054" /> + <rect class="cpu" x="342.521" y="536.914" width="4.008" height="3.086" /> + <rect class="wait" x="358.555" y="520.000" width="4.007" height="0.232" /> + <rect class="cpu" x="358.555" y="537.349" width="4.007" height="2.651" /> + <rect class="wait" x="362.562" y="520.000" width="4.007" height="0.014" /> + <rect class="cpu" x="362.562" y="537.119" width="4.007" height="2.881" /> + <rect class="wait" x="370.576" y="520.000" width="4.008" height="0.005" /> + <rect class="cpu" x="370.576" y="537.520" width="4.008" height="2.480" /> + <rect class="wait" x="374.584" y="520.000" width="4.006" height="0.301" /> + <rect class="cpu" x="374.584" y="537.880" width="4.006" height="2.120" /> + <rect class="wait" x="378.590" y="520.000" width="4.006" height="4.068" /> + <rect class="cpu" x="378.590" y="537.711" width="4.006" height="2.289" /> + <rect class="wait" x="382.596" y="520.000" width="4.007" height="2.960" /> + <rect class="cpu" x="382.596" y="538.699" width="4.007" height="1.301" /> + <rect class="wait" x="402.645" y="520.000" width="4.011" height="1.604" /> + <rect class="cpu" x="402.645" y="536.663" width="4.011" height="3.337" /> + <rect class="wait" x="410.663" y="520.000" width="4.007" height="0.012" /> + <rect class="cpu" x="410.663" y="537.448" width="4.007" height="2.552" /> + <rect class="wait" x="426.696" y="520.000" width="4.006" height="0.049" /> + <rect class="cpu" x="426.696" y="537.566" width="4.006" height="2.434" /> + <rect class="wait" x="486.814" y="520.000" width="4.006" height="2.925" /> + <rect class="cpu" x="486.814" y="538.142" width="4.006" height="1.858" /> + <rect class="wait" x="490.819" y="520.000" width="4.006" height="2.362" /> + <rect class="cpu" x="490.819" y="538.664" width="4.006" height="1.336" /> + <rect class="wait" x="502.838" y="520.000" width="4.006" height="0.011" /> + <rect class="cpu" x="502.838" y="536.810" width="4.006" height="3.190" /> + <rect class="wait" x="510.850" y="520.000" width="4.008" height="7.818" /> + <rect class="cpu" x="510.850" y="538.538" width="4.008" height="1.462" /> + <rect class="wait" x="514.858" y="520.000" width="4.006" height="9.283" /> + <rect class="cpu" x="514.858" y="538.086" width="4.006" height="1.914" /> + <rect class="wait" x="518.864" y="520.000" width="4.006" height="3.837" /> + <rect class="cpu" x="518.864" y="539.119" width="4.006" height="0.881" /> + <rect class="wait" x="522.870" y="520.000" width="4.006" height="4.877" /> + <rect class="cpu" x="522.870" y="539.223" width="4.006" height="0.777" /> + <rect class="wait" x="526.876" y="520.000" width="4.007" height="5.918" /> + <rect class="cpu" x="526.876" y="537.402" width="4.007" height="2.598" /> + <rect class="wait" x="534.889" y="520.000" width="4.006" height="1.805" /> + <rect class="cpu" x="534.889" y="537.794" width="4.006" height="2.206" /> + <rect class="wait" x="538.895" y="520.000" width="4.007" height="1.347" /> + <rect class="cpu" x="538.895" y="536.630" width="4.007" height="3.370" /> + <rect class="wait" x="558.930" y="520.000" width="4.006" height="4.866" /> + <rect class="cpu" x="558.930" y="539.460" width="4.006" height="0.540" /> + <rect class="wait" x="639.084" y="520.000" width="4.006" height="0.038" /> + <rect class="cpu" x="639.084" y="537.918" width="4.006" height="2.082" /> + <text x="122.986" y="534.000">systemd-readahe [104] <tspan class="run">0.309s</tspan></text> + <line class="dot" x1="117.986" y1="530.000" x2="101.950" y2="530.000" /> + +<!-- systemd-readahe [105] ppid=1 runtime=0.095s --> + <rect class="ps" x="121.993" y="540.000" width="180.453" height="20.000" /> + <rect class="wait" x="166.186" y="540.000" width="4.006" height="0.283" /> + <rect class="cpu" x="166.186" y="556.846" width="4.006" height="3.154" /> + <rect class="wait" x="222.300" y="540.000" width="4.009" height="0.260" /> + <rect class="cpu" x="222.300" y="557.481" width="4.009" height="2.519" /> + <rect class="wait" x="242.344" y="540.000" width="4.006" height="0.294" /> + <rect class="cpu" x="242.344" y="557.778" width="4.006" height="2.222" /> + <rect class="wait" x="270.393" y="540.000" width="4.007" height="0.312" /> + <rect class="cpu" x="270.393" y="557.667" width="4.007" height="2.333" /> + <rect class="wait" x="278.406" y="540.000" width="4.008" height="0.284" /> + <rect class="cpu" x="278.406" y="557.876" width="4.008" height="2.124" /> + <rect class="wait" x="282.414" y="540.000" width="4.007" height="0.190" /> + <rect class="cpu" x="282.414" y="557.338" width="4.007" height="2.662" /> + <text x="126.993" y="554.000">systemd-readahe [105] <tspan class="run">0.095s</tspan></text> + <line class="dot" x1="121.993" y1="550.000" x2="101.950" y2="550.000" /> + +<!-- mount [106] ppid=1 runtime=0.004s --> + <rect class="ps" x="121.993" y="560.000" width="8.013" height="20.000" /> + <rect class="wait" x="121.993" y="560.000" width="4.007" height="0.237" /> + <rect class="cpu" x="121.993" y="577.876" width="4.007" height="2.124" /> + <text x="135.006" y="574.000">mount [106] <tspan class="run">0.004s</tspan></text> + <line class="dot" x1="121.993" y1="570.000" x2="101.950" y2="570.000" /> + +<!-- mount [107] ppid=1 runtime=0.000s --> +<!-- udevadm [108] ppid=1 runtime=0.004s --> + <rect class="ps" x="126.000" y="580.000" width="4.006" height="20.000" /> + <text x="135.006" y="594.000">udevadm [108] <tspan class="run">0.004s</tspan></text> + <line class="dot" x1="126.000" y1="590.000" x2="101.950" y2="590.000" /> + +<!-- systemd-journal [112] ppid=1 runtime=0.437s --> + <rect class="ps" x="126.000" y="600.000" width="1969.494" height="20.000" /> + <rect class="wait" x="126.000" y="600.000" width="4.006" height="0.068" /> + <rect class="cpu" x="126.000" y="608.253" width="4.006" height="11.747" /> + <rect class="wait" x="130.006" y="600.000" width="4.007" height="0.035" /> + <rect class="cpu" x="130.006" y="610.010" width="4.007" height="9.990" /> + <rect class="wait" x="134.013" y="600.000" width="4.123" height="2.238" /> + <rect class="cpu" x="134.013" y="619.044" width="4.123" height="0.956" /> + <rect class="wait" x="138.135" y="600.000" width="4.006" height="0.279" /> + <rect class="cpu" x="138.135" y="617.934" width="4.006" height="2.066" /> + <rect class="wait" x="178.214" y="600.000" width="4.024" height="0.582" /> + <rect class="cpu" x="178.214" y="613.359" width="4.024" height="6.641" /> + <rect class="wait" x="186.244" y="600.000" width="4.006" height="0.275" /> + <rect class="cpu" x="186.244" y="616.954" width="4.006" height="3.046" /> + <rect class="wait" x="190.250" y="600.000" width="4.006" height="0.135" /> + <rect class="cpu" x="190.250" y="611.051" width="4.006" height="8.949" /> + <rect class="wait" x="194.256" y="600.000" width="4.006" height="0.956" /> + <rect class="cpu" x="194.256" y="609.990" width="4.006" height="10.010" /> + <rect class="wait" x="198.262" y="600.000" width="4.006" height="0.467" /> + <rect class="cpu" x="198.262" y="605.417" width="4.006" height="14.583" /> + <rect class="wait" x="202.268" y="600.000" width="4.007" height="0.829" /> + <rect class="cpu" x="202.268" y="611.721" width="4.007" height="8.279" /> + <rect class="wait" x="206.275" y="600.000" width="4.006" height="0.909" /> + <rect class="cpu" x="206.275" y="601.494" width="4.006" height="18.506" /> + <rect class="wait" x="218.294" y="600.000" width="4.007" height="0.033" /> + <rect class="cpu" x="218.294" y="617.830" width="4.007" height="2.170" /> + <rect class="wait" x="238.335" y="600.000" width="4.009" height="0.096" /> + <rect class="cpu" x="238.335" y="616.199" width="4.009" height="3.801" /> + <rect class="wait" x="294.434" y="600.000" width="4.007" height="0.021" /> + <rect class="cpu" x="294.434" y="617.047" width="4.007" height="2.953" /> + <rect class="wait" x="314.468" y="600.000" width="4.008" height="0.033" /> + <rect class="cpu" x="314.468" y="611.535" width="4.008" height="8.465" /> + <rect class="wait" x="318.476" y="600.000" width="4.007" height="0.033" /> + <rect class="cpu" x="318.476" y="612.542" width="4.007" height="7.458" /> + <rect class="wait" x="322.483" y="600.000" width="4.008" height="0.017" /> + <rect class="cpu" x="322.483" y="617.477" width="4.008" height="2.523" /> + <rect class="wait" x="330.500" y="600.000" width="4.006" height="0.015" /> + <rect class="cpu" x="330.500" y="617.804" width="4.006" height="2.196" /> + <rect class="wait" x="334.506" y="600.000" width="4.008" height="0.038" /> + <rect class="cpu" x="334.506" y="611.702" width="4.008" height="8.298" /> + <rect class="wait" x="338.513" y="600.000" width="4.008" height="0.122" /> + <rect class="cpu" x="338.513" y="610.454" width="4.008" height="9.546" /> + <rect class="wait" x="342.521" y="600.000" width="4.008" height="0.093" /> + <rect class="cpu" x="342.521" y="614.582" width="4.008" height="5.418" /> + <rect class="wait" x="378.590" y="600.000" width="4.006" height="0.676" /> + <rect class="cpu" x="378.590" y="615.514" width="4.006" height="4.486" /> + <rect class="wait" x="382.596" y="600.000" width="4.007" height="1.309" /> + <rect class="cpu" x="382.596" y="614.483" width="4.007" height="5.517" /> + <rect class="wait" x="406.656" y="600.000" width="4.007" height="0.338" /> + <rect class="cpu" x="406.656" y="617.930" width="4.007" height="2.070" /> + <rect class="wait" x="482.808" y="600.000" width="4.006" height="0.033" /> + <rect class="cpu" x="482.808" y="617.991" width="4.006" height="2.009" /> + <rect class="wait" x="498.831" y="600.000" width="4.006" height="0.010" /> + <rect class="cpu" x="498.831" y="617.851" width="4.006" height="2.149" /> + <rect class="wait" x="510.850" y="600.000" width="4.008" height="1.178" /> + <rect class="cpu" x="510.850" y="617.355" width="4.008" height="2.645" /> + <rect class="wait" x="522.870" y="600.000" width="4.006" height="2.382" /> + <rect class="cpu" x="522.870" y="618.588" width="4.006" height="1.412" /> + <rect class="wait" x="1397.138" y="600.000" width="4.013" height="0.051" /> + <rect class="cpu" x="1397.138" y="617.443" width="4.013" height="2.557" /> + <rect class="wait" x="1999.160" y="600.000" width="4.014" height="0.021" /> + <rect class="cpu" x="1999.160" y="617.486" width="4.014" height="2.514" /> + <text x="131.000" y="614.000">systemd-journal [112] <tspan class="run">0.437s</tspan></text> + <line class="dot" x1="126.000" y1="610.000" x2="101.950" y2="610.000" /> + +<!-- mount [115] ppid=1 runtime=0.000s --> +<!-- systemd-udevd [116] ppid=1 runtime=0.065s --> + <rect class="ps" x="130.006" y="620.000" width="1965.489" height="20.000" /> + <rect class="wait" x="130.006" y="620.000" width="4.007" height="1.917" /> + <rect class="cpu" x="130.006" y="627.819" width="4.007" height="12.181" /> + <rect class="wait" x="134.013" y="620.000" width="4.123" height="9.297" /> + <rect class="cpu" x="134.013" y="637.246" width="4.123" height="2.754" /> + <rect class="wait" x="138.135" y="620.000" width="4.006" height="19.221" /> + <rect class="cpu" x="138.135" y="636.788" width="4.006" height="3.212" /> + <rect class="wait" x="142.141" y="620.000" width="4.002" height="13.318" /> + <rect class="cpu" x="142.141" y="635.582" width="4.002" height="4.418" /> + <rect class="wait" x="146.144" y="620.000" width="4.009" height="3.195" /> + <rect class="cpu" x="146.144" y="639.272" width="4.009" height="0.728" /> + <rect class="wait" x="442.730" y="620.000" width="4.010" height="3.776" /> + <rect class="cpu" x="442.730" y="639.203" width="4.010" height="0.797" /> + <text x="135.006" y="634.000">systemd-udevd [116] <tspan class="run">0.065s</tspan></text> + <line class="dot" x1="130.006" y1="630.000" x2="101.950" y2="630.000" /> + +<!-- systemd-udevd [121] ppid=116 runtime=0.067s --> + <rect class="ps" x="134.013" y="640.000" width="637.368" height="20.000" /> + <rect class="wait" x="134.013" y="640.000" width="4.123" height="5.009" /> + <rect class="cpu" x="134.013" y="655.796" width="4.123" height="4.204" /> + <rect class="wait" x="138.135" y="640.000" width="4.006" height="4.355" /> + <rect class="cpu" x="138.135" y="658.270" width="4.006" height="1.730" /> + <rect class="wait" x="142.141" y="640.000" width="4.002" height="3.033" /> + <rect class="cpu" x="142.141" y="654.041" width="4.002" height="5.959" /> + <rect class="wait" x="154.163" y="640.000" width="4.008" height="2.876" /> + <rect class="cpu" x="154.163" y="657.139" width="4.008" height="2.861" /> + <rect class="wait" x="242.344" y="640.000" width="4.006" height="1.599" /> + <rect class="cpu" x="242.344" y="656.950" width="4.006" height="3.050" /> + <rect class="wait" x="354.547" y="640.000" width="4.008" height="0.592" /> + <rect class="cpu" x="354.547" y="657.429" width="4.008" height="2.571" /> + <rect class="wait" x="438.722" y="640.000" width="4.008" height="3.638" /> + <rect class="cpu" x="438.722" y="658.611" width="4.008" height="1.389" /> + <rect class="wait" x="442.730" y="640.000" width="4.010" height="1.980" /> + <rect class="cpu" x="442.730" y="655.453" width="4.010" height="4.547" /> + <rect class="wait" x="446.740" y="640.000" width="4.005" height="0.525" /> + <rect class="cpu" x="446.740" y="657.917" width="4.005" height="2.083" /> + <text x="139.013" y="654.000">systemd-udevd [121] <tspan class="run">0.067s</tspan></text> + <line class="dot" x1="134.013" y1="650.000" x2="130.006" y2="650.000" /> + +<!-- rename_device [199] ppid=121 runtime=0.000s --> + <line class="dot" x1="134.013" y1="650.000" x2="134.013" y2="660.000" /> +<!-- systemd-udevd [122] ppid=116 runtime=0.050s --> + <rect class="ps" x="134.013" y="660.000" width="637.368" height="20.000" /> + <rect class="wait" x="134.013" y="660.000" width="4.123" height="3.606" /> + <rect class="cpu" x="134.013" y="676.766" width="4.123" height="3.234" /> + <rect class="wait" x="138.135" y="660.000" width="4.006" height="6.155" /> + <rect class="cpu" x="138.135" y="675.844" width="4.006" height="4.156" /> + <rect class="wait" x="142.141" y="660.000" width="4.002" height="4.987" /> + <rect class="cpu" x="142.141" y="677.567" width="4.002" height="2.433" /> + <rect class="wait" x="154.163" y="660.000" width="4.008" height="1.422" /> + <rect class="cpu" x="154.163" y="677.226" width="4.008" height="2.774" /> + <rect class="wait" x="158.170" y="660.000" width="4.007" height="0.158" /> + <rect class="cpu" x="158.170" y="676.233" width="4.007" height="3.767" /> + <rect class="wait" x="442.730" y="660.000" width="4.010" height="3.350" /> + <rect class="cpu" x="442.730" y="678.267" width="4.010" height="1.733" /> + <text x="139.013" y="674.000">systemd-udevd [122] <tspan class="run">0.050s</tspan></text> + <line class="dot" x1="134.013" y1="670.000" x2="130.006" y2="670.000" /> + +<!-- alsactl [463] ppid=122 runtime=0.000s --> + <line class="dot" x1="134.013" y1="670.000" x2="134.013" y2="680.000" /> +<!-- systemd-udevd [123] ppid=116 runtime=0.042s --> + <rect class="ps" x="134.013" y="680.000" width="637.368" height="20.000" /> + <rect class="wait" x="134.013" y="680.000" width="4.123" height="1.311" /> + <rect class="cpu" x="134.013" y="697.235" width="4.123" height="2.765" /> + <rect class="wait" x="138.135" y="680.000" width="4.006" height="9.171" /> + <rect class="cpu" x="138.135" y="696.556" width="4.006" height="3.444" /> + <rect class="wait" x="142.141" y="680.000" width="4.002" height="5.084" /> + <rect class="cpu" x="142.141" y="698.403" width="4.002" height="1.597" /> + <rect class="wait" x="146.144" y="680.000" width="4.009" height="3.637" /> + <rect class="cpu" x="146.144" y="697.536" width="4.009" height="2.464" /> + <rect class="wait" x="154.163" y="680.000" width="4.008" height="4.055" /> + <rect class="cpu" x="154.163" y="698.601" width="4.008" height="1.399" /> + <rect class="wait" x="438.722" y="680.000" width="4.008" height="0.517" /> + <rect class="cpu" x="438.722" y="696.352" width="4.008" height="3.648" /> + <rect class="wait" x="442.730" y="680.000" width="4.010" height="0.574" /> + <rect class="cpu" x="442.730" y="697.964" width="4.010" height="2.036" /> + <text x="139.013" y="694.000">systemd-udevd [123] <tspan class="run">0.042s</tspan></text> + <line class="dot" x1="134.013" y1="690.000" x2="130.006" y2="690.000" /> + +<!-- systemd-udevd [124] ppid=116 runtime=0.013s --> + <rect class="ps" x="134.013" y="700.000" width="637.368" height="20.000" /> + <rect class="wait" x="138.135" y="700.000" width="4.006" height="5.145" /> + <rect class="cpu" x="138.135" y="718.239" width="4.006" height="1.761" /> + <text x="139.013" y="714.000">systemd-udevd [124] <tspan class="run">0.013s</tspan></text> + <line class="dot" x1="134.013" y1="710.000" x2="130.006" y2="710.000" /> + +<!-- adb [157] ppid=124 runtime=0.000s --> +<!-- adb [175] ppid=157 runtime=0.000s --> + <line class="dot" x1="134.013" y1="710.000" x2="134.013" y2="720.000" /> +<!-- systemd-udevd [461] ppid=124 runtime=0.000s --> + <line class="dot" x1="134.013" y1="710.000" x2="134.013" y2="720.000" /> +<!-- systemd-udevd [125] ppid=116 runtime=0.058s --> + <rect class="ps" x="134.013" y="720.000" width="637.368" height="20.000" /> + <rect class="wait" x="134.013" y="720.000" width="4.123" height="4.002" /> + <rect class="cpu" x="134.013" y="737.900" width="4.123" height="2.100" /> + <rect class="wait" x="138.135" y="720.000" width="4.006" height="5.437" /> + <rect class="cpu" x="138.135" y="738.396" width="4.006" height="1.604" /> + <rect class="wait" x="146.144" y="720.000" width="4.009" height="0.286" /> + <rect class="cpu" x="146.144" y="731.838" width="4.009" height="8.162" /> + <rect class="wait" x="154.163" y="720.000" width="4.008" height="1.303" /> + <rect class="cpu" x="154.163" y="734.229" width="4.008" height="5.771" /> + <rect class="wait" x="158.170" y="720.000" width="4.007" height="5.263" /> + <rect class="cpu" x="158.170" y="735.037" width="4.007" height="4.963" /> + <rect class="wait" x="442.730" y="720.000" width="4.010" height="2.787" /> + <rect class="cpu" x="442.730" y="737.488" width="4.010" height="2.512" /> + <text x="139.013" y="734.000">systemd-udevd [125] <tspan class="run">0.058s</tspan></text> + <line class="dot" x1="134.013" y1="730.000" x2="130.006" y2="730.000" /> + +<!-- systemd-udevd [126] ppid=116 runtime=0.032s --> + <rect class="ps" x="134.013" y="740.000" width="637.368" height="20.000" /> + <rect class="wait" x="134.013" y="740.000" width="4.123" height="1.886" /> + <rect class="cpu" x="134.013" y="757.841" width="4.123" height="2.159" /> + <rect class="wait" x="138.135" y="740.000" width="4.006" height="5.295" /> + <rect class="cpu" x="138.135" y="758.946" width="4.006" height="1.054" /> + <rect class="wait" x="242.344" y="740.000" width="4.006" height="2.172" /> + <rect class="cpu" x="242.344" y="751.229" width="4.006" height="8.771" /> + <rect class="wait" x="442.730" y="740.000" width="4.010" height="2.412" /> + <rect class="cpu" x="442.730" y="757.995" width="4.010" height="2.005" /> + <text x="139.013" y="754.000">systemd-udevd [126] <tspan class="run">0.032s</tspan></text> + <line class="dot" x1="134.013" y1="750.000" x2="130.006" y2="750.000" /> + +<!-- sh [171] ppid=126 runtime=0.001s --> + <line class="dot" x1="134.013" y1="750.000" x2="134.013" y2="760.000" /> +<!-- modprobe [197] ppid=171 runtime=0.000s --> + <line class="dot" x1="134.013" y1="750.000" x2="134.013" y2="760.000" /> +<!-- systemd-udevd [127] ppid=116 runtime=0.102s --> + <rect class="ps" x="134.013" y="760.000" width="637.368" height="20.000" /> + <rect class="wait" x="134.013" y="760.000" width="4.123" height="1.870" /> + <rect class="cpu" x="134.013" y="777.423" width="4.123" height="2.577" /> + <rect class="wait" x="138.135" y="760.000" width="4.006" height="11.694" /> + <rect class="cpu" x="138.135" y="776.680" width="4.006" height="3.320" /> + <rect class="wait" x="166.186" y="760.000" width="4.006" height="20.000" /> + <rect class="cpu" x="166.186" y="778.785" width="4.006" height="1.215" /> + <rect class="wait" x="174.198" y="760.000" width="4.016" height="0.824" /> + <rect class="cpu" x="174.198" y="769.344" width="4.016" height="10.656" /> + <rect class="wait" x="182.238" y="760.000" width="4.006" height="0.553" /> + <rect class="cpu" x="182.238" y="775.987" width="4.006" height="4.013" /> + <rect class="wait" x="186.244" y="760.000" width="4.006" height="13.495" /> + <rect class="cpu" x="186.244" y="775.441" width="4.006" height="4.559" /> + <rect class="wait" x="190.250" y="760.000" width="4.006" height="20.000" /> + <rect class="cpu" x="190.250" y="778.910" width="4.006" height="1.090" /> + <rect class="wait" x="194.256" y="760.000" width="4.006" height="12.998" /> + <rect class="cpu" x="194.256" y="774.931" width="4.006" height="5.069" /> + <rect class="wait" x="198.262" y="760.000" width="4.006" height="0.668" /> + <rect class="cpu" x="198.262" y="776.159" width="4.006" height="3.841" /> + <rect class="wait" x="202.268" y="760.000" width="4.007" height="2.419" /> + <rect class="cpu" x="202.268" y="779.544" width="4.007" height="0.456" /> + <rect class="wait" x="238.335" y="760.000" width="4.009" height="1.722" /> + <rect class="cpu" x="238.335" y="774.264" width="4.009" height="5.736" /> + <rect class="wait" x="442.730" y="760.000" width="4.010" height="2.087" /> + <rect class="cpu" x="442.730" y="778.585" width="4.010" height="1.415" /> + <text x="139.013" y="774.000">systemd-udevd [127] <tspan class="run">0.102s</tspan></text> + <line class="dot" x1="134.013" y1="770.000" x2="130.006" y2="770.000" /> + +<!-- systemd-udevd [128] ppid=116 runtime=0.028s --> + <rect class="ps" x="134.013" y="780.000" width="637.368" height="20.000" /> + <rect class="wait" x="138.135" y="780.000" width="4.006" height="2.001" /> + <rect class="cpu" x="138.135" y="797.400" width="4.006" height="2.600" /> + <rect class="wait" x="146.144" y="780.000" width="4.009" height="1.675" /> + <rect class="cpu" x="146.144" y="795.699" width="4.009" height="4.301" /> + <rect class="wait" x="154.163" y="780.000" width="4.008" height="0.039" /> + <rect class="cpu" x="154.163" y="796.633" width="4.008" height="3.367" /> + <text x="139.013" y="794.000">systemd-udevd [128] <tspan class="run">0.028s</tspan></text> + <line class="dot" x1="134.013" y1="790.000" x2="130.006" y2="790.000" /> + +<!-- systemd-udevd [129] ppid=116 runtime=0.024s --> + <rect class="ps" x="134.013" y="800.000" width="637.368" height="20.000" /> + <rect class="wait" x="134.013" y="800.000" width="4.123" height="0.750" /> + <rect class="cpu" x="134.013" y="817.478" width="4.123" height="2.522" /> + <rect class="wait" x="138.135" y="800.000" width="4.006" height="4.903" /> + <rect class="cpu" x="138.135" y="818.204" width="4.006" height="1.796" /> + <rect class="wait" x="142.141" y="800.000" width="4.002" height="7.004" /> + <rect class="cpu" x="142.141" y="815.832" width="4.002" height="4.168" /> + <text x="139.013" y="814.000">systemd-udevd [129] <tspan class="run">0.024s</tspan></text> + <line class="dot" x1="134.013" y1="810.000" x2="130.006" y2="810.000" /> + +<!-- systemd-udevd [130] ppid=116 runtime=0.008s --> + <rect class="ps" x="134.013" y="820.000" width="637.368" height="20.000" /> + <rect class="wait" x="134.013" y="820.000" width="4.123" height="0.598" /> + <rect class="cpu" x="134.013" y="837.859" width="4.123" height="2.141" /> + <text x="139.013" y="834.000">systemd-udevd [130] <tspan class="run">0.008s</tspan></text> + <line class="dot" x1="134.013" y1="830.000" x2="130.006" y2="830.000" /> + +<!-- systemd-udevd [131] ppid=116 runtime=0.011s --> + <rect class="ps" x="134.013" y="840.000" width="637.368" height="20.000" /> + <rect class="wait" x="134.013" y="840.000" width="4.123" height="4.495" /> + <rect class="cpu" x="134.013" y="859.540" width="4.123" height="0.460" /> + <rect class="wait" x="146.144" y="840.000" width="4.009" height="2.106" /> + <rect class="cpu" x="146.144" y="859.087" width="4.009" height="0.913" /> + <text x="139.013" y="854.000">systemd-udevd [131] <tspan class="run">0.011s</tspan></text> + <line class="dot" x1="134.013" y1="850.000" x2="130.006" y2="850.000" /> + +<!-- cdrom_id [176] ppid=131 runtime=0.000s --> + <line class="dot" x1="134.013" y1="850.000" x2="134.013" y2="860.000" /> +<!-- systemd-udevd [132] ppid=116 runtime=0.004s --> + <rect class="ps" x="134.013" y="860.000" width="637.368" height="20.000" /> + <text x="139.013" y="874.000">systemd-udevd [132] <tspan class="run">0.004s</tspan></text> + <line class="dot" x1="134.013" y1="870.000" x2="130.006" y2="870.000" /> + +<!-- systemd-udevd [133] ppid=116 runtime=0.013s --> + <rect class="ps" x="134.013" y="880.000" width="637.368" height="20.000" /> + <rect class="wait" x="138.135" y="880.000" width="4.006" height="0.047" /> + <rect class="cpu" x="138.135" y="897.732" width="4.006" height="2.268" /> + <rect class="wait" x="146.144" y="880.000" width="4.009" height="2.300" /> + <rect class="cpu" x="146.144" y="899.235" width="4.009" height="0.765" /> + <text x="139.013" y="894.000">systemd-udevd [133] <tspan class="run">0.013s</tspan></text> + <line class="dot" x1="134.013" y1="890.000" x2="130.006" y2="890.000" /> + +<!-- rename_device [193] ppid=133 runtime=0.000s --> + <line class="dot" x1="134.013" y1="890.000" x2="134.013" y2="900.000" /> +<!-- systemd-udevd [134] ppid=116 runtime=0.020s --> + <rect class="ps" x="134.013" y="900.000" width="637.368" height="20.000" /> + <rect class="wait" x="138.135" y="900.000" width="4.006" height="1.310" /> + <rect class="cpu" x="138.135" y="917.729" width="4.006" height="2.271" /> + <rect class="wait" x="142.141" y="900.000" width="4.002" height="7.483" /> + <rect class="cpu" x="142.141" y="917.776" width="4.002" height="2.224" /> + <rect class="wait" x="154.163" y="900.000" width="4.008" height="5.006" /> + <rect class="cpu" x="154.163" y="918.831" width="4.008" height="1.169" /> + <text x="139.013" y="914.000">systemd-udevd [134] <tspan class="run">0.020s</tspan></text> + <line class="dot" x1="134.013" y1="910.000" x2="130.006" y2="910.000" /> + +<!-- systemd-udevd [135] ppid=116 runtime=0.014s --> + <rect class="ps" x="134.013" y="920.000" width="637.368" height="20.000" /> + <rect class="wait" x="142.141" y="920.000" width="4.002" height="1.546" /> + <rect class="cpu" x="142.141" y="935.543" width="4.002" height="4.457" /> + <text x="139.013" y="934.000">systemd-udevd [135] <tspan class="run">0.014s</tspan></text> + <line class="dot" x1="134.013" y1="930.000" x2="130.006" y2="930.000" /> + +<!-- alsactl [202] ppid=135 runtime=0.000s --> + <line class="dot" x1="134.013" y1="930.000" x2="134.013" y2="940.000" /> +<!-- systemd-udevd [136] ppid=116 runtime=0.014s --> + <rect class="ps" x="134.013" y="940.000" width="637.368" height="20.000" /> + <rect class="wait" x="142.141" y="940.000" width="4.002" height="0.268" /> + <rect class="cpu" x="142.141" y="956.396" width="4.002" height="3.604" /> + <rect class="wait" x="154.163" y="940.000" width="4.008" height="2.301" /> + <rect class="cpu" x="154.163" y="958.910" width="4.008" height="1.090" /> + <text x="139.013" y="954.000">systemd-udevd [136] <tspan class="run">0.014s</tspan></text> + <line class="dot" x1="134.013" y1="950.000" x2="130.006" y2="950.000" /> + +<!-- systemd-udevd [137] ppid=116 runtime=0.007s --> + <rect class="ps" x="134.013" y="960.000" width="637.368" height="20.000" /> + <text x="139.013" y="974.000">systemd-udevd [137] <tspan class="run">0.007s</tspan></text> + <line class="dot" x1="134.013" y1="970.000" x2="130.006" y2="970.000" /> + +<!-- keymap [203] ppid=137 runtime=0.000s --> + <line class="dot" x1="134.013" y1="970.000" x2="134.013" y2="980.000" /> +<!-- systemd-udevd [138] ppid=116 runtime=0.003s --> + <rect class="ps" x="134.013" y="980.000" width="637.368" height="20.000" /> + <text x="139.013" y="994.000">systemd-udevd [138] <tspan class="run">0.003s</tspan></text> + <line class="dot" x1="134.013" y1="990.000" x2="130.006" y2="990.000" /> + +<!-- systemd-udevd [139] ppid=116 runtime=0.001s --> + <rect class="ps" x="134.013" y="1000.000" width="637.368" height="20.000" /> + <text x="139.013" y="1014.000">systemd-udevd [139] <tspan class="run">0.001s</tspan></text> + <line class="dot" x1="134.013" y1="1010.000" x2="130.006" y2="1010.000" /> + +<!-- systemd-udevd [140] ppid=116 runtime=0.000s --> +<!-- systemd-udevd [141] ppid=116 runtime=0.000s --> +<!-- systemd-udevd [142] ppid=116 runtime=0.000s --> +<!-- systemd-udevd [143] ppid=116 runtime=0.000s --> +<!-- systemd-udevd [144] ppid=116 runtime=0.000s --> +<!-- systemd-udevd [145] ppid=116 runtime=0.000s --> +<!-- systemd-udevd [146] ppid=116 runtime=0.000s --> +<!-- systemd-udevd [147] ppid=116 runtime=0.000s --> +<!-- systemd-udevd [162] ppid=116 runtime=0.000s --> +<!-- systemd-udevd [163] ppid=116 runtime=0.000s --> +<!-- systemd-udevd [164] ppid=116 runtime=0.000s --> +<!-- systemd-udevd [165] ppid=116 runtime=0.000s --> +<!-- systemd-udevd [166] ppid=116 runtime=0.000s --> +<!-- systemd-udevd [167] ppid=116 runtime=0.000s --> +<!-- systemd-udevd [168] ppid=116 runtime=0.000s --> +<!-- systemd-udevd [169] ppid=116 runtime=0.000s --> +<!-- systemd-udevd [170] ppid=116 runtime=0.000s --> + <line class="dot" x1="130.006" y1="1010.000" x2="130.006" y2="640.000" /> +<!-- udevadm [119] ppid=1 runtime=0.010s --> + <rect class="ps" x="134.013" y="1020.000" width="4.123" height="20.000" /> + <text x="143.135" y="1034.000">udevadm [119] <tspan class="run">0.010s</tspan></text> + <line class="dot" x1="134.013" y1="1030.000" x2="101.950" y2="1030.000" /> + +<!-- systemd-fsck [148] ppid=1 runtime=0.001s --> + <rect class="ps" x="134.013" y="1040.000" width="12.131" height="20.000" /> + <text x="151.144" y="1054.000">systemd-fsck [148] <tspan class="run">0.001s</tspan></text> + <line class="dot" x1="134.013" y1="1050.000" x2="101.950" y2="1050.000" /> + +<!-- fsck [150] ppid=148 runtime=0.001s --> + <rect class="ps" x="138.135" y="1060.000" width="8.008" height="20.000" /> + <rect class="wait" x="138.135" y="1060.000" width="4.006" height="2.210" /> + <rect class="cpu" x="138.135" y="1079.451" width="4.006" height="0.549" /> + <text x="151.144" y="1074.000">fsck [150] <tspan class="run">0.001s</tspan></text> + <line class="dot" x1="138.135" y1="1070.000" x2="134.013" y2="1070.000" /> + <line class="dot" x1="134.013" y1="1070.000" x2="134.013" y2="1060.000" /> + +<!-- fsck.ext4 [180] ppid=150 runtime=0.000s --> + <line class="dot" x1="138.135" y1="1070.000" x2="138.135" y2="1080.000" /> +<!-- systemd-sysctl [151] ppid=1 runtime=0.000s --> +<!-- mount [153] ppid=1 runtime=0.001s --> + <rect class="ps" x="138.135" y="1080.000" width="4.006" height="20.000" /> + <text x="147.141" y="1094.000">mount [153] <tspan class="run">0.001s</tspan></text> + <line class="dot" x1="138.135" y1="1090.000" x2="101.950" y2="1090.000" /> + +<!-- (le-setup) [154] ppid=1 runtime=0.002s --> + <rect class="ps" x="138.135" y="1100.000" width="4.006" height="20.000" /> + <text x="147.141" y="1114.000">(le-setup) [154] <tspan class="run">0.002s</tspan></text> + <line class="dot" x1="138.135" y1="1110.000" x2="101.950" y2="1110.000" /> + +<!-- adb [177] ppid=1 runtime=0.000s --> +<!-- (mount-fs) [216] ppid=1 runtime=0.000s --> +<!-- (tmpfiles) [222] ppid=1 runtime=0.003s --> + <rect class="ps" x="154.163" y="1120.000" width="4.008" height="20.000" /> + <text x="163.170" y="1134.000">(tmpfiles) [222] <tspan class="run">0.003s</tspan></text> + <line class="dot" x1="154.163" y1="1130.000" x2="101.950" y2="1130.000" /> + +<!-- systemctl [223] ppid=1 runtime=0.003s --> + <rect class="ps" x="158.170" y="1140.000" width="20.044" height="20.000" /> + <text x="183.214" y="1154.000">systemctl [223] <tspan class="run">0.003s</tspan></text> + <line class="dot" x1="158.170" y1="1150.000" x2="101.950" y2="1150.000" /> + +<!-- (dom-seed) [226] ppid=1 runtime=0.000s --> +<!-- alsactl [233] ppid=1 runtime=0.002s --> + <rect class="ps" x="170.191" y="1160.000" width="8.023" height="20.000" /> + <text x="183.214" y="1174.000">alsactl [233] <tspan class="run">0.002s</tspan></text> + <line class="dot" x1="170.191" y1="1170.000" x2="101.950" y2="1170.000" /> + +<!-- NetworkManager [237] ppid=1 runtime=0.100s --> + <rect class="ps" x="174.198" y="1180.000" width="1921.296" height="20.000" /> + <rect class="wait" x="198.262" y="1180.000" width="4.006" height="0.398" /> + <rect class="cpu" x="198.262" y="1195.819" width="4.006" height="4.181" /> + <rect class="wait" x="202.268" y="1180.000" width="4.007" height="1.491" /> + <rect class="cpu" x="202.268" y="1197.668" width="4.007" height="2.332" /> + <rect class="wait" x="210.280" y="1180.000" width="4.006" height="1.974" /> + <rect class="cpu" x="210.280" y="1197.206" width="4.006" height="2.794" /> + <rect class="wait" x="214.286" y="1180.000" width="4.007" height="0.007" /> + <rect class="cpu" x="214.286" y="1195.052" width="4.007" height="4.948" /> + <rect class="wait" x="226.310" y="1180.000" width="4.007" height="0.326" /> + <rect class="cpu" x="226.310" y="1197.692" width="4.007" height="2.308" /> + <rect class="wait" x="238.335" y="1180.000" width="4.009" height="6.597" /> + <rect class="cpu" x="238.335" y="1195.812" width="4.009" height="4.188" /> + <rect class="wait" x="378.590" y="1180.000" width="4.006" height="2.354" /> + <rect class="cpu" x="378.590" y="1197.473" width="4.006" height="2.527" /> + <rect class="wait" x="611.030" y="1180.000" width="4.007" height="0.060" /> + <rect class="cpu" x="611.030" y="1195.412" width="4.007" height="4.588" /> + <text x="179.198" y="1194.000">NetworkManager [237] <tspan class="run">0.100s</tspan></text> + <line class="dot" x1="174.198" y1="1190.000" x2="101.950" y2="1190.000" /> + +<!-- dhclient [390] ppid=237 runtime=0.009s --> + <rect class="ps" x="382.596" y="1200.000" width="1712.899" height="20.000" /> + <rect class="wait" x="382.596" y="1200.000" width="4.007" height="0.606" /> + <rect class="cpu" x="382.596" y="1215.745" width="4.007" height="4.255" /> + <text x="387.596" y="1214.000">dhclient [390] <tspan class="run">0.009s</tspan></text> + <line class="dot" x1="382.596" y1="1210.000" x2="174.198" y2="1210.000" /> + +<!-- dhclient [621] ppid=237 runtime=0.016s --> + <rect class="ps" x="743.310" y="1220.000" width="80.173" height="20.000" /> + <rect class="wait" x="743.310" y="1220.000" width="4.013" height="0.005" /> + <rect class="cpu" x="743.310" y="1232.514" width="4.013" height="7.486" /> + <text x="828.483" y="1234.000">dhclient [621] <tspan class="run">0.016s</tspan></text> + <line class="dot" x1="743.310" y1="1230.000" x2="174.198" y2="1230.000" /> + <line class="dot" x1="174.198" y1="1230.000" x2="174.198" y2="1200.000" /> + +<!-- nm-dhcp-client. [622] ppid=621 runtime=0.000s --> + <line class="dot" x1="743.310" y1="1230.000" x2="743.310" y2="1240.000" /> +<!-- ntpd [239] ppid=1 runtime=0.000s --> +<!-- systemd-logind [241] ppid=1 runtime=0.016s --> + <rect class="ps" x="174.198" y="1240.000" width="1921.296" height="20.000" /> + <rect class="wait" x="338.513" y="1240.000" width="4.008" height="0.026" /> + <rect class="cpu" x="338.513" y="1256.985" width="4.008" height="3.015" /> + <text x="179.198" y="1254.000">systemd-logind [241] <tspan class="run">0.016s</tspan></text> + <line class="dot" x1="174.198" y1="1250.000" x2="101.950" y2="1250.000" /> + +<!-- ntpd [242] ppid=1 runtime=0.007s --> + <rect class="ps" x="178.214" y="1260.000" width="1917.280" height="20.000" /> + <text x="183.214" y="1274.000">ntpd [242] <tspan class="run">0.007s</tspan></text> + <line class="dot" x1="178.214" y1="1270.000" x2="101.950" y2="1270.000" /> + +<!-- ntpd [246] ppid=242 runtime=0.002s --> + <rect class="ps" x="182.238" y="1280.000" width="693.353" height="20.000" /> + <text x="187.238" y="1294.000">ntpd [246] <tspan class="run">0.002s</tspan></text> + <line class="dot" x1="182.238" y1="1290.000" x2="178.214" y2="1290.000" /> + <line class="dot" x1="178.214" y1="1290.000" x2="178.214" y2="1280.000" /> + +<!-- avahi-daemon [243] ppid=1 runtime=0.019s --> + <rect class="ps" x="178.214" y="1300.000" width="1917.280" height="20.000" /> + <text x="183.214" y="1314.000">avahi-daemon [243] <tspan class="run">0.019s</tspan></text> + <line class="dot" x1="178.214" y1="1310.000" x2="101.950" y2="1310.000" /> + +<!-- avahi-daemon [245] ppid=243 runtime=0.000s --> + <line class="dot" x1="178.214" y1="1310.000" x2="178.214" y2="1320.000" /> +<!-- dbus-daemon [244] ppid=1 runtime=0.188s --> + <rect class="ps" x="178.214" y="1320.000" width="1917.280" height="20.000" /> + <rect class="wait" x="178.214" y="1320.000" width="4.024" height="1.062" /> + <rect class="cpu" x="178.214" y="1334.463" width="4.024" height="5.537" /> + <rect class="wait" x="322.483" y="1320.000" width="4.008" height="0.058" /> + <rect class="cpu" x="322.483" y="1337.838" width="4.008" height="2.162" /> + <rect class="wait" x="334.506" y="1320.000" width="4.008" height="0.423" /> + <rect class="cpu" x="334.506" y="1337.532" width="4.008" height="2.468" /> + <rect class="wait" x="386.603" y="1320.000" width="4.007" height="1.284" /> + <rect class="cpu" x="386.603" y="1335.251" width="4.007" height="4.749" /> + <rect class="wait" x="390.610" y="1320.000" width="4.006" height="1.227" /> + <rect class="cpu" x="390.610" y="1337.525" width="4.006" height="2.475" /> + <rect class="wait" x="402.645" y="1320.000" width="4.011" height="4.244" /> + <rect class="cpu" x="402.645" y="1337.270" width="4.011" height="2.730" /> + <rect class="wait" x="406.656" y="1320.000" width="4.007" height="1.507" /> + <rect class="cpu" x="406.656" y="1337.765" width="4.007" height="2.235" /> + <rect class="wait" x="458.759" y="1320.000" width="4.007" height="0.791" /> + <rect class="cpu" x="458.759" y="1336.524" width="4.007" height="3.476" /> + <rect class="wait" x="462.766" y="1320.000" width="4.010" height="1.219" /> + <rect class="cpu" x="462.766" y="1337.201" width="4.010" height="2.799" /> + <rect class="wait" x="510.850" y="1320.000" width="4.008" height="3.680" /> + <rect class="cpu" x="510.850" y="1338.127" width="4.008" height="1.873" /> + <rect class="wait" x="522.870" y="1320.000" width="4.006" height="3.822" /> + <rect class="cpu" x="522.870" y="1338.555" width="4.006" height="1.445" /> + <rect class="wait" x="558.930" y="1320.000" width="4.006" height="2.658" /> + <rect class="cpu" x="558.930" y="1336.173" width="4.006" height="3.827" /> + <rect class="wait" x="562.936" y="1320.000" width="4.006" height="0.592" /> + <rect class="cpu" x="562.936" y="1336.448" width="4.006" height="3.552" /> + <rect class="wait" x="607.021" y="1320.000" width="4.009" height="0.134" /> + <rect class="cpu" x="607.021" y="1337.804" width="4.009" height="2.196" /> + <rect class="wait" x="611.030" y="1320.000" width="4.007" height="1.025" /> + <rect class="cpu" x="611.030" y="1334.413" width="4.007" height="5.587" /> + <rect class="wait" x="615.037" y="1320.000" width="4.009" height="0.662" /> + <rect class="cpu" x="615.037" y="1336.551" width="4.009" height="3.449" /> + <rect class="wait" x="655.111" y="1320.000" width="4.006" height="2.013" /> + <rect class="cpu" x="655.111" y="1337.721" width="4.006" height="2.279" /> + <rect class="wait" x="911.650" y="1320.000" width="4.006" height="0.041" /> + <rect class="cpu" x="911.650" y="1337.958" width="4.006" height="2.042" /> + <rect class="wait" x="1678.118" y="1320.000" width="4.008" height="0.784" /> + <rect class="cpu" x="1678.118" y="1337.448" width="4.008" height="2.552" /> + <rect class="wait" x="1682.126" y="1320.000" width="4.007" height="0.026" /> + <rect class="cpu" x="1682.126" y="1337.697" width="4.007" height="2.303" /> + <text x="183.214" y="1334.000">dbus-daemon [244] <tspan class="run">0.188s</tspan></text> + <line class="dot" x1="178.214" y1="1330.000" x2="101.950" y2="1330.000" /> + +<!-- dbus-daemon [478] ppid=244 runtime=0.000s --> +<!-- nm-dispatcher.a [479] ppid=478 runtime=0.006s --> + <rect class="ps" x="486.814" y="1340.000" width="1010.671" height="20.000" /> + <rect class="wait" x="486.814" y="1340.000" width="4.006" height="1.044" /> + <rect class="cpu" x="486.814" y="1357.587" width="4.006" height="2.413" /> + <text x="491.814" y="1354.000">nm-dispatcher.a [479] <tspan class="run">0.006s</tspan></text> + <line class="dot" x1="486.814" y1="1350.000" x2="178.214" y2="1350.000" /> + <line class="dot" x1="178.214" y1="1350.000" x2="178.214" y2="1340.000" /> + +<!-- dbus-daemon [516] ppid=244 runtime=0.000s --> + <line class="dot" x1="178.214" y1="1350.000" x2="178.214" y2="1340.000" /> +<!-- packagekitd [517] ppid=516 runtime=0.043s --> + <rect class="ps" x="510.850" y="1360.000" width="1584.645" height="20.000" /> + <rect class="wait" x="510.850" y="1360.000" width="4.008" height="0.915" /> + <rect class="cpu" x="510.850" y="1375.902" width="4.008" height="4.098" /> + <rect class="wait" x="1678.118" y="1360.000" width="4.008" height="0.990" /> + <rect class="cpu" x="1678.118" y="1373.434" width="4.008" height="6.566" /> + <rect class="wait" x="1682.126" y="1360.000" width="4.007" height="0.061" /> + <rect class="cpu" x="1682.126" y="1376.006" width="4.007" height="3.994" /> + <text x="515.850" y="1374.000">packagekitd [517] <tspan class="run">0.043s</tspan></text> + <line class="dot" x1="510.850" y1="1370.000" x2="178.214" y2="1370.000" /> + <line class="dot" x1="178.214" y1="1370.000" x2="178.214" y2="1340.000" /> + +<!-- yumBackend.py [654] ppid=517 runtime=0.311s --> + <rect class="ps" x="1686.133" y="1380.000" width="409.362" height="20.000" /> + <rect class="wait" x="1686.133" y="1380.000" width="4.007" height="0.111" /> + <rect class="cpu" x="1686.133" y="1388.205" width="4.007" height="11.795" /> + <rect class="wait" x="1690.140" y="1380.000" width="4.009" height="0.039" /> + <rect class="cpu" x="1690.140" y="1383.962" width="4.009" height="16.038" /> + <rect class="wait" x="1694.150" y="1380.000" width="4.009" height="0.059" /> + <rect class="cpu" x="1694.150" y="1391.420" width="4.009" height="8.580" /> + <rect class="wait" x="1698.159" y="1380.000" width="4.007" height="0.053" /> + <rect class="cpu" x="1698.159" y="1389.028" width="4.007" height="10.972" /> + <rect class="wait" x="1702.166" y="1380.000" width="4.007" height="0.100" /> + <rect class="cpu" x="1702.166" y="1391.669" width="4.007" height="8.331" /> + <rect class="wait" x="1706.173" y="1380.000" width="4.013" height="0.095" /> + <rect class="cpu" x="1706.173" y="1390.251" width="4.013" height="9.749" /> + <rect class="wait" x="1710.186" y="1380.000" width="4.007" height="0.051" /> + <rect class="cpu" x="1710.186" y="1390.121" width="4.007" height="9.879" /> + <rect class="wait" x="1714.193" y="1380.000" width="4.007" height="0.095" /> + <rect class="cpu" x="1714.193" y="1389.920" width="4.007" height="10.080" /> + <rect class="wait" x="1718.200" y="1380.000" width="4.007" height="0.051" /> + <rect class="cpu" x="1718.200" y="1389.868" width="4.007" height="10.132" /> + <rect class="wait" x="1722.208" y="1380.000" width="4.013" height="0.129" /> + <rect class="cpu" x="1722.208" y="1394.081" width="4.013" height="5.919" /> + <rect class="wait" x="1726.220" y="1380.000" width="4.009" height="0.023" /> + <rect class="cpu" x="1726.220" y="1388.296" width="4.009" height="11.704" /> + <rect class="wait" x="1730.230" y="1380.000" width="4.006" height="0.023" /> + <rect class="cpu" x="1730.230" y="1384.318" width="4.006" height="15.682" /> + <rect class="wait" x="1734.236" y="1380.000" width="4.007" height="0.164" /> + <rect class="cpu" x="1734.236" y="1389.023" width="4.007" height="10.977" /> + <rect class="wait" x="1738.243" y="1380.000" width="4.015" height="0.225" /> + <rect class="cpu" x="1738.243" y="1385.175" width="4.015" height="14.825" /> + <text x="1691.133" y="1394.000">yumBackend.py [654] <tspan class="run">0.311s</tspan></text> + <line class="dot" x1="1686.133" y1="1390.000" x2="510.850" y2="1390.000" /> + <line class="dot" x1="510.850" y1="1390.000" x2="510.850" y2="1380.000" /> + +<!-- systemd-user-se [249] ppid=1 runtime=0.000s --> +<!-- polkitd [252] ppid=1 runtime=0.129s --> + <rect class="ps" x="186.244" y="1400.000" width="1909.251" height="20.000" /> + <rect class="wait" x="334.506" y="1400.000" width="4.008" height="0.022" /> + <rect class="cpu" x="334.506" y="1414.359" width="4.008" height="5.641" /> + <rect class="wait" x="386.603" y="1400.000" width="4.007" height="0.201" /> + <rect class="cpu" x="386.603" y="1416.066" width="4.007" height="3.934" /> + <rect class="wait" x="390.610" y="1400.000" width="4.006" height="0.105" /> + <rect class="cpu" x="390.610" y="1417.352" width="4.006" height="2.648" /> + <rect class="wait" x="426.696" y="1400.000" width="4.006" height="0.022" /> + <rect class="cpu" x="426.696" y="1417.032" width="4.006" height="2.968" /> + <rect class="wait" x="458.759" y="1400.000" width="4.007" height="0.025" /> + <rect class="cpu" x="458.759" y="1417.455" width="4.007" height="2.545" /> + <rect class="wait" x="462.766" y="1400.000" width="4.010" height="0.000" /> + <rect class="cpu" x="462.766" y="1416.642" width="4.010" height="3.358" /> + <rect class="wait" x="558.930" y="1400.000" width="4.006" height="0.219" /> + <rect class="cpu" x="558.930" y="1417.777" width="4.006" height="2.223" /> + <rect class="wait" x="611.030" y="1400.000" width="4.007" height="0.103" /> + <rect class="cpu" x="611.030" y="1412.955" width="4.007" height="7.045" /> + <rect class="wait" x="615.037" y="1400.000" width="4.009" height="1.842" /> + <rect class="cpu" x="615.037" y="1408.755" width="4.009" height="11.245" /> + <rect class="wait" x="619.046" y="1400.000" width="4.008" height="0.000" /> + <rect class="cpu" x="619.046" y="1414.118" width="4.008" height="5.882" /> + <rect class="wait" x="655.111" y="1400.000" width="4.006" height="0.441" /> + <rect class="cpu" x="655.111" y="1412.761" width="4.006" height="7.239" /> + <text x="191.244" y="1414.000">polkitd [252] <tspan class="run">0.129s</tspan></text> + <line class="dot" x1="186.244" y1="1410.000" x2="101.950" y2="1410.000" /> + +<!-- gdm-binary [253] ppid=1 runtime=0.016s --> + <rect class="ps" x="186.244" y="1420.000" width="1909.251" height="20.000" /> + <rect class="wait" x="194.256" y="1420.000" width="4.006" height="0.212" /> + <rect class="cpu" x="194.256" y="1435.704" width="4.006" height="4.296" /> + <text x="191.244" y="1434.000">gdm-binary [253] <tspan class="run">0.016s</tspan></text> + <line class="dot" x1="186.244" y1="1430.000" x2="101.950" y2="1430.000" /> + +<!-- gdm-simple-slav [273] ppid=253 runtime=0.024s --> + <rect class="ps" x="202.268" y="1440.000" width="1893.227" height="20.000" /> + <rect class="wait" x="338.513" y="1440.000" width="4.008" height="0.328" /> + <rect class="cpu" x="338.513" y="1457.489" width="4.008" height="2.511" /> + <text x="207.268" y="1454.000">gdm-simple-slav [273] <tspan class="run">0.024s</tspan></text> + <line class="dot" x1="202.268" y1="1450.000" x2="186.244" y2="1450.000" /> + <line class="dot" x1="186.244" y1="1450.000" x2="186.244" y2="1440.000" /> + +<!-- Xorg [286] ppid=273 runtime=1.979s --> + <rect class="ps" x="210.280" y="1460.000" width="1885.214" height="20.000" /> + <rect class="wait" x="242.344" y="1460.000" width="4.006" height="1.063" /> + <rect class="cpu" x="242.344" y="1466.696" width="4.006" height="13.304" /> + <rect class="wait" x="246.350" y="1460.000" width="4.008" height="0.498" /> + <rect class="cpu" x="246.350" y="1476.527" width="4.008" height="3.473" /> + <rect class="wait" x="250.358" y="1460.000" width="4.006" height="20.000" /> + <rect class="cpu" x="250.358" y="1478.647" width="4.006" height="1.353" /> + <rect class="wait" x="254.363" y="1460.000" width="4.006" height="13.276" /> + <rect class="cpu" x="254.363" y="1478.312" width="4.006" height="1.688" /> + <rect class="wait" x="258.369" y="1460.000" width="4.008" height="12.097" /> + <rect class="cpu" x="258.369" y="1473.195" width="4.008" height="6.805" /> + <rect class="wait" x="262.377" y="1460.000" width="4.009" height="0.511" /> + <rect class="cpu" x="262.377" y="1468.921" width="4.009" height="11.079" /> + <rect class="wait" x="266.386" y="1460.000" width="4.007" height="10.116" /> + <rect class="cpu" x="266.386" y="1475.559" width="4.007" height="4.441" /> + <rect class="wait" x="270.393" y="1460.000" width="4.007" height="13.608" /> + <rect class="cpu" x="270.393" y="1478.661" width="4.007" height="1.339" /> + <rect class="wait" x="274.400" y="1460.000" width="4.007" height="20.000" /> + <rect class="cpu" x="274.400" y="1477.972" width="4.007" height="2.028" /> + <rect class="wait" x="278.406" y="1460.000" width="4.008" height="0.010" /> + <rect class="cpu" x="278.406" y="1467.049" width="4.008" height="12.951" /> + <rect class="wait" x="282.414" y="1460.000" width="4.007" height="4.222" /> + <rect class="cpu" x="282.414" y="1476.125" width="4.007" height="3.875" /> + <rect class="wait" x="286.422" y="1460.000" width="4.006" height="0.036" /> + <rect class="cpu" x="286.422" y="1470.867" width="4.006" height="9.133" /> + <rect class="wait" x="290.428" y="1460.000" width="4.006" height="0.211" /> + <rect class="cpu" x="290.428" y="1475.659" width="4.006" height="4.341" /> + <rect class="wait" x="294.434" y="1460.000" width="4.007" height="3.077" /> + <rect class="cpu" x="294.434" y="1469.919" width="4.007" height="10.081" /> + <rect class="wait" x="302.446" y="1460.000" width="4.007" height="13.398" /> + <rect class="cpu" x="302.446" y="1478.434" width="4.007" height="1.566" /> + <rect class="wait" x="306.453" y="1460.000" width="4.006" height="12.147" /> + <rect class="cpu" x="306.453" y="1462.307" width="4.006" height="17.693" /> + <rect class="wait" x="310.459" y="1460.000" width="4.009" height="10.053" /> + <rect class="cpu" x="310.459" y="1473.363" width="4.009" height="6.637" /> + <rect class="wait" x="314.468" y="1460.000" width="4.008" height="6.687" /> + <rect class="cpu" x="314.468" y="1476.751" width="4.008" height="3.249" /> + <rect class="wait" x="362.562" y="1460.000" width="4.007" height="1.574" /> + <rect class="cpu" x="362.562" y="1477.376" width="4.007" height="2.624" /> + <rect class="wait" x="370.576" y="1460.000" width="4.008" height="0.000" /> + <rect class="cpu" x="370.576" y="1477.872" width="4.008" height="2.128" /> + <rect class="wait" x="382.596" y="1460.000" width="4.007" height="4.586" /> + <rect class="cpu" x="382.596" y="1472.549" width="4.007" height="7.451" /> + <rect class="wait" x="386.603" y="1460.000" width="4.007" height="0.359" /> + <rect class="cpu" x="386.603" y="1472.731" width="4.007" height="7.269" /> + <rect class="wait" x="390.610" y="1460.000" width="4.006" height="9.491" /> + <rect class="cpu" x="390.610" y="1464.089" width="4.006" height="15.911" /> + <rect class="wait" x="394.616" y="1460.000" width="4.008" height="11.830" /> + <rect class="cpu" x="394.616" y="1477.421" width="4.008" height="2.579" /> + <rect class="wait" x="398.624" y="1460.000" width="4.021" height="11.317" /> + <rect class="cpu" x="398.624" y="1471.661" width="4.021" height="8.339" /> + <rect class="wait" x="438.722" y="1460.000" width="4.008" height="0.079" /> + <rect class="cpu" x="438.722" y="1477.289" width="4.008" height="2.711" /> + <rect class="wait" x="442.730" y="1460.000" width="4.010" height="1.662" /> + <rect class="cpu" x="442.730" y="1474.820" width="4.010" height="5.180" /> + <rect class="wait" x="466.776" y="1460.000" width="4.008" height="0.049" /> + <rect class="cpu" x="466.776" y="1477.130" width="4.008" height="2.870" /> + <rect class="wait" x="470.784" y="1460.000" width="4.008" height="0.193" /> + <rect class="cpu" x="470.784" y="1470.251" width="4.008" height="9.749" /> + <rect class="wait" x="490.819" y="1460.000" width="4.006" height="2.109" /> + <rect class="cpu" x="490.819" y="1476.871" width="4.006" height="3.129" /> + <rect class="wait" x="494.825" y="1460.000" width="4.006" height="0.107" /> + <rect class="cpu" x="494.825" y="1474.993" width="4.006" height="5.007" /> + <rect class="wait" x="502.838" y="1460.000" width="4.006" height="4.590" /> + <rect class="cpu" x="502.838" y="1475.829" width="4.006" height="4.171" /> + <rect class="wait" x="506.844" y="1460.000" width="4.006" height="2.287" /> + <rect class="cpu" x="506.844" y="1465.317" width="4.006" height="14.683" /> + <rect class="wait" x="510.850" y="1460.000" width="4.008" height="3.634" /> + <rect class="cpu" x="510.850" y="1478.738" width="4.008" height="1.262" /> + <rect class="wait" x="514.858" y="1460.000" width="4.006" height="5.071" /> + <rect class="cpu" x="514.858" y="1479.710" width="4.006" height="0.290" /> + <rect class="wait" x="518.864" y="1460.000" width="4.006" height="2.163" /> + <rect class="cpu" x="518.864" y="1475.976" width="4.006" height="4.024" /> + <rect class="wait" x="522.870" y="1460.000" width="4.006" height="0.255" /> + <rect class="cpu" x="522.870" y="1472.451" width="4.006" height="7.549" /> + <rect class="wait" x="530.883" y="1460.000" width="4.006" height="1.194" /> + <rect class="cpu" x="530.883" y="1475.084" width="4.006" height="4.916" /> + <rect class="wait" x="538.895" y="1460.000" width="4.007" height="0.665" /> + <rect class="cpu" x="538.895" y="1470.428" width="4.007" height="9.572" /> + <rect class="wait" x="542.902" y="1460.000" width="4.009" height="0.079" /> + <rect class="cpu" x="542.902" y="1471.157" width="4.009" height="8.843" /> + <rect class="wait" x="546.911" y="1460.000" width="4.006" height="9.851" /> + <rect class="cpu" x="546.911" y="1466.925" width="4.006" height="13.075" /> + <rect class="wait" x="550.917" y="1460.000" width="4.006" height="12.656" /> + <rect class="cpu" x="550.917" y="1473.704" width="4.006" height="6.296" /> + <rect class="wait" x="554.922" y="1460.000" width="4.007" height="9.304" /> + <rect class="cpu" x="554.922" y="1472.686" width="4.007" height="7.314" /> + <rect class="wait" x="566.943" y="1460.000" width="4.006" height="0.000" /> + <rect class="cpu" x="566.943" y="1477.142" width="4.006" height="2.858" /> + <rect class="wait" x="570.949" y="1460.000" width="4.007" height="1.590" /> + <rect class="cpu" x="570.949" y="1470.022" width="4.007" height="9.978" /> + <rect class="wait" x="574.956" y="1460.000" width="4.010" height="1.472" /> + <rect class="cpu" x="574.956" y="1471.185" width="4.010" height="8.815" /> + <rect class="wait" x="578.966" y="1460.000" width="4.007" height="4.395" /> + <rect class="cpu" x="578.966" y="1472.614" width="4.007" height="7.386" /> + <rect class="wait" x="586.981" y="1460.000" width="4.009" height="0.000" /> + <rect class="cpu" x="586.981" y="1477.858" width="4.009" height="2.142" /> + <rect class="wait" x="594.998" y="1460.000" width="4.010" height="0.000" /> + <rect class="cpu" x="594.998" y="1477.194" width="4.010" height="2.806" /> + <rect class="wait" x="643.090" y="1460.000" width="4.007" height="3.160" /> + <rect class="cpu" x="643.090" y="1473.701" width="4.007" height="6.299" /> + <rect class="wait" x="659.117" y="1460.000" width="4.008" height="0.109" /> + <rect class="cpu" x="659.117" y="1468.234" width="4.008" height="11.766" /> + <rect class="wait" x="663.125" y="1460.000" width="4.008" height="0.109" /> + <rect class="cpu" x="663.125" y="1470.589" width="4.008" height="9.411" /> + <rect class="wait" x="667.133" y="1460.000" width="4.012" height="0.062" /> + <rect class="cpu" x="667.133" y="1470.238" width="4.012" height="9.762" /> + <rect class="wait" x="671.145" y="1460.000" width="4.006" height="0.012" /> + <rect class="cpu" x="671.145" y="1476.037" width="4.006" height="3.963" /> + <rect class="wait" x="675.152" y="1460.000" width="4.009" height="0.042" /> + <rect class="cpu" x="675.152" y="1470.094" width="4.009" height="9.906" /> + <rect class="wait" x="679.161" y="1460.000" width="4.011" height="0.044" /> + <rect class="cpu" x="679.161" y="1472.456" width="4.011" height="7.544" /> + <rect class="wait" x="683.171" y="1460.000" width="4.009" height="0.060" /> + <rect class="cpu" x="683.171" y="1472.763" width="4.009" height="7.237" /> + <rect class="wait" x="687.180" y="1460.000" width="4.009" height="0.082" /> + <rect class="cpu" x="687.180" y="1469.138" width="4.009" height="10.862" /> + <rect class="wait" x="691.189" y="1460.000" width="4.010" height="0.152" /> + <rect class="cpu" x="691.189" y="1468.209" width="4.010" height="11.791" /> + <rect class="wait" x="695.200" y="1460.000" width="4.007" height="3.319" /> + <rect class="cpu" x="695.200" y="1477.927" width="4.007" height="2.073" /> + <rect class="wait" x="699.207" y="1460.000" width="4.010" height="3.486" /> + <rect class="cpu" x="699.207" y="1471.878" width="4.010" height="8.122" /> + <rect class="wait" x="703.216" y="1460.000" width="4.009" height="0.093" /> + <rect class="cpu" x="703.216" y="1470.174" width="4.009" height="9.826" /> + <rect class="wait" x="707.226" y="1460.000" width="4.009" height="0.027" /> + <rect class="cpu" x="707.226" y="1473.695" width="4.009" height="6.305" /> + <rect class="wait" x="711.235" y="1460.000" width="4.010" height="0.036" /> + <rect class="cpu" x="711.235" y="1470.523" width="4.010" height="9.477" /> + <rect class="wait" x="715.245" y="1460.000" width="4.014" height="0.036" /> + <rect class="cpu" x="715.245" y="1470.876" width="4.014" height="9.124" /> + <rect class="wait" x="719.258" y="1460.000" width="4.007" height="3.084" /> + <rect class="cpu" x="719.258" y="1472.101" width="4.007" height="7.899" /> + <rect class="wait" x="723.265" y="1460.000" width="4.008" height="0.034" /> + <rect class="cpu" x="723.265" y="1468.663" width="4.008" height="11.337" /> + <rect class="wait" x="727.273" y="1460.000" width="4.014" height="0.024" /> + <rect class="cpu" x="727.273" y="1468.501" width="4.014" height="11.499" /> + <rect class="wait" x="731.286" y="1460.000" width="4.009" height="1.373" /> + <rect class="cpu" x="731.286" y="1472.729" width="4.009" height="7.271" /> + <rect class="wait" x="735.295" y="1460.000" width="4.009" height="2.832" /> + <rect class="cpu" x="735.295" y="1471.312" width="4.009" height="8.688" /> + <rect class="wait" x="739.304" y="1460.000" width="4.006" height="0.040" /> + <rect class="cpu" x="739.304" y="1465.305" width="4.006" height="14.695" /> + <rect class="wait" x="743.310" y="1460.000" width="4.013" height="0.015" /> + <rect class="cpu" x="743.310" y="1474.503" width="4.013" height="5.497" /> + <rect class="wait" x="747.323" y="1460.000" width="4.007" height="0.022" /> + <rect class="cpu" x="747.323" y="1472.120" width="4.007" height="7.880" /> + <rect class="wait" x="751.330" y="1460.000" width="4.010" height="0.032" /> + <rect class="cpu" x="751.330" y="1466.892" width="4.010" height="13.108" /> + <rect class="wait" x="755.340" y="1460.000" width="4.010" height="0.245" /> + <rect class="cpu" x="755.340" y="1472.327" width="4.010" height="7.673" /> + <rect class="wait" x="759.350" y="1460.000" width="4.009" height="0.032" /> + <rect class="cpu" x="759.350" y="1473.686" width="4.009" height="6.314" /> + <rect class="wait" x="763.359" y="1460.000" width="4.008" height="0.033" /> + <rect class="cpu" x="763.359" y="1469.589" width="4.008" height="10.411" /> + <rect class="wait" x="767.367" y="1460.000" width="4.014" height="0.112" /> + <rect class="cpu" x="767.367" y="1468.004" width="4.014" height="11.996" /> + <rect class="wait" x="771.381" y="1460.000" width="4.009" height="3.503" /> + <rect class="cpu" x="771.381" y="1476.839" width="4.009" height="3.161" /> + <rect class="wait" x="775.390" y="1460.000" width="4.006" height="3.184" /> + <rect class="cpu" x="775.390" y="1471.364" width="4.006" height="8.636" /> + <rect class="wait" x="779.396" y="1460.000" width="4.010" height="0.060" /> + <rect class="cpu" x="779.396" y="1471.662" width="4.010" height="8.338" /> + <rect class="wait" x="783.406" y="1460.000" width="4.009" height="0.011" /> + <rect class="cpu" x="783.406" y="1471.578" width="4.009" height="8.422" /> + <rect class="wait" x="787.415" y="1460.000" width="4.007" height="0.035" /> + <rect class="cpu" x="787.415" y="1468.784" width="4.007" height="11.216" /> + <rect class="wait" x="791.422" y="1460.000" width="4.006" height="2.941" /> + <rect class="cpu" x="791.422" y="1469.478" width="4.006" height="10.522" /> + <rect class="wait" x="795.428" y="1460.000" width="4.008" height="0.046" /> + <rect class="cpu" x="795.428" y="1469.492" width="4.008" height="10.508" /> + <rect class="wait" x="799.436" y="1460.000" width="4.008" height="0.222" /> + <rect class="cpu" x="799.436" y="1471.482" width="4.008" height="8.518" /> + <rect class="wait" x="803.444" y="1460.000" width="4.011" height="2.791" /> + <rect class="cpu" x="803.444" y="1476.528" width="4.011" height="3.472" /> + <rect class="wait" x="807.454" y="1460.000" width="4.006" height="3.106" /> + <rect class="cpu" x="807.454" y="1471.940" width="4.006" height="8.060" /> + <rect class="wait" x="811.460" y="1460.000" width="4.010" height="0.106" /> + <rect class="cpu" x="811.460" y="1472.837" width="4.010" height="7.163" /> + <rect class="wait" x="815.470" y="1460.000" width="4.007" height="2.372" /> + <rect class="cpu" x="815.470" y="1471.745" width="4.007" height="8.255" /> + <rect class="wait" x="819.477" y="1460.000" width="4.006" height="2.650" /> + <rect class="cpu" x="819.477" y="1468.252" width="4.006" height="11.748" /> + <rect class="wait" x="823.483" y="1460.000" width="4.008" height="0.036" /> + <rect class="cpu" x="823.483" y="1470.426" width="4.008" height="9.574" /> + <rect class="wait" x="827.492" y="1460.000" width="4.009" height="1.178" /> + <rect class="cpu" x="827.492" y="1472.405" width="4.009" height="7.595" /> + <rect class="wait" x="831.500" y="1460.000" width="4.010" height="2.380" /> + <rect class="cpu" x="831.500" y="1473.016" width="4.010" height="6.984" /> + <rect class="wait" x="835.510" y="1460.000" width="4.007" height="0.133" /> + <rect class="cpu" x="835.510" y="1465.719" width="4.007" height="14.281" /> + <rect class="wait" x="839.517" y="1460.000" width="4.011" height="0.070" /> + <rect class="cpu" x="839.517" y="1469.658" width="4.011" height="10.342" /> + <rect class="wait" x="843.528" y="1460.000" width="4.010" height="0.032" /> + <rect class="cpu" x="843.528" y="1470.896" width="4.010" height="9.104" /> + <rect class="wait" x="847.538" y="1460.000" width="4.006" height="2.758" /> + <rect class="cpu" x="847.538" y="1471.356" width="4.006" height="8.644" /> + <rect class="wait" x="851.544" y="1460.000" width="4.007" height="0.034" /> + <rect class="cpu" x="851.544" y="1468.785" width="4.007" height="11.215" /> + <rect class="wait" x="855.550" y="1460.000" width="4.006" height="0.037" /> + <rect class="cpu" x="855.550" y="1474.291" width="4.006" height="5.709" /> + <rect class="wait" x="859.557" y="1460.000" width="4.006" height="0.018" /> + <rect class="cpu" x="859.557" y="1477.248" width="4.006" height="2.752" /> + <rect class="wait" x="867.570" y="1460.000" width="4.015" height="7.559" /> + <rect class="cpu" x="867.570" y="1478.513" width="4.015" height="1.487" /> + <rect class="wait" x="871.585" y="1460.000" width="4.006" height="7.957" /> + <rect class="cpu" x="871.585" y="1479.072" width="4.006" height="0.928" /> + <rect class="wait" x="899.632" y="1460.000" width="4.006" height="0.027" /> + <rect class="cpu" x="899.632" y="1473.886" width="4.006" height="6.114" /> + <rect class="wait" x="903.639" y="1460.000" width="4.006" height="0.020" /> + <rect class="cpu" x="903.639" y="1475.169" width="4.006" height="4.831" /> + <rect class="wait" x="907.644" y="1460.000" width="4.006" height="0.026" /> + <rect class="cpu" x="907.644" y="1474.470" width="4.006" height="5.530" /> + <rect class="wait" x="911.650" y="1460.000" width="4.006" height="0.034" /> + <rect class="cpu" x="911.650" y="1471.278" width="4.006" height="8.722" /> + <rect class="wait" x="915.656" y="1460.000" width="4.007" height="0.031" /> + <rect class="cpu" x="915.656" y="1474.605" width="4.007" height="5.395" /> + <rect class="wait" x="919.664" y="1460.000" width="4.007" height="0.047" /> + <rect class="cpu" x="919.664" y="1473.279" width="4.007" height="6.721" /> + <rect class="wait" x="923.671" y="1460.000" width="4.008" height="0.054" /> + <rect class="cpu" x="923.671" y="1473.811" width="4.008" height="6.189" /> + <rect class="wait" x="947.725" y="1460.000" width="4.008" height="0.031" /> + <rect class="cpu" x="947.725" y="1477.881" width="4.008" height="2.119" /> + <rect class="wait" x="951.733" y="1460.000" width="4.006" height="0.053" /> + <rect class="cpu" x="951.733" y="1473.555" width="4.006" height="6.445" /> + <rect class="wait" x="955.739" y="1460.000" width="4.008" height="0.069" /> + <rect class="cpu" x="955.739" y="1474.579" width="4.008" height="5.421" /> + <rect class="wait" x="959.747" y="1460.000" width="4.011" height="0.047" /> + <rect class="cpu" x="959.747" y="1474.021" width="4.011" height="5.979" /> + <rect class="wait" x="963.758" y="1460.000" width="4.008" height="0.049" /> + <rect class="cpu" x="963.758" y="1474.586" width="4.008" height="5.414" /> + <rect class="wait" x="967.766" y="1460.000" width="4.007" height="0.050" /> + <rect class="cpu" x="967.766" y="1473.228" width="4.007" height="6.772" /> + <rect class="wait" x="971.773" y="1460.000" width="4.010" height="0.067" /> + <rect class="cpu" x="971.773" y="1473.107" width="4.010" height="6.893" /> + <rect class="wait" x="975.783" y="1460.000" width="4.014" height="0.052" /> + <rect class="cpu" x="975.783" y="1473.883" width="4.014" height="6.117" /> + <rect class="wait" x="979.797" y="1460.000" width="4.009" height="0.047" /> + <rect class="cpu" x="979.797" y="1474.548" width="4.009" height="5.452" /> + <rect class="wait" x="983.805" y="1460.000" width="4.009" height="0.049" /> + <rect class="cpu" x="983.805" y="1473.675" width="4.009" height="6.325" /> + <rect class="wait" x="987.814" y="1460.000" width="4.014" height="0.043" /> + <rect class="cpu" x="987.814" y="1474.733" width="4.014" height="5.267" /> + <rect class="wait" x="991.828" y="1460.000" width="4.010" height="0.049" /> + <rect class="cpu" x="991.828" y="1474.124" width="4.010" height="5.876" /> + <rect class="wait" x="995.837" y="1460.000" width="4.014" height="0.056" /> + <rect class="cpu" x="995.837" y="1473.906" width="4.014" height="6.094" /> + <rect class="wait" x="999.852" y="1460.000" width="4.015" height="0.054" /> + <rect class="cpu" x="999.852" y="1473.312" width="4.015" height="6.688" /> + <rect class="wait" x="1003.866" y="1460.000" width="4.010" height="0.014" /> + <rect class="cpu" x="1003.866" y="1475.536" width="4.010" height="4.464" /> + <rect class="wait" x="1015.900" y="1460.000" width="4.014" height="0.055" /> + <rect class="cpu" x="1015.900" y="1475.053" width="4.014" height="4.947" /> + <rect class="wait" x="1019.914" y="1460.000" width="4.014" height="0.037" /> + <rect class="cpu" x="1019.914" y="1476.694" width="4.014" height="3.306" /> + <rect class="wait" x="1023.928" y="1460.000" width="4.010" height="0.032" /> + <rect class="cpu" x="1023.928" y="1477.622" width="4.010" height="2.378" /> + <rect class="wait" x="1035.955" y="1460.000" width="4.008" height="0.000" /> + <rect class="cpu" x="1035.955" y="1477.552" width="4.008" height="2.448" /> + <rect class="wait" x="1039.963" y="1460.000" width="4.006" height="0.000" /> + <rect class="cpu" x="1039.963" y="1477.957" width="4.006" height="2.043" /> + <rect class="wait" x="1060.001" y="1460.000" width="4.007" height="0.005" /> + <rect class="cpu" x="1060.001" y="1475.680" width="4.007" height="4.320" /> + <rect class="wait" x="1064.008" y="1460.000" width="4.006" height="0.300" /> + <rect class="cpu" x="1064.008" y="1473.686" width="4.006" height="6.314" /> + <rect class="wait" x="1080.040" y="1460.000" width="4.008" height="0.024" /> + <rect class="cpu" x="1080.040" y="1476.460" width="4.008" height="3.540" /> + <text x="215.280" y="1474.000">Xorg [286] <tspan class="run">1.979s</tspan></text> + <line class="dot" x1="210.280" y1="1470.000" x2="202.268" y2="1470.000" /> + +<!-- xkbcomp [294] ppid=286 runtime=0.000s --> + <line class="dot" x1="210.280" y1="1470.000" x2="210.280" y2="1480.000" /> +<!-- Default [297] ppid=273 runtime=0.000s --> +<!-- xrdb [298] ppid=297 runtime=0.000s --> + <line class="dot" x1="202.268" y1="1470.000" x2="202.268" y2="1460.000" /> +<!-- gdm-session-wor [305] ppid=273 runtime=0.017s --> + <rect class="ps" x="322.483" y="1480.000" width="1773.011" height="20.000" /> + <rect class="wait" x="334.506" y="1480.000" width="4.008" height="0.173" /> + <rect class="cpu" x="334.506" y="1495.599" width="4.008" height="4.401" /> + <rect class="wait" x="338.513" y="1480.000" width="4.008" height="0.000" /> + <rect class="cpu" x="338.513" y="1497.563" width="4.008" height="2.437" /> + <text x="327.483" y="1494.000">gdm-session-wor [305] <tspan class="run">0.017s</tspan></text> + <line class="dot" x1="322.483" y1="1490.000" x2="202.268" y2="1490.000" /> + <line class="dot" x1="202.268" y1="1490.000" x2="202.268" y2="1460.000" /> + +<!-- gnome-session [311] ppid=305 runtime=0.208s --> + <rect class="ps" x="342.521" y="1500.000" width="1752.974" height="20.000" /> + <rect class="wait" x="342.521" y="1500.000" width="4.008" height="0.035" /> + <rect class="cpu" x="342.521" y="1513.666" width="4.008" height="6.334" /> + <rect class="wait" x="346.529" y="1500.000" width="4.008" height="0.011" /> + <rect class="cpu" x="346.529" y="1515.206" width="4.008" height="4.794" /> + <rect class="wait" x="358.555" y="1500.000" width="4.007" height="0.089" /> + <rect class="cpu" x="358.555" y="1509.531" width="4.007" height="10.469" /> + <rect class="wait" x="362.562" y="1500.000" width="4.007" height="0.084" /> + <rect class="cpu" x="362.562" y="1514.942" width="4.007" height="5.058" /> + <rect class="wait" x="366.569" y="1500.000" width="4.007" height="0.368" /> + <rect class="cpu" x="366.569" y="1506.189" width="4.007" height="13.811" /> + <rect class="wait" x="374.584" y="1500.000" width="4.006" height="1.127" /> + <rect class="cpu" x="374.584" y="1515.131" width="4.006" height="4.869" /> + <rect class="wait" x="470.784" y="1500.000" width="4.008" height="0.008" /> + <rect class="cpu" x="470.784" y="1516.764" width="4.008" height="3.236" /> + <rect class="wait" x="526.876" y="1500.000" width="4.007" height="5.695" /> + <rect class="cpu" x="526.876" y="1512.077" width="4.007" height="7.923" /> + <rect class="wait" x="530.883" y="1500.000" width="4.006" height="4.298" /> + <rect class="cpu" x="530.883" y="1504.794" width="4.006" height="15.206" /> + <rect class="wait" x="534.889" y="1500.000" width="4.006" height="0.030" /> + <rect class="cpu" x="534.889" y="1505.142" width="4.006" height="14.858" /> + <text x="347.521" y="1514.000">gnome-session [311] <tspan class="run">0.208s</tspan></text> + <line class="dot" x1="342.521" y1="1510.000" x2="322.483" y2="1510.000" /> + <line class="dot" x1="322.483" y1="1510.000" x2="322.483" y2="1500.000" /> + +<!-- bash [332] ppid=311 runtime=0.000s --> +<!-- bash [341] ppid=311 runtime=0.000s --> +<!-- gnome-session-c [367] ppid=311 runtime=0.027s --> + <rect class="ps" x="370.576" y="1520.000" width="4.008" height="20.000" /> + <text x="379.584" y="1534.000">gnome-session-c [367] <tspan class="run">0.027s</tspan></text> + <line class="dot" x1="370.576" y1="1530.000" x2="342.521" y2="1530.000" /> + +<!-- gnome-session-c [368] ppid=367 runtime=0.000s --> + <line class="dot" x1="370.576" y1="1530.000" x2="370.576" y2="1540.000" /> +<!-- start-pulseaudi [372] ppid=311 runtime=0.001s --> + <rect class="ps" x="378.590" y="1540.000" width="28.067" height="20.000" /> + <text x="411.656" y="1554.000">start-pulseaudi [372] <tspan class="run">0.001s</tspan></text> + <line class="dot" x1="378.590" y1="1550.000" x2="342.521" y2="1550.000" /> + +<!-- pulseaudio [381] ppid=372 runtime=0.000s --> +<!-- pulseaudio [384] ppid=381 runtime=0.000s --> + <line class="dot" x1="378.590" y1="1550.000" x2="378.590" y2="1560.000" /> +<!-- pulseaudio [385] ppid=384 runtime=0.096s --> + <rect class="ps" x="382.596" y="1560.000" width="1712.899" height="20.000" /> + <rect class="wait" x="382.596" y="1560.000" width="4.007" height="0.336" /> + <rect class="cpu" x="382.596" y="1567.734" width="4.007" height="12.266" /> + <rect class="wait" x="386.603" y="1560.000" width="4.007" height="0.006" /> + <rect class="cpu" x="386.603" y="1575.867" width="4.007" height="4.133" /> + <rect class="wait" x="390.610" y="1560.000" width="4.006" height="0.000" /> + <rect class="cpu" x="390.610" y="1576.110" width="4.006" height="3.890" /> + <rect class="wait" x="398.624" y="1560.000" width="4.021" height="0.005" /> + <rect class="cpu" x="398.624" y="1577.987" width="4.021" height="2.013" /> + <rect class="wait" x="402.645" y="1560.000" width="4.011" height="0.237" /> + <rect class="cpu" x="402.645" y="1572.928" width="4.011" height="7.072" /> + <rect class="wait" x="450.745" y="1560.000" width="4.007" height="0.024" /> + <rect class="cpu" x="450.745" y="1576.890" width="4.007" height="3.110" /> + <rect class="wait" x="454.752" y="1560.000" width="4.007" height="0.059" /> + <rect class="cpu" x="454.752" y="1573.075" width="4.007" height="6.925" /> + <text x="387.596" y="1574.000">pulseaudio [385] <tspan class="run">0.096s</tspan></text> + <line class="dot" x1="382.596" y1="1570.000" x2="378.590" y2="1570.000" /> + <line class="dot" x1="378.590" y1="1570.000" x2="378.590" y2="1560.000" /> + +<!-- pactl [398] ppid=372 runtime=0.000s --> +<!-- pactl [401] ppid=372 runtime=0.000s --> + <line class="dot" x1="378.590" y1="1570.000" x2="378.590" y2="1560.000" /> +<!-- gnome-keyring-d [373] ppid=311 runtime=0.000s --> +<!-- gnome-keyring-d [375] ppid=311 runtime=0.000s --> +<!-- gnome-settings- [378] ppid=311 runtime=0.562s --> + <rect class="ps" x="378.590" y="1580.000" width="1716.905" height="20.000" /> + <rect class="wait" x="378.590" y="1580.000" width="4.006" height="3.127" /> + <rect class="cpu" x="378.590" y="1586.993" width="4.006" height="13.007" /> + <rect class="wait" x="398.624" y="1580.000" width="4.021" height="0.035" /> + <rect class="cpu" x="398.624" y="1597.889" width="4.021" height="2.111" /> + <rect class="wait" x="402.645" y="1580.000" width="4.011" height="0.000" /> + <rect class="cpu" x="402.645" y="1597.724" width="4.011" height="2.276" /> + <rect class="wait" x="426.696" y="1580.000" width="4.006" height="0.000" /> + <rect class="cpu" x="426.696" y="1597.470" width="4.006" height="2.530" /> + <rect class="wait" x="430.702" y="1580.000" width="4.006" height="0.481" /> + <rect class="cpu" x="430.702" y="1583.133" width="4.006" height="16.867" /> + <rect class="wait" x="434.708" y="1580.000" width="4.014" height="0.102" /> + <rect class="cpu" x="434.708" y="1591.302" width="4.014" height="8.698" /> + <rect class="wait" x="470.784" y="1580.000" width="4.008" height="0.025" /> + <rect class="cpu" x="470.784" y="1588.447" width="4.008" height="11.553" /> + <rect class="wait" x="474.792" y="1580.000" width="4.007" height="0.329" /> + <rect class="cpu" x="474.792" y="1587.420" width="4.007" height="12.580" /> + <rect class="wait" x="490.819" y="1580.000" width="4.006" height="0.052" /> + <rect class="cpu" x="490.819" y="1581.130" width="4.006" height="18.870" /> + <rect class="wait" x="494.825" y="1580.000" width="4.006" height="0.021" /> + <rect class="cpu" x="494.825" y="1580.146" width="4.006" height="19.854" /> + <rect class="wait" x="498.831" y="1580.000" width="4.006" height="0.407" /> + <rect class="cpu" x="498.831" y="1581.082" width="4.006" height="18.918" /> + <rect class="wait" x="502.838" y="1580.000" width="4.006" height="2.388" /> + <rect class="cpu" x="502.838" y="1591.356" width="4.006" height="8.644" /> + <rect class="wait" x="506.844" y="1580.000" width="4.006" height="5.160" /> + <rect class="cpu" x="506.844" y="1597.733" width="4.006" height="2.267" /> + <rect class="wait" x="510.850" y="1580.000" width="4.008" height="6.511" /> + <rect class="cpu" x="510.850" y="1586.906" width="4.008" height="13.094" /> + <rect class="wait" x="514.858" y="1580.000" width="4.006" height="2.112" /> + <rect class="cpu" x="514.858" y="1582.294" width="4.006" height="17.706" /> + <rect class="wait" x="518.864" y="1580.000" width="4.006" height="2.600" /> + <rect class="cpu" x="518.864" y="1586.231" width="4.006" height="13.769" /> + <rect class="wait" x="522.870" y="1580.000" width="4.006" height="4.761" /> + <rect class="cpu" x="522.870" y="1593.022" width="4.006" height="6.978" /> + <rect class="wait" x="526.876" y="1580.000" width="4.007" height="2.200" /> + <rect class="cpu" x="526.876" y="1595.504" width="4.007" height="4.496" /> + <rect class="wait" x="530.883" y="1580.000" width="4.006" height="1.754" /> + <rect class="cpu" x="530.883" y="1597.251" width="4.006" height="2.749" /> + <rect class="wait" x="558.930" y="1580.000" width="4.006" height="4.381" /> + <rect class="cpu" x="558.930" y="1585.960" width="4.006" height="14.040" /> + <rect class="wait" x="562.936" y="1580.000" width="4.006" height="2.534" /> + <rect class="cpu" x="562.936" y="1583.557" width="4.006" height="16.443" /> + <rect class="wait" x="566.943" y="1580.000" width="4.006" height="0.275" /> + <rect class="cpu" x="566.943" y="1580.151" width="4.006" height="19.849" /> + <rect class="wait" x="570.949" y="1580.000" width="4.007" height="0.012" /> + <rect class="cpu" x="570.949" y="1589.995" width="4.007" height="10.005" /> + <rect class="wait" x="578.966" y="1580.000" width="4.007" height="0.307" /> + <rect class="cpu" x="578.966" y="1596.849" width="4.007" height="3.151" /> + <rect class="wait" x="1678.118" y="1580.000" width="4.008" height="0.598" /> + <rect class="cpu" x="1678.118" y="1597.743" width="4.008" height="2.257" /> + <text x="383.590" y="1594.000">gnome-settings- [378] <tspan class="run">0.562s</tspan></text> + <line class="dot" x1="378.590" y1="1590.000" x2="342.521" y2="1590.000" /> + +<!-- gnome-shell [506] ppid=311 runtime=3.107s --> + <rect class="ps" x="494.825" y="1600.000" width="1600.669" height="20.000" /> + <rect class="wait" x="494.825" y="1600.000" width="4.006" height="0.424" /> + <rect class="cpu" x="494.825" y="1602.826" width="4.006" height="17.174" /> + <rect class="wait" x="498.831" y="1600.000" width="4.006" height="0.876" /> + <rect class="cpu" x="498.831" y="1604.763" width="4.006" height="15.237" /> + <rect class="wait" x="502.838" y="1600.000" width="4.006" height="2.217" /> + <rect class="cpu" x="502.838" y="1619.054" width="4.006" height="0.946" /> + <rect class="wait" x="506.844" y="1600.000" width="4.006" height="1.149" /> + <rect class="cpu" x="506.844" y="1614.276" width="4.006" height="5.724" /> + <rect class="wait" x="510.850" y="1600.000" width="4.008" height="3.474" /> + <rect class="cpu" x="510.850" y="1605.674" width="4.008" height="14.326" /> + <rect class="wait" x="514.858" y="1600.000" width="4.006" height="8.304" /> + <rect class="cpu" x="514.858" y="1610.970" width="4.006" height="9.030" /> + <rect class="wait" x="518.864" y="1600.000" width="4.006" height="7.631" /> + <rect class="cpu" x="518.864" y="1607.700" width="4.006" height="12.300" /> + <rect class="wait" x="522.870" y="1600.000" width="4.006" height="4.776" /> + <rect class="cpu" x="522.870" y="1605.194" width="4.006" height="14.806" /> + <rect class="wait" x="526.876" y="1600.000" width="4.007" height="0.549" /> + <rect class="cpu" x="526.876" y="1601.002" width="4.007" height="18.998" /> + <rect class="wait" x="530.883" y="1600.000" width="4.006" height="5.918" /> + <rect class="cpu" x="530.883" y="1606.432" width="4.006" height="13.568" /> + <rect class="wait" x="534.889" y="1600.000" width="4.006" height="1.875" /> + <rect class="cpu" x="534.889" y="1601.254" width="4.006" height="18.746" /> + <rect class="wait" x="538.895" y="1600.000" width="4.007" height="0.851" /> + <rect class="cpu" x="538.895" y="1601.501" width="4.007" height="18.499" /> + <rect class="wait" x="542.902" y="1600.000" width="4.009" height="0.862" /> + <rect class="cpu" x="542.902" y="1603.626" width="4.009" height="16.374" /> + <rect class="wait" x="546.911" y="1600.000" width="4.006" height="0.583" /> + <rect class="cpu" x="546.911" y="1601.195" width="4.006" height="18.805" /> + <rect class="wait" x="550.917" y="1600.000" width="4.006" height="0.003" /> + <rect class="cpu" x="550.917" y="1617.474" width="4.006" height="2.526" /> + <rect class="wait" x="558.930" y="1600.000" width="4.006" height="2.229" /> + <rect class="cpu" x="558.930" y="1607.980" width="4.006" height="12.020" /> + <rect class="wait" x="562.936" y="1600.000" width="4.006" height="3.322" /> + <rect class="cpu" x="562.936" y="1603.272" width="4.006" height="16.728" /> + <rect class="wait" x="566.943" y="1600.000" width="4.006" height="1.108" /> + <rect class="cpu" x="566.943" y="1600.773" width="4.006" height="19.227" /> + <rect class="wait" x="570.949" y="1600.000" width="4.007" height="0.407" /> + <rect class="cpu" x="570.949" y="1600.647" width="4.007" height="19.353" /> + <rect class="wait" x="574.956" y="1600.000" width="4.010" height="0.585" /> + <rect class="cpu" x="574.956" y="1611.151" width="4.010" height="8.849" /> + <rect class="wait" x="578.966" y="1600.000" width="4.007" height="0.059" /> + <rect class="cpu" x="578.966" y="1603.916" width="4.007" height="16.084" /> + <rect class="wait" x="582.973" y="1600.000" width="4.008" height="0.247" /> + <rect class="cpu" x="582.973" y="1601.458" width="4.008" height="18.542" /> + <rect class="wait" x="586.981" y="1600.000" width="4.009" height="0.019" /> + <rect class="cpu" x="586.981" y="1617.214" width="4.009" height="2.786" /> + <rect class="wait" x="590.990" y="1600.000" width="4.008" height="0.033" /> + <rect class="cpu" x="590.990" y="1611.872" width="4.008" height="8.128" /> + <rect class="wait" x="594.998" y="1600.000" width="4.010" height="0.084" /> + <rect class="cpu" x="594.998" y="1601.900" width="4.010" height="18.100" /> + <rect class="wait" x="599.008" y="1600.000" width="4.006" height="0.649" /> + <rect class="cpu" x="599.008" y="1604.657" width="4.006" height="15.343" /> + <rect class="wait" x="603.014" y="1600.000" width="4.007" height="0.294" /> + <rect class="cpu" x="603.014" y="1600.699" width="4.007" height="19.301" /> + <rect class="wait" x="607.021" y="1600.000" width="4.009" height="0.118" /> + <rect class="cpu" x="607.021" y="1603.981" width="4.009" height="16.019" /> + <rect class="wait" x="611.030" y="1600.000" width="4.007" height="0.012" /> + <rect class="cpu" x="611.030" y="1616.405" width="4.007" height="3.595" /> + <rect class="wait" x="619.046" y="1600.000" width="4.008" height="0.040" /> + <rect class="cpu" x="619.046" y="1611.253" width="4.008" height="8.747" /> + <rect class="wait" x="623.054" y="1600.000" width="4.007" height="0.104" /> + <rect class="cpu" x="623.054" y="1603.340" width="4.007" height="16.660" /> + <rect class="wait" x="627.061" y="1600.000" width="4.007" height="0.142" /> + <rect class="cpu" x="627.061" y="1603.770" width="4.007" height="16.230" /> + <rect class="wait" x="631.068" y="1600.000" width="4.007" height="0.106" /> + <rect class="cpu" x="631.068" y="1603.195" width="4.007" height="16.805" /> + <rect class="wait" x="635.075" y="1600.000" width="4.009" height="0.356" /> + <rect class="cpu" x="635.075" y="1605.227" width="4.009" height="14.773" /> + <rect class="wait" x="639.084" y="1600.000" width="4.006" height="1.149" /> + <rect class="cpu" x="639.084" y="1602.928" width="4.006" height="17.072" /> + <rect class="wait" x="643.090" y="1600.000" width="4.007" height="4.780" /> + <rect class="cpu" x="643.090" y="1614.708" width="4.007" height="5.292" /> + <rect class="wait" x="647.097" y="1600.000" width="4.007" height="0.149" /> + <rect class="cpu" x="647.097" y="1602.266" width="4.007" height="17.734" /> + <rect class="wait" x="651.104" y="1600.000" width="4.007" height="1.686" /> + <rect class="cpu" x="651.104" y="1605.282" width="4.007" height="14.718" /> + <rect class="wait" x="655.111" y="1600.000" width="4.006" height="1.470" /> + <rect class="cpu" x="655.111" y="1602.662" width="4.006" height="17.338" /> + <rect class="wait" x="659.117" y="1600.000" width="4.008" height="0.045" /> + <rect class="cpu" x="659.117" y="1613.241" width="4.008" height="6.759" /> + <rect class="wait" x="663.125" y="1600.000" width="4.008" height="0.037" /> + <rect class="cpu" x="663.125" y="1614.938" width="4.008" height="5.062" /> + <rect class="wait" x="667.133" y="1600.000" width="4.012" height="0.029" /> + <rect class="cpu" x="667.133" y="1613.271" width="4.012" height="6.729" /> + <rect class="wait" x="671.145" y="1600.000" width="4.006" height="0.140" /> + <rect class="cpu" x="671.145" y="1604.080" width="4.006" height="15.920" /> + <rect class="wait" x="675.152" y="1600.000" width="4.009" height="0.022" /> + <rect class="cpu" x="675.152" y="1612.681" width="4.009" height="7.319" /> + <rect class="wait" x="679.161" y="1600.000" width="4.011" height="0.012" /> + <rect class="cpu" x="679.161" y="1611.617" width="4.011" height="8.383" /> + <rect class="wait" x="683.171" y="1600.000" width="4.009" height="0.039" /> + <rect class="cpu" x="683.171" y="1608.219" width="4.009" height="11.781" /> + <rect class="wait" x="687.180" y="1600.000" width="4.009" height="0.021" /> + <rect class="cpu" x="687.180" y="1613.445" width="4.009" height="6.555" /> + <rect class="wait" x="691.189" y="1600.000" width="4.010" height="0.002" /> + <rect class="cpu" x="691.189" y="1615.057" width="4.010" height="4.943" /> + <rect class="wait" x="695.200" y="1600.000" width="4.007" height="0.027" /> + <rect class="cpu" x="695.200" y="1609.274" width="4.007" height="10.726" /> + <rect class="wait" x="699.207" y="1600.000" width="4.010" height="0.018" /> + <rect class="cpu" x="699.207" y="1611.481" width="4.010" height="8.519" /> + <rect class="wait" x="703.216" y="1600.000" width="4.009" height="0.004" /> + <rect class="cpu" x="703.216" y="1612.914" width="4.009" height="7.086" /> + <rect class="wait" x="707.226" y="1600.000" width="4.009" height="0.025" /> + <rect class="cpu" x="707.226" y="1607.057" width="4.009" height="12.943" /> + <rect class="wait" x="711.235" y="1600.000" width="4.010" height="0.022" /> + <rect class="cpu" x="711.235" y="1613.129" width="4.010" height="6.871" /> + <rect class="wait" x="715.245" y="1600.000" width="4.014" height="0.005" /> + <rect class="cpu" x="715.245" y="1612.603" width="4.014" height="7.397" /> + <rect class="wait" x="719.258" y="1600.000" width="4.007" height="0.026" /> + <rect class="cpu" x="719.258" y="1607.545" width="4.007" height="12.455" /> + <rect class="wait" x="723.265" y="1600.000" width="4.008" height="0.020" /> + <rect class="cpu" x="723.265" y="1613.511" width="4.008" height="6.489" /> + <rect class="wait" x="727.273" y="1600.000" width="4.014" height="0.004" /> + <rect class="cpu" x="727.273" y="1613.327" width="4.014" height="6.673" /> + <rect class="wait" x="731.286" y="1600.000" width="4.009" height="0.014" /> + <rect class="cpu" x="731.286" y="1608.897" width="4.009" height="11.103" /> + <rect class="wait" x="735.295" y="1600.000" width="4.009" height="0.073" /> + <rect class="cpu" x="735.295" y="1608.831" width="4.009" height="11.169" /> + <rect class="wait" x="739.304" y="1600.000" width="4.006" height="0.000" /> + <rect class="cpu" x="739.304" y="1617.966" width="4.006" height="2.034" /> + <rect class="wait" x="743.310" y="1600.000" width="4.013" height="0.014" /> + <rect class="cpu" x="743.310" y="1607.834" width="4.013" height="12.166" /> + <rect class="wait" x="747.323" y="1600.000" width="4.007" height="0.026" /> + <rect class="cpu" x="747.323" y="1608.211" width="4.007" height="11.789" /> + <rect class="wait" x="751.330" y="1600.000" width="4.010" height="0.025" /> + <rect class="cpu" x="751.330" y="1616.814" width="4.010" height="3.186" /> + <rect class="wait" x="755.340" y="1600.000" width="4.010" height="0.064" /> + <rect class="cpu" x="755.340" y="1610.959" width="4.010" height="9.041" /> + <rect class="wait" x="759.350" y="1600.000" width="4.009" height="0.027" /> + <rect class="cpu" x="759.350" y="1608.055" width="4.009" height="11.945" /> + <rect class="wait" x="763.359" y="1600.000" width="4.008" height="0.028" /> + <rect class="cpu" x="763.359" y="1612.572" width="4.008" height="7.428" /> + <rect class="wait" x="767.367" y="1600.000" width="4.014" height="0.000" /> + <rect class="cpu" x="767.367" y="1616.174" width="4.014" height="3.826" /> + <rect class="wait" x="771.381" y="1600.000" width="4.009" height="0.018" /> + <rect class="cpu" x="771.381" y="1608.839" width="4.009" height="11.161" /> + <rect class="wait" x="775.390" y="1600.000" width="4.006" height="0.022" /> + <rect class="cpu" x="775.390" y="1612.844" width="4.006" height="7.156" /> + <rect class="wait" x="779.396" y="1600.000" width="4.010" height="0.019" /> + <rect class="cpu" x="779.396" y="1611.893" width="4.010" height="8.107" /> + <rect class="wait" x="783.406" y="1600.000" width="4.009" height="0.022" /> + <rect class="cpu" x="783.406" y="1607.844" width="4.009" height="12.156" /> + <rect class="wait" x="787.415" y="1600.000" width="4.007" height="0.027" /> + <rect class="cpu" x="787.415" y="1609.209" width="4.007" height="10.791" /> + <rect class="wait" x="791.422" y="1600.000" width="4.006" height="0.015" /> + <rect class="cpu" x="791.422" y="1615.583" width="4.006" height="4.417" /> + <rect class="wait" x="795.428" y="1600.000" width="4.008" height="0.004" /> + <rect class="cpu" x="795.428" y="1611.424" width="4.008" height="8.576" /> + <rect class="wait" x="799.436" y="1600.000" width="4.008" height="0.032" /> + <rect class="cpu" x="799.436" y="1606.571" width="4.008" height="13.429" /> + <rect class="wait" x="803.444" y="1600.000" width="4.011" height="0.075" /> + <rect class="cpu" x="803.444" y="1607.931" width="4.011" height="12.069" /> + <rect class="wait" x="807.454" y="1600.000" width="4.006" height="0.064" /> + <rect class="cpu" x="807.454" y="1614.154" width="4.006" height="5.846" /> + <rect class="wait" x="811.460" y="1600.000" width="4.010" height="0.022" /> + <rect class="cpu" x="811.460" y="1607.928" width="4.010" height="12.072" /> + <rect class="wait" x="815.470" y="1600.000" width="4.007" height="0.029" /> + <rect class="cpu" x="815.470" y="1609.015" width="4.007" height="10.985" /> + <rect class="wait" x="819.477" y="1600.000" width="4.006" height="0.028" /> + <rect class="cpu" x="819.477" y="1616.480" width="4.006" height="3.520" /> + <rect class="wait" x="823.483" y="1600.000" width="4.008" height="0.005" /> + <rect class="cpu" x="823.483" y="1611.444" width="4.008" height="8.556" /> + <rect class="wait" x="827.492" y="1600.000" width="4.009" height="0.015" /> + <rect class="cpu" x="827.492" y="1610.505" width="4.009" height="9.495" /> + <rect class="wait" x="831.500" y="1600.000" width="4.010" height="0.019" /> + <rect class="cpu" x="831.500" y="1608.376" width="4.010" height="11.624" /> + <rect class="wait" x="835.510" y="1600.000" width="4.007" height="0.016" /> + <rect class="cpu" x="835.510" y="1616.821" width="4.007" height="3.179" /> + <rect class="wait" x="839.517" y="1600.000" width="4.011" height="0.007" /> + <rect class="cpu" x="839.517" y="1611.659" width="4.011" height="8.341" /> + <rect class="wait" x="843.528" y="1600.000" width="4.010" height="0.025" /> + <rect class="cpu" x="843.528" y="1610.662" width="4.010" height="9.338" /> + <rect class="wait" x="847.538" y="1600.000" width="4.006" height="0.018" /> + <rect class="cpu" x="847.538" y="1608.944" width="4.006" height="11.056" /> + <rect class="wait" x="851.544" y="1600.000" width="4.007" height="0.021" /> + <rect class="cpu" x="851.544" y="1611.926" width="4.007" height="8.074" /> + <rect class="wait" x="855.550" y="1600.000" width="4.006" height="0.019" /> + <rect class="cpu" x="855.550" y="1604.022" width="4.006" height="15.978" /> + <rect class="wait" x="859.557" y="1600.000" width="4.006" height="0.016" /> + <rect class="cpu" x="859.557" y="1600.137" width="4.006" height="19.863" /> + <rect class="wait" x="863.563" y="1600.000" width="4.007" height="1.626" /> + <rect class="cpu" x="863.563" y="1602.006" width="4.007" height="17.994" /> + <rect class="wait" x="867.570" y="1600.000" width="4.015" height="5.201" /> + <rect class="cpu" x="867.570" y="1616.303" width="4.015" height="3.697" /> + <rect class="wait" x="871.585" y="1600.000" width="4.006" height="0.031" /> + <rect class="cpu" x="871.585" y="1612.116" width="4.006" height="7.884" /> + <rect class="wait" x="875.591" y="1600.000" width="4.006" height="0.223" /> + <rect class="cpu" x="875.591" y="1603.123" width="4.006" height="16.877" /> + <rect class="wait" x="879.598" y="1600.000" width="4.007" height="0.033" /> + <rect class="cpu" x="879.598" y="1605.575" width="4.007" height="14.425" /> + <rect class="wait" x="883.605" y="1600.000" width="4.006" height="0.060" /> + <rect class="cpu" x="883.605" y="1602.294" width="4.006" height="17.706" /> + <rect class="wait" x="887.611" y="1600.000" width="4.006" height="0.077" /> + <rect class="cpu" x="887.611" y="1602.475" width="4.006" height="17.525" /> + <rect class="wait" x="891.617" y="1600.000" width="4.009" height="0.279" /> + <rect class="cpu" x="891.617" y="1607.613" width="4.009" height="12.387" /> + <rect class="wait" x="895.626" y="1600.000" width="4.006" height="0.216" /> + <rect class="cpu" x="895.626" y="1607.770" width="4.006" height="12.230" /> + <rect class="wait" x="899.632" y="1600.000" width="4.006" height="0.019" /> + <rect class="cpu" x="899.632" y="1601.340" width="4.006" height="18.660" /> + <rect class="wait" x="903.639" y="1600.000" width="4.006" height="0.015" /> + <rect class="cpu" x="903.639" y="1600.919" width="4.006" height="19.081" /> + <rect class="wait" x="907.644" y="1600.000" width="4.006" height="0.040" /> + <rect class="cpu" x="907.644" y="1603.231" width="4.006" height="16.769" /> + <rect class="wait" x="911.650" y="1600.000" width="4.006" height="0.268" /> + <rect class="cpu" x="911.650" y="1607.438" width="4.006" height="12.562" /> + <rect class="wait" x="915.656" y="1600.000" width="4.007" height="0.123" /> + <rect class="cpu" x="915.656" y="1606.526" width="4.007" height="13.474" /> + <rect class="wait" x="919.664" y="1600.000" width="4.007" height="0.022" /> + <rect class="cpu" x="919.664" y="1614.685" width="4.007" height="5.315" /> + <rect class="wait" x="923.671" y="1600.000" width="4.008" height="0.100" /> + <rect class="cpu" x="923.671" y="1612.431" width="4.008" height="7.569" /> + <rect class="wait" x="927.678" y="1600.000" width="4.011" height="0.019" /> + <rect class="cpu" x="927.678" y="1616.458" width="4.011" height="3.542" /> + <rect class="wait" x="931.689" y="1600.000" width="4.008" height="0.028" /> + <rect class="cpu" x="931.689" y="1615.772" width="4.008" height="4.228" /> + <rect class="wait" x="935.697" y="1600.000" width="4.009" height="0.020" /> + <rect class="cpu" x="935.697" y="1615.930" width="4.009" height="4.070" /> + <rect class="wait" x="939.706" y="1600.000" width="4.010" height="0.056" /> + <rect class="cpu" x="939.706" y="1616.281" width="4.010" height="3.719" /> + <rect class="wait" x="943.717" y="1600.000" width="4.008" height="0.028" /> + <rect class="cpu" x="943.717" y="1614.971" width="4.008" height="5.029" /> + <rect class="wait" x="947.725" y="1600.000" width="4.008" height="0.021" /> + <rect class="cpu" x="947.725" y="1616.314" width="4.008" height="3.686" /> + <rect class="wait" x="951.733" y="1600.000" width="4.006" height="0.041" /> + <rect class="cpu" x="951.733" y="1613.539" width="4.006" height="6.461" /> + <rect class="wait" x="955.739" y="1600.000" width="4.008" height="0.029" /> + <rect class="cpu" x="955.739" y="1611.423" width="4.008" height="8.577" /> + <rect class="wait" x="959.747" y="1600.000" width="4.011" height="0.018" /> + <rect class="cpu" x="959.747" y="1615.062" width="4.011" height="4.938" /> + <rect class="wait" x="963.758" y="1600.000" width="4.008" height="0.050" /> + <rect class="cpu" x="963.758" y="1612.723" width="4.008" height="7.277" /> + <rect class="wait" x="967.766" y="1600.000" width="4.007" height="0.025" /> + <rect class="cpu" x="967.766" y="1615.925" width="4.007" height="4.075" /> + <rect class="wait" x="971.773" y="1600.000" width="4.010" height="0.043" /> + <rect class="cpu" x="971.773" y="1613.813" width="4.010" height="6.187" /> + <rect class="wait" x="975.783" y="1600.000" width="4.014" height="0.059" /> + <rect class="cpu" x="975.783" y="1612.125" width="4.014" height="7.875" /> + <rect class="wait" x="979.797" y="1600.000" width="4.009" height="0.027" /> + <rect class="cpu" x="979.797" y="1611.786" width="4.009" height="8.214" /> + <rect class="wait" x="983.805" y="1600.000" width="4.009" height="0.053" /> + <rect class="cpu" x="983.805" y="1612.375" width="4.009" height="7.625" /> + <rect class="wait" x="987.814" y="1600.000" width="4.014" height="0.031" /> + <rect class="cpu" x="987.814" y="1615.075" width="4.014" height="4.925" /> + <rect class="wait" x="991.828" y="1600.000" width="4.010" height="0.042" /> + <rect class="cpu" x="991.828" y="1612.658" width="4.010" height="7.342" /> + <rect class="wait" x="995.837" y="1600.000" width="4.014" height="0.020" /> + <rect class="cpu" x="995.837" y="1613.041" width="4.014" height="6.959" /> + <rect class="wait" x="999.852" y="1600.000" width="4.015" height="0.045" /> + <rect class="cpu" x="999.852" y="1612.932" width="4.015" height="7.068" /> + <rect class="wait" x="1003.866" y="1600.000" width="4.010" height="0.030" /> + <rect class="cpu" x="1003.866" y="1611.843" width="4.010" height="8.157" /> + <rect class="wait" x="1007.876" y="1600.000" width="4.014" height="0.030" /> + <rect class="cpu" x="1007.876" y="1616.534" width="4.014" height="3.466" /> + <rect class="wait" x="1011.890" y="1600.000" width="4.009" height="0.042" /> + <rect class="cpu" x="1011.890" y="1615.861" width="4.009" height="4.139" /> + <rect class="wait" x="1015.900" y="1600.000" width="4.014" height="0.037" /> + <rect class="cpu" x="1015.900" y="1615.675" width="4.014" height="4.325" /> + <rect class="wait" x="1019.914" y="1600.000" width="4.014" height="0.030" /> + <rect class="cpu" x="1019.914" y="1615.355" width="4.014" height="4.645" /> + <rect class="wait" x="1023.928" y="1600.000" width="4.010" height="0.029" /> + <rect class="cpu" x="1023.928" y="1613.734" width="4.010" height="6.266" /> + <rect class="wait" x="1027.938" y="1600.000" width="4.009" height="0.072" /> + <rect class="cpu" x="1027.938" y="1606.981" width="4.009" height="13.019" /> + <rect class="wait" x="1031.947" y="1600.000" width="4.008" height="0.040" /> + <rect class="cpu" x="1031.947" y="1613.520" width="4.008" height="6.480" /> + <rect class="wait" x="1035.955" y="1600.000" width="4.008" height="0.037" /> + <rect class="cpu" x="1035.955" y="1615.756" width="4.008" height="4.244" /> + <rect class="wait" x="1039.963" y="1600.000" width="4.006" height="0.013" /> + <rect class="cpu" x="1039.963" y="1603.398" width="4.006" height="16.602" /> + <rect class="wait" x="1043.969" y="1600.000" width="4.007" height="2.247" /> + <rect class="cpu" x="1043.969" y="1602.803" width="4.007" height="17.197" /> + <rect class="wait" x="1047.976" y="1600.000" width="4.007" height="0.232" /> + <rect class="cpu" x="1047.976" y="1609.069" width="4.007" height="10.931" /> + <rect class="wait" x="1051.984" y="1600.000" width="4.006" height="0.032" /> + <rect class="cpu" x="1051.984" y="1608.515" width="4.006" height="11.485" /> + <rect class="wait" x="1055.990" y="1600.000" width="4.011" height="0.194" /> + <rect class="cpu" x="1055.990" y="1607.859" width="4.011" height="12.141" /> + <rect class="wait" x="1060.001" y="1600.000" width="4.007" height="0.139" /> + <rect class="cpu" x="1060.001" y="1609.904" width="4.007" height="10.096" /> + <rect class="wait" x="1064.008" y="1600.000" width="4.006" height="0.370" /> + <rect class="cpu" x="1064.008" y="1602.578" width="4.006" height="17.422" /> + <rect class="wait" x="1068.014" y="1600.000" width="4.006" height="0.450" /> + <rect class="cpu" x="1068.014" y="1614.765" width="4.006" height="5.235" /> + <rect class="wait" x="1072.020" y="1600.000" width="4.007" height="0.108" /> + <rect class="cpu" x="1072.020" y="1611.254" width="4.007" height="8.746" /> + <rect class="wait" x="1076.027" y="1600.000" width="4.013" height="0.104" /> + <rect class="cpu" x="1076.027" y="1614.980" width="4.013" height="5.020" /> + <rect class="wait" x="1080.040" y="1600.000" width="4.008" height="0.025" /> + <rect class="cpu" x="1080.040" y="1613.535" width="4.008" height="6.465" /> + <rect class="wait" x="1084.048" y="1600.000" width="4.010" height="0.098" /> + <rect class="cpu" x="1084.048" y="1608.444" width="4.010" height="11.556" /> + <rect class="wait" x="1088.058" y="1600.000" width="4.014" height="0.012" /> + <rect class="cpu" x="1088.058" y="1615.577" width="4.014" height="4.423" /> + <rect class="wait" x="1244.592" y="1600.000" width="4.014" height="0.000" /> + <rect class="cpu" x="1244.592" y="1616.801" width="4.014" height="3.199" /> + <text x="499.825" y="1614.000">gnome-shell [506] <tspan class="run">3.107s</tspan></text> + <line class="dot" x1="494.825" y1="1610.000" x2="342.521" y2="1610.000" /> + +<!-- gnome-terminal [626] ppid=506 runtime=0.207s --> + <rect class="ps" x="1039.963" y="1620.000" width="1055.532" height="20.000" /> + <rect class="wait" x="1039.963" y="1620.000" width="4.006" height="0.232" /> + <rect class="cpu" x="1039.963" y="1626.856" width="4.006" height="13.144" /> + <rect class="wait" x="1043.969" y="1620.000" width="4.007" height="0.193" /> + <rect class="cpu" x="1043.969" y="1620.392" width="4.007" height="19.608" /> + <rect class="wait" x="1047.976" y="1620.000" width="4.007" height="0.367" /> + <rect class="cpu" x="1047.976" y="1631.165" width="4.007" height="8.835" /> + <rect class="wait" x="1051.984" y="1620.000" width="4.006" height="0.192" /> + <rect class="cpu" x="1051.984" y="1627.087" width="4.006" height="12.913" /> + <rect class="wait" x="1055.990" y="1620.000" width="4.011" height="0.156" /> + <rect class="cpu" x="1055.990" y="1626.261" width="4.011" height="13.739" /> + <rect class="wait" x="1060.001" y="1620.000" width="4.007" height="0.116" /> + <rect class="cpu" x="1060.001" y="1627.638" width="4.007" height="12.362" /> + <rect class="wait" x="1064.008" y="1620.000" width="4.006" height="0.428" /> + <rect class="cpu" x="1064.008" y="1627.684" width="4.006" height="12.316" /> + <text x="1044.963" y="1634.000">gnome-terminal [626] <tspan class="run">0.207s</tspan></text> + <line class="dot" x1="1039.963" y1="1630.000" x2="494.825" y2="1630.000" /> + <line class="dot" x1="494.825" y1="1630.000" x2="494.825" y2="1620.000" /> + +<!-- gnome-pty-helpe [632] ppid=626 runtime=0.000s --> +<!-- bash [633] ppid=626 runtime=0.070s --> + <rect class="ps" x="1068.014" y="1640.000" width="1027.481" height="20.000" /> + <rect class="wait" x="1068.014" y="1640.000" width="4.006" height="0.127" /> + <rect class="cpu" x="1068.014" y="1646.365" width="4.006" height="13.635" /> + <rect class="wait" x="1072.020" y="1640.000" width="4.007" height="0.209" /> + <rect class="cpu" x="1072.020" y="1647.650" width="4.007" height="12.350" /> + <rect class="wait" x="1076.027" y="1640.000" width="4.013" height="0.109" /> + <rect class="cpu" x="1076.027" y="1651.014" width="4.013" height="8.986" /> + <text x="1073.014" y="1654.000">bash [633] <tspan class="run">0.070s</tspan></text> + <line class="dot" x1="1068.014" y1="1650.000" x2="1039.963" y2="1650.000" /> + <line class="dot" x1="1039.963" y1="1650.000" x2="1039.963" y2="1640.000" /> + +<!-- bash [643] ppid=633 runtime=0.000s --> + <line class="dot" x1="1068.014" y1="1650.000" x2="1068.014" y2="1660.000" /> +<!-- canberra-gtk-pl [511] ppid=311 runtime=0.058s --> + <rect class="ps" x="502.838" y="1660.000" width="16.026" height="20.000" /> + <rect class="wait" x="502.838" y="1660.000" width="4.006" height="1.232" /> + <rect class="cpu" x="502.838" y="1674.738" width="4.006" height="5.262" /> + <rect class="wait" x="506.844" y="1660.000" width="4.006" height="3.799" /> + <rect class="cpu" x="506.844" y="1678.139" width="4.006" height="1.861" /> + <rect class="wait" x="510.850" y="1660.000" width="4.008" height="9.701" /> + <rect class="cpu" x="510.850" y="1671.014" width="4.008" height="8.986" /> + <text x="523.864" y="1674.000">canberra-gtk-pl [511] <tspan class="run">0.058s</tspan></text> + <line class="dot" x1="502.838" y1="1670.000" x2="342.521" y2="1670.000" /> + +<!-- evolution-alarm [512] ppid=311 runtime=0.173s --> + <rect class="ps" x="502.838" y="1680.000" width="1592.657" height="20.000" /> + <rect class="wait" x="502.838" y="1680.000" width="4.006" height="5.359" /> + <rect class="cpu" x="502.838" y="1686.566" width="4.006" height="13.434" /> + <rect class="wait" x="506.844" y="1680.000" width="4.006" height="0.930" /> + <rect class="cpu" x="506.844" y="1690.626" width="4.006" height="9.374" /> + <rect class="wait" x="510.850" y="1680.000" width="4.008" height="2.936" /> + <rect class="cpu" x="510.850" y="1691.092" width="4.008" height="8.908" /> + <rect class="wait" x="530.883" y="1680.000" width="4.006" height="1.186" /> + <rect class="cpu" x="530.883" y="1688.745" width="4.006" height="11.255" /> + <rect class="wait" x="534.889" y="1680.000" width="4.006" height="0.197" /> + <rect class="cpu" x="534.889" y="1687.621" width="4.006" height="12.379" /> + <rect class="wait" x="558.930" y="1680.000" width="4.006" height="5.010" /> + <rect class="cpu" x="558.930" y="1687.859" width="4.006" height="12.141" /> + <rect class="wait" x="562.936" y="1680.000" width="4.006" height="3.235" /> + <rect class="cpu" x="562.936" y="1685.952" width="4.006" height="14.048" /> + <text x="507.838" y="1694.000">evolution-alarm [512] <tspan class="run">0.173s</tspan></text> + <line class="dot" x1="502.838" y1="1690.000" x2="342.521" y2="1690.000" /> + <line class="dot" x1="342.521" y1="1690.000" x2="342.521" y2="1520.000" /> + +<!-- modem-manager [276] ppid=1 runtime=0.123s --> + <rect class="ps" x="206.275" y="1700.000" width="1889.220" height="20.000" /> + <rect class="wait" x="206.275" y="1700.000" width="4.006" height="0.046" /> + <rect class="cpu" x="206.275" y="1714.685" width="4.006" height="5.315" /> + <rect class="wait" x="218.294" y="1700.000" width="4.007" height="0.103" /> + <rect class="cpu" x="218.294" y="1716.550" width="4.007" height="3.450" /> + <rect class="wait" x="438.722" y="1700.000" width="4.008" height="2.694" /> + <rect class="cpu" x="438.722" y="1719.284" width="4.008" height="0.716" /> + <rect class="wait" x="498.831" y="1700.000" width="4.006" height="0.213" /> + <rect class="cpu" x="498.831" y="1717.921" width="4.006" height="2.079" /> + <rect class="wait" x="799.436" y="1700.000" width="4.008" height="0.242" /> + <rect class="cpu" x="799.436" y="1708.504" width="4.008" height="11.496" /> + <rect class="wait" x="803.444" y="1700.000" width="4.011" height="0.039" /> + <rect class="cpu" x="803.444" y="1708.834" width="4.011" height="11.166" /> + <rect class="wait" x="807.454" y="1700.000" width="4.006" height="0.019" /> + <rect class="cpu" x="807.454" y="1711.319" width="4.006" height="8.681" /> + <text x="211.275" y="1714.000">modem-manager [276] <tspan class="run">0.123s</tspan></text> + <line class="dot" x1="206.275" y1="1710.000" x2="101.950" y2="1710.000" /> + +<!-- bluetoothd [277] ppid=1 runtime=0.004s --> + <rect class="ps" x="206.275" y="1720.000" width="1889.220" height="20.000" /> + <text x="211.275" y="1734.000">bluetoothd [277] <tspan class="run">0.004s</tspan></text> + <line class="dot" x1="206.275" y1="1730.000" x2="101.950" y2="1730.000" /> + +<!-- accounts-daemon [307] ppid=1 runtime=0.093s --> + <rect class="ps" x="322.483" y="1740.000" width="1773.011" height="20.000" /> + <rect class="wait" x="322.483" y="1740.000" width="4.008" height="0.909" /> + <rect class="cpu" x="322.483" y="1751.378" width="4.008" height="8.622" /> + <rect class="wait" x="326.491" y="1740.000" width="4.009" height="0.065" /> + <rect class="cpu" x="326.491" y="1741.712" width="4.009" height="18.288" /> + <rect class="wait" x="330.500" y="1740.000" width="4.006" height="0.053" /> + <rect class="cpu" x="330.500" y="1743.600" width="4.006" height="16.400" /> + <text x="327.483" y="1754.000">accounts-daemon [307] <tspan class="run">0.093s</tspan></text> + <line class="dot" x1="322.483" y1="1750.000" x2="101.950" y2="1750.000" /> + +<!-- dbus-launch [320] ppid=1 runtime=0.000s --> +<!-- dbus-daemon [321] ppid=1 runtime=0.123s --> + <rect class="ps" x="346.529" y="1760.000" width="1748.965" height="20.000" /> + <rect class="wait" x="366.569" y="1760.000" width="4.007" height="0.238" /> + <rect class="cpu" x="366.569" y="1775.403" width="4.007" height="4.597" /> + <rect class="wait" x="378.590" y="1760.000" width="4.006" height="0.143" /> + <rect class="cpu" x="378.590" y="1777.197" width="4.006" height="2.803" /> + <rect class="wait" x="486.814" y="1760.000" width="4.006" height="1.507" /> + <rect class="cpu" x="486.814" y="1777.744" width="4.006" height="2.256" /> + <rect class="wait" x="530.883" y="1760.000" width="4.006" height="3.954" /> + <rect class="cpu" x="530.883" y="1778.147" width="4.006" height="1.853" /> + <rect class="wait" x="542.902" y="1760.000" width="4.009" height="2.549" /> + <rect class="cpu" x="542.902" y="1777.715" width="4.009" height="2.285" /> + <rect class="wait" x="558.930" y="1760.000" width="4.006" height="2.805" /> + <rect class="cpu" x="558.930" y="1778.621" width="4.006" height="1.379" /> + <rect class="wait" x="615.037" y="1760.000" width="4.009" height="1.241" /> + <rect class="cpu" x="615.037" y="1777.781" width="4.009" height="2.219" /> + <rect class="wait" x="623.054" y="1760.000" width="4.007" height="0.007" /> + <rect class="cpu" x="623.054" y="1776.700" width="4.007" height="3.300" /> + <rect class="wait" x="647.097" y="1760.000" width="4.007" height="1.985" /> + <rect class="cpu" x="647.097" y="1777.350" width="4.007" height="2.650" /> + <rect class="wait" x="651.104" y="1760.000" width="4.007" height="0.835" /> + <rect class="cpu" x="651.104" y="1777.964" width="4.007" height="2.036" /> + <rect class="wait" x="655.111" y="1760.000" width="4.006" height="0.438" /> + <rect class="cpu" x="655.111" y="1777.687" width="4.006" height="2.313" /> + <rect class="wait" x="1858.668" y="1760.000" width="4.011" height="2.716" /> + <rect class="cpu" x="1858.668" y="1778.398" width="4.011" height="1.602" /> + <text x="351.529" y="1774.000">dbus-daemon [321] <tspan class="run">0.123s</tspan></text> + <line class="dot" x1="346.529" y1="1770.000" x2="101.950" y2="1770.000" /> + +<!-- dbus-daemon [429] ppid=321 runtime=0.000s --> +<!-- gvfsd [430] ppid=429 runtime=0.005s --> + <rect class="ps" x="430.702" y="1780.000" width="1664.793" height="20.000" /> + <text x="435.702" y="1794.000">gvfsd [430] <tspan class="run">0.005s</tspan></text> + <line class="dot" x1="430.702" y1="1790.000" x2="346.529" y2="1790.000" /> + <line class="dot" x1="346.529" y1="1790.000" x2="346.529" y2="1780.000" /> + +<!-- dbus-daemon [469] ppid=321 runtime=0.000s --> +<!-- gvfs-udisks2-vo [470] ppid=469 runtime=0.013s --> + <rect class="ps" x="478.799" y="1800.000" width="1616.696" height="20.000" /> + <rect class="wait" x="486.814" y="1800.000" width="4.006" height="0.310" /> + <rect class="cpu" x="486.814" y="1815.572" width="4.006" height="4.428" /> + <text x="483.799" y="1814.000">gvfs-udisks2-vo [470] <tspan class="run">0.013s</tspan></text> + <line class="dot" x1="478.799" y1="1810.000" x2="346.529" y2="1810.000" /> + <line class="dot" x1="346.529" y1="1810.000" x2="346.529" y2="1780.000" /> + +<!-- dbus-daemon [529] ppid=321 runtime=0.000s --> +<!-- evolution-sourc [530] ppid=529 runtime=0.078s --> + <rect class="ps" x="518.864" y="1820.000" width="1576.631" height="20.000" /> + <rect class="wait" x="518.864" y="1820.000" width="4.006" height="6.626" /> + <rect class="cpu" x="518.864" y="1826.916" width="4.006" height="13.084" /> + <rect class="wait" x="522.870" y="1820.000" width="4.006" height="3.836" /> + <rect class="cpu" x="522.870" y="1827.573" width="4.006" height="12.427" /> + <rect class="wait" x="526.876" y="1820.000" width="4.007" height="0.947" /> + <rect class="cpu" x="526.876" y="1830.407" width="4.007" height="9.593" /> + <text x="523.864" y="1834.000">evolution-sourc [530] <tspan class="run">0.078s</tspan></text> + <line class="dot" x1="518.864" y1="1830.000" x2="346.529" y2="1830.000" /> + <line class="dot" x1="346.529" y1="1830.000" x2="346.529" y2="1780.000" /> + +<!-- dbus-daemon [546] ppid=321 runtime=0.000s --> +<!-- goa-daemon [547] ppid=546 runtime=0.011s --> + <rect class="ps" x="530.883" y="1840.000" width="1564.612" height="20.000" /> + <rect class="wait" x="530.883" y="1840.000" width="4.006" height="0.763" /> + <rect class="cpu" x="530.883" y="1854.741" width="4.006" height="5.259" /> + <text x="535.883" y="1854.000">goa-daemon [547] <tspan class="run">0.011s</tspan></text> + <line class="dot" x1="530.883" y1="1850.000" x2="346.529" y2="1850.000" /> + <line class="dot" x1="346.529" y1="1850.000" x2="346.529" y2="1780.000" /> + +<!-- dbus-daemon [551] ppid=321 runtime=0.000s --> +<!-- evolution-calen [552] ppid=551 runtime=0.132s --> + <rect class="ps" x="538.895" y="1860.000" width="1556.599" height="20.000" /> + <rect class="wait" x="538.895" y="1860.000" width="4.007" height="5.129" /> + <rect class="cpu" x="538.895" y="1864.704" width="4.007" height="15.296" /> + <rect class="wait" x="542.902" y="1860.000" width="4.009" height="0.250" /> + <rect class="cpu" x="542.902" y="1872.727" width="4.009" height="7.273" /> + <rect class="wait" x="546.911" y="1860.000" width="4.006" height="0.612" /> + <rect class="cpu" x="546.911" y="1861.540" width="4.006" height="18.460" /> + <rect class="wait" x="550.917" y="1860.000" width="4.006" height="0.069" /> + <rect class="cpu" x="550.917" y="1860.381" width="4.006" height="19.619" /> + <rect class="wait" x="558.930" y="1860.000" width="4.006" height="3.056" /> + <rect class="cpu" x="558.930" y="1879.205" width="4.006" height="0.795" /> + <text x="543.895" y="1874.000">evolution-calen [552] <tspan class="run">0.132s</tspan></text> + <line class="dot" x1="538.895" y1="1870.000" x2="346.529" y2="1870.000" /> + <line class="dot" x1="346.529" y1="1870.000" x2="346.529" y2="1780.000" /> + +<!-- dbus-daemon [578] ppid=321 runtime=0.000s --> +<!-- gnome-shell-cal [579] ppid=578 runtime=0.031s --> + <rect class="ps" x="590.990" y="1880.000" width="1504.505" height="20.000" /> + <rect class="wait" x="590.990" y="1880.000" width="4.008" height="0.038" /> + <rect class="cpu" x="590.990" y="1892.481" width="4.008" height="7.519" /> + <rect class="wait" x="599.008" y="1880.000" width="4.006" height="0.400" /> + <rect class="cpu" x="599.008" y="1897.870" width="4.006" height="2.130" /> + <rect class="wait" x="615.037" y="1880.000" width="4.009" height="1.284" /> + <rect class="cpu" x="615.037" y="1896.496" width="4.009" height="3.504" /> + <text x="595.990" y="1894.000">gnome-shell-cal [579] <tspan class="run">0.031s</tspan></text> + <line class="dot" x1="590.990" y1="1890.000" x2="346.529" y2="1890.000" /> + <line class="dot" x1="346.529" y1="1890.000" x2="346.529" y2="1780.000" /> + +<!-- dbus-daemon [588] ppid=321 runtime=0.000s --> +<!-- nautilus [589] ppid=588 runtime=0.092s --> + <rect class="ps" x="643.090" y="1900.000" width="1215.578" height="20.000" /> + <rect class="wait" x="643.090" y="1900.000" width="4.007" height="1.194" /> + <rect class="cpu" x="643.090" y="1914.851" width="4.007" height="5.149" /> + <rect class="wait" x="647.097" y="1900.000" width="4.007" height="1.206" /> + <rect class="cpu" x="647.097" y="1904.161" width="4.007" height="15.839" /> + <rect class="wait" x="651.104" y="1900.000" width="4.007" height="1.599" /> + <rect class="cpu" x="651.104" y="1902.255" width="4.007" height="17.745" /> + <rect class="wait" x="655.111" y="1900.000" width="4.006" height="7.055" /> + <rect class="cpu" x="655.111" y="1913.289" width="4.006" height="6.711" /> + <text x="648.090" y="1914.000">nautilus [589] <tspan class="run">0.092s</tspan></text> + <line class="dot" x1="643.090" y1="1910.000" x2="346.529" y2="1910.000" /> + <line class="dot" x1="346.529" y1="1910.000" x2="346.529" y2="1780.000" /> + +<!-- dbus-daemon [590] ppid=321 runtime=0.000s --> +<!-- gnome-contacts- [591] ppid=590 runtime=0.043s --> + <rect class="ps" x="643.090" y="1920.000" width="1006.925" height="20.000" /> + <rect class="wait" x="643.090" y="1920.000" width="4.007" height="0.020" /> + <rect class="cpu" x="643.090" y="1930.913" width="4.007" height="9.087" /> + <rect class="wait" x="647.097" y="1920.000" width="4.007" height="0.308" /> + <rect class="cpu" x="647.097" y="1930.982" width="4.007" height="9.018" /> + <text x="648.090" y="1934.000">gnome-contacts- [591] <tspan class="run">0.043s</tspan></text> + <line class="dot" x1="643.090" y1="1930.000" x2="346.529" y2="1930.000" /> + <line class="dot" x1="346.529" y1="1930.000" x2="346.529" y2="1780.000" /> + +<!-- dbus-daemon [604] ppid=321 runtime=0.000s --> + <line class="dot" x1="346.529" y1="1930.000" x2="346.529" y2="1780.000" /> +<!-- evolution-addre [605] ppid=604 runtime=0.019s --> + <rect class="ps" x="651.104" y="1940.000" width="1444.391" height="20.000" /> + <rect class="wait" x="651.104" y="1940.000" width="4.007" height="0.057" /> + <rect class="cpu" x="651.104" y="1951.785" width="4.007" height="8.215" /> + <text x="656.104" y="1954.000">evolution-addre [605] <tspan class="run">0.019s</tspan></text> + <line class="dot" x1="651.104" y1="1950.000" x2="346.529" y2="1950.000" /> + <line class="dot" x1="346.529" y1="1950.000" x2="346.529" y2="1780.000" /> + +<!-- systemd-fsck [343] ppid=1 runtime=0.000s --> +<!-- fsck [344] ppid=343 runtime=0.000s --> +<!-- systemd-cgroups [346] ppid=343 runtime=0.000s --> + <line class="dot" x1="101.950" y1="1950.000" x2="101.950" y2="20.000" /> +<!-- mount [348] ppid=1 runtime=0.000s --> +<!-- at-spi-bus-laun [355] ppid=1 runtime=0.000s --> +<!-- dbus-daemon [359] ppid=355 runtime=0.011s --> + <rect class="ps" x="366.569" y="1960.000" width="1728.926" height="20.000" /> + <text x="371.569" y="1974.000">dbus-daemon [359] <tspan class="run">0.011s</tspan></text> + <line class="dot" x1="366.569" y1="1970.000" x2="101.950" y2="1970.000" /> + <line class="dot" x1="101.950" y1="1970.000" x2="101.950" y2="20.000" /> + +<!-- dbus-daemon [361] ppid=359 runtime=0.000s --> + <line class="dot" x1="366.569" y1="1970.000" x2="366.569" y2="1980.000" /> +<!-- at-spi2-registr [362] ppid=361 runtime=0.022s --> + <rect class="ps" x="366.569" y="1980.000" width="1728.926" height="20.000" /> + <rect class="wait" x="366.569" y="1980.000" width="4.007" height="0.152" /> + <rect class="cpu" x="366.569" y="1994.846" width="4.007" height="5.154" /> + <text x="371.569" y="1994.000">at-spi2-registr [362] <tspan class="run">0.022s</tspan></text> + <line class="dot" x1="366.569" y1="1990.000" x2="366.569" y2="1990.000" /> + <line class="dot" x1="366.569" y1="1990.000" x2="366.569" y2="1980.000" /> + +<!-- gnome-keyring-d [374] ppid=1 runtime=0.008s --> + <rect class="ps" x="378.590" y="2000.000" width="1716.905" height="20.000" /> + <rect class="wait" x="514.858" y="2000.000" width="4.006" height="3.078" /> + <rect class="cpu" x="514.858" y="2019.890" width="4.006" height="0.110" /> + <text x="383.590" y="2014.000">gnome-keyring-d [374] <tspan class="run">0.008s</tspan></text> + <line class="dot" x1="378.590" y1="2010.000" x2="101.950" y2="2010.000" /> + +<!-- rtkit-daemon [386] ppid=1 runtime=0.015s --> + <rect class="ps" x="382.596" y="2020.000" width="1712.899" height="20.000" /> + <rect class="wait" x="386.603" y="2020.000" width="4.007" height="0.618" /> + <rect class="cpu" x="386.603" y="2037.429" width="4.007" height="2.571" /> + <text x="387.596" y="2034.000">rtkit-daemon [386] <tspan class="run">0.015s</tspan></text> + <line class="dot" x1="382.596" y1="2030.000" x2="101.950" y2="2030.000" /> + +<!-- upowerd [400] ppid=1 runtime=0.083s --> + <rect class="ps" x="406.656" y="2040.000" width="1688.838" height="20.000" /> + <rect class="wait" x="406.656" y="2040.000" width="4.007" height="0.204" /> + <rect class="cpu" x="406.656" y="2055.546" width="4.007" height="4.454" /> + <rect class="wait" x="414.670" y="2040.000" width="4.007" height="0.046" /> + <rect class="cpu" x="414.670" y="2045.541" width="4.007" height="14.459" /> + <rect class="wait" x="418.677" y="2040.000" width="4.007" height="10.445" /> + <rect class="cpu" x="418.677" y="2053.499" width="4.007" height="6.501" /> + <rect class="wait" x="422.684" y="2040.000" width="4.012" height="13.589" /> + <rect class="cpu" x="422.684" y="2056.627" width="4.012" height="3.373" /> + <rect class="wait" x="426.696" y="2040.000" width="4.006" height="3.543" /> + <rect class="cpu" x="426.696" y="2057.472" width="4.006" height="2.528" /> + <rect class="wait" x="438.722" y="2040.000" width="4.008" height="1.105" /> + <rect class="cpu" x="438.722" y="2057.979" width="4.008" height="2.021" /> + <rect class="wait" x="442.730" y="2040.000" width="4.010" height="2.005" /> + <rect class="cpu" x="442.730" y="2058.376" width="4.010" height="1.624" /> + <text x="411.656" y="2054.000">upowerd [400] <tspan class="run">0.083s</tspan></text> + <line class="dot" x1="406.656" y1="2050.000" x2="101.950" y2="2050.000" /> + +<!-- pm-is-supported [404] ppid=400 runtime=0.000s --> +<!-- pm-is-supported [414] ppid=400 runtime=0.000s --> + <line class="dot" x1="406.656" y1="2050.000" x2="406.656" y2="2060.000" /> +<!-- pm-powersave [425] ppid=1 runtime=0.000s --> +<!-- gvfsd-fuse [448] ppid=1 runtime=0.000s --> +<!-- dconf-service [466] ppid=1 runtime=0.000s --> +<!-- udisksd [472] ppid=1 runtime=0.056s --> + <rect class="ps" x="478.799" y="2060.000" width="1616.696" height="20.000" /> + <rect class="wait" x="478.799" y="2060.000" width="4.009" height="0.073" /> + <rect class="cpu" x="478.799" y="2069.966" width="4.009" height="10.034" /> + <rect class="wait" x="482.808" y="2060.000" width="4.006" height="0.508" /> + <rect class="cpu" x="482.808" y="2065.475" width="4.006" height="14.525" /> + <rect class="wait" x="522.870" y="2060.000" width="4.006" height="1.151" /> + <rect class="cpu" x="522.870" y="2076.927" width="4.006" height="3.073" /> + <text x="483.799" y="2074.000">udisksd [472] <tspan class="run">0.056s</tspan></text> + <line class="dot" x1="478.799" y1="2070.000" x2="101.950" y2="2070.000" /> + +<!-- gvfs-gphoto2-vo [487] ppid=1 runtime=0.001s --> + <rect class="ps" x="490.819" y="2080.000" width="1604.675" height="20.000" /> + <text x="495.819" y="2094.000">gvfs-gphoto2-vo [487] <tspan class="run">0.001s</tspan></text> + <line class="dot" x1="490.819" y1="2090.000" x2="101.950" y2="2090.000" /> + +<!-- gvfs-afc-volume [500] ppid=1 runtime=0.001s --> + <rect class="ps" x="490.819" y="2100.000" width="1604.675" height="20.000" /> + <text x="495.819" y="2114.000">gvfs-afc-volume [500] <tspan class="run">0.001s</tspan></text> + <line class="dot" x1="490.819" y1="2110.000" x2="101.950" y2="2110.000" /> + +<!-- colord [515] ppid=1 runtime=0.109s --> + <rect class="ps" x="510.850" y="2120.000" width="1584.645" height="20.000" /> + <rect class="wait" x="510.850" y="2120.000" width="4.008" height="2.078" /> + <rect class="cpu" x="510.850" y="2133.937" width="4.008" height="6.063" /> + <rect class="wait" x="514.858" y="2120.000" width="4.006" height="10.053" /> + <rect class="cpu" x="514.858" y="2131.131" width="4.006" height="8.869" /> + <rect class="wait" x="518.864" y="2120.000" width="4.006" height="5.783" /> + <rect class="cpu" x="518.864" y="2127.112" width="4.006" height="12.888" /> + <rect class="wait" x="522.870" y="2120.000" width="4.006" height="3.797" /> + <rect class="cpu" x="522.870" y="2125.355" width="4.006" height="14.645" /> + <rect class="wait" x="558.930" y="2120.000" width="4.006" height="7.481" /> + <rect class="cpu" x="558.930" y="2135.246" width="4.006" height="4.754" /> + <rect class="wait" x="562.936" y="2120.000" width="4.006" height="9.320" /> + <rect class="cpu" x="562.936" y="2134.073" width="4.006" height="5.927" /> + <text x="515.850" y="2134.000">colord [515] <tspan class="run">0.109s</tspan></text> + <line class="dot" x1="510.850" y1="2130.000" x2="101.950" y2="2130.000" /> + +<!-- gconftool-2 [532] ppid=1 runtime=0.000s --> +<!-- gconftool-2 [536] ppid=1 runtime=0.000s --> +<!-- gconfd-2 [538] ppid=1 runtime=0.013s --> + <rect class="ps" x="518.864" y="2140.000" width="1576.631" height="20.000" /> + <rect class="wait" x="518.864" y="2140.000" width="4.006" height="3.065" /> + <rect class="cpu" x="518.864" y="2158.928" width="4.006" height="1.072" /> + <rect class="wait" x="1047.976" y="2140.000" width="4.007" height="0.061" /> + <rect class="cpu" x="1047.976" y="2155.063" width="4.007" height="4.937" /> + <text x="523.864" y="2154.000">gconfd-2 [538] <tspan class="run">0.013s</tspan></text> + <line class="dot" x1="518.864" y1="2150.000" x2="101.950" y2="2150.000" /> + +<!-- gconftool-2 [540] ppid=1 runtime=0.000s --> +<!-- cupsd [550] ppid=1 runtime=0.014s --> + <rect class="ps" x="534.889" y="2160.000" width="1560.606" height="20.000" /> + <rect class="wait" x="534.889" y="2160.000" width="4.006" height="1.915" /> + <rect class="cpu" x="534.889" y="2173.048" width="4.006" height="6.952" /> + <text x="539.889" y="2174.000">cupsd [550] <tspan class="run">0.014s</tspan></text> + <line class="dot" x1="534.889" y1="2170.000" x2="101.950" y2="2170.000" /> + +<!-- gsd-printer [554] ppid=1 runtime=0.000s --> +<!-- (d-notify) [651] ppid=1 runtime=0.000s --> + <line class="dot" x1="101.950" y1="2170.000" x2="101.950" y2="20.000" /> + +<!-- idle detected at 10.921 seconds --> +<line class="idle" x1="1092.072" y1="-20.000" x2="1092.072" y2="2200.000" /> +<text class="idle" x="1097.072" y="2200.000">10.9s</text> +</g> + +<g transform="translate(10, 0)"> +<text class="t1" x="0" y="30">Bootchart for lon - Sun, 13 Jan 2013 00:44:39 +0100</text> +<text class="t2" x="20" y="50">System: Linux 3.8.0-0.rc2.git4.2.fc19.x86_64 #1 SMP Wed Jan 9 20:08:36 UTC 2013 x86_64</text> +<text class="t2" x="20" y="65">CPU: Intel(R) Core(TM) i5-2540M CPU @ 2.60GHz +</text> +<text class="t2" x="20" y="80">Disk: INTEL SSDSA2CW12 +</text> +<text class="t2" x="20" y="95">Boot options: init=/usr/lib/systemd/systemd-bootchart root=/dev/sda2 rootfstype=ext4 libahci.ignore_sss=1 quiet initcall_debug +</text> +<text class="t2" x="20" y="110">Build: Fedora release 19 (Rawhide) +</text> +<text class="t2" x="20" y="125">Log start time: 0.981s</text> +<text class="t2" x="20" y="140">Idle time: 10.921s</text> +<text class="sec" x="20" y="155">Graph data: 25.000 samples/sec, recorded 500 total, dropped 0 samples, 279 processes, 159 filtered</text> +</g> + +<g transform="translate(10,200)"> +<text class="t2" x="20" y="0">Top CPU consumers:</text> +<text class="t3" x="20" y="20">3.107s - gnome-shell[506]</text> +<text class="t3" x="20" y="33">1.979s - Xorg[286]</text> +<text class="t3" x="20" y="46">1.021s - systemd-bootcha[98]</text> +<text class="t3" x="20" y="59">0.562s - gnome-settings-[378]</text> +<text class="t3" x="20" y="72">0.437s - systemd-journal[112]</text> +<text class="t3" x="20" y="85">0.359s - systemd[1]</text> +<text class="t3" x="20" y="98">0.311s - yumBackend.py[654]</text> +<text class="t3" x="20" y="111">0.309s - systemd-readahe[104]</text> +<text class="t3" x="20" y="124">0.282s - migration/0[8]</text> +<text class="t3" x="20" y="137">0.208s - gnome-session[311]</text> +</g> + + +</svg> diff --git a/Software/systemd/PasswordAgents.mdwn b/Software/systemd/PasswordAgents.mdwn new file mode 100644 index 00000000..1c09b334 --- /dev/null +++ b/Software/systemd/PasswordAgents.mdwn @@ -0,0 +1,35 @@ + +[[Back to systemd|http://www.freedesktop.org/wiki/Software/systemd/]] + + +# Password Agents + +systemd 12 and newer support lightweight password agents which can be used to query the user for system-level passwords or passphrases. These are passphrases that are not related to a specific user, but to some kind of hardware or service. Right now this is used exclusively for encrypted harddisk passphrases but later on this is likely to be used to query passphrases of SSL certificates at Apache startup time as well. The basic idea is that a system component requesting a password entry can simply drop a simple .ini-style file into /run/systemd/ask-password which multiple different agents may watch via inotify(), and query the user as necessary. The answer is then sent back to the querier via an AF_UNIX/SOCK_DGRAM socket. Multiple agents might be running at the same time in which case they all should query the user and the agent which answers first wins. Right now systemd ships with the following passphrase agents: + +* A Plymouth agent used for querying passwords during boot-up +* A console agent used in similar situations if Plymouth is not available +* A GNOME agent which can be run as part of the normal user session which pops up a notification message and icon which when clicked receives the passphrase from the user. This is useful and necessary in case an encrypted system harddisk is plugged in when the machine is already up. +* A wall(1) agent which sends wall messages as soon as a password shall be entered. +* A simple tty agent which is built into "systemctl start" (and similar commands) and asks passwords to the user during manual startup of a service +* A simple tty agent which can be run manually to respond to all queued passwords +It is easy to write additional agents. The basic algorithm to follow looks like this: + +* Create an inotify watch on /run/systemd/ask-password, watch for IN_CLOSE_WRITE|IN_MOVED_TO +* Ignore all events on files in that directory that do not start with "ask." +* As soon as a file named "ask.xxxx" shows up, read it. It's a simple .ini file that may be parsed with the usual parsers. The xxxx suffix is randomized. +* Make sure to ignore unknown .ini file keys in those files, so that we can easily extend the format later on. +* You'll find the question to ask the user in the Message= field in the [Ask] section. It is a single-line string in UTF-8, which might be internationalized (by the party that originally asks the question, not by the agent). +* You'll find an icon name (following the XDG icon naming spec) to show next to the message in the Icon= field in the [Ask] section +* You'll find the PID of the client asking the question in the PID= field in the [Ask] section (Before asking your question use kill(PID, 0) and ignore the file if this returns ESRCH; there's no need to show the data of this field but if you want to you may) +* The socket to send the response to is configured via Socket= in the [Ask] section. It is a AF_UNIX/SOCK_DGRAM socket in the file system. +* Ignore files where the time specified in the [[NotAfter|NotAfter]]= field in the [Ask] section is in the past. The time is specified in usecs, and refers to the CLOCK_MONOTONIC clock. If [[NotAfter|NotAfter]]= is 0, no such check should take place. +* Make sure to hide a password query dialog as soon as a) the ask.xxxx file is deleted, watch this with inotify. b) the [[NotAfter|NotAfter]]= time elapses, if it is set != 0. +* Access to the socket is restricted to privileged users. To acquire the necessary privileges to send the answer back, consider using [[PolicyKit|PolicyKit]]. In fact, the GNOME agent we ship does that, and you may simply piggyback on that, by executing "/usr/bin/pkexec /lib/systemd/systemd-reply-password 1 /path/to/socket" or "/usr/bin/pkexec /lib/systemd/systemd-reply-password 0 /path/to/socket" and writing the password to its standard input. Use '1' as argument if a password was entered by the user, or '0' if the user canceled the request. +* If you do not want to use PK ensure to acquire the necessary privileges in some other way and send a single datagram to the socket consisting of the password string either prefixed with "+" or with "-" depending on whether the password entry was successful or not. You may but don't have to include a final NUL byte in your message. +Again, it is essential that you stop showing the password box/notification/status icon if the ask.xxx file is removed or when [[NotAfter|NotAfter]]= elapses (if it is set != 0)! + +It may happen that multiple password entries are pending at the same time. Your agent needs to be able to deal with that. Depending on your environment you may either choose to show all outstanding passwords at the same time or instead only one and as soon as the user replied to that one go on to the next one. + +You may test this all with manually invoking the "systemd-ask-password" tool on the command line. Pass --no-tty to ensure the password is asked via the agent system. Note that only privileged users may use this tool (after all this is intended purely for system-level passwords). + +If you write a system level agent a smart way to activate it is using systemd .path units. This will ensure that systemd will watch the /run/systemd/ask-password directory and spawn the agent as soon as that directory becomes non-empty. In fact, the console, wall and Plymouth agents are started like this. If systemd is used to maintain user sessions as well you can use a similar scheme to automatically spawn your user password agent as well. (As of this moment we have not switched any DE over to use systemd for session management, however.) diff --git a/Software/systemd/PaxControlGroups.mdwn b/Software/systemd/PaxControlGroups.mdwn new file mode 100644 index 00000000..a2fbbf78 --- /dev/null +++ b/Software/systemd/PaxControlGroups.mdwn @@ -0,0 +1,55 @@ + +[[Back to systemd|http://www.freedesktop.org/wiki/Software/systemd/]] + + +# Pax Controla Groupiana + +_aka "How to behave nicely in the cgroupfs trees"_ + +Are you writing an application interfacing with the cgroups tree? The cgroups trees are a shared resource, other applications will use them too. Here are a few recommendations how to write your application in a way that minimizes conflicts with other applications. If you follow these guidelines applications should not step on any other application's toes and users will be happy. + +Before you read these recommendations please make sure you understand cgroups thoroughly, and specifically are aware what a controller is, what a named hierarchy is and so on. + + +## Intended Audience + +You should consider these recommendations if you are you working on one of the following: + +* You write a system or session manager based on cgroups (like systemd) +* You write a VM manager based on cgroups (like libvirt) +* You write a terminal application and want to place every shell in a separate cgroup (like gnome-terminal) +* You write a web browser and want to place every renderer in a separate cgroup (like Firefox or Chrome) +* You create a container for some purpose (such as systemd-nspawn) +* Or you use cgroups for any other purpose and want things to work nicely with other applications. + +## General Recommendations + +* If you use one of the kernel controllers, do *not* assume you are the only one who uses them. Other programs may manipulate the tree, add cgroups and change group attributes at any time, and they will not inform you about it. The kernel provided controller hierarchies are a shared resource, so be nice. +* If you use a generic named hierarchy with no controller attached, then you may assume it's yours and only yours, and that no other programs interfere with it. +* If you use a generic named hierarchy with no controller attached, then make sure to name it after your project in order to minimize namespacing conflicts. A hierarchy named "name=web" is a bit generic. A hierarchy named "name=apache" a much better choice, if you are an Apache developer and need an entire hierarchy all for yourself. +* Do *not* assume everybody uses the same library to manipulate the cgroups tree as you are. In fact most likely most applications and the user himself will manipulate the tree without any further indirection (i.e. will use naked system calls/shell commands) +* Never create cgroups at the top of the tree (i.e. with an absolute path). If possible find the cgroup your own process was started in and create subgroups only below that group (read /proc/self/cgroup to find it). If that's not applicable, then at least place yourself below the cgroup path of PID 1 (read /proc/1/cgroup to find it). This is important to ensure that containers work properly (the cgroupfs tree is currently not virtualized for containers!), and solves permission problems, and makes the whole system nicely stackable. +* A corollary of this: If you spawn subprocesses expect that they will create subcgroups. That means when terminating there might be subcgroups below the ones you created and you hence need to recursively remove them too. In fact, many of your operations must probably be executed in a recursive fashion. +* Do not play permission games: if you are an unprivileged user application then it's *not* your business to ensure you have the right permissions (i.e. do not include any setuid code in your app to create groups) Instead your system manager (such as systemd) should provide you with the right set of permissions on the cgroup you are running in to create subgroups. Normally that should mean that depending on administrator configuration you will or will not get access to create subgroups under the cgroup you are running in and the ability to add PIDs to it. If you don't get access to these hierarchies then this might be a decision by the administrator and you should do your best to go on, and fail gracefully. +* If you create a cgroup, then you are in charge of removing it too after using it. Do not remove other program's cgroups. Special exception: in some cases it is OK to pre-set attributes on certain cgroups that are primarily managed by another program. (Example: in systemd we are fine if you externally pre-create or manipulate service cgroups, for example to make changes to some attributes you cannot control with systemd natively, see below). In that case: create the cgroup and set the sticky bit (+t) on the tasks file in it. This will then be used as an indication to the primary manager of the group not to remove the cgroup at the end, in order to avoid that your settings are lost. This is of course a bit of a misuse of the sticky bit, but given that it serves no other purpose on Linux for normal files, it is an OK use, with a fitting meaning given the name of "sticky bit". +* If you find a process in a cgroup you are about to remove, and it is not yours, consider leaving the cgroup around. I.e. if rmdir returns EEMPTY, ignore this. +* The cgroup mount point for a specific hierarchy is /sys/fs/cgroup/<controller>/. (Example: /sys/fs/cgroup/cpu for the "cpu" controller). In your application you are welcome to rely on these standardized mount points, and it is not necessary to dynamically determine the current mount point via /proc/self/mountinfo (but if you do, that's of course fine, too). Note that /sys/fs/cgroup/<controller> might actually just be a symlink to some other mount point (see below). +* If multiple controllers are mounted into the same hierarchy it is guaranteed that symlinks exist to make sure all jointly mounted controllers are still available under /sys/fs/cgroup/<controller>/. Example: if "cpu" and "cpuacct" are mounted together, then symlinks /sys/fs/cgroup/cpu and /sys/fs/cgroup/cpuacct will point to the joint mountpoint (which could be something like /sys/fs/cgroup/cpu+cpuacct). +* Your application should not mount the cgroup controller file systems (unless it is your own private named hierarchy). This is exclusively a job for the system manager or a system-wide init script such as cgconfig. If you work on a system manager or such an init script you must mount the cgroup controllers to /sys/fs/cgroup/<controller>/ or provide compatibility symlinks. +* It's a good idea not to fail if a cgroup already exists when you try to create it. Ignore EEXIST on mkdir. +* Avoid renaming cgroups or similar fancier file operations. +* Expect that other programs might readjust the attributes on your cgroups dynamically during runtime. +* When creating a cgroup pick a nice a descriptive name that is guessable and no surprise to the admin. The admin will thank you for this if he has to read the output of "ps -eo pid,args,cgroups" +* /sys/fs/cgroup is a tmpfs. If you create your own private named hierarchy then you are welcome to mount it into a subdirectory of this directory. This minimizes surprises for the user. +* /sys/fs/cgroup is a tmpfs, but it's only intended use is to act as place where control group hierarchies can be mounted or symlinked to. You should not place any other kind of file in this directory. The same way as /dev/shm is for POSIX shared memory segments only -- and nothing else -- this directory is for cgroup hierarchies only. Just because something is a tmpfs it doesn't mean you can actually use it for "temporary" files, thank you. + +## Cooperation with systemd + +systemd adheres to the recommendations above and guarantees additional behavior which might be useful for writing applications that cooperate with systemd on cgroup management: + +* If a service cgroup already exists, systemd will make use of it and not recreate it. (If +t is set on the tasks file it will not remove it when stopping a service, otherwise it will, see above). It is hence OK to pre-create cgroups and then let systemd use it, without having systemd remove it afterwards. +* If a service cgroup already exists, systemd will not override the attributes of the cgroup with the exception of those explicitly configured in the systemd unit files. It is hence OK to pre-create cgroups for use in systemd, and pre-apply attributes to it. +* To avoid that systemd places all services in automatic cgroups in the "cpu" hierarchy change the [[DefaultControllers|DefaultControllers]]= in /etc/systemd/system.conf and set it to the empty string. +* By default systemd will place services only in automatic cgroups in the "cpu" hierarchy and in its own private tree "name=systemd". If you want it to duplicate these trees in other hierarchies add them to [[DefaultControllers|DefaultControllers]]= in /etc/systemd/system.conf +* To opt-out or opt-in specific services from the automatic tree generation in the kernel controller hierarchies use [[ControlGroup|ControlGroup]]= in the unit file. Use "[[ControlGroup|ControlGroup]]=cpu:/" to opt-out of cgroup assignment for a service or "[[ControlGroup|ControlGroup]]=cpu:/foo/bar" to manipulate the cgroup path. +* Stay away from the name=systemd named hierarchy. It's private property of systemd. You are welcome to explore it, but it is uncool to modify it from outside systemd. Thanks.
\ No newline at end of file diff --git a/Software/systemd/PredictableNetworkInterfaceNames.mdwn b/Software/systemd/PredictableNetworkInterfaceNames.mdwn new file mode 100644 index 00000000..81d4f81d --- /dev/null +++ b/Software/systemd/PredictableNetworkInterfaceNames.mdwn @@ -0,0 +1,66 @@ + +[[Back to systemd|http://www.freedesktop.org/wiki/Software/systemd/]] + + +# Predictable Network Interface Names + +Starting with v197 systemd/udev will automatically assign predictable, stable network interface names for all local Ethernet, WLAN and WWAN interfaces. This is a departure from the traditional interface naming scheme ("eth0", "eth1", "wlan0", ...), but should fix real problems. + + +## Why? + +The classic naming scheme for network interfaces applied by the kernel is to simply assign names beginning with "eth0", "eth1", ... to all interfaces as they are probed by the drivers. As the driver probing is generally not predictable for modern technology this means that as soon as multiple network interfaces are available the assignment of the names "eth0", "eth1" and so on is generally not fixed anymore and it might very well happen that "eth0" on one boot ends up being "eth1" on the next. This can have serious security implications, for example in firewall rules which are coded for certain naming schemes, and which are hence very sensitive to unpredictable changing names. + +To fix this problem multiple solutions have been proposed and implemented. For a longer time udev shipped support for assigning permanent "ethX" names to certain interfaces based on their MAC addresses. This turned out to have a multitude of problems, among them: this required a writable root directory which is generally not available; the statelessness of the system is lost as booting an OS image on a system will result in changed configuration of the image; on many systems MAC addresses are not actually fixed, such as on a lot of embedded hardware and particularly on all kinds of virtualization solutions. The biggest of all however is that the userspace components trying to assign the interface name raced against the kernel assigning new names from the same "ethX" namespace, a race condition with all kinds of weird effects, among them that assignment of names sometimes failed. As a result support for this has been removed from systemd/udev a while back. + +Another solution that has been implemented is "biosdevname" which tries to find fixed slot topology information in certain firmware interfaces and uses them to assign fixed names to interfaces which incorporate their physical location on the mainboard. In a way this naming scheme is similar to what is already done natively in udev for various device nodes via /dev/*/by-path/ symlinks. In many cases, biosdevname departs from the low-level kernel device identification schemes that udev generally uses for these symlinks, and instead invents its own enumeration schemes. + +Finally, many distributions support renaming interfaces to user-chosen names (think: "internet0", "dmz0", ...) keyed off their MAC addresses or physical locations as part of their networking scripts. This is a very good choice but does have the problem that it implies that the user is willing and capable of choosing and assigning these names. + +We believe it is a good default choice to generalize the scheme pioneered by "biosdevname". Assigning fixed names based on firmware/topology/location information has the big advantage that the names are fully automatic, fully predictable, that they stay fixed even if hardware is added or removed (i.e. no reenumeration takes place) and that broken hardware can be replaced seamlessly. That said, they admittedly are sometimes harder to read than the "eth0" or "wlan0" everybody is used to. Example: "enp5s0" + + +## What precisely has changed in v197? + +With systemd 197 we have added native support for a number of different naming policies into systemd/udevd proper and made a scheme similar to biosdevname's (but generally more powerful, and closer to kernel-internal device identification schemes) the default. The following different naming schemes for network interfaces are now supported by udev natively: + +1. Names incorporating Firmware/BIOS provided index numbers for on-board devices (example: `eno1`) +1. Names incorporating Firmware/BIOS provided PCI Express hotplug slot index numbers (example: `ens1`) +1. Names incorporating physical/geographical location of the connector of the hardware (example: `enp2s0`) +1. Names incorporating the interfaces's MAC address (example: `enx78e7d1ea46da`) +1. Classic, unpredictable kernel-native ethX naming (example: `eth0`) +By default, systemd v197 will now name interfaces following policy 1) if that information from the firmware is applicable and available, falling back to 2) if that information from the firmware is applicable and available, falling back to 3) if applicable, falling back to 5) in all other cases. Policy 4) is not used by default, but is available if the user chooses so. + +This combined policy is only applied as last resort. That means, if the system has biosdevname installed, it will take precedence. If the user has added udev rules which change the name of the kernel devices these will take precedence too. Also, any distribution specific naming schemes generally take precedence. + + +## Come again, what good does this do? + +With this new scheme you now get: + +* Stable interface names across reboots +* Stable interface names even when hardware is added or removed, i.e. no re-enumeration takes place +* Stable interface names when kernels or drivers are updated/changed +* Stable interface names even if you have to replace broken ethernet cards by new ones +* The names are automatically determined without user configuration, they just work +* The interface names are fully predictable, i.e. just by looking at lspci you can figure out what the interface is going to be called +* Fully stateless operation, changing the hardware configuration will not result in changes in /etc +* Compatibility with read-only root +* The network interface naming now follows more closely the scheme used for aliasing block device nodes and other device nodes in /dev via symlinks +* Applicability to both x86 and non-x86 machines +* The same on all distributions that adopted systemd/udev +* It's easy to opt out of the scheme (see below) +Does this have any drawbacks? Yes, it does. Previously it was practically guaranteed that hosts equipped with a single ethernet card only had a single "eth0" interface. With this new scheme in place, an administrator now has to check first what the local interface name is before he can invoke commands on it where previously he had a good chance that "eth0" was the right name. + + +## I don't like this, how do I disable this? + +You basically have three options: + + 1. You disable the assignment of fixed names, so that the unpredictable kernel names are used again. For this, simply mask udev's rule file for the default policy: `ln -s /dev/null /etc/udev/rules.d/80-net-name-slot.rules` + 1. You create your own manual naming scheme, for example by naming your interfaces "internet0", "dmz0" or "lan0". For that create your own udev rules file and set the NAME property for the devices. Make sure to order it before the default policy file, for example by naming it `/etc/udev/rules.d/70-my-net-names.rules` + 1. You alter the default policy file, for picking a different naming scheme, for example for naming all interface names after their MAC address by default: `cp /usr/lib/udev/rules.d/80-net-name-slot.rules /etc/udev/rules.d/80-net-name-slot.rules`, then edit the file there and change the lines as necessary. + +## How does the new naming scheme look like, precisely? + +That's documented in detail in a comment block [[the sources of the net_id built-in|http://cgit.freedesktop.org/systemd/systemd/tree/src/udev/udev-builtin-net_id.c#n20]]. Please refer to this in case you are wondering how to decode the new interface names. diff --git a/Software/systemd/Preset.mdwn b/Software/systemd/Preset.mdwn new file mode 100644 index 00000000..3fbc27d1 --- /dev/null +++ b/Software/systemd/Preset.mdwn @@ -0,0 +1,48 @@ + +[[Back to systemd|http://www.freedesktop.org/wiki/Software/systemd/]] + + +# Presets + + +## Why? + +Different **distributions** have different policies on which services shall be enabled by default when the package they are shipped in is installed. On Fedora all services stay off by default, so that installing a package will not cause a service to be enabled (with some exceptions). On Debian all services are immediately enabled by default, so that installing a package will cause its service(s) to be enabled right-away. + +Different **spins** (flavours, remixes, whatever you might want to call them) of a distribution also have different policies on what services to enable, and what services to leave off. For example, the Fedora default will enable gdm as display manager by default, while the Fedora KDE spin will enable kdm instead. + +Different **sites** might also have different policies what to turn on by default and what to turn off. For example, one administrator would prefer to enforce the policy of "ssh should be always on, but everything else off", while another one might say "snmp always on, and for everything else use the distribution policy defaults". + + +## The Logic + +Traditionally, policy about what services shall be enabled and what services shall not have been decided globally by the distributions, and were enforced in each package individually. This made it cumbersome to implement different policies per spin or per site, or to create software packages that do the right thing on more than one distribution. The enablement _mechanism_ was also encoding the enablement _policy_. + +systemd 32 and newer support package "preset" policies. These encode which units shall be enabled by default when they are installed, and which units shall not be enabled. + +Preset files may be written for specific distributions, for specific spins or for specific sites, in order to enforce different policies as needed. Preset policies are stored in .preset files in /usr/lib/systemd/system-preset/. If no policy exists the default implied policy of "enable everything" is enforced, i.e. in Debian style. + +The policy encoded in preset files is applied to a unit by invoking "systemctl preset <unit>". It is recommended to use this command in all package post installation scriptlets. "systemctl preset <unit>" is identical to "systemctl enable <unit>" resp. "systemctl disable <unit>" depending on the policy. + +Preset files allow clean separation of enablement _mechanism_ (inside the package scriptlets, by invoking "systemctl preset"), and enablement _policy_ (centralized in the preset files). + + +## Documentation + +Documentation for the preset policy file format is available here: [[http://www.freedesktop.org/software/systemd/man/systemd.preset.html|http://www.freedesktop.org/software/systemd/man/systemd.preset.html]] + +Documentation for "systemctl preset" you find here: [[http://www.freedesktop.org/software/systemd/man/systemctl.html|http://www.freedesktop.org/software/systemd/man/systemctl.html]] + +Documentation for the recommended package scriptlets you find here: [[http://www.freedesktop.org/software/systemd/man/daemon.html|http://www.freedesktop.org/software/systemd/man/daemon.html]] + + +## How To + +For the preset logic to be useful, distributions need to implement a couple of steps: + +* The default distribution policy needs to be encoded in a preset file /usr/lib/systemd/system-preset/99-default.preset or suchlike, unless the implied policy of "enable everything" is the right choice. For a Fedora-like policy of "enable nothing" it is sufficient to include the single line "disable *" into that file. The default preset file should be installed as part of one the core packages of the distribution. +* All packages need to be updated to use "systemctl preset" in the post install scriptlets. +* (Optionally) spins/remixes/flavours should define their own preset file, either overriding or extending the default distribution preset policy. +Also see the fedora feature page: + +[[https://fedoraproject.org/wiki/Features/PackagePresets|https://fedoraproject.org/wiki/Features/PackagePresets]] diff --git a/Software/systemd/RootStorageDaemons.mdwn b/Software/systemd/RootStorageDaemons.mdwn new file mode 100644 index 00000000..13ad514f --- /dev/null +++ b/Software/systemd/RootStorageDaemons.mdwn @@ -0,0 +1,80 @@ + +[[Back to systemd|http://www.freedesktop.org/wiki/Software/systemd/]] + + +# systemd and Storage Daemons for the Root File System + +a.k.a. _Pax Cellae pro Radix Arbor_ + +(or something like that, my Latin is a bit rusty) + +A number of complex storage technologies on Linux (e.g. RAID, volume management, networked storage) require user space services to run while the storage is active and mountable. This requirement becomes tricky as soon as the root file system of the Linux operating system is stored on such storage technology. Previously no clear path to make this work was available. This text tries to clear up the resulting confusion, and what is now supported and what is not. + + +## A Bit of Background + +When complex storage technologies are used as backing for the root file system this needs to be set up by the initial RAM file system (initramfs), i.e. on Fedora by Dracut. In newer systemd versions teardown of the root file system backing is also done by the initramfs: after terminating all remaining running processes and unmounting all file systems it can (which means excluding the root fs) systemd will jump back into the initramfs code allowing it to unmount the final file systems (and its storage backing) that could not be unmounted as long as the OS was still running from the main root file system. The initramfs' job is to detach/unmount the root fs, i.e. inverting the exact commands it used to set them up in the first place. This is not only cleaner, but also allows for the first time arbitrary complex stacks of storage technology. + +Previous attempts to handle root file system setups with complex storage as backing usually tried to maintain the root storage with program code stored on the root storage itself, thus creating a number of dependency loops. Safely detaching such a root file system becomes messy, since the program code on the storage needs to stay around longer than the storage, which is technically contradicting. + + +## What's new? + +As a result, we hereby clarify that we do not support storage technology setups where the storage daemons are being run from the storage it maintains itself. In other words: a storage daemon backing the root file system cannot be stored on the root file system itself. + +What we do support instead is that these storage daemons are started from the initramfs, stay running all the time during normal operation and are terminated only after we returned control back to the initramfs and by the initramfs. As such, storage daemons involved with maintaining the root file system storage conceptually are more like kernel threads than like normal system services: from the perspective of the init system (i.e. systemd) these services have been started before systemd got initialized and stay around until after systemd is already gone. These daemons can only be updated by updating the initramfs and rebooting, a takeover from initramfs-supplied services to replacements from the root file system is not supported. + + +## What does this mean? + +Near the end of system shutdown, systemd executes a small tool called systemd-shutdown, replacing its own process. This tool (which runs as PID 1, as it entirely replaces the systemd init process) then iterates through the mounted file systems and running processes (as well as a couple of other resources) and tries to unmount/read-only mount/detach/kill them. It continues to do this in a tight loop as long as this results in any effect. From this killing spree a couple of processes are automatically excluded: PID 1 itself of course, as well as all kernel threads. After the killing/unmounting spree control is passed back to the initramfs, whose job is then to unmount/detach whatever might be remaining. + +The same killing spree logic (but not the unmount/detach/read-only logic) is applied during the transition from the initrd to the main system (i.e. the "switch_root" operation), so that no processes from the initrd survive to the main system. + +To implement the supported logic proposed above (i.e. where storage daemons needed for the root fs which are started by the initramfs stay around during normal operation and are only killed after control is passed back to the initramfs) we need to exclude these daemons from the shutdown/switch_root killing spree. To accomplish this the following logic is available starting with systemd 38: + +Processes (run by the root user) whose first character of the zeroth command line argument is '@' are excluded from the killing spree, much the same way as kernel threads are excluded too. Thus, a daemon which wants to take advantage of this logic needs to place the following at the top of its main() function: + + +[[!format txt """ + ... + argv[0][0] = '@'; + ... +"""]] +And that's already it. Note that this functionality is only to be used by programs running from the initramfs, and **not** for programs running from the root file system itself. Programs which use this functionality and are running from the root file system are considered buggy since they effectively prohibit clean unmounting/detaching of the root file system and its backing storage. + +_Again: if your code is being run from the root file system, then this logic suggested above is **NOT** for you. Sorry. Talk to us, we can probably help you to find a different solution to your problem._ + +The recommended way to distinguish between run-from-initramfs and run-from-rootfs for a daemon is to check for /etc/initrd-release (which exists on all modern initrd implementations, see [[The Initrd Interface|http://www.freedesktop.org/wiki/Software/systemd/InitrdInterface]] for details) which when exists results in argv[0][0] being set to '@', and otherwise doesn't. Something like this: + + +[[!format txt """ +#include <unistd.h> + +int main(int argc, char *argv[]) { + ... + if (access("/etc/initrd-release", F_OK) >= 0) + argv[0][0] = '@'; + ... +} +"""]] +Why '@'? Why argv[0][0]? First of all, a technique like this is not without precedent: traditionally Unix login shells set argv[0][0] to '-' to clarify they are login shells. This logic is also very easy to implement. We have been looking for other ways to mark processes for exclusion from the killing spree, but could not find any that was equally simple to implement and quick to read when traversing through /proc. Also, as a side effect replacing the first character of argv[0] with '@' also visually invalidates the path normally stored in argv[0] (which usually starts with '/') thus helping the administrator to understand that your daemon is actually not originating from the actual root file system, but from a path in a completely different namespace (i.e. the initramfs namespace). Other than that we just think that '@' is a cool character which looks pretty in the ps output... ;-) + +Note that your code should only modify argv[0][0] and leave the comm name (i.e. /proc/self/comm) of your process untouched. + + +## To which technologies does this apply? + +These recommendations apply to those storage daemons which need to stay around until after the storage they maintain is unmounted. If your storage daemon is fine with being shut down before its storage device is unmounted you may ignore the recommendations above. + +This all applies to storage technology only, not to daemons with any other (non-storage related) purposes. + + +## What else to keep in mind? + +If your daemon implements the logic pointed out above it should work nicely from initramfs environments. In many cases it might be necessary to additionally support storage daemons to be started from within the actual OS, for example when complex storage setups are used for auxiliary file systems, i.e. not the root file system, or created by the administrator during runtime. Here are a few additional notes for supporting these setups: + +* If your storage daemon is run from the main OS (i.e. not the initramfs) it will also be terminated when the OS shuts down (i.e. before we pass control back to the initramfs). Your daemon needs to handle this properly. +* It is not acceptable to spawn off background processes transparently from user commands or udev rules. Whenever a process is forked off on Unix it inherits a multitude of process attributes (ranging from the obvious to the not-so-obvious such as security contexts or audit trails) from its parent process. It is practically impossible to fully detach a service from the process context of the spawning process. In particular, systemd tracks which processes belong to a service or login sessions very closely, and by spawning off your storage daemon from udev or an administrator command you thus make it part of its service/login. Effectively this means that whenever udev is shut down, your storage daemon is killed too, resp. whenever the login session goes away your storage might be terminated as well. (Also note that recent udev versions will automatically kill all long running background processes forked off udev rules now.) So, in summary: double-forking off processes from user commands or udev rules is **NOT** OK! +* To automatically spawn storage daemons from udev rules or administrator commands, the recommended technology is socket-based activation as implemented by systemd. Transparently for your client code connecting to the socket of your storage daemon will result in the storage to be started. For that it is simply necessary to inform systemd about the socket you'd like it to listen on on behalf of your daemon and minimally modify the daemon to receive the listening socket for its services from systemd instead of creating it on its own. Such modifications can be minimal, and are easily written in a way that does not negatively impact usability on non-systemd systems. For more information on making use of socket activation in your program consult this blog story: [[http://0pointer.de/blog/projects/socket-activation.html|http://0pointer.de/blog/projects/socket-activation.html]] +* Consider having a look at [[the initrd Interface of systemd|http://www.freedesktop.org/wiki/Software/systemd/InitrdInterface]]
\ No newline at end of file diff --git a/Software/systemd/SystemUpdates.mdwn b/Software/systemd/SystemUpdates.mdwn new file mode 100644 index 00000000..dfff4a84 --- /dev/null +++ b/Software/systemd/SystemUpdates.mdwn @@ -0,0 +1,41 @@ + +[[Back to systemd|http://www.freedesktop.org/wiki/Software/systemd/]] + + +# Implementing Offline System Updates + +_This is implemented starting with systemd 183._ + +Here are some guidelines how to implement "offline" OS updates with systemd. By "offline" OS updates we mean package installations and updates that are run with the system booted into a special system update mode, in order to avoid problems related to conflicts of libraries and services that are currently running with those on disk. This document is inspired [[by this GNOME design whiteboard|https://live.gnome.org/GnomeOS/Design/Whiteboards/SoftwareUpdates]]. + +The logic: + +1. The package manager prepares system updates by downloading all (RPM or DEB or whatever) packages to update off-line in a special directory /var/lib/system-update (or another directory of the package/upgrade manager's choice). +1. When the user OK'ed the update a symlink /system-update is created that points to /var/lib/system-update (or wherever the upgrade package directory is called) and the system is rebooted. This symlink is in the root directory, since we need to check for it very early at boot, at a time where /var is not available yet. +1. Very early in the new boot a systemd generator checks whether /system-update exists. If so, it (temporarily and for this boot only) redirects (i.e. symlinks) default.target to system-update.target, a new target that is intended to pull in the base system (i.e. sysinit.target, so that all file systems are mounted but little else) and the system update script. +1. The system now continues to boot into default.target, and thus into system-update.target. This target pulls in the OS update script, which is executed after all file systems are mounted. +1. The system update script now creates a btrfs snapshot (if possible), then installs all RPMs. After completion (regardless whether the update succeeded or failed) the /system-update symlink is removed. In addition, on failure it reverts to the old btrfs state (modulo the aforementioned symlink), on success it leaves the newly made changes in place. +1. The system is now rebooted. Since the /system-update symlink is gone, the generator won't redirect default.target this time and we now boot into the full system again. +Advantages of this approach over in-system updates: + +1. Only the components of the OS that are required to access the file systems are started and initialized. No other daemons/services are running, thus minimizing problems with conflicting versions of libraries/daemons/other files on disk and in memory. +1. The btrfs snapshot of the OS is fairly reliable and mostly atomic +Disadvantages of this approach over in-system updates: + +1. The system is rebooted twice. +Advantages of this approach over rescue partition based updates: + +1. The exact same storage initialization configuration is used for the update process as for the main OS, thus avoiding problems in finding the OS hierarchy and mounting it properly. +1. Since the journal is available all updates logs are saved and stored on disk the usual way and available for later review next to the usual logs. +Disadvantages of this approach over rescue partition based updates: + +1. The basic mounts are done with code that might be subject to the updating process. This means that while the problems with conflicts between processes/libraries in memory on disk are minimized they are not zero. +To clear up some confusion: generators are small binaries that live in /usr/lib/systemd/system-generators. systemd will execute those binaries very early at bootup (and at configuration reload time), before the unit files are loaded. The generators can dynamically generate unit files in /run, and override existing definitions freely. (For more information see [[Generators|http://www.freedesktop.org/wiki/Software/systemd/Generators]].) + +The generator code and the basic definition of systemd-update.target live within the systemd tarball/package itself. The system update script and creation of /system-update should live in the distribution's package manager or packages such as PackageKit. + +A few more recommendations: + +1. To make things a bit more robust we recommend hooking the update script into system-update.target via a .wants/ symlink in the distribution package, rather than depending on "systemctl enable" in the postinst scriptlets of your package. More specifically, for your update script create a .service file, without [Install] section, and then add a symlink like /usr/lib/systemd/system-update.target.wants/foobar.service → ../foobar.service to your package. +1. Make sure to remove the /system-update symlink _early_ in the update script to avoid reboot loops in case the update fails. +1. Use OnFailure=reboot.target in the service file for your update script to ensure that a reboot is automatically triggered if the update fails. OnFailure= makes sure that the specified unit is activated if your script exits uncleanly (by non-zero error code, or signal/coredump). If your script succeeds you should trigger the reboot in your own code, for example by invoking logind's Reboot() call. See [[On logind|http://www.freedesktop.org/wiki/Software/systemd/logind]] for details.
\ No newline at end of file diff --git a/Software/systemd/TheCaseForTheUsrMerge.mdwn b/Software/systemd/TheCaseForTheUsrMerge.mdwn new file mode 100644 index 00000000..20c105de --- /dev/null +++ b/Software/systemd/TheCaseForTheUsrMerge.mdwn @@ -0,0 +1,121 @@ + +[[Back to systemd|http://www.freedesktop.org/wiki/Software/systemd/]] + + +# The Case for the /usr Merge + +**Why the /usr Merge Makes Sense for Compatibility Reasons** + +_This is based on the [[Fedora feature|https://fedoraproject.org/wiki/Features/UsrMove]] for the same topic, put together by Harald Hoyer and Kay Sievers. This feature has been implemented successfully in Fedora 17._ + +Note that this page discusses a topic that is actually independent of systemd. systemd supports both systems with split and with merged /usr, and the /usr merge also makes sense for systemd-less systems. That said we want to encourage distributions adopting systemd to also adopt the /usr merge. + + +### What's Being Discussed Here? + +Fedora (and other distributions) have finished work on getting rid of the separation of /bin and /usr/bin, as well as /sbin and /usr/sbin, /lib and /usr/lib, and /lib64 and /usr/lib64. All files from the directories in / will be merged into their respective counterparts in /usr, and symlinks for the old directories will be created instead: + + +[[!format txt """ +/bin → /usr/bin +/sbin → /usr/sbin +/lib → /usr/lib +/lib64 → /usr/lib64 +"""]] +You are wondering why merging /bin, /sbin, /lib, /lib64 into their respective counterparts in /usr makes sense, and why distributions are pushing for it? You are wondering whether your own distribution should adopt the same change? Here are a few answers to these questions, with an emphasis on a compatibility point of view: + + +### Compatibility: The Gist of It + +* Improved compatibility with other Unixes/Linuxes in _behavior_: After the /usr merge all binaries become available in both /bin and /usr/bin, resp. both /sbin and /usr/sbin (simply because /bin becomes a symlink to /usr/bin, resp. /sbin to /usr/sbin). That means scripts/programs written for other Unixes or other Linuxes and ported to your distribution will no longer need fixing for the file system paths of the binaries called, which is otherwise a major source of frustration. /usr/bin and /bin (resp. /usr/sbin and /sbin) become entirely equivalent. +* Improved compatibility with other Unixes (in particular Solaris) in _appearance_: The primary commercial Unix implementation is nowadays Oracle Solaris. Solaris has already completed the same /usr merge in Solaris 11. By making the same change in Linux we minimize the difference towards the primary Unix implementation, thus easing portability from Solaris. +* Improved compatibility with GNU build systems: The biggest part of Linux software is built with GNU autoconf/automake (i.e. GNU autotools), which are unaware of the Linux-specific /usr split. Maintaining the /usr split requires non-trivial project-specific handling in the upstream build system, and in your distribution's packages. With the /usr merge, this work becomes unnecessary and porting packages to Linux becomes simpler. +* Improved compatibility with current upstream development: In order to minimize the delta from your Linux distribution to upstream development the /usr merge is key. + +### Compatibility: The Longer Version + +A unified filesystem layout (as it results from the /usr merge) is more compatible with UNIX than Linux’ traditional split of /bin vs. /usr/bin. Unixes differ in where individual tools are installed, their locations in many cases are not defined at all and differ in the various Linux distributions. The /usr merge removes this difference in its entirety, and provides full compatibility with the locations of tools of any Unix via the symlink from /bin to /usr/bin. + + +#### Example + +* /usr/bin/foo may be called by other tools either via /usr/bin/foo or /bin/foo, both paths become fully equivalent through the /usr merge. The operating system ends up executing exactly the same file, simply because the symlink /bin just redirects the invocation to /usr/bin. +The historical justification for a /bin, /sbin and /lib separate from /usr no longer applies today. ([[More on the historical justification for the split|http://lists.busybox.net/pipermail/busybox/2010-December/074114.html]], by Rob Landley) They were split off to have selected tools on a faster hard disk (which was small, because it was more expensive) and to contain all the tools necessary to mount the slower /usr partition. Today, a separate /usr partition already must be mounted by the initramfs during early boot, thus making the justification for a split-off moot. In addition a lot of tools in /bin and /sbin in the status quo already lost the ability to run without a pre-mounted /usr. There is no valid reason anymore to have the operating system spread over multiple hierarchies, it lost its purpose. + +Solaris implemented the core part of the /usr merge 15 years ago already, and completed it with the introduction of Solaris 11. Solaris has /bin and /sbin only as symlinks in the root file system, the same way as you will have after the /usr merge: [[Transitioning From Oracle Solaris 10 to Oracle Solaris 11 - User Environment Feature Changes|http://docs.oracle.com/cd/E23824_01/html/E24456/userenv-1.html]]. + +Not implementing the /usr merge in your distribution will isolate it from upstream development. It will make porting of packages needlessly difficult, because packagers need to split up installed files into multiple directories and hard code different locations for tools; both will cause unnecessary incompatibilities. Several Linux distributions are agreeing with the benefits of the /usr merge and are already in the process to implement the /usr merge. This means that upstream projects will adapt quickly to the change, those making portability to your distribution harder. + + +### Beyond Compatibility + +One major benefit of the /usr merge is the reduction of complexity of our system: the new file system hierarchy becomes much simpler, and the separation between vendor-supplied OS resources and users resources becomes much cleaner. As a result of the reduced complexity of the hierarchy, packaging becomes much simpler too, since the problems of handling the split in the .spec files go away. + +The merged directory /usr, containing almost the entire vendor-supplied operating system resources, offers us a number of new features regarding OS snapshotting and options for enterprise environments for network sharing or running multiple guests on one host. Most of this is much harder to accomplish, or even impossible, with the current arbitrary split of tools across multiple directories. + +_With all vendor-supplied OS resources in a single directory /usr they may be shared atomically, snapshots of them become atomic, and the file system may be made read-only as a single unit._ + + +#### Example: /usr Network Share + +* With the merged /usr directory we can offer a read-only export of the vendor supplied OS to the network, which will contain almost the entire operating system resources. The client hosts will then only need a minimal host-specific root filesystem with symlinks pointing into the shared /usr filesystem. From a maintenance perspective this is the first time where sharing the operating system over the network starts to make sense. Without the merged /usr directory (like in traditional Linux) we can only share parts of the OS at a time, but not the core components of it that are located in the root file system. The host-specific root filesystem hence traditionally needs to be much larger, cannot be shared among client hosts and needs to be updated individually and often. Vendor-supplied OS resources traditionally ended up "leaking" into the host-specific root file system. + +#### Example: Multiple Guest Operating Systems on the Same Host + +* With the merged /usr directory, we can offer to share /usr read-only with multiple guest operating systems, which will shrink down the guest file system to a couple of MB. The ratio of the per-guest host-only part vs. the shared operating system becomes nearly optimal. +In the long run the maintenance burden resulting of the split-up tools in your distribution, and hard-coded deviating installation locations to distribute binaries and other packaged files into multiple hierarchies will very likely cause more trouble than the /usr merge itself will cause. + + +## Myths and Facts + +**Myth #1**: Fedora is the first OS to implement the /usr merge + +**Fact**: Oracle Solaris has implemented the /usr merge in parts 15 years ago, and completed it in Solaris 11. Fedora is following suit here, it is not the pioneer. + +**Myth #2**: Fedora is the only Linux distribution to implement the /usr merge + +**Fact**: Multiple other Linux distributions have been working in a similar direction. + +**Myth #3**: The /usr merge decreases compatibility with other Unixes/Linuxes + +**Fact**: By providing all binary tools in /usr/bin as well as in /bin (resp. /usr/sbin + /sbin) compatibility with hard coded binary paths in scripts is increased. When a distro A installs a tool “foo” in /usr/bin, and distro B installs it in /bin, then we’ll provide it in both, thus creating compatibility with both A and B. + +**Myth #4**: The /usr merge’s only purpose is to look pretty, and has no other benefits + +**Fact**: The /usr merge makes sharing the vendor-supplied OS resources between a host and networked clients as well as a host and local light-weight containers easier and atomic. Snapshotting the OS becomes a viable option. The /usr merge also allows making the entire vendor-supplied OS resources read-only for increased security and robustness. + +**Myth #5**: Adopting the /usr merge in your distribution means additional work for your distribution's package maintainers + +**Fact**: When the merge is implemented in other distributions and upstream, not adopting the /usr merge in your distribution means more work, adopting it is cheap. + +**Myth #6**: A split /usr is Unix “standard”, and a merged /usr would be Linux-specific + +**Fact**: On SysV Unix /bin traditionally has been a symlink to /usr/bin. A non-symlinked version of that directory is specific to non-SysV Unix and Linux. + +**Myth #7**: After the /usr merge one can no longer mount /usr read-only, as it is common usage in many areas. + +**Fact**: Au contraire! One of the reasons we are actually doing this is to make a read-only /usr more thorough: the entire vendor-supplied OS resources can be made read-only, i.e. all of what traditionally was stored in /bin, /sbin, /lib on top of what is already in /usr. + +**Myth #8**: The /usr merge will break my old installation which has /usr on a separate partition. + +**Fact**: This is perfectly well supported, and one of the reasons we are actually doing this is to make placing /usr of a separate partition more thorough. What changes is simply that you need to boot with an initrd that mounts /usr before jumping into the root file system. Most distributions rely on initrds anyway, so effectively little changes. + +**Myth #9**: The /usr split is useful to have a minimal rescue system on the root file system, and the rest of the OS on /usr. + +**Fact**: On Fedora the root directory contains ~450MB already. This hasn't been minimal since a long time, and due to today's complex storage and networking technologies it's unrealistic to ever reduce this again. In fact, since the introduction of initrds to Linux the initrd took over the role as minimal rescue system that requires only a working boot loader to be started, but not a full file system. + +**Myth #10**: The status quo of a split /usr with mounting it without initrd is perfectly well supported right now and works. + +**Fact**: A split /usr without involvement of an initrd mounting it before jumping into the root file system [[hasn't worked correctly since a long time|http://freedesktop.org/wiki/Software/systemd/separate-usr-is-broken]]. + +**Myth #11**: Instead of merging / into /usr it would make a lot more sense to merge /usr into /. + +**Fact**: This would make the separation between vendor-supplied OS resources and machine-specific even worse, thus making OS snapshots and network/container sharing of it much harder and non-atomic, and clutter the root file system with a multitude of new directories. + + + +--- + + + +If this page didn't answer your questions you may continue reading [[on the Fedora feature page|https://fedoraproject.org/wiki/Features/UsrMove]] and this [[mail from Lennart|http://thread.gmane.org/gmane.linux.redhat.fedora.devel/155511/focus=155792]]. diff --git a/Software/systemd/TipsAndTricks.mdwn b/Software/systemd/TipsAndTricks.mdwn new file mode 100644 index 00000000..a7ef0186 --- /dev/null +++ b/Software/systemd/TipsAndTricks.mdwn @@ -0,0 +1,190 @@ + +[[Back to systemd|http://www.freedesktop.org/wiki/Software/systemd/]] + + +# Tips & Tricks + +Also check out the [[Frequently Asked Questions|http://www.freedesktop.org/wiki/Software/systemd/FrequentlyAskedQuestions]]! + + +## Listing running services + + +[[!format txt """ +$ systemctl +UNIT LOAD ACTIVE SUB JOB DESCRIPTION +accounts-daemon.service loaded active running Accounts Service +atd.service loaded active running Job spooling tools +avahi-daemon.service loaded active running Avahi mDNS/DNS-SD Stack +bluetooth.service loaded active running Bluetooth Manager +colord-sane.service loaded active running Daemon for monitoring attached scanners and registering them with colord +colord.service loaded active running Manage, Install and Generate Color Profiles +crond.service loaded active running Command Scheduler +cups.service loaded active running CUPS Printing Service +dbus.service loaded active running D-Bus System Message Bus +... +"""]] + +## Showing runtime status + + +[[!format txt """ +$ systemctl status udisks2.service +udisks2.service - Storage Daemon + Loaded: loaded (/usr/lib/systemd/system/udisks2.service; static) + Active: active (running) since Wed, 27 Jun 2012 20:49:25 +0200; 1 day and 1h ago + Main PID: 615 (udisksd) + CGroup: name=systemd:/system/udisks2.service + └ 615 /usr/lib/udisks2/udisksd --no-debug + +Jun 27 20:49:25 epsilon udisksd[615]: udisks daemon version 1.94.0 starting +Jun 27 20:49:25 epsilon udisksd[615]: Acquired the name org.freedesktop.UDisks2 on the system message bus +"""]] + +## cgroup tree + + +[[!format txt """ +$ systemd-cgls +└ system + ├ 1 /usr/lib/systemd/systemd --system --deserialize 18 + ├ ntpd.service + │ └ 8471 /usr/sbin/ntpd -u ntp:ntp -g + ├ upower.service + │ └ 798 /usr/libexec/upowerd + ├ wpa_supplicant.service + │ └ 751 /usr/sbin/wpa_supplicant -u -f /var/log/wpa_supplicant.log -c /etc/wpa_supplicant/wpa_supplicant.conf -u -f /var/log/wpa_supplicant.log -P /var/run/wpa_supplicant.pid + ├ nfs-idmap.service + │ └ 731 /usr/sbin/rpc.idmapd + ├ nfs-rquotad.service + │ └ 753 /usr/sbin/rpc.rquotad + ├ nfs-mountd.service + │ └ 732 /usr/sbin/rpc.mountd + ├ nfs-lock.service + │ └ 704 /sbin/rpc.statd + ├ rpcbind.service + │ └ 680 /sbin/rpcbind -w + ├ postfix.service + │ ├ 859 /usr/libexec/postfix/master + │ ├ 877 qmgr -l -t fifo -u + │ └ 32271 pickup -l -t fifo -u + ├ colord-sane.service + │ └ 647 /usr/libexec/colord-sane + ├ udisks2.service + │ └ 615 /usr/lib/udisks2/udisksd --no-debug + ├ colord.service + │ └ 607 /usr/libexec/colord + ├ prefdm.service + │ ├ 567 /usr/sbin/gdm-binary -nodaemon + │ ├ 602 /usr/libexec/gdm-simple-slave --display-id /org/gnome/DisplayManager/Display1 + │ ├ 612 /usr/bin/Xorg :0 -br -verbose -auth /var/run/gdm/auth-for-gdm-O00GPA/database -seat seat0 -nolisten tcp + │ └ 905 gdm-session-worker [pam/gdm-password] + ├ systemd-ask-password-wall.service + │ └ 645 /usr/bin/systemd-tty-ask-password-agent --wall + ├ atd.service + │ └ 544 /usr/sbin/atd -f + ├ ksmtuned.service + │ ├ 548 /bin/bash /usr/sbin/ksmtuned + │ └ 1092 sleep 60 + ├ dbus.service + │ ├ 586 /bin/dbus-daemon --system --address=systemd: --nofork --systemd-activation + │ ├ 601 /usr/libexec/polkit-1/polkitd --no-debug + │ └ 657 /usr/sbin/modem-manager + ├ cups.service + │ └ 508 /usr/sbin/cupsd -f + ├ avahi-daemon.service + │ ├ 506 avahi-daemon: running [epsilon.local] + │ └ 516 avahi-daemon: chroot helper + ├ system-setup-keyboard.service + │ └ 504 /usr/bin/system-setup-keyboard + ├ accounts-daemon.service + │ └ 502 /usr/libexec/accounts-daemon + ├ systemd-logind.service + │ └ 498 /usr/lib/systemd/systemd-logind + ├ crond.service + │ └ 486 /usr/sbin/crond -n + ├ NetworkManager.service + │ ├ 484 /usr/sbin/NetworkManager --no-daemon + │ └ 8437 /sbin/dhclient -d -4 -sf /usr/libexec/nm-dhcp-client.action -pf /var/run/dhclient-wlan0.pid -lf /var/lib/dhclient/dhclient-903b6f6aa7a1-46c8-82a9-7f637dfbb3e4-wlan0.lease -cf /var/run/nm-d... + ├ libvirtd.service + │ ├ 480 /usr/sbin/libvirtd + │ └ 571 /sbin/dnsmasq --strict-order --bind-interfaces --pid-file=/var/run/libvirt/network/default.pid --conf-file= --except-interface lo --listenaddress 192.168.122.1 --dhcp-range 192.168.122.2,1... + ├ bluetooth.service + │ └ 479 /usr/sbin/bluetoothd -n + ├ systemd-udev.service + │ └ 287 /usr/lib/systemd/systemd-udevd + └ systemd-journald.service + └ 280 /usr/lib/systemd/systemd-journald + +"""]] + +## ps with cgroups + + +[[!format txt """ +$ alias psc='ps xawf -eo pid,user,cgroup,args' +$ psc + PID USER CGROUP COMMAND +... + 1 root name=systemd:/systemd-1 /bin/systemd systemd.log_target=kmsg systemd.log_level=debug selinux=0 + 415 root name=systemd:/systemd-1/sysinit.service /sbin/udevd -d + 928 root name=systemd:/systemd-1/atd.service /usr/sbin/atd -f + 930 root name=systemd:/systemd-1/ntpd.service /usr/sbin/ntpd -n + 932 root name=systemd:/systemd-1/crond.service /usr/sbin/crond -n + 935 root name=systemd:/systemd-1/auditd.service /sbin/auditd -n + 943 root name=systemd:/systemd-1/auditd.service \_ /sbin/audispd + 964 root name=systemd:/systemd-1/auditd.service \_ /usr/sbin/sedispatch + 937 root name=systemd:/systemd-1/acpid.service /usr/sbin/acpid -f + 941 rpc name=systemd:/systemd-1/rpcbind.service /sbin/rpcbind -f + 944 root name=systemd:/systemd-1/rsyslog.service /sbin/rsyslogd -n -c 4 + 947 root name=systemd:/systemd-1/systemd-logger.service /lib/systemd/systemd-logger + 950 root name=systemd:/systemd-1/cups.service /usr/sbin/cupsd -f + 955 dbus name=systemd:/systemd-1/messagebus.service /bin/dbus-daemon --system --address=systemd: --nofork --systemd-activation + 969 root name=systemd:/systemd-1/getty@.service/tty6 /sbin/mingetty tty6 + 970 root name=systemd:/systemd-1/getty@.service/tty5 /sbin/mingetty tty5 + 971 root name=systemd:/systemd-1/getty@.service/tty1 /sbin/mingetty tty1 + 973 root name=systemd:/systemd-1/getty@.service/tty4 /sbin/mingetty tty4 + 974 root name=systemd:/user/lennart/2 login -- lennart + 1824 lennart name=systemd:/user/lennart/2 \_ -bash + 975 root name=systemd:/systemd-1/getty@.service/tty3 /sbin/mingetty tty3 + 988 root name=systemd:/systemd-1/polkitd.service /usr/libexec/polkit-1/polkitd + 994 rtkit name=systemd:/systemd-1/rtkit-daemon.service /usr/libexec/rtkit-daemon +... +"""]] + +## Changing the Default Boot Target + + +[[!format txt """ +$ ln -sf /usr/lib/systemd/system/multi-user.target /etc/systemd/system/default.target +"""]] +This line makes the multi user target (i.e. full system, but no graphical UI) the default target to boot into. This is kinda equivalent to setting runlevel 3 as the default runlevel on Fedora/sysvinit systems. + + +[[!format txt """ +$ ln -sf /usr/lib/systemd/system/graphical.target /etc/systemd/system/default.target +"""]] +This line makes the graphical target (i.e. full system, including graphical UI) the default target to boot into. Kinda equivalent to runlevel 5 on fedora/sysvinit systems. This is how things are shipped by default. + + +## What other units does a unit depend on? + +For example, if you want to figure out which services a target like multi-user.target pulls in, use something like this: + + +[[!format txt """ +$ systemctl show -p "Wants" multi-user.target +Wants=rc-local.service avahi-daemon.service rpcbind.service NetworkManager.service acpid.service dbus.service atd.service crond.service auditd.service ntpd.service udisks.service bluetooth.service cups.service wpa_supplicant.service getty.target modem-manager.service portreserve.service abrtd.service yum-updatesd.service upowerd.service test-first.service pcscd.service rsyslog.service haldaemon.service remote-fs.target plymouth-quit.service systemd-update-utmp-runlevel.service sendmail.service lvm2-monitor.service cpuspeed.service udev-post.service mdmonitor.service iscsid.service livesys.service livesys-late.service irqbalance.service iscsi.service netfs.service +"""]] +Instead of "Wants" you might also try "[[WantedBy|WantedBy]]", "Requires", "[[RequiredBy|RequiredBy]]", "Conflicts", "[[ConflictedBy|ConflictedBy]]", "Before", "After" for the respective types of dependencies and their inverse. + + +## What would get started if I booted into a specific target? + +If you want systemd to calculate the "initial" transaction it would execute on boot, try something like this: + + +[[!format txt """ +$ systemd --test --system --unit=foobar.target +"""]] +for a boot target foobar.target. Note that this is mostly a debugging tool that actually does a lot more than just calculate the initial transaction, so don't build scripts based on this. diff --git a/Software/systemd/VirtualizedTesting.mdwn b/Software/systemd/VirtualizedTesting.mdwn new file mode 100644 index 00000000..9620aeac --- /dev/null +++ b/Software/systemd/VirtualizedTesting.mdwn @@ -0,0 +1,73 @@ + +[[Back to systemd|http://www.freedesktop.org/wiki/Software/systemd/]] + + +# Testing systemd during Development in Virtualization + +For quickly testing systemd during development it us useful to boot it up in a container and in a QEMU VM. + + +## Testing in a VM + +Here's a nice hack if you regularly build and test-boot systemd, are gutsy enough to install it into your host, but too afraid or too lazy to continuously reboot your host. + +Create a shell script like this: + + +[[!format txt """ +#!/bin/sh + +sudo sync +sudo /bin/sh -c 'echo 3 > /proc/sys/vm/drop_caches' +sudo umount / +sudo modprobe kvm-intel + +exec sudo qemu-kvm -smp 2 -m 512 -snapshot /dev/sda +"""]] +This will boot your local host system as a throw-away VM guest. It will take your main harddisk, boot from it in the VM, allow changes to it, but these changes are all just buffered in memory and never hit the real disk. Any changes made in this VM will be lost when the VM terminates. I have called this script "q", and hence for test booting my own system all I do is type the following command in my systemd source tree and I can see if it worked. + + +[[!format txt """ +$ make -j10 && sudo make install && q +"""]] +The first three lines are necessary to ensure that the kernel's disk caches are all synced to disk before qemu takes the snapshot of it. Yes, invoking "umount /" will sync your file system to disk as a side effect, even though it will actually fail. When the machine boots up the file system will still be marked dirty (and hence you will get an fsck, usually), but it will work fine nonetheless in virtually all cases. + +Of course, if the host's hard disk changes while the VM is running this will be visible to the VM, and might confuse it. If you use this little hack you should keep changes on the host at a minimum, hence. Yeah this all is a hack, but a really useful and neat one. + +YMMV if you use LVM or btrfs. + + +## Testing in a Container + +Test-booting systemd in a container has the benefit of being much easier to debug/instrument from the outside. + +**Important:** As preparation it is essential to turn off auditing entirely on your system. Auditing is broken with containers, and will trigger all kinds of error in containers if not turned off. Use _audit=0_ on the host's kernel command line to turn it off. + +Then, as the first step I install Fedora into a container tree: + + +[[!format txt """ +$ sudo yum -y --releasever=18 --nogpg --installroot=$HOME/fedora-tree --disablerepo='*' --enablerepo=fedora install systemd passwd yum fedora-release vim-minimal +"""]] +You can do something similar with debootstrap on a Debian system. Now, we need to set a root password in order to be able to log in: + + +[[!format txt """ +$ sudo systemd-nspawn -D ~/fedora-tree/ +# passwd +... +# ^D +"""]] +As the next step we can already boot the container: + + +[[!format txt """ +$ sudo systemd-nspawn -bD ~/fedora-tree/ 3 +"""]] +To test systemd in the container I then run this from my source tree on the host: + + +[[!format txt """ +$ make -j10 && sudo DESTDIR=$HOME/fedora-tree make install && sudo systemd-nspawn -bD ~/fedora-tree/ 3 +"""]] +And that's already it. diff --git a/Software/systemd/catalog.mdwn b/Software/systemd/catalog.mdwn new file mode 100644 index 00000000..94a78280 --- /dev/null +++ b/Software/systemd/catalog.mdwn @@ -0,0 +1,65 @@ + +[[Back to systemd|http://www.freedesktop.org/wiki/Software/systemd/]] + + +# Journal Message Catalogs + +Starting with 196 systemd includes a message catalog system which allows augmentation on display of journal log messages with short explanation texts, keyed off the MESSAGE_ID= field of the entry. Many important log messages generated by systemd itself have message catalog entries. External packages can easily provide catalog data for their own messages. + +The message catalog has a number of purposes: + +* Provide the administrator, user or developer with further information about the issue at hand, beyond the actual message text +* Provide links to further documentation on the topic of the specific message +* Provide native language explanations for English language system messages +* Provide links for support forums, hotlines or other contacts + +## Format + +Message catalog source files are simple text files that follow an RFC822 inspired format. To get an understanding of the format [[here's an example file|http://cgit.freedesktop.org/systemd/systemd/plain/catalog/systemd.catalog]], which includes entries for many important messages systemd itself generates. On installation of a package that includes message catalogs all installed message catalog source files get compiled into a binary index, which is then used to look up catalog data. + +journalctl's "-x" command line parameter may be used to augment on display journal log messages with message catalog data when browsing. "journalctl --list-catalog" may be used to print a list of all known catalog entries. + +To register additional catalog entries, packages may drop (text) catalog files into /usr/lib/systemd/catalog/ with a suffix of .catalog. The files are not accessed directly when needed, but need to be built into a binary index file with "journalctl --update-catalog". + +Here's an example how a single catalog entry looks like in the text source format. Multiple of these may be listed one after the other per catalog source file: + + +[[!format txt """ +-- fc2e22bc6ee647b6b90729ab34a250b1 +Subject: Process @COREDUMP_PID@ (@COREDUMP_COMM@) dumped core +Defined-By: systemd +Support: http://lists.freedesktop.org/mailman/listinfo/systemd-devel +Documentation: man:core(5) +Documentation: http://www.freedesktop.org/wiki/Software/systemd/catalog/@MESSAGE_ID@ + +Process @COREDUMP_PID@ (@COREDUMP_COMM@) crashed and dumped core. + +This usually indicates a programming error in the crashing program and +should be reported to its vendor as a bug. +"""]] +The text format of the .catalog files is as follows: + +* Simple, UTF-8 text files, with usual line breaks at 76 chars. URLs and suchlike where line-breaks are undesirable may use longer lines. As catalog files need to be usable on text consoles it is essential that the 76 char line break rule is otherwise followed for human readable text. +* Lines starting with # are ignored, and may be used for comments. +* The files consist of a series of entries. For each message ID (in combination with a locale) only a single entry may be defined. Every entry consists of: + * A separator line beginning with "-- ", followed by a hexadecimal message ID formatted as lower case ASCII string. Optionally, the message ID may be suffixed by a space and a locale identifier, such as "de" or "fr_FR", if i10n is required. + * A series of entry headers, in RFC822-style but not supporting continuation lines. Some header fields may appear more than once per entry. The following header fields are currently known (but additional fields may be added later): + * Subject: A short, one-line human readable description of the message + * Defined-By: Who defined this message. Usually a package name or suchlike + * Support: A URI for getting further support. This can be a web URL or a telephone number in the tel:// namespace + * Documentation: URIs for further user, administrator or developer documentation on the log entry. URIs should be listed in order of relevance, the most relevant documentation first. + * An empty line + * The actual catalog entry payload, as human readable prose. Multiple paragraphs may be separated by empty lines. The prose should first describe the message and when it occurs, possibly followed by recommendations how to deal with the message and (if it is an error message) correct the problem at hand. This message text should be readable by users and administrators. Information for developers should be stored externally instead, and referenced via a Documentation= header field. +* When a catalog entry is printed on screen for a specific log entry simple variable replacements are applied. Journal field names enclosed in @ will be replaced by their values, if such a field is available in an entry. If such a field is not defined in an entry the enclosing @ will be dropped but the variable name is kept. +See [[systemd's own message catalog|http://cgit.freedesktop.org/systemd/systemd/plain/catalog/systemd.catalog]] for a complete example for a catalog file. + + +## Adding Message Catalog Support to Your Program + +Note that the message catalog is only available for messages generated with the MESSAGE_ID= journal meta data field, as this is need to find the right entry for a message. For more information on the MESSAGE_ID= journal entry field see [[systemd.journal-fields(7)|http://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html]]. + +To add message catalog entries for log messages your application generates, please follow the following guidelines: + +* Use the [[native Journal logging APIs|http://0pointer.de/blog/projects/journal-submit.html]] to generate your messages, and define message IDs for all messages you want to add catalog entries for. You may use "journalctl --new-id128" to allocate new message IDs. +* Write a catalog entry file for your messages and ship them in your package and install them to `/usr/lib/systemd/catalog/` (if you package your software with RPM use `%_journalcatalogdir`) +* Ensure that after installation of your application's RPM/DEB "`journalctl --update-catalog`" is executed, in order to update the binary catalog index. (if you package your software with RPM use the `%journal_catalog_update` macro to achieve that.)
\ No newline at end of file diff --git a/Software/systemd/dbus.mdwn b/Software/systemd/dbus.mdwn new file mode 100644 index 00000000..4c850d74 --- /dev/null +++ b/Software/systemd/dbus.mdwn @@ -0,0 +1,1227 @@ + +[[Back to systemd|http://www.freedesktop.org/wiki/Software/systemd/]] + + +# The D-Bus API of systemd/PID 1 + +systemd and its auxiliary daemons expose a number of APIs on D-Bus. The following describes the various APIs exposed by the system and service manager itself, and does not cover the auxiliary daemons. + +The service manager exposes a number of objects on the bus: one manager object as central entry point for clients and individual objects for each unit and for each queued job. The unit objects each implement a generic Unit interface plus a type-specific interface. For example, service units implement `org.freedesktop.systemd1.Unit` as well as `org.freedesktop.system1.Service`. The manager object can be used to list unit and job objects, or to directly convert a unit name or job id into a bus path of the corresponding D-Bus objects. + +Note that properties exposing time values are usually encoded in microseconds (usec) on the bus, even if their corresponding settings in the unit files are in seconds. + +In contrast to most of the other services of the systemd suite PID 1 does not use PolicyKit for controlling access to privileged operations, but relies exclusively on the low-level D-Bus policy language. (This is done in order to avoid a cyclic dependency between PolicyKit and systemd/PID 1.) This means that sensitive operations exposed by PID 1 on the bus are generally not available to unprivileged processes directly. However some (such as shutdown/reboot/suspend) are made available via [[logind's interfaces|http://www.freedesktop.org/wiki/Software/systemd/logind]]. + + +## The Manager Object + +The main entry point object is available on the fixed `/org/freedesktop/systemd1` object path: + + +[[!format txt """ +$ gdbus introspect --system --dest org.freedesktop.systemd1 --object-path /org/freedesktop/systemd1 +node /org/freedesktop/systemd1 { + interface org.freedesktop.systemd1.Manager { + methods: + GetUnit(in s name, + out o unit); + GetUnitByPID(in u pid, + out o unit); + LoadUnit(in s name, + out o unit); + StartUnit(in s name, + in s mode, + out o job); + StartUnitReplace(in s old_unit, + in s new_unit, + in s mode, + out o job); + StopUnit(in s name, + in s mode, + out o job); + ReloadUnit(in s name, + in s mode, + out o job); + RestartUnit(in s name, + in s mode, + out o job); + TryRestartUnit(in s name, + in s mode, + out o job); + ReloadOrRestartUnit(in s name, + in s mode, + out o job); + ReloadOrTryRestartUnit(in s name, + in s mode, + out o job); + KillUnit(in s name, + in s who, + in i signal); + ResetFailedUnit(in s name); + GetJob(in u id, + out o job); + CancelJob(in u id); + ClearJobs(); + ResetFailed(); + ListUnits(out a(ssssssouso) units); + ListJobs(out a(usssoo) jobs); + Subscribe(); + Unsubscribe(); + CreateSnapshot(in s name, + in b cleanup, + out o unit); + RemoveSnapshot(in s name); + Reload(); + Reexecute(); + Exit(); + Reboot(); + PowerOff(); + Halt(); + KExec(); + SwitchRoot(in s new_root, + in s init); + SetEnvironment(in as names); + UnsetEnvironment(in as names); + UnsetAndSetEnvironment(in as unset, + in as set); + ListUnitFiles(out a(ss) changes); + GetUnitFileState(in s file, + out s state); + EnableUnitFiles(in as files, + in b runtime, + in b force, + out b carries_install_info, + out a(sss) changes); + DisableUnitFiles(in as files, + in b runtime, + out a(sss) changes); + ReenableUnitFiles(in as files, + in b runtime, + in b force, + out b carries_install_info, + out a(sss) changes); + LinkUnitFiles(in as files, + in b runtime, + in b force, + out a(sss) changes); + PresetUnitFiles(in as files, + in b runtime, + in b force, + out b carries_install_info, + out a(sss) changes); + MaskUnitFiles(in as files, + in b runtime, + in b force, + out a(sss) changes); + UnmaskUnitFiles(in as files, + in b runtime, + out a(sss) changes); + signals: + UnitNew(s id, + o unit); + UnitRemoved(s id, + o unit); + JobNew(u id, + o job, + s unit); + JobRemoved(u id, + o job, + s unit, + s result); + StartupFinished(t firmware, + t loader, + t kernel, + t initrd, + t userspace, + t total); + UnitFilesChanged(); + properties: + readonly s Version = 'systemd 185'; + readonly s Features = '+PAM +LIBWRAP +AUDIT +SELINUX +IMA +SYSVINIT +LIBCRYPTSETUP'; + readonly s Tainted = ''; + readonly t FirmwareTimestamp = 0; + readonly t FirmwareTimestampMonotonic = 0; + readonly t LoaderTimestamp = 0; + readonly t LoaderTimestampMonotonic = 0; + readonly t KernelTimestamp =1340822954124381; + readonly t KernelTimestampMonotonic = 0; + readonly t InitRDTimestamp = 1340822954724393; + readonly t InitRDTimestampMonotonic = 2431571; + readonly t UserspaceTimestamp = 1340822956472674; + readonly t UserspaceTimestampMonotonic = 4179853; + readonly t FinishTimestamp = 1340822966825952; + readonly t FinishTimestampMonotonic = 14533131; + readwrite s LogLevel = 'debug'; + readwrite s LogTarget = 'kmsg'; + readonly u NNames = 249; + readonly u NJobs = 0; + readonly u NInstalledJobs = 4; + readonly u NFailedJobs = 0; + readonly d Progress = 1.0; + readonly as Environment = ['SYSFONT=latarcyrheb-sun16', 'PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin', 'DRACUT_QUIET=yes', 'LANG=en_US.UTF-8', 'KEYTABLE=de-latin1']; + readonly b ConfirmSpawn = false; + readonly b ShowStatus = true; + readonly as UnitPath = ['/etc/systemd/system', '/run/systemd/generator', '/usr/lib/systemd/system']; + readonly s ControlGroupHierarchy = '/system'; + readonly as DefaultControllers = ['cpu']; + readonly s DefaultStandardOutput = 'journal'; + readonly s DefaultStandardError = 'inherit'; + readwrite s RuntimeWatchdogUSec = 0; + readwrite s ShutdownWatchdogUSec = 600000000; + readonly s Virtualization = 'kvm'; + }; + interface org.freedesktop.DBus.Properties { + }; + interface org.freedesktop.DBus.Peer { + }; + interface org.freedesktop.DBus.Introspectable { + }; +}; +"""]] + +### Security + +Read access is generally granted to all clients, but changes may only be made by privileged clients. PolicyKit is not used by this service, and access controlled exclusively via the D-Bus policy enforcement. + + +### Methods + +Note that many of the calls exist twice: once on the Manager object, and once on the respective unit objects. This is to optimize access times so that methods that belong to unit objects do not have to be called with a resolved unit path, but can be called with only the unit id, too. + +**GetUnit()** may be used to get the unit object path for a unit name. It takes the unit name and returns the object path. If a unit has not been loaded yet by this name this call will fail. + +**GetUnitByPID()** may be used to get the unit object path of the unit a process ID belongs to. Takes a Unix PID and returns the object path. The PID must refer to an existing process of the system. + +**LoadUnit()** is similar to GetUnit() but will load the unit from disk if possible. + +**StartUnit()** enqeues a start job, and possibly depending jobs. Takes the unit to activate, plus a mode string. The mode needs to be one of replace, fail, isolate, ignore-dependencies, ignore-requirements. If "replace" the call will start the unit and its dependencies, possibly replacing already queued jobs that conflict with this. If "fail" the call will start the unit and its dependencies, but will fail if this would change an already queued job. If "isolate" the call will start the unit in question and terminate all units that aren't dependencies of it. If "ignore-dependencies" it will start a unit but ignore all its dependencies. If "ignore-requirements" it will start a unit but only ignore the requirement dependencies. It is not recommended to make use of the latter two options. Returns the newly created job object. + +**StartUnitReplace()** is similar to **StartUnit()** but replaces a job that is queued for one unit by a job for another. + +**StopUnit()** is similar to **StartUnit()** but stops the specified unit rather than starting it. Note that "isolate" mode is invalid for this call. + +**ReloadUnit()**, **RestartUnit()**, **TryRestartUnit()**, **ReloadOrRestartUnit()**, **ReloadOrTryRestartUnit()** may be used to restart and/or reload a unit, and takes similar arguments as **StartUnit()**. Reloading is done only if the unit is already running and fails otherwise. If a service is restarted that isn't running it will be started, unless the "Try" flavor is used in which case a service that isn't running is not affected by the restart. The "ReloadOrRestart" flavors attempt a reload if the unit supports it and use a restart otherwise. + +**KillUnit()** may be used to kill (i.e. send a signal to) all processes of a unit. Takes the unit name, an enum who and a UNIX signal number to send. The who enum is one of "main", "control" or "all". If "main", only the main process of a unit is killed. If "control" only the control process of the unit is killed, if "all" all processes are killed. A "control" process is for example a process that is configured via ExecStop= and is spawned in parallel to the main daemon process, in order to shut it down. + +**GetJob()** returns the job object path for a specific job, identified by its id. + +**CancelJob()** cancels a specific job identified by its numer ID. This operation is also available in the **!Cancel()** method of Job objects (see below), and exists primarily to reduce the necessary round trips to execute this operation. Note that this will not have any effect on jobs whose execution has already begun. + +**ClearJobs()** flushes the job queue, removing all jobs that are still queued. Note that this does not have any effect on jobs whose execution has already begun, it only flushes jobs that are queued and have not yet begun execution. + +**ResetFailedUnit()** resets the "failed" state of a specific unit. + +**ResetFailed()** resets the "failed" state of all units. + +**ListUnits()** returns an array with all currently loaded units. Note that units may be known by multiple names at the same name, and hence there might be more unit names loaded than actual units behind them. The array consists of structures with the following elements: + +* The primary unit name as string +* The human readable description string +* The load state (i.e. whether the unit file has been loaded successfully) +* The active state (i.e. whether the unit is currently started or not) +* The sub state (a more fine-grained version of the active state that is specific to the unit type, which the active state is not) +* A unit that is being followed in its state by this unit, if there is any, otherwise the empty string. +* The unit object path +* If there is a job queued for the job unit the numeric job id, 0 otherwise +* The job type as string +* The job object path +**ListJobs()** returns an array with all currently queued jobs. Returns an array consisting of structures with the following elements: + +* The numeric job id +* The primary unit name for this job +* The job type as string +* The job state as string +* The job object path +* The unit object path +**Subscribe()** enables most bus signals to be sent out. Clients which are interested in signals need to call this function. Signals are only sent out if at least one client invoked this function. **Unsubscribe()** undoes the signal subscription that Subscribe() implements. It is not necessary to invoke Unsubscribe() as clients are tracked. Signals are no longer sent out as soon as all clients which previously asked for Subscribe() either closed the bus connection or invoked Unsubscribe(). + +**CreateSnapshot()** creates a snapshot unit for the current system state, and stores it under the specified name. It will return the unit object path to the new snapshot. If the cleanup boolean is true the snapshot will be removed automatically when it has been activated, otherwise it remains and can be activated multiple times. Snapshots are not persistent. + +**RemoveSnapshot()** removes a snapshot. This call is also available in the **Remove()** method of Snapshot objects (see below), and exists primarily to reduce the number of required roundtrips for this call. + +**Reload()** may be invoked to reload all unit files. + +**Reexecute()** may be invoked to reexecute the main manager process. It will serialize its state, reexecute, and deserizalize the state again. This is useful for upgrades and is a more comprehensive version of Reload(). + +**Exit()** may be invoked to ask the manager to exit. This is not available for the system manager and is useful only for user session managers. + +**Reboot()**, **PowerOff()**, **Halt()**, **KExec()** may be used to ask for immediate reboot, powering down, halt or kexec based reboot of the system. Note that this does not shut down any services and immediately transitions into the reboot process. These functions are normally only called as last step of shutdown, and should not be called directly. To shut down the machine it is a much better choice generally to invoke Reboot() and PoweOff() on the logind manager object. See [[On logind|http://www.freedesktop.org/wiki/Software/systemd/logind]] for more information. + +**SwitchRoot()** may be used to transition to a new root directory. This is intended to be used by initial RAM disks. The call takes two arguments: the new root directory (which needs to be specified), plus an init binary path (which may be left empty, in which case it is automatically searched for). The state of the system manager will be serialized before the transition. After the transition the manager binary on the main system is invoked and replaces the old PID 1. All state will then be deserialized. + +**SetEnvironment()** may be used to alter the environment block that is passed to all spawned processes. Takes a string array with environment variable assignments. Settings passed will override previously set variables. + +**UnsetEnvironment()** may be used to unset environment variables. Takes a string array with environment variable names. All variables specified will be unset (if they have been set previously) and no longer be passed to all spawned processes. This call has no effect for variables that were previously not set, but will not fail in that case. + +**UnsetAndSetEnvironment()** is a combination of UnsetEnvironment() and SetEnvironment(). It takes two lists. The first one is a list of variables to unset, the second one of assignments to set. If a variable is listed in both the variable is set after this call, i.e. the set list overrides the unset list. + +**ListUnitFiles()** returns an array of unit names plus their enablement status. Note that ListUnit() returns a list of units currently loaded into memory, while ListUnitFiles() returns a list of unit _files_ that could be found on disk. Note that while most units are read directly from a unit file with the same name some units are not backed by files, and some files (templates) cannot directly be loaded as units but need to be instantiated. + +**GetUnitFileState()** returns the current enablement status of specific unit file. + +**EnableUnitFiles()** may be used to enable one or more units in the system (by creating symlinks to them in /etc or /run). It takes a list of unit files to enable (either just file names or full absolute paths if the unit files are residing outside the usual unit search paths), and two booleans: the first controls whether the unit shall be enabled for runtime only (true, /run), or persistently (false, /etc). The second one controls whether symlinks pointing to other units shall be replaced if necessary. This call returns one boolean and an array with the changes made. The boolean signals whether the unit files contained any enablement information (i.e. an [Install]) section. The changes list consists of structures with three strings: the type of the change (one of _symlink_ or _unlink_), the file name of the symlink and the destination of the symlink. Note that most of the following calls return a changes list in the same format. + +Similar, **DisableUnitFiles()** disables one or more units in the system, i.e. removes all symlinks to them in /etc and /run. + +Similar, **ReenableUnitFiles()** applies the changes to one or more units that would result from disabling and enabling the unit quickly one after the other in an atomic fashion. This is useful to apply updated [Install] information contained in unit files. + +Similar, **LinkUnitFiles()** links unit files (that are located outside of the usual unit search paths) into the unit search path. + +Similar, **PresetUnitFiles()** enables/disables one or more units file according to the preset policy. See [[Presets|http://freedesktop.org/wiki/Software/systemd/Preset]] for more information. + +Similar, **MaskUnitFiles()** masks unit files, and **UnmaskUnitFiles()** unmasks them again. + + +### Signals + +Note that most signals are sent out only after **Subscribe()** has been invoked by at least one client. Make sure to invoke this call when subscribing to these signals! + +**UnitNew()** and **UnitRemoved()** are sent out each time a new unit is loaded or unloaded. Note that this has little to do with whether a unit is available on disk or not, and simply reflects the units that are currently loaded into memory. The signals take two parameters: the primary unit name and the object path. + +**JobNew()** and **JobRemoved()** are sent out each time a new job is queued or dequeued. Both signals take the numeric job ID, the bus path and the primary unit name for this job as argument. **JobRemoved()** also includes a result string, being one of `done`, `canceled`, `timeout`, `failed`, `dependency`, `skipped`. `done` indicates successful execution of a job. `canceled` indicates that a job has been canceled (via CancelJob() above) before it finished execution (this doesn't necessarily mean though that the job operation is actually cancelled too, see above). `timeout` indicates that the job timeout was reached. `failed` indicates that the job failed. `dependency` indicates that a job this job has been depending on failed and the job hence has been removed too. `skipped` indicates that a job was skipped because it didn't apply to the units current state. + +**StartupFinished()** is sent out when startup finished. It carries six usec timespan values each indicating how much boot time has been spent in the firmware (if known), in the boot loader (if known), in the kernel initialization phase, in the initrd (if known), in userspace and in total. These values may also be calculated from the FirmwareTimestampMonotonic, LoaderTimestampMonotonic, InitRDTimestampMonotonic, UserspaceTimestampMonotonic, FinishTimestampMonotonic properties (see below). + +**UnitFilesChanged()** is sent out each time the list of enabled or masked unit files on disk have changed. + + +### Properties + +Most properties simply reflect the respective options in `/etc/systemd/system.conf` and the kernel command line. The others: + +**Version** encodes the version string of the running systemd instance. + +**Features** encodes the features that have been enabled resp. disabled for this build. Enabled options are prefixed with +, disabled options with -. + +**Tainted** encodes a couple of taint flags, as colon separated list. When systemd detects it is run on a system with certain problems it will set an appropriate taint flag. Taints may be used to lower the chance of bogus bug reports. The following taints are currently known: `split-usr`, `mtab-not-symlink`, `cgroups-missing`, `local-hwclock`. `split-usr` is set if /usr is not pre-mounted when systemd is first invoked. See [[Booting Without /usr is Broken|http://freedesktop.org/wiki/Software/systemd/separate-usr-is-broken]] for details why this is bad. `mtab-not-symlink` indicates that `/etc/mtab` is not a symlink to `/proc/self/mounts` as required. `cgroups-missing` indicates that control groups have not been enabled in the kernel. `local-hwclock` indicates that the local RTC is configured to be in local time rather than UTC. + +**FirmwareTimestamp**, **FirmwareTimestampMonotonic**, **LoaderTimestamp**, **LoaderTimestampMonotonic**, **KernelTimestamp**, **KernelTimestampMonotonic**, **InitRDTimestamp**, **InitRDTimestampMonotonic**, **UserspaceTimestamp**, **UserspaceTimestampMonotonic**, **FinishTimestamp**, **FinishTimestampMonotonic** encode CLOCK_REALTIME resp. CLOCK_MONOTONIC usec timestamps taken when the firmware first began execution, when the boot loader first began execution, when the kernel first began execution, when the initrd first began execution, when the main systemd instance began execution and finally, when all queued startup jobs finished execution. These values are useful for determining boot-time performance. Note that as monotonic time begins with the kernel startup the KernelTimestampMonotonic timestamp will always be 0, and FirmwareTimestampMonotonic and LoaderTimestampMonotonic are to be read as negative values. Also, not all fields are available, depending on the used firmware, boot loader or initrd implementation. In these cases the resp. pairs of timestamps are both 0, indicating that no data is available. + +**NNames** encodes how many unit names are currently known. This only includes names of units that are currently loaded and can be more than actually loaded units since units may have more than one name. + +**NJobs** encodes how many jobs are currently queued. + +**NInstalledJobs** encodes how many jobs have ever been queued in total. + +**NFailedJobs** encodes how many jobs have ever failed in total. + +**Progress** encodes boot progress as floating point value between 0.0 and 1.0. This value begins at 0.0 at early-boot and ends at 1.0 when boot is finished and is based on the number of executed and queued jobs. After startup this field is always 1.0 indicating a finished boot. + +**Environment** encodes the environment block passed to all executed services. It may be altered with bus calls such as SetEnvironment() (see above). + +**UnitPath** encodes the currently active unit file search path. It is an array of strings, each being one file system path. + +**ControlGroupHierarchy** encodes the control group root path for this systemd instance. Prefixing `/sys/fs/cgroup/` turns this into a file system path. + +**Virtualization** contains a short ID string describing the virtualization technology the system runs in. On bare-metal hardware this is the empty string, otherwise an identifier such as "kvm", "vmware" and so on. For a full list of IDs see systemd-detect-virt(1). Note that only the "innermost" virtualization technology is exported here. This detects both full-machine virtualizations (VMs) and shared-kernel virtualization (containers). + + +## Unit Objects + +All Unit objects implement the generic `org.freedesktop.systemd1.Unit` interface. Depending on the unit type they also implement one unit-type-specific interface, as described below. + + +[[!format txt """ +$ gdbus introspect --system --dest org.freedesktop.systemd1 --object-path /org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice +node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice { + interface org.freedesktop.systemd1.Unit { + methods: + Start(in s mode, + out o job); + Stop(in s mode, + out o job); + Reload(in s mode, + out o job); + Restart(in s mode, + out o job); + TryRestart(in s mode, + out o job); + ReloadOrRestart(in s mode, + out o job); + ReloadOrTryRestart(in s mode, + out o job); + Kill(in s who, + in i signal); + ResetFailed(); + signals: + properties: + readonly s Id = 'avahi-daemon.service'; + readonly as Names = ['avahi-daemon.service']; + readonly s Following = ''; + readonly as Requires = ['avahi-daemon.socket', 'systemd-journald.socket', 'dbus.socket', 'basic.target']; + readonly as RequiresOverridable = []; + readonly as Requisite = []; + readonly as RequisiteOverridable = []; + readonly as Wants = []; + readonly as BindsTo = []; + readonly as RequiredBy = []; + readonly as RequiredByOverridable = []; + readonly as WantedBy = ['multi-user.target', 'graphical.target']; + readonly as BoundBy = []; + readonly as Conflicts = ['shutdown.target']; + readonly as ConflictedBy = []; + readonly as Before = ['shutdown.target', 'multi-user.target']; + readonly as After = ['avahi-daemon.socket', 'systemd-journald.socket', 'dbus.socket', 'basic.target']; + readonly as OnFailure = []; + readonly as Triggers = []; + readonly as TriggeredBy = ['avahi-daemon.socket']; + readonly as PropagatesReloadTo = []; + readonly as ReloadPropagatedFrom = []; + readonly as RequiresMountsFor = []; + readonly s Description = 'Avahi mDNS/DNS-SD Stack'; + readonly s SourcePath = ''; + readonly as Documentation = []; + readonly s LoadState = 'loaded'; + readonly s ActiveState = 'active'; + readonly s SubState = 'running'; + readonly s FragmentPath = '/usr/lib/systemd/system/avahi-daemon.service'; + readonly s UnitFileState = 'enabled'; + readonly t InactiveExitTimestamp = 1342738862998751; + readonly t InactiveExitTimestampMonotonic = 6799251; + readonly t ActiveEnterTimestamp = 1342738863176072; + readonly t ActiveEnterTimestampMonotonic = 6976573; + readonly t ActiveExitTimestamp = 0; + readonly t ActiveExitTimestampMonotonic = 0; + readonly t InactiveEnterTimestamp = 0; + readonly t InactiveEnterTimestampMonotonic = 0; + readonly b CanStart = true; + readonly b CanStop = true; + readonly b CanReload = true; + readonly b CanIsolate = false; + readonly (uo) Job = (0, '/org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice'); + readonly b StopWhenUnneeded = false; + readonly b RefuseManualStart = false; + readonly b RefuseManualStop = false; + readonly b AllowIsolate = false; + readonly b DefaultDependencies = true; + readonly b OnFailureIsolate = false; + readonly b IgnoreOnIsolate = false; + readonly b IgnoreOnSnapshot = false; + readonly s DefaultControlGroup = 'name=systemd:/system/avahi-daemon.service'; + readonly as ControlGroup = ['cpu:/system/avahi-daemon.service', 'name=systemd:/system/avahi-daemon.service']; + readonly a(sss) ControlGroupAttributes = []; + readonly b NeedDaemonReload = false; + readonly t JobTimeoutUSec = 0; + readonly t ConditionTimestamp = 1342738862978791; + readonly t ConditionTimestampMonotonic = 6779295; + readonly b ConditionResult = true; + readonly (ss) LoadError = ('', ''); + }; + interface org.freedesktop.systemd1.Service { + }; + interface org.freedesktop.DBus.Properties { + }; + interface org.freedesktop.DBus.Peer { + }; + interface org.freedesktop.DBus.Introspectable { + }; +}; +"""]] + +### Methods + +**Start()**, **Stop()**, **Reload()**, **Restart()**, **TryRestart()**, **ReloadOrRestart()**, **ReloadOrTryRestart()**, **Kill()** and **ResetFailed()** implement the same operation as the respective method calls on the Manager object (see above), however operate on the unit object and hence do not take a unit name parameter. Invoking the methods directly on the Manager object has the advantage of not requiring a **GetUnit()** call to get the unit object for a specific unit name. Calling the methods on the Manager object is hence a round trip optimization. + + +### Properties + +**Id** contains the primary name of the unit. + +**Names** contains all names of the unit, including the primary name that is also exposed in **Id**. + +**Following** either contains the empty string or contains the name of another unit that this unit follows in state. This is used for some device units which reflect the unit state machine of another unit, and which other unit this is might possibly change. + +**Requires**, **RequiresOverridable**, **Requisite**, **RequisiteOverridable**, **Wants**, **BindsTo**, **RequiredBy**, **RequiredByOverridable**, **WantedBy**, **BoundBy**, **Conflicts**, **ConflictedBy**, **Before**, **After**, **OnFailure**, **Triggers**, **TriggeredBy**, **PropagatesReloadTo**, **RequiresMountsFor** contain arrays which encode the dependencies and their inverse dependencies (where this applies), as configured in the unit file or determined automatically. + +**Description** contains the human readable description string for the unit. + +**SourcePath** contains the path to a configuration file this unit is automatically generated from in case it is not a native unit (in which case it contains the empty string). For example, all mount units generated from `/etc/fstab` have this field set to this value. + +**Documentation** contains a string array with URLs of documentation for this unit. + +**LoadState** contains a state value that reflects whether the configuration file of this unit has been loaded. The following states are currently defined: _loaded_, _error_, _masked_. _loaded_ indicates that the configuration was successfully loaded. _error_ indicates that the configuration failed to load, the **LoadError** field (see below) contains information about the cause of this failure. _masked_ indicates that the unit is currently masked out (i.e. symlinked to /dev/null or suchlike). Note that the **LoadState** is fully orthogonal to the **ActiveState** (see below) as units without valid loaded configuration might be active (because configuration might have been reloaded at a time where a unit was already active). + +**ActiveState** contains a state value that reflects whether the unit is currently active or not. The following states are currently defined: _active_, _reloading_, _inactive_, _failed_, _activating_, _deactivating_. _active_ indicates that unit is active (obviously...). _reloading_ indicates that the unit is active and currently reloading its configuration. _inactive_ indicates that it is inactive and the previous run was successful or no previous run has taken place yet. _failed_ indicates that it is inactive and the previous run was not successful (more information about the reason for this is available on the unit type specific interfaces, for example for services in the **Result** property, see below). _activating_ indicates that the unit has previously been inactive but is currently in the process of entering an active state. Conversely _deactivating_ indicates that the unit is currently in the process of deactivation. + +**SubState** encodes states of the same state machine that **ActiveState** covers, but knows more fine-grained states that are unit-type-specific. Where **ActiveState** only covers six high-level states, **SubState** covers possibly many more low-level unit-type-specific states that are mapped to the six high-level states. Note that multiple low-level states might map to the same high-level state, but not vice versa. Not all high-level states have low-level counterparts on all unit types. At this point the low-level states are not documented here, and are more likely to be extended later on than the common high-level states explained above. + +**FragmentPath** contains the unit file path this unit was read from, if there is any (if not this contains the empty string). + +**UnitFileState** encodes the install state of the unit file of **FragmentPath**. It currently knows the following states: _enabled_, _enabled-runtime_, _linked_, _linked-runtime_, _masked_, _masked-runtime_, _static_, _disabled_, _invalid_. _enabled_ indicates that a unit file is permanently enabled. _enable-runtime_ indicates the unit file is only temporarily enabled, and will no longer be enabled after a reboot (that means, it is enabled via /run symlinks, rather than /etc). _linked_ indicates that a unit is linked into /etc permanently, _linked_ indicates that a unit is linked into /run temporarily (until the next reboot). _masked_ indicates that the unit file is masked permanently, _masked-runtime_ indicates that it is only temporarily masked in /run, until the next reboot. _static_ indicates that the unit is statically enabled, i.e. always enabled and doesn't need to be enabled explicitly. _invalid_ indicates that it could not be determined whether the unit file is enabled. + +**InactiveExitTimestamp**, **InactiveExitTimestampMonotonic**, **ActiveEnterTimestamp**, **ActiveEnterTimestampMonotonic**, **ActiveExitTimestamp**, **ActiveExitTimestampMonotonic**, **InactiveEnterTimestamp**, **InactiveEnterTimestampMonotonic** contain CLOCK_REALTIME and CLOCK_MONOTONIC 64bit usec timestamps of the last time a unit left the inactive state, entered the active state, exited the active state, or entered an inactive state. These are the points in time where the unit transitioned _inactive/failed_ → _activating_, _activating_ → _active_, _active_ → _deactivating_, and finally _deactivating_ → _inactive/failed_. The fields are 0 in case such a transition has not been recording on this boot yet. + +**CanStart**, **CanStop**, **CanReload** encodes as booleans whether the unit supports the start, stop or reload operations. Even if a unit supports such an operation the client might not necessary have the right privileges to execute them. + +**CanIsolate** encodes as boolean whether the unit may be started in isolation mode. + +**Job** encodes the job ID and job object path of the job currently scheduled or executed for this unit, if there is any. If no job is scheduled or executed the job id field will be 0. + +**StopWhenUnneeded**, **RefuseManualStart**, **RefuseManualStop**, **AllowIsolate**, **DefaultDependencies**, **OnFailureIsolate**, **IgnoreOnIsolate**, **IgnoreOnSnapshot** map directly to the corresponding configuration booleans in the unit file. + +**DefaultControlGroup** contains the main control group of this unit as a string. This refers to a group in systemd's own _name=systemd_ hierarchy, which systemd uses to watch and manipulate the unit and all its processes. + +**ControlGroup** contains an array of the control groups this unit is making use of. This includes the default control group in the _name=systemd_ hierarchy, but also includes groups in additional hierarchies. + +**ControlGroupAttributes** contains an array of string triples for each control group to set for this unit. Each triplet consists of hierarchy name, field and value. + +**NeedDaemonReload** is a boolean that indicates whether the configuration file this unit is loaded from (i.e. **FragmentPath** or **SourcePath**) has changed since the configuration was read and hence whether a configuration reload is recommended. + +**JobTimeoutUSec** maps directly to the corresponding configuration setting in the unit file. + +**ConditionTimestamp** and **ConditionTimestampMonotonic** contain the CLOCK_REALTIME/CLOCK_MONOTONIC usec timestamps of the last time the configured conditions of the unit have been checked, or 0 if they have never been checked. Conditions are checked when a unit is requested to start. + +**ConditionResult** contain the condition result of the last time the configured conditions of this unit were checked. + +**LoadError** contains a pair of strings. If the unit failed to load (as encoded in **LoadState**, see above), then this will include a D-Bus error pair consisting of the error ID and an explanatory human readable string of what happened. If it succeeded to load this will be a pair of empty strings. + + +## Service Unit Objects + +All service unit objects implement the `org.freedesktop.systemd1.Service` interface (described here) in addition to the generic `org.freedesktop.systemd1.Unit` interface (see above). + + +[[!format txt """ +$ gdbus introspect --system --dest org.freedesktop.systemd1 --object-path /org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservicenode /org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice { + interface org.freedesktop.systemd1.Unit { + }; + interface org.freedesktop.systemd1.Service { + methods: + signals: + properties: + readonly s Type = 'dbus'; + readonly s Restart = 'no'; + readonly s PIDFile = ''; + readonly s NotifyAccess = 'main'; + readonly t RestartUSec = 100000; + readonly t TimeoutUSec = 90000000; + readonly t WatchdogUSec = 0; + readonly t WatchdogTimestamp = 0; + readonly t WatchdogTimestampMonotonic = 0; + readonly t StartLimitInterval = 10000000; + readonly u StartLimitBurst = 5; + readwrite s StartLimitAction = 'none'; + readonly a(sasbttuii) ExecStartPre = []; + readonly a(sasbttuii) ExecStart = [('/usr/sbin/avahi-daemon', ['/usr/sbin/avahi-daemon', '-s'], false, 1342738862998611, 6799112, 0, 0, 338, 0, 0)]; + readonly a(sasbttuii) ExecStartPost = []; + readonly a(sasbttuii) ExecReload = [('/usr/sbin/avahi-daemon', ['/usr/sbin/avahi-daemon', '-r'], false, 0, 0, 0, 0, 0, 0, 0)]; + readonly a(sasbttuii) ExecStop = []; + readonly a(sasbttuii) ExecStopPost = []; + readonly as Environment = []; + readonly u UMask = 18; + readonly t LimitCPU = 18446744073709551615; + readonly t LimitFSIZE = 18446744073709551615; + readonly t LimitDATA = 18446744073709551615; + readonly t LimitSTACK = 18446744073709551615; + readonly t LimitCORE = 18446744073709551615; + readonly t LimitRSS = 18446744073709551615; + readonly t LimitNOFILE = 4096; + readonly t LimitAS = 18446744073709551615; + readonly t LimitNPROC = 29974; + readonly t LimitMEMLOCK = 65536; + readonly t LimitLOCKS = 18446744073709551615; + readonly t LimitSIGPENDING = 29974; + readonly t LimitMSGQUEUE = 819200; + readonly t LimitNICE = 0; + readonly t LimitRTPRIO = 0; + readonly t LimitRTTIME = 18446744073709551615; + readonly s WorkingDirectory = ''; + readonly s RootDirectory = ''; + readonly i OOMScoreAdjust = 0; + readonly i Nice = 0; + readonly i IOScheduling = 0; + readonly i CPUSchedulingPolicy = 0; + readonly i CPUSchedulingPriority = 0; + readonly ay CPUAffinity = []; + readonly t TimerSlackNS; + readonly b CPUSchedulingResetOnFork = false; + readonly b NonBlocking = false; + readonly s StandardInput = 'null'; + readonly s StandardOutput = 'journal'; + readonly s StandardError = 'inherit'; + readonly s TTYPath = ''; + readonly b TTYReset = false; + readonly b TTYVHangup = false; + readonly b TTYVTDisallocate = false; + readonly i SyslogPriority = 30; + readonly s SyslogIdentifier = ''; + readonly b SyslogLevelPrefix = true; + readonly s Capabilities = ''; + readonly i SecureBits = 0; + readonly t CapabilityBoundingSet = 18446744073709551615; + readonly s User = ''; + readonly s Group = ''; + readonly as SupplementaryGroups = []; + readonly s TCPWrapName = ''; + readonly s PAMName = ''; + readonly as ReadWriteDirectories = []; + readonly as ReadOnlyDirectories = []; + readonly as InaccessibleDirectories = []; + readonly t MountFlags = 1048576; + readonly b PrivateTmp = false; + readonly b SameProcessGroup = false; + readonly s KillMode = 'control-group'; + readonly i KillSignal = 15; + readonly s UtmpIdentifier = ''; + readonly b ControlGroupModify = false; + readonly b ControlGroupPersistent = false; + readonly b PrivateNetwork = false; + readonly b IgnoreSIGPIPE = true; + readonly b NoNewPrivileges = false; + readonly au SystemCallFilter = []; + readonly s KillMode = 'control-group'; + readonly i KillSignal = 15; + readonly b SendSIGKILL = true; + readonly b PermissionsStartOnly = false; + readonly b RootDirectoryStartOnly = false; + readonly b RemainAfterExit = false; + readonly t ExecMainStartTimestamp = 1342738862998734; + readonly t ExecMainStartTimestampMonotonic = 6799234; + readonly t ExecMainExitTimestamp = 1342738862998734; + readonly t ExecMainExitTimestampMonotonic = 6799234; + readonly u ExecMainPID = 338; + readonly i ExecMainCode = 0; + readonly i ExecMainStatus = 0; + readonly u MainPID = 338; + readonly u ControlPID = 0; + readonly s BusName = 'org.freedesktop.Avahi'; + readonly s StatusText = 'Server startup complete. Host name is epsilon.local. Local service cookie is 3963893972.'; + readonly s Result = 'success'; + }; + interface org.freedesktop.DBus.Properties { + }; + interface org.freedesktop.DBus.Peer { + }; + interface org.freedesktop.DBus.Introspectable { + }; +}; +"""]] + +### Properties + +Most properties of the Service interface map directly to the corresponding settings in service unit files. For the sake of brevity, here's a list of all exceptions only: + +**WatchdogTimestamp** and **WatchdogTimestampMonotonic** contain CLOCK_REALTIME/CLOCK_MONOTONIC usec timestamps of the last watchdog ping received from the service, or 0 if none was ever received. + +**ExecStartPre**, **ExecStart**, **ExecStartPost**, **ExecReload**, **ExecStop**, **ExecStop** each are arrays of structures each containing: the binary path to execute; an array with all arguments to pass to the executed command, starting with argument 0; a boolean whether it should be considered a failure if the process exits uncleanly; two pairs of CLOCK_REALTIME/CLOCK_MONOTONIC usec timestamps when the process began and finished running the last time, or 0 if it never ran or never finished running; the PID of the process, or 0 if it has not run yet; the exit code and status of the last run. This field hence maps more or less to the corresponding setting in the service unit file but is augmented with runtime data. + +**LimitCPU** (and related properties) map more or less directly to the corresponding settings in the service unit files, however are set to 18446744073709551615 (i.e. -1) if they aren't set. + +**Capabilities** contains the configured capabilities, as formatted with cap_to_text(). + +**SecureBits**, **CapabilityBoundingSet**, **MountFlags** also correspond to the configured settings of the unit files, but are encoded as the actual binary flag fields they are, rather than formatted as string. + +**ExecMainStartTimestamp**, **ExecMainStartTimestampMonotonic**, **ExecMainExitTimestamp**, **ExecMainExitTimestampMonotonic**, **ExecMainPID**, **ExecMainCode**, **ExecMainStatus** contain information about the main process of the service as far as it is known. This is often the same runtime information that is stored in **ExecStart**. However, it deviates for Type=forking services where the main process of the service is not forked off systemd directly. These fields either contain information of the last run of the process or of the current running process. + +**MainPID** and **ControlPID** contain the main and control PID of the service. The main PID is the current main PID of the service and is 0 when the service currently has no main PID. The control PID is the PID of the current start/stop/reload process running and is 0 if no such process is currently running. That means that **ExecMainPID** and **MainPID** differ in the way that the latter immediately reflects whether a main process is currently running while the latter possible contains information collected from the last run even if the process is no longer around. + +**StatusText** contains the status text passed to the service manager via a call to sd_notify(). This may be used by services to inform the service manager about its internal state with a nice explanatory string. + +**Result** encodes the execution result of the last run of the service. It is useful to determine the reason a service failed if it is in _failed_ state (see **ActiveState** above). The following values are currently known: _success_ is set if the unit didn't fail. _resources_ indicates that not enough resources have been available to fork off and execute the service processes. _timeout_ indicates that a time-out occurred while executing a service operation. _exit-code_ indicates that a service process exited with an unclean exit code. _signal_ indicates that a service process exited with an uncaught signal. _core-dump_ indicates that a service process exited uncleanly and dumped core. _watchdog_ indicates that a service did not send out watchdog ping messages often enough. _start-limit_ indicates that a service has been started too frequently in a time frame (as configured in **StartLimitInterval**, **StartLimitBurst**). + + +## Socket Unit Objects + +All socket unit objects implement the `org.freedesktop.systemd1.Socket` interface (described here) in addition to the generic `org.freedesktop.systemd1.Unit` interface (see above). + + +[[!format txt """ +$ gdbus introspect --system --dest org.freedesktop.systemd1 --object-path /org/freedesktop/systemd1/unit/avahi_2ddaemon_2esocket +node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2esocket { + interface org.freedesktop.systemd1.Unit { + }; + interface org.freedesktop.systemd1.Socket { + methods: + signals: + properties: + readonly b BindIPv6Only = 'default'; + readonly u Backlog = 128; + readonly t TimeoutUSec = 90000000; + readonly a(sasbttuii) ExecStartPre = []; + readonly a(sasbttuii) ExecStartPost = []; + readonly a(sasbttuii) ExecStopPre = []; + readonly a(sasbttuii) ExecStopPost = []; + readonly as Environment = []; + readonly u UMask = 18; + readonly t LimitCPU = 18446744073709551615; + readonly t LimitFSIZE = 18446744073709551615; + readonly t LimitDATA = 18446744073709551615; + readonly t LimitSTACK = 18446744073709551615; + readonly t LimitCORE = 18446744073709551615; + readonly t LimitRSS = 18446744073709551615; + readonly t LimitNOFILE = 4096; + readonly t LimitAS = 18446744073709551615; + readonly t LimitNPROC = 61434; + readonly t LimitMEMLOCK = 65536; + readonly t LimitLOCKS = 18446744073709551615; + readonly t LimitSIGPENDING = 61434; + readonly t LimitMSGQUEUE = 819200; + readonly t LimitNICE = 0; + readonly t LimitRTPRIO = 0; + readonly t LimitRTTIME = 18446744073709551615; + readonly s WorkingDirectory = ''; + readonly s RootDirectory = ''; + readonly i OOMScoreAdjust = 0; + readonly i Nice = 0; + readonly i IOScheduling = 0; + readonly i CPUSchedulingPolicy = 0; + readonly i CPUSchedulingPriority = 0; + readonly ay CPUAffinity = []; + readonly t TimerSlackNS; + readonly b CPUSchedulingResetOnFork = false; + readonly b NonBlocking = false; + readonly s StandardInput = 'null'; + readonly s StandardOutput = 'journal'; + readonly s StandardError = 'inherit'; + readonly s TTYPath = ''; + readonly b TTYReset = false; + readonly b TTYVHangup = false; + readonly b TTYVTDisallocate = false; + readonly i SyslogPriority = 30; + readonly s SyslogIdentifier = ''; + readonly b SyslogLevelPrefix = true; + readonly s Capabilities = ''; + readonly i SecureBits = 0; + readonly t CapabilityBoundingSet = 18446744073709551615; + readonly s User = ''; + readonly s Group = ''; + readonly as SupplementaryGroups = []; + readonly s TCPWrapName = ''; + readonly s PAMName = ''; + readonly as ReadWriteDirectories = []; + readonly as ReadOnlyDirectories = []; + readonly as InaccessibleDirectories = []; + readonly t MountFlags = 0; + readonly b PrivateTmp = false; + readonly b SameProcessGroup = false; + readonly s KillMode = 'control-group'; + readonly i KillSignal = 15; + readonly s UtmpIdentifier = ''; + readonly b ControlGroupModify = false; + readonly b ControlGroupPersistent = false; + readonly b PrivateNetwork = false; + readonly b IgnoreSIGPIPE = true; + readonly b NoNewPrivileges = false; + readonly au SystemCallFilter = []; + readonly s KillMode = 'control-group'; + readonly i KillSignal = 15; + readonly b SendSIGKILL = true; + readonly u ControlPID = 0; + readonly s BindToDevice = ''; + readonly u DirectoryMode = 493; + readonly u SocketMode = 438; + readonly b Accept = false; + readonly b KeepAlive = false; + readonly i Priority = -1; + readonly t ReceiveBuffer = 0; + readonly t SendBuffer = 0; + readonly i IPTOS = -1; + readonly i IPTTL = -1; + readonly t PipeSize = 0; + readonly b FreeBind = false; + readonly b Transparent = false; + readonly b Broadcast = false; + readonly b PassCredentials = false; + readonly b PassSecurity = false; + readonly i Mark = -1; + readonly u MaxConnections = 64; + readonly u NAccepted = 0; + readonly u NConnections = 0; + readonly x MessageQueueMaxMessages = 0; + readonly x MessageQueueMessageSize = 0; + readonly s Result = 'success'; + readonly s SmackLabel = ''; + readonly s SmackLabelIPIn = ''; + readonly s SmackLabelIPOut = ''; + }; + interface org.freedesktop.DBus.Properties { + }; + interface org.freedesktop.DBus.Peer { + }; + interface org.freedesktop.DBus.Introspectable { + }; +}; +"""]] + +### Properties + +Most of the properties map directly to the corresponding settings in socket unit files. As socket units can include **ExecStartPre** (and similar) fields which contain information about processes to execute. They also share most of the fields related to the execution context that Service objects expose (see above). In addition to these properties there are the following: + +**NAccepted** contains the accumulated number of connections ever accepted on this socket. This only applies to sockets with **Accept** set to _true_, i.e. those where systemd is responsible for accepted connections. + +Similar **NConnections** contains the number of currently open connections on this socket, and also applies only to socket with **Accept** set to _true_. + +**Result** encodes the reason why a socket unit failed if it is in _failed_ state (see **ActiveState** above). The values _success_, _resources_, _timeout_, _exit-code_, _signal_ and _core-dump_ have the same meaning as they have for the corresponding field of service units (see above). In addition to that the value **service-failed-permanent** indicates that the service of this socket failed continuously. + + +## Target Unit Objects + +All target unit objects implement the `org.freedesktop.systemd1.Target` interface (described here) in addition to the generic `org.freedesktop.systemd1.Unit` interface (see above). + + +[[!format txt """ +$ gdbus introspect --system --dest org.freedesktop.systemd1 --object-path /org/freedesktop/systemd1/unit/basic_2etarget +node /org/freedesktop/systemd1/unit/basic_2etarget { + interface org.freedesktop.systemd1.Unit { + }; + interface org.freedesktop.systemd1.Target { + methods: + signals: + properties: + }; + interface org.freedesktop.DBus.Properties { + }; + interface org.freedesktop.DBus.Peer { + }; + interface org.freedesktop.DBus.Introspectable { + }; +}; +"""]] +Target units have neither type-specific methods nor properties. + + +## Device Unit Objects + +All device unit objects implement the `org.freedesktop.systemd1.Device` interface (described here) in addition to the generic `org.freedesktop.systemd1.Unit` interface (see above). + + +[[!format txt """ +$ gdbus introspect --system --dest org.freedesktop.systemd1 --object-path /org/freedesktop/systemd1/unit/dev_2ddisk_2dby_5cx2did_2data_5cx2dSAMSUNG_5fHD501LJ_5fS0MUJ1KQ161445_2edevice +node /org/freedesktop/systemd1/unit/dev_2ddisk_2dby_5cx2did_2data_5cx2dSAMSUNG_5fHD501LJ_5fS0MUJ1KQ161445_2edevice { + interface org.freedesktop.systemd1.Unit { + }; + interface org.freedesktop.systemd1.Device { + methods: + signals: + properties: + readonly s SysFSPath = '/sys/devices/pci0000:00/0000:00:1f.2/ata2/host1/target1:0:0/1:0:0:0/block/sdb'; + }; + interface org.freedesktop.DBus.Properties { + }; + interface org.freedesktop.DBus.Peer { + }; + interface org.freedesktop.DBus.Introspectable { + }; +}; +"""]] + +### Properties + +Device units only expose a single type-specific property: + +**SysFSPath** contains the sysfs path of the kernel device this object corresponds to. + + +## Mount Unit Objects + +All mount unit objects implement the `org.freedesktop.systemd1.Mount` interface (described here) in addition to the generic `org.freedesktop.systemd1.Unit` interface (see above). + + +[[!format txt """ +$ gdbus introspect --system --dest org.freedesktop.systemd1 --object-path /org/freedesktop/systemd1/unit/home_2emount +node /org/freedesktop/systemd1/unit/home_2emount { + interface org.freedesktop.systemd1.Unit { + }; + interface org.freedesktop.systemd1.Mount { + methods: + signals: + properties: + readonly s Where = '/home'; + readonly s What = '/dev/mapper/home'; + readonly s Options = 'rw,relatime,rw,seclabel,data=ordered'; + readonly s Type = 'ext4'; + readonly t TimeoutUSec = 90000000; + readonly a(sasbttuii) ExecMount = [('/bin/mount', ['/bin/mount', '/dev/disk/by-uuid/59a54df8-d070-4907-a4a7-2e0ce05d5c2a', '/home', '-t', 'ext4'], false, 1357656124168977, 11158027, 1357656124274805, 11263855, 608, 1, 0)]; + readonly a(sasbttuii) ExecUnmount = []; + readonly a(sasbttuii) ExecRemount = []; + readonly as Environment = []; + readonly u UMask = 18; + readonly t LimitCPU = 18446744073709551615; + readonly t LimitFSIZE = 18446744073709551615; + readonly t LimitDATA = 18446744073709551615; + readonly t LimitSTACK = 18446744073709551615; + readonly t LimitCORE = 18446744073709551615; + readonly t LimitRSS = 18446744073709551615; + readonly t LimitNOFILE = 4096; + readonly t LimitAS = 18446744073709551615; + readonly t LimitNPROC = 61434; + readonly t LimitMEMLOCK = 65536; + readonly t LimitLOCKS = 18446744073709551615; + readonly t LimitSIGPENDING = 61434; + readonly t LimitMSGQUEUE = 819200; + readonly t LimitNICE = 0; + readonly t LimitRTPRIO = 0; + readonly t LimitRTTIME = 18446744073709551615; + readonly s WorkingDirectory = ''; + readonly s RootDirectory = ''; + readonly i OOMScoreAdjust = 0; + readonly i Nice = 0; + readonly i IOScheduling = 0; + readonly i CPUSchedulingPolicy = 0; + readonly i CPUSchedulingPriority = 0; + readonly ay CPUAffinity = []; + readonly t TimerSlackNS; + readonly b CPUSchedulingResetOnFork = false; + readonly b NonBlocking = false; + readonly s StandardInput = 'null'; + readonly s StandardOutput = 'journal'; + readonly s StandardError = 'inherit'; + readonly s TTYPath = ''; + readonly b TTYReset = false; + readonly b TTYVHangup = false; + readonly b TTYVTDisallocate = false; + readonly i SyslogPriority = 30; + readonly s SyslogIdentifier = ''; + readonly b SyslogLevelPrefix = true; + readonly s Capabilities = ''; + readonly i SecureBits = 0; + readonly t CapabilityBoundingSet = 18446744073709551615; + readonly s User = ''; + readonly s Group = ''; + readonly as SupplementaryGroups = []; + readonly s TCPWrapName = ''; + readonly s PAMName = ''; + readonly as ReadWriteDirectories = []; + readonly as ReadOnlyDirectories = []; + readonly as InaccessibleDirectories = []; + readonly t MountFlags = 0; + readonly b PrivateTmp = false; + readonly b SameProcessGroup = true; + readonly s KillMode = 'control-group'; + readonly i KillSignal = 15; + readonly s UtmpIdentifier = ''; + readonly b ControlGroupModify = false; + readonly b ControlGroupPersistent = false; + readonly b PrivateNetwork = false; + readonly b IgnoreSIGPIPE = true; + readonly b NoNewPrivileges = false; + readonly au SystemCallFilter = []; + readonly s KillMode = 'control-group'; + readonly i KillSignal = 15; + readonly b SendSIGKILL = true; + readonly u ControlPID = 0; + readonly u DirectoryMode = 493; + readonly s Result = 'success'; + }; + interface org.freedesktop.DBus.Properties { + }; + interface org.freedesktop.DBus.Peer { + }; + interface org.freedesktop.DBus.Introspectable { + }; +}; +"""]] + +### Properties + +Most of the properties map directly to the corresponding settings in mount unit files. As mount units invoke the `/usr/bin/mount` command their bus objects include implicit **ExecMount** (and similar) fields which contain information about processes to execute. They also share most of the fields related to the execution context that Service objects expose (see above). In addition to these properties there are the following: + +**ControlPID** contains the PID of the currently running `/usr/bin/mount` or `/usr/bin/umount` command if there is one running, otherwise 0. + +**Result** contains a value explaining why a mount unit failed if it failed. It can take the values _success_, _resources_, _timeout_, _exit-code_, _signal_, _core-dump_ which have the identical meaning as the corresponding values of the corresponding field of service unit objects (see above). + + +## Automount Unit Objects + +All automount unit objects implement the `org.freedesktop.systemd1.Automount` interface (described here) in addition to the generic `org.freedesktop.systemd1.Unit` interface (see above). + + +[[!format txt """ +$ gdbus introspect --system --dest org.freedesktop.systemd1 --object-path /org/freedesktop/systemd1/unit/proc_2dsys_2dfs_2dbinfmt_5fmisc_2eautomount +node /org/freedesktop/systemd1/unit/proc_2dsys_2dfs_2dbinfmt_5fmisc_2eautomount { + interface org.freedesktop.systemd1.Unit { + }; + interface org.freedesktop.systemd1.Automount { + methods: + signals: + properties: + readonly s Where = '/proc/sys/fs/binfmt_misc'; + readonly u DirectoryMode = 493; + readonly s Result = 'success'; + }; + interface org.freedesktop.DBus.Properties { + }; + interface org.freedesktop.DBus.Peer { + }; + interface org.freedesktop.DBus.Introspectable { + }; +}; +"""]] + +### Properties + +Most of the properties map directly to the corresponding settings in the automount unit files. + +**Result** knows the values _success_ and _resources_, at this time. They have the same meanings as the corresponding values of the corresponding field of the Service object. + + +## Snapshot Unit Objects + +All snapshot unit objects implement the `org.freedesktop.systemd1.Snapshot` interface (described here) in addition to the generic `org.freedesktop.systemd1.Unit` interface (see above). + + +[[!format txt """ +$ gdbus introspect --system --dest org.freedesktop.systemd1 --object-path /org/freedesktop/systemd1/unit/foo_2esnapshot +node /org/freedesktop/systemd1/unit/foo_2esnapshot { + interface org.freedesktop.systemd1.Unit { + }; + interface org.freedesktop.systemd1.Snapshot { + methods: + Remove(); + signals: + properties: + readonly b Cleanup = false; + }; + interface org.freedesktop.DBus.Properties { + }; + interface org.freedesktop.DBus.Peer { + }; + interface org.freedesktop.DBus.Introspectable { + }; +}; +"""]] + +### Methods + +**Remove()** deletes the snapshot unit. This operation is also available in the **[[RemoveSnapshot|RemoveSnapshot]]()** operation of the Manager object (see above), which is sometimes nicer to call, in order to reduce roundtrips. + + +### Properties + +**Cleanup** is a boolean that indicates that the snapshot unit should be removed automatically after the first time it is activated. + + +## Timer Unit Objects + +All timer unit objects implement the `org.freedesktop.systemd1.Timer` interface (described here) in addition to the generic `org.freedesktop.systemd1.Unit` interface (see above). + + +[[!format txt """ +$ gdbus introspect --system --dest org.freedesktop.systemd1 --object-path /org/freedesktop/systemd1/unit/systemd_2dtmpfiles_2dclean_2etimer +node /org/freedesktop/systemd1/unit/systemd_2dtmpfiles_2dclean_2etimer { + interface org.freedesktop.systemd1.Unit { + }; + interface org.freedesktop.systemd1.Timer { + readonly s Unit = 'systemd-tmpfiles-clean.service'; + readonly a(stt) TimersMonotonic = [('OnUnitActiveUSec', 86400000000, 173700033104), ('OnBootUSec', 900000000, 900000000)]; + readonly a(sst) TimersCalendar = []; + readonly t NextElapseUSecRealtime = 0; + readonly t NextElapseUSecMonotonic = 173700033104; + readonly s Result = 'success'; + }; + interface org.freedesktop.DBus.Properties { + }; + interface org.freedesktop.DBus.Peer { + }; + interface org.freedesktop.DBus.Introspectable { + }; +}; +"""]] + +### Properties + +**Unit** contains the name of the unit to activate when the timer elapses. + +**TimersMonotonic** contains an array of structs that contain information about all monotonic timers of this timer unit. The structs contain a string identifying the timer base, which is one of _OnActiveUSec_, _OnBootUSec_, _OnStartupUSec_, _OnUnitActiveUSec_, _OnUnitInactiveUSec_, which correspond to the settings of the same names in the timer unit files; the usec offset from this timer base in monotonic time; the next elapsation point on the CLOCK_MONOTONIC clock, relative its epoch. + +**TimersCalendar** contains an array of structs that contain information about all realtime/calendar timers of this timer unit. The structs contain a string identifying the timer base, which may only be _OnCalendar_ for now; the calendar specification string; the next elapsation point on the CLOCK_REALTIME clock, relative to its epoch. + +**NextElapseUSecRealtime** contains the next elapsation point on the CLOCK_REALTIME clock in usec since the epoch, or 0 if this timer event does not include at least one calendar event. + +Similar, **NextElapseUSecMonotonic** contains the next elapsation point on the CLOCK_MONOTONIC clock in usec since the epoch, or 0 if this timer event does not include at least one monotonic event. + +**Result** knows the values _success_ and _resources_ with the same meanings as the matching values of the corresponding property of the service interface. + + +## Swap Unit Objects + +All swap unit objects implement the `org.freedesktop.systemd1.Swap` interface (described here) in addition to the generic `org.freedesktop.systemd1.Unit` interface (see above). + + +[[!format txt """ +$ gdbus introspect --system --dest org.freedesktop.systemd1 --object-path /org/freedesktop/systemd1/unit/dev_2dsda3_2eswap +node /org/freedesktop/systemd1/unit/dev_2dsda3_2eswap { + interface org.freedesktop.systemd1.Unit { + }; + interface org.freedesktop.systemd1.Swap { + methods: + signals: + properties: + readonly s What = '/dev/sda3'; + readonly i Priority = -1; + readonly t TimeoutUSec; + readonly a(sasbttuii) ExecActivate = []; + readonly a(sasbttuii) ExecDeactivate = []; + readonly as Environment = []; + readonly u UMask = 18; + readonly t LimitCPU = 18446744073709551615; + readonly t LimitFSIZE = 18446744073709551615; + readonly t LimitDATA = 18446744073709551615; + readonly t LimitSTACK = 18446744073709551615; + readonly t LimitCORE = 18446744073709551615; + readonly t LimitRSS = 18446744073709551615; + readonly t LimitNOFILE = 4096; + readonly t LimitAS = 18446744073709551615; + readonly t LimitNPROC = 61434; + readonly t LimitMEMLOCK = 65536; + readonly t LimitLOCKS = 18446744073709551615; + readonly t LimitSIGPENDING = 61434; + readonly t LimitMSGQUEUE = 819200; + readonly t LimitNICE = 0; + readonly t LimitRTPRIO = 0; + readonly t LimitRTTIME = 18446744073709551615; + readonly s WorkingDirectory = ''; + readonly s RootDirectory = ''; + readonly i OOMScoreAdjust = 0; + readonly i Nice = 0; + readonly i IOScheduling = 0; + readonly i CPUSchedulingPolicy = 0; + readonly i CPUSchedulingPriority = 0; + readonly ay CPUAffinity = []; + readonly t TimerSlackNS; + readonly b CPUSchedulingResetOnFork = false; + readonly b NonBlocking = false; + readonly s StandardInput = 'null'; + readonly s StandardOutput = 'journal'; + readonly s StandardError = 'inherit'; + readonly s TTYPath = ''; + readonly b TTYReset = false; + readonly b TTYVHangup = false; + readonly b TTYVTDisallocate = false; + readonly i SyslogPriority = 30; + readonly s SyslogIdentifier = ''; + readonly b SyslogLevelPrefix = true; + readonly s Capabilities = ''; + readonly i SecureBits = 0; + readonly t CapabilityBoundingSet = 18446744073709551615; + readonly s User = ''; + readonly s Group = ''; + readonly as SupplementaryGroups = []; + readonly s TCPWrapName = ''; + readonly s PAMName = ''; + readonly as ReadWriteDirectories = []; + readonly as ReadOnlyDirectories = []; + readonly as InaccessibleDirectories = []; + readonly t MountFlags = 0; + readonly b PrivateTmp = false; + readonly b SameProcessGroup = false; + readonly s KillMode = 'control-group'; + readonly i KillSignal = 15; + readonly s UtmpIdentifier = ''; + readonly b ControlGroupModify = false; + readonly b ControlGroupPersistent = false; + readonly b PrivateNetwork = false; + readonly b IgnoreSIGPIPE = true; + readonly b NoNewPrivileges = false; + readonly au SystemCallFilter = []; + readonly s KillMode = 'control-group'; + readonly i KillSignal = 15; + readonly b SendSIGKILL = true; + readonly u ControlPID = 0; + readonly s Result = 'success'; + }; + interface org.freedesktop.DBus.Properties { + }; + interface org.freedesktop.DBus.Peer { + }; + interface org.freedesktop.DBus.Introspectable { + }; +"""]] + +### Properties + +Most of the properties map directly to the corresponding settings in swap unit files. As mount units invoke the `/usr/bin/swapon` command their bus objects include implicit **ExecActivate** (and similar) fields which contain information about processes to execute. They also share most of the fields related to the execution context that Service objects expose (see above). In addition to these properties there are the following: + +**ControlPID** contains the PID of the currently running `/usr/bin/swapon` or `/usr/bin/swapoff` command if there is one running, otherwise 0. + +**Result** contains a value explaining why a mount unit failed if it failed. It can take the values _success_, _resources_, _timeout_, _exit-code_, _signal_, _core-dump_ which have the identical meanings as the corresponding values of the corresponding field of service unit objects (see above). + + +## Path Unit Objects + +All path unit objects implement the `org.freedesktop.systemd1.Path` interface (described here) in addition to the generic `org.freedesktop.systemd1.Unit` interface (see above). + + +[[!format txt """ +$ gdbus introspect --system --dest org.freedesktop.systemd1 --object-path /org/freedesktop/systemd1/unit/cups_2epath +node /org/freedesktop/systemd1/unit/cups_2epath { + interface org.freedesktop.systemd1.Unit { + }; + interface org.freedesktop.systemd1.Path { + methods: + signals: + properties: + readonly s Unit = 'cups.service'; + readonly a(ss) Paths = [('PathExistsGlob', '/var/spool/cups/d*')]; + readonly b MakeDirectory = false; + readonly u DirectoryMode = 493; + readonly s Result = 'success'; + }; + interface org.freedesktop.DBus.Properties { + }; + interface org.freedesktop.DBus.Peer { + }; + interface org.freedesktop.DBus.Introspectable { + }; +}; +"""]] + +### Properties + +Most properties correspond directly with the matching settings in path unit files. The others: + +**Paths** contains an array of structs. Each struct contains the condition to watch, which can be one of _PathExists_, _PathExistsGlob_, _PathChanged_, _PathModified_, _DirectoryNotEmpty_ which correspond directly to the matching settings in the path unit files; and the path to watch, possibly including glob expressions. + +**Result** contains a result value which can be _success_ or _resources_, which have the same meaning as the corresponding field of the service interface. + + +## Job Objects + +Job objects encapsulate scheduled or running jobs. Each unit can have none or one jobs in the execution queue. Each job is attached to exactly one unit. + + +[[!format txt """ +$ gdbus introspect --system --dest org.freedesktop.systemd1 --object-path /org/freedesktop/systemd1/job/1292 +node /org/freedesktop/systemd1/job/1292 { + interface org.freedesktop.systemd1.Job { + methods: + Cancel(); + signals: + properties: + readonly u Id = 1292; + readonly (so) Unit = ('slow.service', '/org/freedesktop/systemd1/unit/slow_2eservice'); + readonly s JobType = 'start'; + readonly s State = 'running'; + }; + interface org.freedesktop.DBus.Properties { + }; + interface org.freedesktop.DBus.Peer { + }; + interface org.freedesktop.DBus.Introspectable { + }; +}; +"""]] + +### Methods + +**Cancel()** cancels the job. Note that this will remove a job from the queue if it is not yet executed but generally will not cause a job that is already in the process of being executed to be aborted. This operation may also be requested via the **[[CancelJob|CancelJob]]()** method of the Manager object (see above), which is sometimes useful to reduce roundtrips. + + +### Properties + +**Id** is the numeric Id of the job. During the runtime of a systemd instance each numeric ID is only assigned once. + +**Unit** refers to the unit this job belongs two. It is a structure consisting of the name of the unit and a bus path to the unit's object. + +**JobType** refers to the job's type and is one of _start_, _verify-active_, _stop_, _reload_, _restart_, _try-restart_, _reload-or-start_. Note that later versions might define additional values. + +**State** refers to the job's state and is one of _waiting_ and _running_. The former indicates that a job is currently queued but has not begun to execute yet, the latter indicates that a job is currently being executed. + + + +--- + + + +These D-Bus interfaces follow [[the usual interface versioning guidelines|http://0pointer.de/blog/projects/versioning-dbus.html]]. diff --git a/Software/systemd/export.mdwn b/Software/systemd/export.mdwn new file mode 100644 index 00000000..ea9960b1 --- /dev/null +++ b/Software/systemd/export.mdwn @@ -0,0 +1,75 @@ + +[[Back to systemd|http://www.freedesktop.org/wiki/Software/systemd/]] + + +# Journal Export Format + +* _Note that this document describes the binary serialization format of journals only, as used for transfer across the network. For interfacing with web technologies there's the [[Journal JSON Format|http://www.freedesktop.org/wiki/Software/systemd/json]]. The binary format on disk is documented as [[Journal File Format|http://www.freedesktop.org/wiki/Software/systemd/journal-files]]._ +Before reading on, please make sure you are aware of the [[basic properties of journal entries|http://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html]], in particular realize that they may include binary non-text data (though usually don't), and the same field might have multiple values assigned within the same entry (though usually hasn't). + +When exporting journal data for other uses or transferring it via the network/local IPC the _journal export format_ is used. It's a simple serialization of journal entries, that is easy to read without any special tools, but still binary safe where necessary. The format is like this: + +* Two journal entries that follow each other are separated by a double newline. +* Journal fields consisting only of characters >= 32 (space) and < 127 (i.e. printable, non-control ASCII) are serialized as they are (i.e. field name, followed by '=', followed by field data), followed by a newline as separator to the next field. Note that fields containing tabs or newlines cannot be formatted like this. +* Other journal fields are serialized in a special binary safe way: field name, followed by newline, followed by a binary 64bit little endian size value, followed by the binary field data, followed by a newline as separator to the next field. +* Entry metadata that is not actually a field is serialized like it was a field, but beginning with two underscores. More specifically, `__CURSOR=`, `__REALTIME_TIMESTAMP=`, `__MONOTONIC_TIMESTAMP=` are introduced this way. Note that these meta-fields are only generated when actual journal files are serialized. They are omitted for entries that do not originate from a journal file (for example because they are transferred for the first time to be stored in one). Or in other words: if you are generating this format you shouldn't care about these special double-underscore fields. But you might find them usable when you deserialize the format generated by us. Additional fields prefixed with two underscores might be added later on, your parser should skip over the fields it does not know. +* The order in which fields appear in an entry is undefined and might be different for each entry that is serialized. +And that's already it. + +This format can be generated via "journalctl -o export". + +Here's an example for two serialized entries which consist only of text data: + + +[[!format txt """ +__CURSOR=s=739ad463348b4ceca5a9e69c95a3c93f;i=4ece7;b=6c7c6013a26343b29e964691ff25d04c;m=4fc72436e;t=4c508a72423d9;x=d3e5610681098c10;p=system.journal +__REALTIME_TIMESTAMP=1342540861416409 +__MONOTONIC_TIMESTAMP=21415215982 +_BOOT_ID=6c7c6013a26343b29e964691ff25d04c +_TRANSPORT=syslog +PRIORITY=4 +SYSLOG_FACILITY=3 +SYSLOG_IDENTIFIER=gdm-password] +SYSLOG_PID=587 +MESSAGE=AccountsService-DEBUG(+): ActUserManager: ignoring unspecified session '8' since it's not graphical: Success +_PID=587 +_UID=0 +_GID=500 +_COMM=gdm-session-wor +_EXE=/usr/libexec/gdm-session-worker +_CMDLINE=gdm-session-worker [pam/gdm-password] +_AUDIT_SESSION=2 +_AUDIT_LOGINUID=500 +_SYSTEMD_CGROUP=/user/lennart/2 +_SYSTEMD_SESSION=2 +_SELINUX_CONTEXT=system_u:system_r:xdm_t:s0-s0:c0.c1023 +_SOURCE_REALTIME_TIMESTAMP=1342540861413961 +_MACHINE_ID=a91663387a90b89f185d4e860000001a +_HOSTNAME=epsilon + +__CURSOR=s=739ad463348b4ceca5a9e69c95a3c93f;i=4ece8;b=6c7c6013a26343b29e964691ff25d04c;m=4fc72572f;t=4c508a7243799;x=68597058a89b7246;p=system.journal +__REALTIME_TIMESTAMP=1342540861421465 +__MONOTONIC_TIMESTAMP=21415221039 +_BOOT_ID=6c7c6013a26343b29e964691ff25d04c +_TRANSPORT=syslog +PRIORITY=6 +SYSLOG_FACILITY=9 +SYSLOG_IDENTIFIER=/USR/SBIN/CROND +SYSLOG_PID=8278 +MESSAGE=(root) CMD (run-parts /etc/cron.hourly) +_PID=8278 +_UID=0 +_GID=0 +_COMM=run-parts +_EXE=/usr/bin/bash +_CMDLINE=/bin/bash /bin/run-parts /etc/cron.hourly +_AUDIT_SESSION=8 +_AUDIT_LOGINUID=0 +_SYSTEMD_CGROUP=/user/root/8 +_SYSTEMD_SESSION=8 +_SELINUX_CONTEXT=system_u:system_r:crond_t:s0-s0:c0.c1023 +_SOURCE_REALTIME_TIMESTAMP=1342540861416351 +_MACHINE_ID=a91663387a90b89f185d4e860000001a +_HOSTNAME=epsilon +"""]] +Yupp, no example with binary data here: the wiki can't show this nicely. Sorry. diff --git a/Software/systemd/hackfests.mdwn b/Software/systemd/hackfests.mdwn new file mode 100644 index 00000000..c79e2143 --- /dev/null +++ b/Software/systemd/hackfests.mdwn @@ -0,0 +1,15 @@ + +[[Back to systemd|http://www.freedesktop.org/wiki/Software/systemd/]] + + +# Organizing Your Own systemd Hackfest + +Face-to-face hackfests and sprints are invaluable for a Free Software project. If you are interested in organizing a hackfest for systemd, here are a few suggestions: + +* Organize them colocated with another event, such as a big Free Software conference. Often the organizers of that bigger conference might even give you room for free, and it's definitely more likely that more people will attend your hackfest since companies are more likely to sponsor travel. +* Ask on system-devel if people are interested to attend, and what time they'd prefer +* Set up an event page on Google+, and make sure to ping Kay or Lennart so that they can share it on systemd's own Google+ page. +* Ask Lennart to announce the event on his blog. +* Edit the main systemd Wiki page and add it to the list of Hackfests planned. +* Kay, Michal and Lennart all are located in central Europe. Organizing a hackfest in this area will increase the likeliness for them to be able to attend. +The people behind systemd are frequently attending the Linux Plumbers Conference, the Red Hat Developer Conference, the various LinuxCons and GUADEC. They all make good places to colocate a hackfest at. diff --git a/Software/systemd/hostnamed.mdwn b/Software/systemd/hostnamed.mdwn new file mode 100644 index 00000000..67e9a1c7 --- /dev/null +++ b/Software/systemd/hostnamed.mdwn @@ -0,0 +1,114 @@ + +[[Back to systemd|http://www.freedesktop.org/wiki/Software/systemd/]] + + +# hostnamed + +systemd 25 and newer include systemd-hostnamed. This is a tiny daemon that can be used to control the host name and related machine meta data from user programs. It currently offers access to five variables: + +* The current host name (Example: dhcp-192-168-47-11) +* The static (configured) host name (Example: lennarts-computer) +* The pretty host name (Example: Lennart's Computer) +* A suitable icon name for the local host (Example: computer-laptop) +* A chassis type (Example: "tablet") +See [[systemd-hostnamed.service(8)|http://www.freedesktop.org/software/systemd/man/systemd-hostnamed.service.html]] for more information. + +The daemon is accessible via D-Bus: + + +[[!format txt """ +$ gdbus introspect --system --dest org.freedesktop.hostname1 --object-path /org/freedesktop/hostname1 +node /org/freedesktop/hostname1 { + interface org.freedesktop.hostname1 { + methods: + SetHostname(in s name, + in b user_interaction); + SetStaticHostname(in s name, + in b user_interaction); + SetPrettyHostname(in s name, + in b user_interaction); + SetIconName(in s name, + in b user_interaction); + SetChassis(in s name, + in b user_interaction); + signals: + properties: + readonly s Hostname = 'dhcp-192-168-47-11'; + readonly s StaticHostname = 'lennarts-computer'; + readonly s PrettyHostname = 'Lennart's Computer'; + readonly s IconName = 'computer-laptop'; + readonly s Chassis = 'laptop'; + }; + interface org.freedesktop.DBus.Properties { + }; + interface org.freedesktop.DBus.Introspectable { + }; + interface org.freedesktop.DBus.Peer { + }; +}; +"""]] +Whenever the hostname or other meta data is changed via the daemon PropertyChanged signals are sent out to which clients can subscribe. Changing a hostname using this interface is authenticated via PolicyKit. + +A couple of notes on the semantics: + +The **static (configured) host name** is the one configured in /etc/hostname or a similar file. It is chosen by the local user. It is not always in sync with the current host name as returned by the gethostname() system call. If no host name is configured this property will be the empty string. Setting this property to the empty string will remove /etc/hostname. This hostname should be an internet-style hostname, 7bit ASCII, no special chars/spaces, lower case. + +The **transient (dynamic) host name** is the one configured via the kernel's sethostbyname(). It can be different from the static hostname in case DHCP or mDNS have been configured to change the name based on network information. This property is never empty. If no host name is set this will default to "localhost". Setting this property to the empty string will reset the dynamic hostname to the static host name. If no static host name is configured the dynamic host name will be reset to "localhost". This hostname should be an internet-style hostname, 7bit ASCII, no special chars/spaces, lower case. + +The **pretty host name** is a free-form UTF8 host name for presentation to the user. UIs should ensure that the pretty hostname and the static hostname stay in sync. I.e. when the former is "Lennart's Computer" the latter should be "lennarts-computer". If no pretty host name is set this setting will be the empty string. Applications should then find a suitable fallback, such as the dynamic hostname. + +The **icon name** is a name following the XDG icon naming spec. If not set information such as the chassis type (see below) are used to find a suitable fallback icon name (i.e. "computer-laptop" vs. "computer-desktop" is picked based on the chassis information). If no such data is available returns the empty string. In that case an application should fall back to a replacement icon, for example "computer". If this property is set to the empty string this automatic fallback name selection is enabled again. + +The **chassis type** should be one of the following that are currently defined: "desktop", "laptop", "server", "tablet", "handset", as well as the special chassis types "vm" and "container" for virtualized systems that lack an immediate physical chassis. Note that in most cases the chassis type will be determined automatically from DMI/SMBIOS/ACPI firmware information. Writing to this setting is hence useful only to override misdetected chassis types, or configure a chassis type if none could be auto-detected. Set this property to the empty string to reenable the automatic detection of the chassis type from firmware information. + +A client which wants to change the local host name for DHCP/mDNS should invoke SetHostname("newname", false) as soon as the name is available and afterwards reset it via SetHostname(""). + +Note that hostnamed starts only on request and terminates after a short idle period. This effectively means that [[PropertyChanged|PropertyChanged]] messages are not sent out for changes made directly on the files (as in: administrator edits the files with vi). This is actually intended behavior: manual configuration changes should require manual reloading of them. + +The transient (dynamic) hostname directly maps to the kernel hostname. This hostname should be assumed to be highly dynamic, and hence should be watched directly, without involving [[PropertyChanged|PropertyChanged]] messages from hostnamed. For that, open /proc/sys/kernel/hostname and poll() for SIGHUP which is triggered by the kernel every time the hostname changes. Again: this is special for the transient (dynamic) hostname, and does not apply to the configured (fixed) hostname. + +Applications may bypass the daemon to read the hostname data if notifications of host name changes are not necessary. Use gethostname(), /etc/hostname (possibly with per-distribution fallbacks), and /etc/machine-data for that. For more information on these files and syscalls see the respective man pages. + +The user_interaction boolean parameters can be used to control whether PolicyKit should interactively ask the user for authentication credentials if it needs to. + +The PolicyKit action for SetHostname() is _org.freedesktop.hostname1.set-hostname_. For SetStaticHostname() and SetPrettyHostname() it is _org.freedesktop.hostname1.set-static-hostname_. For SetIconName() and SetChassis() it is _org.freedesktop.hostname1.set-machine-info_. + +This is inspired by, but not the same as David Zeuthen's xdg-hostname: [[http://people.freedesktop.org/~david/xdg-hostname/|http://people.freedesktop.org/~david/xdg-hostname/]] + +Also see David's original Fedora feature page about this: [[http://fedoraproject.org/wiki/Features/BetterHostname|http://fedoraproject.org/wiki/Features/BetterHostname]] + +The sources for hostnamed are available in git for review: [[http://cgit.freedesktop.org/systemd/systemd/tree/src/hostname/hostnamed.c|http://cgit.freedesktop.org/systemd/systemd/tree/src/hostname/hostnamed.c]] + +Here are three examples how the pretty hostname and the icon name should be used: + +* When registering DNS-SD services: use the pretty host name in the service name, and pass the icon name in the TXT data, if there is an icon name. Browsing clients can then show the server icon on each service. Especially useful for WebDAV stuff. Similar for UPnP media sharing. +* Set the bluetooth name to the pretty host name. +* When your file browser has a "Computer" icon, replace the name with the pretty hostname if set, and the icon with the icon name, if it is set. +To properly handle name lookups with changing local hostnames without having to edit /etc/hosts for them we recommend using hostnamed in combination with nss-myhostname: [[http://0pointer.de/lennart/projects/nss-myhostname/|http://0pointer.de/lennart/projects/nss-myhostname/]] + +Here are some recommendations to follow when generating a static (internet) hostname from a pretty name: + +* Generate a single DNS label only, not an FQDN. That means no dots allowed. Strip them, or replace them by "-". +* It's probably safer not to use any non-ASCII chars, even if DNS allows this in some way these days. In fact, restrict your charset to a-zA-Z0-9, -. Strip other chars, or try to replace them in some smart way with chars from this set, for example "ä" → "ae" and suchlike, and use "-" as replacement for all kinds of punctuation chars or spaces. +* Try to avoid creating repeated "-", as well as "-" as the first or last char. +* Limit the hostname to 63 chars, which is the length of a DNS label +* If after stripping special chars the empty string is the result, you can pass this as-is to hostnamed in which case it will automatically make "localhost" out of this. +* It probably is a good idea to replace uppercase by lowercase chars +Note that while hostnamed applies some checks to the hostname you pass they are much looser than the recommendations above. For example, hostnamed will also accept "_" in the hostname, but I'd recommend not using this to avoid clashes with DNS-SD service types. Also hostnamed allows you longer hostnames, but because of the DNS label limitations I'd recommend not making use of this. + +Here are a couple of example conversions: + +* "Lennart's PC" → lennarts-pc +* "Müllers Computer" → muellers-computer +* "Voran!" → voran +* "Es war einmal ein Männlein" → "es-war-einmal-ein-maennlein" +* "Jawoll. Ist doch wahr!" → "jawoll-ist-doch-wahr" +* "レナート" → "localhost" +* "...zack!!! zack!..." → "zack-zack" +Oh, and of course, an already valid internet hostname label you enter and pass through this conversion should stay unmodified, so that users have direct control of it, if they want -- by simply ignoring the fact that the pretty hostname is pretty and just edit it as if it was the normal internet name. + + + +--- + + This D-Bus interface follows [[the usual interface versioning guidelines|http://0pointer.de/blog/projects/versioning-dbus.html]]. diff --git a/Software/systemd/inhibit.mdwn b/Software/systemd/inhibit.mdwn new file mode 100644 index 00000000..da64bee9 --- /dev/null +++ b/Software/systemd/inhibit.mdwn @@ -0,0 +1,148 @@ + +[[Back to systemd|http://www.freedesktop.org/wiki/Software/systemd/]] + + +# Inhibitor Locks + +systemd 183 and newer include a logic to inhibit system shutdowns and sleep states. This is implemented as part of [[systemd-logind.daemon(8)|http://www.freedesktop.org/software/systemd/man/systemd-logind.service.html]] There are a couple of different use cases for this: + +* A CD burning application wants to ensure that the system is not turned off or suspended while the burn process is in progress. +* A package manager wants to ensure that the system is not turned off while a package upgrade is in progress. +* An office suite wants to be notified before system suspend in order to save all data to disk, and delay the suspend logic until all data is written. +* A web browser wants to be notified before system hibernation in order to free its cache to minimize the amount of memory that needs to be virtualized. +* A screen lock tool wants to bring up the screen lock right before suspend, and delay the suspend until that's complete. +Applications which want to make use of the inhibition logic shall take an inhibitor lock via the [[logind D-Bus API|http://www.freedesktop.org/wiki/Software/systemd/logind]]. + +Seven distinct inhibitor lock types may be taken, or a combination of them: + +1. _sleep_ inhibits system suspend and hibernation requested by (unprivileged) **users** +1. _shutdown_ inhibits high-level system power-off and reboot requested by (unprivileged) **users** +1. _idle_ inhibits that the system goes into idle mode, possibly resulting in **automatic** system suspend or shutdown depending on configuration. +1. _handle-power-key_ inhibits the low-level (i.e. logind-internal) handling of the system power **hardware** key, allowing (possibly unprivileged) external code to handle the event instead. +1. Similar, _handle-suspend-key_ inhibits the low-level handling of the system **hardware** suspend key. +1. Similar, _handle-hibernate-key_ inhibits the low-level handling of the system **hardware** hibernate key. +1. Similar, _handle-lid-switch_ inhibits the low-level handling of the systemd **hardware** lid switch. +Two different modes of locks are supported: + +1. _block_ inhibits operations entirely until the lock is released. If such a lock is taken the operation will fail (but still may be overridden if the user possesses the necessary privileges). +1. _delay_ inhibits operations only temporarily, either until the lock is released or up to a certain amount of time. The InhibitDelayMaxSec= setting in [[logind.conf(5)|http://www.freedesktop.org/software/systemd/man/logind.conf.html]] controls the timeout for this. This is intended to be used by applications which need a synchronous way to execute actions before system suspend but shall not be allowed to block suspend indefinitely. This mode is only available for _sleep_ and _shutdown_ locks. +Inhibitor locks are taken via the Inhibit() D-Bus call on the logind Manager object: + + +[[!format txt """ +$ gdbus introspect --system --dest org.freedesktop.login1 --object-path /org/freedesktop/login1 +node /org/freedesktop/login1 { + interface org.freedesktop.login1.Manager { + methods: + Inhibit(in s what, + in s who, + in s why, + in s mode, + out h fd); + ListInhibitors(out a(ssssuu) inhibitors); + ... + signals: + PrepareForShutdown(b active); + PrepareForSleep(b active); + ... + properties: + readonly s BlockInhibited = ''; + readonly s DelayInhibited = ''; + readonly t InhibitDelayMaxUSec = 5000000; + readonly b PreparingForShutdown = false; + readonly b PreparingForSleep = false; + ... + }; + ... +}; +"""]] +**Inhibit()** is the only API necessary to take a lock. It takes four arguments: + +* _What_ is a colon-separated list of lock types, i.e. `shutdown`, `sleep`, `idle`, `handle-power-key`, `handle-suspend-key`, `handle-hibernate-key`, `handle-lid-switch`. Example: "shutdown:idle" +* _Who_ is a human-readable, descriptive string of who is taking the lock. Example: "Package Updater" +* _Why_ is a human-readable, descriptive string of why the lock is taken. Example: "Package Update in Progress" +* _Mode_ is one of `block` or `delay`, see above. Example: "block" +Inhibit() returns a single value, a file descriptor that encapsulates the lock. As soon as the file descriptor is closed (and all its duplicates) the lock is automatically released. If the client dies while the lock is taken the kernel automatically closes the file descriptor so that the lock is automatically released. A delay lock taken this way should be released ASAP on reception of PrepareForShutdown(true) (see below), but of course only after execution of the actions the application wanted to delay the operation for in the first place. + +**ListInhibitors()** lists all currently active inhibitor locks. It returns an array of structs, each consisting of What, Who, Why, Mode as above, plus the PID and UID of the process that requested the lock. + +The **PrepareForShutdown()** and **PrepareForSleep()** signals are emitted when a system suspend or shutdown has been requested and is about to be executed, as well as after the the suspend/shutdown was completed (or failed). The signals carry a boolean argument. If _True_ the shutdown/sleep has been requested, and the preparation phase for it begins, if _False_ the operation has finished completion (or failed). If _True_, this should be used as indication for applications to quickly execute the operations they wanted to execute before suspend/shutdown and then release any delay lock taken. If _False_ the suspend/shutdown operation is over, either successfully or unsuccessfully (of course, this signal will never be sent if a shutdown request was successful). The signal with _False_ is generally delivered only after the system comes back from suspend, the signal with _True_ possibly as well, for example when no delay lock was taken in the first place, and the system suspend hence executed without any delay. The signal with _False_ is usually the signal on which applications request a new delay lock in order to be synchronously notified about the next suspend/shutdown cycle. Note that watching PrepareForShutdown(true)[[/PrepareForSleep|Software/systemd/inhibit/PrepareForSleep]](true) without taking a delay lock is racy and should not be done, as any code that an application might want to execute on this signal might not actually finish before the suspend/shutdown cycle is executed. _Again_: if you watch PrepareForSuspend(true), then you really should have taken a delay lock first. PrepareForShutdown(false) may be subscribed to by applications which want to be notified about system resume events. Note that this will only be sent out for suspend/resume cycles done via logind, i.e. generally only for high-level user-induced suspend cycles, and not automatic, low-level kernel induced ones which might exist on certain devices with more aggressive power management. + +The **BlockInhibited** and **DelayInhibited** properties encode what types of locks are currently taken. These fields are a colon separated list of `shutdown`, `sleep`, `idle`, `handle-power-key`, `handle-suspend-key`, `handle-hibernate-key`, `handle-lid-switch`. The list is basically the union of the What fields of all currently active locks of the specific mode. + +**InhibitDelayMaxUSec** contains the delay timeout value as configured in [[logind.conf(5)|http://www.freedesktop.org/software/systemd/man/logind.conf.html]]. + +The **PreparingForShutdown** and **PreparingForSleep** boolean properties are true between the two PrepareForShutdown() resp PrepareForSleep() signals that are sent out. Note that these properties do not trigger PropertyChanged signals. + + +## Taking Blocking Locks + +Here's the basic scheme for applications which need blocking locks such as a package manager or CD burning application: + +1. Take the lock +1. Do your work you don't want to see interrupted by system sleep or shutdown +1. Release the lock +Example pseudo code: +[[!format txt """ +fd = Inhibit("shutdown:idle", "Package Manager", "Upgrade in progress...", "block"); +/* ... + do your work + ... */ +close(fd); +"""]] + +## Taking Delay Locks + +Here's the basic scheme for applications which need delay locks such as a web browser or office suite: + +1. As you open a document, take the delay lock +1. As soon as you see PrepareForSleep(true), save your data, then release the lock +1. As soon as you see PrepareForSleep(false), take the delay lock again, continue as before. +Example pseudo code: +[[!format txt """ +int fd = -1; + +takeLock() { + if (fd >= 0) + return; + + fd = Inhibit("sleep", "Word Processor", "Save any unsaved data in time...", "delay"); +} + +onDocumentOpen(void) { + takeLock(); +} + +onPrepareForSleep(bool b) { + if (b) { + saveData(); + if (fd >= 0) { + close(fd); + fd = -1; + } + } else + takeLock(); + +} +"""]] + +## Taking Key Handling Locks + +By default logind will handle the power and sleep keys of the machine, as well as the lid switch in all states. This ensures that this basic system behavior is guaranteed to work in all circumstances, on text consoles as well as on all graphical environments. However, some DE might want to do their own handling of these keys, for example in order to show a pretty dialog box before executing the relevant operation, or to simply disable the action under certain conditions. For these cases the handle-power-key, handle-suspend-key, handle-hibernate-key and handle-lid-switch type inhibitor locks are available. When taken, these locks simply disable the low-level handling of the keys, they have no effect on system suspend/hibernate/poweroff executed with other mechanisms than the hardware keys (such as the user typing "systemctl suspend" in a shell). A DE intending to do its own handling of these keys should simply take the locks at login time, and release them on logout; alternatively it might make sense to take this lock only temporarily under certain circumstances (e.g. take the lid switch lock only when a second monitor is plugged in, in order to support the common setup where people close their laptops when they have the big screen connected). + +These locks need to be taken in the "block" mode, "delay" is not supported for them. + +If a DE wants to ensure the lock screen for the eventual resume is on the screen before the system enters suspend state, it should do this via a suspend delay inhibitor block (see above). + + +## Miscellanea + +Taking inhibitor locks is a privileged operation. Depending on the action _org.freedesktop.login1.inhibit-block-shutdown_, _org.freedesktop.login1.inhibit-delay-shutdown_, _org.freedesktop.login1.inhibit-block-sleep_, _org.freedesktop.login1.inhibit-delay-sleep_, _org.freedesktop.login1.inhibit-block-idle_, _org.freedesktop.login1.inhibit-handle-power-key_, _org.freedesktop.login1.inhibit-handle-suspend-key_, _org.freedesktop.login1.inhibit-handle-hibernate-key_,_org.freedesktop.login1.inhibit-handle-lid-switch_. In general it should be assumed that delay locks are easier to obtain than blocking locks, simply because their impact is much more minimal. Note that the policy checks for Inhibit() are never interactive. + +Inhibitor locks should not be misused. For example taking idle blocking locks without a very good reason might cause mobile devices to never auto-suspend. This can be quite detrimental for the battery. + +If an application finds a lock denied it should not consider this much of an error and just continue its operation without the protecting lock. + +The tool [[systemd-inhibit(1)|http://www.freedesktop.org/software/systemd/man/systemd-inhibit.html]] may be used to take locks or list active locks from the command line. + +Note that gnome-session also provides an [[inhibitor API|http://people.gnome.org/~mccann/gnome-session/docs/gnome-session.html#org.gnome.SessionManager.Inhibit]], which is very similar to the one of systemd. Internally, locks taken on gnome-session's interface will be forwarded to logind, hence both APIs are supported. While both offer similar functionality they do differ in some regards. For obvious reasons gnome-session can offer logout locks and screensaver avoidance locks which logind lacks. logind's API OTOH supports delay locks in addition to block locks like GNOME. Also, logind is available to system components, and centralizes locks from all users, not just those of a specific one. In general: if in doubt it is probably advisable to stick to the GNOME locks, unless there is a good reason to use the logind APIs directly. When locks are to be enumerated it is better to use the logind APIs however, since they also include locks taken by system services and other users. diff --git a/Software/systemd/json.mdwn b/Software/systemd/json.mdwn new file mode 100644 index 00000000..f37ff201 --- /dev/null +++ b/Software/systemd/json.mdwn @@ -0,0 +1,39 @@ + +[[Back to systemd|http://www.freedesktop.org/wiki/Software/systemd/]] + + +# Journal JSON Format + +* _Note that this document describes the JSON serialization format of the journal only, as used for interfacing with web technologies. For binary transfer of journal data across the network there's the [[Journal Export Format|http://www.freedesktop.org/wiki/Software/systemd/export]] instead. The binary format on disk is documented as [[Journal File Format|http://www.freedesktop.org/wiki/Software/systemd/journal-files]]._ +Before reading on, please make sure you are aware of the [[basic properties of journal entries|http://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html]], in particular realize that they may include binary non-text data (though usually don't), and the same field might have multiple values assigned within the same entry (though usually hasn't). + +In most cases the Journal JSON serialization is the obvious mapping of the entry field names (as JSON strings) to the entry field values (also as JSON strings) encapsulated in one JSON object. However, there are a few special cases to handle: + +* A field that contains non-printable or non-UTF8 is serialized as a number array instead. This is necessary to handle binary data in a safe way without losing data, since JSON cannot embed binary data natively. Each byte of the binary field will be mapped to its numeric value in the range 0..255. +* The JSON serializer can optionally skip huge (as in larger than a specific threshold) data fields from the JSON object. If that is enabled and a data field is too large, the field name is still included in the JSON object but assigned _null_. +* Within the same entry, Journal fields may have multiple values assigned. This is not allowed in JSON. The serializer will hence create a single JSON field only for these cases, and assign it an array of values (which the can be strings, _null_ or number arrays, see above). +* If the JSON data originates from a journal file it may include the special addressing fields `__CURSOR`, `__REALTIME_TIMESTAMP`, `__MONOTONIC_TIMESTAMP`, which contain the cursor string of this entry as string, and the realtime/monotonic timestamps of this entry as formatted numeric string of usec since the respective epoch. +Here's an example, illustrating all cases mentioned above. Consider this entry: + + +[[!format txt """ +MESSAGE=Hello World +_UDEV_DEVNODE=/dev/waldo +_UDEV_DEVLINK=/dev/alias1 +_UDEV_DEVLINK=/dev/alias2 +BINARY=this is a binary value \a +LARGE=this is a super large value (let's pretend at least, for the sake of this example) +"""]] +This translates into the following JSON Object: + + +[[!format txt """ +{ + "MESSAGE" : "Hello World", + "_UDEV_DEVNODE" : "/dev/waldo", + "_UDEV_DEVLINK" : [ "/dev/alias1", "/dev/alias2" ], + "BINARY" : [ 116, 104, 105, 115, 32, 105, 115, 32, 97, 32, 98, 105, 110, 97, 114, 121, 32, 118, 97, 108, 117, 101, 32, 7 ], + "LARGE" : null +} +"""]] + diff --git a/Software/systemd/localed.mdwn b/Software/systemd/localed.mdwn new file mode 100644 index 00000000..68ea5d2c --- /dev/null +++ b/Software/systemd/localed.mdwn @@ -0,0 +1,73 @@ + +[[Back to systemd|http://www.freedesktop.org/wiki/Software/systemd/]] + + +# localed + +systemd 30 and newer include systemd-localed. This is a tiny daemon that can be used to control the system locale and keyboard mapping from user programs. + +See [[systemd-localed.service(8)|http://www.freedesktop.org/software/systemd/man/systemd-localed.service.html]] for more information. + +The daemon is accessible via D-Bus: +[[!format txt """ +$ gdbus introspect --system --dest org.freedesktop.locale1 --object-path /org/freedesktop/locale1 +node /org/freedesktop/locale1 { + interface org.freedesktop.locale1 { + methods: + SetLocale(in as locale, + in b user_interaction); + SetVConsoleKeyboard(in s keymap, + in s keymap_toggle, + in b convert, + in b user_interaction); + SetX11Keyboard(in s layout, + in s model, + in s variant, + in s options, + in b convert, + in b user_interaction); + signals: + properties: + readonly as Locale = ['LANG=en_US.UTF-8']; + readonly s VConsoleKeymap = 'de'; + readonly s VConsoleKeymapToggle = ''; + readonly s X11Layout = 'de'; + readonly s X11Model = ''; + readonly s X11Variant = ''; + readonly s X11Options = ''; + }; + interface org.freedesktop.DBus.Properties { + }; + interface org.freedesktop.DBus.Introspectable { + }; + interface org.freedesktop.DBus.Peer { + }; +}; +"""]] +Whenever the system locale or keymap is changed via the daemon PropertyChanged signals are sent out to which clients can subscribe. + +Changing the system locale or keymap using this interface is authenticated via PolicyKit. The PolicyKit action for SetLocale() is _org.freedesktop.locale1.set-locale_. The PolicyKit action for SetX11Keyboard() and !SetVConsoleKeyboard() is _org.freedesktop.locale1.set-keyboard_. + +The user_interaction boolean parameters can be used to control whether PolicyKit should interactively ask the user for authentication credentials if it needs to. + +The system locale consists of an array of environment-variable-assignment-like strings. The following strings are known: LANG=, LC_CTYPE=, LC_NUMERIC=, LC_TIME=, LC_COLLATE=, LC_MONETARY=, LC_MESSAGES=, LC_PAPER=, LC_NAME=, LC_ADDRESS=, LC_TELEPHONE=, LC_MEASUREMENT=, LC_IDENTIFICATION=. + +If you set a new system locale all old system locale settings will be dropped, and the new settings will be saved to disk. It will also be passed to the system manager, and subsequently started daemons will inherit the new system locale from it. Note that already running daemons will not learn about the new system locale. + +The **SetVConsoleKeyboard()** call may be used to set the key mapping on the virtual console. Similarly, **SetX11Keyboard()** may be used to set the default key mapping of the X11 servers. + +Note that SetVConsoleKeyboard() instantly applies the new keymapping to the console, while SetX11Keyboard() simply sets a default that may be used by later sessions. + +The boolean argument _convert_ may be set to optionally convert the console keyboard configuration to X11 keyboard mappings, resp. vice versa. If true and SetVConsoleKeyboard() is used the nearest X11 keyboard setting for the chosen console setting is set. If true and SetX11Keyboard() is used the nearest console keyboard setting for the chosen X11 setting is set. Usually it is hence sufficient to call one of the two functions. + +For graphical UIs that need to set the system keyboard mapping simply invoke SetX11Keyboard(), set convert=true and ignore SetVConsoleKeyboard(). + +Use the empty string for the keymap parameters you wish not to set. + +The sources for localed are available in git for review: [[http://cgit.freedesktop.org/systemd/systemd/tree/src/locale/localed.c|http://cgit.freedesktop.org/systemd/systemd/tree/src/locale/localed.c]] + + + +--- + + This D-Bus interface follows [[the usual interface versioning guidelines|http://0pointer.de/blog/projects/versioning-dbus.html]]. diff --git a/Software/systemd/logind.mdwn b/Software/systemd/logind.mdwn new file mode 100644 index 00000000..9920aea5 --- /dev/null +++ b/Software/systemd/logind.mdwn @@ -0,0 +1,431 @@ + +[[Back to systemd|http://www.freedesktop.org/wiki/Software/systemd/]] + + +# logind + +systemd 30 and newer include systemd-logind. This is a tiny daemon that manages user logins and seats in various ways. + +See [[systemd-logind(8).service|http://www.freedesktop.org/software/systemd/man/systemd-logind.service.html]] for more information. Please consult [[Multi-Seat on Linux|http://www.freedesktop.org/wiki/Software/systemd/multiseat]] for more information on the basic concepts. + +The daemon provides both a C library interface as well as a D-Bus interface. The library interface may be used to introspect and watch the state of user logins or seat. The bus interface provides the same but in addition may also be used to make changes to system state. For more information please consult the man pages: [[sd-login(7)|http://www.freedesktop.org/software/systemd/man/sd-login.html]] + +If you are interested in writing a display manager that makes use of logind, please have look at [[Writing Display Managers|http://www.freedesktop.org/wiki/Software/systemd/writing-display-managers]]. If you are interested in writing a desktop environment that makes use of logind, please have look at [[Writing Desktop Environments|http://www.freedesktop.org/wiki/Software/systemd/writing-desktop-environments]]. + +The inhibition logic is documented in [[Inhibitor Locks|http://www.freedesktop.org/wiki/Software/systemd/inhibit]]. + + +## The Manager Object + +The service exposes the following interfaces on the Manager object on the bus: + + +[[!format txt """ +$ gdbus introspect --system --dest org.freedesktop.login1 --object-path /org/freedesktop/login1 +node /org/freedesktop/login1 { + interface org.freedesktop.login1.Manager { + methods: + GetSession(in s id, + out o session); + GetSessionByPID(in u pid, + out o session); + GetUser(in u uid, + out o user); + GetSeat(in s id, + out o seat); + ListSessions(out a(susso) sessions); + ListUsers(out a(uso) users); + ListSeats(out a(so) seats); + CreateSession(...); + ReleaseSession(...); + ActivateSession(in s id); + ActivateSessionOnSeat(in s id, + in s seat); + LockSession(in s id); + UnlockSession(in s id); + LockSessions(); + UnlockSessions(); + KillSession(in s id, + in s who, + in s signal); + KillUser(in u uid, + in s signal); + TerminateSession(in s id); + TerminateUser(in u uid); + TerminateSeat(in s id); + SetUserLinger(in u uid, + in b b, + in b interactive); + AttachDevice(in s seat, + in s sysfs, + in b interactive); + FlushDevices(in b interactive); + PowerOff(in b interactive); + Reboot(in b interactive); + Suspend(in b interactive); + Hibernate(in b interactive); + HybridSleep(in b interactive); + CanPowerOff(out s result); + CanReboot(out s result); + CanSuspend(out s result); + CanHibernate(out s result); + CanHybridSleep(out s result); + Inhibit(in s what, + in s who, + in s why, + in s mode, + out h fd); + ListInhibitors(out a(ssssuu) inhibitors); + signals: + SessionNew(s id, + o path); + SessionRemoved(s id, + o path); + UserNew(u uid, + o path); + UserRemoved(u uid, + o path); + SeatNew(s id, + o path); + SeatRemoved(s id, + o path); + PrepareForShutdown(b active); + PrepareForSleep(b active); + properties: + readonly s ControlGroupHierarchy = '/user'; + readonly as Controllers = []; + readonly as ResetControllers = ['cpu']; + readonly u NAutoVTs = 6; + readonly as KillOnlyUsers = []; + readonly as KillExcludeUsers = ['root']; + readonly b KillUserProcesses = false; + readonly b IdleHint = false; + readonly t IdleSinceHint = 1340873864854884; + readonly t IdleSinceHintMonotonic = 14409495315; + readonly s BlockInhibited = ''; + readonly s DelayInhibited = ''; + readonly t InhibitDelayMaxUSec = 5000000; + readonly s HandlePowerKey = 'poweroff'; + readonly s HandleSuspendKey = 'suspend'; + readonly s HandleHibernateKey = 'hibernate'; + readonly s HandleLidSwitch = 'suspend'; + readonly b PreparingForShutdown = false; + readonly b PreparingForSleep = false; + }; + interface org.freedesktop.DBus.Properties { + }; + interface org.freedesktop.DBus.Peer { + }; + interface org.freedesktop.DBus.Introspectable { + }; +}; +"""]] + +### Security + +A number of operations are protected via the PolicyKit privilege system. SetUserLinger() requires the _org.freedesktop.login1.set-user-linger_ privilege. AttachDevice() requires _org.freedesktop.login1.attach-device_ and FlushDevices() _org.freedesktop.login1.flush-devices_. PowerOff(), Reboot(), Suspend(), Hibernate(), HybridSleep() require _org.freedesktop.login1.power-off_, _org.freedesktop.login1.power-off-multiple-sessions_, _org.freedesktop.login1.power-off-ignore-inhibit_, _org.freedesktop.login1.reboot_, _org.freedesktop.login1.reboot-multiple-sessions_, _org.freedesktop.login1.reboot-ignore-inhibit_, _org.freedesktop.login1.suspend_, _org.freedesktop.login1.suspend-multiple-sessions_, _org.freedesktop.login1.suspend-ignore-inhibit_, _org.freedesktop.login1.hibernate_, _org.freedesktop.login1.hibernate-multiple-sessions_ resp. _org.freedesktop.login1.hibernate-ignore-inhibit_, depending whether there are other sessions around or active inhibits. Inhibit() is protected via either one of _org.freedesktop.login1.inhibit-block-shutdown_, _org.freedesktop.login1.inhibit-delay-shutdown_, _org.freedesktop.login1.inhibit-block-sleep_, _org.freedesktop.login1.inhibit-delay-sleep_, _org.freedesktop.login1.inhibit-block-idle_, _org.freedesktop.login1.inhibit-handle-power-key_, _org.freedesktop.login1.inhibit-handle-suspend-key_, _org.freedesktop.login1.inhibit-handle-hibernate-key_, _org.freedesktop.login1.inhibit-handle-lid-switch_ depending on the lock type and mode taken. + +The user_interaction boolean parameters can be used to control whether PolicyKit should interactively ask the user for authentication credentials if it needs to. + + +### Methods + +**GetSession()** may be used to get the session object path for the session with the specified ID. Similar, **GetUser()** and **GetSeat()** get the user resp. seat objects. **GetSessionByPID()** gets the session object of the session the specified PID belongs to if there is any. + +**ListSessions()** returns an array with all current sessions. The structures in the array consist of the following fields: session id, user id, user name, seat id, session object path. If a session does not have a seat attached the seat id field will be an empty string. + +**ListUsers()** returns an array with all currently logged in users. The structures in the array consist of the following fields: user id, user name, user object path. + +**ListSeats()** returns an array with all currently available seats. The structure in the array consists of the following fields: seat id, seat object path. + +**CreateSession()** and **ReleaseSession()** may be used to open or close login sessions. These calls should _never_ be invoked directly by clients. Creating/closing sessions is exclusively the job of PAM and its pam_systemd module. + +**ActivateSession()** brings the session with the specified ID into the foreground. **ActivateSessionOnSeat()** does the same, but only if the seat id matches. + +**LockSession()** asks the session with the specified ID to activate the screen lock. **UnlockSession()** asks the session with the specified ID to remove an active screen lock, if there is any. This is implemented by sending out the Lock() and Unlock() signals from the respective session object which session managers are supposed to listen on. + +**LockSessions()** asks all sessions to activate the screen locks. This may be used to lock any access to the machine in one action. Similar, **UnlockSessions()** asks all sessions to deactivate their screen locks. + +**KillSession()** may be used to send a Unix signal to one or all processes of a session. As arguments it takes the session id, either the string "leader" or "all" and a signal number. If "leader" is passed only the session "leader" is killed. If "all" is passed all processes of the session are killed. + +**KillUser()** may be used to send a Unix signal to all processes of a user. As argument it takes the user id and a signal number. + +**TerminateSession()**, **TerminateUser()**, **TerminateSeat()** may be used to forcibly terminate one specific session, all processes of a user, resp. all sessions attached to a specific seat. The session, user, seat is identified by their respective IDs. + +**SetUserLinger()** enables or disables user lingering. If enabled the runtime directory of a user is kept around and he may continue to run processes while he is logged out. If disabled the runtime directory goes away as soon as he logs out. Expects three arguments: the UID, a boolean whether to enable/disable and a boolean controlling the PolicyKit authorization interactivity (see above). Note that the user linger state is persistently stored on disk. + +**AttachDevice()** may be used to assign a specific device to a specific seat. The device is identified by its /sys path, and must be eligible for seat assignments. Takes three arguments: the seat id, the sysfs path, and a boolean for controlling PolicyKit interactivity (see above). Device assignments are persistently stored to disk. To create a new seat, simply specify a previously unused seat id. For more information about the seat assignment logic see [[Multi-Seat for Linux|http://www.freedesktop.org/wiki/Software/systemd/multiseat]]. + +**FlushDevices()** removes all explicit seat assignments for devices, resetting all assignments to the automatic defaults. The only argument this takes is the PolicyKit interactivity boolean (see above). + +**PowerOff()**, **Reboot()**, **Suspend()**, **Hibernate()**, **HybridSleep()** results in the system being powered off, rebooted, suspend, hibernated or hibernated+suspended. The only argument is the PolicyKit interactivity boolean (see above). The main purpose of these calls is that they enforce [[PolicyKit|PolicyKit]] policy and hence allow powering off/rebooting/suspending/hibernating even by unprivileged users. They also enforce inhibition locks. UIs should expose these calls as primary mechanism to poweroff/reboot/suspend/hibernate/hybrid-sleep the machine. + +**CanPowerOff()**, **CanReboot()**, **CanSuspend()**, **CanHibernate()**, **CanHybridSleep()** tests whether the system supports the respective operation and whether the calling user is eligible for the desired operation. Returns one of "na", "yes", "no" or "challenge". If "na" is returned the operation is not available because hardware, kernel or drivers do not support it. If "yes" is returned the operation is supported and the user may execute the operation without further authentication. If "no" is returned the operation is available but the user is not allowed to execute the operation. If "challenge" is returned the operation is available, but only after authorization. + +**Inhibit()** creates an inhibition lock. It takes four parameters: What, Who, Why and Mode. "What" is one or more of "shutdown", "sleep", "idle", "handle-power-key", "handle-suspend-key", "handle-hibernate-key", "handle-lid-switch", separated by colons, for inhibiting poweroff/reboot, suspend/hibernate, the automatic idle logic, or hardware key handling. "Who" should be a short human readable string identifying the application taking the lock. "Why" should be a short human readable string identifying the reason why the lock is taken. Finally, "Mode" is either "block" or "delay" which encodes whether the inhibit shall be consider mandatory or whether it should just delay the operation to a certain maximum time. The call returns a file descriptor. The lock is released the moment this file descriptor (and all its duplicates) are closed. For more information on the inhibition logic see [[Inhibitor Locks|http://www.freedesktop.org/wiki/Software/systemd/inhibit]]. + +**ListInhibitors()** lists all currently active inhibitors. Returns an array of structures consisting of what, who, why, mode, user ID and process ID. + + +### Signals + +Whenever the inhibition state or idle hint changes daemon **PropertyChanged** signals are sent out to which clients can subscribe. + +The **SessionNew()**, **SessionRemoved()**, **UserNew()**, **UserRemoved()**, **SeatNew()**, **SeatRemoved()** signals are sent each time a session is created or removed, a user logs in or out, or a seat is added or removed. They each contain the ID of the object plus the object path. + +The **PrepareForShutdown()** resp. **PrepareForSleep()** signals are sent right before (with the argument True) and after (with the argument False) the system goes down for reboot/poweroff, resp. suspend/hibernate. This may be used by applications for saving data on disk, releasing memory or doing other jobs that shall be done shortly before shutdown/sleep, in conjunction with delay inhibitor locks. After completion of this work they should release their inhibition locks in order not to delay the operation any further. For more information see [[Inhibitor Locks|http://www.freedesktop.org/wiki/Software/systemd/inhibit]]. + + +### Properties + +Most properties simply reflect the configuration stored in logind.conf. For more information, see: [[logind.conf(5)|http://www.freedesktop.org/software/systemd/man/logind.conf.html]] + +The **IdleHint** property reflects the idle hint state of the system. If the system is idle it might get into automatic suspend or shutdown, depending on configuration. + +**IdleSinceHint** and **IdleSinceHintMonotonic** encode the timestamps of the last change of the idle hint boolean, in CLOCK_REALTIME resp. CLOCK_MONOTONIC timestamps in usec since the epoch. + +The **BlockInhibited** and **DelayInhibited** properties encode the currently active locks of the respective modes. They are colon separated lists of "shutdown", "sleep", "idle" (see above). + +The **PreparingForShutdown** and **PreparingForSleep** boolean properties are true between the two PrepareForShutdown resp. PrepareForSleep signals are sent. Note that these properties do not send out PropertyChanged signals. + + +## Seat Objects + + +[[!format txt """ +$ gdbus introspect --system --dest org.freedesktop.login1 --object-path /org/freedesktop/login1/seat/seat0 +node /org/freedesktop/login1/seat/seat0 { + interface org.freedesktop.login1.Seat { + methods: + Terminate(); + ActivateSession(in s id); + signals: + properties: + readonly s Id = 'seat0'; + readonly so ActiveSession = ('2', '/org/freedesktop/login1/session/2'); + readonly b CanMultiSession = true; + readonly b CanTTY = true; + readonly b CanGraphical = true; + readonly a(so) Sessions = [('2', '/org/freedesktop/login1/session/2')]; + readonly b IdleHint = false; + readonly t IdleSinceHint = 1340873864854884; + readonly t IdleSinceHintMonotonic = 14409495315; + }; + interface org.freedesktop.DBus.Properties { + }; + interface org.freedesktop.DBus.Peer { + }; + interface org.freedesktop.DBus.Introspectable { + }; +}; +"""]] + +### Methods + +**Terminate()** and **ActivateSession()** work similar to TerminateSeat(), ActivationSessionOnSeat() on the Manager object. + + +### Signals + +Whenever **ActiveSession**, **Sessions**, **CanGraphical**, **CanMultiSession** and **CanTTY** or the idle state changes **PropertyChanged** signals are sent out to which clients can subscribe. + + +### Properties + +The **Id** property encodes the ID of the seat. + +**ActiveSession** encodes the currently active session if there is one. It is a structure consisting of session id and object path. + +**CanMultiSession** encodes whether the session is multi-session capable, CanTTY whether it is suitable for text logins, CanGraphical whether it is suitable for graphical sessions. + +The **Sessions** array is an array of all current sessions of this seat, each encoded in a structure consisting of the ID and the object path. + +The **IdleHint**, **IdleSinceHint**, **IdleSinceHint** properties encode the idle state, similar to the one exposed on the Manager object, but specific for this seat. + + +## User Objects + + +[[!format txt """ +$ gdbus introspect --system --dest org.freedesktop.login1 --object-path /org/freedesktop/login1/user/500 +node /org/freedesktop/login1/user/500 { + interface org.freedesktop.login1.User { + methods: + Terminate(); + Kill(in s signal); + signals: + properties: + readonly u UID = 500; + readonly u GID = 500; + readonly s Name = 'lennart'; + readonly t Timestamp = 1340822974613785; + readonly t TimestampMonotonic = 22320963; + readonly s RuntimePath = '/run/user/500'; + readonly s DefaultControlGroup = 'name=systemd:/user/lennart'; + readonly (so) Display = ('2', '/org/freedesktop/login1/session/2'); + readonly s State = 'active'; + readonly a(so) Sessions = [('2', '/org/freedesktop/login1/session/2')]; + readonly b IdleHint = false; + readonly t IdleSinceHint = 1340873864854884; + readonly t IdleSinceHintMonotonic = 14409495315; + }; + interface org.freedesktop.DBus.Properties { + }; + interface org.freedesktop.DBus.Peer { + }; + interface org.freedesktop.DBus.Introspectable { + }; +}; +"""]] + +### Methods + +**Terminate()** and **Kill()** work similar to the TerminateUser() resp. KillUser() calls on the manager object. + + +### Signals + +Whenever **Sessions** or the idle state changes **PropertyChanged** signals are sent out to which clients can subscribe. + + +### Properties + +The **UID** and **GID** properties encode the Unix UID and primary GID of the user. + +The **Name** property encodes the user name. + +**Timestamp** and **TimestampMonotonic** encode the login time of the user in usec since the epoch, in the CLOCK_REALTIME resp. CLOCK_MONOTONIC clocks. + +**RuntimePath** encodes the runtime path of the user, i.e. $XDG_RUNTIME_DIR, for details see the [[XDG Basedir Specification|http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html]]. + +**DefaultControlGroup** encodes the default control group of the user within the system hierarchy. + +**Display** encodes which graphical session should be used as primary UI display for the use. It is a structure encoding session ID and object path of the session to use. + +**State** encodes the user state, one of "offline", "lingering", "online", "active", "closing". See [[sd_uid_get_state(3)|http://www.freedesktop.org/software/systemd/man/sd_uid_get_state.html]] for more information about the states. + +**Sessions** is an array of structures encoding all current sessions of the user. Each structure consists of ID and object path. + +The **IdleHint**, **IdleSinceHint**, **IdleSinceHintMonotonic** properties encode the idle hint state of the user, similar to the Manager's properties, but specific for this user. + + +## Session Objects + + +[[!format txt """ +$ gdbus introspect --system --dest org.freedesktop.login1 --object-path /org/freedesktop/login1/session/2 +node /org/freedesktop/login1/session/2 { + interface org.freedesktop.login1.Session { + methods: + Terminate(); + Activate(); + Lock(); + Unlock(); + SetIdleHint(in b b); + Kill(in s who, + in s signal); + signals: + Lock(); + Unlock(); + properties: + readonly s Id = '2'; + readonly (uo) User = (500, '/org/freedesktop/login1/user/500'); + readonly s Name = 'lennart'; + readonly t Timestamp = 1340822974628160; + readonly t TimestampMonotonic = 22335339; + readonly s DefaultControlGroup = 'name=systemd:/user/lennart/2'; + readonly u VTNr = 2; + readonly (so) Seat = ('seat0', '/org/freedesktop/login1/seat/seat0'); + readonly s TTY = ''; + readonly s Display = ':0'; + readonly b Remote = false; + readonly s RemoteHost = ''; + readonly s RemoteUser = ''; + readonly s Service = 'gdm-password'; + readonly u Leader = 905; + readonly u Audit = 2; + readonly s Type = 'x11'; + readonly s Class = 'user'; + readonly b Active = true; + readonly s State = 'active'; + readonly as Controllers = []; + readonly as ResetControllers = []; + readonly b KillProcesses = false; + readonly b IdleHint = false; + readonly t IdleSinceHint = 1340873864854884; + readonly t IdleSinceHintMonotonic = 14409495315; + }; + interface org.freedesktop.DBus.Properties { + }; + interface org.freedesktop.DBus.Peer { + }; + interface org.freedesktop.DBus.Introspectable { + }; +}; +"""]] + +### Methods + +**Terminate()**, **Activate()**, **Lock()**, **Unlock()**, **Kill()** work similar to the respective calls on the Manager object. + +**SetIdleHint()** shall be called by the session object to update the idle state of the session, whenever it changes. + + +### Signals + +Whenever **Active** or the idle state changes **PropertyChanged** signals are sent out to which clients can subscribe. + +**Lock** (resp. **Unlock**) is sent when the session is asked to be screen-locked/screen-unlocked. A session manager of the session should listen to this signal and act accordingly. This signal is sent out as a result of the **Lock()** resp. **Unlock()** methods. + + +### Properties + +**Id** encodes the session ID. + +**User** encodes the user ID of the user this session belongs to. This is a structure encoding the Unix UID and the object path. + +**Name** encodes the user name. + +**Timestamp** and **TimestampMonotonic** encode the usec timestamp since the epoch when the session was created, in CLOCK_REALTIME resp. CLOCK_MONOTONIC. + +**DefaultControlGroup** encodes the default control group of the session, in systemd's own cgroup hierarchy. + +**VTNr** encodes the virtual terminal number of the session if there is any, 0 otherwise. + +**Seat** encodes the seat this session belongs to, if there is any. This is a structure consisting of the ID and the seat object path. + +**TTY** encodes the kernel TTY path of the session if this is a text login. If not this is an empty string. + +**Display** encodes the X11 display name if this is a graphical login. If not this is an empty string. + +**Remote** encodes whether the session is local or remote. + +**RemoteHost** and **RemoteUser** encode the remote host and user if this is a remote session, or an empty string otherwise. + +**Service** encodes the PAM service name that registered the session. + +**Leader** encodes the PID of the process that registered the session. + +**Audit** encodes the Kernel Audit session ID of the session, if auditing is available. + +**Type** encodes the session type. It's one of "unspecified" (for cron PAM sessions and suchlike), "tty" (for text logins) or "x11" (for graphical logins). + +**Class** encodes the session class. It's one of "user" (for normal user sessions), "greeter" (for display manager pseudo-sessions), "lock-screen" (for display lock screens). + +**Active** is a boolean that is true if the session is active, i.e. currently in the foreground. This field is semi-redundant due to State. + +**State** encodes the session state and one of "online", "active", "closing". See [[sd_session_get_state(3)|http://www.freedesktop.org/software/systemd/man/sd_session_is_active.html]] for more information about the states. + +**Controllers** and **ResetControllers** encode the cgroup controllers this session has been explicitly added to/remove from, using pam_systemd's command line. + +**KillProcesses** encodes whether the processes of this session shall be killed if the session ends. It's also controllable on pam_systemd's command line. + +**IdleHint**, **IdleSinceHint**, **IdleSinceHintMonotonic** encapsulate the idle hint state of this session, similar to how the respective properties on the manager object do it for the whole system. + + + +--- + + + +These D-Bus interfaces follow [[the usual interface versioning guidelines|http://0pointer.de/blog/projects/versioning-dbus.html]]. diff --git a/Software/systemd/multiseat.mdwn b/Software/systemd/multiseat.mdwn new file mode 100644 index 00000000..ac66d59d --- /dev/null +++ b/Software/systemd/multiseat.mdwn @@ -0,0 +1,181 @@ + +[[Back to systemd|http://www.freedesktop.org/wiki/Software/systemd/]] + + +# Multi-Seat on Linux + +systemd, versions 30 and newer, includes support for keeping track of user sessions and seats. This adds full hotplug multi-seat support to Linux. Here's a quick overview on how it works. + +If you are interested in the actual APIs for multi-seat support, please have a look at the [[logind Bus API|http://www.freedesktop.org/wiki/Software/systemd/logind]] and [[sd-login(7)|http://www.freedesktop.org/software/systemd/man/sd-login.html]]. If you are planning to write (or port) a multi-seat aware display manager, please have a look at [[Writing Display Managers|http://www.freedesktop.org/wiki/Software/systemd/writing-display-managers]]. + + +## Definition of Terms + +* A **seat** consists of all hardware devices assigned to a specific workplace. It consists of at least one graphics device, and usually also includes keyboard, mouse. It can also include video cameras, sound cards and more. Seats are identified by seat names, which are short strings (<= 64chars), that start with the four characters "seat" followed by at least one more character from the range a-zA-Z0-9, "_" and "-". They are suitable for inclusion in file names. Seat names may or may not be stable and may be reused if a seat becomes available again. +* A **session** is defined by the time a user is logged in until he logs out. A session is bound to one or no seats (the latter for 'virtual' ssh logins). Multiple sessions can be attached to the same seat, but only one of them can be active, the others are in the background. A session is identified by a short string. systemd ensures that audit sessions are identical to systemd sessions, and uses the audit session id as session id in systemd (if auditing is enabled). The session identifier too shall be considered a short string (<= 64chars) consisting only of a-zA-Z0-9, "_" and "-", suitable for inclusion in a file name. Session IDs are unique on the local machine and are never reused as long as the machine is online. +* A **user** (the way we know it on Unix) corresponds to the person using a computer. A single user can have opened multiple sessions at the same time. A user is identified by a numeric user id (UID) or a user name (string). +* A **multi-session** system allows multiple user sessions on the same seat at the same time. Linux+systemd qualifies. +* A **multi-seat** system allows multiple independent seats that can be individually and simultaneously used by different users. Linux+systemd qualifies. +All hardware devices that are eligible to being assigned to a seat, are assigned to one. A device can be assigned to only one seat at a time. If a device is not assigned to any particular other seat it is implicitly assigned to the special default seat called "seat0". + +Note that hardware like printers, hard disks or network cards is generally not assigned to a specific seat. They are available to all seats equally. (Well, with one exception: USB sticks can be assigned to a seat.) + +"seat0" always exists. + + +## udev Rules + +Assignment of hardware devices to seats is managed inside the udev database, via settings on the devices: + +* Tag "seat": if set this device is eligible to be assigned to a seat. This tag is set for graphics devices, mice, keyboards, video cards, sound cards and more. Note that some devices like sound cards consist of multiple subdevices (i.e. a PCM for input and another one for output). This tag will be set only for the _originating_ device, not for the individual subdevices. A UI for configuring assignment of devices to seats should enumerate and subscribe to all devices with this tag set and show them in the UI. Note that USB hubs can be assigned to a seat as well, in which case all (current and future) devices plugged into it will also be assigned to the same seat (unless they are explicitly assigned to another seat). +* Tag "master-of-seat": if set this device is enough for a seat to be considered existent. This tag is usually set for the framebuffer device of graphics cards. A seat hence consists of an arbitrary number of devices marked with the "seat" tag, but (at least) one of these devices needs to be tagged with "master-of-seat" before the seat is actually considered to be around. +* Property "ID_SEAT": if set specifies the name of the seat a specific device is assigned to. _If not set the device is assigned to seat0_ (!). Also, to speed up enumeration of hardware belonging to a specific seat the seat is also set as tag on the device. i.e. if the property "ID_SEAT=seat-waldo" is set for a device the tag "seat-waldo" will be set as well. Note (_and this is important!_) that if a device is assigned to seat0, it will usually not carry such a tag and you need to enumerate all devices and check the "ID_SEAT" property manually. Again, if a device is assigned to seat0 this is visible on the device in two ways: with a property ID_SEAT=seat0 and with no property ID_SEAT set for it at all. +* Property "ID_AUTOSEAT": if set to "1" then this device automatically generates a new seat and independent seat, which is named after the path of the device. This is set for specialized USB hubs like the Plugable devices, which when plugged in should create a hotplug seat without further configuration. +* Property "ID_FOR_SEAT": when creating additional (manual) seats starting from a graphics device this is a good choice to name the seat after. It is created from the path of the device. This is useful in UIs for configuring seats: as soon as you create a new seat from a graphics device, read this property and prefix it with "seat-" and use it as name for the seat +A seat exists only and exclusively because a properly tagged device with the right ID_SEAT property exists. Besides udev rules there is no persistent data about seats stored on disk. + +Note that logind manages ACLs on a number of device classes, to allow user code to access the device nodes attached to a seat as long as the user has an active session on it. This is mostly transparent to applications. As mentioned above, for certain user software it might be a good idea to watch whether they can access device nodes instead of thinking about seats. + + +## Uses + +* If you are writing a display server (like X11) and you have not been told a seat to run on, imply that you are running for seat0. Now, to find graphics cards and input devices for your X server enumerate all devices, and filter those out that are not assigned to your seat. For this, use the ID_SEAT property and the seatXXX tag. And don't forget that devices assigned to the special seat0 seat do not have the tag or the property ID_SEAT set. (see below for a code example for this) +* If you are writing a display manager (like gdm), then enumerate all seats via logind's D-Bus interface, and subscribe to new seats being created. Then, spawn an X server and login screen on each seat showing up. (For details, see [[Writing Display Managers|http://www.freedesktop.org/wiki/Software/systemd/writing-display-managers]]) +* If you are writing a bootup splash tool (like Plymouth), then ignore all seat information completely and make use of all input devices and graphics cards as they become available. Stop using them as soon as the first X server starts up. +* If you are writing user-level software interfacing directly with kernel drivers (like PulseAudio), consider ignoring seat information completely, and make available to the user all devices he/she can access. A device that a user cannot access is a device that is not assigned to any of the seats he is currently active on. In order to track changes when sessions come and go (and are activated/deactivated) consider watching the devices nodes with inotify so that you are notified when the access mode changes. This scheme works only if your software runs under the user ID of the user himself! +* If you are writing a UI to configure seats and assign specific hardware to them, enumerate all hardware with the tag "seat", and read the ID_SEAT property from them to determine seat assignments. When changing assignments, use the AttachDevice() D-Bus call of the logind service which takes a seat name and a number of sysfs paths to the devices. You can also use this call to create a new seat, simply by assigning a graphics device to a previously unused seat name. Use ID_FOR_SEAT as a starting point for a new seat name. +This is only a very basic introduction, for details see [[logind Bus API|http://www.freedesktop.org/wiki/Software/systemd/logind]] and [[sd-login(7)|http://www.freedesktop.org/software/systemd/man/sd-login.html]]. If you have questions ping Lennart. + + +## Examples + +You may use _loginctl_ to list and introspect the seats on your system. Here's an example on a system with two seats: + + +[[!format txt """ +$ loginctl list-seats +SEAT +seat0 +seat-usb-pci-0000_00_1d_0-usb-0_1_2 +"""]] + +[[!format txt """ +$ loginctl seat-status seat0 +seat0 + Sessions: *1 + Devices: + ├ /sys/devices/LNXSYSTM:00/LNXPWRBN:00/input/input2 + │ (input:input2) "Power Button" + ├ /sys/devices/LNXSYSTM:00/device:00/PNP0A08:00/LNXVIDEO:00/input/input8 + │ (input:input8) "Video Bus" + ├ /sys/devices/LNXSYSTM:00/device:00/PNP0C0D:00/input/input0 + │ (input:input0) "Lid Switch" + ├ /sys/devices/LNXSYSTM:00/device:00/PNP0C0E:00/input/input1 + │ (input:input1) "Sleep Button" + ├ /sys/devices/pci0000:00/0000:00:02.0/drm/card0 + │ (drm:card0) + ├ /sys/devices/pci0000:00/0000:00:02.0/graphics/fb0 + │ (graphics:fb0) "inteldrmfb" + ├ /sys/devices/pci0000:00/0000:00:1a.0/usb1 + │ (usb:usb1) + │ └ /sys/devices/pci0000:00/0000:00:1a.0/usb1/1-1 + │ (usb:1-1) + │ ├ /sys/devices/pci0000:00/0000:00:1a.0/usb1/1-1/1-1.6/1-1.6:1.0/input/input6 + │ │ (input:input6) "Integrated Camera" + │ └ /sys/devices/pci0000:00/0000:00:1a.0/usb1/1-1/1-1.6/1-1.6:1.0/video4linux/video0 + │ (video4linux:video0) "Integrated Camera" + ├ /sys/devices/pci0000:00/0000:00:1b.0/sound/card0 + │ (sound:card0) "Intel" + ├ /sys/devices/pci0000:00/0000:00:1d.0/usb2 + │ (usb:usb2) + │ └ /sys/devices/pci0000:00/0000:00:1d.0/usb2/2-1 + │ (usb:2-1) + │ ├ /sys/devices/pci0000:00/0000:00:1d.0/usb2/2-1/2-1.8/2-1.8:1.0/input/input5 + │ │ (input:input5) "N-Trig Touchscreen" + │ └ /sys/devices/pci0000:00/0000:00:1d.0/usb2/2-1/2-1.8/2-1.8:1.1/input/input9 + │ (input:input9) "N-Trig Touchscreen" + ├ /sys/devices/platform/i8042/serio0/input/input3 + │ (input:input3) "AT Translated Set 2 keyboard" + ├ /sys/devices/platform/i8042/serio1/input/input4 + │ (input:input4) "SynPS/2 Synaptics TouchPad" + ├ /sys/devices/platform/i8042/serio1/serio2/input/input10 + │ (input:input10) "TPPS/2 IBM TrackPoint" + ├ /sys/devices/platform/thinkpad_acpi/input/input7 + │ (input:input7) "ThinkPad Extra Buttons" + └ /sys/devices/platform/thinkpad_acpi/sound/card29 + (sound:card29) "ThinkPadEC" +"""]] + +[[!format txt """ +$ loginctl seat-status seat-usb-pci-0000_00_1d_0-usb-0_1_2 +seat-usb-pci-0000_00_1d_0-usb-0_1_2 + Devices: + └ /sys/devices/pci0000:00/0000:00:1d.0/usb2/2-1/2-1.2 + (usb:2-1.2) + ├ /sys/devices/pci0000:00/0000:00:1d.0/usb2/2-1/2-1.2/2-1.2.1/graphics/fb1 + │ (graphics:fb1) "udlfb" + ├ /sys/devices/pci0000:00/0000:00:1d.0/usb2/2-1/2-1.2/2-1.2.3/2-1.2.3:1.0/sound/card1 + │ (sound:card1) "Device" + ├ /sys/devices/pci0000:00/0000:00:1d.0/usb2/2-1/2-1.2/2-1.2.3/2-1.2.3:1.3/input/input11 + │ (input:input11) "C-Media Electronics Inc. USB Multimedia Audio Device" + ├ /sys/devices/pci0000:00/0000:00:1d.0/usb2/2-1/2-1.2/2-1.2.5/2-1.2.5:1.0/input/input12 + │ (input:input12) "EL USB Keyboard " + ├ /sys/devices/pci0000:00/0000:00:1d.0/usb2/2-1/2-1.2/2-1.2.5/2-1.2.5:1.1/input/input13 + │ (input:input13) "EL USB Keyboard " + └ /sys/devices/pci0000:00/0000:00:1d.0/usb2/2-1/2-1.2/2-1.2.6/2-1.2.6:1.0/input/input14 + (input:input14) "Logitech USB-PS/2 Optical Mouse" +"""]] +You may use "loginctl attach" to assign hardware to a specific seat. + +Here's a short code example (no error checking, so don't use this as is) for enumerating all input devices on a specific seat. A display server might use something like this: + + +[[!format txt """ +int enum_input_on_seat(const char *seat) { + struct udev *udev; + struct udev_enumerate *enumerate; + struct udev_list_entry *item, *first; + + if (!seat) /* ← Here's the beef */ + seat = "seat0"; /* ← Here's the beef */ + + udev = udev_new(); + + enumerate = udev_enumerate_new(udev); + udev_enumerate_add_match_subsystem(enumerate, "input"); + + if (strcmp(seat, "seat0") != 0) /* ← Here's the beef */ + udev_enumerate_add_match_tag(enumerate, seat); /* ← Here's the beef */ + + udev_enumerate_scan_devices(enumerate); + + first = udev_enumerate_get_list_entry(e); + udev_list_entry_foreach(item, first) { + struct udev_device *d; + const char *d_seat; + + d = udev_device_new_from_syspath(udev, udev_list_entry_get_name(item)); + + d_seat = udev_device_get_property_value(d, "ID_SEAT"); /* ← Here's the beef */ + if (!d_seat) /* ← Here's the beef */ + d_seat = "seat0"; /* ← Here's the beef */ + + if (strcmp(seat, d_seat) == 0) { /* ← Here's the beef */ + + /* Found a device, yihaaa! */ + printf("Found device %s\n", udev_device_new_from_syspath(d)); + + do_something_with_our_input_device(d); + } + + udev_device_unref(d); + } + + udev_enumerate_unref(enumerate); + udev_unref(udev); +} +"""]] + +## Multi-Seat X + +Note that even though XOrg gained, in version 1.12 of xserver, a new -seat switch to make use of multi-seat information it does so only for input devices, not for displays. To work around this systemd includes a tiny wrapper binary in /lib/systemd/systemd-multi-seat-x which emulates the right behaviour by creating a throw-away X configuration file which does the right thing. If you are implementing a multi-seat display manager you probably want to use this binary instead of the real X binary for now. As soon as XOrg upstream gains proper multi-seat support also for displays this binary will be removed from systemd, hence write your DM to fallback to the real X server if systemd's wrapper is not found. diff --git a/Software/systemd/screenshot.png b/Software/systemd/screenshot.png Binary files differnew file mode 100644 index 00000000..7a8a4a8c --- /dev/null +++ b/Software/systemd/screenshot.png diff --git a/Software/systemd/separate-usr-is-broken.mdwn b/Software/systemd/separate-usr-is-broken.mdwn new file mode 100644 index 00000000..8ef40875 --- /dev/null +++ b/Software/systemd/separate-usr-is-broken.mdwn @@ -0,0 +1,40 @@ + +[[Back to systemd|http://www.freedesktop.org/wiki/Software/systemd/]] + + +# Booting Without /usr is Broken + +You probably discovered this page because your shiny new systemd system referred you here during boot time, when it warned you that booting without /usr pre-mounted wasn't supported anymore. And now you wonder what this all is about. Here's an attempt of an explanation: + +One thing in advance: systemd itself is actually completely fine with /usr on a separate file system that is not pre-mounted at boot time. However, the common basic set of OS components of modern Linux machines is not, and has not been in quite some time. And it is unlikely that this is going to be fixed any time soon, or even ever. + +Most of the failures you will experience with /usr split off and not pre-mounted in the initramfs are graceful failures: they won't become directly visible, however certain features become unavailable due to these failures. Quite a number of programs these days hook themselves into the early boot process at various stages. A popular way to do this is for example via udev rules. The binaries called from these rules are sometimes located on /usr/bin, or link against libraries in /usr/lib, or use data files from /usr/share. If these rules fail udev will proceed with the next one, however later on applications will then not properly detect these udev devices or features of these devices. Here's a short, very in-comprehensive list of software we are aware of that currently are not able to provide the full set of functionality when /usr is split off and not pre-mounted at boot: udev-pci-db/udev-usb-db and all rules depending on this (using the PCI/USB database in /usr/share), PulseAudio, NetworkManager, ModemManager, udisks, libatasmart, usb_modeswitch, gnome-color-manager, usbmuxd, ALSA, D-Bus, CUPS, Plymouth, LVM, hplip, multipath, Argyll, VMWare, the locale logic of most programs and a lot of other stuff. + +You don't believe us? Well, here's a command line that reveals a few obvious cases of udev rules that will silently fail to work if /usr is split off and not pre-mounted: `egrep 'usb-db|pci-db|FROM_DATABASE|/usr' /*/udev/rules.d/*` -- and you find a lot more if you actually look for it. On my fresh Fedora 15 install that's 23 obvious cases. + + +## The Status Quo + +Due to this, many upstream developers have decided to consider the problem of a separate /usr that is not mounted during early boot an outdated question, and started to close bugs regarding these issues as WONTFIX. We certainly cannot blame them, as the benefit of supporting this is questionable and brings a lot of additional work with it. + +And let's clarify a few things: + +1. **It isn't systemd's fault.** systemd works fine with /usr on a separate file system that is not pre-mounted at boot. +1. **systemd is merely the messenger.** Don't shoot the messenger. +1. **There's no news in all of this.** The message you saw is just a statement of fact, describing the status quo. Things have been this way since a while. +1. **The message is merely a warning.** You can choose to ignore it. +1. **Don't blame us**, don't abuse us, it's not our fault. +We have been working on the Linux userspace since quite some time, and simply have enough of the constant bug reports regarding these issues, since they are actually very hard to track down because the failures are mostly graceful. Hence we placed this warning into the early boot process of every systemd Linux system with a split off and not pre-mounted /usr, so that people understand what is going on. + + +## Going Forward + +/usr on its own filesystem is useful in some custom setups. But instead of expecting the traditional Unix way to (sometimes mindlessly) distributing tools between /usr and /, and require more and more tools to move to /, we now just expect /usr to be pre-mounted from inside the initramfs, to be available before 'init' starts. The duty of the minimal boot system that consisted of /bin, /sbin and /lib on traditional Unix, has been taken over by the initramfs of modern Linux. An initramfs that supports mounting /usr on top of / before it starts 'init', makes all existing setups work properly. + +There is no way to reliably bring up a modern system with an empty /usr. There are two alternatives to fix it: move /usr back to the rootfs or use an initramfs which can hide the split-off from the system. + +On the Fedora distribution we have succeeded to clean up the situation and the confusion the current split between / and /usr has created. We have moved all tools that over time have been moved to / back to /usr (where they belong), and the root file system only contains compatibility symlinks for /bin and /sbin into /usr. All binaries of the system are exclusively located within the /usr hierarchy. + +In this new definition of /usr, the directory can be mounted read-only by default, while the rootfs may be either read-write or read-only (for stateless systems) and contains only the empty mount point directories, compat-symlinks to /usr and the host-specific data like /etc, /root, /srv. In comparison to today's setups, the rootfs will be very small. The host-specific data will be properly separated from the installed operating system. The new /usr could also easily be shared read-only across several systems. Such a setup would be more efficient, can provide additional security, is more flexible to use, provides saner options for custom setups, and is much simpler to setup and maintain. + +For more information on this please continue to [[The Case for the /usr Merge|http://www.freedesktop.org/wiki/Software/systemd/TheCaseForTheUsrMerge]]. diff --git a/Software/systemd/syslog.mdwn b/Software/systemd/syslog.mdwn new file mode 100644 index 00000000..45988ef0 --- /dev/null +++ b/Software/systemd/syslog.mdwn @@ -0,0 +1,45 @@ + +[[Back to systemd|http://www.freedesktop.org/wiki/Software/systemd/]] + + +# Writing syslog Daemons Which Cooperate Nicely With systemd + +Here are a few notes on things to keep in mind when you work on a classic BSD syslog daemon for Linux, to ensure that your syslog daemon works nicely together with systemd. If your syslog implementation does not follow these rules, then it will not be compatible with systemd v38 and newer. + +A few notes in advance: systemd centralizes all log streams in the Journal daemon. Messages coming in via /dev/log, via the native protocol, via STDOUT/STDERR of all services and via the kernel are received in the journal daemon. The journal daemon then stores them to disk or in RAM (depending on the configuration of the Storage= option in journald.conf), and optionally forwards them to the console, the kernel log buffer, or to a classic BSD syslog daemon -- and that's where you come in. + +Note that it is now the journal that listens on /dev/log, no longer the BSD syslog daemon directly. If your logging daemon wants to get access to all logging data then it should listen on /run/systemd/journal/syslog instead via the syslog.socket unit file that is shipped along with systemd. On a systemd system it is no longer OK to listen on /dev/log directly, and your daemon may not bind to the /run/systemd/journal/syslog socket on its own. If you do that then you will lose logging from STDOUT/STDERR of services (as well as other stuff). + +Your BSD compatible logging service should alias `syslog.service` to itself (i.e. symlink) when it is _enabled_. That way [[syslog.socket|http://cgit.freedesktop.org/systemd/systemd/plain/units/syslog.socket]] will activate your service when things are logged. Of course, only one implementation of BSD syslog can own that symlink, and hence only one implementation can be enabled at a time, but that's intended as there can only be one process listening on that socket. (see below for details how to manage this symlink.) Note that this means that syslog.socket as shipped with systemd is _shared_ among all implementations, and the implementation that is in control is configured with where syslog.service points to. + +Note that journald tries hard to forward to your BSD syslog daemon as much as it can. That means you will get more than you traditionally got on /dev/log, such as stuff all daemons log on STDOUT/STDERR and the messages that are logged natively to systemd. Also, we will send stuff like the original SCM_CREDENTIALS along if possible. + +(BTW, journald is smart enough not to forward the kernel messages it gets to you, you should read that on your own, directly from /proc/kmsg, as you always did. It's also smart enough never to forward kernel messages back to the kernel, but that probably shouldn't concern you too much...) + +And here are the recommendations: + +* First of all, make sure your syslog daemon installs a native service unit file (SysV scripts are not sufficient!) and is socket activatable. Newer systemd versions (v35+) do not support non-socket-activated syslog daemons anymore and we do no longer recommend people to order their units after syslog.target. That means that unless your syslog implementation is socket activatable many services will not be able to log to your syslog implementation and early boot messages are lost entirely to your implementation. Note that your service should install only one unit file, and nothing else. Do not install socket unit files. +* Make sure that in your unit file you set StandardOutput=null in the [Service] block. This makes sure that regardless what the global default for StandardOutput= is the output of your syslog implementation goes to /dev/null. This matters since the default StandardOutput= value for all units can be set to syslog and this should not create a feedback loop with your implementation where the messages your syslog implementation writes out are fed back to it. In other words: you need to explicitly opt out of the default standard output redirection we do for other services. (Also note that you do not need to set StandardError= explicitly, since that inherits the setting of StandardOutput= by default) +* /proc/kmsg is your property, flush it to disk as soon as you start up. +* Name your service unit after your daemon (e.g. rsyslog.service or syslog-ng.service) and make sure to include Alias=syslog.service in your [Install] section in the unit file. This is ensures that the symlink syslog.service is created if your service is enabled and that it points to your service. Also add WantedBy=multi-user.target so that your service gets started at boot, and add Requires=syslog.socket in [Unit] so that you pull in the socket unit. +Here are a few other recommendations, that are not directly related to systemd: + +* Make sure to read the priority prefixes of the kmsg log messages the same way like from normal userspace syslog messages. When systemd writes to kmsg it will prefix all messages with valid priorities which include standard syslog facility values. OTOH for kernel messages the facility is always 0. If you need to know whether a message originated in the kernel rely on the facility value, not just on the fact that you read the message from /proc/kmsg! A number of userspace applications write messages to kmsg (systemd, udev, dracut, others), and they'll nowadays all set correct facility values. +* When you read a message from the socket use SCM_CREDENTIALS to get information about the client generating it, and possibly patch the message with this data in order to make it impossible for clients to fake identities. +The unit file you install for your service should look something like this: + + +[[!format txt """ +[Unit] +Description=System Logging Service +Requires=syslog.socket + +[Service] +ExecStart=/usr/sbin/syslog-ng -n +StandardOutput=null + +[Install] +Alias=syslog.service +WantedBy=multi-user.target +"""]] +And remember: don't ship any socket unit for /dev/log or /run/systemd/journal/syslog (or even make your daemon bind directly to these sockets)! That's already shipped along with systemd for you. diff --git a/Software/systemd/timedated.mdwn b/Software/systemd/timedated.mdwn new file mode 100644 index 00000000..543671fd --- /dev/null +++ b/Software/systemd/timedated.mdwn @@ -0,0 +1,100 @@ + +[[Back to systemd|http://www.freedesktop.org/wiki/Software/systemd/]] + + +# timedated + +systemd 30 and newer include systemd-timedated. This is a tiny daemon that can be used to control the system time and related settings. It currently offers access to four settings: + +* The system time +* The system timezone +* A boolean controlling whether the system RTC is in local or UTC timezone +* Whether the NTP services is enabled/started or disabled/stopped. +See [[systemd-timedated.service(8)|http://www.freedesktop.org/software/systemd/man/systemd-timedated.service.html]] for more information. + +The daemon is accessible via D-Bus: + + +[[!format txt """ +$ gdbus introspect --system --dest org.freedesktop.timedate1 --object-path /org/freedesktop/timedate1 +node /org/freedesktop/timedate1 { + interface org.freedesktop.timedate1 { + methods: + SetTime(in x usec_utc, + in b relative, + in b user_interaction); + SetTimezone(in s timezone, + in b user_interaction); + SetLocalRTC(in b local_rtc, + in b fix_system, + in b user_interaction); + SetNTP(in b use_ntp, + in b user_interaction); + signals: + properties: + readonly s Timezone = 'Europe/Berlin'; + readonly b LocalRTC = false; + readonly b NTP = true; + }; + interface org.freedesktop.DBus.Properties { + }; + interface org.freedesktop.DBus.Introspectable { + }; + interface org.freedesktop.DBus.Peer { + }; +}; +"""]] +Use **SetTime()** to change the system clock. Pass a value of microseconds since 1 Jan 1970 UTC. If "relative" is true the passed usec value will be added to the current system time, if it is false the current system time will be set to the passed usec value. If the system time is set with this call the RTC will be updated as well. + +Use **SetTimezone()** to set the system timezone. Pass a value like "Europe/Berlin" to set the timezone. Valid timezones you may parse from /usr/share/zoneinfo/zone.tab. If the RTC is configured to be maintained in local time it will be updated accordingly. + +Use **SetLocalRTC()** to control whether the RTC is in local time or UTC. It is strongly recommended to maintain the RTC in UTC. Some OSes (Windows) however maintain the RTC in local time which might make it necessary to enable this feature. However, this creates various problems as daylight changes might be missed. If fix_system is passed "true" the time from the RTC is read again and the system clock adjusted according to the new setting. If fix_system is passed "false" the system time is written to the RTC taking the new setting into account. Use fix_system=true in installers and livecds where the RTC is probably more reliable than the system time. Use fix_system=false in configuration UIs that are run during normal operation and where the system clock is probably more reliable than the RTC. + +Use **SetNTP()** to control whether the system clock is synchronized with the network using NTP. This will enable/start resp. disable/stop the NTP service. + +Whenever the timezone and local_rtc settings are changed via the daemon PropertyChanged signals are sent out to which clients can subscribe. Changing the time settings using this interface is authenticated via PolicyKit. + +Note that this service will not inform you about system time changes. Use timerfd() with CLOCK_REALTIME and TFD_TIMER_CANCEL_ON_SET for that. + +The user_interaction boolean parameters can be used to control whether PolicyKit should interactively ask the user for authentication credentials if it needs to. + +The PolicyKit action for SetTimezone() is _org.freedesktop.timedate1.set-timezone_. For SetLocalRTC() it is _org.freedesktop.timedate1.set-local-rtc_, for SetTime() it is _org.freedesktop.timedate1.set-time_ and for SetNTP() it is _org.freedesktop.timedate1.set-ntp_. + +The sources for timedated are available in git for review: [[http://cgit.freedesktop.org/systemd/systemd/tree/src/timedate/timedated.c|http://cgit.freedesktop.org/systemd/systemd/tree/src/timedate/timedated.c]] + +For more information how the system clock and RTC interact see [[http://lists.freedesktop.org/archives/systemd-devel/2011-May/002526.html|http://lists.freedesktop.org/archives/systemd-devel/2011-May/002526.html]] + +Plan: We plan to add a new boolean "CanNTP" soon, which can be used to determine whether the system can do NTP or not. + + +## Hooking in an NTP Implementation + +systemd-timedated can enable/disable NTP implementations. Since multiple NTP implementations exist the unit to enable/start/disable/stop for this is not hardcoded in timedated and may be configured via drop-in files in /usr/lib/systemd/ntp-units.d/*.list. An NTP implementation should ship one of these files in its RPM listing the unit to disable or enable. timedated will then enable/disable the first unit it finds from all .list files in that directory. The files are sorted alphabetically by their names. A single file can list multiple unit files. Empty lines and lines starting with # are ignored. Example: the NTP implementation ntpd could ship: + + +[[!format txt """ +ntpd.service +"""]] +as `/usr/lib/systemd/ntp-units.d/60-ntpd.list`. Similar, chrony could ship: + + +[[!format txt """ +chronyd.service +"""]] +as `/usr/lib/systemd/ntp-units.d/50-chrony.list`. If both servers are installed chrony would be controlled preferably by timedated, since `50-chrony.list` is alphabetically before `60-ntpd.list`. + +Note that distributions can also override how the individual implementations order themselves alphabetically. For example, a distribution could drop in this: + + +[[!format txt """ +# Prefer ntpd over chronyd +ntpd.service +chronyd.service +"""]] +as `/usr/lib/systemd/ntp-units.d/00-fedora.list` in which case this overrides the others, `since 00-fedora.list` is alphabetically before both `50-chrony.list` and `60-ntpd.list`. + + + +--- + + This D-Bus interface follows [[the usual interface versioning guidelines|http://0pointer.de/blog/projects/versioning-dbus.html]]. diff --git a/Software/udisks.mdwn b/Software/udisks.mdwn new file mode 100644 index 00000000..4691dc94 --- /dev/null +++ b/Software/udisks.mdwn @@ -0,0 +1,57 @@ + + +# udisks + +The udisks project provides: + +* a daemon, udisksd, that implements well-defined D-Bus interfaces that can be used to query and manipulate storage devices. +* a command-line tool, udisksctl, that can be used to query and use the daemon +The actions that a user can perform using udisks are restricted using [[polkit|Software/PolicyKit]]. + + +## Download + +The latest version can be downloaded from the [[here|http://udisks.freedesktop.org/releases/]]. + + +## Documentation + +There is [[online documentation|http://udisks.freedesktop.org/docs/latest/]] available, which documents the D-Bus API and the command-line tools provided by udisks. + + +## Bugs + +When [[filing bugs against udisks|http://bugs.freedesktop.org/enter_bug.cgi?product=udisks]], please include + +* the output of 'udisksctl dump' +* the output of 'udevadm info --export-db' (as root) +* the output of 'cat /proc/self/mountinfo' +* the output of 'cat /etc/fstab' +* the version of udisks, gvfs and libatasmart + * On Fedora/RHEL this is the output of 'rpm -q udisks2 gvfs libatasmart' +If the bugs is related to the GNOME desktop please also include + +* the output of 'gvfs-mount -li' captured from the desktop session as the user (not root) +If the bug happens when plugging in a device or activating a device also include + +* the output of 'udisksctl monitor' +* the output of 'gvfs-mount -oi' captured from the desktop session as the user (not root) +* the output of 'udevadm monitor --udev --property' (as root) +while plugging in or activating the device. + +If the bug is related to ATA SMART include (replace /dev/sda with the device for the disk in question) + +* the output of 'skdump /dev/sda' (as root) +* the binary file skdump-output obtained via 'skdump --save=skdump-output /dev/sda' (as root) + +## Hacking + +Join the [[mailing list|http://lists.freedesktop.org/mailman/listinfo/devkit-devel]] to get involved with feature development. + +Development happens in [[git|GettingInvolved]], in the udisks module. There is a [[web interface|http://cgit.freedesktop.org/udisks]] to the repository. + + + +--- + + [[CategoryHalReplacement|CategoryHalReplacement]] diff --git a/Software/uim.mdwn b/Software/uim.mdwn new file mode 100644 index 00000000..79ae6dd0 --- /dev/null +++ b/Software/uim.mdwn @@ -0,0 +1,2 @@ + +Official site of uim moved. Please visit [[http://code.google.com/p/uim/|http://code.google.com/p/uim/]] diff --git a/Software/unicode-translation.mdwn b/Software/unicode-translation.mdwn new file mode 100644 index 00000000..36c96fcd --- /dev/null +++ b/Software/unicode-translation.mdwn @@ -0,0 +1,35 @@ +# unicode-translation and unicode-han-translation + +The unicode-translation project aims to translate Unicode character names and other data into many languages using the gettext framework. It is a subproject of [[project UTF-8|Software/utf-8]]. + +The related unicode-han-translation project translates the Unicode definitions of East Asian ideographs. + +unicode-translation and unicode-han-translation use the Translation Project infrastructure (<http://www.iro.umontreal.ca/translation/>). + +* [[unicode-translation status|http://www2.iro.umontreal.ca/translation/registry.cgi?domain=unicode-translation]] +* [[unicode-han-translation status|http://www2.iro.umontreal.ca/translation/registry.cgi?domain=unicode-han-translation]] + +## Download + +<http://freedesktop.org/Software/unicode-translation/releases/> + + +## CVS + + +### Anonymous CVS + + cvs -d:pserver:anoncvs@cvs.freedesktop.org:/cvs/utf-8 co unicode-translation + cvs -d:pserver:anoncvs@cvs.freedesktop.org:/cvs/utf-8 co unicode-han-translation + +### Developer CVS + + cvs -d:ext:developername@cvs.freedesktop.org/cvs/utf-8 co unicode-translation + cvs -d:ext:developername@cvs.freedesktop.org/cvs/utf-8 co unicode-han-translation + +### Browse with viewcvs + +* <http://cvs.freedesktop.org/utf-8/unicode-translation/> +* <http://cvs.freedesktop.org/utf-8/unicode-han-translation/> + +-- [[NoahLevitt]] - 16 Jan 2004 diff --git a/Software/urfkill.mdwn b/Software/urfkill.mdwn new file mode 100644 index 00000000..ae690f93 --- /dev/null +++ b/Software/urfkill.mdwn @@ -0,0 +1,59 @@ + + +# urfkill + +For the laptop and mobile devices users, the management of the radio killswitches is important for the connectivity and power consumption. [[HAL|Software/hal]] used to take care of this job, but it is now [[deprecated|http://lists.freedesktop.org/archives/hal/2008-May/011560.html]]. The urfkill project is created to fill the gap and to provide more flexible configuration for the rfkill-related function keys. + + +## Download + +The latest release is 0.3.0 and can be downloaded from [[github|https://github.com/downloads/lcp/urfkill/urfkill-0.3.0.tar.xz]]. + +Development happens in [[git|GettingInvolved]]. There is a [[web interface|https://github.com/lcp/urfkill/]] to the repository. + + +## Documentation + +The documents of the D-Bus API and liburfkill-glib can be found [[here|http://lcp.github.com/urfkill-doc/]]. + + +### HowTo + +[[How to launch urfkill during system boot|Software/urfkill/HowToLaunch]] + + +## Known Issues + +* For Lenovo Thinkpad X200, the bluetooth killswitch (hci0) sometimes was soft-blocked after turning on bluetooth. + +Solution: set "force_sync" to true in /etc/urfkill/urfkill.conf + +* The bluetooth killswitches cannot be controlled by urfkilld in Lenovo [[ThinkPad|ThinkPad]] laptops. + +The states of the bluetooth killswitches in [[ThinkPad|ThinkPad]] are maintained by the kernel platform drivers, i.e. thinkpad_acpi, and urfkilld has no way to change it. + +Solution: please leave them alone. + + +## Bugs + +Please mail to Gary Lin ([[glin@suse.com|mailto:glin@suse.com]]) and Joey Lee ([[jlee@suse.com|mailto:jlee@suse.com]]) or poke me (glin) on #udev/irc.freenode.net + + +## Client + +* [[rfkiller|https://github.com/lcp/rfkiller]] - a gnome-extension which utilizes urfkill to manage killswitches. + + +## TODO + +* Provide a policy for the user to setup rfkill control rules when catching WLAN/BT/3G keycodes. +* Integrate with GUI to provide power consumption function to user, e.g. + * Killswitch-Manager + * killswitch-applet + * python-killswitch + + +--- + + [[CategoryHalReplacement|CategoryHalReplacement]] diff --git a/Software/urfkill/urfkilldaemon b/Software/urfkill/urfkilldaemon new file mode 100644 index 00000000..930437ad --- /dev/null +++ b/Software/urfkill/urfkilldaemon @@ -0,0 +1,102 @@ +#! /bin/bash +# Copyright (c) 2002-2010 SuSE Linux AG, Nuernberg, Germany. +# All rights reserved. +# +# Authors: Lee, Chun-Yi <jlee@novell.com> +# +# LSB compliant service control script; see http://www.linuxbase.org/spec/ +# +### BEGIN INIT INFO +# Provides: urfkilldaemon +# Required-Start: dbus +# Required-Stop: $null +# Should-Stop: $null +# Default-Start: 2 3 5 +# Default-Stop: +# Short-Description: Urfkill is a daemon to control radio killswitches through /dev/rfkill. +# Description: Urfkill is a daemon to control radio killswitches through /dev/rfkill and supports PolicyKit +# authorization mechanism. +# urfkill is a project to handle rfkill events in userspace and aimed to replace the rfkill +# input handler in kernel, i.e. rfkill-input, and provide a flexible policy for rfkill keys. +# +### END INIT INFO + +# Check for missing binaries (stale symlinks should not happen) +URFKILLD_BIN=/usr/lib/urfkill/urfkilld +test -x $URFKILLD_BIN || exit 5 + +# Shell functions sourced from /etc/rc.status: +# rc_check check and set local and overall rc status +# rc_status check and set local and overall rc status +# rc_status -v ditto but be verbose in local rc status +# rc_status -v -r ditto and clear the local rc status +# rc_status -s display "skipped" and exit with status 3 +# rc_status -u display "unused" and exit with status 3 +# rc_failed set local and overall rc status to failed +# rc_failed <num> set local and overall rc status to <num> +# rc_reset clear local rc status (overall remains) +# rc_exit exit appropriate to overall rc status +# rc_active checks whether a service is activated by symlinks +# rc_splash arg sets the boot splash screen to arg (if active) +. /etc/rc.status + +# Reset status of this service +rc_reset + +case "$1" in + start) + if [ ! -d /sys/class/rfkill ] ; then + echo -n "urfkilldaemon: didn't detect any killswitch" + rc_status -s + rc_exit + fi + + echo -n "Starting urfkilld " + startproc $URFKILLD_BIN + rc_status -v + ;; + stop) + echo -n "Shutting down urfkilld " + killproc -TERM $URFKILLD_BIN + rc_status -v + ;; + try-restart) + $0 status + if test $? = 0; then + $0 restart + else + rc_reset # Not running is not a failure. + fi + rc_status + ;; + restart) + $0 stop + $0 start + rc_status + ;; + force-reload|reload) + echo -n "Reload service urfkilld " + killproc -HUP $URFKILLD_BIN + rc_status -v + ;; + status) + echo -n "Checking for service urfkilld " + PID=`checkproc -v $URFKILLD_BIN` + if rc_status ; then + case `cat /proc/$PID/cmdline` in *events.ignore) rc_failed 3 ;; esac + fi + rc_status -v + ;; + probe) + ## Optional: Probe for the necessity of a reload, print out the + ## argument to this init script which is required for a reload. + ## Note: probe is not (yet) part of LSB (as of 1.2) + # test /etc/FOO/FOO.conf -nt /var/run/FOO.pid && echo reload + ;; + *) + echo "Usage: $0" \ + "{start|stop|status|try-restart|restart|force-reload|reload|probe}" + exit 1 + ;; +esac +rc_exit diff --git a/Software/utf-8.mdwn b/Software/utf-8.mdwn new file mode 100644 index 00000000..25586a2f --- /dev/null +++ b/Software/utf-8.mdwn @@ -0,0 +1,41 @@ + + +## Project UTF-8 + +Project UTF-8’s purpose is to document and promote proper Unicode support (particularly UTF-8 support) in free and Open Source software. + +The latest specification for UTF-8, dated 2003-11, can be found as IETF’s STD 63 or [[RFC 3629|http://www.faqs.org/rfcs/rfc3629.html]]. + + +#### Discussion + +There is a mailing list: [[utf-8@lists.freedesktop.org|mailto:utf-8@lists.freedesktop.org]]. To join the list, send a message to [[utf-8-request@lists.freedesktop.org|mailto:utf-8-request@lists.freedesktop.org]] with only the word ‘subscribe’ in the body. [[List archives|http://freedesktop.org/pipermail/utf-8/]] are available. + +IRC discussions happen in the **[[#unicode|irc://irc.gnome.org/unicode]]** channel on **irc.gnome.org**. [[Here|Software/IrcClients]] is a helpful list of irc clients that support UTF-8. + + +#### Contributing + +To contribute to these pages, create a wiki account, then join the above IRC channel and ask someone to add you to [[FreedesktopGroup|FreedesktopGroup]]. + +Current project members include + +* Behdad Esfahbod +* Noah Levitt +* Roozbeh Pournader +* Danilo Segan +* Mariano Suárez-Alvarez +* Miloslav Trmac +* Alexander Winston + +### Project UTF-8 Pages + + * [[BadSoftware|Software/BadSoftware]]. Contrary to what Markus Kuhn is doing with his [[UTF-8 and Unicode FAQ|http://www.cl.cam.ac.uk/~mgk25/unicode.html]], we will be trying to maintain a list of software that doesn’t support UTF-8. Since UTF-8 is _the_ character set standard, we consider every piece of software that doesn’t support UTF-8 to be very old-fashioned and out of date. + * [[BMP-Only|Software/BMP-Only]]. A list of software that supports only the [[BMP|Software/BMP]] of Unicode, and thus lacks full Unicode support. + * [[Fonts|Software/Fonts]]. A list of free and non-free fonts supporting various ranges of Unicode. + * [[unicode-translation|Software/unicode-translation]]. A subproject of project UTF-8 with the goal of translating Unicode character names and other data into many languages using the gettext framework. +-- [[AlexanderWinston|AlexanderWinston]] - 14 Jun 2004 + +-- [[AlexanderWinston|AlexanderWinston]] - 07 Apr 2004 + +-- [[NoahLevitt|NoahLevitt]] - 17 Feb 2004 diff --git a/Software/vaapi.mdwn b/Software/vaapi.mdwn new file mode 100644 index 00000000..4c6b2c9c --- /dev/null +++ b/Software/vaapi.mdwn @@ -0,0 +1,114 @@ +### News + +* Sep 20'12 -- All new software releases will from now on be available from <http://www.freedesktop.org/software/vaapi/> +* Mar 26'10 -- Add H.264 decoding to Intel Ironlake (HD Graphics) platforms (libVA i965_h264 branch) +* Jul 13'09 -- libVA mailing list was created on fd.o (<http://lists.freedesktop.org/mailman/listinfo/libva>) +* Jul 01'09 -- libVA news on LWN (<http://lwn.net/Articles/339349/>) +* Jul 01'09 -- Add MPEG-2 VLD driver into libVA for Intel integrated G45 graphics chip +* Jun 12'09 -- Update VA-API to version 0.30 to include encode support +* Sep 13'07 -- Create libVA git repository on freedesktop.org + +### About + +The main motivation for VA-API (Video Acceleration API) is to enable hardware accelerated video decode/encode at various entry-points (VLD, IDCT, Motion Compensation etc.) for the prevailing coding standards today (MPEG-2, MPEG-4 ASP/H.263, MPEG-4 AVC/H.264, and VC-1/VMW3). Extending XvMC was considered, but due to its original design for MPEG-2 [[MotionComp|MotionComp]] only, it made more sense to design an interface from scratch that can fully expose the video decode capabilities in today's GPUs. + +The current video decode/encode interface is window system independent, so that potentially it can be used with graphics sub-systems other than X. In a nutshell it is basically a scheme to pass various types of data buffers from the application to the GPU for decoding or encoding. Feedback on the API is greatly welcomed, as this is intended to be a community collaborative effort. + + +### Download + +The latest releases of libva software can be found at: <http://www.freedesktop.org/software/vaapi/> + + +### Git + +libva an implementation of VA-API for Linux, is now available via git from the following location (<http://cgit.freedesktop.org/libva/>): + + git clone git://anongit.freedesktop.org/git/libva + +The gstreamer-vaapi elements are available at: <https://gitorious.org/vaapi/gstreamer-vaapi> + + git clone git://gitorious.org/vaapi/gstreamer-vaapi.git + +### Specification + +Latest VA-API decode/encode specification can be found at <http://cgit.freedesktop.org/libva/tree/va/va.h>, + +Post-processing interface can be found at <http://cgit.freedesktop.org/libva/tree/va/va_x11.h> + + +### Drivers (back-ends) that implement VA-API + +* Broadcom Crystal HD (work-in-progress): + * <http://gitorious.org/crystalhd-video> +* Intel Embedded Graphics Drivers (IEGD): + * <http://edc.intel.com/Software/Downloads/IEGD/> +* Intel Embedded Media and Graphics Drivers (EMGD): + * <http://edc.intel.com/Software/Downloads/EMGD/> +* Intel GMA500 driver (OEM only): + * <https://launchpad.net/~ubuntu-mobile/+archive/ppa> +* Intel integrated G45 graphics chips: + * <http://cgit.freedesktop.org/vaapi/intel-driver> +* IMG VXD375/385 and VXE250/285 video engines: + * <http://cgit.freedesktop.org/vaapi/pvr-driver/> +* VDPAU back-end for NVIDIA and VIA chipsets: + * <http://cgit.freedesktop.org/vaapi/vdpau-driver/> +* VIA / S3 Graphics Accelerated Linux Driver: + * <http://www.s3graphics.com/en/index.aspx> +* XvBA / ATI Graphics Backend (for proprietary driver only) + * <http://cgit.freedesktop.org/vaapi/xvba-driver/> +Other back-ends are currently under development. + + +### Decoding Hardware with no backend available + +* NONE FOR NOW + +### Software using VA-API + +* Clutter toolkit (through `clutter-gst`, thus GStreamer): + * <http://clutter-project.org/> +* FFmpeg (upstream SVN tree >= 2010/01/18 / version 0.6.x and onwards): + * <http://ffmpeg.org/> +* Fluendo video codec pack for Intel Atom (GStreamer): + * <http://www.fluendo.com/> +* Gnash flash player: + * <http://wiki.gnashdev.org/Hardware_Video_decoding> +* GStreamer: + * <http://gitorious.org/vaapi/gstreamer-vaapi> +* Lightspark flash player: + * <http://lightspark.sourceforge.net/> +* MPlayer/VAAPI: + * <http://gitorious.org/vaapi/mplayer> (`hwaccel-vaapi` branch) +* MythTV (work-in-progress): + * <http://www.mythtv.org/wiki/VAAPI> +* [[RealPlayer]] for MID: + * <https://community.helixcommunity.org/Licenses/realplayer_for_mid_faq.html> +* Totem movie player (simply requires GStreamer VA-API plug-ins): + * <http://projects.gnome.org/totem/> +* VideoLAN - VLC media player: + * <http://www.videolan.org/> +* XBMC: + * <http://www.xbmc.org/> +* Xine: + * <https://github.com/huceke/xine-lib-vaapi/tree/vaapi> + +### libVA sample code + +* Hardware video decoding acceleration demos: + * <http://gitorious.org/hwdecode-demos/> +* Decode sample program: + * <http://cgit.freedesktop.org/libva/tree/test/decode/mpeg2vldemo.c> +* Encode sample program: + * <http://cgit.freedesktop.org/libva/tree/test/encode/h264encode.c> +* Post-processing sample program: + * <http://cgit.freedesktop.org/libva/tree/test/putsurface/putsurface.c> + +### Architecture + +[[!img Linux_vaAPI.gif] + + +### Contact + +Jonathan Bian ([[jonathan.bian@intel.com|mailto:jonathan.bian@intel.com]]); Austin Yuan ([[shengquan.yuan@intel.com|mailto:shengquan.yuan@intel.com]]) diff --git a/Software/vaapi/Linux_vaAPI.gif b/Software/vaapi/Linux_vaAPI.gif Binary files differnew file mode 100644 index 00000000..a01b7f93 --- /dev/null +++ b/Software/vaapi/Linux_vaAPI.gif diff --git a/Software/vaapi/libva-arch.gif b/Software/vaapi/libva-arch.gif Binary files differnew file mode 100644 index 00000000..e2b10787 --- /dev/null +++ b/Software/vaapi/libva-arch.gif diff --git a/Software/waimea.mdwn b/Software/waimea.mdwn new file mode 100644 index 00000000..596ce0b0 --- /dev/null +++ b/Software/waimea.mdwn @@ -0,0 +1,22 @@ +## Waimea + +Waimea is a highly customizable window manager for the X Window system conforming to the latest EWMH specification. Waimea supports multiple virtual desktops and by using the cairo graphics library for all rendering, waimea provides a modern vector-based style engine that takes advantage of display hardware acceleration when available (through the X Render Extension). + + +### Screenshots +[[!table header="no" class="mointable" data=""" + [[[[!img http:/~davidr/screenshots/waimea-1.png]|http:/~davidr/screenshots/waimea-1.png]] | [[[[!img http:/~davidr/screenshots/waimea-2.png]|http:/~davidr/screenshots/waimea-2.png]] | [[[[!img http:/~davidr/screenshots/waimea-3.png]|http:/~davidr/screenshots/waimea-3.png]] +"""]] + + +### CVS Access + + $ cvs -d :pserver:anoncvs@cvs.waimea.org:/cvs/waimea login + CVS password: <hit return> + $ cvs -d :pserver:anoncvs@cvs.waimea.org:/cvs/waimea co waimea + +### Mailing List + +The [[waimea mailing list|http://freedesktop.org/cgi-bin/mailman/listinfo/waimea]] is the place for discussion of the waimea window manager. + +-- [[DavidReveman]] - 12 May 2004 diff --git a/Software/wininfo.mdwn b/Software/wininfo.mdwn new file mode 100644 index 00000000..76a8a84f --- /dev/null +++ b/Software/wininfo.mdwn @@ -0,0 +1,29 @@ + + +## X Window Information + +X Window Information is a window information utility for developers of applications, toolkits, and window managers. X Window Information follows your pointer providing information about the windows below. Information presented includes: + + * A detailed description of the window hierarchy below the pointer. + * Parsed interpretations of standard properties from both the application window and the window manager. + * Information about X server resources used by the application. +X Window Information requires Gtk+-2 and an X server supporting the X-Resource extension. + + +### CVS + +The CVS (see [[GettingInvolved|GettingInvolved]]) module for this software is "xapps/wininfo". To view the source online visit the [[ViewCVS page for this module|http://cvs.freedesktop.org/xapps/wininfo/]]. + + +### Authors + +X Window Information was written by Billy Biggs. + + +### Download + + * [[wininfo-0.7.tar.gz|http://www.freedesktop.org/software/wininfo/wininfo-0.7.tar.gz]]: X Window Information 0.7 + * [[wininfo-0.6.tar.gz|http://www.freedesktop.org/software/wininfo/wininfo-0.6.tar.gz]]: X Window Information 0.6 + * [[wininfo-0.5.tar.gz|http://www.freedesktop.org/software/wininfo/wininfo-0.5.tar.gz]]: X Window Information 0.5 + + diff --git a/Software/wmctrl.mdwn b/Software/wmctrl.mdwn new file mode 100644 index 00000000..e74bd7b7 --- /dev/null +++ b/Software/wmctrl.mdwn @@ -0,0 +1,361 @@ + + +# wmctrl + +From the [[wmctrl homepage|http://tripie.sweb.cz/utils/wmctrl/]]: + + * The wmctrl program is a UNIX/Linux command line tool to interact with an EWMH/NetWM compatible X Window Manager. The tool provides command line access to almost all the features defined in the EWMH specification. It can be used, for example, to obtain information about the window manager, to get a detailed list of desktops and managed windows, to switch and resize desktops, to make windows full-screen, always-above or sticky, and to activate, close, move, resize, maximize and minimize them. The command line access to these window management functions makes it easy to automate and execute them from any application that is able to run a command in response to an event. + +## Installing wmctrl + +A source tarball is available on the homepage; alternately, wmctrl is available from the [[RPMforge|http://rpmforge.net]] repository for Red Hat Linux and clones, or as part of the [[Debian|http://packages.debian.org/search?searchon=names&exact=1&suite=all§ion=all&keywords=wmctrl]] distribution. + + +## Additional documentation + +From the [[Spiral of Hope|http://spiralofhope.wordpress.com/2010/02/03/wmctrl-user-documentation/]] blog: + +wmctrl is one of very few programs which give control over your various windows within X. kde (with a GUI) and openbox (via rc.xml) have a way, and some other applications include Devil’s Pie, and some tools which come with X; xdpyinfo; xprop; xlsclients; xlsatoms; and xwininfo. Please let me know if you find any other interesting tools. + +Notice that in this list there are two third-party programs. Two. Of all of these, wmctrl seems to be the only tool which can actually do things to an existing window from the commandline. It was last updated in 2005. Seriously, we all use X daily but the tools are .. I don’t even have the words; welcome to the world of Linux. + +I’m not even going to go into the rant of users needing creating the documentation for the software they use. I’ve already covered that in my previous post. + +1. Introduction 2. Show information about the window manager and about the environment. 3. List windows managed by the window manager. 4. List desktops. 5. Switch to the specified desktop. 6. Activate a window. 7. Close the window gracefully. 8. Move the window to the current desktop and activate it. 9. Move the window to the specified desktop. 10. Resize and move the window around the desktop. 11. Change the state of the window. 12. Set the long title of the window. 13. Set the short title of the window. 14. Set both the long and short title of the window. 15. Activate or deactivate the window manager’s “showing the desktop” mode. 16. Change the viewport for the current desktop. 17. Change the number of desktops. 18. Change the geometry of all desktops. 19. Print help. 20. Options and misc. + + * 20.1 Interpret <WIN> as a numerical window ID. + * 20.2 Include PIDs in the window list. + * 20.3 Include geometry in the window list. + * 20.4 Include WM_CLASS in the window list or interpret <WIN> as the WM_CLASS name. + * 20.5 Override auto-detection and force UTF-8 mode. + * 20.6 Match the full window title and be case-sensitive + * 20.7 Be verbose. + * 20.8 Use a workaround. + * 20.9 -r + * 20.9.1 acting on a mouse-selected window + * 20.9.2 acting on the current window +21. real-world examples + + * 21.1 force window dimensions when launching an app + +### Introduction + +Sometime in 2007 I did a lot of work to figure wmctrl out. I essentially cleaned up its man page and created examples. I also came up with quite a number of questions along the way. Just the other day I was prompted to find those old notes and post them. I intended to get wmctrl and re-test things, but I have issues compiling it, probably because of my 64bit awesomeness and newer x libraries. .. and that damned type declaration. I don’t feel like hacking around in the wmctrl source code (right now?) or getting help for it, but I’ll get those notes for you anyway. The notes ought to still be good since the “latest” wmctrl version has not changed. However, the transition from one format to another might mean there are odd mistakes (missing spaces, incorrect characters) so please let me know if you have any issues or you’d like an update. This is probably the best piece of documentation on wmctrl and I demand perfection out of my docs. I’m the kind of guy who will put two spaces after a period in HTML (where the second is discarded). + +There are two reasons I was hesitant to just copy-and-paste my notes. One is that I intended to put them up on my CMS when it got built. The other is that I really wanted to re-test everything and provide even better examples. I’ve learned in the few years that I’ve played with wmctrl, and I’m positive I could build some cool scripts to really help people out. But until things come together, I suppose this’ll get trapped in a blog post. + +Blogs are SO inappropriate for resources like this which ought to be kept up-to-date. Wikis ftw. + +Show information about the window manager and about the environment. + + * wmctrl -m Name: Blackbox Class: N/A PID: N/A Window manager's "showing the desktop" mode: N/A +List windows managed by the window manager. + + * wmctrl -l 0x0080006a -1 localhost panel 0x0180007c 0 localhost Mozilla Firefox 0x02600007 3 localhost user@localhost: /home/user - Shell - Konsole 0x00600011 1 localhost KTorrent 0x02200007 0 localhost user@localhost: /home/user - Shell - Konsole 1 2 3 4 +The columns: + +1. The window ID. This is used for the -i switch. 2. The desktop ID. It begins counting at 0. -1 means that window is on all desktops. Used with -d and more. 3. The client machine 4. The name (long title) of the window. Used with -r mostly, and can be renamed with -N and -T. + +List desktops. + +List desktops. The current desktop is marked with an asterisk. + + * wmctrl -d 0 * DG: 1920x1200 VP: 0,0 WA: 0,0 1920x1200 1 - DG: 1920x1200 VP: N/A WA: 0,0 1920x1200 2 - DG: 1920x1200 VP: N/A WA: 0,0 1920x1200 3 - DG: 1920x1200 VP: N/A WA: 0,0 1920x1200 1 2 3 4 5 +The columns + +1. the desktop number. It begins counting at 0. 2. ‘*’ means it’s the current desktop 3. geometry 4. viewport 5. workarea 6. TODO: title — the man page describes this, but it’s missing from the command. File a bug report. + +Switch to the specified desktop. + + * # Create two desktops: wmctrl -n 1 # Switch to desktop 1 wmctrl -s 1 +notes + +* The programmer starts counting at 0. So 1 means the second desktop. * Your window manager must be configured to provide multiple desktops for this to mean anything. + +Activate a window. + +Activate the window by switching to its desktop and raising it. + + * # Create two desktops: wmctrl -n 1 # Switch to desktop 1: wmctrl -s 0 # Move the window to another desktop: wmctrl -r "KTorrent" -t 1 # Activate the window by switching to its desktop and raising it: wmctrl -a "KTorrent" +notes + +* TODO: With a tray-enabled application like KTorrent, activating it while it’s minimized as a tray icon is a Bad Idea and won’t display it properly. You’d have to ‘restore’ it from its tray state – by right-clicking its tray icon and selecting ‘restore’. Explore a wmctrl-only example. + +Close the window gracefully. + + * wmctrl -c -r "KTorrent" +notes + +* TODO: With a tray-enabled application like KTorrent, closing it will minimize it to the tray. If it’s already in the tray, then -c won’t do anything. wmctrl doesn’t have an alternate close or a ‘kill’ command for this case. Request this feature. * Does not work with mousepad. + +Move the window to the current desktop and activate it. + + * # Create two desktops: wmctrl -n 1 # Switch to desktop 1: wmctrl -s 0 # Move the window to another desktop: wmctrl -r "KTorrent" -t 1 # Switch to that window's desktop and activate that window: wmctrl -R "KTorrent" +notes + +* With a tray-enabled application like KTorrent, activating it while it’s minimized as a tray icon is a Bad Idea and won’t display it properly. You’d have to ‘restore’ it from its tray state – by right-clicking its tray icon and selecting ‘restore’. + +Move the window to the specified desktop. + + * # Create two desktops: wmctrl -n 1 # Switch to desktop 1: wmctrl -s 0 # Move the window to another desktop: wmctrl -r "KTorrent" -t 1 +notes + +* Tray-enabled applications like KTorrent won’t go anywhere if they’re minimized to the tray. + +Resize and move the window around the desktop. + + * wmctrl -r "KTorrent" -e 1,0,0,800,600 + * 1 2 3 4 5 +This example will move the window to the top-left of the screen (0,0) and resize it to 800×600 pixels. The five options are: “gravity,X,Y,width,height”: + +1. gravity — I’m not sure what this + + * 0 means ‘default’ and the coordinates of 0,0 will move the window too high up. + * 1 seems to look good for me. +2. X — The X coordinates. How far from the left the window will begin. Use -1 to leave this value as-is. 3. Y — The Y coordinates. How far from the top the window will begin. Use -1 to leave this value as-is. 4. width — The new window width in pixels Use -1 to leave this value as-is. 5. height — The new window hight in pixels. Use -1 to leave this value as-is. + +notes + +* “gravity,X,Y,width,height” follows the EWMH specification * width and height are NOT like using the mouse to resize a window. With KTorrent, some of the elements are ‘chopped off’ because of the resize. A slight adjustment using the mouse corrects this. * Tray-enabled applications like KTorrent won’t go anywhere or do anything if they’re minimized to the tray. + +The EWMH specification describe ‘gravity’ thusly: + + * win_gravity: placed at the reference point [[StaticGravity|StaticGravity]] the left top corner of the client window [[NorthWestGravity|NorthWestGravity]] the left top corner of the frame window [[NorthGravity|NorthGravity]] the center of the frame window's top side [[NorthEastGravity|NorthEastGravity]] the right top corner of the frame window [[EastGravity|EastGravity]] the center of the frame window's right side [[SouthEastGravity|SouthEastGravity]] the right bottom corner of the frame window [[SouthGravity|SouthGravity]] the center of the frame window's bottom side [[SouthWestGravity|SouthWestGravity]] the left bottom corner of the frame window [[WestGravity|WestGravity]] the center of the frame window's left side [[CenterGravity|CenterGravity]] the center of the frame window +But wmctrl doesn’t seem to respect these. It expects an integer. + +Change the state of the window. + +Change the state of the window. Using this option it’s possible for example to make the window maximized, minimized or fullscreen. + +The EWMH specification defines a _NET_WM_STATE request. wmctrl supports these properties: + +* modal — doesn’t seem to do anything, but I don’t really understand it anyway. * sticky — doesn’t work * maximized_vert — works * maximized_horz — works * shaded — works * skip_taskbar — works, but I can’t add it back. =/ * skip_pager — works * hidden — does not work, and really shouldn’t since the ‘minimize’ action would be responsible for setting this. Except wmctrl doesn’t have that. =/ * fullscreen — works. Removes the window title and border and forces fullscreen. + + * 1.0.7 fullscreen issue (see below) +* above — works * below — works * TODO: demands_attention — this is defined in the EWMH specs but was not listed in the wmctrl manual and does not appear to be supported. Request it. + +Examples: + + * wmctrl -r "KTorrent" -b add,shaded wmctrl -r "KTorrent" -b remove,shaded wmctrl -r "KTorrent" -b toggle,shaded +Multiple commands at once are done like this: + + * wmctrl -r "KTorrent" -b toggle,shaded,maximized_horz +Set the long title of the window. + +Set the name (long title) of the window. + + * wmctrl -r "KTorrent" -N "something" wmctrl -r "something" -N "KTorrent" +notes + +* Changing it back doesn’t seem to work. * Warning: This influences the use of the -r switch! * This is great for testing on an xterm shell if your environment automatically changes the title for you. Then you can just change directories to get things restored nicely. * For KTorrent after the first time I use this wmctrl feature I have to minimize it to the tray and restore it to view the change. + +Their example shows ‘zenity’ but I prefer kdialog. In a terminal emulator window, do: + + * title=`kdialog --title "Change window title" \ + * --inputbox "New window title"`; \ wmctrl -r :SELECT: -T "$title" +complex stuff + +It would be nice if I could have regular expressions which could match a title. I can partially understand how it could be done, but I don’t want to bother implementing the feature myself. =/ Some nonsense like this: + + * wmtrl -r `wmtrl -l|grep title|othergrep <first 10 characters>` -N "new title" +Where the othergrep thing matches the 10 characters at the beginning of each line. I don’t know how to do that though. Something like (<sup>……….) or (</sup>.{10}) I think. + +Set the short title of the window. + +Set the icon name (short title) of the window. + + * wmctrl -r "KTorrent" -I "string" +notes + +* See -N for more info. * I’m not sure what this is supposed to do. + +Set both the long and short title of the window. + + * wmctrl -r "KTorrent" -T "string" +notes + +* See -N for more info. * I can’t change the title back. This is the same problem as -N. + +Activate or deactivate the window manager’s “showing the desktop” mode. + +Activate or deactivate window manager’s “showing the desktop” mode. Many window managers do not implement this mode. + + * wmctrl -k on wmctrl -k off +notes + +* doesn’t work for me. + +Change the viewport for the current desktop. + +Change the viewport for the current desktop. The X and Y values are separated with a comma. They define the top left corner of the viewport. The window manager may ignore the request. + + * wmctrl -o 1024,768 +notes + +* This is ignored. + +Change the number of desktops. + +Change number of desktops. The window manager may ignore the request. + +Learn how many desktops you have: + + * $ wmctrl -d 0 * DG: 1920x1200 VP: 0,0 WA: 0,0 1920x1200 1 - DG: 1920x1200 VP: N/A WA: 0,0 1920x1200 2 - DG: 1920x1200 VP: N/A WA: 0,0 1920x1200 3 - DG: 1920x1200 VP: N/A WA: 0,0 1920x1200 # Create two desktops: wmctrl -n 1 +Now check again: + + * $ wmctrl -d 0 * DG: 1920x1200 VP: 0,0 WA: 0,0 1920x1200 1 - DG: 1920x1200 VP: N/A WA: 0,0 1920x1200 +notes + +* This programmer begins counting at 0. So ‘1′ means ‘2 desktops’ * Blackbox 0.70.1 and bbkeys 0.9.0 won’t really honour this. It’ll set it so that -d displays the ‘correct’ number of desktops, but my hotkeys to change desktops will still work. So it looks like bbkeys doesn’t respect wmctrl’s setting or Blackbox isn’t honouring wmctrl’s setting. + +Change the geometry of all desktops. + +Change geometry (common size) of all desktops. The window manager may ignore the request. + + * wmctrl -g 1024,768 +notes + +* Blackbox ignores this request. + +Print help. + + * wmctrl -h +(basically prints the man page) + +Options and misc. + + * --version +Interpret <WIN> as a numerical window ID. + +The -i option may be used to interpret the argument as a numerical window ID + + * $wmctrl -l 0x00600056 -1 localhost panel 0x02000143 0 localhost Mozilla Firefox 0x00400007 0 localhost user@localhost: /home/user - Shell - Konsole 0x00e00011 0 localhost KTorrent wmctrl -i 0x00e00011 -b toggle,shaded +notes + +* This is an alternate to using -r. * Defaults to use a decimal number. * If it starts with “0x”, then it’s assumed to be a hexadecimal number. * TODO: <WIN> as a numerical window ID doesn’t seem to work consistently. Perhaps not all options support it or something crazy is going on. It used to work very well for me. Re-test. + +Include PIDs in the window list. + +Include PIDs in the window list. Very few X applications support this feature. + + * wmctrl -l -p 0x00600056 -1 4302 localhost panel 0x02000143 0 5964 localhost Mozilla Firefox 0x00400007 0 8639 localhost user@localhost: /home/user - Shell - Konsole 0x00e00011 0 8706 localhost KTorrent +notes + +* blackbox supports this. =) + +Include geometry in the window list. + + * wmctrl -l -G 0x00600056 -1 0 1174 1920 26 localhost panel 0x02000143 0 649 25 1285 1147 localhost Mozilla Firefox 0x00400007 0 43 59 1092 481 localhost user@localhost: /home/user - Shell - Konsole 0x00e00011 0 51 653 904 509 localhost KTorrent +Include WM_CLASS in the window list or interpret <WIN> as the WM_CLASS name. + + * wmctrl -l -x 0x00600056 -1 panel.fbpanel localhost panel 0x02000143 0 Gecko.Mozilla-firefox-bin localhost Mozilla Firefox 0x00400007 0 Qt-subapplication. localhost user@localhost: /home/user - Shell - Konsole 0x00e00011 0 ktorrent.Ktorrent localhost KTorrent +notes + +* TODO: describe interpreting <WIN> as the WM_CLASS name. Useful for: -a, -c, -R and -r. + +Override auto-detection and force UTF-8 mode. + + * wmctrl -u (other switches) +Match the full window title and be case-sensitive + +Modifies the behavior of the window title matching algorithm. It will match only the full window title instead of a substring, when this option is used. Furthermore it makes the matching case sensitive. + + * wmctrl -F (other switches) +Be verbose. + +Be verbose. Useful for debugging. + + * wmctrl -l 0x00600056 -1 localhost panel 0x02000143 0 localhost Mozilla Firefox 0x00400007 0 localhost user@localhost: /home/user - Shell - Konsole 0x00e00011 0 localhost KTorrent wmctrl -l -v envir_utf8: 1 0x00600056 -1 localhost panel 0x02000143 0 localhost Mozilla Firefox Invalid type of WM_NAME property. 0x00400007 0 localhost user@localhost: /home/user - Shell - Konsole Invalid type of WM_NAME property. 0x00e00011 0 localhost KTorrent +Use a workaround. + +Use a workaround. The option may appear multiple times + + * wmctrl -w DESKTOP_TITLES_INVALID_UTF8 (other switches) +list of options as of 1.07 + +* DESKTOP_TITLES_INVALID_UTF8 — Print non-ASCII desktop titles correctly when using Window Maker. + +-r + +wmctrl -r is used to specify the window name (long title) to act on. It is used for a number of features: + +* Move the window to the specified desktop. * Resize and move the window around the desktop. * Change the state of the window. * Set the long title of the window. * Set the short title of the window. * Set both the long and short title of the window. + +notes; + +* It’s interpreted as a string. * It’s matched against the window name (long title) * Only the first matching window is used. * The matching isn’t case sensitive * The string may appear in any position of the title. * If you don’t want to use the name of the window, then try the -i switch. + +acting on a mouse-selected window + +Select the window by clicking on it. + + * wmctrl -b toggle,shaded -r :SELECT: +acting on the current window + +Use the currently active window for the action. + + * wmctrl -b toggle,shaded -r :ACTIVE: +real-world examples + +force window dimensions when launching an app + +A bbkeys hotkey can be set up to use xtoolwait and wmctrl to force a specific size. If a second occurrence is launched, I can relocate that one and resize it. + + * [Execute] (Mod1-Control-F) {xtoolwait yourapp & wmpid=$! && wait $wmpid && wmctrl -F -r "yourapp title" -e 1,0,0,800,1148 && wmctrl -F -r "yourapp other title" -e 1,800,0,800,1148} +It’s not hard to have this as a simple script like this: + + * xtoolwait yourapp & wmpid=$! wait $wmpid wmctrl -F -r "yourapp title" -e 1,0,0,800,1148 +I’d bet that anyone decent with bash could whip up something that’s nice and reusable too. (TODO) + +Also, I’m going to post a user addition here. I’m unable to do any real testing on it without wmctrl working. + + * wmctrl -ir `wmctrl -lx | grep Pidgin.Pidgin | cut -d" " -f1` -e 0,1200,0,-1,-1 +I also just bumped into some patches for wmctrl. I haven’t read any further and haven’t tested them out. + +* Removing decorations in Metacity * Move and Hide + +Fullscreen issue + +Proof that wmctrl usually works + +(Blackbox 0.70.1) + +1. Start xine windowed + + * xine dvd:// +2. alt-tab back to your term + +3. Prove that wmctrl can communicate to xine and fullscreen works: + + * wmctrl -r "xine" -b toggle,fullscreen +(fullscreen now) + +4. alt-tab back to your term (you might need to do it twice) + +5. Prove that wmctrl can remove fullscreen: + + * wmctrl -r "xine" -b toggle,fullscreen +(windowed now) + +6. Another proof: + + * wmctrl -r "xine" -b toggle,fullscreen +(fullscreen now) + + * wmctrl -r "xine" -b remove,fullscreen +(windowed now) + +Proof of an issue when the app starts fullscreen + +1. Start xine fullscreen + + * xine -f dvd:// +2. Now alt-tab back out to your term. You might have to click on the xine window for alt-tab to work. + +3. try to remove fullscreen + + * wmctrl -r "xine" -b remove,fullscreen +This does not do anything. + + * wmctrl -r "xine" -b toggle,fullscreen +This does not do anything. diff --git a/Software/xdg-user-dirs.mdwn b/Software/xdg-user-dirs.mdwn new file mode 100644 index 00000000..3529d08e --- /dev/null +++ b/Software/xdg-user-dirs.mdwn @@ -0,0 +1,84 @@ +## xdg-user-dirs + +xdg-user-dirs is a tool to help manage "well known" user directories like the desktop folder and the music folder. It also handles localization (i.e. translation) of the filenames. + +The way it works is that xdg-user-dirs-update is run very early in the login phase. This program reads a configuration file, and a set of default directories. It then creates localized versions of these directories in the users home directory and sets up a config file in $(XDG_CONFIG_HOME)/user-dirs.dirs (XDG_CONFIG_HOME defaults to ~/.config) that applications can read to find these directories. + + +## Settings + +Sysadmins can configure things by editing /etc/xdg/user-dirs.conf. At the moment there are only two settings, you can disable the whole thing, and you can specify the charset encoding used for filenames. They can also set or change the default directories and their initial values in /etc/xdg/user-dirs.defaults. + +$(XDG_CONFIG_HOME)/user-dirs.dirs specifies the current set of directories for the user. This file is in a shell format, so its easy to access from a shell script. This file can also be modified by users (manually or via applications) to change the directories used. Note: To disable a directory, point it to the homedir. If you delete it it will be recreated on the next login. + +Here is a shellscript example of how to find the desktop and the download directory: + + test -f ${XDG_CONFIG_HOME:-~/.config}/user-dirs.dirs && source ${XDG_CONFIG_HOME:-~/.config}/user-dirs.dirs + echo ${XDG_DESKTOP_DIR:-$HOME/Desktop} + echo ${XDG_DOWNLOAD_DIR:-$HOME} + +For application code the hope is that the various desktops will integrate this and have a nice API to find these directories. + + +## Translations + +Translations of xdg-user-dirs are now handled by the [[translation project|http://translationproject.org/]]. All translations should go through there. The merging from translation project to freedesktop.org is managed by Mikel Olasagasti. + + +## Code + +The [[Git|Infrastructure/git]] module for this code is [[xdg/xdg-user-dirs|http://cgit.freedesktop.org/xdg/xdg-user-dirs/]]. + + +### Download + +* <http://user-dirs.freedesktop.org/releases/xdg-user-dirs-0.14.tar.gz> + * New translations + * Use right permissions on ~/.config if created (0700) +* <http://user-dirs.freedesktop.org/releases/xdg-user-dirs-0.13.tar.gz> + * New translations + * Fix memory leak + * Generate <ChangeLog> from git +* <http://user-dirs.freedesktop.org/releases/xdg-user-dirs-0.12.tar.gz> + * New translations +* <http://user-dirs.freedesktop.org/releases/xdg-user-dirs-0.11.tar.gz> + * New translations + * Change "Download" to "Downloads" by default to match other names + * Fix bashism in xdg-user-dir +* <http://user-dirs.freedesktop.org/releases/xdg-user-dirs-0.10.tar.gz> + * New translations + * Update cut and paste code to handle oom and c++ +* <http://user-dirs.freedesktop.org/releases/xdg-user-dirs-0.9.tar.gz> + * New translations + * Relocatable + * Fix possible crash +* <http://user-dirs.freedesktop.org/releases/xdg-user-dirs-0.8.tar.gz> + * Remove accidental debug spew +* <http://user-dirs.freedesktop.org/releases/xdg-user-dirs-0.7.tar.gz> + * Don't recreate dirs set to $HOME +* <http://user-dirs.freedesktop.org/releases/xdg-user-dirs-0.6.tar.gz> + * New translations + * Fixed buggy printouts on --force + * Make xdg-user-dir-lookup.c #include:able + * Add xdg_user_dir_lookup_with_fallback to xdg-user-dir-lookup.c + * Add docs to xdg-user-dir-lookup.c +* <http://user-dirs.freedesktop.org/releases/xdg-user-dirs-0.5.tar.gz> + * New translations +* <http://user-dirs.freedesktop.org/releases/xdg-user-dirs-0.4.tar.gz> + * New translations + * fix build with external libintl +* <http://user-dirs.freedesktop.org/releases/xdg-user-dirs-0.3.tar.gz> + * Create ~/.config dir if needed +* <http://user-dirs.freedesktop.org/releases/xdg-user-dirs-0.2.tar.gz> + * Build fixes + * Update user-dirs.dirs atomically +* <http://user-dirs.freedesktop.org/releases/xdg-user-dirs-0.1.tar.gz> + * Add "Applications" to translations + * Support --dummy-output to write config file elsewhere on update + * Support --set to set a directory for the user + * Save the locale used on initial run and forced update + * This can be used to track changes in locale +* <http://user-dirs.freedesktop.org/releases/xdg-user-dirs-0.0.4.tar.gz> + * Added Projects/projects to list of translated keys + * Also support non-homedir-relative directories in user-dirs.dir. + * This isn't recommended (as it can cause problems with e.g. shared homedirs on multiple machines), but can be useful at times. diff --git a/Software/xfullscreen.mdwn b/Software/xfullscreen.mdwn new file mode 100644 index 00000000..53526d0e --- /dev/null +++ b/Software/xfullscreen.mdwn @@ -0,0 +1,15 @@ + + +## xfullscreen + +xfullscreen is a simple C module for applications or window managers to determine useful information for fullscreen modes, compensating for dual-head configurations (with or without XINERAMA support), as well as compensating for the current virtual desktop resolution using the XFree86-[[VidMode|VidMode]] extension. This module provides an easy way to determine the appropriate position and size of the fullscreen window as well as the current pixel aspect ratio. + + +### Authors + +xfullscreen was written by Billy Biggs and Per von Zweigbergk. + + +### Download + + * [[http:/software/xfullscreen/xfullscreen-0.2.tar.gz|http:/software/xfullscreen/xfullscreen-0.2.tar.gz]]: Initial freedesktop release. diff --git a/Software/xoo.mdwn b/Software/xoo.mdwn new file mode 100644 index 00000000..acfa67dc --- /dev/null +++ b/Software/xoo.mdwn @@ -0,0 +1,16 @@ + + +# Xoo + +Xoo is a GTK+ based graphical wrapper around a ‘windowed’ X Server. It is intended for embedded developers that want to simulate a target device (with an accurate display resolution and colour depth, working hardware buttons, and so on) on a desktop machine. + +The size of the embedded X server, and the image around it are themable by the user. The default theme is based on a Compaq iPaq 4700, and supports the hardware buttons. There is also a theme for the Nokia N800 Internet Tablet, and creating a new theme is as simple as writing a XML file. + +The embedded X server can either be Xnest (XFree86/X.org) or Xephyr (KDrive). The advantage of using Xephyr is that it supports the newer X extensions such as Render, RandR, Composite, and Damage; allowing you to test applications using these extensions even if your native X server doesn’t. Xoo can also send a signal to Xephyr so that it will highlight the region it is painting, to help debug redraw problems. + +Xoo is authored by Matthew Allum and Ross Burton. It is free software, available under the GPL. + + +## Download + +Xoo is maintained in Git, at [[http://cgit.freedesktop.org/xorg/app/xoo/|http://cgit.freedesktop.org/xorg/app/xoo/]]. diff --git a/Software/xprint.mdwn b/Software/xprint.mdwn new file mode 100644 index 00000000..9372d364 --- /dev/null +++ b/Software/xprint.mdwn @@ -0,0 +1,6 @@ + +Under construction. + +The main development site for Xprint is [[xprint.mozdev.org|http://xprint.mozdev.org/]]. + +You may want to read the [[Xprint FAQ|http://xprint.mozdev.org/docs/Xprint_FAQ.html]]. diff --git a/Software/xresponse.mdwn b/Software/xresponse.mdwn new file mode 100644 index 00000000..7528fbbb --- /dev/null +++ b/Software/xresponse.mdwn @@ -0,0 +1,14 @@ + + +# Xresponse + +Xresponse is a simple experimental command line tool for measuring UI response times to a mouse click event. It requires the Xtest, to ‘fake’ the mouse event, and XDamage, to report areas of the display that have changed. + +For more info see the included README file. + +Xresponse is authored by Matthew Allum and Ross Burton. It is free software, available under the GPL. + + +## Download + +Xoo is maintained in Git, at [[http://cgit.freedesktop.org/xorg/app/xresponse/|http://cgit.freedesktop.org/xorg/app/xresponse/]]. diff --git a/Software/xrestop.mdwn b/Software/xrestop.mdwn new file mode 100644 index 00000000..bc147ad6 --- /dev/null +++ b/Software/xrestop.mdwn @@ -0,0 +1,36 @@ + + +## xrestop + +Xrestop uses the X-Resource extension to provide 'top' like statistics of each connected X11 client's server side resource usage. It is intended as a developer tool to aid more efficient server resource usage and debug server side leakage. + +It should work with any server supporting the X-Resource extension, including the Xorg server and XFree86 4.3+. "`xdpyinfo | grep Resource`" should tell you if your server supports this extension. + + +### Screenshot + +[[!img xrestop.png] + + +### Note + +The XRes extension in XFree86 and older Xorg releases under estimates total pixmap memory used nor does it report win background pixmap usage. However it is still very useful for detecting server side leaks. See [[https://bugs.freedesktop.org/show_bug.cgi?id=2029|https://bugs.freedesktop.org/show_bug.cgi?id=2029]] for more info and a patch that improves things a little. + + +### Authors + +xrestop was written by Matthew Allum. + + +### Download + + * [[xrestop-0.1.tar.gz|http://downloads.yoctoproject.org/releases/xrestop/xrestop-0.1.tar.gz]]: Initial release + * [[xrestop-0.2.tar.gz|http://downloads.yoctoproject.org/releases/xrestop/xrestop-0.2.tar.gz]]: Adds missing man page, spec file + * [[xrestop-0.3.tar.gz|http://downloads.yoctoproject.org/releases/xrestop/xrestop-0.3.tar.gz]]: Tweaks for Solaris. Man page improvements. + * [[xrestop-0.4.tar.gz|http://downloads.yoctoproject.org/releases/xrestop/xrestop-0.4.tar.gz]]: Quit (q) key support, PID detect bug fixes + other minor tweaks + +### git Source Repos + + * [[http://cgit.freedesktop.org/xorg/app/xrestop|http://cgit.freedesktop.org/xorg/app/xrestop]] cgit web browsing + * [[git://anongit.freedesktop.org/xorg/app/xrestop|git://anongit.freedesktop.org/xorg/app/xrestop]] anonymous git cloning + * [[http://anongit.freedesktop.org/git/xorg/app/xrestop.git|http://anongit.freedesktop.org/git/xorg/app/xrestop.git]] anonymous git cloning via http
\ No newline at end of file diff --git a/Software/xrestop/xrestop.png b/Software/xrestop/xrestop.png Binary files differnew file mode 100644 index 00000000..dbb2bde5 --- /dev/null +++ b/Software/xrestop/xrestop.png diff --git a/Software/xsettings.mdwn b/Software/xsettings.mdwn new file mode 100644 index 00000000..f49c8252 --- /dev/null +++ b/Software/xsettings.mdwn @@ -0,0 +1,16 @@ + + +## xsettings + +xsettings contains a reference implementation of the [[xsettings specification|Specifications/xsettings-spec]]. + + +### CVS + +The CVS (see [[GettingInvolved|GettingInvolved]] for more details) module for this spec is "xsettings". + + +### Download + + * [[xsettings-0.2.tar.gz|http://www.freedesktop.org/software/xsettings/releases/xsettings-0.2.tar.gz]]: Cleanups. + * [[xsettings-0.1.tar.gz|http://www.freedesktop.org/software/xsettings/releases/xsettings-0.1.tar.gz]]: Initial release.
\ No newline at end of file diff --git a/Specifications.mdwn b/Specifications.mdwn new file mode 100644 index 00000000..172bd773 --- /dev/null +++ b/Specifications.mdwn @@ -0,0 +1,81 @@ + + +## These are not really standards + +Note: freedesktop.org is not a standards body. + + +#### Draft specifications that have pretty good de facto adoption/agreement: + + * [[DnD|http://www.newplanetsoftware.com/xdnd/]] is the drag-and-drop specification shared between [[GTK+|GTK+]] and [[Qt|Qt]]. A [[local copy|Specifications/XDND]] of the spec resides on the wiki. [[Work on revisions|Specifications/XDNDRevision]] are in progress. + * [[Window manager specification|Specifications/wm-spec]] standardizes extensions to the ICCCM between X desktops; we are also working to merge these extensions into the ICCCM itself as appropriate. + * The [[XEmbed|Specifications/xembed-spec]] proposed specification for inter-application embedding of controls. + * [[X clipboard explanation|Specifications/clipboards-spec]] is not a formal specification, but explains our consensus on how the X clipboard works. Qt and GTK+ both follow this document. + * [[UTF8_STRING|http://www.pps.jussieu.fr/~jch/software/UTF8_STRING]] selection format for interchange of UTF-8 data. + * [[The XML Bookmark Exchange Language|http://pyxml.sourceforge.net/topics/xbel/]], or XBEL, is an Internet "bookmarks" interchange format. + * [[Desktop Entry specification|Specifications/desktop-entry-spec]] describing information about an application such as the name, icon, and description. These files are used for application launchers and for creating menus of applications that can be launched. + * [[Menu specification|Specifications/menu-spec]] specifies how menus are built up from desktop entries. + * [[Desktop base directory spec|Specifications/basedir-spec]] details how desktops should locate files at runtime. + * The [[Icon Theme specification|Specifications/icon-theme-spec]] proposed specification for a common way to store icon themes. + * [[Free Media Player Specifications|Specifications/free-media-player-specs]] deal with standard ways to store and read metadata across players and media formats. + +#### Draft specifications that are new and not yet widely used, though they may be used by one or more desktops or desktop applications: + + * The [[Icon Naming specification|Specifications/icon-naming-spec]] proposed specification for a common way to name icons and their contexts in an icon theme. + * The [[shared MIME database|Specifications/shared-mime-info-spec]] contains common MIME types, descriptions, and rules for determining the types of files. + * The [[XSETTINGS|Specifications/xsettings-spec]] proposed specification for cross-toolkit configuration of user settings. + * The [[X Direct Save|Specifications/direct-save]] (XDS) protocol specifies how to save a file by dragging to a file manager window. + * The [[System tray protocol|Specifications/systemtray-spec]] proposed specification for a "notification area" feature. [[Notes from the XDevConf meeting|Specifications/SystrayAndAppletsMeeting]]. + * The [[Recent File|Specifications/recent-file-spec]] specification proposed specification for storing lists of recently used files. + * The [[Thumbnail|http://triq.net/~jens/thumbnail-spec/index.html]] management specification proposed specification for storing file thumbnails ([[copy available here|http://people.freedesktop.org/~vuntz/thumbnail-spec-cache/]]). + * Proposal for an [[extension to the ICCCM selections mechanism|Specifications/clipboards-extension-spec]] allowing xclipboard-like tools to limit the amount of transferred data. + * The [[startup-notification-spec|Specifications/startup-notification-spec]] describes a mechanism to allow desktop environments to track application startup, to provide user feedback and other features. + * The [[Cursor Conventions specification|Specifications/cursor-spec]] is a draft specification that seeks to standardize usage and names for mouse cursors. + * The [[File URI specification|Specifications/file-uri-spec]] defines how to interpret [[file://|file://]] URIs, as used for drag and drop and other desktop uses. + * The [[Clipboard manager specification|Specifications/clipboard-manager-spec]] describes a way for a clipboard manager to store clipboard data when applications quit. + * The [[Trash specification|Specifications/trash-spec]] provides a common way in which all "Trash can" implementations should store, list, and undelete trashed files. + * The [[Autostart specification|Specifications/autostart-spec]] describes how applications can be started automatically after the user has logged in and how media can request a specific application to be executed or a specific file on the media to be opened after the media has been mounted. + * The [[GHNS and DXS specs|http://ghns.freedesktop.org/spec/]] describe a collaborative data exchange platform based on the HTTP protocol and web service interaction. + * [[ICC Profiles in X Specification|Specifications/icc_profiles_in_x_spec]] + * The [[Open Collaboration Services|Specifications/open-collaboration-services]] specification describes an API to integrate community web sites with the desktop. + * The [[DesktopCouch|Specifications/desktopcouch]] specification describes record formats for integrating [[CouchDB|http://couchdb.apache.org]] in the desktop, already being used by some applications, like Evolution, Tomboy and Firefox + * [[Sound Theme Spec|Specifications/sound-theme-spec]] is a specification proposal for sound theme and sound naming. + * The [[Help Specification|Specifications/help-spec]] specifies a standard location and URI scheme of installed help documents. + * [[File Manager D-Bus Interface|Specifications/file-manager-interface]], a common way to interact with the desktop's file manager. + * The [[OpenRaster specification|Specifications/OpenRaster]] describes an open exchange format for layered raster-based graphics. +If you feel any of these specs should be moved among the "standard", "de facto", and "proposed" categories, please let us know on [[xdg-list@lists.freedesktop.org|mailto:xdg-list@lists.freedesktop.org]]. + + +#### Proposed X extensions: + + * [[X Fixes Extension|Software/FixesExt]] is a draft specification for changes in how the device independent parts of the X server works. + * [[X Damage Extension|Software/XDamage]] is a draft specification for an extension to allow applications to track modified areas within a window or pixmap. + * [[X Composite Extension|Software/CompositeExt]] is a draft specification for an extension that moves sub-trees of the window hierarchy to off-screen memory, permitting access to and manipulation of those bits, including constructing the parent window contents programmatically rather than automatically. + * [[X Event Interception Extension|Software/XEvIE]] is a draft specification for an extension to allow a client program to intercept all input events. ([[link|http://www.freedesktop.org/~ajax/xevie/xevie.html]]) +The above four extensions are deployed as of Xorg 6.8. Damage and Fixes are enabled by default, while Composite and XEvIE must be enabled by the user at runtime. + + +#### Specifications currently in the planning/requirements-gathering stages: + + * [[Shared File Metadata Spec|Specifications/shared-filemetadata-spec]] (reading/writing/searching file based metadata) + * [[MIME run actions|Specifications/mime-actions-spec]] (deciding which application should be used to open a file). + * [[Shared configuration system|Specifications/config-spec]] (a desktop-neutral replacement for gconf and similar). + * [[Shared default keyboard shortcuts|Specifications/default-keys-spec]] (every application running should use the same keys for _Save_, _Quit_, etc). + * [[Audio files meta data|Specifications/audio-metadata-spec]] (apps that deal with audio files should use same abbreviations when dealing with the meta data) + * [[Bidirectional scripts|Specifications/bidi-spec]] (support for bidirectional scripts like Arabic and Hebrew in desktop software) + * [[Proposed Help Spec|Specifications/help-system]] (The beginnings of a specification for how to find help files.) + * [[Shortcut to a database connection|Specifications/db-shortcut-spec]] (The proposal of a specification for how to store information about remote database connections; currently used by Kexi: www.kexi-project.org) + * [[Desktop configuration Spec|Specifications/desktop-config-spec]] (A D-BUS protocol and schema specification for desktop configuration) + * [[Desktop Bookmark Spec|Specifications/desktop-bookmark-spec]] (A storage format for bookmarks used by file selectors and applications; it should supercede the [[Recent File|Specifications/recent-file-spec]] specification; currently used by GTK) + * [[Desktop Language Checking Spec|Specifications/desktop-language-checking-spec]] (a spec for spell and grammar checking) + * [[MPRIS Media player remote interfacing specification|Specifications/mpris-interfacing-specification]] A media player DBus interfacing specification + * [[Composite retained drawing protocol|Specifications/Composite-retained-drawing]] + * [[OpenICC Directory Proposal|http://www.oyranos.com/wiki/index.php?title=OpenIccDirectoryProposal]] for placing and finding colour related files in a system + * The [[Application Package Specification|ApplicationPackageSpec]] is designed to provide a desktop neutral way to package an application. Installation is not required. + * [[DBPC - DBus for process control|Specifications/DBPC]] is layer above DBUS which define a standard set of objects, interfaces and methods for use in process control. It will provide a common standard for industrial communication, especially between HMI, SCADA and field electronic equipement. + * [[Secret Storage Spec|Specifications/secret-storage-spec]] is a draft of an API for securely storing secrets using a D-Bus service. + * [[StatusNotifierIcon|Specifications/StatusNotifierIcon]] - a proposal for cleaning up the notification area/panel. + +#### Retracted Specifications + + * The [[Desktop Color Scheme specification|Specifications/colorscheme-spec]] is a draft specification that defines names for colors to be used for rendering user interface elements. It also provides an algorithm for generating a matching set of colors from a single base color (**The colorscheme spec has been pulled on request of its authors**).
\ No newline at end of file diff --git a/Specifications/AddingMIMETutor.mdwn b/Specifications/AddingMIMETutor.mdwn new file mode 100644 index 00000000..400d9746 --- /dev/null +++ b/Specifications/AddingMIMETutor.mdwn @@ -0,0 +1,48 @@ + + +## Tutorial: adding MIME information to the database + +This tutorial is for application authors and users who want to extend the database. For example, the Gimp may wish to add: + +* **image/png** can be **edited** using the **Gimp**. +* **image/png** should be **described** in **English** as **"Portable Network Graphics file"**. +* Files whose **names** end in **.png** should have the type **image/png**. +Users should normally use a graphical editor application, such as [[MIME-Editor|http://rox.sourceforge.net/desktop/MIME-Editor]], to edit the database (although ideally no user-editing should be required at all). If you really want to do it manually, create a file called **$XDG_DATA_HOME/mime/packages/Override.xml** in the format described below. + +(see the [[Base Directory Specification|Specifications/basedir-spec]] for information about the XDG_ variables) + +When your application is installed, it should install a file with the application's name in **$XDG_DATA_DIRS/mime/packages**. For example, doing **./configure && make install** with Gimp should create **/usr/local/share/mime/packages/gimp.xml**. + +This file has the following format: + + <?xml version="1.0" encoding="UTF-8"?> + <mime-info xmlns="http://www.freedesktop.org/standards/shared-mime-info"> + <mime-type type="image/png"> + <comment xml:lang="en">PNG image</comment> + <comment xml:lang="af">png beeld</comment> + ... + <magic priority="50"> + <match type="string" value="\x89PNG" offset="0"/> + </magic> + <glob pattern="*.png"/> + </mime-type> + </mime-info> + +This provides a comment (in two languages), a rule to recognise PNG files by their contents, and a rule to recognise them by their names. You can provide information about several types in the single **gimp.xml** file. You do not need to provide any information which is also in the base package (in fact, all the information above is already present; this is just an example!). + +You can also add extra elements, provided they are namespaced to avoid conflicts. For example: + + <desktop:can-edit-with>gimp.desktop</desktop:can-edit-with> + +This indicates that the named desktop entry file describes an application that can edit **image/png** files. Note that the above is just an example; the desktop entry specification does not currently define this element. See the [[MIME actions specification|Specifications/mime-actions-spec]] for more details. + +Note also that information added to the database should be static ("gimp can edit PNG files"), **not** configuration ("gimp is the preferred editor for PNG files"). See the [[shared configuration system|Specifications/config-spec]] for storing configuration information. + +Once you have installed the **gimp.xml** file, run the **update-mime-database** command to rebuild the output files. This program checks that the syntax of your file is correct and merges the information in it with that in the other XML files in the **packages** directory. It then puts the rules for recognising files into one set of files, and the information about each type into other files (eg **$XDG_DATA_DIR/mime/image/png.xml**), where other programs can access it easily. + +When the Gimp is uninstalled, it should remove the **gimp.xml** file and run **update-mime-database** again to remove the information from the database. + + +## Submitting patches for the main package + +If you have added types that should go in the common freedesktop.org base list of types, you should create an enhancement request on [[the MIME bugtracker|https://bugs.freedesktop.org/buglist.cgi?product=shared-mime-info&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED]] following the instructions in the [[HACKING file|http://cgit.freedesktop.org/xdg/shared-mime-info/tree/HACKING]] (note that sending the created XML file will not be enough). diff --git a/Specifications/ClipboardExtensions.mdwn b/Specifications/ClipboardExtensions.mdwn new file mode 100644 index 00000000..6746eacb --- /dev/null +++ b/Specifications/ClipboardExtensions.mdwn @@ -0,0 +1,17 @@ + + +# Selection target _NET_MAX_SELECTION_SIZE + +When a client encounters target `_NET_MAX_SELECTION_SIZE` in `SelectionRequest` event, it should use its value as a limit for the following targets in the same request (i.e. the request should be of type `MULTIPLE`). The `_NET_MAX_SELECTION_SIZE` target should be always the first target in the `MULTIPLE` request. + +The target `_NET_MAX_SELECTION_SIZE` is a side-effect target, as described in ICCCM section 2.6.3. When handling this target, the matching property on the requestor window should be of type `XA_INTEGER`, format 32, with 2 elements. + +If the selection owner's connection to the X server is local, the first element is used as the limit, otherwise the second element is used as the limit. A local connection is identified by a value of `XDisplayString()` with the first character `':'`, for example, `":0.0"`. A value of -1 for either element means no limit. + +The value should limit the sum of the sizes in the request, not separately each of them. The client should reject subsequent targets if they would cause the total amount of data transferred for all targets to exceed the limit. Note that there is no requirement that if one target is rejected, all other targets will be rejected or all that subsequent targets will be rejected. + +Clients are not required to limit the data size precisely to the given value. If the computation of the data size would be expensive for the client, a certain reasonable inaccurancy is allowed. In other words, if the client for various reasons doesn't know exact size of the data to be transfered, it should try to estimate it, rather than transfering data with size that is possibly magnitudes larger. + +The intent of this target is to avoid unwanted large transfers, so it should be requsted only by xclipboard-like tools. They should use a request of type `MULTIPLE` with `_NET_MAX_SELECTION_SIZE` as the first target in the `MULTIPLE` request, with the requested target(s) after it. + +-- Main.[[BillSpitzak|BillSpitzak]] - 06 Jan 2004 (unchaged from .txt file except for formatting) diff --git a/Specifications/ClipboardsWiki.mdwn b/Specifications/ClipboardsWiki.mdwn new file mode 100644 index 00000000..c06f84f5 --- /dev/null +++ b/Specifications/ClipboardsWiki.mdwn @@ -0,0 +1,121 @@ + +Historically, X clients have not handled cut-and-paste in a consistent way, leading users to believe that X doesn't even have a working clipboard. This isn't really accurate; there is a conventional behavior, somewhat standardized in the ICCCM. But many apps don't follow the conventional behavior. + +X has a thing called "selections" which are just clipboards, essentially (implemented with an asynchronous protocol so you don't actually copy data to them). There are three standard selections defined in the ICCCM: `PRIMARY`, `SECONDARY`, and `CLIPBOARD`. + +The ICCCM defines these as follows: + +_"The selection named by the atom `PRIMARY` is used for all commands that take only a single argument and is the principal means of communication between clients that use the selection mechanism. + +The selection named by the atom `SECONDARY` is used: + + * As the second argument to commands taking two arguments (for + * example, "exchange primary and secondary selections") + * As a means of obtaining data when there is a primary selection and + * the user does not want to disturb it +The selection named by the atom `CLIPBOARD` is used to hold data that is being transferred between clients, that is, data that usually is being cut and then pasted or copied and then pasted."_ + +In addition, the ICCCM has a thing called "cut buffers" which most clients no longer support. + +There are two historical interpretations of the ICCCM: + + * 1 use `PRIMARY` for mouse selection, middle mouse button paste, and + * explicit cut/copy/paste menu items (Qt 2, GNU Emacs 20) +2 use `CLIPBOARD` for the Windows-style cut/copy/paste menu items; + + * use `PRIMARY` for the currently-selected text, even if it isn't explicitly copied, and for middle-mouse-click (Netscape, Mozilla, XEmacs, some GTK+ apps) +No one ever does anything interesting with `SECONDARY` as far as I can tell. + +The current consensus is that interpretation 2 is correct. Qt 3 and GNU Emacs 21 will use interpretation 2, changing the behavior of previous versions. + +The correct behavior can be summarized as follows: `CLIPBOARD` works just like the clipboard on Mac or Windows; it only changes on explicit cut/copy. `PRIMARY` is an "easter egg" for expert users, regular users can just ignore it; it's normally pastable only via middle-mouse-click. + +The rationale for this behavior is mostly that behavior 1 has a lot of problems, namely: + + * inconsistent with Mac/Windows + * confusingly, selecting anything overwrites the clipboard + * not efficient with a tool such as xclipboard + * you should be able to select text, then paste the clipboard + * over it, but that doesn't work if the selection and clipboard are the same + * the Copy menu item is useless and does nothing, + * which is confusing + * if you think of `PRIMARY` as the current selection, + * Cut doesn't make any sense since the selection simultaneously disappears and becomes the current selection +Application authors should follow the following guidelines to get correct behavior: + + * selecting but with no explicit copy should only set `PRIMARY`, + * never `CLIPBOARD` + * middle mouse button should paste `PRIMARY`, never `CLIPBOARD` + * explicit cut/copy commands (i.e. menu items, toolbar buttons) + * should always set `CLIPBOARD` to the currently-selected data (i.e. conceptually copy `PRIMARY` to `CLIPBOARD`) + * explicit paste commands should paste `CLIPBOARD`, not `PRIMARY` + * possibly contradicting the ICCCM, clients don't need to support + * `SECONDARY`, though if anyone can figure out what it's good for they should feel free to use it for that + * cut buffers are evil; they only support ASCII, they don't + * work with many clients, and they require data to be copied to the X server. Therefore clients should avoid using cut buffers and use only selections. +Apps that follow these guidelines give users a simple mental model to understand what's going on. `PRIMARY` is the current selection. Middle button pastes the current selection. `CLIPBOARD` is just like on Mac/Windows. You don't have to know about `PRIMARY` if you're a newbie. + +I don't think there's a sane mental model if we collapse everything into `PRIMARY` and ignore clipboard, see rationale above. + +A remaining somewhat odd thing about X selections is that exiting the app you did a cut/copy from removes the cut/copied data from the clipboard, since the selection protocol is asynchronous and requires the source app to provide the data at paste time. The solution here would be a standardized protocol for a "clipboard daemon" so that apps could hand off their data to a daemon when they exit. Or alternatively, you can run an application such as xclipboard which constantly "harvests" clipboard selections. + +References: + + * the ICCCM, obviously + * [[http://freedesktop.org/~keithp/talks/selection.ps|http://freedesktop.org/~keithp/talks/selection.ps]] + * [[http://www.jwz.org/doc/x-cut-and-paste.html|http://www.jwz.org/doc/x-cut-and-paste.html]] +-- Main.[[BillSpitzak|BillSpitzak]] - 11 Dec 2003 (copied with cleanup changes *only* from clipboards.txt) + + + +--- + + + +--- + + + +Another interpretation becoming popular is to say the `PRIMARY` selection is really [[DragAndDrop|DragAndDrop]], with the advantage that you can rearrange windows and open/close them between the "drag" and the "drop". In fact this makes a lot of sense, and is even coded already in how XDnD interacts with older programs (drop will do a middle-mouse-click in older programs) + +-- Main.[[BillSpitzak|BillSpitzak]] - 11 Dec 2003 + + + +--- + + + +The problem of clipboard "volatility" is a little worse than is described above. The reasoning behind the asynchronous transfer protocol used by X cut-and-paste is that the source and destination apps will want to negotiate the "best" format that both sides can handle. The 1980s Macintosh model (IIRC) was that there was a single preferred format for each clipboard datatype that all applications that handled that datatype were expected to support. This enabled putting just one representation on the non-volatile clipboard. This is arguably the right thing for X to do also. It seems likely that UTF-8 is the preferred text format, PNG the preferred format for bitmap graphics, TTF for fonts. Other cases are harder to decide. Someone needs to standardize them :-). + +-- Main.[[BartMassey|BartMassey]] - 10 Feb 2005 + +The obvious way to standardize the X clipboard is to use standard internet MIME types, which seems to be the direction it is going. Most people agree that we need some sort of standardized clipboard manager. In order to hold data from closed applications, it will have to decide what data types to negotiate. Therefore, it makes sense for the clipboard manager specs to include management of the preferred clipboard data types. + +-- Main.[[JoeKrahn|JoeKrahn]] - 09 Dec 2010 + + + +--- + + + +--- + + + +X application copy/paste proposal for atom SECONDARY + +Extend default X copy paste functionality to include paste over highlight without breaking current mouse-highlight (copy) mouse middle-click (paste) methods. + +Practical use for the atom SECONDARY. If mouse-highlight (HL) data is different from contents of atom PRIMARY, duplicate atom PRIMARY into atom SECONDARY and put content of (HL) in atom PRIMARY. Then on (HL) middle-click if (HL) is same as atom PRIMARY contents paste data from atom SECONDARY. + +This keeps the existing behavior, implements additional features and is not difficult to implement. Since atom SECONDARY is mostly unused this would be a good use for it - IMO. + +-- [[FriscoRose|FriscoRose]] - 10 Nov 2005 + +I completely agree here. Middle-clicking into highlighted text only makes sense if it can automatically paste the previously highlighted text. However, it seems that many developers want to move away from the middle-click paste and just use the MS-Win/Mac-OSX approach of requiring keyboard input to copy/paste. + +IMHO, it makes sense to continue supporting middle-click pasting for those who find it useful, but it may also be useful to update the cut/paste standards such that those who don't want it can disable it. Perhaps there could be a formal Paste event, or just a WM-protocol hint that tells applications which mouse button represents a paste. + +-- Main.[[JoeKrahn|JoeKrahn]] - 09 Dec 2010 diff --git a/Specifications/Composite-retained-drawing.mdwn b/Specifications/Composite-retained-drawing.mdwn new file mode 100644 index 00000000..198fbead --- /dev/null +++ b/Specifications/Composite-retained-drawing.mdwn @@ -0,0 +1,153 @@ + +PDF available at: [[http://gitweb.beryl-project.org/?p=users/racarr/architecture/.git;a=blob_plain;f=cmrds.pdf;hb=HEAD|http://gitweb.beryl-project.org/?p=users/racarr/architecture/.git;a=blob_plain;f=cmrds.pdf;hb=HEAD]] + +Composite Manager Retained Drawing Protocol RFC + +Robert Carr + +02/28/07 + +Outline and justification: + +Results from development in the creation of 'first generation' mainstream composite window managers has outlined the need for several reconsiderations in regards to applications interacting and communicating with the composite manager. Currently code can interact with a composite manager in one of several fashions: + +1. Composite managers can expose a plugin interface enabling libraries functioning as plugins to implement new functionality for a composite manager. This is effective for many of the traditional window manager functionalities, but has several weaknesses. Slow code in the composite manager will make an entire system feel sluggish, and furthermore under existing and easily forseeable plugin architectures plugins such as the Thumbnail plugin of Beryl and Compiz waste an excessive amount of CPU even while not doing anything interesting. Furthermore applications requiring an excessive amount of user interaction are cumbersome and difficult to write, and attempts to do so often expose the problem of slow code in a composite manager making the entire system feel sluggish. Lastly applications requiring a great deal of interaction with other components of the desktop are not well suited to existing as a plugin for a compositor, while they still might find it useful to leverage some of the power of a compositor. +1. Composite managers can communicate with client applications through X window properties. This is a suitable way to store simple information and flags, but the use quickly breaks down when attempting to traffic large (things such as Pixmaps or a vertex array) amounts of information in a latency sensitive manner. +1. Composite managers can communicate with client applications through an interprocess communications protocol such as DBUS. This is a suitable way for triggering actions, and a sort of 'scripting' but suffers from similar issues to that of X properties in leveraging the compositor for producing rich client applications. +As a solution this document proposes the creation of a low level protocol used to leverage the composite manager for drawing purposes. Composite managers would expose a struct in shared memory where client applications could queue 'Requests' to specify specific drawing operations and state changes. The proposed protocol is lightweight and generic allowing for implementation in a multitude of composite managers while maintaining ABI compatibility. + +Structure of implementation and low level protocol description + +The protocol will be built upon Requests structured as following: + +1. An enumeration of named opcodes for each request. +1. For each opcode a structure representing any parameters or attributes which the client application must communicate to the compositor to complete the specific request +1. A structure representing an entire request containing the opcode, and a union of attribute structures for all opcodes. Furthermore the request structure will contain a pointer to the next and previous request. +Composite managers will expose a struct in shared memory (henceforth referred to as the transport) (TODO: Best method to establish initial communication?) containing: + +1. A doubly linked list of requests, client applications will add requests to the end of this list and the composite manager will clear requests from the list upon executing them. +1. A struct representing the last executed request and opcodes for any return information which this request may have generated. The return information will be a pointer to a struct made accessible of a type defined by the particular request. +1. A lock on the structure to prevent issues with multiple clients accessing the structure. Ideally clients will interact with the protocol through a higher level library. +Composite managers will be required to ensure that at each paint all requests are cleared EXCEPT in the case where a lock exists on the transport (Though adding a request will not neccesarily trigger a paint) (TODO: Damage attribute on transport/something?). Furthermore the composite manager will be required to guarantee that actions occur in the order they were added. (TODO: Client attribute to requests to enable sorting of requests when clients don't respect the lock?). Respect of the lock on the transport must be observed at the client level. + +Opcodes + +The first version of the CMRD protocol defines 13 opcodes. + +Opcode 0: + + * Name: [[CompositeManagerQueryProtocolVersionRequest|CompositeManagerQueryProtocolVersionRequest]] Attributes: None Return attributes: + * int major; int minor; Description and implementation notes: Returns the major +and minor version of the implemented protocol. + +Opcode 1: + + * Name: [[CompositeManagerReadyRequest|CompositeManagerReadyRequest]] Attributes: None Return Attributes: + * int ready; Description and implementation notes: Indicates whether +the composite manager is ready and able to respond + +drawing requests. + +Opcode 2: + + * Name: [[CompositeManagerScreengrabLockExistsRequest|CompositeManagerScreengrabLockExistsRequest]] Attributes: TODO Return attributes: + * int exists; Description and implementation notes: The concept of a +'Screengrab Lock' is used to indicate whether a client is using the composite manager for a fullscreen and screengrabbing effect, where it would not be appropriate for other clients to do the same. An actual X grab may or may not be issued based on attributes. + +Opcode 3: + + * Name: [[CompositeManagerPushScreengrabLockRequest|CompositeManagerPushScreengrabLockRequest]] Attributes: TODO Return attributes: + * TODO Description and implementation notes: Pushes a +screengrab lock. + +Opcode 4: + + * Name: [[CompositeManagerPopScreengrabLockRequest|CompositeManagerPopScreengrabLockRequest]] Attributes: None Return attributes: None Description and implementation notes: Pops the active +screengrab lock. + +Opcode 5: + + * Name: [[CompositeManagerSetDrawingLevelRequest|CompositeManagerSetDrawingLevelRequest]] Attributes: + * Window level; int screen; Return attributes: None Description and implementation notes: Sets the current +drawing level, in that further drawing requests will be rendered at the same level as the 'Window level' attribute, or above all windows if 'Bool screen' is true. + +Opcode 6: + + * Name: [[CompositeManagerSetDamageResponseRequest|CompositeManagerSetDamageResponseRequest]] Attributes: + * int respond; Return attributes: None Description and implementation notes: Temporarily +toggles the composite manager from repainting damaged areas. + +Opcode 7: + + * Name: [[CompositeManagerSetActiveTextureFromWindowRequest|CompositeManagerSetActiveTextureFromWindowRequest]] Attributes: + * Window window; Return attributes: None Description and implementation notes: Creates a texture +from the CURRENT drawable of the window and uses it for future retained drawing operations. + +Opcode 8: + + * Name: [[CompositeManagerSetActiveTextureFromPixmapRequest|CompositeManagerSetActiveTextureFromPixmapRequest]] Attributes: + * Pixmap pixmap; Return attributes: None Description and implementation notes: BINDS a texture +from the passed pixmap and uses it for future retained drawing operations. + +Opcode 9: + + * Name: [[CompositeManagerSetRenderScreenOffscreenRequest|CompositeManagerSetRenderScreenOffscreenRequest]] Attributes: + * int offscreen Return attributes: None Description and implementation notes: Based on the +value of offscreen begin rendering the screen to an offscreen framebuffer object or GLXPBuffer (based on availability of FBO), and set the active texture to a texture generated from such rendering. + +Opcode 10: + + * Name: [[CompositeManagerSetCurrentVertexArrayRequest|CompositeManagerSetCurrentVertexArrayRequest]] Attributes: + * float * vertices; int nvertices; Return attributes: None Description and implementation notes: float * vertices +should be a 0 offset array of vertices in the format + + * x, y, z. This is used as the geometry for future drawn +objects. It is to be assumed that the vertices are in screen coordinates, with 0, 0 (x, y) being the TOP LEFT of the screen. + +Opcode 11: + + * Name: [[CompositeManagerSetCurrentTextureArrayRequest|CompositeManagerSetCurrentTextureArrayRequest]] Attributes: + * float * coords; int ncoords; Return attributes: None Description and implementation notes: Same format as +[[CompositeManagerSetCurrentVertexArray|CompositeManagerSetCurrentVertexArray]] without the z coordinate. This is used as the texture coordinates for future drawn objects. + +Opcode 12: + + * Name: [[CompositeManagerDrawRequest|CompositeManagerDrawRequest]] Attributes: None Return attributes: None Description and implementation notes: Enable the +current retained drawing texture, and render the geometry in the current vertex array with the texture coordinates in the current texture array. + +Opcode 13: + + * Name: [[CompositeManagerDamageScreenRequest|CompositeManagerDamageScreenRequest]] Attributes: None Return attributes: None Description and implementation notes: Force the +composite manager to redraw the screen. + +Example Usage + +Drawing a window thumbnail for Window id at 300, 300 on a quad with width and height 100. + +Requests: + +[[CompositeManagerSetDrawingLevelRequest|CompositeManagerSetDrawingLevelRequest]] ( Window level = 0, screen = TRUE) + +[[CompositeManagerSetActiveTextureFromWindowRequest|CompositeManagerSetActiveTextureFromWindowRequest]] ( Window id) + +[[CompositeManagerSetCurrentVertexArrayRequest|CompositeManagerSetCurrentVertexArrayRequest]] ( float * vertices = 300, 300, 0, 300, 400, 0, 400, 400, 0, 400, 300, 0 nvertices = 4) + +[[CompositeManagerSetCurrentTextureArrayRequest|CompositeManagerSetCurrentTextureArrayRequest]] ( float * coords = 0,0,0,1,1,1,1,0 ncoords = 4) + +[[CompositeManagerDrawRequest|CompositeManagerDrawRequest]] + +Drawing a thumbnail of what the screen would look like on a different viewport at 300, 300 on a quad with width and height 100. + +Requests: + +[[CompositeManagerSetRenderOffscreenRequest|CompositeManagerSetRenderOffscreenRequest]] offscreen = 1 + +<span style="display:none">Set X property such that the viewport will be moved to your desired viewport</span> + +[[CompositeManagerDamageScreenRequest|CompositeManagerDamageScreenRequest]] + +[[CompositeManagerSetCurrentVertexArrayRequest|CompositeManagerSetCurrentVertexArrayRequest]] ( float * vertices = 300, 300, 0, 300, 400, 0, 400, 400, 0, 400, 300, 0 nvertices = 4) + +[[CompositeManagerSetCurrentTextureArrayRequest|CompositeManagerSetCurrentTextureArrayRequest]] ( float * coords = 0,0,0,1,1,1,1,0 ncoords = 4) + +[[CompositeManagerDrawRequest|CompositeManagerDrawRequest]] diff --git a/Specifications/DBPC.mdwn b/Specifications/DBPC.mdwn new file mode 100644 index 00000000..0df73127 --- /dev/null +++ b/Specifications/DBPC.mdwn @@ -0,0 +1,133 @@ + +[[!img DBPC-logo-nb.png] + +Links [[!map pages="Specifications/DBPC/*"]] + +[[!toc 3]] + + +## Overview + +Since popularity of Linux operating system in industrial environment increase, needs for interoperability between Linux applications and industrial equipment come true. Actually most every Linux scada/HMI project reinvents the wheel for field communication, without interoperability. + +Mainly, DPBC (DBus for process control) is a standard abstraction layer between SCADA and field equipment. + +DBPC is based on D-Bus which is a message bus and activation system that is set to achieve deep penetration in Linux. + +DBPC define a standard set of objects, interfaces and methods for use in process control. It will provide a common standard for industrial communication, especially between HMI, SCADA and field electronic equipement. + + +## Participate + +If you have ideas you want to suggest but don't want to edit this main document, please go to the [[brainstorming Page|Specifications/DBPC/Discussion]]. + + +## Synoptic + +[[!img DBPC-Synoptic.png] + +Trivial diagrammatic description of DBPC architecture. + + +## Audience + + * Process control and automation engineer + * Linux user and open source programmer + * HMI and SCADA open source project + * Industrial embedded systems programmer + * Industrial equipment manufacturer + * Industrial computer manufacturer + +## Definitions +DBus +: D-Bus is an inter-process communication (IPC) mechanism implemented as a software data bus which permits communication between applications. Unless it is not a process field bus as used in factory floor, its core functionality can easily be apprehended in the same way by control engineer. For more detail about DBus and IPC see related IPC specification. + +DBPC +: DBPC is a layer above DBUS. It define a standard set of objects, interfaces and methods for use in process control, automation and domotic applications, to facilitate interoperability. Primary goal is defining a common communication language for real time communication of plant data between control devices from different manufacturers and SCADA, HMI, process control and open source applications. + +DBPC-server +: DBPC servers are services which provide common tags access trough DBus. Generally a DBPC server grants real time data access to one or more remote programmable logic controller. Most of time is done by pooling. Typically DBus servers represent a field bus protocol. (For example : ModbusTCP DBPC server, Profibus DBPC server). + +DBPC-client +: DBPC client are compliant application which access to tags in one or more DBPC-server. + +Tags +: Each datum made available by a DBPC server is called a tag. Tags correspond (roughly) to physical values, factory state, command signals, etc. A tag's value may be read or written by a DBPC client. + +Device +: From a DBPC point of view, devices are equipment or objects which may be controlled or monitored through a DBPC server. While the primary target of DBPC are industrial applications, DBPC servers may also be implemented for other types of "industiral" devices : HVAC, heating control, domotic, real time data producers, metéo stations, telescopes, multimedia equipment, IR remote controls, DCF clocks, robotics, USB gadgets, RFID readers, etc. + +PLC Programmable logical controller +: Programmable logic controllers are digital computers used for automation of electromechanical processes. Unlike general-purpose computers, PLCs are designed for multiple input/output arrangements, extended temperature ranges, immunity to electrical noise, and resistance to vibration and impact. Although the IEC 61131-3 define PLC programming languages, manufacturers typically implement their own programming tools and interfaces. Interoperability is not yet a priority for PLC manufacturers. + +Field bus +: Fieldbus is an industrial automation network system for real-time distributed control. It offers a protocol for interconnecting instruments actuators and sensors with a controller. The domain of field bus application is typically an industrial plant. Many competing fieldbus technologies exist, merging them with D-Bus is a brave goal followed by DBPC. + + + +## Specification + + +### Part 1, DBPC Basis + +[[Part 1|Specifications/DBPC/part1]] This part introduce basis usage of D-Bus for process control. + + +### Part 2, DBPC Tags : interfaces and methods description + +[[Part 2|Specifications/DBPC/part2]] This part specify common D-Bus objects, interface and method for DBPC tags. + + +### Part 3, DBPC Devices : specification, interfaces and methods description + +[[Part 3|Specifications/DBPC/part3]] This part specify common D-Bus objects, interface and method for DBPC devices. + + +### Part 4, DBPC Servers : specification, interfaces and methods description + +[[Part 4|Specifications/DBPC/part4]] This part specify common D-Bus objects, interface and method for DBPC server. + + +### Part 5, DBPC Configuration file + +[[Part 5|Specifications/DBPC/part5]] This part define a common configuration file format which are used by DBPC servers. + + +## FAQ + + +### What is the difference between DBPC for Linux and OPC-DA for Windows ? + +[[OPC-DA|http://www.opcfoundation.org/Default.aspx/01_about/01_whatis.asp?MID=AboutOPC]] was designed to bridge Windows and process control hardware and software applications. Standard defines consistent method of accessing field data from plant floor devices. Actually, OPC-DA is probably the most common interoperability tool used in automation and process control world. + +The need for interoperability are often equally applicable in Linux world. However, because OPC-DA is based on the OLE, COM, and DCOM technologies developed by Microsoft for the Microsoft Windows operating system family there are encumbrances preventing wholesale adaptation of these technologies to Linux systems. With this in mind, DBPC was created to present end users with a common cross-platform experience allowing DBPC and OPC-DA "feel" functionally similar. + +Nevertheless, DBPC distinguish of OPC-DA in one sens that it target to exploit full advantage and benefit provided by Linux operating system and Open source software development. So we personally expect better performance and reliability. + +Although DBPC is open source oriented, DBPC also still to encourage, manufacturer providing there own DBPC compliant software, not necessary open source, in the same way than OPC. + + +### New specification OPC-UA work with Linux ? Do we really need DBPC ? + +[[OPC-UA|http://www.opcfoundation.org/Default.aspx/01_about/UA.asp?MID=AboutOPC]] is an evolution of OPC-DA. It has been created to extend some features lacking with OPC-DA. + +OPC-UA is more like a communication protocol. DBPC is still an Inter-Process Communication. + + * In one hand, OPC-UA will be suitable for automation network and inter-systems interoperability, because it is XML based and include authentication support. + * In the other hand DBPC is rooted in Linux thanks to D-bus which allow deep system integration and eases application development. D-Bus offers low-latency and low-overhead and designed to be small and efficient to minimize round-trips. So very suitable for embedded systems as well as fanless touchscreen HMI. In addition, because the protocol is binary (as opposed to textual), it may remove some serialization overhead. +OPC-UA may benefit of DBPC and reciprocally. As a reslut of OPC-UA can be implemented as a upper layer (wrapper) above DBPC, similar to upcoming XMP-RPC, SOAP, CGI and so on. + + +### There are many interprocess communication and networking protocols. Why D-BUS ? + +A first approach may be reading [[D-Bus FAQ|http://dbus.freedesktop.org/doc/dbus-faq.html#other-ipc]], 9 to 18 which compare D-Bus with several IPC. + +When choosing an IPC for process control in Linux, some criteria were decisive : + +* Availability : D-Bus has strong integration with the Gnome and KDE desktop environments. +* Portability : D-Bus is portable to many Linux or UNIX flavors -- a port to Windows is in progress. +* Liability : The D-Bus low-level API reference implementation and protocol have been heavily tested in "real world" systems. +* Multi-language support : D-Bus is supported by many programming languages including : C, C++, Java, Python, Perl, etc. +* Scripting : D-Bus may be used from terminal (dbus-send) allowing command line/shell scripting. +* Efficiency : D-Bus may be effectively implemented in low performance hardware and embedded systems. +* Openness : A a side effect, instead of DBPC, HMI applications might benefit by supporting D-Bus connectivity.
\ No newline at end of file diff --git a/Specifications/DBPC/DBPC-Synoptic.png b/Specifications/DBPC/DBPC-Synoptic.png Binary files differnew file mode 100644 index 00000000..583381e5 --- /dev/null +++ b/Specifications/DBPC/DBPC-Synoptic.png diff --git a/Specifications/DBPC/DBPC-logo-nb.png b/Specifications/DBPC/DBPC-logo-nb.png Binary files differnew file mode 100644 index 00000000..5df7ef85 --- /dev/null +++ b/Specifications/DBPC/DBPC-logo-nb.png diff --git a/Specifications/DBPC/Discussion.mdwn b/Specifications/DBPC/Discussion.mdwn new file mode 100644 index 00000000..2e11a42e --- /dev/null +++ b/Specifications/DBPC/Discussion.mdwn @@ -0,0 +1,71 @@ + +[[DBPC|Specifications/DBPC]] + +Open you brain, + +Discussion about DBPC can take place here. + + + +--- + + I would like to help to develop DBPC. Can we have a mailling list for it? [[LuisMatos|LuisMatos]] + +--- + + +### about DBPC server + +* plugin driven development: dbpc server only provides a way to achieve communication. It does not provides one.; +* it must be lightweight so it can be used for in any kind of embedded system; +* it has to have control over communication with the plugins, so that the communication can be organized (request for a bunch of data once, instead of a lots of connections and low data).; +* have an event driven api, so that the clients don't ask for changed data, but the server provides the changed data.; +[[LuisMatos|LuisMatos]] + +Not sure about what you mean. I imagine a server more like a daemon than a plugin..? + +Yes, no problem, Dbus is lightweight enough. + +Yes, it is better fetching an array than one request for each bit. Server must also have methods for control its behavior and troubleshooting. + +Yes it must be a fine if servers may pool PLC values only when there is a subscription to the corresponding item and return events when values changed. D-BUS is event based, so DBPC client can easily subscribe to DBPC events. Nevertheless I did not find a way to inform the server about event subscription and release. DBus Events seems to be only some kind of broadcast. + +As an optimization we should pool PLC values only when needed. DBPC server can act like a proxy. If several applications access to the same item at the same time, we will not update item value every time but only if value is outdated. + +Rey Cyril 23.06.2009 + +"Not sure about what you mean. I imagine a server more like a daemon than a plugin..?" + +DBPC is a daemon, but it only manages data and connections. connection types and data getting must be managed by plugins. For example, one DBPC server, plugin for modbus, profibus, etc + +Luis Matos + + + +--- + + +# Configuration files + +using [[libconfig|http://www.hyperrealm.com/libconfig/]] ? [[Example|http://www.hyperrealm.com/libconfig/test.cfg.txt]] + +or ... a XML file? + +bad, bad example: + +<sources> + + * <source name="controller1" plugin="modbus" > + * <param1>192.168.0.1</param> +</source> + +</sources> + +<tags> + + * <tag source="controller1" tagname="tag" address="M101.0" type="bit"/> +</tags> + +grep tag : returns all tag names grep source: all sources grep tag, remove all names and " you can get an array of tagname, address and datatype. + +Luis Matos diff --git a/Specifications/DBPC/part1.mdwn b/Specifications/DBPC/part1.mdwn new file mode 100644 index 00000000..059a6837 --- /dev/null +++ b/Specifications/DBPC/part1.mdwn @@ -0,0 +1,12 @@ + + +# DBPC Basis + +[[DBPC|Specifications/DBPC]] + +[[!toc 2]] + + +## Introduction + +forthcoming ... diff --git a/Specifications/DBPC/part2.mdwn b/Specifications/DBPC/part2.mdwn new file mode 100644 index 00000000..dee57565 --- /dev/null +++ b/Specifications/DBPC/part2.mdwn @@ -0,0 +1,86 @@ +# DBPC Tags : interfaces and methods description + +[[DBPC|Specifications/DBPC]] + +[[!toc 3]] + + +## Introduction + +All data points available trough DBPC are represented by an tags object. Those objects are available trough DBUS thanks to a DBPC server. + +This part describe standard DBPC tags class models. + +There is a basic class called tag. all tags class corresponding to data points value are inherited from this basic class + + +## Tags interface + + <interface name="org.dbpc.tag"> + <method name="get_description"> + <arg direction="out" type="s" /> + </method> + <method name="get_refresh"> + <arg direction="out" type="s" /> + </method> + <method name="get_validity"> + <arg direction="out" type="s" /> + </method> + <method name="get_device"> + <arg direction="out" type="s" /> + </method> + <method name="get_adress"> + <arg direction="out" type="s" /> + </method> + <method name="get_name"> + <arg direction="out" type="s" /> + </method> + </interface> + +## Boolean interface + + <interface name="org.dbpc.boolean"> + <method name="read"> + <arg direction="out" type="b" /> + </method> + <method name="write"> + <arg direction="in" type="b" name="value" /> + <arg direction="out" type="b" /> + </method> + </interface> + +## Interger interface + + <interface name="org.dbpc.integer"> + <method name="read"> + <arg direction="out" type="i" /> + </method> + <method name="write"> + <arg direction="in" type="i" name="value" /> + <arg direction="out" type="b" /> + </method> + </interface> + +## Real interface + +... + + +## Analog input interface + +... + + +## Analog output interface + +... + + +## Alarm Interface interface + +... + + +## Isa88 Function interface + +... diff --git a/Specifications/DBPC/part3.mdwn b/Specifications/DBPC/part3.mdwn new file mode 100644 index 00000000..aa91923b --- /dev/null +++ b/Specifications/DBPC/part3.mdwn @@ -0,0 +1,40 @@ +# DBPC Devices : specification, interfaces and methods description + +[[DBPC|Specifications/DBPC]] + +forthcoming ... + +### Interfaces + + <!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN" + "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd"> + <node name="/org/dbpc/device/FillingControler"> + + <interface name="org.freedesktop.DBus.Introspectable"> + <method name="Introspect"> + <arg direction="out" type="s" /> + </method> + </interface> + + <interface name="org.dbpc.device"> + <method name="get_server"> + <arg direction="out" type="s" /> + </method> + <method name="disconnect"> + <arg direction="out" type="b" /> + </method> + <method name="get_address"> + <arg direction="out" type="s" /> + </method> + <method name="get_name"> + <arg direction="out" type="s" /> + </method> + <method name="get_description"> + <arg direction="out" type="s" /> + </method> + <method name="connect"> + <arg direction="out" type="b" /> + </method> + </interface> + + </node> diff --git a/Specifications/DBPC/part4.mdwn b/Specifications/DBPC/part4.mdwn new file mode 100644 index 00000000..3eec77c9 --- /dev/null +++ b/Specifications/DBPC/part4.mdwn @@ -0,0 +1,61 @@ +# DBPC Servers : specification, interfaces and methods description + +[[DBPC|Specifications/DBPC]] + +[[!toc 2]] + + +## Introduction + +A DBPC server is a D-Bus service offering communication facilities with industrial equipement. + + +## Servers type + +Server can be mandatory for a field bus, protocol or electronic equipment : + + * **Field bus or protocol based servers** allow retrieving tags value trough a communication interface and make those values available, thanks to D-bus, trough a DBPC server. + * **Electronic device based server** are generally supplied by manufacturers which would provide a standardized interface for there equipments within Linux systems. + +## D-bus service bus name + +D-Bus service name of DBPC server begin always with "org.dbpc.". Usually server name correspond to the corresponding protocol. (example: org.dbpc.modbustcp) + +An other name can be choose with option -n + + +## Servers configuration file + +By default, configuration file is stored in "/etc/dbpc/". Configuration file has the same name than the D-Bus service name, folowed by ".conf". (example: modbustcp.conf) + +Another file can be choose with option -f + + +## Server methods + + <!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN" + "http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd"> + <node name="/org/dbpc/server"> + + <interface name="org.freedesktop.DBus.Introspectable"> + <method name="Introspect"> + <arg direction="out" type="s" /> + </method> + </interface> + + <interface name="org.dbpc.server"> + <method name="get_state"> + <arg direction="in" type="v" name="variant" /> + <arg direction="out" type="s" /> + </method> + </interface> + + </node> + +## Server implementation name + +Server implementations are usually named with the field bus or protocol designation, optionally followed by a specific name or identifier and finishing with "DBPC server". (example: ModbusTCP_..._DBPCserver) + +Generic server may be only called with a specific name or identifier followed by "DBPCserver". + +Electronic equipment server name usually begin with manufacturer name followed by model designation and finish with "DBPC_server". (example: Wago_750-863_DBPCserver) diff --git a/Specifications/DBPC/part5.mdwn b/Specifications/DBPC/part5.mdwn new file mode 100644 index 00000000..a84ba4c7 --- /dev/null +++ b/Specifications/DBPC/part5.mdwn @@ -0,0 +1,77 @@ +# Part 5, DBPC Configuration file + +[[DBPC|Specifications/DBPC]] + +[[!toc 2]] + + +## Introduction + +DBPC configuration files may be automatically generated by third party software. So every DBPC server should have the same configuration file structure. This part describes configuration files used by DBPC. + +Introduction exemple : + + <project> + <devices> + <device name="FillingControler"> + <address>192.168.1.4</address> + <description>Filling machine programmable logic controler for DBPC simulation</description> + + <tags> + <tag name="A230LI10" type="integer"> + <address>MW10</address> + <refresh>on use</refresh> + <validity>3s</validity> + <description>unit A230 level indicator 10</description> + </tag> + <tag name="motor/A230M20" type="bool"> + <address>A10.3</address> + <refresh>on use</refresh> + <validity>2.5s</validity> + <description>unit A230 command filling pumpe 20</description> + </tag> + <tag name="motor/A230M20MS" type="bool"> + <address>E10.3</address> + <refresh>on use</refresh> + <validity>2s</validity> + <description>unit A230 status filling pumpe 20</description> + </tag> + </tags> + + </device> + + <device name="MixerController"> + <address>adr18</address> + <protocol>ModbusRTU</protocol> + <description>Bier tank mixer programmable logic controler for DBPC simulation</description> + + <tags> + <tag name="A300LI10" type="integer"> + <address>MW10</address> + <refresh>on use</refresh> + <validity>3s</validity> + <description>unit A230 level indicator 10</description> + </tag> + <tag name="A300M20" type="bool"> + <address>A11.3</address> + <refresh>on use</refresh> + <validity>2.5s</validity> + <description>unit A230 command filling pumpe 20</description> + </tag> + <tag name="A300M20MS" type="bool"> + <address>A11.3</address> + <refresh>on use</refresh> + <validity>2s</validity> + <description>unit A230 status filling pumpe 20</description> + </tag> + </tags> + + </device> + + </devices> + + ... + + </project> + +Unknow entry are ignored. So this file can be shared with other app und custom tag can be added. diff --git a/Specifications/OpenRaster.mdwn b/Specifications/OpenRaster.mdwn new file mode 100644 index 00000000..5a1b0a59 --- /dev/null +++ b/Specifications/OpenRaster.mdwn @@ -0,0 +1,31 @@ + + +# OpenRaster + +OpenRaster is an open exchange format for layered raster based graphics. The format is inspired by OpenDocument, and aims to reuse as much of related open formats as makes sense. + +OpenRaster was initiated at the Libre Graphics Meeting 2006 in Lyon, when developers from the Gimp and Krita teams, and other potentially interested parties met for the first time. + +Today OpenRaster is supported by several free and open source applications, libraries and tools. + + +## Resources + +* Source code for common components: [[OpenRaster GIT|http://gitorious.org/openraster]] +* Mailing list: [[create@freedesktop.org|http://lists.freedesktop.org/mailman/listinfo/create]] +* Bug tracker: [[Currently open bugs|https://bugs.freedesktop.org/buglist.cgi?query_format=specific&order=relevance+desc&bug_status=__open__&product=OpenRaster&content=]] | [[File a new bug|https://bugs.freedesktop.org/enter_bug.cgi?product=OpenRaster]] + +## Specifications & Requirements + +* [[Draft Specification|Specifications/OpenRaster/Draft]] + * To be worked on in Wiki form and progressed to a formal version. + * Please discuss changes via the mailing list. +* [[Requirements and Challenges|Specifications/OpenRaster/Requirements]] +* [[Contributing|Specifications/OpenRaster/Contributing]] + +## See Also + +* [[Application support|Specifications/OpenRaster/ApplicationSupport]] +* [[Desktop integration|Specifications/OpenRaster/DesktopIntegration]] +* [[Utilities|Specifications/OpenRaster/Utilities]] +* [[Reference library|Specifications/OpenRaster/ReferenceLibrary]]
\ No newline at end of file diff --git a/Specifications/OpenRaster/ApplicationSupport.mdwn b/Specifications/OpenRaster/ApplicationSupport.mdwn new file mode 100644 index 00000000..20f467fb --- /dev/null +++ b/Specifications/OpenRaster/ApplicationSupport.mdwn @@ -0,0 +1,33 @@ + +_This page is part of the [[OpenRaster file format description|Specifications/OpenRaster]]._ + + + +--- + + + +Please add your application here when you implement [[OpenRaster|Specifications/OpenRaster]] support. + + +## Editing applications +[[!table header="no" class="mointable" data=""" + **Application** | **Basic support** | **Default file format** + [[MyPaint|http://www.mypaint.info]] | Since 0.6 (January 2009) | Yes + [[DrawPile|http://sourceforge.net/projects/drawpile/]] | In development version (June 2009), will be in 0.7 | Unknown + [[Krita|http://krita.org/]] | Since 2.0 (May 2009) | No + [[GIMP|http://www.gimp.org/]] | In development version (January 2010), will be in 2.8 Plug-in for 2.6 [[available|http://registry.gimp.org/node/18435]] | No + [[Pinta|http://pinta-project.com/]] | Since 0.4 (July 2010) | Unknown + [[Native|http://www.nathive.org/]] | Since 0.908 (June 2010) | Yes + [[paint.net|http://www.getpaint.net/]] | Plugin ([[OpenRaster Filetype|http://forums.getpaint.net/index.php?/topic/20984-openraster-filetype/]]) | No +"""]] + + +## Frameworks + +[[gegl|http://www.gegl.org/]]: Reported by author to be able to open files produced by [[MyPaint|MyPaint]] + + +## Preview applications + +No known implementation as of October 2010. Support in Gtk and Qt based applications, via GdkPixbuf and !QImage is [[planned|http://lists.freedesktop.org/archives/create/2010-October/003276.html]]. diff --git a/Specifications/OpenRaster/Contributing.mdwn b/Specifications/OpenRaster/Contributing.mdwn new file mode 100644 index 00000000..82037941 --- /dev/null +++ b/Specifications/OpenRaster/Contributing.mdwn @@ -0,0 +1,31 @@ + +_This page is part of the [[OpenRaster file format description|Specifications/OpenRaster]]._ + + + +--- + + + +[[OpenRaster|Specifications/OpenRaster]] is an open project, and is in need of your help! + +These are the core areas you can help. + + +## Specification + +For everything we want to support in OpenRaster, there needs to be a clear and sufficiently detailed specification that has concensus among the projects using OpenRaster. This is developed by taking real-life usecases and problems, look at the needs and requirements for the solution and proposing an addition or modification to the spec on the mailing list. Often prototype implementations can be useful in judging the feasibility of a solution. + +[[Open specification issues|https://bugs.freedesktop.org/buglist.cgi?query_format=advanced&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&bug_status=NEEDINFO&component=Specification&product=OpenRaster]] + + +## Adoption in relevant projects + +To be useful to the end-user OpenRaster needs to be adopted and implemented in applications, desktop environment, tools and libraries. For a list of applications that already implements OpenRaster, see [[../ApplicationSupport|Specifications/OpenRaster/ApplicationSupport]]. Development here should generally be done upstream in the individual projects. + + +## Common software components + +As a project, OpenRaster also provides some common software components. These often target developers more than end users. For instance libora, a [[reference library|Specifications/OpenRaster/Contributing/ReferenceLibrary]] or some [[utilities|Specifications/OpenRaster/Utilities]]. All the common code the [[OpenRaster|OpenRaster]] project hosts is found [[on gitorious|http://gitorious.org/openraster]] and have components on our bugtracker. + +[[Open issues|https://bugs.freedesktop.org/buglist.cgi?query_format=advanced&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&bug_status=NEEDINFO&component=gimp-plugin-file-ora&component=libora&component=ora-thumbnailers&component=oratools&product=OpenRaster]] diff --git a/Specifications/OpenRaster/DesktopIntegration.mdwn b/Specifications/OpenRaster/DesktopIntegration.mdwn new file mode 100644 index 00000000..a12bc4db --- /dev/null +++ b/Specifications/OpenRaster/DesktopIntegration.mdwn @@ -0,0 +1,32 @@ + +_This page is part of the [[OpenRaster file format description|Specifications/OpenRaster]]._ + + + +--- + + + + +## File type association + + +### MIME type + +For GNU/Linux and similar systems + +* shared-mime-info version > 0.60 will have image/openraster available +* Krita (in next released version, which will be the stable 2.1, in the end) uses this version, albeit carrying a local copy of it (to avoid a dependency on a not-released-yet shared-mime-info version) +Details: [[http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=545396|http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=545396]] + + +## File manager preview / Thumbnailer +[[!table header="no" class="mointable" data=""" +**Platform** | **Upstream support** | **Support via ODF compatibility** | **Standalone support** | **API documentation** +GNOME | [[N/A|https://bugzilla.gnome.org/show_bug.cgi?id=605577]] | ooo-thumbnailer? | [[ora-thumbnailers|Specifications/OpenRaster/ora-thumbnailers]] | [[Nautilus thumbnail API|http://library.gnome.org/devel/integration-guide/stable/thumbnailer.html.en]] +KDE | [[https://bugs.kde.org/show_bug.cgi?id=220335%20Issue%20filed|https://bugs.kde.org/show_bug.cgi?id=220335%20Issue%20filed]] | [[patch available|https://bugs.kde.org/show_bug.cgi?id=255755]] for KOffice | [[ora-thumbnailers|OpenRaster/ora-thumbnailers]] | [[Kio:ThumbCreator|http://api.kde.org/4.x-api/kdelibs-apidocs/kio/html/classThumbCreator.html]] +Xfce <= 4.8 | [[thunar-thumbnailers|http://goodies.xfce.org/projects/thunar-plugins/thunar-thumbnailers]] | [[http://bugzilla.xfce.org/show_bug.cgi?id=6108%20patch%20available|http://bugzilla.xfce.org/show_bug.cgi?id=6108%20patch%20available]] for thunar-thumbnailers | [[ora-thumbnailers|OpenRaster/ora-thumbnailers]] | [[Thunar thumbnail API|http://thunar.xfce.org/documentation/C/customizing-thunar.html]] +Xfce >= 4.8 | Explicit support for image/openraster in [[tumbler's odf-thumbnailer plugin|http://git.xfce.org/xfce/tumbler/tree/plugins]]. Packaged in Debian as "tumbler-plugins-extra". || | N/A | [[https://live.gnome.org/ThumbnailerSpec|https://live.gnome.org/ThumbnailerSpec]] +Windows | N/A | [[patches welcome|http://lists.freedesktop.org/archives/libreoffice/2010-October/001357.html]] for [[LibreOffice|LibreOffice]] | [[forum thread with code|http://forum.intilinux.com/mypaint-development-and-suggestions/ora-extension-support]] | [[IThumbnailProvider/IExtractImage|http://msdn.microsoft.com/en-us/library/cc144118(VS.85).aspx]] +Mac OS X | N/A | ? | | [[QLThumbnailRequest|http://developer.apple.com/library/mac/#documentation/UserExperience/Reference/QLThumbnailRequest_Ref/Reference/reference.html]] +"""]] diff --git a/Specifications/OpenRaster/Draft.mdwn b/Specifications/OpenRaster/Draft.mdwn new file mode 100644 index 00000000..f3d4789a --- /dev/null +++ b/Specifications/OpenRaster/Draft.mdwn @@ -0,0 +1,53 @@ + +_This page is part of the [[OpenRaster file format description|Specifications/OpenRaster]]._ + + + +--- + + + + +# Draft OpenRaster Specification + + +## Baseline Intent + +Every [[OpenRaster|Specifications/OpenRaster]] file is compliant to Baseline. + +This intent is for exchange between applications and it is allowed to have custom extensions in such a file. + +* [[File Layout Specification|Specifications/OpenRaster/Draft/FileLayout]] +* [[Layer Stack Specification|Specifications/OpenRaster/Draft/LayersStack]] + +## Archival Intent + +This intent is for long-term archival and does not allow any application specific extensions. It places additional restrictions on the Baseline Intent. + +* Still under discussion. + +## Extensions / Modules + +This describes optional features that are not part of baseline. Extensions should have published working code, and be supported in more than one OpenRaster-aware application. + +* [[Layer Selection Status|Specifications/OpenRaster/Draft/LayerSelectionStatus]] - load and save layer selection state +* [[Layer Edit Locking Status|Specifications/OpenRaster/Draft/LayerEditLockingStatus]] - load & save layer immutability state + +## Proposals and Application Specific Extensions + +Those might move to the Extensions after discussion. Application developers are invited to create a wiki entry here and develop it. At some point it might be proposed for inclusion to the Extensions through the Create mailing list. + +* [[Effects Specification|Specifications/OpenRaster/Draft/EffectsSpecification]] +* [[Palette|Specifications/OpenRaster/Draft/Palette]] +* [[Embed Fonts|Specifications/OpenRaster/Draft/EmbedFonts]] (Proposal to extension) +* [[Multiple pages|Specifications/OpenRaster/Draft/MultiplePages]] +* [[Animation|Specifications/OpenRaster/Draft/Animation]] support using multiple pages and a timer like PSD do +* [[Undo-history|Specifications/OpenRaster/Draft/UndoHistory]] support undo/history of commands/actions like PSD do +* [[Version numbering|Specifications/OpenRaster/Draft/VersionNumber]] +* [[PNG data requirements|Specifications/OpenRaster/Draft/PngDataRequirements]] + +## Related Links + +* [[Sample OpenRaster files|http://gitorious.org/openraster/openraster-example-files/trees/master]] for testing +* [[../DesktopIntegration|Specifications/OpenRaster/DesktopIntegration]] for the mime entry, and a list of programs using the thumbnails +* [[Thumbnail Managing Standard|http://jens.triq.net/thumbnail-spec/index.html]]
\ No newline at end of file diff --git a/Specifications/OpenRaster/Draft/Animation.mdwn b/Specifications/OpenRaster/Draft/Animation.mdwn new file mode 100644 index 00000000..521dfa57 --- /dev/null +++ b/Specifications/OpenRaster/Draft/Animation.mdwn @@ -0,0 +1,19 @@ + +_This page is part of the [[Draft OpenRaster specification|Specifications/OpenRaster/Draft]]._ + + + +--- + + + +State: Proposal + + +### Animation + +* One OpenRaster file would be able to contain more than one image. This would be useful for things like sketchbooks, comic stories, or anything else where you might want to have raster images in sequence but where using separate image files would be impractical. +* File contain timing for every raster image, and a jump/loop count settings. +* Any program which does not support animation OpenRaster files would simply show the first raster and hide the others (or, perhaps, show a raster defined as “default” by the image author). +* Any program could implement, crudely, something like this using layer groups. However, that would be unlikely to be recognized across implementations. +(Contributions: 19 October 2010 Efa (& others?)) diff --git a/Specifications/OpenRaster/Draft/EffectsSpecification.mdwn b/Specifications/OpenRaster/Draft/EffectsSpecification.mdwn new file mode 100644 index 00000000..259a1ead --- /dev/null +++ b/Specifications/OpenRaster/Draft/EffectsSpecification.mdwn @@ -0,0 +1,123 @@ +_This page is part of the [[Draft OpenRaster specification|Specifications/OpenRaster/Draft]]._ + +--- + +Status: Proposed Extension (currently unimplemented?) + Note: this is an early draft of the specification, do not take anything on this page for granted, pretty much everything is open for discussion. + + +# Filter Effects + +As a standard extension, outside baseline but defined in the standard schema, OpenRaster layers stacks should be able to contain parameterised filters which themselves might contain sub-stacks. This document shows how the extension would be integrated into baseline OpenRaster `stack.xml` syntax, describes the additional elements and attributes, and lists the available filters. + + <stack> + <stack> + <filter name="invert" type="invert" /> + <!-- layers --> + </stack> + <!-- ... layers ... --> + <filter name="filter1" type="standard:gaussianblur"> + <params> + <param name="radius">10</param> + </params> + <stack> + <layer name="mask2" src="data/mask2.data" composite-op="svg:src-over" /> + <layer name="mask1" src="data/mask1.png" /> + </stack> + </filter> + <!-- ... more layers ... --> + </stack> + +# Semantics + +TODO: define how flters are to be applied. Presumably to just the layers inside the nested `<stack/>` element? If so, how is the result to be composited onto the results of the layers below? + + +## filter element + +This element defines a layer which instead of containing pixel data, applies a filter onto the composited result of the layers below it in the stack. The attributes are: + +* "`type`": the type of the filter. Type names make use of namespaces, they must have the following form: "namespace:name". Three namespaces are defined: + * "standard": for the list of filters and the associated mathematics, see the relevant OpenRaster specification + * "composite": composite filter are filters which are a composition of a list of standard filters. The name must be the name of a filter defined in the same file. + * "application": non-standard filters; the name is formed as followed "application:filtername". For example, for an application called MyGraphApp, the full name is "application:MyGraphApp:MyFilter". Use of such a type of filter prevents the file from being a Full Baseline OpenRaster file; however use of the "`output`" attribute defined below allows the file to be conformant to the Viewing Baseline. +* "`output`": the file name of the data of the filter output, this attribute is only needed when the type of the filter is of the "application" namespace, and if the user wants to create a Viewing Baseline layer stack. + +## params element + +This element is used to describe the parameters used for a filter layer. The standard filters each have a defined list of parameters, defined permissible values. Attributes: + +* "`version`": correspond to the version of the filter, either the version of the filter specification for standard filter, or any number defined by the application for application-specific filters. + +## param element + +Description of the attributes: + +* "`name`": the name of the parameter. +The parameter's value is formed by the content of the `param` element. + +For "composite" filters, the params element allows variables to be defined which are then used to parameterise each contained filter. For example, consider a composite function composed of "standard:blur" filter with the parameter "radius" applied with a "standard:invert" filter. It is defined as follows in the composite section: + + <compositefilter name="blurinvert" > + <filter name="blur"> + <params> + <param name="radius"> + @R@ + </param> + </params> + </filter> + <filter name="invert" /> + </compositefilter> + +Then the usage would be: + + <filter name="composite:blurinvert" > + <params> + <param name="R">10</param> + </params> + </filter> + +TODO: reconsider this, is it useful ? it just come out of my mind that is the only usefull use of parameters for composite filter, but if it's useless, lets not allow any parameters for them ! + + +# Standard Filters + +The mathematics behind each filter is described in the SVG 1.1 Specification, and each filter accepts the same parameters. + +OpenRaster files may use filters not described in this document, in which case the file won't be valid for interoperability, unless the result of the operation is also available (see the `output` attribute above). + + +## ColorMatrix + +See [[SVG 1.1 Specification|http://www.w3.org/TR/SVG11/filters.html#feColorMatrixElement]]. + + +## ConvolveMatrix + +See [[SVG 1.1 Specification|http://www.w3.org/TR/SVG11/filters.html#feConvolveMatrixElement]]. + + +## ComponentTransfer + +See [[SVG 1.1 Specification|http://www.w3.org/TR/SVG11/filters.html#feComponentTransferElement]]. + + +## GaussianBlur + +See [[SVG 1.1 Specification|http://www.w3.org/TR/SVG11/filters.html#feGaussianBlurElement]]. + + +## Tile + +See [[SVG 1.1 Specification|http://www.w3.org/TR/SVG11/filters.html#feTileElement]]. + + +## Morphology + +See [[SVG 1.1 Specification|http://www.w3.org/TR/SVG11/filters.html#feMorphologyElement]]. + + +## Distortion correction + + +## Burn and Dodge diff --git a/Specifications/OpenRaster/Draft/EmbedFonts.mdwn b/Specifications/OpenRaster/Draft/EmbedFonts.mdwn new file mode 100644 index 00000000..8f1a0d33 --- /dev/null +++ b/Specifications/OpenRaster/Draft/EmbedFonts.mdwn @@ -0,0 +1,21 @@ + +_This page is part of the [[Draft OpenRaster specification|Specifications/OpenRaster/Draft]]._ + + + +--- + + + +State: Proposal + + +### Embed fonts as TTF files + +To improve the user experience and maximize the representation accuracy is possible to store the .ttf fonts itself into the .ora file. + +Additionally the implementation must check if the font is libre, then: + +* If is libre: Embed it directly into the .ora +* If is not libre: Alert the user about the license issues, and offer him to avoid the embeding or to embed it despite of the legal issues. +(Contributions: 28-30 May 2010 by Markos) diff --git a/Specifications/OpenRaster/Draft/FileLayout.mdwn b/Specifications/OpenRaster/Draft/FileLayout.mdwn new file mode 100644 index 00000000..9607f0b0 --- /dev/null +++ b/Specifications/OpenRaster/Draft/FileLayout.mdwn @@ -0,0 +1,61 @@ +_This page is part of the [[Draft OpenRaster specification|Specifications/OpenRaster/Draft]]. It has archived [[discussion threads|Specifications/OpenRaster/Draft/FileLayout/Discussion]]._ + +--- + +:_Status: what is already specified is pretty much final_ + + +# OpenRaster File Layout + + +## Storage + +OpenRaster files have the file name extension **.ora**. The data is stored within a [[Zip file|http://www.pkware.com/documents/casestudies/APPNOTE.TXT]] wrapper. + +_Technical note: Zip files can use a different compression algorithm on a per-file basis. Only DEFLATED and STORED should be used for OpenRaster files. The file names within OpenRaster "zip files" are case-sensitive and must be UTF-8 encoded. If you decide to write non-ascii file names, be aware that the Zip format has an UTF-8 flag for each file name. Make sure this flag is set, otherwise the content might get decoded as cp437. Notw also that the Zip file format has a 64bit extension which must be enabled to write files larger than 4GB._ + +This file format is hereafter referred to as an "OpenRaster file" in this specification. It has a number of required and optional standard files and subdirectories within it: + + example.ora [considered as a folder-like object] + ├ mimetype + ├ stack.xml + ├ data/ + │ ├ [image data files referenced by stack.xml, typically layer*.png] + │ └ [other data files, indexed elsewhere] + ├ Thumbnails/ + │ └ thumbnail.png + └ [mergedimage.png (optional)] + +## Required Files + + +### mimetype + +The first file in the archive must be called "`mimetype`", without a file name extension. It must be STORED without compression. This file must contain the string "`image/openraster`", with no whitespace or trailing newline. + + +### stack.xml + +This is the UTF-8 encoded XML file from the [[Layers Stack Specification|Specifications/OpenRaster/Draft/LayersStack]]. + + +### data + +This directory is (by convention) where data files are usually stored. Files must be referenced in `stack.xml` by their full path relative to the OpenRaster file's root, e.g. "`data/layer2.png`". + +All files inside this directory should be referenced from somewhere. Well known file name extensions (like .png) should be lower case. + + +### Thumbnails/thumbnail.png + +An OpenRaster file _must_ have a `thumbnail.png` in order to allow file browser software to render the thumbnail effciently. It _must_ be a non-interlaced PNG with 8 bits per channel of at most 256x256 pixels. It _should_ be as big as possible without upscaling or changing the aspect ratio. Any aspect ratio is permitted. It _should not_ contain any frame or decoration. + +The thumbnail file must not be referenced in any `.xml` file. + + +## Optional Files + + +### mergedimage.png + +An OpenRaster file _may_ contain the final rendered image without any frame or decoration. This file _must_ be a PNG file with 8 or 16 bits per channel. The `mergedimage.png` file is obligatory in the Archival Intent. diff --git a/Specifications/OpenRaster/Draft/FileLayout/Discussion.mdwn b/Specifications/OpenRaster/Draft/FileLayout/Discussion.mdwn new file mode 100644 index 00000000..6eb769d8 --- /dev/null +++ b/Specifications/OpenRaster/Draft/FileLayout/Discussion.mdwn @@ -0,0 +1,9 @@ + +_This is an archived discussion page from the defunct [[CREATE wiki|http://wayback.archive.org/web/*/http://create.freedesktop.org/]], and is not watched by the original authors. For further discussion of the [[parent page|Specifications/OpenRaster/Draft/FileLayout]] or any other part of the [[OpenRaster specification|Specifications/OpenRaster]], please use the [[mailing list|http://lists.freedesktop.org/mailman/listinfo/create]] instead._ + + +## Extension + +Proposal: use .odr as extension, to be compliant to other OpenDocument file formats--Efa 16:14, 19 October 2010 (UTC) + +How does this help at all with OpenDocument compliance? Anyhow, the extension is fairly set in stone at this point. --Jonnor 15:46, 23 October 2010 (UTC) diff --git a/Specifications/OpenRaster/Draft/LayerEditLockingStatus.mdwn b/Specifications/OpenRaster/Draft/LayerEditLockingStatus.mdwn new file mode 100644 index 00000000..e6eb84f9 --- /dev/null +++ b/Specifications/OpenRaster/Draft/LayerEditLockingStatus.mdwn @@ -0,0 +1,37 @@ +_This page is part of the [[Draft OpenRaster specification|Specifications/OpenRaster/Draft]]._ + +--- + +State: Implemented ([[awaiting schema merge|https://gitorious.org/openraster/openraster-standard/merge_requests/1]]) + Bug: [[https://bugs.freedesktop.org/show_bug.cgi?id=37714|https://bugs.freedesktop.org/show_bug.cgi?id=37714]] + + +## Layer Edit Locking Status + +Editor applications sometimes have a concept of layers which are currently locked to prevent accidental editing. This state should be saved as part of OpenRaster files which might be opened again for editing in order to assist user workflow. Therefore, the `<layer/>` element in a layer stack definition should support the following extra attribute: + +* "`edit-locked`": the layer edit locking status, expressed as an [[xsd:boolean|http://www.w3.org/TR/xmlschema-2/#boolean]]. True values ("`true`", canonically) mean that the layer was locked to prevent accidental edits by the user, and should be regarded as un-editable after loading if such immutable layers are supported by the editor. False values ("`false`", canonically) indicate that the layer is not edit locked, and should be treated as editable immediately after loading. The default is false. +(It is intended that other kinds of "locking", e.g. _alpha locking_ which makes the alpha channel of a layer immutable, should suffix their attribute names with the string `"-locked"` for consistency. Don't just use "`locked`" on its own; there's more than one kind of immutability.) + + +### Example + +When a user does not wish to accidentally paint colour onto a monochrome sketch layer, they may wish to _edit-lock_ that layer in the user interface. When the working document is saved, such a layer stack might be saved as: + + <stack> + <layer name="sketch" x="0" y="0" src="data/layer001.png" edit-locked="true"/> + <layer name="colours" x="-512" y="-128" src="data/layer002.png"/> + </stack> + +### Impact on Applications + +This change has no impact on the viewing baseline intent. + +Applications supporting the full baseline intent which permit layers to be made immutable by the user to prevent accidental edits should mark edit-locked layers with the `edit-locked` attribute when saving, and restore their edit-locked state when loading. Applications may impose their own definition of what _edit-locked_ actually means; for example, in MyPaint, layers marked as locked in this way cannot be painted to, but are also unavailable for selection by brushstroke or for brushstroke picking. + +The `edit-locked` attribute must be omitted when saving for the archival intent. + + +### Support + +Implemented in Krita and MyPaint development trunks since 2012-03-26. diff --git a/Specifications/OpenRaster/Draft/LayerSelectionStatus.mdwn b/Specifications/OpenRaster/Draft/LayerSelectionStatus.mdwn new file mode 100644 index 00000000..8a63b919 --- /dev/null +++ b/Specifications/OpenRaster/Draft/LayerSelectionStatus.mdwn @@ -0,0 +1,33 @@ +_This page is part of the [[Draft OpenRaster specification|Specifications/OpenRaster/Draft]]._ + +--- + +State: Implemented ([[awaiting schema merge|https://gitorious.org/openraster/openraster-standard/merge_requests/1]]) + Bug: [[https://bugs.freedesktop.org/show_bug.cgi?id=37713|https://bugs.freedesktop.org/show_bug.cgi?id=37713]] + + +## Layer Selection Status + +Editor applications normally have a concept of which layer or layers, are currently selected by the user for editing. It is more convenient for the user if such applications save this information to OpenRaster files, and are able to select the same layer or layers again when the file is reloaded. Therefore, the `<layer/>` element in a layer stack definition should support the following extra attribute: + +* "`selected`": the layer selection status, expressed as an [[xsd:boolean|http://www.w3.org/TR/xmlschema-2/#boolean]]. True values ("`true`", canonically), mean that the layer is selected by the user, and may be made active for editing after loading. False values ("`false`", canonically) indicate that the layer is not selected. The default is false. + +### Example + + <stack> + <layer name="sketch" x="0" y="0" src="data/layer001.png"/> + <layer name="colours" x="-512" y="-128" src="data/layer002.png" selected="true"/> + </stack> + +### Impact on Applications + +This change has no impact on the viewing baseline intent. + +Apps supporting the full baseline intent which permit layers to be chosen by the user for editing or any other purpose should mark a single such chosen layer as `selected` when saving, ideally a layer currently receptive to editing. Upon loading, apps should respect the user selection and should make any layer marked as `selected` both selected in the interface and, if supported, receptive to editing. When loading, it is acceptable to make only a single layer selected (and possibly receptive to editing) if that is all that is supported and multiple layers are marked as `selected` in the OpenRaster file being loaded. The choice of which layer to make active is left as an implementation detail, but should be guided by the `selected` attributes of layers. + +The `selected` attribute must be omitted when saving for the archival intent. + + +### Support + +Implemented in Krita and MyPaint development trunks since 2012-03-26. diff --git a/Specifications/OpenRaster/Draft/LayersStack.mdwn b/Specifications/OpenRaster/Draft/LayersStack.mdwn new file mode 100644 index 00000000..3ce5edfd --- /dev/null +++ b/Specifications/OpenRaster/Draft/LayersStack.mdwn @@ -0,0 +1,90 @@ +_This page is part of the [[Draft OpenRaster specification|Specifications/OpenRaster/Draft]]._ + +--- + +Note: this is an early draft of the specification, do not take anything on this page for granted. Pretty much everything is open for discussion. + + +# Introduction + +This document specifies the [[OpenRaster|Specifications/OpenRaster/Draft]] Layer Stack XML format. The main two goals of the specification are interoperability between applications and allowing files to be saved without destructive pixel operations. + +Note that this document does not define how the data is stored, and especially doesn't address the issue of how to store pixels nor how OpenRaster files can be stored on disk. This document doesn't address the mathematics behind layer compositing operations: it's simpler to describe that using other standard bodies' documents at this stage. + +The first part of the document explains the concept of a baseline Layer Stack, with examples. Each attribute and element defined by the baseline profile is explained individually. + + +## Baseline documents + +A baseline OpenRaster document is a document that can be opened and look similar on all applications and platforms. The baseline layer stack format defines the minimum requirement to achieve interoperability and what is unsafe for interoperability. Layer Stack format permits extensions, which should be individually specified in detail, and work safely with the baseline profile. + +Some users will require full interoperability, to create files which can be edited on every application supporting OpenRaster. Other users will only need to view OpenRaster files. This specification defines two classes of baseline support: + +* "Full baseline", which allows reading and editing +* "Viewing baseline" which guarantees visualization of the file, but editing might damage the result + +# Syntax + +The formal syntax of the layer stack is given following the [[RelaxNG schema|http://www.relaxng.org]]: + +* <https://gitorious.org/openraster/openraster-standard/blobs/master/schema.rnc> (compact format, canonical schema) +* <https://gitorious.org/openraster/openraster-standard/blobs/master/schema.rng> (xml format) + +# Example + + <?xml version='1.0' encoding='UTF-8'?> + <image w="300" h="177"> + <stack> + <stack x="10"> + <stack> + <layer name="OpenRaster Logo" src="data/hw.svg" x="5" y="5" /> + <text x="50" y="10">Use a Rich Text XML Specification to write cool text in your OpenRaster File</text> + </stack> + </stack> + <!-- filters are syntactically permissible, but not valid for baseline --> + <layer name="layer1" src="data/image1.png" /> + </stack> + </image> + +# Elements and Attributes + + +## Common attributes + +* "`x`" and "`y`": position attributes. These are signed integers with a default value of 0. +* "`name`": The name of the object represented by an element. A Unicode string, encoded in the XML document's own encoding. + +## image element + +This is the root element of the file. The logical size of the image is given by the mandatory "`w`" and "`h`" attributes, which are positive integers. The content expressed within `image` may have extents which are can be smaller or larger, and so the image should be cropped to (0,0,w,h) when displaying, printing, or otherwise exporting to a context which requires a rectangular image. + + +## stack element + +This element describes a group of layers. They may contain sub-`stack`s, `layer`s, or `text` elements. The first element in a stack is the uppermost. + + +## layer element + +The layer element defines a graphical layer within a layer stack, stored in a separate file within the OpenRaster file. The following attribute is required: + +* "`src`": the path to the stored data file for this layer. See the [[File Layout Specification|Specifications/OpenRaster/Draft/FileLayout]] for an explanation of the values which can go here. +Layer elements may have `name`, `x` and `y` attributes, as defined above. + +The following attributes are optional: + +* "`composite-op`": the compositing operation used by this layer. + * Valid values are the following operations as defined by the [[SVG 1.2 standard|http://dev.w3.org/SVG/modules/compositing/master/SVGCompositing.html#comp-op-property]] + * `svg:src-over` | `svg:plus` | `svg:multiply` | `svg:screen` | `svg:overlay` | `svg:darken` | `svg:lighten` | `svg:color-dodge` | `svg:color-burn` | `svg:hard-light` | `svg:soft-light` | `svg:difference` + * In addition, the following non-separable compositing operations are defined in the (SVG, Canvas and CSS) [[Compositing and Blending 1.0 Editor's Draft|http://dvcs.w3.org/hg/FXTF/rawfile/tip/compositing/index.html]]: + * `svg:color` | `svg:luminosity` | `svg:hue` | `svg:saturation`. + * Default value: `svg:src-over`. This is the traditional "normal" or "over" operation used for alpha compositing. + * In the future other compositing modes might be added, and a way for applications to define new modes will be specified. +* "opacity" a simple floating-point number, between 0.0 for fully transparent and 1.0 for fully opaque. +* "`visibility`" : The visibility of this layer. + * Valid values are either `visible`, or `hidden`. + * Default value: `visible`. + +## text element + +TODO: define it! Ideally, use another rich text specification, e.g. a relevant subset of the OpenDocument Text specification or XHTML. diff --git a/Specifications/OpenRaster/Draft/MultiplePages.mdwn b/Specifications/OpenRaster/Draft/MultiplePages.mdwn new file mode 100644 index 00000000..63967dcc --- /dev/null +++ b/Specifications/OpenRaster/Draft/MultiplePages.mdwn @@ -0,0 +1,18 @@ + +_This page is part of the [[Draft OpenRaster specification|Specifications/OpenRaster/Draft]]._ + + + +--- + + + +State: Proposal + + +### Multiple pages + +* One OpenRaster file would be able to contain more than one page. This would be useful for things like sketchbooks, comic stories, or anything else where you might want to have raster images in sequence but where using separate image files would be impractical. +* Any program which does not support multi-page OpenRaster files would simply show the first page and hide the others (or, perhaps, show a page defined as “default” by the image author). +* Any program could implement, crudely, something like this using layer groups. However, that would be unlikely to be recognized across implementations. +(Contributions: 5 August 2010 Tina Russell) diff --git a/Specifications/OpenRaster/Draft/Palette.mdwn b/Specifications/OpenRaster/Draft/Palette.mdwn new file mode 100644 index 00000000..95efac7e --- /dev/null +++ b/Specifications/OpenRaster/Draft/Palette.mdwn @@ -0,0 +1,15 @@ + +_This page is part of the [[Draft OpenRaster specification|Specifications/OpenRaster/Draft]]._ + + + +--- + + + +State: Proposal + + +### palette.gpl or palette.xml (MyPaint proposal) + +Color swatches set (as additional info for editing application) can be saved in palette.gpl in Gimp's .gpl format, or in palette.xml in XML format. XML format should base on [[/SwatchesFileFormatDraft|Specifications/OpenRaster/Draft/Palette/SwatchesFileFormatDraft]]. --Portnov 19:31, 30 September 2009 (UTC) diff --git a/Specifications/OpenRaster/Draft/Palette/SwatchesFileFormatDraft.mdwn b/Specifications/OpenRaster/Draft/Palette/SwatchesFileFormatDraft.mdwn new file mode 100644 index 00000000..5b3d2dc0 --- /dev/null +++ b/Specifications/OpenRaster/Draft/Palette/SwatchesFileFormatDraft.mdwn @@ -0,0 +1,150 @@ +_This page has archived [[discussion threads|Specifications/OpenRaster/Draft/Palette/SwatchesFileFormatDraft/Discussion]]._ + + +# Colour file format - Specification Draft + + +## Example + + <colors xmlns:xlink="http://www.w3.org/1999/xlink"> + <color name="blue"> + <label lang="en">Blue</label> + <label lang="es">Azul</label> + <label lang="en_US_SoCal">glassy</label> + <CMYK space="2ndFloorCMYK" c="0.8703" m="0.6172" y="0" k="0"/> + <Lab space="mine" L="34.67" a="54.1289" b="-103.3359"/> + <HSV space="prof01" h="240" s="1" v="1"/> + <HLS space="prof02" h="240" l="0.5" s="1"/> + <Luv space="prof03" L="34.6701" u="-15.0121" v="-124.7986"/> + <XYZ space="prof04" x="0.1566" y="0.0833" z="0.7196"/> + <Yxy space="prof05" Y="0.0833" x="0.1632" y="0.0869"/> + <Gray space="prof06" g="0.2515"/> + <sRGB r="0" g="0" b="1.0"/> + <RGB space="lcd" r="0.1608" g="-0.1518" b="1.0753"/> + </color><br/> + <color name="red"> + <label lang="en">Red</label> + <CMYK space="2ndFloorCMYK" c="0.0011" m="0.7992" y="0.9405" k="0.0038"/> + <sRGB r="1.0" g="0" b="0"/> + </color><br/> + <colorspace name="2ndFloorCMYK" xlink:href="2nd_floor.icm"/> + <colorspace name="mine" xlink:href="sample.icm"/> + <colorspace name="lcd" xlink:href="generic_lcd.icm"/> + </colors> + +## Colors grouping (a proposal) + +When have many swatches in one file, some type of groups will be needed. Example: + + <group> + <label lang='en'>One group</label> + <color name='red'> + <label lang='en'>Red</label> + <sRGB r="1.0" g="0" b="0"/> + </color> + <group> + <label lang='en'>Nested group</label> + ... + </group> + </group> + <group> + ... + +--Portnov 16:40, 23 September 2009 (UTC) + + +## RelaxNG Compact + + namespace xlink = "http://www.w3.org/1999/xlink" + grammar { + start = element colors { + color+, colorSpace* + } + color = element color { + attribute name { text }, + label *, + (RGB ? & sRGB ? & CMYK ? & Lab ? & HSV ? & HLS ? & Luv ? & XYZ ? & Yxy ? & Gray ? & YCbCr ?) + } + label = element label { + attribute lang { text } ?, + text + } + spaceAttribute = attribute space { text } + RGBAttributes = + attribute r { xsd:float }, + attribute g { xsd:float }, + attribute b { xsd:float } + RGB = element RGB { + spaceAttribute, + RGBAttributes + } + sRGB = element sRGB { + RGBAttributes + } + CMYK = element CMYK { + spaceAttribute, + attribute c { xsd:float }, + attribute m { xsd:float }, + attribute y { xsd:float }, + attribute k { xsd:float } + } + Lab = element Lab { + spaceAttribute, + attribute L { xsd:float }, + attribute a { xsd:float }, + attribute b { xsd:float } + } + HSV = element HSV { + spaceAttribute, + attribute h { xsd:float }, + attribute s { xsd:float }, + attribute v { xsd:float } + } + HLS = element HLS { + spaceAttribute, + attribute h { xsd:float }, + attribute l { xsd:float }, + attribute s { xsd:float } + } + Luv = element Luv { + spaceAttribute, + attribute L { xsd:float }, + attribute u { xsd:float }, + attribute v { xsd:float } + } + XYZ = element XYZ { + spaceAttribute, + attribute x { xsd:float }, + attribute y { xsd:float }, + attribute z { xsd:float } + } + Yxy = element Yxy { + spaceAttribute, + attribute Y { xsd:float }, + attribute x { xsd:float }, + attribute y { xsd:float } + } + YCbCr = element YCbCr { + spaceAttribute, + attribute Y { xsd:float }, + attribute Cb { xsd:float }, + attribute Cr { xsd:float } + } + Gray = element Gray { + spaceAttribute, + attribute g { xsd:float } + } + colorSpace = element colorspace { + attribute name { text }, + attribute xlink:href { xsd:anyURI } + } + } + +### Using for validating + +To use the above !RelaxNG schema to validate a swatch you can use: + + trang -I rnc -O rng colors.rnc colors.rng + xmllint --relaxng colors.rng colors.xml + +## Description of elements and attributes diff --git a/Specifications/OpenRaster/Draft/PngDataRequirements.mdwn b/Specifications/OpenRaster/Draft/PngDataRequirements.mdwn new file mode 100644 index 00000000..00c78e28 --- /dev/null +++ b/Specifications/OpenRaster/Draft/PngDataRequirements.mdwn @@ -0,0 +1,45 @@ + +_This page is part of the [[Draft OpenRaster specification|Specifications/OpenRaster/Draft]]._ + + + +--- + + + +State: Proposal + Affects: [[../FileLayout|Specifications/OpenRaster/Draft/FileLayout]] (addenda) + + +## Proposal: PNG Data Requirements + +The OpenRaster specification should place certain limitations on image data within **.ora** containers in order to ensure that the widest range of applications can open them and display them correctly. + + +### General PNG data requirements + +Current specification: [[../FileLayout|Specifications/OpenRaster/Draft/FileLayout]] + Change: new section + +Unless otherwise specified for a particular kind of PNG data stream in an OpenRaster file; + +* PNG data _should not_ be interlaced (OpenRaster is not a streaming format) +* Applications reading OpenRaster data _should_ read and process colour management chunks present in PNG files [[as described in the PNG specification|http://www.w3.org/TR/PNG/#4Concepts.ColourSpaces]]. + * This specification does not place requirements on how applications should _use_ this colour management information internally. + * It may however express filters or layer blending modes in terms of particular colour spaces. +* Applications writing OpenRaster files _should_ write appropriate colour management chunks to each PNG file in the wrapper. + +### Layer data requirements + +Current specification: [[../FileLayout#data|Specifications/OpenRaster/Draft/FileLayout]] + Change: addendum + +Stored data files for layers should be encoded in PNG format + + +### Thumbnails/thumbnail.png + +Current specification: [[../FileLayout#Thumbnails.2BAC8-thumbnail.png|Specifications/OpenRaster/Draft/FileLayout]] + Change: addendum + +Thumbnail images _should_ be encoded in the sRGB colour space. They should be written with an `sRGB` chunk (and the "Perceptual" rendering intent), and with the canonical `cHRM` and `gAMA` chunks and data values for the sRGB encoding colour space. diff --git a/Specifications/OpenRaster/Draft/UndoHistory.mdwn b/Specifications/OpenRaster/Draft/UndoHistory.mdwn new file mode 100644 index 00000000..f4f76f25 --- /dev/null +++ b/Specifications/OpenRaster/Draft/UndoHistory.mdwn @@ -0,0 +1,17 @@ + +_This page is part of the [[Draft OpenRaster specification|Specifications/OpenRaster/Draft]]._ + + + +--- + + + +State: Proposal + + +### Undo-history + +* OpenRaster file would be able to contain his undo history, like PSD do. This would be useful to continue the editing session in next days or at a later time, without loss anything. +* Any program which does not support Undo-history OpenRaster files, would simply show the last version of the raster and skip the undo commands history. +(Contributions: 13 October 2010 Efa) diff --git a/Specifications/OpenRaster/Draft/VersionNumber.mdwn b/Specifications/OpenRaster/Draft/VersionNumber.mdwn new file mode 100644 index 00000000..b3740c18 --- /dev/null +++ b/Specifications/OpenRaster/Draft/VersionNumber.mdwn @@ -0,0 +1,31 @@ +_This page is part of the [[Draft OpenRaster specification|Specifications/OpenRaster/Draft]]._ + +--- + +State: Proposal + Bug: <https://bugs.freedesktop.org/show_bug.cgi?id=37715> + Bug: <https://bugs.freedesktop.org/show_bug.cgi?id=37717> + Affects: [[../LayersStack|Specifications/OpenRaster/Draft/LayersStack]]. + + +## Version Numbering + +The OpenRaster specification should be versioned, and historical versions should be kept available on this wiki so that developers can refer back to them. `/Specifications/OpenRaster/<version>` would probably be a good place to publish each version when it's finished. + + +### Version number interpretation + +Version numbers have the form `<major>.<minor>` where both _<major>_ and _<minor>_ are integers. No other form should be used; in particular use no form other than dot-separated decimal digits. To compare two version numbers, parse each "`.`"-separated part as a positive integer, and compare corresponding parts numerically. If more parts are found in one version number than the other, the missing parts are to be treated as zero. + +The version number of this initial draft specification is `0.0`. Drafts which succeed released versions of the specification may be given version numbers too; these version numbers will precede the version numbers being drafted. + + +### Layers Stack definition changes + +In order to determine which version of the specification a particular OpenRaster file was created for, applications writing OpenRaster files must store a version code in the root `<image/>` element of the layers stack definition. + + <image version="0.0" w="640" h="480"> + <!-- ... --> + </image> + +* "`version`": this attribute specifies the version of the OpenRaster specification to which the document is conformant. Values are [[xsd:string|http://www.w3.org/TR/xmlschema-2/#string]] type, with a particular format and interpretation as defined in the [[#Version number interpretation|Specifications/OpenRaster/Draft/VersionNumber]] section. This attribute has a default value of "`0.0`". diff --git a/Specifications/OpenRaster/ReferenceLibrary.mdwn b/Specifications/OpenRaster/ReferenceLibrary.mdwn new file mode 100644 index 00000000..71ff2793 --- /dev/null +++ b/Specifications/OpenRaster/ReferenceLibrary.mdwn @@ -0,0 +1,51 @@ + +_This page is part of the [[OpenRaster file format description|Specifications/OpenRaster]]. It has archived [[discussion threads|Specifications/OpenRaster/ReferenceLibrary/Discussion]]._ + + + +--- + + + +At the moment this page serves as a brainstorming sandbox for a [[OpenRaster|Specifications/OpenRaster]] reference implementation (from now on referred to as _libora_). Following [[libpng|http://www.libpng.org/]] as an example it should be written in standard C for easy portability, have a low dependency count and a low memory consumption. + + +## Dependencies + +A list of dependencies (the goal is to use only the really essential ones): + +* [[libpng|http://www.libpng.org/]] - for image encoding/compression +* [[zlib|http://www.zlib.net/]] - for compression +* [[expat|http://expat.sourceforge.net/]] - for XML parsing +* [[exempi|http://libopenraw.freedesktop.org/wiki/Exempi]] - XMP metadata handling + +## License + +Simplified BSD License + + +## Development + +The development repository of _libora_ is located [[here|http://gitorious.org/openraster/libora]]. To build the code you will need (besides the required libraries) the [[CMake|http://www.cmake.org/]] build system. + +The code was so far tested only on Ubuntu 9.10, so expect some initial problems when porting to other platforms (especially Windows and OSX). + + +## Progress + +* What is done? + * Basic opening and saving of documents + * Nested stack support (Tested only for single stack ... probably some bugs here) + * Layer saving for RGBA/RGB 8/16-bit images (tested only for 8-bit) + * oratool is some kind of demonstration/test ... put ORA file in and it reads it, writes it back (layers) and measures time + * oratool: unpacking layers to multiple files - works for PNGs but disabled at the moment +* What will be done + * Thumbnail saving (image provided by the host application) + * oratool: Basic terminal tool for displaying ORA info + * Basic metadata support + * Tiled images saving mechanisms (reduce memory usage for applications that use tiled images) +* What would be nice to do + * Custom layer metadata + * Vector layers, text layers + * Filters +(Contributors: 12 Jan -- 17 Feb 2010 Lukacu diff --git a/Specifications/OpenRaster/ReferenceLibrary/Discussion.mdwn b/Specifications/OpenRaster/ReferenceLibrary/Discussion.mdwn new file mode 100644 index 00000000..f3b4da99 --- /dev/null +++ b/Specifications/OpenRaster/ReferenceLibrary/Discussion.mdwn @@ -0,0 +1,11 @@ + +_This is an archived discussion page from the defunct [[CREATE wiki|http://wayback.archive.org/web/*/http://create.freedesktop.org/]], and is not watched by the original authors. For further discussion of the [[parent page|Specifications/OpenRaster/ReferenceLibrary]] or any other part of the [[OpenRaster specification|Specifications/OpenRaster]], please use the [[mailing list|http://lists.freedesktop.org/mailman/listinfo/create]] instead._ + + +### License + +a exception which explicit allows for static linking would encourage proprietary usage. KaiUweBehrmann 06:07, 22 January 2010 (UTC) + + * agreed. I am not all that familiar with licenses (beyond GPL and LGPL) ... do you recommend something like BSD license perhaps? --Lukacu 09:54, 22 January 2010 (UTC) + * Yes a BSD-style license would allow this (BSD is very short, just read it...). --Maxy 21:44, 4 February 2010 (UTC) + * No problem, I can change the license headers before my next push to the repository --Lukacu 23:57, 4 February 2010 (UTC)
\ No newline at end of file diff --git a/Specifications/OpenRaster/Requirements.mdwn b/Specifications/OpenRaster/Requirements.mdwn new file mode 100644 index 00000000..e15a428e --- /dev/null +++ b/Specifications/OpenRaster/Requirements.mdwn @@ -0,0 +1,55 @@ + +_This page is part of the [[OpenRaster file format description|Specifications/OpenRaster]]._ + + + +--- + + + +(The following is historical information salvaged from the old wiki. It preserves the final text from the Requirements and Challenges sections as of 22 January 2011.) + + +# OpenRaster Requirements + +Following features should be present: + + +## General + +* full freely available documentation +* OpenDocument type of file format (archive with multiple files inside) +* extensible, but private undocumented extensions should be excluded, any extension should be added to the spec and documentation of the file format +* applications aren't expected to support all features of the file format, but when manipulating the file they shouldn't lose any information they can't handle + +### Metadata + +* storage of metadata using {XMP - Dublin Core - IPTC} tags +* possibility to store metadata tags per layer +* storage of EXIF tags +* all text data in Unicode (UTF-8 or UTF-16) + +### Layers + +* storage of multiple layers +* storage of each layer's coordinates +* storage of blending (compositing) options for each layer +* storage of adjustment layers +* storage of layer effects +* groups of layers +* color information - profile, colorspace + +### Other + +* storage of paths, clipping paths, text on path +* selections, masks +* embedding documents within OpenDocument framework +* support undo/history of commands/actions like PSD do + +## Challenges + +A major problem is that because all features aren't available in all the programs, image won't be displayed the same way in different applications, especially for adjustement/filters layers. And "viewer" apps like inkscape or scribus won't have any implementation at all of those features + +A likely work-around is the optional storage of a redundant extra layer containing the fully rendered pixel data as seen after all image processing, or possibly a lower-resolution snapshot of it suitable for previewing and thumbnailing. + +Different implementations levels might be defined, like, tiny, simple, small, normal, full and custom. diff --git a/Specifications/OpenRaster/Utilities.mdwn b/Specifications/OpenRaster/Utilities.mdwn new file mode 100644 index 00000000..a0843528 --- /dev/null +++ b/Specifications/OpenRaster/Utilities.mdwn @@ -0,0 +1,17 @@ + +_This page is part of the [[OpenRaster file format description|Specifications/OpenRaster]]._ + + + +--- + + + +Stuff that could be useful for end users or developers. + + +### Ideas + +* File verificator: verify stack.xml schema, data files, thumbnails against the standard +* Cli tool for doing simple manipulations like extracting layers, packing back into file, moving/reordering/resizing layers, et.c. +* _**Your idea goes here!**_
\ No newline at end of file diff --git a/Specifications/OtherSystems.mdwn b/Specifications/OtherSystems.mdwn new file mode 100644 index 00000000..4a3eabf8 --- /dev/null +++ b/Specifications/OtherSystems.mdwn @@ -0,0 +1,175 @@ +# History and related systems + +This document describes some of the existing MIME database solutions that were around when the [[Shared MIME Database|Specifications/shared-mime-info-spec]] system was devised. The new database sought to unify the GNOME, KDE and ROX databases, while providing a way for applications and new specifications to extend the database. + + +## KDE + +KDE uses '.desktop' files, with Type=Mime``Type, one file per type to determine type from file name. The files are arranged in the filesystem to mirror the two-level MIME type hierarchy. The syntax is very similar to other '.desktop' files, with Name, Comment= etc. + +Example file: + + [Desktop Entry] + Encoding=UTF-8 + MimeType=application/x-kword + Comment=KWord + Comment[af]=kword + [... etc. other translations ] + Icon=kword + Type=MimeType + Patterns=*.kwd;*.kwt; + X-KDE-AutoEmbed=false + + [Property::X-KDE-NativeExtension] + Type=QString + Value=.kwd + +KDE does not have a separate system for specifying extension matches, but uses case-sensitive glob patterns for everything. + +A single file stores all the rules for recognising files by content. This is almost identical to file(1)'s 'magic.mime' database file, but without the encoding field. + +The format is described in the file itself as follows: + + # The format is 4-5 columns: + # Column #1: byte number to begin checking from, ">" indicates continuation + # Column #2: type of data to match + # Column #3: contents of data to match + # Column #4: MIME type of result + +## GNOME + +GNOME uses the gnome-vfs library to determine the MIME type of a file. This library loads name-to-type rules from files with a '.mime' extension in a system-wide directory (set at install time), and merged with those in the user's directory. It loads textual descriptions for the types from files in the same directories, ending with '.keys'. The file 'gnome-vfs.mime' in the system directory is always loaded first (allowing everything else to override it). The file 'user.mime' in the user's directory is always loaded last, making these settings take precedence over all others. + +The format of the .mime files are described as follows: + + # Mime types as provided by the GNOME libraries for GNOME. + # + # Applications can provide more mime types by installing other + # .mime files in the PREFIX/share/mime-info directory. + # + # The format of this file is: + # + # mime-type + # ext[,prio]: list of extensions for this mime-type + # regex[,prio]: a regular expression that matches the filename + # + # more than one ext: and regex: fields can be present. + # + # prio is the priority for the match, the default is 1. This is required + # to distinguish composed filenames, for example .gz has a priority of 1 + # and .tar.gz has a priority of 2 (thus a file having the filename + # something.tar.gz will match the mime-type for tar.gz before the mime-type + # for .gz + # + # The values in this file are kept in alphabetical order for convenience. + # Please maintain this when adding new types. Also consider adding a + # human-readable description to gnome-vfs.keys when adding a new type here. + # + # Also do please not add illegal mime types, observe the mime standard when + # adding new types. + +When looking up the type for a file, gnome-vfs looks first for an exact-case match for the extension, then an all upper-case match, then an all lower-case match. If no matches are found, or there is no '.' in the name, then the regular expression matches are checked. It does this first for rules with priority 2, then for those with priority 1. The modification time on the 'mime-info' directories is used to detect changes. + +The .keys files contain type-to-description rules, eg: + + application/msword + description=Microsoft Word document + [de]description=Microsoft Word-Dokument + ... + +Guidelines for writing descriptions can be found in the 'mime-descriptions-guidelines.txt' file. + +The format for magic entries is defined as: + + # The format of magic entries is: + # + # offset''start[:offset''end] pattern''type pattern [&pattern''mask] type + # + # <offset''start> and <offset''end> are decimal numbers (file offsets). + # + # <pattern_type> is (byte | short | long | string | date | beshort | + # belong | bedate | leshort | lelong | ledate). + # + # <pattern> is an ASCII string with non-printable characters escaped + # as hex or octal escape sequences, and spaces and other important + # whitespace escaped with '\'. + # + # <pattern_mask> is a string of hex digits. The mask must be the same + # length as the pattern. + # + # <type> is a valid MIME type. + # + # Order magic patterns such that ambiguous ones (such as + # application/x-ms-dos-executable) are at the end of the list and + # therefore get applied last. + # + # Avoid rules that require a seek deep into the examined file. If you + # must, locate such rules at the end of the list so that they get + # applied last + # + # When designing new document formats, make them easily recognizable + # by defining a sufficiently unique magic pattern near the document + # start. A good pattern is at least four bytes long and contains one + # or two non-printable characters so that text files won't be + # misidentified. + +## ROX + +Note that ROX is now using the new specification. This section details the previous implementation. + +ROX searches 'MIME-info' directories in CHOICESPATH ('~/Choices/MIME-info:/usr/local/share/Choices/MIME-info:/usr/share/Choices/MIME-info' by default). Files from earlier directories override those in later ones, but the order within a directory is not specified. + +The files are in the same format as GNOME, except: + +* There are no .keys files, so files of all extensions are loaded. +* The priority is ignored. +* A case-sensitive match is tried first, then a lower-case match. No upper-case match is tried. + + application/x-compressed-postscript + ext: ps.gz eps.gz + +When looking up the type for a file, ROX starts with the first '.' and tries a case-sensitive match of the remaining text against the extensions. The it tries again with the filename in lower-case. It then tries again from the second '.', and so on. If no type is found, it tries the regular expressions. + +ROX has no rules for determining a file's type from its contents. + + +## ACAP Media Type Dataset Class + +The ACAP Media Type Dataset Class[ACAP] draft proposes a network-based solution to the problem. The sytem is intended mainly to allow email clients to find a viewer application for an attachment. The draft gives the following example of a record for the 'image/jpeg' type: + + attribute value + --------- ----- + entry JPEG image + mediatype.common.type image/jpeg + mediatype.common.extension jpg + mediatype.common.extensionOther (jpeg jpe jfif jfi) + mediatype.common.description JPEG is an image format most suitable + for compressing photographs + mediatype.common.suppressWarning 1 + mediatype.macOS.type.bin JPEG + mediatype.macOS.creator.bin JVWR + mediatype.macOS.creator.name JPEG View + mediatype.macOS.action.edit.bin 8BIM + mediatype.macOS.action.edit.name Adobe Photoshop + mediatype.unix.action.view xv + +Finding a type involves sending a query to a remote database, which is intended to allow companies to configure MIME information on a company-wide basis. The system is designed to allow a single database to be shared between different platforms. + +It is not designed for handing a large number of lookups quickly, making the system too slow for use in file managers and similar. Both its name and contents matching are more primitive than other systems; only extensions can be matched, case is ignored, and the contents matching can only match an exact string at the start of the file. It provides similar information to this specification, except that it defines many items of platform-specific information in the core specification, instead of using namespacing to allow vendor extensions. + + +## References + +GNOME: The GNOME desktop, [[http://www.gnome.org|http://www.gnome.org]] + +KDE: The KDE desktop, [[http://www.kde.org|http://www.kde.org]] + +ROX: The ROX desktop, [[http://rox.sourceforge.net|http://rox.sourceforge.net]] + +Desktop``Entries: Desktop Entry Specification, [[http://www.freedesktop.org/standards/desktop-entry-spec.html|http://www.freedesktop.org/standards/desktop-entry-spec.html]] + +SharedMIME: Shared MIME-info Database, [[http://www.freedesktop.org/standards/shared-mime-info-spec|http://www.freedesktop.org/standards/shared-mime-info-spec]] + +ACAP: ACAP Media Type Dataset Class, [[ftp://ftp.ietf.org/internet-drafts/draft-ietf-acap-mediatype-01.txt|ftp://ftp.ietf.org/internet-drafts/draft-ietf-acap-mediatype-01.txt]] + +-- Main.[[ThomasLeonard|ThomasLeonard]] - 09 Oct 2003 diff --git a/Specifications/StatusNotifierIcon.mdwn b/Specifications/StatusNotifierIcon.mdwn new file mode 100644 index 00000000..56fbf080 --- /dev/null +++ b/Specifications/StatusNotifierIcon.mdwn @@ -0,0 +1,8 @@ + + +# StatusNotifierIcon + +Draft Specs and Ideas: + +* [[http://www.notmart.org/misc/statusnotifieritem/index.html|http://www.notmart.org/misc/statusnotifieritem/index.html]] +* [[https://wiki.ubuntu.com/DesktopExperienceTeam/ApplicationIndicators|https://wiki.ubuntu.com/DesktopExperienceTeam/ApplicationIndicators]]
\ No newline at end of file diff --git a/Specifications/SystrayAndAppletsMeeting.mdwn b/Specifications/SystrayAndAppletsMeeting.mdwn new file mode 100644 index 00000000..2f961276 --- /dev/null +++ b/Specifications/SystrayAndAppletsMeeting.mdwn @@ -0,0 +1,47 @@ + +Notes from the Systray and Panel Applets meeting: + +* Just for minimizing is the wrong approach - use the taskbar +* What should (and shouldn't) be the systray? + * This is made more difficult to control because of the literal representation of a system tray item as an actual icon. + * having a "systray" that is really nothing more than information published on an IPC bus would make splitting up the functions into the taskbar, the systray or other presentation mechanisms a matter of policy defined by the host application rather than by the application publishing the system tray item/icon. this allows greater flexibility today and in the future by not tieing ourselves down to a specific interpretation of how it should look and how the user should be allowed to interact with it, but by simply defining the actual information that needs to be presented and communicated between the host application (e.g. the desktop panel) and the application associated with the systray entry. +* Provide a menu like the OS X dock in the taskbar +* Current uses: + * minimization (bad?) + * notifications + * new mail + * software updates + * cross desktop applets (since the tray is cross-desktop) + * visible daemons + * marketing (yes, it's actually there and working) +* cross desktop applications needs to be fixed +* notifications need to be fixed? +* redefine the current spec to be more purposeful and focused, and promote panel applets instead + * a better design than the current OOP icons via XEmbed is needed for the various reasons noted at [[http://aseigo.bddf.ca/?pID=1092|http://aseigo.bddf.ca/?pID=1092]] (and probably other reasons too =) +* how to make cross-platform applets + * Add applet menu + * .desktop file + * [[ShowOnlyIn|ShowOnlyIn]]= etc is required + * Menu merge + * panel provides standard items to applet to merge into its menu + * Size negotiation + * max useful size + * min useful size + * orientation + * use X calls to do negotiation (XEmbed related?) + * Life Cycle + * .so? - use proxy + * desktop looks like (for a GNOME applet): + * Exec=gnome-applet-wrapper --applet=foo.so X-GNOME-Applet=foo.so (for KDE) + * Exec=kappletproxy --applet=foo.so # or whatever we call it X-KDE-Applet=foo.so + * two paths, one panel is in charge, the other the panel is in charge (for activation) + * d-bus service for activation + * Saving config + * sometimes deleting an applet should delete config, sometimes it should not + * Middle-click move? + * shouldn't interaction policies be up to the host application? -AJS +* Breaking Up the Systray into the Taskbar and Individual Applets + * the systray is a well-known concept to users and developers, and one that isn't completely broken if done properly + * the taskbar should be for management of windows, not all items in the systray map cleanly to windows. if we simply add systray icons to the taskbar when no window for it exists, we start to confuse the purpose of the taskbar which leads to a confusing and unclear (read: not usable) interface for users. the MacOS X dock is rife with these issues, and users tend to struggle with it because of that. + * the taskbar currently has flexibility that remove the guarnatee that you can always see these icons/menus (such as "only show windows on the current desktop" or "show only minimized windows"). so we either limit the taskbar, or we lose one of the benefits of the systray: constant and universal visibility. trying to present two separate concepts in the same gui leads to making both less expressive. + * moving the systray into individual applets means, really, just making little individual systrays. systrays with one icon each, if you will.
\ No newline at end of file diff --git a/Specifications/XDND.mdwn b/Specifications/XDND.mdwn new file mode 100644 index 00000000..b57ef5b1 --- /dev/null +++ b/Specifications/XDND.mdwn @@ -0,0 +1,440 @@ + + +# Drag-and-Drop Protocol for the X Window System + +[[!toc 2]] + +This page was created from Google's cache of [[http://www.newplanetsoftware.com/xdnd/|http://www.newplanetsoftware.com/xdnd/]]. It needs reformatting. + +Note: While almost all modern applications that support drag and drop try to follow this standard, there are a number of common errors that have led to a large number of interoperability problems in the past. Please check your programs against programs from several other desktops to help ensure you have followed the standard correctly. See this document for a list of common mistakes: + + * [[Drag and drop warts|Draganddropwarts]] + +# Contents + + +## Introduction + +Today, Drag-and-Drop (DND) is considered a requirement for commercial-quality applications. On most operating systems, support for DND is built-in, so everybody uses it and all programs can communicate with each other. + +On X, however, there is no standard, so various groups have developed their own protocols, with the result that programs written for one protocol cannot talk to programs written for a different protocol. Clearly this does not satisfy the fundamental requirement that DND allow the user to drag data from any program to any other program. + +What is required is a single protocol that everybody can use so all programs can exchange data via DND. (The X Selection mechanism insures that everybody can exchange data via the clipboard.) + +The basic requirements for such a protocol are that it provide visual feedback to the user during the drag and that it allow the target to choose whatever data format it prefers from among all the formats that the source can provide. In addition, it must be efficient so that the visual feedback does not lag behind the user's actions, and it must be safe from deadlock, race conditions, and other hazards inherent in asynchronous systems. + +Current version: 5 Last updated on April 5, 2003 + + +## Definitions + +The **source** is the window that will supply the data. + +The **target** is the window that the cursor is on top of and which will receive the drop if the mouse is released. + +You should be familiar with the **X Selection** mechanism described in the Xlib manuals: Volume 0, Appendix L and Volume 1, Chapter 10. + +All data types and actions are referred to by their corresponding **X Atoms**. The atom names of the data types are the corresponding [[MIME types|ftp://ftp.isi.edu/in-notes/iana/assignments/media-types/]], in all lower case. (RFC's for MIME: [[!RFC 2045 desc="2045"]], [[!RFC 2047 desc="2047"]], [[!RFC 2048 desc="2048"]], [[!RFC 2049 desc="2049"]]) + +All constants mentioned in this document are the string names of X atoms, capitalized as shown. This avoids the need for hard-coded values, which would require a global registry. + + +## Example walk-through + +**Note:** Parenthesized numbers in bold-face are the number of packets sent to or from the server. + + +### Step 0: + +Windows announce that they support the XDND protocol by creating a window property `XdndAware`. + + +### Step 1: + +When a drag begins, the source takes ownership of `XdndSelection`. + +When the mouse enters a window that supports XDND (search for window property: avg **8**), the source sends a `ClientMessage` of type `XdndEnter` (**2**) which contains the protocol version to use and the data types supported by the source. + +An extension has been developed to allow dropping on other windows. + + +### Step 2: + +The target receives `XdndEnter`. + +The `ClientMessage` only has space for three data types, so if the source supports more than this, the target must retrieve the property `XdndTypeList` from the source window in order to get the list of available types. (**2**) + + +### Step 3: + +The source sends a `ClientMessage` of type `XdndPosition`. (**2**) This tells the target the position of the mouse and the action that the user requested. + + +### Step 4: + +The target receives `XdndPosition`. + +The target window must determine which widget the mouse is in and ask it whether or not it will accept the drop. For efficiency, the target window should keep track of whether or not the widget will accept the drop and only ask again if the action changes or the mouse enters a different part of the widget. Once the widget has said that it will accept the drop and as long as the action remains the same and the mouse remains in the same part, the widget gets all the `XdndPosition` messages so that it can re-draw itself to show the user where the data will be inserted, if appropriate. + +To determine whether or not it can accept the drop, the target widget consults the list of types from the `XdndEnter` message and the requested action from the `XdndPosition` message. + +If it cannot perform the requested action, it can return either `XdndActionCopy` or `XdndActionPrivate`. If neither of these are possible, then it should refuse the drop. + +If it needs to look at the data itself, it calls `XConvertSelection()` for `XdndSelection`, the data type that it is interested in, and the given time stamp. (**7**) It can do this more than once, if necessary. + +If it can accept the drop, it should hilight its border to notify the user. If it retrieved the data, it should cache it so it does not need to be retrieved again when the actual drop occurs. + + +### Step 5: + +The target sends a `ClientMessage` of type `XdndStatus`. (**2**) This tells the source whether or not it will accept the drop, and, if so, what action will be taken. It also includes a rectangle that means "don't send another `XdndPosition` message until the mouse moves out of here". + + +### Step 6: + +The source receives `XdndStatus`. It can use the action to change the cursor to indicate whether or not the user's requested action will be performed. + +When the mouse moves out of the given rectangle, go to Step 3. + +`XdndPosition` messages are normally triggered by `MotionNotify` events. However, if the mouse moves while the source is waiting for an `XdndStatus` message, the source has to cache the new mouse position and generate another `XdndPosition` message as soon as it receives the `XdndStatus` message. (This will be necessary when the server-target connection is much slower than the server-source connection.) + + +### Step 7: + +If the mouse leaves the window, the source sends a `ClientMessage` of type `XdndLeave`. (**2**) + +If the mouse button is released in the window, the source waits for the last `XdndStatus` message (if necessary) and then sends a `ClientMessage` of type `XdndLeave` or `XdndDrop`, depending on the "accept" flag in the last `XdndStatus`. (**2**) + +If the source never received any `XdndStatus` messages at all, it should send `XdndLeave` without waiting. + +If the source doesn't receive the expected `XdndStatus` within a reasonable amount of time, it should send `XdndLeave`. While waiting for `XdndStatus`, the source can block, but it must at least process `SelectionRequest` events so the target can examine the data. + + +### Step 8: + +If the target receives `XdndLeave`, it frees any cached data and forgets the whole incident. + +If the target receives `XdndDrop` and will accept it, it first uses `XConvertSelection()` to retrieve the data using the given time stamp (if it doesn't already have it cached). (**7**) It then uses the data in conjunction with the last action and mouse position that was acknowledged via `XdndStatus`. (Over a slow network, this makes the drop location consistent with the visual feedback given to the user.) Once it is finished, it sends `XdndFinished`. + +If the target receives `XdndDrop` and will not accept it, it sends `XdndFinished` and then treats it as `XdndLeave`. + + +## Theory + +Every part of this protocol serves a purpose: + + +### XdndAware + +In order for the user to be able to transfer data from any application to any other application via DND, every application that supports XDND version N must also support all previous versions (3 to N-1). The `XdndAware` property provides the highest version number supported by the target (Nt). If the source supports versions up to Ns, then the version that will actually be used is min(Ns,Nt). This is the version sent in the `XdndEnter` message. It is important to note that `XdndAware` allows this to be calculated before any messages are actually sent. + +The property can also act as an extra filter, because it can contain a list of types accepted by the target, as explained in the Technical Details section. + +It is also critical for scrolling (see Notes section below) and for coexisting with other DND protocols (since one can try something else if `XdndAware` is not present) and is useful for debugging since it lets one check the target's XDND version, after which one can expect to receive an `XdndStatus` message. + + +### X Selection + +By using `XConvertSelection()`, one can use the same data conversion code for both the Clipboard and Drag-and-Drop. This is an especially large saving if the target requests the type `MULTIPLE` or if the source is forced to send the data incrementally (type `INCR`). It also makes checking the data independent of the main sequence of messages, so `XdndStatus` correctly reports "yes" or "no" the first time. + +By using `XdndSelection`, the dropped data doesn't interfere with the clipboard data stored in `XA_PRIMARY`. + +Using `XConvertSelection()` does have the problem that the user can begin dragging something else before the data transfer is complete. However, the X clipboard has the same problem, so this doesn't impose any additional constraints on the user, and it can be avoided as explained below in the discussion of the `XdndFinished` message. + + +### Actions + +Specifying the action separately from the data type allows one to avoid defining N*M atoms for N data types and M actions. Since the user must have full control of what will happen, exactly one action is specified by the source. This is passed in the `XdndPosition` message to allow it to change during the drag. (e.g. if the user presses or releases modifier keys) The action accepted by the target is passed back in the `XdndStatus` message to allow the source to provide feedback in the cursor. + +The special action `XdndActionAsk` tells the target that it should ask the user what to do after the drop occurs. This allows one to implement the effect obtained by right-dragging in Windows95(R), where the file manager asks the user whether to move, copy, create a link, or cancel. The list of actions is retrieved from the `XdndActionList` property, and the description of each action that is shown to the user is retrieved from the `XdndActionDescription` property, both on the source window. Note that the user should be asked before retrieving the data and thus also before sending `XdndFinished`. + +The special action `XdndActionPrivate` tells the source that the target will do something that the source doesn't understand and that won't require anything from the source other than a copy of the data. + + +### Messages + +The `XdndEnter` message initiates the session and gives the target a chance to set up local variables such as the transformation from root window coordinates to target window coordinates. It also provides a list of supported data types so the target doesn't have to call `XConvertSelection()` for `XdndSelection`, `TARGETS`. + +The `XdndPosition` message provides mouse locations so that the target does not have to query the X server in order to redraw itself properly. There is no other reliable way for the target to get the mouse location because X will force the cursor to be grabbed by the source window, so only the source window will be receiving events. The target needs the mouse location because it has to update itself to show where the data will be inserted. This is especially important in text editors, spreadsheets, and file managers. + +The time stamp in the `XdndPosition` message must be passed to `XConvertSelection()` to insure that the correct data is received. + +The `XdndStatus` message provides feedback to the source (e.g. it might want to change the cursor) and insures that `XdndPosition` messages do not pile up when the network connection is slow. + +The `XdndLeave` message cancels the session. + +The `XdndDrop` message tells the target to proceed with the drop. The time stamp must be passed to `XConvertSelection()` to insure that the correct data is received. + +The `XdndFinished` message tells the source that the target is done and no longer needs the data. This allows the source to implement any one of three different behaviors: + +* Block until the message is received. In this case, the source must be prepared to time out in case the target malfunctions and must reject outdated requests. +* Don't block and reject outdated requests by comparing the time when the selection was last acquired with the timestamp in the selection request. (which comes from the `XdndDrop` message) +* Don't block and keep a history of previous data. This can be very difficult to implement, but it is clearly the ideal behavior from the user's perspective because it allows him to drop something and then continue working with the assurance that the target will get the data regardless of how slow the network connections are. +When the source receives `XdndFinished`, it can remove the item from its history, thereby keeping it from getting too large. The source must also be prepared to throw out extremely old data in case a target malfunctions. + + +### Protecting against malfunctioning programs + +If the version number in the `XdndEnter` message is higher than what the target can support, the target should ignore the source. + +While the source and target are receiving XDND messages from each other, they should ignore all XDND messages from other windows. + +If either application crashes while DND is active, the other application must avoid crashing on a `BadWindow` error. The only safe way to do this is to actually catch the error by installing an error handler with `XSetErrorHandler()`. In addition, the target must also listen for `DestroyNotify` events so that it doesn't wait forever for another `XdndPosition` if the source crashes between receiving `XdndStatus` and sending `XdndPosition`. + +* If the target crashes, the source will automatically receive another `EnterNotify` event, as if the mouse had moved. Any `XdndPosition` in the network will generate a `BadWindow` error. +* If the source crashes, the target should treat it like `XdndLeave`. +As discussed above, the source must be careful to avoid locking up if the target does not send `XdndFinished`. + + +## Notes + +When the source and target are the same, the drop should be hysteretic within a region around the source window. (e.g. a 50 pixel border) The target remains the source as long as the mouse doesn't move into another widget that is willing to accept the drop. This makes it much easier for the user to drop the data on an invisible part of the source because dragging the mouse out onto the root window or a stray xterm will cause the source to scroll. The `XdndAware` property makes hysteresis possible because the root window, stray xterms, and especially the window border created by the window manager are ignored. + +We are collecting examples to show DND might work in various cases. Dragging text is straightforward since there are several well-known formats, including `text/plain` and `text/enriched`. Dragging files is at least equally important. + +We have also developed extensions that allow dropping on the root window and on windows that do not support XDND. + +`XdndActionLink` only makes sense within a single program or between cooperating programs because the target must obtain not only the data, but also the location of the data. In all other cases, the target should respond with `XdndActionCopy` or `XdndActionPrivate` in the `XdndStatus` message. + +On the other hand, `XdndActionAsk` makes equally good sense between unrelated programs and cooperating programs. However, when the source and target are unrelated, the target may choose to provide a list of actions that it can perform on its own after retrieving the data instead of asking the source for a list of actions. + +Remember also that you must debounce the mouse drag. If the user moves the mouse by only a couple of pixels while clicking to select something, then it is far more likely that the user is a bit clumsy than that the user intends to start a drag. A threshold of 3 pixels is typical. + + +### Getting up on my soap box... + +In my opinion, programs should not change the cursor during the drag because this provides the user with the most consistent picture. The user is always dragging the same data, regardless of whether or not the current target will accept it. It is the target that should change to show whether or not it will accept the drop. + +However, if you want to be Microsoft compliant, you have to change the cursor. As usual, Microsoft got it backwards... + +As a side note, on page 253 of his book, About Face, Alan Cooper agrees wholeheartedly. + +The single exception that I endorse is adding a small symbol to the cursor to show that the requested action will be performed, instead of `XdndActionPrivate`. For an example, refer to the page on dragging files. + + +## Optimizations + +When the source and target windows are part of the same application, sending X Client Messages is a waste of time and bandwidth, especially if the program and server are on different machines. Implementations should therefore detect the special cases of "source = target" and "source and target in same application" and handle them via function calls. + +To avoid calling `XConvertSelection()` in the above cases: + +* There is no need to examine the data when "source = target" because the source must know what it is dragging. +* If the actual call to `XConvertSelection()` is hidden behind an interface, then when the source and target are in the same application, the interface can simulate the call without going to the server. +Targets do not have to retrieve `XdndTypeList` from the source window if they find what they are looking for in the three types listed in the XdndEnter message. + +It is pointless to send XdndPosition messages when the mouse is stationary. + +To avoid unnecessary messages from the source to the server, one should only change the cursor when the target or status (acceptance and action) changes. + +Unfortunately, one cannot avoid calling `XTranslateCoordinates()` continuously, because of overlapping windows. + + +## Technical details + +Current version: 5 + +All constants mentioned below are the string names of X atoms, capitalized as shown. This avoids the need for hard-coded values, which would require a global registry. + + +## Atoms and Properties + + +### XdndAware + +This window property must be of type `XA_ATOM` and must contain the highest version number of the protocol supported by the target. (Version numbers start at zero. The maximum version number is `0xFF` because there is only one byte allocated for it in the `XdndEnter` message. At one new version every three months, which is very rapid turnover, this will last 64 years.) + +The property must be set on each top-level X window that contains widgets that can accept drops. (new in version 3) The property should not be set on subwindows. The target must dispatch the messages to the appropriate widget. Since window managers often insert extra layers of windows, this requires searching down the subwindow tree using `XTranslateCoordinates()`. + + +### XdndSelection + +This is the name of the X Selection that is used when the target wants to examine the data during the drag phase and when it wants to retrieve the data after a drop. + + +### Data types + +All data types are referred to by their corresponding X Atoms. The atom names are the corresponding MIME types, in all lower case. (RFC's for MIME: [[!RFC 2045 desc="2045"]], [[!RFC 2047 desc="2047"]], [[!RFC 2048 desc="2048"]], [[!RFC 2049 desc="2049"]]) + +For text, the charset attribute can be appended to the MIME type. (e.g. `Japanese` -> `text/plain;charset="ISO-2022-JP"`) If the charset attribute is not specified, it is assumed to be `ISO-8859-1`. (new in version 4) + +Note that any data type may be transferred via the `INCR` protocol. + + +### XdndTypeList + +If the source supports more than 3 data types, this window property must be set on the source window, must be of type `XA_ATOM`, and must contain a list of all the supported data types. + + +### Actions (new in version 2) + +All actions are referred to by their corresponding X Atoms. The predefined actions are + +* `XdndActionCopy` +* `XdndActionMove` +* `XdndActionLink` +* `XdndActionAsk` +* `XdndActionPrivate` +The `XdndAction` prefix is reserved for future expansion, but any other name can be used for other actions as long as both the source and the target recognize it and agree on what it means. The predefined atom None is not allowed as an action. + +The default is `XdndActionCopy`, and this is assumed to be the action when using version 0 or 1. + +In general, `XdndActionMove` is implemented by first requesting the data and then the special target `DELETE` defined in the X Selection protocol. (File managers will obviously just use mv or its equivalent.) `DELETE` should be sent before `XdndFinished`. + +Refer to the Theory and Notes sections for more information. + + +### XdndActionList (new in version 2) + +If the source sends `XdndActionAsk`, this window property must be set on the source window, must be of type `XA_ATOM`, and must contain a list of all the supported actions. The first one should be the default so the user doesn't have to change the selection in the radio group too often. + + +### XdndActionDescription (new in version 2) + +If the source sends `XdndActionAsk`, this window property must be set on the source window, must be of type `XA_STRING`, and must contain a list of ASCII strings separated by NULL's that the target should display when describing the choices to the user. These strings must be in the same order as the atoms in the `XdndActionList` property. + +The option to cancel the operation must always be provided in the dialog displayed to the user, via a Cancel button, but should not be included in `XdndActionList`. + + +### XdndProxy (new in version 4) + +If this window property exists, it must be of type `XA_WINDOW` and must contain the ID of the proxy window that should be checked for `XdndAware` and that should receive all the client messages, etc. In order for the proxy window to behave correctly, the appropriate field of the client messages, window or `data.l[0]`, must contain the ID of the window in which the mouse is located, not the proxy window that is receiving the messages. The only place where the proxy window should be used is when checking `XdndAware` and in the calls to `XSendEvent()`. + +The proxy window must have the `XdndProxy` property set to point to itself. If it doesn't or if the proxy window doesn't exist at all, one should ignore `XdndProxy` on the assumption that it is left over after a crash. + + +## Client Messages + +Note: All unused flags must be set to zero in every message. This allows one to define new flags without incrementing the version number. + + +### XdndEnter + +Sent from source to target when the mouse enters a window that supports XDND. + +* `data.l[0]` contains the XID of the source window. +* `data.l[1]`: + * Bit 0 is set if the source supports more than three data types. + * The high byte contains the protocol version to use (minimum of the source's and target's highest supported versions). + * The rest of the bits are reserved for future use. +* `data.l[2,3,4]` contain the first three types that the source supports. Unused slots are set to None. The ordering is arbitrary since, in general, the source cannot know what the target prefers. + +If the Source supports more than three data types, bit 0 of `data.l[1]` is set. This tells the Target to check the property `XdndTypeList` on the Source window for the list of available types. This property should contain all the available types. + + +### XdndPosition + +Sent from source to target to provide mouse location. + +* `data.l[0]` contains the XID of the source window. +* `data.l[1]` is reserved for future use (flags). +* `data.l[2]` contains the coordinates of the mouse position relative to the root window. + * `data.l[2] = (x << 16) | y` +* `data.l[3]` contains the time stamp for retrieving the data. (new in version 1) +* `data.l[4]` contains the action requested by the user. (new in version 2) + +### XdndStatus + +Sent from target to source to provide feedback on whether or not the drop will be accepted, and, if so, what action will be taken. + +* `data.l[0]` contains the XID of the target window. (This is required so `XdndStatus` messages that arrive after `XdndLeave` is sent will be ignored.) +* `data.l[1]`: + * Bit 0 is set if the current target will accept the drop. + * Bit 1 is set if the target wants `XdndPosition` messages while the mouse moves inside the rectangle in `data.l[2,3]`. + * The rest of the bits are reserved for future use. +* `data.l[2,3]` contains a rectangle in root coordinates that means "don't send another `XdndPosition` message until the mouse moves out of here". It is legal to specify an empty rectangle. This means "send another message when the mouse moves". Even if the rectangle is not empty, it is legal for the source to send `XdndPosition` messages while in the rectangle. The rectangle is stored in the standard Xlib format of (x,y,w,h): + * `data.l[2] = (x << 16) | y` + * `data.l[3] = (w << 16) | h` +* `data.l[4]` contains the action accepted by the target. This is normally only allowed to be either the action specified in the `XdndPosition` message, `XdndActionCopy`, or `XdndActionPrivate`. None should be sent if the drop will not be accepted. (new in version 2) + +### XdndLeave + +Sent from source to target to cancel the drop. + +* `data.l[0]` contains the XID of the source window. +* `data.l[1]` is reserved for future use (flags). + +### XdndDrop + +Sent from source to target to complete the drop. + +* `data.l[0]` contains the XID of the source window. +* `data.l[1]` is reserved for future use (flags). +* `data.l[2]` contains the time stamp for retrieving the data. (new in version 1) + +### XdndFinished (new in version 2) + +Sent from target to source to indicate that the source can toss the data because the target no longer needs access to it. + +* `data.l[0]` contains the XID of the target window. +* `data.l[1]`: + * Bit 0 is set if the current target accepted the drop and successfully performed the accepted drop action. (new in version 5) (If the version being used by the source is less than 5, then the program should proceed as if the bit were set, regardless of its actual value.) + * The rest of the bits are reserved for future use. +* `data.l[2]` contains the action performed by the target. None should be sent if the current target rejected the drop, i.e., when bit 0 of `data.l[1]` is zero. (new in version 5) (**Note:** Performing an action other than the one that was accepted with the last `XdndStatus` message is strongly discouraged because the user expects the action to match the visual feedback that was given based on the `XdndStatus` messages!) + +## Sample implementation + +If you are interested in supporting this protocol, but daunted by having to start from scratch, you can obtain sample C++ code via anonymous ftp. This code may be used under any license. + +Paul Sheer has implemented XDND v2 in C as a generic library. The files are xdnd.c and xdnd.h + +If you use a different language, please consider donating your code for others to look at. + +We also have a binary that you can use to test interoperability between a correct implementation and your implementation. + +While implementing this protocol, you may find it very useful to use the programs `xlsatoms` to list all the atoms that the server knows about, `xprop` to list all the properties on a particular window, and `xscope` to study the timing of events. + +Even if you implement XDND from scratch, we would appreciate it if your distribution included some sort of documentation that states clearly that you are supporting this protocol and provides a reference to this web page. This will help get the snowball rolling. The more programs that support the same protocol, the more useful Drag-and-Drop will be for the users. If you tell us that you support the protocol, we will also add you to the list of supporters. + + +## Changes from previous versions + +December 25, 2002: + + * Version 5 adds additional information to the XdndFinished message in order to allow the Java DND API to be implemented on top of XDND. (Thanks to Danila A. Sinopalnikov for working out the details.) +August 31, 2002: + + * Added requirement to File Dragging protocol. The user name must be provided via the new text/x-xdnd-username data type. +November 21, 2000: + + * Thanks to Daniel Biddle for pointing out that the MIME types should be specified in the format ISO-8859-1, not iso8859-1. +October 26, 2000: + + * Minor modifications to actions required by File Dragging protocol. +February 22, 2000: + + * Added additional notes about why the host name must always be included when dragging files. +June 7, 1999: + + * Version 4 adds XdndProxy window property to support the new protocol for dropping on the root window. Rewrote the protocol for dropping on the root window to conform to the latest implementations. Added note in Technical Details section about how to specify the character set for text. Created Direct Save (XDS) protocol layered on top of XDND. +December 1, 1998: + + * Rewrote the protocol for dropping on the root window to conform to the latest implementations. +September 19, 1998: + + * The File Dragging protocol now uses the well established text/uri-list instead of url/url. Added note to Optimization section about caching the window stack. +September 7, 1998: + + * Version 3 changes the way XdndAware is handled. To reduce the number of !XTranslateCoordinates() calls to the X server and to make life easier for programs that use multiple X windows per widget, XdndAware must now be placed on the top-level X window, not on subwindows. This change is unfortunately incompatible with previous versions. However, since there are still relatively few programs that have been released with XDND support, the specification has simply been adjusted so XDND compliance only requires supporting version 3 and up. (This will never happen again!) In addition, Jeroen van der Zijp has invented an extension that allows dropping onto windows that do not support XDND, and Arnt Gulbrandsen has developed a way to drop on the root window. +August 17, 1998: + + * Version 2 adds the following features: +* The concept of an action. Previously, only copy was supported. Now, the source can specify any action, and the target can either accept it or fall back on copy or private. The predefined actions are XdndActionCopy (the default), XdndActionMove, XdndActionLink, XdndActionAsk, and XdndActionPrivate. Ask tells the target to get a list of acceptable actions from the source's XdndActionList and XdndActionDescription window properties and then ask the user which one to perform. +* The target is required to send XdndFinished. (Yes, I caved in :) However, if the source blocks, it must be prepared to time out in case the target is malfunctioning. Ideally, the source will not need to block because it will keep a history of past selections. The timestamp in XdndDrop allows the source to safely avoid both blocking and keeping a history by simply rejecting outdated requests. + * Part of the reason for adding XdndFinished is that this allows XDND to be used with higher level API's (e.g. JavaBeans) that require notification of the end of the operation. + * With these new features, the File Dragging protocol becomes much simpler. Added page of supporters. +February 25, 1998: + + * Added examples of how XDND fits into the larger picture of cooperating applications. +February 24, 1998: + + * Added trashcan discussion to the File Dragging protocol. +February 2, 1998: + + * Version 0 has a hole. If the user begins a second drag from the same source before the data has been transferred to the first target (over a really slow network, obviously), then the first target may get the wrong data. Thanks to Donal K. Fellows for pointing this out. Version 1 fixes this by adding a time stamp to XdndPosition and XdndDrop which must be used when requesting the data. This way, if the user quickly begins a second drag, the first target will at least get no data instead of the wrong data. Please refer to the Theory section for a more complete discussion and the reasons why this was not fixed by adding a "drop finished" message. +January 28, 1998: + + * Added comparison to Xde. + +## Acknowledgements + +This protocol was developed by John Lindal at New Planet Software, with help from Glenn Bach and lots of feedback from Arnt Gulbrandsen at Troll Tech and Owen Taylor of GTK+ and input from Elliot Lee at Red Hat Software. diff --git a/Specifications/XDNDRevision.mdwn b/Specifications/XDNDRevision.mdwn new file mode 100644 index 00000000..5a203d01 --- /dev/null +++ b/Specifications/XDNDRevision.mdwn @@ -0,0 +1,24 @@ + +Notes from XDND round-table at XDevConf 2005: + +- ordering of types + + * - Not specified, but qt implements it - would be good if everyone supported it. higher priority are chosen first. This fixes dropping content onto file browser (gedit->konqi, etc) +- text encodings - apps do educated guess? + + * - Defined UTF-8 as encoding for text content? + * - Ability to provide other encodings too? - Backwards compat issue - Put charset/encoding into the mimetype? (text/html:utf-8) +- Mini spec (registry) of how to do various encodings needs to be created + +- suggested filenames + + * - (using zip/tar? .. text/html@zip) - performance with tar/zip? + * - OASIS? - needs experiments - remote X server could be slow, but worth the effort? +- applying to uri-list drag + + * - problem of remote clients ([[file:/|file:/]] not valid on the other host) - hostname not implemented well + * - applying uri-list with second target of content is not implemented anywhere but a possible solution (the ROX applications support this for single-file drags using application/octet-stream, but you have to turn off "Don't use hostnames" in the Compatibility box, which breaks some other applications) - alternative having a second response saying "give me the content" - uuid to make hostname issue easier to deal with +- kio copying uri list - how to know who owns + + * - Qt problem - doesn't expose ability to say "I'm done, do your delete" - basically a UI problem during long operations - XDS is a solution? +See also [[Draganddropwarts|Draganddropwarts]]. diff --git a/Specifications/XDS.mdwn b/Specifications/XDS.mdwn new file mode 100644 index 00000000..d4d41dc6 --- /dev/null +++ b/Specifications/XDS.mdwn @@ -0,0 +1,129 @@ + + +## Saving Files Via Drag-and-Drop: The Direct Save Protocol for the X Window System + +[[!toc ]] + +This document was created from Google's cache of [[http://www.newplanetsoftware.com/xds/|http://www.newplanetsoftware.com/xds/]]. + + +## Introduction + +The Direct Save Protocol (XDS) builds on top of the [[XDND|XDND]] protocol to allow users to save a file by simply dragging it to a file manager window, thereby avoiding the necessity of having a directory browser in each application's Save File dialog. + +Current version: 0 Last updated on June 7, 1999 + +[[Supporters of the XDS protocol|http://www.newplanetsoftware.com/xds/supporters.html]] + + +## Example walk-through + +Note: Parenthesized numbers in bold-face are the number of packets sent to or from the server. + + +### Step 0: Before the drop + +Before the drag begins, the source creates a window property `XdndDirectSave` on itself of type `text/plain` (including the charset attribute, if necessary) that contains the file name (without a path) in which the user wants to save. + +The source should specify the action `XdndActionDirectSave`. + +When the file manager receives `XdndPosition`, it should only accept the drop if the target directory is writable. If the mouse is over the icon or name of a writable directory, this is the target, and the icon should be highlighted. Otherwise, the target is the directory whose contents are displayed in the window. Since continuous feedback is provided to the source, this will not cause problems even if the window's directory is not writable and some of its subdirectories are writable. + + +### Step 1: Drop is send + +When the file manager received `XdndDrop`, it should first check for `XdndDirectSave`. If this is not provided, it should fall back on `text/uri-list`. + +If it finds the `XdndDirectSave` target, it retrieves the data from the source window's `XdndDirectSave` property (**2**), converts it to a URL (e.g. `name` -> `file://host/path/name`), places this in the `XdndDirectSave` property (**2**), changes the type to match the character set (if necessary), and requests `XdndDirectSave` from the source. (**7**) + + +### Step 2: Transmit source location + +The source receives the request for `XdndDirectSave`, retrieves the data from its `XdndDirectSave` property (**2**), and tries to save the data to the specified location. + +If successful, it responds to the target's request with data of type `XA_STRING` containing the single character `S (0x53)`, indicating success. It then waits for the file manager to respond further. + +If it would like to use the specified location but cannot because it is on a different machine, it responds with data of type `XA_STRING` containing the single character `F (0x46)`, indicating failure. It then waits for the file manager to respond further. + +If it refuses to save the data in the specified location (e.g. it does not allow saving on a different machine because the file's contents are not relocatable), it responds with data of type `XA_STRING` containing the single character `E (0x45)`, indicating an error. + + +### Step 3: Status code exchange + +The file manager receives the result. + +If it receives `S`, it refreshes its display to show the new file and then sends `XdndFinished`. + +If it receives `F`, it checks for the data type `application/octet-stream`. If this is available, it retrieves it and tries to save the file itself. If successful, it refreshes its display. Otherwise, it changes the source window's `XdndDirectSave` property to zero length to indicate failure. (**1**) It then sends `XdndFinished`. + +If it receives `E`, it sends `XdndFinished`. + + +### Step 4: Finishing + +The source receives `XdndFinished`. + +If it sent `S` or `F`, it checks its `XdndDirectSave` property. If this is not empty, the source updates the file path and name that it stores and clears its "needs save" flag. (The property can be empty in either case, as explained in the Notes section.) + +Regardless of what it sent or received, it must delete the `XdndDirectSave` property when it is finished. (This can be done in the `XGetWindowProperty()` call.) + + +## Notes + +Given that some prefer not to use a file manager, it is still a good idea to provide a directory browser so the user has a choice. + +If one chooses not to provide a directory browser, then the interface might act as follows: + +* When the user initiates Save, the program displays a modeless dialog with an input field, a Save button, and a draggable icon. If the file does not exist on disk, the input field contains an example name. If the file exists on the same machine, the input field contains the full path + name. If the file exists on a different machine, the input field contains the full URL. +* If the user drags the icon, use the XDS protocol and dismiss the dialog if successful. +* If the input field contains a full path + name, the Save button should enabled. If the user clicks it (or presses Return), save the file directly and dismiss the dialog if successful. +The source should report the error if it sends `E` in Step 2. The target should report it if an error occurs in Step 3. + +Other applications can use this protocol if they need the name of the data in addition to the data itself by simply retrieving the contents of the `XdndDirectSave` window property before requesting the actual data. + +If a program expects a large amount of data (e.g. a video clip) then it could in principle pretend to be a file manager in order to obtain the data on disk instead of via the X Selection. In this case, it must always set the property to zero length in Step 3 so the source doesn't think that the data has been saved. Since this will only work if the source is on the same machine, however, it is usually better to use a Publish-Subscribe protocol where the target simply checks for modifications to a file written by the source. + + +### Technical details + +Current version: 0 + +Unless otherwise noted, all constants mentioned below are the string names of X atoms, capitalized as shown. This avoids the need for hard-coded values, which would require a global registry. + + +### Atoms and Properties + +**`XdndDirectSave`** + +This is both a window property and a data type. In both cases, the full name of the atom is `XdndDirectSave0`. The version number is included in the name to allow new versions of the protocol in the future. All applications are required to support all previous versions of this protocol. A file manager should search the list of available data types starting with the latest version of `XdndDirectSave` that it supports and use the latest version that it finds. This is equivalent to the way the XDND protocol works. For direct save, the version number is part of the atom name instead of being stored in a window property because the latter method would require more network traffic. + +The window property must be of type `text/plain`, including the `charset` attribute, if necessary. This allows file names to contain any character that the file system can handle. File managers that cannot handle the character set can refuse the drop. Applications that cannot handle the character set returned by the file manager can treat this as an error and return `E`. (Refer to step 2 of the walk-through.) If the charset attribute is not set, it is assumed to be `ISO-8859-1`. + +**`XdndActionDirectSave`** + +This is the action that is sent to the target. + +**`application/octet-stream`** + +This data type is reserved to provide the data in the exact format that the program would write to disk. + + +## Sample implementation + +While implementing this protocol, you may find it very useful to use the programs `xlsatoms` to list all the atoms that the server knows about, `xprop` to list all the properties on a particular window, and `xscope` to study the timing of events. + +Even if you implement Direct Save from scratch, we would appreciate it if your distribution included some sort of documentation that states clearly that you are supporting this protocol and provides a reference to this web page. This will help get the snowball rolling. The more applications that support the same protocol, the more useful Direct Save will be for the users. If you tell us that you support the protocol, we will also add you to the list of supporters. + + +## Changes from previous versions + +October 26, 2000: + + * Action changed to `XdndActionDirectSave`. +June 7, 1999: + + * Initial publication. + +## Acknowledgements + +This protocol was developed by Main.[[ThomasLeonard|ThomasLeonard]] who works on the [[ROX Desktop|http://rox.sourceforge.net]] and John Lindal at [[New Planet Software|http://www.newplanetsoftware.com]]. diff --git a/Specifications/XSettingsRegistry.mdwn b/Specifications/XSettingsRegistry.mdwn new file mode 100644 index 00000000..c22ad823 --- /dev/null +++ b/Specifications/XSettingsRegistry.mdwn @@ -0,0 +1,166 @@ + + +# XSETTINGS registry + +This page lists the shared settings which are currently under the control of the XSETTINGS system. Desktop configuration interfaces should provide a way to set these. + +Note that currently only GTK supports XSETTINGS, so the distinction between 'all desktops' and 'all GTK desktops' is currently irrelevant. The type and default value is given for each one. + + +## Shared by all desktops + + +### Net/DoubleClickTime + +Maximum time allowed between two clicks for them to be considered a double click (in milliseconds) + + * int 250 + +### Net/DoubleClickDistance + +Maximum distance allowed between two clicks for them to be considered a double click (in pixels) + + * int 5 + +### Net/DndDragThreshold + +Number of pixels the cursor can move before dragging + + * int 8 + +### Net/CursorBlink + +Whether the cursor should blink + + * bool True + +### Net/CursorBlinkTime + +Length of the cursor blink cycle, in milleseconds + + * int 1200 + +### Net/ThemeName + +Name of theme to use. This is a directory either in <tt>~/.themes</tt> (except on Debian), or the 'system' theme directory, which depends on where GTK was installed. Basically, it could be anywhere. This should really use the base dir spec or something similar to locate the theme. + + * string "Default" + +### Net/IconThemeName + +Name of icon theme to use for icons. + + * string "hicolor" + +## Xft settings + +These settings can be shared by all Xft clients. + + +### Xft/Antialias + +Whether to antialias Xft fonts; 0`no, 1`yes, -1=default + + * int -1 + +### Xft/Hinting + +Whether to hint Xft fonts; 0`no, 1`yes, -1=default + + * int -1 + +### Xft/HintStyle + +What degree of hinting to use; "hintnone", "hintslight", "hintmedium", or "hintfull" + + * string "hintnone" + +### Xft/RGBA + +Type of subpixel antialiasing; "none", "rgb", "bgr", "vrgb", "vbgr" + + * string "none" + +### Xft/DPI + +Resolution for Xft, in 1024 * dots/inch. -1 to use default value + + * int -1 + +## GTK only + +These settings are only used by GTK desktops at present. Some way to share these should be found, or they should be moved out to some other system. + + +### Gtk/CanChangeAccels + +Whether menu accelerators can be changed by pressing a key over the menu item. + + * bool False + +### Gtk/ColorPalette + +Palette to use in the color selector. + + * string "black:white:gray50:red:purple:blue:light blue:green:yellow:orange:lavender:brown:goldenrod4:dodger blue:pink:light green:gray10:gray30:gray75:gray90" + +### Gtk/FontName + +Name of default font to use + + * string "Sans 10" + +### Gtk/IconSizes + +List of icon sizes (gtk-menu`16,16;gtk-button`20,20... + + * string NULL + +### Gtk/KeyThemeName + +Name of key theme RC file to load. + + * string NULL + +### Gtk/ToolbarStyle + +Whether default toolbars have text only, text and icons, icons only, etc. + + * enum {Icons, Text, Both, Both_Horiz} Both + +### Gtk/ToolbarIconSize + +Size of icons in default toolbars. + + * enum LARGE_TOOLBAR + +### Gtk/IMPreeditStyle + +How to draw the input method preedit string. + + * enum Callback + +### Gtk/IMStatusStyle + +How to draw the input method statusbar. + + * enum Callback + +### Gtk/MenuImages + +Whether images should be shown in menus + + * bool True + +### Gtk/ButtonImages + +Whether stock icons should be shown in buttons + + * bool True + +### Gtk/MenuBarAccel + +The accelerator for moving the focus to the menubar + + * string "F10" +-- Main.[[MatthiasClasen|MatthiasClasen]] - 30 Aug 2004. Discussion of this specification should occur on [[xdg|http:/mailman/listinfo/xdg]]. diff --git a/Specifications/audio-metadata-spec.mdwn b/Specifications/audio-metadata-spec.mdwn new file mode 100644 index 00000000..17359f2e --- /dev/null +++ b/Specifications/audio-metadata-spec.mdwn @@ -0,0 +1,50 @@ + +---++Audio File Meta Data + +Often time applications that deal with audio file data have a shorthand so the user can define how they want the data to be used over a number of files. + +Some examples include + + * CD Rippers that passes CDDB information to command line encoders along with the file + * ID3 editors that let you batch change files + * Tools that automaticly rename audio files based upon the meta data (id3) within the files. + * Audio file players that display file information +The goal of this standard is to choose a common set of abbreviations, so users don't have to learn a new different, but very similar set for every application. Not only is there typically many different types of applications that would use abbreviations,but in the free desktop world there are often many different application that can do the same functionality. + +The list here is just a few basic items. Each application will probably have many more options. Some applications wont support all of the basic options either. It isn't mandatory that every options is supported. + +Key: First column is the item that the rest of the columns can represent. The preferred choice presented to the user goes from left to right. + +Audio Track. The lower case letters go with the track (even if they are often the same such as in year or genre) and the upper case letters are for the album. This makes it easier to visually recognize if the title means the album or the track. + +The reason for the duplicate artist stems from compilation albums such as soundtracks, best of, or even remix/techno albums. In those cases the song artist is often different than the album artist. +[[!table header="no" class="mointable" data=""" + Title | %{title} | %t + Artist | %{artist} | %a + Track Number | %{number} | %n + Comment | %{comment} | %c + Year | %{year} | %y + Genre | %{genre} | %g +||| + Album Title | %{albumtitle} | %T + Album Artist | %{albumartist} | %A + Number of tracks on album | %{tracks} | %N + Album Comment | %{albumcomment} | %C + Album Year | %{albumyear} | %Y + Album Genre | %{albumgenre} | %G +"""]] + +File Attributes (when using outside tools to tell them more information about the file not related to the track) +[[!table header="no" class="mointable" data=""" + File Name | %{file} | %f + File Path | %{filepath} | %p + File Type Extension | %{extension} | %e +"""]] + +Modifiers (when using outside tools that take a file input and output a new one) +[[!table header="no" class="mointable" data=""" + Input File | %{input} | %i + Output File | %{output} | %o +"""]] + +-- Main.[[BenjaminMeyer|BenjaminMeyer]] - 01 Jul 2004 diff --git a/Specifications/autostart-spec.mdwn b/Specifications/autostart-spec.mdwn new file mode 100644 index 00000000..a9ef5f35 --- /dev/null +++ b/Specifications/autostart-spec.mdwn @@ -0,0 +1,20 @@ + + +## Autostart Specification + +The autostart specification defines a method for automatically starting applications during the startup of a desktop environment after the user has logged in and after mounting a removable medium. + + +### Mailinglist + +Discussion of this specification should occur on [[xdg|http:/mailman/listinfo/xdg]]. + + +### CVS + +The [[CVS|http:GettingInvolved#CVS]] module for this spec is [[autostart-spec|http://cvs.freedesktop.org/menus/autostart-spec/]]. + + +### Spec + + * Version 0.5 - [[html (one page)|http://standards.freedesktop.org/autostart-spec/autostart-spec-0.5.html]] - [[html (multiple pages)|http://standards.freedesktop.org/autostart-spec/0.5/]] - [[xml|http://standards.freedesktop.org/autostart-spec/autostart-spec-0.5.xml]]
\ No newline at end of file diff --git a/Specifications/basedir-spec.mdwn b/Specifications/basedir-spec.mdwn new file mode 100644 index 00000000..2c7951de --- /dev/null +++ b/Specifications/basedir-spec.mdwn @@ -0,0 +1,22 @@ + + +## Basedir + +Various specifications specify files and file formats. This specification defines where these files should be looked for by defining one or more base directories relative to which files should be located. + + +### Mailinglist + +Discussion of this specification should occur on [[xdg|http:/mailman/listinfo/xdg]]. + + +### CVS + +The [[CVS|http:GettingInvolved#CVS]] module for this spec is [[basedir-spec|http://cvs.freedesktop.org/basedir/basedir-spec/]]. + + +### Spec + + * [[Latest version|http://standards.freedesktop.org/basedir-spec/latest/]] + * Version 0.6 - [[html (one page)|http://standards.freedesktop.org/basedir-spec/basedir-spec-0.6.html]] - [[html (multiple pages)|http://standards.freedesktop.org/basedir-spec/0.6/]] - [[xml|http://standards.freedesktop.org/basedir-spec/basedir-spec-0.6.xml]] + * Version 0.5 - [[html (one page)|http://standards.freedesktop.org/basedir-spec/basedir-spec-0.5.html]] - [[html (multiple pages)|http://standards.freedesktop.org/basedir-spec/0.5/]] - [[xml|http://standards.freedesktop.org/basedir-spec/basedir-spec-0.5.xml]]
\ No newline at end of file diff --git a/Specifications/bidi-spec.mdwn b/Specifications/bidi-spec.mdwn new file mode 100644 index 00000000..b800d97c --- /dev/null +++ b/Specifications/bidi-spec.mdwn @@ -0,0 +1,47 @@ + + +## Bidirectional Scripts in Desktop Software + +Bidirectional scripts are those with characters flowing from right to left. Major bidirectional scripts are the Arabic, Persian and Hebrew scripts, but there are other ones too. Supporting these languages in the user interface of a desktop system needs special support in several layers of the system. Experiments and history shows such special support moves on the very thin edge between completely unusable and highly usable. So they deserve their own guidelines for a consistent cross-desktop behavior. That's what we aim to do here. + + +### Readings (a.k.a. References) + +* [[Unicode Bidirectional Algorithm|http://www.unicode.org/reports/tr9/]] (UBA from now on, a.k.a UAX#9) is the place to start. It contains the basic algorithm to map a Unicode plain text string to a visual ordering. +* [[Bidirectional Layouts in GTK+|http://behdad.org/download/Presentations/bidi-layouts/]] is a presentation of the state of art bidi support in Gtk+ by mid 2004. Discusses several problems and concepts that are general to all GUI applications. +* [[Hierarchically Implicit Bidi|http://cben-hacks.sourceforge.net/bidi/hibidi.html]] is a personal proposal for a hierarchical bidi system. +* [[Guidelines of a Logical User Interface for Editing Bidirectional Text|http://imagic.weizmann.ac.il/~dov/Hebrew/logicUI24.htm]] (also [[here|http://www-306.ibm.com/software/globalization/topics/bidiui/index.jsp]]) is the guidelines in use by IBM. +* [[Yudit Bidirectional Information|http://yudit.org/bidi/]] discusses surprises and potential security problems with bidi text support complying to the UBA. +* [[Examples of bidirectional IRIs|http://www.w3.org/International/iri-edit/BidiExamples]] linked from [[Editing 'Internationalized Resource Identifiers (IRIs)'|http://www.w3.org/International/iri-edit/]]. +* [[Mozilla Bi-Di API proposal|http://www.langbox.com/AraMosaic/mozilla/BiDi_API.html]] (out-dated) is the old proposal to add support for bidirectional text to Mozilla. Note that the API proposed in this document is missing essential features, like line breaking support. +* [[The 'direction' and 'unicode-bidi' properties|http://www.w3.org/TR/CSS21/visuren.html#direction]] in CSS 2.1 specification, and its [[box model|http://www.w3.org/TR/CSS21/box.html#q11]]. +* [[A|http://lists.w3.org/Archives/Public/www-style/2002Aug/0396.html]] [[couple|http://lists.w3.org/Archives/Public/www-style/2002Sep/0049.html]] messages about start/end margins as opposed to left/right margins in CSS 3. Unfortunately seems like the whole thing did not make it into final CSS 3. [[Mozilla|https://bugzilla.mozilla.org/show_bug.cgi?id=74880]] bug about the issue, and [[KDE|http://bugs.kde.org/show_bug.cgi?id=56219]]'s. +* [[Exploring Better Source Editing for Bidirectional XHTML and XML|http://www.sw.it.aoyama.ac.jp/2005/pub/IUC28-bidi/IUC28.html]], a paper from IUC28, Septembre 2005. Excellent reading in itself, but even more valuable is the list of references. Check it out. +* [[Better tutorial on mixed directionality|http://groups.google.ca/group/comp.windows.x.intrinsics/msg/936cf8754a29b740?q=group:comp.windows.x.intrinsics+author:goerwitz&hl=en&lr=&c2coff=1&as_drrb=b&as_mind=9&as_minm=4&as_miny=1994&as_maxd=9&as_maxm=4&as_maxy=1994&rnum=1]] is a Usenet post about cursor movement in bidirectional text. +* [[Documentation for BiDi Mozilla|http://developer.mozilla.org/en/docs/Documentation_for_BiDi_Mozilla]]. This is preliminary documentation of the changes introduced to Mozilla as part of the bidi support contributed by IBM (a.k.a. IBMBIDI). +* [[RFC: Standard for automatic insertion of bidi control characters|http://osdir.com/ml/region.israel.ivrix.discuss/2003-05/msg00031.html]]. Interesting discussion thread on good ol' ivrix list. + +### Non-Readings (a.k.a. Pre-Unicode Tries) + +* [[Understanding bidirectional language support|http://www-306.ibm.com/software/webservers/hostondemand/library/v8infocenter/hod/en/help/bidi.html]] is an older IBM standard. +* ECMA TR53 Handling of Bi-directional Texts, Second Edition is a technical report on supporting bidi text in text terminals. No one knows if it was ever implemented. + +### Implementations + +* [[GNU FriBidi|http://fribidi.org/]] is GNU project's implementation of the UBA, also used in several other projects. +* [[Automatic paragraph direction according to the UBA in Gtk+|http://bugzilla.gnome.org/show_bug.cgi?id=70451]] (bugzilla discussion) (also +[[this|http://bugzilla.gnome.org/show_bug.cgi?id=136529]] and [[this|http://bugzilla.gnome.org/show_bug.cgi?id=116626]].) + +* [[Handling markup text from a bidi point of view|http://bugzilla.gnome.org/show_bug.cgi?id=168108]] (bugzilla discussion). +* [[miniBidi|http://cvs.arabeyes.org/viewcvs/projects/adawat/minibidi]] is a minimal implemention of the UBA (BMP only, implicit only). +* [[PGBA: Pretty Good Bidi Algorithm|http://crl.nmsu.edu/~mleisher/ucdata.html]] (approximate, implicit only) +* [[GtkBidiText: A Gtk BiDirectional text widget for Hebrew|http://imagic.weizmann.ac.il/~dov/freesw/gtk/gtkbiditext/]] (out-dated) +* [[ProtoBidi: The Prototype Bidirectional Widget|http://imagic.weizmann.ac.il/~dov/Hebrew/protobidi/]] (out-dated) +* [[Mozilla BiDi UI Extension|http://bidiui.mozdev.org/]] is a Mozilla extension to support bidi widgets on Mozilla user interface. +* [[Gedit Bidi Assistant|http://live.gnome.org/Gedit/Plugins/BidiAssist]] is a Gedit plugin for dealing with Unicode bidirectional markup. + +### Mailinglist + +All bidi discussion is currently on [[bidi at lists freedesktop org|http://freedesktop.org/mailman/listinfo/bidi/]]. The archives are [[here|http://freedesktop.org/pipermail/bidi/]]. + +-- [[BehdadEsfahbod|BehdadEsfahbod]] - June 7, 2005 diff --git a/Specifications/clipboard-manager-spec.mdwn b/Specifications/clipboard-manager-spec.mdwn new file mode 100644 index 00000000..85b9254d --- /dev/null +++ b/Specifications/clipboard-manager-spec.mdwn @@ -0,0 +1,16 @@ + + +## Clipboard Manager specification + +This document specifies how the clipboard manager application works, and how applications interact with it when they want to transfer clipboard data to it. + + +### Mailinglist + +Discussion of this specification should occur on [[xdg|http://lists.freedesktop.org/mailman/listinfo/xdg]]. + + +### Spec + + * Version 0.1: [[ClipboardManager|ClipboardManager]] Wiki format +-- Main.[[AndersCarlsson|AndersCarlsson]] - 13 Jun 2005 diff --git a/Specifications/clipboards-extension-spec.mdwn b/Specifications/clipboards-extension-spec.mdwn new file mode 100644 index 00000000..77eff1fa --- /dev/null +++ b/Specifications/clipboards-extension-spec.mdwn @@ -0,0 +1,21 @@ + + +## Clipboards-Extension + +Proposal for an extension to the ICCCM selections mechanism allowing xclipboard-like tools to limit the amount of transferred data. + + +### Mailinglist + +Discussion of this specification should occur on [[xdg|http://lists.freedesktop.org/mailman/listinfo/xdg]]. + + +### CVS + +The [[CVS|GettingInvolved]] module for this spec is [[selections|http://cvs.freedesktop.org/icccm-extensions/selections/]]. + + +### Spec + + * [[clipboard-extensions.txt|http://standards.freedesktop.org/clipboard-extensions-spec/clipboard-extensions-latest.txt]] + * [[ClipboardExtensions|Specifications/ClipboardExtensions]] (same text translated to Wiki) diff --git a/Specifications/clipboards-spec.mdwn b/Specifications/clipboards-spec.mdwn new file mode 100644 index 00000000..55892a0e --- /dev/null +++ b/Specifications/clipboards-spec.mdwn @@ -0,0 +1,21 @@ + + +### Clipboards + +This is not a formal specification, but explains our consensus on how the X clipboard works. Qt and GTK+ both follow this document + + +### Mailinglist + +Discussion of this specification should occur on [[xdg|http:/mailman/listinfo/xdg]]. + + +### CVS + +The [[CVS|http:GettingInvolved#CVS]] module for this spec is [[icccm-extensions/selections|http://cvs.freedesktop.org/icccm-extensions/selections/]]. + + +### Spec + + * [[clipboards.txt|http://standards.freedesktop.org/clipboards-spec/clipboards-0.1.txt]] + * [[ClipboardsWiki|Specifications/ClipboardsWiki]] (same text in Wiki format)
\ No newline at end of file diff --git a/Specifications/colorscheme-spec.mdwn b/Specifications/colorscheme-spec.mdwn new file mode 100644 index 00000000..7c3e006a --- /dev/null +++ b/Specifications/colorscheme-spec.mdwn @@ -0,0 +1,36 @@ + + +## Desktop Color Scheme Specification Project + +**The colorscheme spec has been pulled on request of its authors** + + +### Introduction + +Selecting an appropriate color scheme for user interface components is one of the most daunting tasks in desktop configuration. Modern desktops use dozens of colors, and selecting a harmonious set of colors is difficult. Color scheme design requires a background in industrial design, and there is presently a lack of tools available to simplify the process. Ensuring a consistent colour scheme is even more challenging, as applications each have their own configuration methods. Changes must be manually propagated across different configuration files or databases. + + +### Purpose + +This specification attempts to define a standard set of color names to be used in application configuration files defining colors for user interface elements. Rather than describing the color value itself, names are defined to identify the purpose of the color. For example, the name Base is used to represent the background, and Active to describe the focused element or window. + +Furthermore, this specification provides a simple and reliable way of generating complete color schemes from a single base color, based on techniques employed by professional designers. + +Finally, this specification identifies ways in which these color schemes can be applied in applications. + + +### Spec + + * Version 0.1 : + * [[%ATTACHURL%/colorscheme-spec-0.1.xml][colorscheme-spec-0.1.xml|%ATTACHURL%/colorscheme-spec-0.1.xml][colorscheme-spec-0.1.xml]] + * [[%ATTACHURL%/colorscheme-spec-0.1.html][colorscheme-spec-0.1.html|%ATTACHURL%/colorscheme-spec-0.1.html][colorscheme-spec-0.1.html]] + +### Reference code and samples + + * [[%ATTACHURL%/both.html][Side-by-side comparison of HSV and Lab results|%ATTACHURL%/both.html][Side-by-side comparison of HSV and Lab results]]: + * [[%ATTACHURL%/ascs.html][HSV|%ATTACHURL%/ascs.html][HSV]]: HSV calculated colorschemes + * [[%ATTACHURL%/dcs.html][Lab|%ATTACHURL%/dcs.html][Lab]]: CIELab calculated color schemes + + + + diff --git a/Specifications/config-spec.mdwn b/Specifications/config-spec.mdwn new file mode 100644 index 00000000..ae44ef21 --- /dev/null +++ b/Specifications/config-spec.mdwn @@ -0,0 +1,48 @@ + + +# Shared configuration system + +All desktops currently have their own configuration systems. They should be unified so that: + + * Settings can easily be shared. + * The [[XSettings|Specifications/xsettings-spec]] system can be replaced (it is too limited, because only one application can change the settings). + * Notification of changes is sent to all interested applications. + * Importing/Exporting Configuration + * Looking up Configuration of System or other Applications + * Users know where their settings are saved, without having to care about which desktop an application is affiliated to. + +## Requirements + + * Must be desktop-neutral, so that all desktops can share the same system. + * Notification of changes must be sent to all interested parties. + * Applications must be able to load a large number of settings efficiently at startup. + * Settings must cascade (the admin sets system defaults, and users may override it where they desire). + * Must be resistant to corruption (especially with concurrent changes and manual user editing). + * Should allow settings to be shared over the network (if different applications on your desktop are running on different machines). + * Keep different users' settings separate. + * Standard API / sample library implementation to access the database. +Useful bonus features: + + * Light-weight enough that boot processes and small utilities can use it (possibly read-only?). + * Human readable storage format (edit config with vi, keep under version control, use diff, etc). + +## Issues + + * A schema system to describe what values keys can have, plus translatable comments, is useful for tools like gconf-editor. There is some debate as to whether schema files are required to use the system, or an optional layer built on top of the system with the low-level backends simply storing strings (KDE and ROX store strings, with application libraries interpreting them according to a schema, while GNOME applications install schema files which are understood by the underlying configuration daemon). + * Are only preferences to be stored? A network-transparent per-user storage system with change notification could be useful for many things, such as storing bookmarks, your address book, a list of recently edited files, etc. We must make sure that the project does not try to do everything. + * Do we have a single way of actually storing the settings, or just an API with pluggable backends? Pluggable backends allow the same API to be used in different environments; a system daemon might want to store values to a local text file without change notification, while a desktop application in a large company might access settings via a remote SQL database. A single backend can't cover all cases, and would prevent some people from adopting the system. The effect of this would be that programmers would choose a configuration system per-application, rather than sysadmins choosing a system per-computer. + +## Plan + +This specification is expected to use the [[Base directory spec|Specifications/basedir-spec]] for the location of configuration files (under *~/.config* by default). + +Ideally, the system should be fast but also network transparent. Possibly, applications could read the database directly if running on the same machine as the config files, or read them via the notification process if not. + +We should define a simple API for setting and getting configuration settings and provide a small library that implements it. It should be possible to use multiple backends (XML files, database, etc) to actually store the settings. + +Change notification could be done using [[D-BUS|Software/dbus]]. + + +## References + + * [[Havoc's description of gconf and his future plans (PDF)|http://www.linux.org.uk/~ajh/ols2002_proceedings.pdf.gz]] (starting at page 414). See also, [[updated future plans|http://www.gnome.org/projects/gconf/plans.html]]. [[UniConf|http://open.nit.ca/wiki/index.php?page=UniConf]]: UniConf lets you build up a configuration tree by 'mounting' generators (like filesystems) onto it. Generators can store keys in memory, on disk, through a database, through gconf, etc, and can be used to combine other trees (fallbacks, cascading, caching, union, etc). Currently, applications each build their own namespace at start-up, or you can use the "auto" moniker to allow for a user to make all apps use a database for config, or all use gconf, etc, rather than hard-coding it in the apps. It can operate with or without a demon. It supports both transactions and notifications. [[Common configuration namespace thread|http://thread.gmane.org/gmane.linux.xdg.devel/2816]] (includes description of KDE's namespace). [[Configuration API thread|http://thread.gmane.org/gmane.linux.xdg.devel/2941]] (requirements, types, backends, schemas) [[Config4GNU|Software/CFG]]: An abstraction layer over many different config file syntaxes (.ini files, fstab, apache, etc). For example to an editor all config files are presented as a XML structure with comments available options and defaults. This is mainly intended for system-level configuration, rather than for user settings. It doesn't not handle notification of changes. Several interfaces to access the complete configuration tree exist, yet the applications themselves are not required to switch to them. A special feature is that the semantic meta-data (options, types, assumed defaults and even wizard logic etc.) for applications are kept as separate description textfiles and thus can be updated together with the app (idealy even kept in sync in cvs) without the need to update or recompile Config4GNU or any frontends. [[Elektra Project|http://elektra.sourceforge.net/]]: "Elektra provides a sigle unified system-wide namespace to represent keys, and a clean API to access it, with many language bindings and some backends." Elektra uses backends to store every (key, value) pair. That can be a separate file in the filesystem, ini-style like, berkleydb or everything else. If locking, networking or cascading is supported is decided by the backend. There is no backend available now for networking. There are no dependencies (except of libc) of the core library. The backends may add dependency (like berkleydb, gconf). [[D-Conf|http://freax.be/wiki/index.php/Temporary_location_for_D-Conf_specs]]: Wiki page with more plans for freedesktop.org config system.
\ No newline at end of file diff --git a/Specifications/cursor-spec.mdwn b/Specifications/cursor-spec.mdwn new file mode 100644 index 00000000..66c9cfcd --- /dev/null +++ b/Specifications/cursor-spec.mdwn @@ -0,0 +1,61 @@ + + +# Cursor conventions specification + +This is a draft specification for a cursor naming and usage standard. + + +## Mailinglist + +Discussion of this specification should occur on [[xdg|http:/mailman/listinfo/xdg]]. + + +## Cursor list +[[!table header="no" class="mointable" data=""" + **Cursor** | **Description** + _default_ | Default cursor. Indicates the interface is idle and prepared to accept commands from the user. Used to manipulate basic user interface elements like buttons and scrollbars. Usually a left pointing diagonal arrow. + _text_ | Text input cursor. Indicates that the cursor is in a region in which horizontal text can be selected and possibly edited. Typically rendered as a vertical I-beam. + _pointer_ | Indicates that the object below the cursor is clickable. This cursor is typically used for links in web browsers. It shouldn't be abused for pushbuttons and other UI elements where it's otherwise apparent by the design of the widget that it's a clickable object. Often rendered as a pointing hand. + _help_ | Help cursor. Indicates that the system is in a context help mode, and if the user clicks an object a small window will open up to provide usage information for that object. The context help mode is typically activated by clicking a help button on the titlebar of a window that provides context help. Often rendered as the default cursor with a question mark symbol next to it. + _progress_ | Default cursor + busy cursor. Indicates a pending activity which may asynchronously affect the interface but which is not blocking commands from the user. + _wait_ | Busy cursor. Indicates that the interface is not prepared to accept commands from the user and is blocked on some external resource. Often rendered as a watch or an hourglass. + _copy_ | !DnD copy cursor. Indicates that a copy of the dragged object will be created in the area below the cursor if dropped. Typically rendered as the default cursor with a small plus sign next to it. + _alias_ | !DnD link cursor. Indicates that a link to the original location of the dragged object will be created in the area below the cursor if dropped. Typically rendered as the default cursor with a small curved arrow next to it. + _no-drop_ | !DnD no-drop cursor. Indicates that the dragged object can't be dropped in the region below the cursor. Typically rendered as the default cursor with a small circle with a diagonal line through it. Can be identical to not-allowed. + _not-allowed_ | Forbidden cursor. Indicates that a particular region is invalid for the current operation. Often rendered as circle with a diagonal line through it. + _all-scroll_ | Scroll/move cursor. Used to indicate that moving the mouse will also move the UI element below the cursor. Often rendered as a combined vertical and horizontal twin-headed arrow. + _row-resize_ | Horizontal splitter bar cursor. Indicates that the bar below the cursor can be moved up and down to resize the objects it separates. Used when it's not apparent if the object below the cursor is just a visual separator between two other UI elements, or an object that can be manipulated. Usually rendered as a vertical twin-headed arrow, split in the middle by a horizontal line. + _col-resize_ | Vertical splitter bar cursor. Indicates that the bar below the cursor can be moved left and right to resize the objects it separates. Used when it's not apparent if the object below the cursor is just a visual separator between two other UI elements, or an object that can be manipulated. Usually rendered as a horizonal twin-headed arrow, split in the middle by a vertical line. + _e-resize_ | Indicates that the cursor is over the right edge of a window, and that the edge can be clicked and dragged in order to resize the window horizontally. + _ne-resize_ | Indicates that the cursor is over the top-right edge of a window, and that the edge can be clicked and dragged in order to resize the window diagonally. + _nw-resize_ | Indicates that the cursor is over the top-left edge of a window, and that the edge can be clicked and dragged in order to resize the window diagonally. + _n-resize_ | Indicates that the cursor is over the top edge of a window, and that the edge can be clicked and dragged in order to resize the window vertically. + _se-resize_ | Indicates that the cursor is over the bottom-right edge of a window, and that the edge can be clicked and dragged in order to resize the window diagonally. + _sw-resize_ | Indicates that the cursor is over the bottom-left edge of a window, and that the edge can be clicked and dragged in order to resize the window diagonally. + _s-resize_ | Indicates that the cursor is over the bottom edge of a window, and that the edge can be clicked and dragged in order to resize the window vertically. + _w-resize_ | Indicates that the cursor is over the left edge of a window, and that the edge can be clicked and dragged in order to resize the window horizontally. +"""]] + + +## Cursor list - Nice to have +[[!table header="no" class="mointable" data=""" + **Cursor** | **Description** + _vertical-text_ | Text input cursor. Indicates that the cursor is in a region in which vertical text can be selected and possibly edited. Typically rendered as a horizontal I-beam. + _crosshair_ | Crosshair cursor. Typically used for precision drawing or manipulation of an area. + _cell_ | The thick plus sign cursor that's typically used in spread-sheet applications to select cells. +"""]] + + +## Cursor list - up for discussion +[[!table header="no" class="mointable" data=""" + **Cursor** | **Description** + _default_ | Default cursor. Indicates the interface is idle and prepared to accept commands from the user. Used to manipulate basic user interface elements like buttons and scrollbars. Usually a left pointing diagonal arrow. + _up-arrow_ | Up pointing arrow cursor. This cursor is typically used to identify an insertion point. + _context-menu_ | Indicates that a context menu is available for the object underneath the cursor. Typically rendered as the default cursor with a small menu-like graphic next to it. + _ew-resize_ | Horizontal resizing cursor. Indicates that cursor is over the the left or right edge of a window, and that ithe edge can be clicked and dragged to resize the window horizontally. Typically rendered as a horizontal twin-headed arrow. + _ns-resize_ | Vertical resizing cursor. Indicates that cursor is over the the top or bottom edge of a window, and that the edge can be clicked and dragged to resize the window vertically. Typically rendered as a verticaly twin-headed arrow. + _nesw-resize_ | Back-diagonal resizing cursor. Indicates that the UI element below the cursor is the top-right or bottom-left corner of a window, and that it can be clicked and dragged to resize the window diagonally. Typically a twin-headed arrow. + _nwse-resize_ | Forward-diagonal resizing cursor. Indicates that the UI element below the cursor is the top-left or bottom-right corner of a window, and that it can be clicked and dragged to resize the window diagonally. Typically a twin-headed arrow. +"""]] + +-- Main.[[FredrikHoeglund|FredrikHoeglund]] - 14 Oct 2003 diff --git a/Specifications/db-shortcut-spec.mdwn b/Specifications/db-shortcut-spec.mdwn new file mode 100644 index 00000000..7ba3bada --- /dev/null +++ b/Specifications/db-shortcut-spec.mdwn @@ -0,0 +1,32 @@ + + +# Shortcut to a database connection/data source + +* Status: Proposal +* Author: Jaroslaw Staniek <js @ iidea dot pl> +1. Justification + +A format named in general "Shortcut to a database connection/data source" allows a user to store in a simple ini-file-like format. There is no single well known format for this. + +The data structure stored using the format is quite linear, so we've succesfully avoided using XML, hence the format is **more human readable**. While I am helping in including database-related specs to OASIS set of office format specs, please note that using XML language is preferred there, not ini format. Thus it may be better idea to have the specification pulished rather within fd.org. + +2. Usage scenarios + +2.1. A file containing data compatible with the format can be kept by a user, who can pass the filename to an application to avoid entering all the information again. + +2.2. Within desktop system, there can be associated filename extension with the file format, so a user can simply click the file to open connetion with default application. + +2.3. User can decide to send the mentioned file, e.g. using e-mail, to allow connections. + +3. Other notes + +* Security: storing passwords is optional. Integration with password managers (like KWallet) is beyond the scope of this specification. +* The format can be also used to store files containing "recent connections' data" at user will. For this we may want to agree on a recommended subdirectory for saving such files within $HOME directory. +* While the format is proposed as implementation-neutral, it is already implemented in Kexi and there are planse to reuse it within other database-related projects. +* Further plans include integration with ODBC/JDBC connection data. +* Formal specification will be provided later, for now I am asking for comments +4. References + +4.1 [[Information within the Kexi project's wiki|http://www.kexi-project.org/wiki/wikiview/index.php?KexiMimeTypes_DataSaving_Loading]] + +4.2 [[Example file with comments|http://websvn.kde.org/trunk/koffice/kexi/tests/startup/testdb.kexis?view=markup]] diff --git a/Specifications/default-keys-spec.mdwn b/Specifications/default-keys-spec.mdwn new file mode 100644 index 00000000..8f1b8972 --- /dev/null +++ b/Specifications/default-keys-spec.mdwn @@ -0,0 +1,117 @@ + + +# Shared default keyboard shortcuts + +Sharing default keyboard shortcuts is being discussed at freedesktop.org in [[this thread|http://listman.redhat.com/archives/xdg-list/2003-July/msg00265.html]], continuing [[here|http://listman.redhat.com/archives/xdg-list/2003-August/msg00012.html]]. + +A good source of keyboard shortcuts in different systems is now in Wikipedia: [[Table of keyboard shortcuts|http://en.wikipedia.org/wiki/Table_of_keyboard_shortcuts]]. Its origin comes from [[http://people.mandriva.com/~fcrozat/shortcuts/shortcuts2.gnumeric|http://people.mandriva.com/~fcrozat/shortcuts/shortcuts2.gnumeric]] (gnumeric spreadsheet). + +We are currently gathering requirements for a specification to handle this. Please add comments. + + +## Points to address + + +### What types of keys are being considered? + +The most important aspect for consistency is to make sure that everything works the same within a session. So, all my applications should use *Ctrl-S* for Save, for example, whether they are from GNOME, KDE or whatever. Having the same key for "Open home directory" if I select KDE from the session menu rather than GNOME is perhaps less important. + + +### What specific keys should be in the "global key name registry"? + +These correspond loosly to the stock items (Save, Delete, New, etc), except that you can only use each one once per menu. + + +### What is the intended set of user interfaces that this supports? Can keys be changed from the UI of individual apps rather than just globally? + +We still need to be able to bind application specific keys. This spec is about letting the user bind eg *Help* to *Ctrl+H* everywhere (non-English users often use the function keys for accents). Rebinding Help from a single application could either be prevented, or should only affect that application. + + +### For application accelerators, how does conflict resolution work? If I change File/Save to something other than Control-S, it's pretty likely to conflict with other accelerators in many applications. + +A good idea (from KDE) is to allow the same key for multiple actions. When pressed, a menu of all possible actions is presented to the user, who can then either choose one or, possibly, change the bindings on some of them. + + +### Where are the settings saved? How are updates managed? + +Owen suggests using Havoc's [[config-spec][newconf|config-spec][newconf]]: + + * Per-directory change notification + * Network transpareny + * Centralised caching + * Potential ability to do atomic changes of multiple keys +Problem: newconf doesn't exist, and won't for a year or two. Going through three processes (newconf, dbus, application) to get every config setting could be very slow. + +Also, it won't work if dbus isn't running. Storing config in XDG_CONFIG_DIRS and using dbus for update notification is fast and works pretty well even if dbus isn't running. But, it's not network-transparent. + + +### seperation of Shortcuts by targets + +Seperate key shortcuts for diffenrent targets. Some shortcuts should be only used by programms, some for the environment(eg. Desktop System(KDE, Gnome), [[WindowManager|WindowManager]], ...), default task(eg. open/start programms/deamons/... or check for mails), get System infos, reboot/logoff/...) + + +### shortcuts Programm association + +The shortcuts should be saved in a per programm file for system defaults and user settings, where user settings have preference. There should be a layer that check the input and fetch the none programm shortcuts and give them the environments(eg. bash, [[WindowManager|WindowManager]]), system(eg. for reboot) or start a programm for Systeminfos, ... . + +If there is no shortcut description as system default or users setting for the active programm(on console the forground or if there are only backgroundprogramms the one with the lowest bg no., and on visualsystems(eg. X Window) the top programm) only the absolut basic system shortcuts should be interpreted(eg. change vitual terminal, change programm, reboot, ...) With the per program and user descript a nationalization is possible(use shortcuts that are possible withe users keybord(the key differ on systems, some keybords have not so much Fx key as a PC one) and the language(some key have other positions(eg. non aphanumeric key can be the main/default for a key or only accessible with key combinations. Which make some key combination impossible). On this way the user can define shortcuts that make a better association of the shortcut and what it does, or which is better to input, or make the use of alternate input device possible(needed for people with disablities(eg. one hand people) or remote controls for multimedia systems). + + +## Existing systems + + +### KDE + +This would probably be quite easy from the KDE side. We currently have all the general shortcuts (i.e., not those specific to a single application) in `~/.kde/share/config/kdeglobals`, but there would be nothing preventing us from reading and writing to another location or with another format. + + +#### What types of keys are being considered? + +Currently KDE distinguishes between default _Global Shortcuts_ and default _General Application Shortcuts_. Globals are for such things as switching between applications or desktops. Generals are the Open, Close, Copy sort of actions. + + +#### What is the intended set of user interfaces that this supports? Can keys be changed from the UI of individual apps rather than just globally? + +KDE allows the default keyboard shortcuts to be defined in the KControl application; however, users can change the *Help* shortcut (for example) to whatever else they want in any KDE application. + + +#### For application accelerators, how does conflict resolution work? + +If I change File/Save to something other than Control-S, it's pretty likely to conflict with other accelerators in many applications. + +I think it's to give the users a selection of which action to execute, as we do in KDE. If there's a shortcut conflict, any decision we'd make as programmers about which one to execute will be dangerous for the user. + + +#### Where are the settings saved? How are updates managed? + + * Regarding saving: we save the defaults in a single file. The kde libraries read the default shortcuts from that file. + * Regarding updates: for a running application, the old shortcuts continue to be effective until the next program start. If we wanted to update them in running programs we could send out a global DCOP message that the default shortcuts have been changed. The kde library would capture the message and updates its shortcuts against the kdeglobals file. Very easy. +(Ellis Whitehead) + + +### GNOME + +GNOME does various different things: + + * A large number of specific key shortcuts are configurable through GConf; things like launching the panel menu or (?) + * There is the notion of a "key-theme" for GTK+ that configures widget bindings. You can switch the current key theme through XSETTINGS, but you have to (restart the applications?) + * Application shortcuts (Save) are not generally configurable in GNOME apps. GTK+ has a mechanism for doing this for individual apps which is generally turned off in GNOME. +(Owen Taylor) + +Gnome keyboard interaction is documented here: [[http://developer.gnome.org/projects/gup/hig/2.0/input-keyboard.html|http://developer.gnome.org/projects/gup/hig/2.0/input-keyboard.html]] + + +### ROX + +ROX allows all keybindings to be changed dynamically, but doesn't provide any shared defaults. + + +### Mozilla + +For a discussion about keyboard shortcuts in Mozilla, see [[http://www.mozilla.org/access/keyboard/|http://www.mozilla.org/access/keyboard/]] + +Mozilla uses Control as modifier key, but this is [[customizable|[http://www.mozilla.org/unix/customizing.html]]]. + +Keybindings in the XPToolkit of Mozilla [[http://www.mozilla.org/xpfe/xptoolkit/keys.html|http://www.mozilla.org/xpfe/xptoolkit/keys.html]] + +-- Main.[[ThomasLeonard|ThomasLeonard]] - 08 Mar 2004 diff --git a/Specifications/desktop-bookmark-spec.mdwn b/Specifications/desktop-bookmark-spec.mdwn new file mode 100644 index 00000000..87c5b647 --- /dev/null +++ b/Specifications/desktop-bookmark-spec.mdwn @@ -0,0 +1,191 @@ + + +# Introduction + + +## Overview + +Bookmarks are widely-used part of the World Wide Web browsers. They are a mechanism through which a user can return to specific sites already visited, much like their book counterparts. + +Recently, bookmarks have become a feature for user with regards to browsing their file system, as a way to access recently used, or often used, places. + +Even the list of recently used files can be seen as being composed of short-lived bookmarks. + + +## Objectives of this specification + +This specification aims to do the following things: + +* Provide a standard mechanism for storing and accessing a list of bookmarks (in form of URI); +* Provide per-application and per-task bookmarks; +* Replace the [[Recent Files Storage Specification|Specifications/recent-file-spec]], providing a single specification for both bookmarks and recent files; +Applications implementing the following specification will have the ability to access all, or just a part of, the bookmarks, which will be stored in a system-wide fashion instead of re-implementing their bookmark system. This way, all the bookmarks associated to an application will be available to each instance of said application, and to other applications performing the same tasks. Also, a notification mechanism should be implemented so that every change inside the bookmarks should be propagated to each application using the bookmarks. + + +# Storage format + +For different desktops and applications to have access to the same information, a protocol for storing the bookmarks list has to be determined. + + +## Base layout + +A valid, UTF-8 encoded XML document will be used for storing the desktop bookmarks. The storage format will conform to the XBEL DTD with custom meta-data; see the [[XBEL|http://pyxml.sourceforge.net/topics/xbel/]] specification for the contents of the bookmark, title, desc and info elements used in this specification. + +A valid desktop bookmark stream must conform to the 1.0 version of the XBEL Specification. The root element must be the `xbel` element, with its `version` attribute set to "1.0". No `folder` element should be used, as well as no `alias` and `separator` elements; if any of those elements are found, they should be ignored. + +Each bookmark must have the `bookmark` element as root node. The target URI of the bookmark must be stored in the `href` attribute of the bookmark element. + +Each `bookmark` element should have its `added`, `modified` and `visited` attributes set with date and time specified as a string conformant to the [[ISO 8601|http://www.w3.org/TR/NOTE-datetime]] specification. The time should be relative to UTC time; local time should be converted to UTC before encoding, and converted back after reading the attribute payload. + + +## Desktop Bookmarks meta-data + +The owner for all the meta-data elements defined in this specification must be Freedesktop.Org. Thus, the `owner` attribute of the meta-data element containing the following elements must be set to `http://freedesktop.org`. Other meta-data, enclosed inside a `metadata` element with another, or no owner, should be ignored. + +All meta-data defined in this specification belongs to a namespace, named `bookmark` whose URI is `http://www.freedesktop.org/standards/desktop-bookmarks`, except for the `mime-type` element, whose namespace is to be named `mime` and must have this URI: `http://www.freedesktop.org/standards/shared-mime-info`. + +Each `metadata` element might contain any combination of the following elements, in any order: + +* The `mime-type` element is mandatory. It must contain the MIME Type of the target pointed by the URI, as defined by the [[Shared MIME|Specifications/shared-mime-info-spec]] Database. +* The `groups` element contains a list of `group` elements, each containing a group name. See the Registered Group Names section for more details on the group names defined by this specification. The groups element is not mandatory. +* The `applications` element contains a list of `application` elements, each referring to an application that has registered the bookmark. +* Each `application` element has a number of attributes: [[!table header="no" class="mointable" data=""" + **Attribute** | **Required** | **Notes** + name | Yes | The name of the application that has registered the bookmark. It must a unique name for each application. Every application element must have this attribute set + exec | Yes | The preferred command line to be used when launching the application; it might contain variables, see the list of valid exec attribute variables for more details. If no exec attribute has been provided, implementors should use the application name followed by the `%u` variable + count | Yes | The number of times the application has registered the bookmark. If not count attribute has been defined, then implementors should assume that the total number of registrations is equal to one +"""]] +|| + modified || Yes || The last time, expressed as a string conformant to the ISO 8601 specification and relative to UTC, that the application registered the bookmark. Each application element must have this attribute set +[[!table header="no" class="mointable" data=""" + timestamp | Yes | The last time, expresses in seconds from the system's Epoch, the application registered the bookmark. Each application element must have this attribute set. **This attribute has been deprecated since revision 0.8.5 of the specification, and should not be used by newly written code**. +"""]] +See the Applications section for the correct behaviour when handling duplicate application registrations. +The `applications` element is mandatory; every bookmark must have at least one valid `application` element. + +* The `icon` element, if present, specifies the icon that should be associated to the bookmark. The icon element must have the following attributes: [[!table header="no" class="mointable" data=""" + **Attribute** | **Required** | **Notes** + type | Yes | The MIME type, belonging to the image/* family of MIME types, of the icon. If no type is set, implementors should use the application/octect-stream MIME type + href | Yes | The URI to the icon file + name | Yes | The name of the icon inside an icon theme, following the Icon Naming Specification +"""]] +Implementors should use the file specified inside the href or the name attributes of the icon element when showing the bookmark. If both the href and the name attributes are specified, the href element takes precedence. +* The `private` element, if present, alters the visibility of the bookmark. A bookmark should be considered private to the groups where it belongs and to the applications that have registered it. See the Visibility section. + +# Storage Files + +Desktop bookmarks file might contain a variable number of bookmarks. Each bookmark file should contain at least one bookmark stored using the format described previously. The default extension for the desktop bookmarks file should be `xbel`. Imlementors should use the same ordering of the bookmarks stored inside the bookmarks file when displaying them, and should take care into storing the bookmarks inside a bookmarks file using the same order in which they are displayed. + +Implementors should also take care of avoiding concurrent accesses to these files; for instance, by using file locking techniques. + + +## File location + +Standard locations for bookmark files defined in this specification are: +[[!table header="no" class="mointable" data=""" + **File** | **Use** + $XDG_USER_DATA/recently-used.xbel | This file must be used for the bookmarks to recently used resources + $XDG_USER_DATA/recent-applications.xbel | This file must be used for the bookmarks to recently used applications, in form of bookmarks to their [[desktop entries|Specifications/desktop-entry-spec]] + $XDG_USER_DATA/shortcuts.xbel | This file must be used for bookmarks to user-defined folders +"""]] + +Application specific desktop bookmark files should be stored under the $XDG_DATA_DIRS/desktop-bookmarks directory. Each directory in the search path should be used. When two desktop bookmark files have the same name, the one appearing earlier should be used. Only files with the `xbel` extension are used; other files are ignored. + + +## File encoding + +All text in the file should be stored in the UTF-8 encoding. Standard encoding rules for XML and XBEL documents applies the desktop bookmark files. No local paths are allowed in the URI tag; they should be converted to a valid URI with a "file" scheme. Items with the same URI are not allowed. + + +## Change notification + +Notification should be accomplished by simply monitoring the files for changes. This can be done by either polling the file every so often, or using a libraries like FAM, d-notify or i-notify. + + +# Registered meta-data + +The meta-data associated to this spec will contain informations about the applications that have registered a bookmark, the groups to which a bookmark belongs and its visibility in relation to applications and groups. + + +## Applications + +Bookmarks must have at least an application registration. + +Bookmarks might be registered by more than one application. For each application registering a bookmark, will be stored the application's name, the application's command line, the number of registrations for the application and the last time the application registered a bookmark, the timestamp (seconds from the system's epoch) of the registration time. + +If an application tries to register again a bookmark, that is: if there already is an application tag with its name attribute set to the same name passed by the application, then the application tag should have the content of the timestamp attribute updated, and the content of the count attribute increased by one. + + +### List of valid exec attribute variables + +Each exec attribute of the application element may take a number of arguments which will be expanded by the implementor. + +Literal % characters must be escaped as %%. Each unrecognised variable should be left unexpanded. + +Recognised variables are as follows: +[[!table header="no" class="mointable" data=""" + %f | the path of the file/directory, retrieved from the URI + %u | the literal URI for the bookmark +"""]] + + +## Groups + +Groups implement meta-classes of bookmarks. The bookmarks belonging to a group (or a set of groups) will be shared across each member of the group. + +For instance, each email client application could register its bookmarks under the group Mail, so that each other mail-related application could access those bookmarks. + +For a list of registered group names, see the Registered group names section. + + +## Visibility + +The privacy hint of a bookmark is set using the private element. Each item with this hint set should be visible only for the groups and applications that registered it. + + +# Appendix A: Implementation recommendations + +Any implementor of this specification should conform to these recommendations: + +* Implementors should use the command line inside the exec attribute of the application element, when launching a bookmark with a specific application. If no exec attribute was found, implementors should try the application's name stored inside the name attribute, followed by a space character and the bookmark's URI. If this fails, the default application for the bookmark's MIME type should be invoked using the bookmark's URI. +* No duplicate entries should be found inside a valid desktop bookmark data stream. If two or more applications register a bookmark to the same URI, implementors should update the modified attribute of the bookmark element; a new application element should be added for each application that is registering the bookmark; if any of the applications is also adding group names, all of these must be merged with the previously set group names; the private element should be set the first time an application requires it. If the same application registers the same bookmark, only the modified attribute of the bookmark element, the timestamp and count attributes of the application element with the same application's name set into the name attribute and the private element should be modified. +* If an icon for the bookmark item is shown, it should be taken from the image file stored inside the href attribute of the icon element; if no such element exists inside the meta-data for the bookmark item, the icon should be the thumbnail of the resource (if available), retrieved using the [[thumbnail managing specification|http://triq.net/~jens/thumbnail-spec/index.html]], or - if no thumbnail is present - the icon associated to the MIME type of the resource. + +# Appendix B: Registered group names + +Remember, these are case-sensitive. When using a group name described in the list below it is strongly recommended to also include the group listed under Related Groups. If a group has multiple related groups the most suitable related group should be included. +[[!table header="no" class="mointable" data=""" + **Group** | **Description** | **Related Groups** + Development | A bookmark related to a development environment | + Office | A bookmark related to an office type document or folder | + Database | A bookmark related to a database application | Office; Development + Email | A bookmark related to an email application | Office + Presentation | A bookmark related to a presentation application | Office + Spreadsheet | A bookmark related to a spreadsheet application | Office + WordProcessor | A bookmark related to a word processing application | Office + Graphics | A bookmark related to a graphical application | + TextEditor | A bookmark related to a text editor | + Viewer | A bookmark related to any kind of file viewer | + Archive | A bookmark related to an archive file | + Multimedia | A bookmark related to a multimedia file or application | + Audio | A bookmark related to an audio file or application | Multimedia + Video | A bookmark related to a video file or application | Multimedia + Photo | A bookmark related to a digital photography file or application | Multimedia; Graphics; Viewer + Application | Special bookmark for application launchers | +"""]] + + +# Appendix C: How to add a new desktop bookmark file + +In order to properly install a new desktop bookmark file, third party applications should: + +* Install new desktop bookmark files inside $XDG_DATA_DIR/desktop-bookmarks for each desktop bookmark file. Please, namespace the filename, as in "vendor-foo.xbel", or use a subdirectory or $XDG_DATA_DIR/desktop-bookmarks so you have "vendor/foo.xbel." Please ensure all desktop bookmark entries are valid. + + +--- + + + +Author: Emmanuele Bassi + +Version: 0.8.5 diff --git a/Specifications/desktop-config-spec.mdwn b/Specifications/desktop-config-spec.mdwn new file mode 100644 index 00000000..a8b09720 --- /dev/null +++ b/Specifications/desktop-config-spec.mdwn @@ -0,0 +1,13 @@ + + +# Desktop configuration specification + + +## Discussion + +If you have ideas you want to suggest but don't want to edit this main document, please go to the [[Discussion Page|Specifications/desktop-config-spec/Discussion]]. + + +## Availability + +[[ViewCVS|http://cvs.pvanhoof.be/cgi-bin/viewcvs.cgi/desktop-config-standard/]] [[Tarball|http://cvs.pvanhoof.be/cgi-bin/viewcvs.cgi/desktop-config-standard/desktop-config-standard.tar.gz?tarball=1]] diff --git a/Specifications/desktop-entry-spec.mdwn b/Specifications/desktop-entry-spec.mdwn new file mode 100644 index 00000000..ac0dfcb4 --- /dev/null +++ b/Specifications/desktop-entry-spec.mdwn @@ -0,0 +1,23 @@ + + +## Desktop Entry Specification + +The desktop entry specification describes desktop entries: files describing information about an application such as the name, icon, and description. These files are used for application launchers and for creating menus of applications that can be launched. + +The entry format described in this document is similar to that traditionally used by KDE and GNOME. Both KDE and GNOME implement version 1.0 of the specification. + + +### Mailinglist + +Discussion of this specification should occur on [[xdg|http://lists.freedesktop.org/mailman/listinfo/xdg]]. + + +### CVS + +The [[CVS|http:GettingInvolved#CVS]] module for this spec is [[desktop-entry-spec|http://cvs.freedesktop.org/menus/desktop-entry-spec/]]. + + +### Spec + + * [[Latest version|http://standards.freedesktop.org/desktop-entry-spec/latest/]] + * Version 1.0 - [[html (one page)|http://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-1.0.html]] - [[html (multiple pages)|http://standards.freedesktop.org/desktop-entry-spec/1.0/]] - [[xml|http://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-1.0.xml]]
\ No newline at end of file diff --git a/Specifications/desktop-language-checking-spec.mdwn b/Specifications/desktop-language-checking-spec.mdwn new file mode 100644 index 00000000..b357890a --- /dev/null +++ b/Specifications/desktop-language-checking-spec.mdwn @@ -0,0 +1,17 @@ + + +# Desktop Language Checking Spec + +The purpose of this specification is to provide a common set of tools for spell and grammar checking on the free desktop. + + +## Enchant + +The spell check interface. + +See [[http://www.abisource.com/projects/enchant/|http://www.abisource.com/projects/enchant/]] + + +## Elixir + +[**Proposed**] The grammar and style checking interface diff --git a/Specifications/desktopcouch.mdwn b/Specifications/desktopcouch.mdwn new file mode 100644 index 00000000..603bd308 --- /dev/null +++ b/Specifications/desktopcouch.mdwn @@ -0,0 +1,51 @@ + +* Rodrigo Moya (rodrigo AT gnome-db.org) +* Stuart Langridge (stuart.langridge AT canonical.com) +* Vincenzo di Somma (vincenzo.di.somma AT canonical.com) +[[!toc ]] + + +### Purpose + +Integration of [[CouchDB|http://couchdb.apache.org]] storage into desktop applications, for automatic replication and synchronization of data between computers. + + +### Examples + +* Store notes, contacts, calendars, bookmarks, etc on a central storage +* Replicate and synchronize that data from users' desktops to several machines +* Provide servers with the ability to provide a web interface to display and manage that data from a browser everywhere (like [[Ubuntu One|http://ubuntuone.com]] or [[Midgard|http://www.midgard-project.org/]]) + +### Software + +Applications implementing the CouchDB replication protocol: + +* [[CouchDB|http://couchdb.apache.org]] +* [[Midgard|http://www.midgard-project.org/]] +Development tools: + +* [[couchdb-glib|https://launchpad.net/couchdb-glib]] is a GLib-based API implementing the [[CouchDB REST API|http://wiki.apache.org/couchdb/HTTP_REST_API]] plus some top-level utilities to make things easier for developers. With bindings for other languages (full list at [[http://live.gnome.org/GObjectIntrospection/Users|http://live.gnome.org/GObjectIntrospection/Users]]) via GObject introspection. +* [[desktopcouch.records|https://launchpad.net/desktopcouch]] is a Python API to allow Python applications to connect to a Desktop CouchDB. The desktopcouch project which it is part of manages all the infrastructure described in this specification. + +### Formats + +Being this a vendor independent solution, anyone can set up a [[CouchDB|http://couchdb.apache.org]] instance on their server and allow others to replicate/synchronize their data there. but for this to work correctly, we need standard formats for every specific record type that is going to be stored in the database. The following links get you to pages describing that format for the following record types: + +* [[Notes|Specifications/desktopcouch/note]]: used by [[Tomboy|http://projects.gnome.org/tomboy/]] +* [[Bookmarks|Specifications/desktopcouch/bookmark]]: used by [[Bindwood|http://launchpad.net/bindwood]] for Firefox +* [[Contacts|Specifications/desktopcouch/contact]]: used by [[Evolution|http://projects.gnome.org/evolution/]], Akonadi +* [[Tasks|Specifications/desktopcouch/task]]: used by [[Evolution|http://projects.gnome.org/evolution/]] +* [[Internal Replication|Specifications/desktopcouch/replication]]: used by desktopcouch itself to maintain replication peerage. + +### Reserved database names + +* management +* users + +### Documentation + +See the [[desktopcouch documentation page|Specifications/desktopcouch/Documentation]]. + +--- + + [[CategoryHomepage|CategoryHomepage]] diff --git a/Specifications/desktopcouch/Documentation.mdwn b/Specifications/desktopcouch/Documentation.mdwn new file mode 100644 index 00000000..6311df32 --- /dev/null +++ b/Specifications/desktopcouch/Documentation.mdwn @@ -0,0 +1,39 @@ + + +# Desktop Couch documentation + +What do you plan to use desktopcouch for? + +[[!toc 2]] + + +## My applications use desktopcouch, and I want to understand more about it and look at the data + +* [[Installing desktopcouch|Specifications/desktopcouch/Documentation/Installing]] - how to install desktopcouch +* [[Viewing my data in desktopcouch|Specifications/desktopcouch/Documentation/ViewingMyData]] - how to see your data in desktopcouch, and how to work with it and delete or change it +* [[Summary of desktopcouch|http://www.kryogenix.org/days/2009/09/03/desktop-couch-irc-talk]] - an IRC lecture given as part of Ubuntu Developer Week, which summarises desktopcouch and its goals and some usage tips. This is quite technical in places, and you can ignore all the parts about how to develop with desktopcouch, but it provides a summary of what desktopcouch is. +* [[Troubleshooting|Specifications/desktopcouch/Documentation/Troubleshooting]]: if desktopcouch seems to not be working, here are some things you can try. + +## I am a developer, and I want the applications I write to store data in and work with desktopcouch + +* [[Summary of desktopcouch|http://www.kryogenix.org/days/2009/09/03/desktop-couch-irc-talk]] - an IRC lecture given as part of Ubuntu Developer Week, which summarises desktopcouch and its goals and some usage tips. +* [[Code tutorial: make your application sync with Ubuntu One|http://arstechnica.com/open-source/guides/2009/12/code-tutorial-make-your-application-sync-with-ubuntu-one.ars/1]]: an Ars Technica article by Ryan Paul explaining how desktopcouch works and how to use it from an application, with examples. +* [[Simple guide to using desktopcouch|Specifications/desktopcouch/Documentation/SimpleGuide]]: some code snippets and general commentary on how to use desktopcouch from your application. +* [[Storing design documents and views on the filesystem|Specifications/desktopcouch/Documentation/DesignDocsFilesystem]] -Desktop Couch will automatically create databases and design documents for you on startup by inspecting the filesystem, meaning that you do not need to check in your application whether your views exist. This document explains how. +* [[Troubleshooting|Specifications/desktopcouch/Documentation/Troubleshooting]]: if desktopcouch seems to not be working, here are some things you can try. +* The [[desktopcouch mailing list|http://groups.google.com/group/desktop-couchdb]] is a good place to ask questions and talk about what you're doing with desktopcouch + +## I am a developer, and I want to hack on the desktopcouch code or one of the desktopcouch APIs like couchdb-glib + +* [[How desktopcouch works|Specifications/desktopcouch/Documentation/How_Desktopcouch_Works]]: describing how the underlying desktopcouch services fit together. +* [[Troubleshooting|Specifications/desktopcouch/Documentation/Troubleshooting]]: if desktopcouch seems to not be working, here are some things you can try. +* [[Get the code|Specifications/desktopcouch/Documentation/Get_The_Code]]: where the desktopcouch code is, and how to get it +* The [[desktopcouch mailing list|http://groups.google.com/group/desktop-couchdb]] is a good place to ask questions and talk about what you're doing with desktopcouch + +## I am a developer, and I want to port desktopcouch to a new distro, operating system, or device + +* [[Simple guide to using desktopcouch|Specifications/desktopcouch/Documentation/SimpleGuide]]: some code snippets and general commentary on how to use desktopcouch from your application. +* [[How desktopcouch works|Specifications/desktopcouch/Documentation/How_Desktopcouch_Works]]: describing how the underlying desktopcouch services fit together. +* [[Get the code|Specifications/desktopcouch/Documentation/Get_The_Code]]: where the desktopcouch code is, and how to get it +* [[Troubleshooting|Specifications/desktopcouch/Documentation/Troubleshooting]]: if desktopcouch seems to not be working, here are some things you can try. +* The [[desktopcouch mailing list|http://groups.google.com/group/desktop-couchdb]] is a good place to ask questions and talk about what you're doing with desktopcouch
\ No newline at end of file diff --git a/Specifications/desktopcouch/Documentation/DesignDocsFilesystem.mdwn b/Specifications/desktopcouch/Documentation/DesignDocsFilesystem.mdwn new file mode 100644 index 00000000..523a12eb --- /dev/null +++ b/Specifications/desktopcouch/Documentation/DesignDocsFilesystem.mdwn @@ -0,0 +1,26 @@ + + +# Storing design documents and views on the filesystem + + +## Creating databases, design documents, and views + +Desktop Couch will automatically create databases and design documents for you on startup by inspecting the filesystem, meaning that you do not need to check in your application whether your views exist. It is of course possible to create views directly through the Records API, but having them created via the filesystem allows managing of the view definitions more easily (they are in separately editable files, which helps with version control) and packaging (the files can be separately stored in a distribution package and installed into the system-level `XDG_DATA_DIR` rather than the user-level folder). + +You will need to [[restart desktopcouch|http://www.freedesktop.org/wiki/Specifications/desktopcouch/Documentation/Troubleshooting]] for changes to take effect. + + +### To create a database + +Create a file `$XDG_DATA_DIR/desktop-couch/databases/YOUR_DB_NAME/database.cfg` + +This file can currently be empty (in future it may contain database setup and configuration information). + + +### To create a design document + +Create a file `$XDG_DATA_DIR/desktop-couch/databases/YOUR_DB_NAME/_design/DESIGN_DOC_NAME/views/VIEW_NAME/map.js` containing the map function from your view. + +If you also require a reduce function for your view, create a file `$XDG_DATA_DIR/desktop-couch/databases/YOUR_DB_NAME/_design/DESIGN_DOC_NAME/views/VIEW_NAME/reduce.js`. + +This is compatible with the filesystem view structure from [[CouchApp|CouchApp]] and CouchDBKit. diff --git a/Specifications/desktopcouch/Documentation/Get_The_Code.mdwn b/Specifications/desktopcouch/Documentation/Get_The_Code.mdwn new file mode 100644 index 00000000..e0e422d9 --- /dev/null +++ b/Specifications/desktopcouch/Documentation/Get_The_Code.mdwn @@ -0,0 +1,5 @@ + + +# Get the code + +The desktopcouch project is on Launchpad, at [[http://launchpad.net/desktopcouch|http://launchpad.net/desktopcouch]]. You can fetch the latest trunk code with bzr by doing `bzr branch lp:desktopcouch`. You can also download release tarballs from [[https://launchpad.net/desktopcouch/+download|https://launchpad.net/desktopcouch/+download]]. diff --git a/Specifications/desktopcouch/Documentation/How_Desktopcouch_Works.mdwn b/Specifications/desktopcouch/Documentation/How_Desktopcouch_Works.mdwn new file mode 100644 index 00000000..f1d66436 --- /dev/null +++ b/Specifications/desktopcouch/Documentation/How_Desktopcouch_Works.mdwn @@ -0,0 +1,51 @@ +# How desktopcouch works + +The process of giving every user a CouchDB for their applications to work with involves a number of engineering choices. This document explains how all those parts fit together and gives some indication as to why the decisions were made. + +If you are using desktopcouch from your applications, or are looking at your desktop CouchDB in a web browser, you don't need to read this document (but go ahead if you want to). It's for people hacking on the core of desktopcouch or people trying to debug strange problems. + + +## Finding the desktopcouch port number + +The Desktop Couch CouchDB server runs on a randomly chosen port. This is because a fixed port would not make sense on a multi-user machine. Since the port is randomly generated, there has to be a way to discover the port; desktopcouch provides a D-Bus API to do so. You can discover the port from the command line with + + dbus-send --session --dest=org.desktopcouch.CouchDB \ + --print-reply --type=method_call / \ + org.desktopcouch.CouchDB.getPort + +Calling the D-Bus getPort API actually starts desktopcouch if it is not already running. This means that desktopcouch does not impact desktop startup time for people who don't use it. It also means that the API is the only reliable way to discover the port; do not grovel through the couchdb log files or `lsof` yourself to get it. + +It is safe to call getPort if desktopcouch is already running; it will simply return the port of the running desktop CouchDB. + +Libraries that wrap desktopcouch, such as `desktopcouch.records` and `couchdb-glib`, should call this API for their users. Users should not have to manually call the D-Bus API themselves, unless they're programming at a very low level. + +The D-Bus getPort API is provided by `/usr/lib/desktopcouch/desktopcouch-service`. This script is run by D-Bus activation, and takes care of starting up desktopcouch if desktopcouch is not already running. + +Desktopcouch should never exit once it is running. However, it may crash; no software is perfect. Applications should be robust against desktopcouch crashing; if the port stops responding, call the D-Bus `getPort` API again, which will restart desktopcouch if crashed. Wrapper libraries such as `desktopcouch.records` should take care of this for applications and not expose this implementation detail where possible. + + +## The desktopcouch startup process + +All desktopcouch's files are stored in the appropriate folders according to the [[XDG BaseDirectory specification|http://standards.freedesktop.org/basedir-spec/basedir-spec-0.6.html]]. On a default machine, desktopcouch-service will look for a CouchDB ini settings file in `$HOME/.config/desktop-couch/desktop-couchdb.ini`. If this ini file does not exist it is created (most of this initialisation work is done in the desktopcouch Python library, specifically `local_files.py` and `start_local_couchdb.py`). Startup also looks for and uses ini files in `/etc/xdg/desktop-couch`; desktopcouch ships with `compulsory-auth.ini` in this folder which sets CouchDB to _require_ authentication for access. The distinction between these two places is that the user-specific ini file is regenerated if it doesn't exist, and contains user-specific data such as the user's OAuth tokens; ini files in `/etc/xdg/desktop-couch` are settings that apply to all desktop CouchDBs. + +On first desktopcouch startup, when the new ini file is created, desktopcouch randomly generates a basic authentication username/password and an OAuth token and token secret, for controlling access to the user's desktop CouchDB. It also writes a "bookmark" file at `$HOME/.local/share/desktop-couch/couchdb.html`, which "forwards" the user to the Futon web interface for their desktop CouchDB. This "forwarding" file is needed because CouchDB is running on a randomly chosen port and therefore Futon itself can't be bookmarked (as the port will change whenever desktopcouch is restarted). So the user can bookmark the "bookmark page" instead, at the `file:///home/USERNAME/.local/share/desktop-couch/couchdb.html` URL. + +CouchDB writes out a logfile which can be used for troubleshooting to `$HOME/.cache/desktop-couch/desktop-couchdb.log`, and also writes its stdout and stderr to the same folder. See [[the Troubleshooting document|http://www.freedesktop.org/wiki/Specifications/desktopcouch/Documentation/Troubleshooting]] for details. + + +## Authentication + +Access to desktopcouch requires authentication, so that only the owner of the desktopcouch can see the data in it. Authentication is through two-legged OAuth. The OAuth token and token secret should be retrieved from the keyring when required; do not cache these tokens, but request them when needed. (They may change; if the ini file is deleted, it will be regenerated with new tokens and the keyring will be updated.) Libraries that access desktopcouch should seamlessly access these tokens and use them to OAuth-sign requests without bothering the user. + +When the ini file is generated, an HTTP basic authentication username and password are also generated. Do not use basic auth to access desktopcouch from code; use OAuth. The basic auth username and password are generated so that the user can have web-browser access to Futon from the bookmark file; if web browsers did OAuth natively, this wouldn't be required. However, if browsers start doing OAuth natively, the basic-auth username/password will be removed; do not rely on them. Use OAuth. + + +## Replication + +The `desktopcouch-service` daemon also manages replication — this is how data is synced between "paired" desktop CouchDBs. Every ten minutes (time hardcoded in `desktopcouch/replication.py`), the daemon starts the replication process, replicating all databases to all paired servers. Paired servers are defined by a [[paired-server record|http://groups.google.com/group/desktop-couchdb/web/paired-servers]] in the `management` database. (The management database is one of the [[reserved databases|http://www.freedesktop.org/wiki/Specifications/desktopcouch#head-247e7700f376eac06430616efc17dac5b722ae9f]]; reserved databases are not replicated.) + +A paired-server record can be added manually, or can be added by the `desktopcouch-pair` tool (available in the desktopcouch-tools package on Ubuntu). Paired servers come in two sorts; local servers and cloud servers. Local servers are those on your local network; this is used to set up synchronisation between two of your own machines without connecting to the wider internet. Cloud servers are servers on the internet. The distinction between the two is that for two local servers A and B, A holds a paired-server record for B and does [[CouchDB pull replication|http://books.couchdb.org/relax/reference/replication]] from B, and B holds a paired-server record for A and does pull replication from A. For a local server L paired with a cloud server C, L holds a paired-server record for C and does both [[push and pull replication|http://books.couchdb.org/relax/reference/replication]] from/to C. (A cloud server can't connect to a local server, since a local server is almost certainly NATted or behind a firewall or both.) + +A cloud paired-server record contains a server address and port for the cloud server, and a service_name. This service_name corresponds to a Python module in `desktopcouch/replication_services`, which implements specific replication for this cloud service. + +A local paired-server record contains the unique identifier for the paired server. Since desktopcouch runs on a randomly chosen port, and since local machines are usually issued IP addresses by DHCP, both the host and port may change at arbitrary intervals. So, if a desktopcouch is paired with other local desktopcouches, `desktopcouch-service` advertises the host and port with zeroconf, tagging the advertisement with that desktopcouch's unique identifier. (A given desktopcouch's unique identifier is defined in a server-identity record, in the management database, with `record_type='http://www.freedesktop.org/wiki/Specifications/desktopcouch/server_identity'`.) At replication time, `desktopcouch-service` walks through the list of paired servers, and if it finds a local server, looks to see if that local server is currently advertising via zeroconf; if it is not, it skips that record. If that local server is advertising, then `desktopcouch-service` uses the zeroconf advertisement to establish a host and port for the local server, and then does pull replication with it. diff --git a/Specifications/desktopcouch/Documentation/Installing.mdwn b/Specifications/desktopcouch/Documentation/Installing.mdwn new file mode 100644 index 00000000..ad0d2885 --- /dev/null +++ b/Specifications/desktopcouch/Documentation/Installing.mdwn @@ -0,0 +1,26 @@ + + +# Installing Desktop Couch + + +## Ubuntu + + +### 9.10 + +Desktop Couch is included in Ubuntu 9.10 by default; you don't have to do anything to install it. + + +### Ubuntu 9.10 flavours (Kubuntu, Xubuntu) + +`apt-get install desktopcouch` + + +## ArchLinux + +If you use yaourt, then `yaourt -S desktopcouch` to install. If not, download desktopcouch from [[http://aur.archlinux.org/packages.php?ID=33019|http://aur.archlinux.org/packages.php?ID=33019]] and then follow the instructions at [[http://wiki.archlinux.org/index.php/PKGBUILD|http://wiki.archlinux.org/index.php/PKGBUILD]] to install. + + +## Gentoo + +The Gentoo repository for desktopcouch is at [[http://gitorious.org/tante_overlay|http://gitorious.org/tante_overlay]]. Gentoo users can just run `layman -a tante && emerge desktopcouch` to install. diff --git a/Specifications/desktopcouch/Documentation/SimpleGuide.mdwn b/Specifications/desktopcouch/Documentation/SimpleGuide.mdwn new file mode 100644 index 00000000..500ec73c --- /dev/null +++ b/Specifications/desktopcouch/Documentation/SimpleGuide.mdwn @@ -0,0 +1,190 @@ +# Simple Guide to using desktopcouch in your applications + +This document describes in basic terms how to store data to and retrieve data from desktopcouch for application developers. + + +## desktopcouch.records + +`desktopcouch.records` is the Python library for accessing desktopcouch from applications. Basic use is as follows (simple examples are also available offline in `/usr/share/doc/python-desktopcouch-records/api/records.txt`): + + >>> from desktopcouch.records.server import CouchDatabase + >>> from desktopcouch.records.record import Record + +Create a database object. Your database needs to exist. If it doesn't, you can create it by passing create=True. + + >>> db = CouchDatabase('testing', create=True) + +Create a Record object. Records have a record type, which should be a URL. The URL should point to a human-readable document which describes your record type. (This is not checked, though.) You can pass in an initial set of data. + + >>> r = Record({'a':'b'}, record_type='http://example.com/testrecord') + +Records work like Python dicts. + + >>> r['c'] = ['d','e','f'] + +Save the record into the database with put_record: + + >>> record_id = db.put_record(r) + +Fetch existing records from the database by ID: + + >>> fetched = db.get_record(record_id) + >>> print fetched['a'] + b + >>> + +There is no ad-hoc query functionality. + +For views, you should specify a design document for all calls. + +Understanding views is the key to using desktopcouch. Do not think of a view as being like a SQL statement. Instead, a view should basically return all your records, with a key of the thing you care about. So, if you have a load of records which are about podcasts, and you want to get the record with a particular URL, then your view might look like: + + function(doc) { emit(doc.url, doc) } + +and you would then call this view and slice the result with the key you want: + + results = db.execute_view("myview", "myapp") + results_i_care_about = results[url_i_care_about] + +The CouchDB book has much more about views at [[http://books.couchdb.org/relax/design-documents/views|http://books.couchdb.org/relax/design-documents/views]]. + +The basics of creating and deleting views in desktopcouch: + + >>> design_doc = "application" + +To create a view: + + >>> map_js = """function(doc) { emit(doc._id, null) }""" + >>> reduce_js = None + >>> db.add_view("blueberries", map_js, reduce_js, design_doc) + +List views for a given design document: + + >>> db.list_views(design_doc) + ['blueberries'] + +Test that a view exists: + + >>> db.view_exists("blueberries", design_doc) + True + +Execute a view. Results from execute_view() take list-like syntax to pick one or more rows to retrieve. Use index or slice notation. + + >>> result = db.execute_view("blueberries", design_doc) + >>> for row in result["idfoo"]: + ... pass # all rows with id "idfoo". Unlike lists, may be more than one. + +Finally, remove a view. It returns a dict containing the deleted view data. + + >>> db.delete_view("blueberries", design_doc) + {'map': 'function(doc) { emit(doc._id, null) }'} + +For most operations (except testing existence), if the view you ask for does not exist, the function will throw a [[KeyError|KeyError]] exception. + +There are also some introductory desktopcouch code snippets on the [[Quickly code snippets|https://wiki.ubuntu.com/Quickly/Snippets]] page. + + +## couchdb-glib + +`couchdb-glib` is a C library for accessing CouchDB servers, included desktopcouch. It heavily uses Glib's GObject to offer a nice API that easily integrates into GNOME/GTK applications. + +To start using, first thing is to include the top-level header file + + #include <couchdb-glib/couchdb-glib.h> + +The entry point for the API is the _CouchDBSession_ object, which can be obtained as shown in the following example: + + CouchDBSession *couchdb; + + couchdb = couchdb_session_new ("http://localhost:5984"); + +The only argument to _couchdb_session_new_ is the URL of the CouchDB instance to connect to. If NULL, it would use the system-wide CouchDB instance (located at [[http://localhost:5984|http://localhost:5984]]). If you want to connect to desktopcouch without having to know what port it is listening in, you can use the high-level object [[DesktopcouchSession|DesktopcouchSession]], which is available in desktopcouch-session.h: + + #include <desktopcouch-glib/desktopcouch-session.h> + + DesktopcouchSession *couchdb; + + couchdb = desktopcouch_session_new (); + +Once you have a _[[CouchdbSession|CouchdbSession]]_ object, you can do all the operations the API provides from it. Please note that most of the API functions have a _GError_ argument as the last parameter, which is used to return error information to the caller. + + +### Working with databases + +First, you can list the databases that are available: + + GSList *couchdb_session_list_databases (CouchdbSession *couchdb, GError **error); + +This would return a list of _[[CouchdbDatabaseInfo|CouchdbDatabaseInfo]]_ structures, which contain information (such as database name, number of documents, etc) for each database available on the CouchDB instance you're connecting to. If you already know the name of a database, you can easily obtain that information for that specific database with the following function: + + CouchdbDatabaseInfo *couchdb_session_get_database_info (CouchdbSession *couchdb, const char *dbname, GError **error); + +You can also create new databases: + + gboolean couchdb_session_create_database (CouchdbSession *couchdb, const char *dbname, GError **error); + +Or delete existing databases: + + gboolean couchdb_session_delete_database (CouchdbSession *couchdb, const char *dbname, GError **error); + + +### Working with documents + +Once you know what database you'll be working with, you can use the documents part of the API. First, you need to obtain a reference to the database you want to use, which is done with _couchdb_session_get_database_: + + CouchdbDatabase *couchdb_session_get_database (CouchdbSession *couchdb, const gchar *dbname, GError **error); + +Then, the _[[CouchdbDatabase|CouchdbDatabase]]_ object offers access to the documents contained in that database: + + GSList *couchdb_database_list_documents (CouchdbDatabase *database, const char *dbname, GError **error); + +This returns a list of _CouchDBDocumentInfo_, which is a struct that contains the unique identifier and last revision number for a specific document. This doesn't retrieve the actual document's contents, just information about them. You can retrieve all documents at once by calling: + + GSList *couchdb_database_get_all_documents (CouchdbDatabase *database, GError **error); + +This returns a GSList of _[[CouchdbDocument|CouchdbDocument]]_s. Or, to get a a specific document: + + CouchDBDocument *couchdb_database_get_document (CouchdbDatabase *database, const char *docid, GError **error); + +This returns a _[[CouchdbDocument|CouchdbDocument]]_ object, which lets you read/modify a document in memory. You can also create an empty _[[CouchdbDocument|CouchdbDocument]]_ object in memory with the _couchdb_document_new_ function, for later saving it to the database. There are several functions you'd want to know for retrieving/setting fields' data on a document: + + gboolean couchdb_document_has_field (CouchdbDocument *document, const char *field); + void couchdb_document_remove_field (CouchdbDocument *document, const char *field); + gboolean couchdb_document_get_boolean_field (CouchdbDocument *document, const char *field); + void couchdb_document_set_boolean_field (CouchdbDocument *document, const char *field, gboolean value); + gint couchdb_document_get_int_field (CouchdbDocument *document, const char *field); + void couchdb_document_set_int_field (CouchdbDocument *document, const char *field, gint value); + gdouble couchdb_document_get_double_field (CouchdbDocument *document, const char *field); + void couchdb_document_set_double_field (CouchdbDocument *document, const char *field, gdouble value); + const char *couchdb_document_get_string_field (CouchdbDocument *document, const char *field); + void couchdb_document_set_string_field (CouchdbDocument *document, const char *field, const char *value); + CouchdbStructField *couchdb_document_get_struct_field (CouchdbDocument *document, const char *field); + void couchdb_document_set_struct_field (CouchdbDocument *document, + const char *field, + CouchdbStructField *value); + +These functions allow you to check for the existence of a field in a document (_couchdb_document_has_field_), remove a field from it (_couchdb_document_remove_field_) and retrieve/set the value of a field in different formats (boolean, integer, double, string). A special mention is needed for the _couchdb_document_get_struct_field_ and _couchdb_document_get_struct_field_, which allow you to have object fields (or structs, if you find it easier to understand it that way) on your documents. Object fields can in turn contain other object fields, and they are manager by the _[[CouchdbStructField|CouchdbStructField]]_ object, which contains very similar methods to those of _[[CouchdbDocument|CouchdbDocument]]_ shown above: + + gboolean couchdb_struct_field_get_boolean_field (CouchdbStructField *sf, const char *field); + void couchdb_struct_field_set_boolean_field (CouchdbStructField *sf, const char *field, gboolean value); + gdouble couchdb_struct_field_get_double_field (CouchdbStructField *sf, const char *field); + void couchdb_struct_field_set_double_field (CouchdbStructField *sf, const char *field, gdouble value); + gint couchdb_struct_field_get_int_field (CouchdbStructField *sf, const char *field); + void couchdb_struct_field_set_int_field (CouchdbStructField *sf, const char *field, gint value); + const char *couchdb_struct_field_get_string_field (CouchdbStructField *sf, const char *field); + void couchdb_struct_field_set_string_field (CouchdbStructField *sf, const char *field, const char *value); + CouchdbStructField *couchdb_struct_field_get_struct_field (CouchdbStructField *sf, const char *field); + void couchdb_struct_field_set_struct_field (CouchdbStructField *sf, const char *field, CouchdbStructField *value); + +Once you have modified your document and want to save it to the database, you use the following function: + + gboolean couchdb_database_put_document (CouchdbDatabase *database, CouchdbDocument *document, GError **error); + +Also, you can remove documents, based on their unique ID: + + gboolean couchdb_database_delete_document (CouchdbDatabase *database, CouchdbDocument *document, GError **error); + + +### Working with contacts + +couchdb-glib provide high-level API for dealing with _[[CouchdbDocument]]_ that are contacts. For that, you can use desktopcouch-glib, which is part of couchdb-glib, and which provides high level classes to make it easier to deal with desktopcouch data. diff --git a/Specifications/desktopcouch/Documentation/Troubleshooting.mdwn b/Specifications/desktopcouch/Documentation/Troubleshooting.mdwn new file mode 100644 index 00000000..53e39c9c --- /dev/null +++ b/Specifications/desktopcouch/Documentation/Troubleshooting.mdwn @@ -0,0 +1,40 @@ +# Desktop Couch Troubleshooting + +If desktopcouch seems to not be working for some reason, here are some things you can try. + + +## When I open the couchdb.html bookmark file I get "Unable to connect" + +This normally means that desktopcouch didn't properly write the bookmark file last time it started up. Try killing and restarting desktopcouch, below. + + +## My data is being stored in desktopcouch but it's not replicating to other desktopcouches or Ubuntu One + +If data isn't syncing to other CouchDBs properly, so (for example) your Evolution contacts are stored in desktopcouch but are not appearing in the Ubuntu One web interface, check the replication log. This is a logfile listing the output from replication, and is at `~/.cache/desktop-couch/log/desktop-couch-replication.log`. This log may give you some clues as to what's going wrong. Ask on irc.freenode.net `#ubuntuone` if the log makes no sense. + +Verify that you have Avahi running: **[[#506601|https://bugs.launchpad.net/bugs/506601]]** Pairing and replication does not work if Avahi is down. + +Verify that desktopcouch is properly started. The correct way of desktopcouch startup is via desktopcouch-service (or DBus autolaunch e.g. on getPort()). desktopcouch.records module is able to start couchdb if it is not running, but it does not start related services: **[[#519028|https://bugs.launchpad.net/bugs/519028]]** Desktopcouch replication and org.desktopcouch.CouchDB.service are NOT started on desktopcouch.records calls. + + +## Killing and restarting desktopcouch + +To re-start desktopcouch from scratch, do the following, in a terminal window: + +1. `killall beam.smp` - this will kill any existing desktopcouch processes. (Note: **do not** do this with `sudo`!) If this says `beam.smp: no process found`, then do `killall beam` instead. +1. `rm ~/.config/desktop-couch/desktop-couchdb.ini` - this will remove the desktopcouch configuration file, which will then be re-generated. (This will _not_ lose any data stored in desktopcouch, do not worry.) +1. `dbus-send --session --dest=org.desktopcouch.CouchDB --print-reply --type=method_call / org.desktopcouch.CouchDB.getPort` - this should restart desktopcouch. You can ignore messages printed by this command +1. `xdg-open file:///home/YOURUSERNAME/.local/share/desktop-couch/couchdb.html` - open the bookmark file, which should then correctly take you to your desktopcouch web interface + +## Can't open CouchDB addressbook from Evolution contacts + +This usually means that desktopcouch is not running, but it might be due to other causes, so to troubleshoot it, please run, on a terminal: + + $ evolution --force-shutdown + $ /usr/lib/evolution/evolution-data-server-2.28 # note that this path might be different depending on your distro/version + # so make sure you check where the evolution-data-server binary is on your + # system if this doesn't work + +Then, start Evolution again and try to open again the CouchDB addressbook. If it fails, have a look at the output on the terminal, it should have some hints as to why it failed. If you don't understand it, please copy all the output and [[file a bug here|https://bugs.edge.launchpad.net/evolution-couchdb/+filebug]], making sure you paste the output from the terminal to the bug report. + +There is a command line application written by aquarius to manage your couchdb instance located on Ubuntu One servers: [[ubuntuone-couchdb-query2|ubuntuone-couchdb-query2]] diff --git a/Specifications/desktopcouch/Documentation/Troubleshooting/ubuntuone-couchdb-query b/Specifications/desktopcouch/Documentation/Troubleshooting/ubuntuone-couchdb-query new file mode 100644 index 00000000..89688b97 --- /dev/null +++ b/Specifications/desktopcouch/Documentation/Troubleshooting/ubuntuone-couchdb-query @@ -0,0 +1,141 @@ +#!/usr/bin/python +"""ubuntuone-couchdb-query: Command line query tool for Ubuntu One CouchDBs""" + +# sil@kryogenix.org, 2010-02-13 + +from optparse import OptionParser +from oauth import oauth +import gnomekeyring, gobject, httplib2, simplejson, urlparse, cgi, urllib + +def get_prod_oauth_token(): + """Get the token from the keyring""" + gobject.set_application_name("Ubuntu One Web API Tool") + + consumer = oauth.OAuthConsumer("ubuntuone", "hammertime") + items = [] + items = gnomekeyring.find_items_sync( + gnomekeyring.ITEM_GENERIC_SECRET, + {'ubuntuone-realm': "https://ubuntuone.com", + 'oauth-consumer-key': consumer.key}) + return oauth.OAuthToken.from_string(items[0].secret) + +def get_oauth_request_header(consumer, access_token, http_url): + """Get an oauth request header given the token and the url""" + signature_method = oauth.OAuthSignatureMethod_PLAINTEXT() + assert http_url.startswith("https") + oauth_request = oauth.OAuthRequest.from_consumer_and_token( + http_url=http_url, + http_method="GET", + oauth_consumer=consumer, + token=access_token) + oauth_request.sign_request(signature_method, consumer, access_token) + return oauth_request.to_header() + +def request(urlpath, sigmeth, http_method, request_body, show_tokens): + """Make a request to couchdb.one.ubuntu.com for the user's data. + + The user supplies a urlpath (for example, dbname). We need to actually + request https://couchdb.one.ubuntu.com/PREFIX/dbname, and sign it with + the user's OAuth token, which must be in the keyring. + + We find the prefix by querying https://one.ubuntu.com/api/account/ + (see desktopcouch.replication_services.ubuntuone, which does this). + """ + + # First check that there's a token in the keyring. + try: + access_token = get_prod_oauth_token() + except: # bare except, norty + raise Exception("Unable to retrieve your Ubuntu One access details " + "from the keyring. Try connecting your machine to Ubuntu One.") + + # Set the signature method. This should be HMAC unless you have a jolly + # good reason for it to not be. + if sigmeth == "PLAINTEXT": + signature_method = oauth.OAuthSignatureMethod_PLAINTEXT() + elif sigmeth == "HMAC_SHA1": + signature_method = oauth.OAuthSignatureMethod_HMAC_SHA1() + else: + signature_method = oauth.OAuthSignatureMethod_PLAINTEXT() + + # Create the Ubuntu One OAuth consumer for all requests + consumer = oauth.OAuthConsumer("ubuntuone", "hammertime") + + if show_tokens: + print "Using OAuth data:" + print "consumer: %s : %s\ntoken: %s" % ( + consumer.key, consumer.secret, access_token) + + # Look up the user's prefix + infourl = "https://one.ubuntu.com/api/account/" + oauth_header = get_oauth_request_header(consumer, access_token, infourl) + client = httplib2.Http() + resp, content = client.request(infourl, "GET", headers=oauth_header) + if resp['status'] == "200": + document = simplejson.loads(content) + if "couchdb_root" not in document: + raise ValueError("couchdb_root not found in %s" % (document,)) + COUCH_ROOT = document["couchdb_root"] + else: + raise ValueError("Error retrieving user data (%s)" % (resp['status'], + url)) + + # COUCH_ROOT must have all internal slashes escaped + schema, netloc, path, params, query, fragment = urlparse.urlparse(COUCH_ROOT) + path = "/" + urllib.quote(path[1:], safe="") # don't escape the first / + COUCH_ROOT = urlparse.urlunparse((schema, netloc, path, params, query, fragment)) + + # Now use COUCH_ROOT and the specified user urlpath to get data + couch_url = "%s%%2f%s" % (COUCH_ROOT, urlpath) + schema, netloc, path, params, query, fragment = urlparse.urlparse(couch_url) + querystr_as_dict = dict(cgi.parse_qsl(query)) + oauth_request = oauth.OAuthRequest.from_consumer_and_token( + http_url=couch_url, + http_method=http_method, + oauth_consumer=consumer, + token=access_token, + parameters=querystr_as_dict) + oauth_request.sign_request(signature_method, consumer, access_token) + resp, content = client.request(couch_url, http_method, + headers=oauth_request.to_header(), body=request_body) + if resp['status'] == "200": + try: + return simplejson.loads(content) + except: + print "(data returned from CouchDB was invalid JSON)" + return content + elif resp['status'] == "400": + print "The server could not parse the oauth token:\n%s" % content + elif resp['status'] == "401": + print "Access Denied" + print "Content:" + return content + else: + return ( + "There was a problem processing the request:\nstatus:%s, response:" + " %r" % (resp['status'], content)) + + +if __name__ == "__main__": + parser = OptionParser(usage="prog [options] urlpath") + parser.add_option("--oauth-signature-method", dest="sigmeth", + default="HMAC_SHA1", + help="OAuth signature method to use (PLAINTEXT or " + "HMAC_SHA1)") + parser.add_option("--http-method", dest="http_method", + default="GET", + help="HTTP method to use") + parser.add_option("--body", dest="body", + default=None, + help="HTTP request body") + parser.add_option("--show-tokens", dest="show_tokens", + default=False, + help="Show the OAuth tokens we're using") + + (options, args) = parser.parse_args() + if len(args) != 1: + parser.error("You must specify a urlpath (e.g., a dbname)") + print request( + urlpath=args[0], sigmeth=options.sigmeth, + http_method=options.http_method, request_body=options.body, + show_tokens=options.show_tokens) diff --git a/Specifications/desktopcouch/Documentation/Troubleshooting/ubuntuone-couchdb-query2 b/Specifications/desktopcouch/Documentation/Troubleshooting/ubuntuone-couchdb-query2 new file mode 100644 index 00000000..3070a757 --- /dev/null +++ b/Specifications/desktopcouch/Documentation/Troubleshooting/ubuntuone-couchdb-query2 @@ -0,0 +1,160 @@ +#!/usr/bin/python +"""ubuntuone-couchdb-query: Command line query tool for Ubuntu One CouchDBs""" + +# sil@kryogenix.org, 2010-02-13 + +from optparse import OptionParser +from oauth import oauth +import gnomekeyring, gobject, httplib2, simplejson, urlparse, cgi, urllib +import socket +socket.setdefaulttimeout(5) + +def get_prod_oauth_token(): + """Get the token from the keyring""" + gobject.set_application_name("Ubuntu One Web API Tool") + + consumer = oauth.OAuthConsumer("ubuntuone", "hammertime") + items = [] + items = gnomekeyring.find_items_sync( + gnomekeyring.ITEM_GENERIC_SECRET, + {'ubuntuone-realm': "https://ubuntuone.com", + 'oauth-consumer-key': consumer.key}) + return oauth.OAuthToken.from_string(items[0].secret) + +def get_oauth_request_header(consumer, access_token, http_url, signature_method): + """Get an oauth request header given the token and the url""" + assert http_url.startswith("https") + oauth_request = oauth.OAuthRequest.from_consumer_and_token( + http_url=http_url, + http_method="GET", + oauth_consumer=consumer, + token=access_token) + oauth_request.sign_request(signature_method, consumer, access_token) + return oauth_request.to_header() + +def request(urlpath, sigmeth, http_method, request_body, show_tokens): + """Make a request to couchdb.one.ubuntu.com for the user's data. + + The user supplies a urlpath (for example, dbname). We need to actually + request https://couchdb.one.ubuntu.com/PREFIX/dbname, and sign it with + the user's OAuth token, which must be in the keyring. + + We find the prefix by querying https://one.ubuntu.com/api/account/ + (see desktopcouch.replication_services.ubuntuone, which does this). + """ + + # First check that there's a token in the keyring. + try: + access_token = get_prod_oauth_token() + except: # bare except, norty + raise Exception("Unable to retrieve your Ubuntu One access details " + "from the keyring. Try connecting your machine to Ubuntu One.") + + # Set the signature method. This should be HMAC unless you have a jolly + # good reason for it to not be. + if sigmeth == "PLAINTEXT": + signature_method = oauth.OAuthSignatureMethod_PLAINTEXT() + elif sigmeth == "HMAC_SHA1": + signature_method = oauth.OAuthSignatureMethod_HMAC_SHA1() + else: + signature_method = oauth.OAuthSignatureMethod_PLAINTEXT() + + # Create the Ubuntu One OAuth consumer for all requests + consumer = oauth.OAuthConsumer("ubuntuone", "hammertime") + + if show_tokens: + print "Using OAuth data:" + print "consumer: %s : %s\ntoken: %s" % ( + consumer.key, consumer.secret, access_token) + + # Look up the user's prefix + infourl = "https://one.ubuntu.com/api/account/" + oauth_header = get_oauth_request_header(consumer, access_token, infourl, signature_method) + client = httplib2.Http() + resp, content = client.request(infourl, "GET", headers=oauth_header) + if resp['status'] == "200": + try: + document = simplejson.loads(content) + except ValueError: + raise Exception("Got unexpected content:\n%s" % content) + if "couchdb_root" not in document: + raise ValueError("couchdb_root not found in %s" % (document,)) + COUCH_ROOT = document["couchdb_root"] + else: + raise ValueError("Error retrieving user data (%s)" % (resp['status'], + url)) + + # COUCH_ROOT must have all internal slashes escaped + schema, netloc, path, params, query, fragment = urlparse.urlparse(COUCH_ROOT) + path = "/" + urllib.quote(path[1:], safe="") # don't escape the first / + COUCH_ROOT = urlparse.urlunparse((schema, netloc, path, params, query, fragment)) + + # Now use COUCH_ROOT and the specified user urlpath to get data + if urlpath == "_all_dbs": + couch_url = "%s%s" % (COUCH_ROOT, urlpath) + else: + couch_url = "%s%%2F%s" % (COUCH_ROOT, urlpath) + schema, netloc, path, params, query, fragment = urlparse.urlparse(couch_url) + querystr_as_dict = dict(cgi.parse_qsl(query)) + oauth_request = oauth.OAuthRequest.from_consumer_and_token( + http_url=couch_url, + http_method=http_method, + oauth_consumer=consumer, + token=access_token, + parameters=querystr_as_dict) + oauth_request.sign_request(signature_method, consumer, access_token) + failed = 0 + while 1: + try: + resp, content = client.request(couch_url, http_method, + headers=oauth_request.to_header(), body=request_body) + break + except IOError: + failed += 1 + if failed > 0: + if failed == 1: + s = "" + else: + s = "s" + print "(request failed %s time%s)" % (failed, s) + if resp['status'] == "200": + try: + return simplejson.loads(content) + except: + print "(data returned from CouchDB was invalid JSON)" + return content + elif resp['status'] == "400": + print "The server could not parse the oauth token:\n%s" % content + elif resp['status'] == "401": + print "Access Denied" + print "Content:" + return content + else: + return ( + "There was a problem processing the request:\nstatus:%s, response:" + " %r" % (resp['status'], content)) + + +if __name__ == "__main__": + parser = OptionParser(usage="prog [options] urlpath") + parser.add_option("--oauth-signature-method", dest="sigmeth", + default="HMAC_SHA1", + help="OAuth signature method to use (PLAINTEXT or " + "HMAC_SHA1)") + parser.add_option("--http-method", dest="http_method", + default="GET", + help="HTTP method to use") + parser.add_option("--body", dest="body", + default=None, + help="HTTP request body") + parser.add_option("--show-tokens", dest="show_tokens", + default=False, + help="Show the OAuth tokens we're using") + + (options, args) = parser.parse_args() + if len(args) != 1: + parser.error("You must specify a urlpath (e.g., a dbname)") + print request( + urlpath=args[0], sigmeth=options.sigmeth, + http_method=options.http_method, request_body=options.body, + show_tokens=options.show_tokens) diff --git a/Specifications/desktopcouch/Documentation/ViewingMyData.mdwn b/Specifications/desktopcouch/Documentation/ViewingMyData.mdwn new file mode 100644 index 00000000..96230ebd --- /dev/null +++ b/Specifications/desktopcouch/Documentation/ViewingMyData.mdwn @@ -0,0 +1,9 @@ + + +# Viewing my data in desktopcouch + +You can see all your desktopcouch databases in the "Futon" web interface by running this command from a terminal window (Applications > Accessories > Terminal): + +`xdg-open ~/.local/share/desktop-couch/couchdb.html` + +If this command doesn't work (for example, you are asked for a password) then restart desktopcouch as described on the [[Troubleshooting|Specifications/desktopcouch/Documentation/Troubleshooting]] page. diff --git a/Specifications/desktopcouch/bookmark.mdwn b/Specifications/desktopcouch/bookmark.mdwn new file mode 100644 index 00000000..d27f5a91 --- /dev/null +++ b/Specifications/desktopcouch/bookmark.mdwn @@ -0,0 +1,11 @@ + +The schema for bookmark storage in Desktop Couch. Used by [[Bindwood|http://launchpad.net/bindwood]] for Firefox and others. + + { + "record_type":"http://www.freedesktop.org/wiki/Specifications/desktopcouch/bookmark", + "uri":"<uri of bookmark>", + "title":"<title of bookmark>", + "application_annotations":{ + ...stuff specific to applications, nobody should rely on these.. + } + } diff --git a/Specifications/desktopcouch/contact.mdwn b/Specifications/desktopcouch/contact.mdwn new file mode 100644 index 00000000..70f2ca92 --- /dev/null +++ b/Specifications/desktopcouch/contact.mdwn @@ -0,0 +1,75 @@ +The schema for contacts records, used by Evolution and Akonadi + + +## Main Document + + { + "_id": string - unique ID of this document, # internal to CouchDB + "_rev": string - revision_for_this_document, #internal to CouchDB + "record_type": "http://www.freedesktop.org/wiki/Specifications/desktopcouch/contact", + "first_name": string - First name of the contact, + "middle_name": string - Middle name of the contact, + "last_name": string - Last name of the contact, + "title": string - Title of the contact, + "suffix": string - Suffix of the contact, + "birth_date": string - Birth date in YYYY-MM-DD format, + "nick_name": string - Nick name, + "spouse_name": string - Spouse name, + "wedding_date": string - Wedding/Anniversary date in YYYY-MM-DD format, + "company": string - Company name, + "department": string - Department name, + "job_title": string - Job title, + "manager_name": string - Manager name, + "assistant_name": string - Assistant name, + "office": string - Office name, + "notes": string - Notes, + "addresses": mergeable list of { + { + "city": string - City name, + "description": string - "work", "home" or "other", + "address1": string - Street name, + "address2": string - Address extension, + "state": string - State / Region name, + "country": string - Country name, + "postalcode": string - Postal code + } + }, + "phone_numbers": mergeable list of { + { + "description": string - "home", "mobile", "home fax", "work", "car", "pager", "work fax", "assistant", "callback", "company", "other", "other fax", "primary", or "telex" + "number": string - Phone number + } + }, + "email_addresses": mergeable list of { + { + "description": string - "work", "home" or "other" + "address": string - Email address + } + }, + "urls": mergeable list of { + { + "description": string - "blog" or "home page" + "address": string - URL + } + }, + "im_addresses": mergeable list of { + { + "address": string - IM user ID + "description": string - Description + "protocol": string - Protocol (aim|gadu-gadu|groupwise|icq|irc|jabber|msn|skype|yahoo) + } + }, + "application_annotations": { + "application_name": { ... } + ...stuff specific to applications, nobody should rely on these... + }, + } + +## Attachments + +* photo: The contact photo. Maximum size 100k. MIME type image/* + +## Explanation + +* Mergeable lists are lists of JSON objects, each of which has a unique identifier +* Dates should be represented in YYYY-MM-DD format diff --git a/Specifications/desktopcouch/note.mdwn b/Specifications/desktopcouch/note.mdwn new file mode 100644 index 00000000..20d443cd --- /dev/null +++ b/Specifications/desktopcouch/note.mdwn @@ -0,0 +1,20 @@ +# Notes + +Note record format, used by [[Tomboy|http://projects.gnome.org/tomboy/]] + + { + "_id": "id_of_this_document", # internal to CouchDB + "_rev": "revision_for_this_document", #internal to CouchDB + "record_type": "http://www.freedesktop.org/wiki/Specifications/desktopcouch/note", + "record_type_version": "1.0", + "title": "<note's title>", + "content": "<note content>", # in HTML/XML format, whatever is specified in the note_format field + "note_format": string, either "xml" or "html" to identify the format the note's content is in + "last_change_date": "<last modification date, in UTC>", + "create_date": "<creation date in UTC>", + "application_annotations": { + "Tomboy": { + ...stuff specific to applications, nobody should rely on these... + } + } + } diff --git a/Specifications/desktopcouch/task.mdwn b/Specifications/desktopcouch/task.mdwn new file mode 100644 index 00000000..60239cfe --- /dev/null +++ b/Specifications/desktopcouch/task.mdwn @@ -0,0 +1,10 @@ +# Tasks + +Task record format, used by [[Evolution|http://projects.gnome.org/evolution/]] + + { + "_id": string - Unique ID for this document # internal to CouchDB + "_rev": string - Revision for this document #internal to CouchDB + "record_type": "http://www.freedesktop.org/wiki/Specifications/desktopcouch/task", + "summary": string - Summary for the task + } diff --git a/Specifications/direct-save.mdwn b/Specifications/direct-save.mdwn new file mode 100644 index 00000000..c40e7de3 --- /dev/null +++ b/Specifications/direct-save.mdwn @@ -0,0 +1,29 @@ + + +### Overview + +The Direct Save Protocol (XDS) builds on top of the [[XDND|Specifications/XDND]] protocol to allow users to save a file by simply dragging it to a file manager window, thereby avoiding the necessity of having a directory browser in each application's Save File dialog. + + +### Mailinglist + +Discussion of this specification should occur on [[xdg|http://www.freedesktop.org/mailman/listinfo/xdg]]. + + +### Current status + +The specification is now stable and not expected to change in incompatible ways. The last change was in 1999. All the ROX applications and those using the JX framework have supported XDS since 1999. + + +### Full specification + + * [[http://www.newplanetsoftware.com/xds/|http://www.newplanetsoftware.com/xds/]] + * [[local copy|Specifications/XDS]] + +### Current implementors + + * [[The Gimp|http://gimp.org]]: The Gimp [[has support in the CVS version|http://article.gmane.org/gmane.comp.video.gimp.user/6831]]. [[ROX-Lib|http://rox.sourceforge.net/phpwiki/index.php/ROX-Lib]]: Provides a Python module to save using the protocol. [[ROX-Filer|http://rox.sourceforge.net/phpwiki/index.php/ROX-Filer]]: Graphical file manager allows dragging to filer windows to save. [[JX Application Framework|http://www.newplanetsoftware.com/jx/]]: C++ widget library. [[Thunar|http://thunar.xfce.org/]]: Xfce File Manager allows dragging to folder windows to save. + +### Links to other specifications + + * [[XDND|http://www.newplanetsoftware.com/xdnd/]] is the drag-and-drop specification shared between GTK+ and Qt. XDS builds on this.
\ No newline at end of file diff --git a/Specifications/file-manager-interface.mdwn b/Specifications/file-manager-interface.mdwn new file mode 100644 index 00000000..42b6fc7a --- /dev/null +++ b/Specifications/file-manager-interface.mdwn @@ -0,0 +1,43 @@ +# File Manager DBus Interface + +Applications sometimes need to interact with the desktop's file manager. This page documents a simple DBus interface that can be used for that purpose. + + <interface name='org.freedesktop.FileManager1'> + <method name='ShowFolders'> + <arg type='as' name='URIs' direction='in'/> + <arg type='s' name='StartupId' direction='in'/> + </method> + <method name='ShowItems'> + <arg type='as' name='URIs' direction='in'/> + <arg type='s' name='StartupId' direction='in'/> + </method> + <method name='ShowItemProperties'> + <arg type='as' name='URIs' direction='in'/> + <arg type='s' name='StartupId' direction='in'/> + </method> + </interface> + +These three methods take an array of URI strings, and a startup id as specified by the startup notification specification. + +[[ShowFolders]] assumes that the specified URIs are folders; the file manager is supposed to show a window with the contents of each folder. Calling this method with `file:///etc` as the single element in the array of URIs will cause the file manager to show the contents of /etc as if the user had navigated to it. The behavior for more than one element is left up to the implementation; commonly, multiple windows will be shown, one for each folder. + +[[ShowItems]] doesn't make any assumptions as to the type of the URIs. The file manager is supposed to select the passed items within their respective parent folders. Calling this method on `file:///etc` as the single element in the array of URIs will cause the file manager to show a file listing for "/", with "etc" highlighted. The behavior for more than one element is left up to the implementation. + +[[ShowItemProperties]] should cause the file manager to show a "properties" window for the specified URIs. For local Unix files, these properties can be the file permissions, icon used for the files, and other metadata. + + +# Activation + +Applications are supposed to use the `org.freedesktop.FileManager1` DBus name and the `/org/freedesktop/FileManager1` object path. The interface name is `org.freedesktop.FileManager1`. + + +# Implementations + +This interface is implmented in the following environments: + +* Nautilus 3.4 and later. + +# References + +* [[Discussion in xdg-list|http://lists.freedesktop.org/archives/xdg/2011-May/011949.html]] +* [[Gnome bugzilla entry for Nautilus's implementation|https://bugzilla.gnome.org/show_bug.cgi?id=636269]] diff --git a/Specifications/file-uri-spec.mdwn b/Specifications/file-uri-spec.mdwn new file mode 100644 index 00000000..6af9dab9 --- /dev/null +++ b/Specifications/file-uri-spec.mdwn @@ -0,0 +1,15 @@ + + +## File URI Specification + +This document specifies how URIs for normal UNIX filenames (file: URIs) are interpreted and created. Its vital that all desktops/application use file URIs in the same way, or applications will be unable to interchange files when using things like drag and drop or passing filenames as URI arguments (as used in desktop files). + + +### Mailinglist + +Discussion of this specification should occur on [[xdg|http:/mailman/listinfo/xdg]]. + + +### Spec + + * Version 1.0: [[file-uri-spec.txt|http://equinox-project.org/spec/file-uri-spec.txt]] diff --git a/Specifications/free-media-player-specs.mdwn b/Specifications/free-media-player-specs.mdwn new file mode 100644 index 00000000..a5d440c4 --- /dev/null +++ b/Specifications/free-media-player-specs.mdwn @@ -0,0 +1,20 @@ + + +## Free Media Player Specifications + +These specifications are designed to provide standard and complete ways to perform common tasks with media (especially music) metadata that may otherwise be very difficult. They aim to be as simple as possible while still being robust and useful, and to be consistent across metadata formats. + + +### Mailinglist + +Discussion of this specification should occur on the [[xdg mailing list|http://lists.freedesktop.org/mailman/listinfo/xdg]]. Some historical discussion can be found on [[the FMPS Google Group|http://groups.google.com/group/fmps]] (some new content is also copied there from the XDG maailing list). + + +### Git + +The [[Git|Infrastructure/git]] location of this specification is currently at [[http://gitorious.org/xdg-specs/xdg-specs/trees/master/specifications/FMPSpecs|http://gitorious.org/xdg-specs/xdg-specs/trees/master/specifications/FMPSpecs]]. + + +### Spec + + * Latest version (1.0) - [[txt (one page)|http://gitorious.org/xdg-specs/xdg-specs/blobs/master/specifications/FMPSpecs/specification.txt]] - [[xml|http://gitorious.org/xdg-specs/xdg-specs/blobs/raw/master/specifications/FMPSpecs/specification.xml]]
\ No newline at end of file diff --git a/Specifications/help-spec.mdwn b/Specifications/help-spec.mdwn new file mode 100644 index 00000000..89e18697 --- /dev/null +++ b/Specifications/help-spec.mdwn @@ -0,0 +1,20 @@ + + +# Help Specification + +[[http://freedesktop.org/wiki/Specifications|http://freedesktop.org/wiki/Specifications]] + + +## About + +This specification provides a common directory layout and URI scheme for locally installed help documents. Documents installed and referenced using this system will have better interoperability between different desktop environments and help applications. + + +## Mailing list + +Discussion of this specification should occur on [[xdg|http://freedesktop.org/mailman/listinfo/xdg]]. + + +## Specification + +[[help-system-spec.xml|help-system-spec.xml]] diff --git a/Specifications/help-spec/help-system-spec.xml b/Specifications/help-spec/help-system-spec.xml new file mode 100644 index 00000000..ffe1a5d4 --- /dev/null +++ b/Specifications/help-spec/help-system-spec.xml @@ -0,0 +1,195 @@ +<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" +"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [ +]> +<article id="index"> + <title>Help System Specification</title> + + <articleinfo> + <title>Help System Specification</title> + <date>2010-04-30</date> + <authorgroup> + <author> + <firstname>Shaun</firstname> + <surname>McCance</surname> + <affiliation> + <address> + <email>shaunm@gnome.org</email> + </address> + </affiliation> + </author> + </authorgroup> + </articleinfo> + + <section id="overview"> + <title>Overview</title> + <para>This specification provides a common directory layout and URI + scheme for locally installed help documents. Documents installed and + referenced using this system will have better interoperability between + different desktop environments and help applications.</para> + </section> + + <section id="layout"> + <title>Directory Layout</title> + + <para>A document is a collection of files, possibly from multiple + directories in a path. Documents may be in any format, or even in + multiple formats; see <xref linkend="formats"/> for details. A + document has a <emphasis>document identifier</emphasis> that + identifies it uniquely and specifies where it can be found on + the file system. A document identifier consists of one or more + characters from the following: digits (U+0030-U+0039), letters + (U+0041-U+005A and U+0061-U+007A), hyphen (U+002D), underscore + (U+005F), period (U+002E), and percent (U+0025).</para> + + <para>Document identifiers are not explicitly namespaced. To + avoid conflicts, document identifiers should start with the name + of the application or package that provides the document. In many + cases, the name of the application or package alone may be used. + Otherwise, the document identifier should start with the name + of the package or application followed by a hyphen.</para> + + <para>Documents are installed under the <filename>help</filename> + subdirectory in <envar>$XDG_DATA_HOME</envar> or in the + <envar>$XDG_DATA_DIRS</envar> path. See the + <ulink url="http://standards.freedesktop.org/basedir-spec/latest/">XDG + Base Directory Specification</ulink> for details on <envar>$XDG_DATA_HOME</envar> + and <envar>$XDG_DATA_DIRS</envar>. Each <filename>help</filename> + directory in the path contains subdirectories for languages. Each + language subdirectory contains subdirectories for documents, where + the name of each subdirectory matches the document identifier of + a document.</para> + + <para>The <emphasis>document path</emphasis> for a given document + is the list of directories of the following form:</para> + + <programlisting><replaceable>datadir</replaceable>/help/<replaceable>lang</replaceable>/<replaceable>document</replaceable></programlisting> + + <variablelist> + <varlistentry> + <term><filename><replaceable>datadir</replaceable></filename></term> + <listitem><para>Either <envar>$XDG_DATA_HOME</envar> or a directory in + the <envar>$XDG_DATA_DIRS</envar> path.</para></listitem> + </varlistentry> + <varlistentry> + <term><filename><replaceable>lang</replaceable></filename></term> + <listitem><para>The language code of a language in the user's + list of preferred languages.</para></listitem> + </varlistentry> + <varlistentry> + <term><filename><replaceable>document</replaceable></filename></term> + <listitem><para>The document identifier of the document.</para></listitem> + </varlistentry> + </variablelist> + + <para>The document path is ordered first according to the position of + <filename><replaceable>datadir</replaceable></filename> in the path, then + by the position of <filename><replaceable>lang</replaceable></filename> + in the user's preferred list of languages. So, for example, if the + user's preferred language list is <systemitem>pt_BT:pt:C</systemitem>, + then <filename>~/.local/share/help/pt/beanstalk</filename> would take + precedence over <filename>/usr/share/help/pt_BR/beanstalk</filename>.</para> + </section> + + <section id="uri-scheme"> + <title>URI Scheme</title> + + <para>Documents are referenced using the <systemitem>help:</systemitem> + URI scheme. The <systemitem>help:</systemitem> URI scheme has the + following form:</para> + + <programlisting>help:<replaceable>document</replaceable>/<replaceable>page</replaceable>?<replaceable>options</replaceable>#<replaceable>anchor</replaceable></programlisting> + + <variablelist> + <varlistentry> + <term><replaceable>document</replaceable></term> + <listitem><para>The document identifier.</para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>page</replaceable></term> + <listitem><para>An identifier for a page within the document. Documents + often consist of multiple logical pages, which may not be reflected in + the actual files on the system. The page identifier is optional. If it + is not present, the preceding <systemitem>/</systemitem> character + should be omitted.</para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>options</replaceable></term> + <listitem><para>Additional options that can influence how applications + present a document. Options are optional. If they are not present, the + preceding <systemitem>?</systemitem> character should be omitted. If + they are present, they must conform to the + <systemitem>application/x-www-form-urlencoded</systemitem> MIME type. + Options may be used, for example, to override language settings or to + provide keys for conditional processing. This specification makes no + specific recommendations for the options.</para></listitem> + </varlistentry> + <varlistentry> + <term><replaceable>anchor</replaceable></term> + <listitem><para>An anchor point within a page. Applications should + scroll to an appropriate point whenever possible. The anchor is + optional. If it is not present, the preceding <systemitem>#</systemitem> + character should be omitted.</para></listitem> + </varlistentry> + </variablelist> + + <para>Page identifiers and anchors may contain any character that is + valid in a document identifier. Some document types may have further + restrictions on page identifiers or anchors.</para> + </section> + + <section id="formats"> + <title>Help Formats</title> + + <para>Documents may be installed in any format. Not all help applications + may recognize and handle the same types of documents. Whenever possible, + help applications should support HTML. Documents may be installed in + multiple formats. Help applications choose which format to use when + multiple formats are present.</para> + + <para>For any format, a help application must map the information found + in the <systemitem>help:</systemitem> URI scheme to the information in + that format. This specification contains recommendations for finding + and handling documents in DocBook, Mallard, HTML, and XHTML.</para> + + <section id="docbook"> + <title>DocBook</title> + <para>DocBook documents have a file named <filename>index.docbook</filename> + in the document path. Any files referenced from the DocBook file, including + XML fragments included through XInclude, should be looked up according to + the document path.</para> + <para>When a help application displays a DocBook document, it will often + display it in multiple pages or chunks, rather than as a single long page. + The page identifier specifies which chunk to display. Not all applications + will split a DocBook document into chunks in the same way, so the page + identifier may not map exactly to the <sgmltag>id</sgmltag> attribute + of an element that is chunked. In this case, the applicaiton displays + the nearest enclosing chunk and treats the page identifier as an anchor + if no anchor was explicitly provided.</para> + </section> + + <section id="mallard"> + <title>Mallard</title> + <para>Mallard documents have a file named <filename>index.page</filename> + in the document path. Other page files may be different directories in + the document path. Any files referenced in any page file, including XML + fragments included through XInclude, should be looked up according to + the document path.</para> + <para>The page identifier specifies the id of a Mallard page file. The + anchor specifies the id of a section within a Mallard page file.</para> + </section> + + <section id="html"> + <title>HTML and XHTML</title> + <para>HTML documents have a file named <filename>index.html</filename> + in the document path. XHTML documents have a file named <filename>index.xhtml</filename> + in the document path. Other HTML or XHTML files in the document may + be in different directories in the document path. Any files referenced + in any HTML or XHTML page, including XML fragments included through + XInclude in XHTML, should be looked up according to the document path.</para> + <para>The page identifier specifies the base file name, without the + <filename>.html</filename> or <filename>.xhtml</filename> extension, + of an HTML or XHTML file in the document. The anchor specifies a named + anchor within the HTML or XHTML file.</para> + </section> + </section> +</article> diff --git a/Specifications/help-system.mdwn b/Specifications/help-system.mdwn new file mode 100644 index 00000000..da6e431d --- /dev/null +++ b/Specifications/help-system.mdwn @@ -0,0 +1,111 @@ + + +# Help System + + +## Discussion + +If you have ideas you want to suggest but don't want to edit this main document, please go to the [[Discussion Page|Specifications/help-system/Discussion]]. + + +## GUADEC Discussion + +Using .desktop files for documentation metatdata, standard location using XDG base directory spec. Search XDG dirs for .desktop files for language subdirectories. $XDG_DATA_DIRS/help/$path/$lang/... Desktop entry basename as ID. Included directories have same structure. + +Use category codes together with the XDG menu specification to categorize application help files. + +We need to extend the .desktop specification for inclues. + +Persons at the meeting (add your nick here, if you're not listed): + +* shaunm +* jpr +* danilo +* cornelius +* physaro +* acuster +* romanofski +* damiend + +## clahey's suggested standard + + +### Locating a given help file + +There are a few sections to this standard. The first is a method for finding a file on the file system given a help uri. + +The list of languages to search for is decided by the environment. Help browsers MUST set a list of languages. Help browsers SHOULD set the list of languages as locale, locale truncated to 2 characters, en_US, en. If the environment has a list of multiple preferred languages, help browsers MAY use that list, with en appended to the end, or some similar scheme. + +Help browsers SHOULD support the "man:" and "info:" URIs (these URI schemes are not registered by the IETF): * "man:" URIs have the form "man:command-name", "man:command-name(section)", or "man:command-name#section". This refers to reference pages in "man" format. The command name can optionally be followed by a parenthesis and section number; see man(7) for more information on the meaning of the section numbers. An example is "man:ls(1)". * "info:" URIs have the form "info:virtual-filename", "info:virtual-filename#nodename", "info:(virtual-filename)", or "info:(virtual-filename)nodename". This scheme refers to online info reference pages (generated from texinfo files), a documentation format used by programs such as the GNU tools. The first two formats are the GNOME format; in nodenames all spaces are written as underscores. The second two formats are the KDE format; spaces in nodenames must be written as %20 (URI escaped). If the form without the nodename is used the nodename is "Top". Examples are "info:gcc", "info:gcc#G++_and_GCC>, "info:(gcc)", and "info:(gcc)G++ and GCC". + +See url(7) at [[http://www.die.net/doc/linux/man/man7/url.7.html|http://www.die.net/doc/linux/man/man7/url.7.html]] for more information about URIs for man pages and info pages. + +Given a uri starting with help:, we take everything after the : and before the # and call it the $path. Now we search for the file. In language order, we search for $XDG_DATA_DIRS/help/$lang/$path/$filename. Search $XDG_DATA_DIRS for each language in turn. I.e., assuming standard $XDG_DATA_DIRS and a non en locale, /usr/share/help/$locale/$path/$filename takes precedence over $HOME/.share/help/en/$path/$filename. + +If we find the file, we look at the type: * If it's html, the # refers to a standard html lookup. * If it's docbook, the # refers to the blockid and the help browser needs to display that blockid. If the help browser displays the docbook file as multiple pages, it MUST display the page containing the given blockid and SHOULD scroll to the given block. * If it's a man page, the # refers to the section name; it SHOULD scroll to the given section. * If it's an info page, the # refers to the node name. + +If the type is a folder, we then look for an index file. First we check for index.html, then for index.docbook and then treat them as above if found. + +If the file is found but can not be handled by the help browser (unknown type or directory with no index,) the help browser MAY continue searching the $XDG_DATA_DIRS with the different languages in the order specified above. + + +### Indexing help files + +The help browser SHOULD display a table of contents. The contents are described by the menu spec. The root is help.menu. This file SHOULD include a link to the main applications.menu file. + +This spec adds two new tags to .desktop files. The first is [[DocPath|DocPath]]. This is the uri for the help to display. If this uri is a directory, the table of contents SHOULD check the contents and include the contents of the help file in the TOC if appropriate. This expansion will be described later. + +The second is [[DocDir|DocDir]]. This is a path to a directory of .desktop files. The contents are displayed as children of the element in the TOC. This is to be used if an app has more than one doc. This way a single entry in the launch menus can correspond to a directory of documentation. + +This can also be used for apps that are internally extensible. Any extensions to the app can add help files to the given [[DocDir|DocDir]]. + +Each file in the [[DocDir|DocDir]] SHOULD be checked for including the contents of the help file in the TOC if appropriate. This expansion will be described later. + +[[DocPath|DocPath]] and [[DocDir|DocDir]] are mutually exclusive. + +When a document specified by an external uri is given, the TOC should be searched for a reference to that uri and that line in the TOC should be selected and displayed (expanding parents if necessary.) + + +#### Expanding the contents of each document + +If a help uri is a directory or an index.html, then the help browser TOC SHOULD check if it will be handled by an index.docbook file. If so, that index.docbook file SHOULD be parsed for internal structure. This structure should be included in the TOC as children of the given desktop file. + +The structure MUST correspond to the internal structure of chapters, sections, and subsections. Chapters should be toplevels, as should sections that are not inside chapters. Subsections and sections that are inside chapters should be children of their parent nodes. + +Links should be to help: uris corresponding to the given chapter, section, or subsection. This may include a reference inside a single .html file if it contains multiple chapters, sections, or subsections. + +This expansion MAY be delayed until a given uri is displayed in the display area, but in this case, when an index.docbook file is processed, the TOC should be checked for uris that point to the top level inside the index.docbook. + +If displaying a URI from an external source, make sure to do this expansion before selecting the URI in the TOC because otherwise the URI might not be in the TOC. + + +## Locating Help Files + + +### GNOME + +Currently, Gnome uses [[ScrollKeeper|ScrollKeeper]] to install, register, and locate help files. Packages install OMF files along with their documentation and call scrollkeeper-install to register them with the system. + +Many other systems also use a separate metadata file, and this approach tends to work well. We need to decide on a metadata file format (probably .desktop files), where they are to be installed, and whether or not we need to call any installation scripts. + + +### TheGIMP + +The helpbrowser in GIMP uses an xml mapping file provided by the documentation package. Each language has his own XML mapping file, which is generated beside the generation of the HTML pages for the helpbrowser. A line in a mapping file looks like the following example: `<help-item id="introduction" ref="ch01.html" title="Introduction"/>` The mapping maps each unique id to a HTML file. The actual language dependend content is distinguished by the language variable set in the system. + + +## Identifying Help Files + +Documents need to have a unique identifier. For instance, the German and English translations of a document need to be identifiable as the same document, so that only one is presented to the user. Furthermore, document identifiers are necessary for invoking particular help files, either from applications, or from hyperlinks in other help files. + +Here are a number of proposals for identifiers: + +* Functional namespacing: + * All applications manuals would have identifiers such as app.*appname*.*docname*. Other manuals would live in top-level namespaces such as desktop or system. +* Reverse-DNS namespacing: + * Identifiers would begin with the reverse domain name of the group that produced the document. So the Gnome User Guide might be org.gnome.user-guide. +* Canonical URIs: + * Identifiers would simply be the URI of a canonical location of the document. The Gnome User Guide would be identified by [[http://www.gnome.org/learn/users-guide/|http://www.gnome.org/learn/users-guide/]] +How to avoid namespace clashes? + +* drop duplicated registrations?
\ No newline at end of file diff --git a/Specifications/help-system/Discussion.mdwn b/Specifications/help-system/Discussion.mdwn new file mode 100644 index 00000000..61ce1f96 --- /dev/null +++ b/Specifications/help-system/Discussion.mdwn @@ -0,0 +1,138 @@ + +Just starting the discussion page. + +Don't forget to sign your entries with your wiki name and to split entries. + +[[ChrisLahey|ChrisLahey]] + + + +--- + + + +The initial discussion started on the freedesktop.org mailing list. [[Shaun's first post|https://listman.redhat.com/archives/xdg-list/2003-December/msg00040.html]] contains a great summary of the goals of a common documentation standard. See also [[my follow-up|http://lists.freedesktop.org/archives/xdg/2004-February/003293.html]] summarizing what we agreed on. + +[[CorneliusSchumacher|CorneliusSchumacher]] + + + +--- + + + +There's a number of possibilities for how we find help files. This is all about coming up with a mapping from URIs to file names. + +The first question is what we use for URIs. There're basically two possibilities here. The first is to use https URLs that resolve to actual files on the internet. We then create some sort of local mapping to find those files on the local box. Let's call this local cache mapping. + +The second possibility is to have a specific URI domain that things map to. For example, we could map help:gnumeric/gnumeric.xml to $XDG_DATA_DIRS/help/C/gnumeric/gnumeric.xml (using the XDG base directory spec.) Of course, the app would look under different languages based on what locale the user was in. A variation on this is what KDE uses. + +There are a number of issues that have to be dealt with in both cases, as well as issues specific to one method or the other. + +The first issue I think of is the fact that a single docbook file often maps to multiple pages of data. This is the case in how help is displayed in both Gnome and KDE. I'm not sure how yelp solves this problem, but khelpcenter, if it can't find the given url, searches the directory given for an index.docbook file and uses that to generate the required html file. It saves this information to a cache file and just loads from that cache file if it exists. This solution works quite well. + +[[ChrisLahey|ChrisLahey]] + + + +--- + + + +I've thought of three possibilities for local cache mapping. Let's call them methods 1, 2, and 3. + +Methods 1 and 2 have in common that they're an arbitrary mapping from URL to filename. Method 1 is to have a database mapping the information and method 2 is to have individual files (probably .desktop file format) each one describing a single document. With method 2, you can have a database with a cache of all the information, but it's not the cononical source. + +For packaging purposes, method 2 is very clearly preferred to method 1. It's much easier for a distro to install an extra file than to modify a file that's already there. This is the reason, for example, that the menu spec allows you to search a directory and add any menu files found to the current menu. + +Method 3 is to have a specified mapping from URL to file name. For example, [[http://www.clahey.net/docs/present.html|http://www.clahey.net/docs/present.html]] might map to /usr/share/docs/www.clahey.net/docs/present.html with a backup to look for present.docbook or something like that. + +Of these 3, my favorite is method 2. However, I don't actually like any of them. I don't want a local cache mapping. + +First, it has the conceptual problem that a URL is variable whereas the docs on a particular distro are not. Or at the very least, they're variable in different dimensions. + +For example, if a distro makes changes to a program that lead to changes in documentation, that particular version of the doc is different from the one at the "cononical" source. Theoretically, you could put the docs in a different place, but there could be links all over the place to those docs. For instance, if docs for another program refer to docs for this program, when the user clicks on that link, you want them to get the docs for the version of the program that they will run, not the docs for some theoretical upstream version. + +Whereas online docs change in a different dimension, that of time. Say someone is using the upstream version of a program. They want the docs for their version, not the ones for the latest version. However, the link is to the online version which is going to be the latest version. Yes, it's going to try to map to the local copy, but which is the correct version of the document? + +The reason using online mappings like this works for DTDs is that they're defining something which isn't nearly as variable. Yes, the language described by the DTD changes over time, but you'll also note that the URL changes when the DTD does, and the documents described by the old DTD still point to the old URL as they should. + +That makes sense because DTDs are about describing the type of the current document. But that's not what links in help docs are for. They're for referring to other help, which should change, even if the referencing document doesn't. Having versioned URLs for the help means a huge maintenance pain keeping the links up to date. + +Local cache mapping is also a problem if a project doesn't have a web space of their own. Or say that the web space is small and won't handle high bandwidth. No matter whether we put the cache in or not, people will sometimes link to it. Or say that the web space is some awful URL. All in all, it seems like an odd requirement to have a web space to be able to link to your docs. + +Finally, perhaps we can come up with some sort of database of information about where the cononical docs are kept and include that in the docs themselves. Perhaps in some metadata. That way we make the cononical version an optional thing instead of a requirement that doesn't really make sense anyway. + +[[ChrisLahey|ChrisLahey]] + + + +--- + + + +I like the idea of having a help: URI namespace. We should really use the XDG data dirs standard for this. We should map <help:/path/to/file.ext> to <$XDG_DATA_DIRS/help/$lang/path/to/file.ext>. I'm totally fine with namespacing the path/to/file.ext with the project name, for example. Having all gnome docs be in <help:/gnome/> would be 100% fine with me. We could also have a <help:/common/> section for css and stuff like that. + +As far as pages inside a file, I'm fairly happy with the behavior that KDE has. <help:/path/to/file.ext> first checks for the given file. It then looks in the same directory for a file called index.docbook and sees if processing that file gives the file being looked for and uses that output if it does. This file isn't generated, but is stored in a cache index.cache.bz2 (that can be shipped so that it uses the cache on the first viewing.) + +One of the advantages of using XDG_DATA_DIRS is that we get the ability for user installed apps to have help very easily. The user can also do things like put a file in $XDG_DATA_HOME/help/common/default.css to change their stylesheet for accessibility or style reasons. + +[[ChrisLahey|ChrisLahey]] + + + +--- + + + +The next problem we need to solve is the table of contents of help (TOC). + +KDE's solution is to use the menu system and just put a reference to the help in the desktop files. This has the advantage that the help is arranged in the same way as the menus, so if the user knows how to find the app, they can find the help for it. + +KDE has the menu system as a subdirectory and keeps some other docs in a different hierarchy, but this is overly complicated. Instead, the help TOC should be a .menu file of its own with the main menu file as a subdirectory. + +One of the things that can be done is to match other elements of the menu system in the TOC. For instance, if a DE adds recently used apps to the menus, those apps can have a special section in the help TOC. + +Gnome uses scrollkeeper. One thing to note about scrollkeeper is that it requires keeping a database which takes up a bit of time every time we install. This also allows for the categories of help to be completely distinct from the applications themselves. This is a problem, since repeating the structure of the menus here means that the user only has to learn one location for a particular app. It would be possible to do the same thing with scrollkeeper, but it would add a whole lot of maintenance work to keep the two structures in sync. + +The one thing I'm not sure how to handle is an app with multiple help files, or even an extendable set of help files. + +For multiple help files, I suppose you could just list them all in the desktop file, but an extendable set of help files creates problems. The example I'm thinking of here is control center. In Novell's Gnome, control center is a single app, but the docs for it are split up into a bunch of bits. Does anyone have any suggestions for this problem? + +[[ChrisLahey|ChrisLahey]] + + + +--- + + + +The next thing I want to discuss is links to outside materials. I assume there's already a way to link to web pages, for instance. The main thing I'm curious about is the concept of launching applications and doing actions in them. For instance, the help manual for a particular app might be able to pull up that particular app or open a specific dialog in that app. + +I think the right way to do this is the simple way. Just support a url scheme that lets you execute code. Perhaps shell: or something like that. This is simple and should work. + +One thing that's important is the security issues here. If you're going to support this link type, you need to make sure that it comes from local documentation, and not a website. + +An alternative to this is to just have a predefined set of actions that are possible. Say a specific directory full of desktop files for help docs to execute. The help doc just specifies the name of the desktop file. This way, even if a website does include such a link, all that happens is one of the predefined actions. (Note, the link shouldn't be allowed to pass arguments to the desktop file for security reasons. I think we need a separate desktop file for each possible thing the help doc might want to do.) + +[[ChrisLahey|ChrisLahey]] + + + +--- + + + +I've started writing up all the ideas here in the parent document as a specification. + +[[ChrisLahey|ChrisLahey]] + + + +--- + + + +I went in and boldly edited the parent document, recommending simple support for man and info. There are LOTS of documents in these formats; if we support them directly, then we have an integrated system for handling them. Forcing everyone to store man and HTML files makes no sense in many circumstances; best to do the translation on the fly, in which case a "man" convention helps. + +[[DavidWheeler|DavidWheeler]] diff --git a/Specifications/icc_profiles_in_x_spec.mdwn b/Specifications/icc_profiles_in_x_spec.mdwn new file mode 100644 index 00000000..a44daa48 --- /dev/null +++ b/Specifications/icc_profiles_in_x_spec.mdwn @@ -0,0 +1,19 @@ + + +## ICC Profiles in X Specification + +The specification describes ICC profile attachement to monitor hardware inside X to achieve network transparency. + + +### Spec + +* Version 0.4 [[ICC Profiles in X Specification 0.4|http://www.freedesktop.org/wiki/OpenIcc/ICC_Profiles_in_X_Specification_0.4]] 2010, september, 19th + + +### References + +The spec was proposed and maintained over the [[OpenIcc|OpenIcc]] [[email list|http://lists.freedesktop.org/mailman/listinfo/openicc]]. + +A History and a list of further tasks is available on [[ColourWiki|http://www.oyranos.org/wiki/index.php?title=Oyranos/X11_Requirements]]. + +[[ICC Profiles in X Users list|http://www.freedesktop.org/wiki/OpenIcc/ICC_Profiles_in_X_Users]] diff --git a/Specifications/icon-naming-spec.mdwn b/Specifications/icon-naming-spec.mdwn new file mode 100644 index 00000000..9fa5ae80 --- /dev/null +++ b/Specifications/icon-naming-spec.mdwn @@ -0,0 +1,34 @@ + + +## Icon Names + +An icon theme can benefit from the use of a standard listing of common icon contexts and names. An icon theme author can then make use of these contexts and names and expect an icon theme to work in a desktop environment or application that implements the naming specification. + + +### Mailinglist + +Discussion of this specification should occur on the [[xdg mailing list|http://lists.freedesktop.org/mailman/listinfo/xdg]]. + + +### Missing Icons List + +This is a [[listing of icons whose names are not yet covered|Specifications/icon-naming-spec/to-be-named]] in the latest Icon Naming Specification. + + +### Additional Icons for several Desktops + +This [[Desktop Icons List|Specifications/icon-naming-spec/desktop-icon-lists]] is meant to be used for icon names for various desktops, which are not covered by the specification. + + +### Git + +The [[Git|Infrastructure/git]] module for this code is [[xdg/default-icon-theme|http://cgit.freedesktop.org/xdg/default-icon-theme/]]. + + +### Spec + + * Latest version - [[html (one page)|http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html]] - [[html (multiple pages)|http://standards.freedesktop.org/icon-naming-spec/latest/]] + * Version 0.8 - [[html (one page)|http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-0.8.html]] - [[html (multiple pages)|http://standards.freedesktop.org/icon-naming-spec/0.8/]] [[xml|http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-0.8.xml]] + * Version 0.7 - [[html (one page)|http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-0.7.html]] - [[html (multiple pages)|http://standards.freedesktop.org/icon-naming-spec/0.7/]] [[xml|http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-0.7.xml]] + * Version 0.6 - [[html (one page)|http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-0.6.html]] - [[html (multiple pages)|http://standards.freedesktop.org/icon-naming-spec/0.6/]] [[xml|http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-0.6.xml]] + * Version 0.4 - [[html (one page)|http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-0.4.html]] - [[html (multiple pages)|http://standards.freedesktop.org/icon-naming-spec/0.4/]] [[xml|http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-0.4.xml]]
\ No newline at end of file diff --git a/Specifications/icon-naming-spec/desktop-icon-lists.mdwn b/Specifications/icon-naming-spec/desktop-icon-lists.mdwn new file mode 100644 index 00000000..cb0be7a0 --- /dev/null +++ b/Specifications/icon-naming-spec/desktop-icon-lists.mdwn @@ -0,0 +1,11 @@ + + +# Desktop Icon Lists + +* [[Programming|Specifications/icon-naming-spec/desktop-icon-lists.Programming]] +* [[Graphic Design|Specifications/icon-naming-spec/desktop-icon-lists.GraphicDesign]] +* [[Data Management|Specifications/icon-naming-spec/desktop-icon-lists.DataManagement]] +* [[Device Icons|Specifications/icon-naming-spec/desktop-icon-lists.DeviceIcons]] +* [[Audio Production|Specifications/icon-naming-spec/desktop-icon-lists.AudioProduction]] +* [[Video Production|Specifications/icon-naming-spec/desktop-icon-lists.VideoProduction]] +* [[Video Gaming|Specifications/icon-naming-spec/desktop-icon-lists.VideoGaming]]
\ No newline at end of file diff --git a/Specifications/icon-naming-spec/to-be-named.mdwn b/Specifications/icon-naming-spec/to-be-named.mdwn new file mode 100644 index 00000000..8653370e --- /dev/null +++ b/Specifications/icon-naming-spec/to-be-named.mdwn @@ -0,0 +1,59 @@ + +This is a listing of icons whose names are not yet covered in the [[latest Icon Naming Specification|http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html]]. + +Please enter (if available) the icon's: + +* temporary or proposed name +* directory +* image or link to where it can be seen +* description +The above information will be carefully considered, discussed and a final name (in compliance with the Icon Naming Specification) will be provided. Discussion of naming and its specifications should occur on the [[xdg mailing list|http://lists.freedesktop.org/mailman/listinfo/xdg]]. +[[!table header="no" class="mointable" data=""" + +Temporary or Proposed Name | Context | | Description | Final/Approved Name | Reported by: + Emotion | ||| | ||| +face-angry | Emotion | | for the >:( emote | TBD | [[DianaFong|DianaFong]] +face-angry-yelling | Emotion | | for the >:( emote | TBD | [[DianaFong|DianaFong]] +face-confused | Emotion | | for the :-S emote | TBD | [[DianaFong|DianaFong]] +face-embarrassed | Emotion | | for the :-[ emote | TBD | [[DianaFong|DianaFong]] +face-laugh | Emotion | | for the XD emote | TBD | [[DianaFong|DianaFong]] +face-sleep | Emotion | | for the (-.-)zzZ emote | TBD | [[DianaFong|DianaFong]] +face-tongue | Emotion | | for the :-p emote | TBD | [[DianaFong|DianaFong]] +face-uneasy | Emotion | | for the :-/ emote | TBD | [[DianaFong|DianaFong]] +face-yawn | Emotion | | for the |-O emote | TBD | [[DianaFong|DianaFong]] + Standard Device | ||| | ||| +gpm-ac-adapter | Standard Device | | AC adapter | TBD | [[DianaFong|DianaFong]] + Standard Status | ||| | ||| +gpm-primary-{000-100} | Standard Status | | Laptop battery status | TBD | [[DianaFong|DianaFong]] +gpm-primary-{000-100}-charging | Standard Status | | Laptop battery icon, on AC power | TBD | [[DianaFong|DianaFong]] +gpm-primary-charged | Standard Status | | Laptop battery icon 100% fill, on AC power | TBD | [[DianaFong|DianaFong]] +gpm-primary-missing | Standard Status | | Laptop battery missing or state invalid | TBD | [[DianaFong|DianaFong]] +gpm-ups-{000-100} | Standard Status | | UPS battery icon | TBD | [[DianaFong|DianaFong]] +gpm-ups-{000-100}-charging | Standard Status | | UPS battery icon, charging | TBD | [[DianaFong|DianaFong]] +gpm-ups-charged | Standard Status | | UPS battery icon 100% fill, on AC power | TBD | [[DianaFong|DianaFong]] +gpm-ups-missing | Standard Status | | UPS battery missing or state invalid | TBD | [[DianaFong|DianaFong]] +gpm-mouse-{000-100} | Standard Status | | CSR mouse icon | TBD | [[DianaFong|DianaFong]] +gpm-keyboard-{000-100} | Standard Status | | CSR keyboard icon | TBD | [[DianaFong|DianaFong]] +gpm-hibernate | Standard Status | | Hibernate icon | TBD | [[DianaFong|DianaFong]] +gpm-suspend | Standard Status | | Suspend icon | TBD | [[DianaFong|DianaFong]] +gpm-brightness-lcd | Standard Status | | LCD brightness icon | TBD | [[DianaFong|DianaFong]] +gpm-brightness-kbd | Standard Status | | Keyboard brightness icon | TBD | [[DianaFong|DianaFong]] + Standard Action | ||| | ||| +go-next-document | Action | [[!img http://img378.imageshack.us/img378/8797/gonextdocumentit8.png] | KDE 3 "next" | TBD | [[JamesRichardTyrer|JamesRichardTyrer]] +go-previous-document | Action | [[!img http://img352.imageshack.us/img352/3867/gopreviousdocumentex7.png] | KDE 3 "previous" | TBD | [[JamesRichardTyrer|JamesRichardTyrer]] +view-fit-window | Action | [[!img http://img142.imageshack.us/img142/9606/viewfitwindowfp7.png] | changes size to fit window | TBD | [[JamesRichardTyrer|JamesRichardTyrer]] +view-fit-height | Action | [[!img http://img209.imageshack.us/img209/3457/viewfitheightgy6.png] | changes size to fit window height | TBD | [[JamesRichardTyrer|JamesRichardTyrer]] +view-fit-width | Action | [[!img http://img149.imageshack.us/img149/9729/viewfitwidthon1.png] | changes size to fit window width | TBD | [[JamesRichardTyrer|JamesRichardTyrer]] +view | Action | [[!img http://img167.imageshack.us/img167/7092/viewsm9.png] | generic view | TBD | [[JamesRichardTyrer|JamesRichardTyrer]] +zoom | Action | [[!img http://img384.imageshack.us/img384/5290/viewmagok0.png] | generic zoom | TBD | [[JamesRichardTyrer|JamesRichardTyrer]] + Standard Emblem | ||| | ||| +emblem-mounted | Emblem | [[!img http://img54.imageshack.us/img54/8898/emblemmountedzu0.png] | emblem to indicate that device is mounted | TBD | [[JamesRichardTyrer|JamesRichardTyrer]] + Standard Application | ||| | ||| +preferences-desktop-display | Applications | [[!img http://www.florilege.org/24x24/apps/gnome-display-properties.png] | Display preferences | TBD | [[MatthiasClasen|MatthiasClasen]] +preferences-desktop-sound | Applications | [[!img http://www.florilege.org/24x24/apps/gnome-sound-properties.png] | Sound preferences | TBD | [[MatthiasClasen|MatthiasClasen]] +preferences-desktop-network | Applications | [[!img http://www.florilege.org/24x24/apps/gnome-network-preferences.png] | Network preferences | TBD | [[MatthiasClasen|MatthiasClasen]] +preferences-desktop-applications | Applications | [[!img http://www.florilege.org/24x24/apps/gnome-settings-default-applications.png] | Default Applications | TBD | [[MatthiasClasen|MatthiasClasen]] +preferences-desktop-mouse | Applications | | Mouse preferences | TBD | [[MatthiasClasen|MatthiasClasen]] +"""]] + +*For [[more info on the gpm icon naming scheme|http://cvs.gnome.org/viewcvs/*checkout*/gnome-power-manager/docs/icon-scheme.html#icon-names]]. diff --git a/Specifications/icon-theme-spec.mdwn b/Specifications/icon-theme-spec.mdwn new file mode 100644 index 00000000..35421b20 --- /dev/null +++ b/Specifications/icon-theme-spec.mdwn @@ -0,0 +1,25 @@ + + +## Icon Themes + +An icon theme is a set of icons that share a common look and feel. The user can then select the icon theme that they want to use, and all applications will use icons from the theme. + + +### Mailinglist + +Discussion of this specification should occur on the [[xdg mailing list|http://lists.freedesktop.org/mailman/listinfo/xdg]]. + + +### Git + +The [[Git|Infrastructure/git]] module for this code is [[xdg/default-icon-theme|http://cgit.freedesktop.org/xdg/default-icon-theme/]]. + + +### Spec + + * Latest version (0.11) - [[html (one page)|http://standards.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html]] - [[html (multiple pages)|http://standards.freedesktop.org/icon-theme-spec/latest/]] - [[xml|http://standards.freedesktop.org/icon-theme-spec/icon-theme-spec-0.11.xml]] + * Version 0.10 - [[html (one page)|http://standards.freedesktop.org/icon-theme-spec/icon-theme-spec-0.10.html]] - [[html (multiple pages)|http://standards.freedesktop.org/icon-theme-spec/0.10/]] - [[xml|http://standards.freedesktop.org/icon-theme-spec/icon-theme-spec-0.10.xml]] + * Version 0.9 - [[html (one page)|http://standards.freedesktop.org/icon-theme-spec/icon-theme-spec-0.9.html]] - [[html (multiple pages)|http://standards.freedesktop.org/icon-theme-spec/0.9/]] - [[xml|http://standards.freedesktop.org/icon-theme-spec/icon-theme-spec-0.9.xml]] + * Version 0.8 - [[html (one page)|http://standards.freedesktop.org/icon-theme-spec/icon-theme-spec-0.8.html]] - [[html (multiple pages)|http://standards.freedesktop.org/icon-theme-spec/0.8/]] - [[xml|http://standards.freedesktop.org/icon-theme-spec/icon-theme-spec-0.8.xml]] + * Version 0.7 - [[html (one page)|http://standards.freedesktop.org/icon-theme-spec/icon-theme-spec-0.7.html]] - [[html (multiple pages)|http://standards.freedesktop.org/icon-theme-spec/0.7/]] - [[xml|http://standards.freedesktop.org/icon-theme-spec/icon-theme-spec-0.7.xml]] + * Version 0.6 - [[html (one page)|http://standards.freedesktop.org/icon-theme-spec/icon-theme-spec-0.6.html]] - [[html (multiple pages)|http://standards.freedesktop.org/icon-theme-spec/0.6/]] - [[xml|http://standards.freedesktop.org/icon-theme-spec/icon-theme-spec-0.6.xml]]
\ No newline at end of file diff --git a/Specifications/menu-spec.mdwn b/Specifications/menu-spec.mdwn new file mode 100644 index 00000000..adad5791 --- /dev/null +++ b/Specifications/menu-spec.mdwn @@ -0,0 +1,28 @@ + + +### Desktop Menu Specification + +This DRAFT document defines how to construct a user-visible hierarchy of applications, typically displayed as a menu. It allows third-party software to add menu items that work for all desktops, and allows system administrators to edit menus in a way that affects all desktops. + + +### Mailinglist + +Discussion of this specification should occur on [[xdg|http://mailman/listinfo/xdg]]. + + +### CVS + +The [[CVS|http:GettingInvolved#CVS]] module for this spec is [[menu-spec|http://cvs.freedesktop.org/menus/menu-spec/]]. + + +### Spec + + * [[Latest version|http://standards.freedesktop.org/menu-spec/latest/]] + * Version 1.0 - [[html (one page)|http://standards.freedesktop.org/menu-spec/menu-spec-1.0.html]] - [[html (multiple pages)|http://standards.freedesktop.org/menu-spec/1.0/]] - [[xml|http://standards.freedesktop.org/menu-spec/menu-spec-1.0.xml]] + * Version 0.9 - [[html (one page)|http://standards.freedesktop.org/menu-spec/menu-spec-0.9.html]] - [[html (multiple pages)|http://standards.freedesktop.org/menu-spec/0.9/]] - [[xml|http://standards.freedesktop.org/menu-spec/menu-spec-0.9.xml]] + * Version 0.8 - [[html (one page)|http://standards.freedesktop.org/menu-spec/menu-spec-0.8.html]] - [[html (multiple pages)|http://standards.freedesktop.org/menu-spec/0.8/]] - [[xml|http://standards.freedesktop.org/menu-spec/menu-spec-0.8.xml]] + * Version 0.7 - [[html (one page)|http://standards.freedesktop.org/menu-spec/menu-spec-0.7.html]] - [[html (multiple pages)|http://standards.freedesktop.org/menu-spec/0.7]] - [[xml|http://standards.freedesktop.org/menu-spec/menu-spec-0.7.xml]] + +### See Also + +The [[xdg-utils|http://portland.freedesktop.org/wiki/XdgUtils]] package is a useful implementation of this specification. It provides simple interfaces to create menu entries or desktop icons on a Free Desktop. xdg-utils should save a typical application developer considerable time and heartburn. diff --git a/Specifications/mime-actions-spec.mdwn b/Specifications/mime-actions-spec.mdwn new file mode 100644 index 00000000..2a134609 --- /dev/null +++ b/Specifications/mime-actions-spec.mdwn @@ -0,0 +1,69 @@ + + +# MIME actions + +The freedesktop.org [[Shared MIME database|Specifications/shared-mime-info-spec]] provides a single way to store static information about MIME types and rules for determining a type. + +In addition to this, three further pieces of information are often needed: + + * Which applications can open a file (_Mozilla can view files of type text/html_). This is defined in the [[MimeTypes|http://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-1.0.html#id2926453]] key of the .desktop file of the application, see the desktop entry spec. + * Which application should open a file by default (_Application X wants to be the default application for text/html after installation_) + * How to let the user change the default application (_Bob wishes to view text/html files in Mozilla by default_). + +## Status + +This specification has been finalized through discussions on the xdg mailing-list, but no formal spec has been written (volunteers welcome). + + +## Default application ordering + +This hasn't been finalized in a cross-desktop way yet; especially since the default application is probably desktop specific in some cases. Discussions happened on the mailing-list about this (see thread "Have a way to dynamically change software associations at distribution level", links at bottom of this page). + +The current status-quo is that KDE orders on the [[InitialPreference|InitialPreference]] key in the .desktop files (higher = preferred), and gnome uses a global configuration file defaults.list. Effectively this makes the default ordering desktop-specific, but gives more work to distributions. + +However, note that the next section provides another solution for ISV applications which want to ensure they become the default application after being installed: they can edit [or create] the global mimeapps.list file in /usr/share/applications. This is also a solution for system administrators who wish to set up a default application ordering for their users. + + +## User-specified application ordering + +Users can change the default order of applications by writing (using graphical tools, of course) into the file ~/.local/share/applications/mimeapps.list + +The syntax of this file is: + + [Added Associations] + mimetype1=foo1.desktop;foo2.desktop;foo3.desktop; + mimetype2=foo4.desktop; + [Removed Associations] + mimetype1=foo5.desktop; + +This means that foo1 is the preferred application for mimetype1, but if it is not installed then foo2 is going to be used, etc. It also means that if another application, say "new.desktop" is installed with mimetype1 in its mimetypes line, it will be at the fourth place in the list of applications associated with mimetype1 (it comes after the explicitely specified ones). On the other hand, the application foo5 was explicitely removed by the user, so it is not associated with mimetype1 anymore. + +This mechanism allows for multiple levels of configuration, where mimeapps.list files override each other in XDG_DATA_DIRS directories. Sysadmin-provided settings can be overridden by user-local mimeapps.list files). + + +## Non normative: Initial set of requirements, not all of which are covered by the current specification + +Do not use any of this in implementations at this point, this was just input for the discussion. + +The list of applications which can open files of a particular type is static information and should be stored in the MIME database, using some extension elements. The [[Adding to the MIME database tutorial|Specifications/AddingMIMETutor]] provides a sample of how this might look. The extension element associates MIME entries with application **.desktop** files (eg, **gimp.desktop**). Issues to address: + + * Must provide a way to find a command to execute to view/edit/etc a file. + * There should be support for multiple actions (view, edit, print, etc). + * There must be some kind of priority system (Vim can view HTML, but should not be the default if a web browser is installed). + * Internationalised descriptions of applications should not be repeated (Gimp should not have to specify translations of "Edit in Gimp" for every MIME type it supports). + * There should be a way to overwrite the system defaults by user defaults. (eg. User a[dmin] will edit text files with vim and user b will use emacs) + * There should be a way to choose a program for an action, therefore there must be made a list of the programs that can do this action to a file format. On this way you can open a file with a program that is not the default program for the file format.(eg. png editor is gimp but you want to test a new picture editor) + * There should be a way to detect which environment is being used and how a file should be open (eg. editing a text file by choosing them with mc in a terminal should use a console based editor, but when mc runs in a xterm, an X-Window editor can also be used) +Setting the default application: + +Because this is configuration information, it should not go in the MIME database. Instead, it should be set using the [[Shared Configuration System|Specifications/config-spec]]. This specification should define a set of key names to be used for this. + + +## References + + * [[Shared mimetypes + activation thread|http://thread.gmane.org/gmane.linux.xdg.devel/2925]] + * [[Associating programs with file types thread|http://thread.gmane.org/gmane.linux.xdg.devel/2524]] + * [[MIME activation discussion thread|http://thread.gmane.org/gmane.linux.xdg.devel/554]] + * [[Default Program / File Association thread|http://thread.gmane.org/gmane.linux.xdg.devel/2228]] ([[part II|http://thread.gmane.org/gmane.linux.xdg.devel/2239]]) + * [[More recent Default Program / File Association thread, where mimeapps.list was introduced|http://thread.gmane.org/gmane.comp.freedesktop.xdg/9828]] + * [[Have a way to dynamically change software associations at distribution level|http://thread.gmane.org/gmane.comp.freedesktop.xdg/11520]] diff --git a/Specifications/mpris-interfacing-specification.mdwn b/Specifications/mpris-interfacing-specification.mdwn new file mode 100644 index 00000000..e69de29b --- /dev/null +++ b/Specifications/mpris-interfacing-specification.mdwn diff --git a/Specifications/open-collaboration-services.mdwn b/Specifications/open-collaboration-services.mdwn new file mode 100644 index 00000000..bf14fe1a --- /dev/null +++ b/Specifications/open-collaboration-services.mdwn @@ -0,0 +1,3855 @@ +# Open Collaboration Services v1.6 + +Frank Karlitschek [[MailTo(karlitschek AT kde.org)|MailTo(karlitschek AT kde.org)]] + +[[OCS Mailinglist|http://lists.freedesktop.org/mailman/listinfo/ocs]] + +[[!toc ]] + + +## Changelog + +Differences between 1.5 and 1.6 PERSON: + + * man -> male extended-attributes: add lastmodified +CONTENT: + + * voting. support for votes from 0 to 100 gpgfingerprint to content add,edit,download,get gpgsignature to content add,edit,download,get support packagenamer/repository in add,edit,download add a summary field add a feedbackurl list add support for search for distributions or licenses add support for icons to list and get support for video files support to fetch recommendations. +COMMENTS: + + * voting +PRIVATEDATA: + + * new module +FORUM: + + * new module +BUILDSERVICE: + + * new module + +## Purpose + +integration of web communities and web bases services into desktop and mobile applications. free, secure, privacy protected, vendor independent. + + +## Examples + +* show all my friends on my desktop and make it possible to contact them via email, messaging, instant messaging, screensharing or other. +* find online support information and show them directly in the application +* show other people with similar interests or from the same city and enable filesharing and collaboration +* show the activities of my friends on my desktop +* show related free software events in my region in my calendar. +* make it possible for a person to become a "friend" of a developer and a fan of an application +* find other people to work together on one document. (collaboration) +* find other people with the same hardware to get help and exchange tips. +* show kde related and personalized news directly on the desktop + +## Naming + +* client - the desktop or mobile application, web frontend or proxy who access the services. +* service provider - web bases application, webservices or online communities who provide open collaboration services. +* provider file - a xml configuration file which maps clients to service providers + +## Requirements + + +### Performance / Scalability + +the services should be usable by millions of people at the same time. because of that it is important to build the architecture in a scalable way. every component of the architecture must be cluster enabled. this means that it must be possible to implement every service or component in a server cluster. + + +### Security + +the data transfer should be encrypted if possible. + + +### Privacy + +it is essential to respect the privacy requirements of the people. every person must have full control over the personal information. + + +### Vendor Independent + +it is important for an application to be independent of a specific websites or services because of that we use independent provider files who map the clients to the service providers. For example the KDE project has provider files hosted on the KDE.org server who contains a list of providers who are providing a specific service. So the application maintainer has full control over which content and services are accessed by the application (client) + + +## Architecture + + +### REST + +We use REST for the webservices calls. Unlike, for example SOAP, REST is very, lightweight, easy to learn and implement and cachable. REST is very widespread in the internet and is used by other popular webservices. REST support is integrated into various web or desktop frameworks and it is platform and technology independent The data exchange format is XML. If you add the format=json parameter you can also get the data in JSON format. + + +### SSL + +we suggest to use ssl to encrypt the data transfer between client and service providers. unencrypted data transfer is also possible when a SSL it too expensive or slow. + + +### Authentication + +most services require a authenticated user. this is important for legal reasons. and to prevent DOS attacks. At the moment we support autentification via login/password or an API key. You have to get the API key from the service provider We will support OpenID in a later version of the specification. + + +#### example login/password + +[[https://frank:password@api.opendesktop.org/v1/activity?page=3|https://frank:password@api.opendesktop.org/v1/activity?page=3]] + + +#### example api key + +[[https://API5142830791365744186814934@api.opendesktop.org/v1/activity?page=3|https://API5142830791365744186814934@api.opendesktop.org/v1/activity?page=3]] + + +### Proxy + +it is possible to implement proxy service provider to integrate other proprietary webservices. + + +### Date Format + +All date and time data is in ISO 8601 format. + + +### Services + +the applications or websites do not have to support every service. We suggest to implement only the services into the clients or service providers which are usefull for the users at this point. + +At the moment there are the following services: + +* [[CONFIG|Specifications/open-collaboration-services]] +* [[PERSON|Specifications/open-collaboration-services]] +* [[FRIEND|Specifications/open-collaboration-services]] +* [[MESSAGE|Specifications/open-collaboration-services]] +* [[ACTIVITY|Specifications/open-collaboration-services]] +* [[CONTENT|Specifications/open-collaboration-services]] +* [[FAN|Specifications/open-collaboration-services]] +* [[KNOWLEDGEBASE|Specifications/open-collaboration-services]] +* [[EVENT|Specifications/open-collaboration-services]] +* [[COMMENTS|Specifications/open-collaboration-services]] +* [[PRIVATE DATA|Specifications/open-collaboration-services]] +* [[FORUM|Specifications/open-collaboration-services]] +* ...more to come later + +### Error Reporting + +every response xml contains a "status", "statuscode" and a "message" tag. the status tag has only two possible values. "ok" or "failed". If the status is "failed" you can get a human readable errortext from the "message" tag. Examples of errormessages are: "data is private" or "person not found". You get a machine readable status in the "statuscode" tag. Statuscode 100 means "request sucessful", 999 means "unknown request". All other codes are specific to the called method and described below. + + +### Versioning + +we support versioning of the service specifications. so if we break the api in an incompatible way we can use a new version number and still keep the old API for legacy applications(client) please note that the api is currently in draft state. so it will change in the future + + +### Provider files + +it is important to decouple the applications from the services. so we suggest to use provider files to control the mapping of applications to service providers. if an application wants to access a services it first gets the provider file to get the list of available providers. than it can access the different providers and merge the results. An example provider file: + + <providers> + + <provider> + <id>opendesktop</id> + <location>https://api.opendesktop.org/v1/</location> + <name>openDesktop.org</name> + <icon></icon> + <termsofuse>https://opendesktop.org/terms/</termsofuse> + <register>https://opendesktop.org/usermanager/new.php</register> + <services> + <person ocsversion="1.3" /> + <friend ocsversion="1.3" /> + <message ocsversion="1.3" /> + <activity ocsversion="1.3" /> + <content ocsversion="1.3" /> + <fan ocsversion="1.3" /> + <knowledgebase ocsversion="1.3" /> + <event ocsversion="1.3" /> + </services> + </provider> + + <provider> + <id>testy</id> + <location>http://api.foo.org</location> + <name>Foo provider</name> + <icon></icon> + <termsofuse>https://foo.org/terms/</termsofuse> + <register>https://foo.org/register.php</register> + <services> + <person ocsversion="1.5" /> + <friend ocsversion="1.3" /> + <message ocsversion="1.3" /> + <knowledgebase ocsversion="1.2" /> + <event ocsversion="1.1" /> + </services> + </provider> + + </providers> + +The KDE provider file is here: [[http://download.kde.org/ocs/providers.xml|http://download.kde.org/ocs/providers.xml]] + + +## Service Specifications + +<a name="CONFIG"></a> +### CONFIG + + +#### config + +get some basic API configuration information + +* Syntax: /v1/config +* Method: GET +* Statuscodes: + * 100 - successful +Example: GET <http://api.opendesktop.org/v1/config> Example: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + </meta> + <data> + <version>1.4</version> + <website>openDesktop.org</website> + <host>api.openDesktop.org</host> + <contact>frank@openDesktop.org</contact> + <ssl>true</ssl> + </data> + </ocs> + +<a name="PERSON"></a> +### PERSON + +The PERSON service is handling the access to user data. you can search people and access personal data of other people of the person made the information public. The personids are stored and shown case sensitive. But if you want to reference a person the personid is case insensitive. + + +#### check + +Check if the given login and password or the API key is valid. It returns the associated username. + +* Syntax: /v1/person/check +* Method: POST +* POST Arguments: login - The login or the API key +* POST Arguments: password - The password +* Mandatory fields: "login" +* Statuscodes: + * 100 - successfull / valid account + * 101 - please specify all mandatory fields + * 102 - login not valid +Example: POST <http://api.opendesktop.org/v1/person/check> postdata: login="frank" password="123456" Checks if frank,123456 is a valid account. Example: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + </meta> + <data> + <person details="check"> + <personid>frank</personid> + </person> + </data> + </ocs> + +#### add + +Registers a new user account on the server. The users still have to approve the account by clicking on a link in a confirmation email to activate the account. Only alphanumeric characters are allowed and the password has to be 8 characters or longer. + +* Syntax: /v1/person/add +* Method: POST +* POST Arguments: login - The login or the API key +* POST Arguments: password - The password +* POST Arguments: firstname - The firstname of the user +* POST Arguments: lastname - The lastname of the user +* POST Arguments: email - the email address. the address must be valid, because the user gets a confirmation email to this address. +* Mandatory fields: "login", "password", "firstname", "lastname" and "email" +* Statuscodes: + * 100 - successfull / valid account + * 101 - please specify all mandatory fields + * 102 - please specify a valid password + * 103 - please specify a valid login + * 104 - login already exists + * 105 - email already taken + * 106 - email invalid +Example: POST <http://api.opendesktop.org/v1/person/add> postdata: login="frank" password="123456" firstname="Frank" lastname="Karlitschek" email="[[karlitschek@kde.org|mailto:karlitschek@kde.org]]" registers a new user account. Example: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + </meta> + </ocs> + +#### search + +find a specific list of persons. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. It is not possible to get a list of more than 1000 people because of privacy issues. + +* Syntax: /v1/person/data +* HTTP method: GET +* url arguments: name - A part of the name or personid you want to search for. +* url arguments: country - The country id of the country you want to search in. +* url arguments: city - The name of the city as a string. +* url arguments: description - A string you want to search for in the description and other fields of the person. +* url arguments: pc - A string you want to search for in the pc/hardware field of the person. +* url arguments: software - A string you want to search for in the software field of the person. +* url arguments: longitude - The longitude of the position where you want to find people. +* url arguments: latitude - The latitude of the position where you want to find people. +* url arguments: distance - The maximum distance of the person to you longitude/latitude position. if you specify the latitude and longitude but no distance the resultset will be ordered by distance. The unit of the distance parameter is degrees. +* url arguments: attributeapp - The applicationname or namespace of the attribute. +* url arguments: attributekey - The key of the attribute. +* url arguments: attributevalue - The value of the attribute. +* url arguments: page - The content page. You can control the size of a page with the pagesize parameter. The first page is 0, the second is 1, ... +* url arguments: pagesize - The amount of entries your get per page. +* Statuscodes: + * 100 - successfull + * 102 - more than 1000 people found. it is not allowed to fetch such a big resultset. please specify more search conditions + * 200 - too many API requests in the last 15 minutes from your IP address. please try again later. +* Result: personlist xml +Example: GET <http://frank:password@api.opendesktop.org/v1/person/data?name=eter&city=don&description=development&latitude=11.2&longitude=22&distance=0.5&page=2&pagesize=10> Gets the third page of the search result list from the search for person where "eter" is in the nickname, firstname or lastname and "don" is in the city and who is interested in "development" and who lived near latitude:11.2 and longitude:22.0 witch a tolerance of 0.5 + +Example: <?xml version="1.0"?> + + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + <totalitems>2</totalitems> + <itemsperpage>10</itemsperpage> + </meta> + <data> + <person details="summary"> + <personid>Testy</personid> + <privacy>0</privacy> + <privacytext>public</privacytext> + <firstname>Peter</firstname> + <lastname>-</lastname> + <company></company> + <gender></gender> + <communityrole></communityrole> + <city>London</city> + <country></country> + </person> + <person details="summary"> + <personid>peter</personid> + <privacy>0</privacy> + <privacytext>public</privacytext> + <firstname>Frank</firstname> + <lastname>Test</lastname> + <company>company</company> + <gender>male</gender> + <communityrole></communityrole> + <city>London</city> + <country></country> + </person> + </data> + </ocs> + +#### get + +get the data from one specific person. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. + +* Syntax: /v1/person/data/"personid"/ +* HTTP method: GET +* Arguments: personid - Id of a person. for example "frank" +* Result: person xml +* Statuscodes: + * 100 - successfull + * 101 - person not found + * 102 - data is private +* Example: GET <http://frank:password@api.opendesktop.org/v1/person/data/frank> +Example: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + </meta> + <data> + <person details="full"> + <personid>Frank</personid> + <privacy>1</privacy> + <privacytext>visible only for registered users</privacytext> + <firstname>Frank</firstname> + <lastname>Test</lastname> + <gender>male</gender> + <communityrole>developer</communityrole> + <homepage>openDesktop.org</homepage> + <homepagetype></homepagetype> + <homepageicon></homepageicon> + <homepage2></homepage2> + <homepagetype2></homepagetype2> + <homepage3></homepage3> + <homepagetype3></homepagetype3> + <homepage4></homepage4> + <homepagetype4></homepagetype4> + <homepageicon4></homepageicon4> + <homepage5></homepage5> + <homepagetype5></homepagetype5> + <homepage6>www.facebook.com/foo</homepage6> + <homepagetype6>Facebook</homepagetype6> + <homepageicon6>http://openDesktop.org/img/socialicons/emblem-facebook.png</homepageicon6> + <company>opendesktop.org</company> + <avatarpic>http://www.KDE-Look.org/CONTENT/user-pics/0/Frank.jpg</avatarpic> + <avatarpicfound>1</avatarpicfound> + <bigavatarpic>http://www.KDE-Look.org/CONTENT/user-bigpics/0/Frank.jpg</bigavatarpic> + <bigavatarpicfound>1</bigavatarpicfound> + <birthday>1973-07-25</birthday> + <jobstatus>working</jobstatus> + <city>Stuttgart</city> + <country>Germany</country> + <latitude></latitude> + <longitude></longitude> + <ircnick>karli</ircnick> + <ircchannels>kde-dev, plasma</ircchannels> + <irclink>irc://irc.freenode.org/kde-dev</irclink> + <irclink>irc://irc.freenode.org/plasma</irclink> + <likes>lot of stuff</likes> + <dontlikes>nothing</dontlikes> + <interests>travel</interests> + <languages>english</languages> + <programminglanguages>php, c++</programminglanguages> + <favouritequote></favouritequote> + <favouritemusic>nin</favouritemusic> + <favouritetvshows></favouritetvshows> + <favouritemovies>fightclub</favouritemovies> + <favouritebooks></favouritebooks> + <favouritegames>ut3</favouritegames> + <description></description> + <profilepage>http://www.KDE-Look.org/usermanager/search.php?username=Frank</profilepage> + </person> + </data> + </ocs> + +#### get self + +get the data from yourself. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. + +* Syntax: /v1/person/self +* HTTP method: GET +* Result: person xml +* Statuscodes: + * 100 - successfull +* Example: GET <http://frank:password@api.opendesktop.org/v1/person/self> +Example: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + </meta> + <data> + <person details="full"> + <personid>Frank</personid> + <privacy>1</privacy> + <privacytext>visible only for registered users</privacytext> + <firstname>Frank</firstname> + <lastname>Test</lastname> + <gender>male</gender> + <communityrole>developer</communityrole> + <homepage>opendesktop.org</homepage> + <company>opendesktop.org</company> + <avatarpic>http://www.KDE-Look.org/CONTENT/user-pics/0/Frank.jpg</avatarpic> + <avatarpicfound>1</avatarpicfound> + <bigavatarpic>http://www.KDE-Look.org/CONTENT/user-bigpics/0/Frank.jpg</bigavatarpic> + <bigavatarpicfound>1</bigavatarpicfound> + <birthday>1973-07-25</birthday> + <jobstatus>working</jobstatus> + <city>Stuttgart</city> + <country>Germany</country> + <latitude></latitude> + <longitude></longitude> + <ircnick>karli</ircnick> + <ircchannels>kde-dev, plasma</ircchannels> + <irclink>irc://irc.freenode.org/kde-dev</irclink> + <irclink>irc://irc.freenode.org/plasma</irclink> + <likes>lot of stuff</likes> + <dontlikes>nothing</dontlikes> + <interests>travel</interests> + <languages>english</languages> + <programminglanguages>php, c++</programminglanguages> + <favouritequote></favouritequote> + <favouritemusic>nin</favouritemusic> + <favouritetvshows></favouritetvshows> + <favouritemovies>fightclub</favouritemovies> + <favouritebooks></favouritebooks> + <favouritegames>ut3</favouritegames> + <description></description> + <profilepage>http://www.KDE-Look.org/usermanager/search.php?username=Frank</profilepage> + </person> + </data> + </ocs> + +#### edit + +Update the latitude, longitude, city and country of myself. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. + +* Syntax: /v1/person/self +* Method: POST +* POST Arguments: latitude - The latitude of myself +* POST Arguments: longitude - The longitude of myself +* POST Arguments: city - Your city +* POST Arguments: country - The 2 letter ISO country code +* Statuscodes: + * 100 - successfull + * 101 - no parameters to update found +Example: POST <http://frank:password@api.opendesktop.org/v1/person/self> postdata: longitude="1.23" latitude="3.45" Updated my position to 1.23 and 3.45 Example: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + </meta> + </ocs> + +#### balance + +Get the account balance of a user. + +* Syntax: /v1/person/balance +* HTTP Method: GET +* Result: status xml +* Example: <http://api.opendesktop.org/v1/person/balance> +Example: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + </meta> + <data> + <person details="balance"> + <currency>USD</currency> + <balance>1.49</balance> + </person> + </data> + </ocs> + +#### get attributes + +Gets the list of extended attributes of a person. You can store several attributes to you person record which are publicly readable for everybody. The attributes are key/value pairs with an "app" parameter as namespace. Store data which is only interesting for your application with your application name as a app namespace. If the data is of general interest use "global" as app parameter. The parameter "app" and "key" are optional in the url. So you access all the attributes from the person or only the attributes from a specific application or the only the value of one specific key. You can search for users which have specific attributes with the search method. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. + +* syntax: /v1/person/attributes/"personid"/"app"/"key" +* HTTP method: GET +* Arguments: personid - The person from which you want to get the attributes. +* Arguments: app - The application from which you want to get the attributes. This parameter is optional. +* Arguments: key - The key of the attribute you want to get. This parameter is optional. +* Statuscodes: + * 100 - successfull +Example: GET <http://frank:password@api.opendesktop.org/v1/person/attributes/fregl/parley/language> Get the value of the key language of the application parley from the user fregl. Example: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + <totalitems>1</totalitems> + </meta> + <data> + <attribute> + <app>parley</app> + <key>language</key> + <value>english, german</value> + <lastmodified>2007-11-01T22:45:20+01:00</lastmodified> + </attribute> + </data> + </ocs> + +#### set attribute + +Set a attribute of a person. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. + +* syntax: /v1/person/setattribute/"app"/"key" +* HTTP method: POST +* Arguments: app - The application where you want to store this attribute at. +* Arguments: key - The key of the attribute. +* POST arguments: value - The value of the attribute. +* Statuscodes: + * 100 - successfull +Example: POST <http://frank:password@api.opendesktop.org/v1/person/setattribute/parley/language> postdata: value="italian" Set the value of the key "language" of the application "parley" to "italian". Example: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + </meta> + </ocs> + +#### delete attribute + +Delete a attribute of a person. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. + +* syntax: /v1/person/deleteattribute/"app"/"key" +* HTTP method: POST +* Arguments: app - The application where the key is stored. +* Arguments: key - The key of the attribute. +* Statuscodes: + * 100 - successfull +Example: POST <http://frank:password@api.opendesktop.org/v1/person/deleteattribute/parley/language> Delete the attribute with the key "language" and the application "parley". Example: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + </meta> + </ocs> + +<a name="FRIEND"></a> +### FRIEND + +The FRIEND service is for handling friendship relations between people. you can get the friends of a specific person or from yourself. You can invite other persons as a friend and manage the invitations. + + +#### get + +Gets the list of friends from a person. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. + +* syntax: /v1/friend/data/"personid" +* HTTP method: GET +* Arguments: personid - The person from which you want to get the friendslist. +* URL Arguments: page - The page of the friendslist. The size of a page is controlled by the pagesize argument. The first page is 0, the second is 1, ... +* URL Arguments: pagesize - The amount of entries per page. +* Statuscodes: + * 100 - successfull + * 101 - data is private + * 102 - user not found +Example: GET <http://frank:password@api.opendesktop.org/v1/friend/data/foobar?pagesize=10&page=1> Gets the second page of friends of the person "foobar" Example: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + <totalitems>3</totalitems> + <itemsperpage>10</itemsperpage> + </meta> + <data> + <user details="id"> + <personid>cornelius</personid> + </user> + <user details="id"> + <personid>dave</personid> + </user> + <user details="id"> + <personid>fen</personid> + </user> + </data> + </ocs> + +#### receivedinvitations + +Gets the list of friendship invitations. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. + +* syntax: /v1/friend/receivedinvitations +* HTTP method: GET +* URL Arguments: page - The page of the list. The size of a page is controlled by the pagesize argument. The first page is 0, the second is 1, ... +* URL Arguments: pagesize - The amount of entries per page. +* Statuscodes: + * 100 - successfull +Example: GET <http://frank:password@api.opendesktop.org/v1/friend/receivedinvitations?page=1> Gets the second page of my received invitations. Example: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + <totalitems>1</totalitems> + <itemsperpage>10</itemsperpage> + </meta> + <data> + <user details="id"> + <personid>testy</personid> + </user> + </data> + </ocs> + +#### sentinvitations + +Gets the list of sent friendship invitations. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. + +* syntax: /v1/friend/sentinvitations +* HTTP method: GET +* URL Arguments: page - The page of the list. The size of a page is controlled by the pagesize argument. The first page is 0, the second is 1, ... +* URL Arguments: pagesize - The amount of entries per page. +* Statuscodes: + * 100 - successfull +Example: GET <http://frank:password@api.opendesktop.org/v1/friend/sentinvitations?page=1> Gets the second page of my sent invitations. Example: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + <totalitems>1</totalitems> + <itemsperpage>10</itemsperpage> + </meta> + <data> + <user details="id"> + <personid>testy</personid> + </user> + </data> + </ocs> + +#### invite + +Invite a person to become a friend. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. + +* Syntax: /v1/friend/invite/"personid" +* Method: POST +* Arguments: personid - The person you want to invite as a friend. +* POST arguments: message - The message you want to send to the person together with your invitation. +* Statuscodes: + * 100 - successfull + * 101 - message must not be empty + * 102 - you can´t invite yourself + * 103 - user not found +Example: POST <http://frank:password@api.opendesktop.org/v1/friend/invite/foobar/> postdata: message="hi. how are you?" Invites the person "foobar" and send him a message "hi. how are you?" Example: + + <?xml version="1.0"?> + <ocs> + <status>ok</status> + <message></message> + </ocs> + +#### approve + +Approve a friendship request. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. + +* Syntax: /v1/friend/approve/"personid" +* Method: POST +* Arguments: personid - The person you want to approve as a friend. +* Statuscodes: + * 100 - successful +Example: POST <http://frank:password@api.opendesktop.org/v1/friend/approve/foobar/> Approve the invitation from the user "foobar" Example: + + <?xml version="1.0"?> + <ocs> + <status>ok</status> + <message></message> + </ocs> + +#### decline + +Decline a friendship request. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. + +* Syntax: /v1/friend/decline/"personid" +* Method: POST +* Arguments: personid - The person you want to decline. +* Statuscodes: + * 100 - successful +Example: POST <http://frank:password@api.opendesktop.org/v1/friend/decline/foobar/> Decline the invitation from the user "foobar" Example: + + <?xml version="1.0"?> + <ocs> + <status>ok</status> + <message></message> + </ocs> + +#### cancel + +Cancel a friendship with a user. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. + +* Syntax: /v1/friend/cancel/"personid" +* Method: POST +* Arguments: personid - The person you want to cancel the friendship with. +* Statuscodes: + * 100 - successful +Example: POST <http://frank:password@api.opendesktop.org/v1/friend/cancel/foobar/> Cancel the friendship with the user "foobar" Example: + + <?xml version="1.0"?> + <ocs> + <status>ok</status> + <message></message> + </ocs> + +<a name="MESSAGE"></a> +### MESSAGE + +The MESSAGE services can be used to send and receive messages. this is always possible even if you don't know the real email address of the other person. The messages are stored in different folders. if you want to access a special folder like for example the inbox you should search in the folders list for a folder with the type "inbox" to get the right folder id. + + +#### folders + +Gets a list of the availabe message folders. You need the ids if you want to access the folders via messagelist. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. + +* Syntax: /v1/message +* HTTP method: GET +* Result: messagefolder xml +* Statuscodes: + * 100 - successfull +* Example: <http://frank:password@api.opendesktop.org/v1/message> +Example: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + <totalitems>4</totalitems> + </meta> + <data> + <folder> + <id>0</id> + <name>inbox</name> + <messagecount>27</messagecount> + <type>inbox</type> + </folder> + <folder> + <id>1</id> + <name>send</name> + <messagecount>9</messagecount> + <type>send</type> + </folder> + <folder> + <id>2</id> + <name>trash</name> + <messagecount>0</messagecount> + <type>trash</type> + </folder> + <folder> + <id>3</id> + <name>archive</name> + <messagecount>0</messagecount> + <type></type> + </folder> + </data> + </ocs> + +#### list + +Gets the list of messages from a specific folder. the messages are sorted in chronological order. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. + +* Syntax: /v1/message/"folder" +* HTTP method: GET +* Arguments: folder - The ID of the folder you want to get. Use the folders method to get the list of folders. +* URL Arguments: status - Show only messages with the specified status. Possible values are: 0-unread, 1-read, 2-replyed +* URL Arguments: page - The content page. The amount of entries can be controlled by the pagesize argument. The first page is 0, the second is 1, ... +* URL Arguments: pagesize - The amount of entries per page. +* Result: messagelist xml + * Status: 0 - unread + * Status: 1 - read + * Status: 2 - answered +* Statuscodes: + * 100 - successfull +Example: GET <http://frank:password@api.opendesktop.org/v1/message/1?page=2&pagesize=10> Gets the third page of messages from the folder with the id 1 of person "frank". firstname, lastname and profilepage are from the sender of the message. Example: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + <totalitems>2</totalitems> + <itemsperpage>10</itemsperpage> + </meta> + <data> + <message details="full"> + <id>8490</id> + <messagefrom>testy</messagefrom> + <firstname>Frank</firstname> + <lastname>Karlitschek</lastname> + <profilepage>http://www.opendesktop.org/usermanager/search.php?username=Frank</profilepage> + <messageto>Frank</messageto> + <senddate>2008-08-10T16:03:59+02:00</senddate> + <status>1</status> + <statustext></statustext> + <subject>test message</subject> + <body>Sorry for bothering but did you ...</body> + </message> + <message details="full"> + <id>8491</id> + <messagefrom>testy1</messagefrom> + <firstname>Testy</firstname> + <lastname>TTT</lastname> + <profilepage>http://www.opendesktop.org/usermanager/search.php?username=testy1</profilepage> + <messageto>Frank1</messageto> + <senddate>2008-08-12T16:03:59+02:00</senddate> + <status>1</status> + <statustext></statustext> + <subject>test message</subject> + <body>Testy 2 ...</body> + </message> + </data> + </ocs> + +#### get + +Get a message. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. the message will be marked as "read" if you access it with this method. + +* Syntax: /v1/message/"folderid"/"messageid" +* HTTP method: GET +* Arguments: folderid - The ID of the folder. Use the folders method to get the list of folders. +* Arguments: messageid - The ID of the message you want to get. +* Result: message xml + * Status: 0 - unread + * Status: 1 - read + * Status: 2 - answered +* Statuscodes: + * 100 - successful + * 101 - message not found +Example: GET <http://frank:password@api.opendesktop.org/v1/message/1/42> Get the message with the id 42 in the folder 1. firstname, lastname and profilepage are from the sender of the message. Example: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + </meta> + <data> + <message details="full"> + <id>8490</id> + <messagefrom>testy</messagefrom> + <firstname>Test</firstname> + <lastname>TTT</lastname> + <profilepage>http://www.opendesktop.org/usermanager/search.php?username=testy</profilepage> + <messageto>Frank</messageto> + <senddate>2008-08-10T16:03:59+02:00</senddate> + <status>1</status> + <statustext></statustext> + <subject>test message</subject> + <body>Sorry for bothering but did you ...</body> + </message> + </data> + </ocs> + +#### send + +Send a message. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. + +* Syntax: /v1/message/"sendfolder" +* HTTP method: POST +* POST Arguments: to - The receiver of the message. +* POST Arguments: subject - The subject of the message. +* POST Arguments: message - The text you want to send. +* Result: status xml +* Statuscodes: + * 100 - successfull + * 101 - user not found + * 102 - subject or message not found + * 103 - you can not send a message to yourself. +* Example: POST <http://frank:password@api.opendesktop.org/v1/message/2> postdata message="coding is fun" subject="hello" to=frank +* Send a message to "frank" with the subject "hello" and a messagebody "coding is fun" +Example: + + <?xml version="1.0"?> + <ocs> + <status>ok</status> + <message></message> + </ocs> + +<a name="ACTIVITY"></a> +### ACTIVITY + +You can use the ACTIVITY services to see what is going on in your friends network. For example who visited you homepage, wo has send you a message and who uploaded a new content to the website. You can also post a microblogging message which is vivible on you profile page and in the activities of your friends. The entries are sorted by timestamp. + + +#### get + +Gets the list of activities. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. + +* Syntax: /v1/activity +* HTTP method: GET +* URL Arguments: page - The activities page. The amount of entris per page is controlled by the pagesize argument. The first page is 0, the second is 1, ... +* URL Arguments: pagesize - The amount of entries per page. +* Result: activities xml +* type categories: + * 1 - status message + * 2 - new friend + * 3 - new content upload + * 4 - profile update + * 5 - profile photo update + * 6 - content edit + * 7 - new message + * 8 - homepage visit + * 9 - become fan + * 10 - no longer fan + * 11 - group created + * 12 - group joined + * 13 - group left + * 14 - event created + * 15 - attending the event + * 16 - no longer attending the event + * 17 - created the job offer + * 18 - edited the job offer + * 19 - has registered (new user) +* Statuscodes: + * 100 - successfull +* Example: GET <http://frank:password@api.opendesktop.org/v1/activity?page=3&pagesize=10> +* Gets the third page of the activities of person "frank" +Example: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + <totalitems>2</totalitems> + <itemsperpage>10</itemsperpage> + </meta> + <data> + <activity details="full"> + <id>42</id> + <personid>testy2</personid> + <firstname>Test</firstname> + <lastname>Te</lastname> + <profilepage>/usermanager/search.php?username=testy2</profilepage> + <avatarpic>http://www.opendesktop.org/usermanager/nopic.png</avatarpic> + <timestamp>2008-08-01T20:30:19+02:00</timestamp> + <type>6</type> + <message>testy2 has updated: "Extract And Compress"</message> + <link>http://www.KDE-Look.org/content/show.php?content=84206</link> + </activity> + <activity details="full"> + <id>43</id> + <personid>foobar2</personid> + <firstname>Foo</firstname> + <lastname>Bar</lastname> + <profilepage>/usermanager/search.php?username=foobar2</profilepage> + <avatarpic>http://www.opendesktop.org/usermanager/nopic.png</avatarpic> + <timestamp>2008-08-02T19:38:10+02:00</timestamp> + <type>6</type> + <message>foobar2 has updated: "Arezzo"</message> + <link>http://www.KDE-Look.org/content/show.php?content=84403</link> + </activity> + </data> + </ocs> + +#### put + +Updates your activities. This is microblogging like Twitter. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. + +* POST: /v1/activity +* POST Arguments: message - The text you want to post. +* Result: status xml +* Example: POST <http://frank:password@api.opendesktop.org/v1/activity> postdata message="coding is fun" +* Posts the text "coding is fun" to franks hompage and the activities of franks friends. +* Statuscodes: + * 100 - successful + * 101 - empty message + * 102 - user not found +Example: + + <?xml version="1.0"?> + <ocs> + <status>ok</status> + <message></message> + </ocs> + +<a name="CONTENT"></a> +### CONTENT + + +#### categories + +Get a list of all available content categories. + +* Syntax: /v1/content/categories +* HTTP Method: GET +* Result: categories xml +* Statuscodes: + * 100 - successful + * 200 - too many API requests in the last 15 minutes from your IP address. please try again later. +* Example: GET <http://frank:password@api.opendesktop.org/v1/content/categories> +Example: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + <totalitems>4</totalitems> + </meta> + <data> + <category> + <id>1</id> + <name>KDE Wallpaper 640x480</name> + </category> + <category> + <id>2</id> + <name>KDE Wallpaper 800x600</name> + </category> + <category> + <id>3</id> + <name>KDE Wallpaper 1024x768</name> + </category> + <category> + <id>4</id> + <name>KDE Wallpaper 1280x1024</name> + </category> + </data> + </ocs> + +#### licenses + +Get a list of all possible licenses. The IDs can be alphanumeric. The IDs should follow "liblicense" if possible. + +* Syntax: /v1/content/licenses +* HTTP Method: GET +* Result: categories xml +* Statuscodes: + * 100 - successful + * 200 - too many API requests in the last 15 minutes from your IP address. please try again later. +* Example: GET <http://frank:password@api.opendesktop.org/v1/content/licenses> +Example: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + <totalitems>17</totalitems> + </meta> + <data> + <license> + <id>1000</id> + <name></name> + <link></link> + </license> + <license> + <id>3</id> + <name>Artistic 2.0</name> + <link>http://dev.perl.org/perl6/rfc/346.html</link> + </license> + <license> + <id>6</id> + <name>BSD</name> + <link>http://www.opensource.org/licenses/bsd-license.php</link> + </license> + </data> + </ocs> + +#### distributions + +Get a list of all possible distributions. The IDs can be alphanumeric. + +* Syntax: /v1/content/distributions +* HTTP Method: GET +* Result: categories xml +* Statuscodes: + * 100 - successful + * 200 - too many API requests in the last 15 minutes from your IP address. please try again later. +* Example: GET <http://frank:password@api.opendesktop.org/v1/content/distributions> +Example: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + <totalitems>23</totalitems> + </meta> + <data> + <distribution> + <id>0</id> + <name></name> + </distribution> + <distribution> + <id>2200</id> + <name>Arch</name> + </distribution> + <distribution> + <id>2000</id> + <name>Ark</name> + </distribution> + <distribution> + <id>1100</id> + <name>Debian</name> + </distribution> + </data> + </ocs> + +#### dependencies + +Get a list of all possible dependencies. + +* Syntax: /v1/content/dependencies +* HTTP Method: GET +* Result: categories xml +* Statuscodes: + * 100 - successful + * 200 - too many API requests in the last 15 minutes from your IP address. please try again later. +* Example: GET <http://frank:password@api.opendesktop.org/v1/content/dependencies> +Example: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + <totalitems>36</totalitems> + </meta> + <data> + <dependtypes> + <id>0</id> + <name></name> + </dependtypes> + <dependtypes> + <id>30</id> + <name>GNOME 1.x</name> + </dependtypes> + <dependtypes> + <id>31</id> + <name>GNOME 2.x</name> + </dependtypes> + <dependtypes> + <id>20</id> + <name>GTK 1.x</name> + </dependtypes> + </data> + </ocs> + +#### homepagetypes + +Get a list of all possible homepagetypes. + +* Syntax: /v1/content/homepages +* HTTP Method: GET +* Result: categories xml +* Statuscodes: + * 100 - successful + * 200 - too many API requests in the last 15 minutes from your IP address. please try again later. +* Example: GET <http://frank:password@api.opendesktop.org/v1/content/homepages> +Example: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + <totalitems>14</totalitems> + </meta> + <data> + <homepagetypes> + <id>0</id> + <name>&nbsp;</name> + </homepagetypes> + <homepagetypes> + <id>10</id> + <name>Blog</name> + </homepagetypes> + <homepagetypes> + <id>20</id> + <name>Facebook</name> + </homepagetypes> + </data> + </ocs> + +#### list + +Gets a list of a specific set of contents. + +* Syntax: /v1/content/data/ +* HTTP Method: GET +* URL Arguments: categories - Ids of the requested category ids seperated by "x". +* URL Arguments: search - the part of the name of the item you want to find. +* URL Arguments: user - show only contents from one specific user. +* URL Arguments: external - if set external=off only contents which are hosted on the same server are shown +* URL Arguments: distribution - show only content which is supported by this distributions. the parameter is a comma seperated list of ids as returned by the "distribution" method +* URL Arguments: license - show only content which is available under a specific license. the parameter is a comma seperated list of ids as returned by the "license" method +* URL Arguments: sortmode - The sortmode of the list. Possible values are: "new" - newest first , "alpha" - alphabetical, "high" - highest rated, "down" - most downloads +* URL Arguments: page - The content page. You can control the size of a page with the pagesize argument. The first page is 0, the second is 1, ... +* URL Arguments: pagesize - The amount of entries per page. +* Result: content xml +* Statuscodes: + * 100 - successful + * 200 - too many API requests in the last 15 minutes from your IP address. please try again later. +* Example: <http://frank:password@api.opendesktop.org/v1/content/data?categories=1x2x3x4&search=foo&sortmode=new&page=1> Gets the second page of the list of the newest contents from categories 1,2,3 and 4 with the string foo in the name. +Example: + + <?xml version="1.0"?> + + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + <totalitems>2</totalitems> + <itemsperpage>10</itemsperpage> + </meta> + <data> + <content details="summary"> + <id>1420</id> + <name>name</name> + <version>11122</version> + <changed>2007-11-24T22:41:08+01:00</changed> + <created>2007-11-01T22:28:24+01:00</created> + <typeid>6</typeid> + <typename>KDE Wallpaper (other)</typename> + <language></language> + <personid>Frank</personid> + <profilepage>http://www.opendesktop.org/usermanager/search.php?username=Frank</profilepage> + <downloads>5</downloads> + <score>50</score> + <comments>0</comments> + <preview1>http://www.KDE-Look.org/content/preview.php?preview=1&id=1420&file1=1420-1.png&file2=1420-2.png&file3=&name=nameeee</preview1> + <previewpic1>http://www.KDE-Look.org/CONTENT/content-pre1/1420-1.png</previewpic1> + </content> + <content details="summary"> + <id>1422</id> + <name>testy2</name> + <version>11</version> + <summary>this is a short summary</summary> + <changed>2007-11-01T22:45:20+01:00</changed> + <created>2007-11-01T22:43:21+01:00</created> + <typeid>7</typeid> + <typename>KDE Wallpaper (SVG)</typename> + <language></language> + <personid>Frank</personid> + <downloads>8</downloads> + <score>50</score> + <comments>0</comments> + <preview1>http://www.KDE-Look.org/content/preview.php?preview=1&id=1422&file1=1422-1.jpg&file2=1422-2.png&file3=1422-3.png&name=vdfdds222</preview1> + <previewpic1>http://www.KDE-Look.org/CONTENT/content-pre1/1422-1.jpg</previewpic1> + <icon width="16" height="16">http://www.KDE-Look.org/img/icon1.png</icon> + <icon width="32" height="32">http://www.KDE-Look.org/img/icon2.png</icon> + <icon width="64" height="64">http://www.KDE-Look.org/img/icon2.png</icon> + <smallpreviewpic1>http://www.KDE-Look.org/CONTENT/content-m1/m1421-1.png</smallpreviewpic1> + <downloadway1>1</downloadway1> + <downloadtype1>Fedora</downloadtype1> + <downloadprice1>2.99</downloadprice1> + <downloadlink1>http://www.opendesktop.org/content/buy.php?content=1422&id=1</downloadlink1> + <downloadname1>pay item 1</downloadname1> + <downloadsize1>2</downloadsize1> + <downloadgpgsignature1></downloadgpgsignature1> + <downloadgpgfingerprint1></downloadgpgfingerprint1> + <downloadtype2>Ubuntu </downloadtype2> + <downloadprice2>0</downloadprice2> + <downloadlink2>http://www.opendesktop.org/content/download.php?content=1422&id=2</downloadlink2> + <downloadname2>free download</downloadname2> + <downloadgpgsignature2></downloadgpgsignature2> + <downloadgpgfingerprint2></downloadgpgfingerprint2> + <downloadtype3>SUSE </downloadtype3> + <downloadprice3>0</downloadprice3> + <downloadlink3>http://www.opendesktop.org/content/download.php?content=1422&id=3</downloadlink3> + <downloadname3>free item</downloadname3> + <downloadgpgsignature3></downloadgpgsignature3> + <downloadgpgfingerprint3></downloadgpgfingerprint3> + <detailpage>http://www.KDE-Look.org/content/show.php?content=100</detailpage> + </content> + </data> + </ocs> + +#### get + +Read content data of one specific content. + +* Syntax: /v1/content/data/"contentid"/ +* HTTP Method: GET +* Arguments: contentid - Id of a content +* Result: content xml +* Statuscodes: + * 100 - successfull + * 101 - content not found + * 200 - too many API requests in the last 15 minutes from your IP address. please try again later. +* Example: <http://frank:password@api.opendesktop.org/v1/content/data/12345> +Example: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + </meta> + <data> + <content details="full"> + <id>100</id> + <name>GradE8</name> + <version></version> + <typeid>10</typeid> + <typename>Theme/Style for KDE 2.1</typename> + <language></language> + <personid>Hans</personid> + <created>2001-09-28T18:45:40+02:00</created> + <changed>2001-09-28T18:45:40+02:00</changed> + <downloads>2</downloads> + <score>67</score> + <description>his is my first KDE 2.0 theme. It isn't the final version, I must add some icons etc...</description> + <summary>this is a short summary</summary> + <changelog></changelog> + <feedbackurl>http://openDesktop.org/feedback</feedbackurl> + <homepage>http://en.wikipedia.org/foo111</homepage> + <homepagetype>Wikipedia</homepagetype> + <homepage2></homepage2> + <homepagetype2></homepagetype2> + <homepage3>http://myhomepage.com</homepage3> + <homepagetype3>Blog</homepagetype3> + <homepage4></homepage4> + <homepagetype4></homepagetype4> + <homepage5></homepage5> + <homepagetype5></homepagetype5> + <homepage6></homepage6> + <homepagetype6></homepagetype6> + <homepage7></homepage7> + <homepagetype7></homepagetype7> + <homepage8></homepage8> + <homepagetype8></homepagetype8> + <homepage9></homepage9> + <homepagetype9></homepagetype9> + <homepage10></homepage10> + <homepagetype10></homepagetype10> + <donationpage>http://www.opendesktop.org/content/donation.php?content=123</donationpage> + <comments>0</comments> + <commentspage>http://www.opendesktop.org/content/show.php?content=100</commentspage> + <fans>22</fans> + <fanspage>http://www.opendesktop.org/content/show.php?action=fan&content=100</fanspage> + <knowledgebaseentries>7</knowledgebaseentries> + <knowledgebasepage>http://www.opendesktop.org/content/show.php?action=knowledgebase&content=100</knowledgebasepage> + <depend></depend> + <preview1>http://www.KDE-Look.org/content/preview.php?preview=1&id=100&file1=100-1.jpg&file2=&file3=&name=GradE8</preview1> + <preview2></preview2> + <preview3></preview3> + <previewpic1>http://www.KDE-Look.org/CONTENT/content-pre1/100-1.jpg</previewpic1> + <previewpic2></previewpic2> + <previewpic3></previewpic3> + <smallpreviewpic1>http://www.KDE-Look.org/CONTENT/content-m1/m100-1.png</smallpreviewpic1> + <smallpreviewpic2></smallpreviewpic2> + <smallpreviewpic3></smallpreviewpic3> + <icon width="16" height="16">http://www.KDE-Look.org/img/icon1.png</icon> + <icon width="32" height="32">http://www.KDE-Look.org/img/icon2.png</icon> + <icon width="64" height="64">http://www.KDE-Look.org/img/icon2.png</icon> + <video>http://www.KDE-Look.org/video/video1.mpg</video> + <video>http://www.KDE-Look.org/video/video2.mpg</video> + <video>http://www.KDE-Look.org/video/video3.mpg</video> + <detailpage>http://www.KDE-Look.org/content/show.php?content=100</detailpage> + <downloadway1>1</downloadway1> + <downloadtype1>Fedora </downloadtype1> + <downloadprice1>0</downloadprice1> + <downloadlink1>http://www.opendesktop.org/content/download.php?content=1423&id=2</downloadlink1> + <downloadname1>gdfgd22</downloadname1> + <downloadsize1>2</downloadsize1> + <downloadgpgfingerprint1>6AD9 150F D8CC 941B 4541 2DCC 68B7 AB89 5754 8D2D</downloadgpgfingerprint1> + <downloadgpgsignature1>iEYEABECAAYFAkxT52oACgkQMNASEGDVgdegPAbDSMHn/xDQCfSplogMr9x0G0ZNqMUAn3WLVmXADVzWdEToTJ8B5wpdm3zb=A6Dy</downloadgpgsignature1> + <downloadpackagename1>packname</downloadpackagename1> + <downloadrepository1>repo</downloadrepository1> + <downloadtype2>Fedora </downloadtype2> + <downloadprice2>2.99</downloadprice2> + <downloadlink2>http://www.opendesktop.org/content/buy.php?content=1423&id=1</downloadlink2> + <downloadname2>gdgg22</downloadname2> + <downloadgpgfingerprint2>6AD9 150F D8CC 941B 4541 2DCC 68B7 AB89 5754 8D2D</downloadgpgfingerprint2> + <downloadgpgsignature2>iEYEABECAAYFAkxT52oACgkQMNASEGDVgdegPAbDSMHn/xDQCfSplogMr9x0G0ZNqMUAn3WLVmXADVzWdEToTJ8B5wpdm3zb=A6Dy</downloadgpgsignature2> + <downloadpackagename2>packname</downloadpackagename2> + <downloadrepository2>repo</downloadrepository2> + </content> + </data> + </ocs> + +#### download + +Download or buy one specific content item. links to the package and links to repositories are supported. You get the dowloadlink or the packagename/packagerepository comination in the XML. + +* Syntax: /v1/content/download/"contentid"/"itemid" +* HTTP Method: GET +* Arguments: contentid - Id of a content +* Arguments: itemid - Id of a content +* Result: status xml +* Statuscodes: + * 100 - successfull + * 101 - content not found + * 102 - payment failed + * 103 - content item not found + * 104 - please login to buy this content + * 200 - too many API requests in the last 15 minutes from your IP address. please try again later. +* Example: <http://api.opendesktop.org/v1/content/download/12345/2> +Example: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + </meta> + <data> + <content details="download"> + <downloadway>0</downloadway> + <downloadlink>http://www......tar.gz</downloadlink> + <mimetype>image/jpeg</mimetype> + <packagename>glibc-2.10.1-10.4.i686.rpm</packagename> + <packagerepository>http://download.opensuse.org/distribution/11.2/repo/oss/</packagerepository> + <gpgfingerprint>6AD9 150F D8CC 941B 4541 2DCC 68B7 AB89 5754 8D2D</gpgfingerprint> + <gpgsignature>iEYEABECAAYFAkxT52oACgkQMNASEGDVgdegPAbDSMHn/xDQCfSplogMr9x0G0ZNqMUAn3WLVmXADVzWdEToTJ8B5wpdm3zb=A6Dy</gpgsignature> + </content> + </data> + </ocs> + +#### vote + +Vote for one specific content. + +* Syntax: /v1/content/vote/"contentid" +* HTTP Method: POST +* Arguments: contentid - Id of a content +* POST Arguments: vote - The vote. "good" or "bad" (deprecated) or an integer between 0 to 100. 0 equals bad and 100 equals good +* Result: status xml +* Statuscodes: + * 100 - successful + * 101 - content not found + * 200 - too many API requests in the last 15 minutes from your IP address. please try again later. +* Example: <http://api.opendesktop.org/v1/content/vote/12345> with the POST variable vote=good +Example: + + <?xml version="1.0"?> + <ocs> + <status>ok</status> + <message></message> + </ocs> + +#### add + +Add a new content entry: + +* Syntax: v1/content/add +* HTTP Method: POST +* POST Arguments: name - the name of the entry +* POST Arguments: type - the type or category of the entry. call the categories method to get a list of all categories. +* POST Arguments: depend - the dependency of this entry. get the possible values by calling /v1/content/dependencies +* POST Arguments: downloadtyp1 - the type of the first download. possible values are: 0 - use the uploaded file, 1 - use the downloadlink1, 2 - use downloadpackagename and downloadrepository +* POST Arguments: downloadname1 - the name of the 1. downloadlink +* POST Arguments: downloadlink1 - the url of the downloadlink +* POST Arguments: downloaddistributiontype1 - the type of the distribution for the download. call /v1/content/distributions for a list of possible options +* POST Arguments: downloadbuy1 - is this download free or paid. 0 - free, 1 - paid. +* POST Arguments: downloadbuyreason1 - the description why is content is not for free. +* POST Arguments: downloadbuyprice1 - the price of this content in USD. +* POST Arguments: downloadgpgfingerprint1 - the gpg fingerprint of this download +* POST Arguments: downloadgpgsignature1 - the gpg signature of this download +* POST Arguments: downloadpackagename1 - the name of the package in the repository +* POST Arguments: downloadpackagerepository1 - the repository where the package is located +* POST Arguments: downloadname2 - the name of the downloadlink +* POST Arguments: downloadlink2 - the url of the downloadlink +* POST Arguments: downloaddistributiontype2 - the type of the distribution for the download. the types are described at downloaddistributiontype1. +* POST Arguments: downloadbuy2 - is this download free or paid. 0 - free, 1 - paid. +* POST Arguments: downloadbuyreason2 - the description why is content is not for free. +* POST Arguments: downloadbuyprice2 - the price of this content in USD. +* POST Arguments: downloadgpgfingerprint2 - the gpg fingerprint of this download +* POST Arguments: downloadgpgsignature2 - the gpg signature of this download +* POST Arguments: downloadpackagename2 - the name of the package in the repository +* POST Arguments: downloadpackagerepository2 - the repository where the package is located +* POST Arguments: downloadname3 - the name of the downloadlink +* POST Arguments: downloadlink3 - the url of the downloadlink +* POST Arguments: downloaddistributiontype3 - the type of the distribution for the download. the types are described at downloaddistributiontype1. +* POST Arguments: downloadbuy3 - is this download free or paid. 0 - free, 1 - paid. +* POST Arguments: downloadbuyreason3 - the description why is content is not for free. +* POST Arguments: downloadbuyprice3 - the price of this content in USD. +* POST Arguments: downloadgpgfingerprint3 - the gpg fingerprint of this download +* POST Arguments: downloadgpgsignature3 - the gpg signature of this download +* POST Arguments: downloadpackagename3 - the name of the package in the repository +* POST Arguments: downloadpackagerepository3 - the repository where the package is located +* POST Arguments: downloadname4 - the name of the downloadlink +* POST Arguments: downloadlink4 - the url of the downloadlink +* POST Arguments: downloaddistributiontype4 - the type of the distribution for the download. the types are described at downloaddistributiontype1. +* POST Arguments: downloadbuy4 - is this download free or paid. 0 - free, 1 - paid. +* POST Arguments: downloadbuyreason4 - the description why is content is not for free. +* POST Arguments: downloadbuyprice4 - the price of this content in USD. +* POST Arguments: downloadgpgfingerprint4 - the gpg fingerprint of this download +* POST Arguments: downloadgpgsignature4 - the gpg signature of this download +* POST Arguments: downloadpackagename4 - the name of the package in the repository +* POST Arguments: downloadpackagerepository4 - the repository where the package is located +* POST Arguments: downloadname5 - the name of the downloadlink +* POST Arguments: downloadlink5 - the url of the downloadlink +* POST Arguments: downloaddistributiontype5 - the type of the distribution for the download. the types are described at downloaddistributiontype1. +* POST Arguments: downloadbuy5 - is this download free or paid. 0 - free, 1 - paid. +* POST Arguments: downloadbuyreason5 - the description why is content is not for free. +* POST Arguments: downloadbuyprice5 - the price of this content in USD. +* POST Arguments: downloadgpgfingerprint5 - the gpg fingerprint of this download +* POST Arguments: downloadgpgsignature5 - the gpg signature of this download +* POST Arguments: downloadpackagename5 - the name of the package in the repository +* POST Arguments: downloadpackagerepository5 - the repository where the package is located +* POST Arguments: downloadname6 - the name of the downloadlink +* POST Arguments: downloadlink6 - the url of the downloadlink +* POST Arguments: downloaddistributiontype6 - the type of the distribution for the download. the types are described at downloaddistributiontype1. +* POST Arguments: downloadbuy6 - is this download free or paid. 0 - free, 1 - paid. +* POST Arguments: downloadbuyreason6 - the description why is content is not for free. +* POST Arguments: downloadbuyprice6 - the price of this content in USD. +* POST Arguments: downloadgpgfingerprint6 - the gpg fingerprint of this download +* POST Arguments: downloadgpgsignature5 - the gpg signature of this download +* POST Arguments: downloadpackagename6 - the name of the package in the repository +* POST Arguments: downloadpackagerepository6 - the repository where the package is located +* POST Arguments: downloadname7 - the name of the downloadlink +* POST Arguments: downloadlink7 - the url of the downloadlink +* POST Arguments: downloaddistributiontype7 - the type of the distribution for the download. the types are described at downloaddistributiontype1. +* POST Arguments: downloadbuy7 - is this download free or paid. 0 - free, 1 - paid. +* POST Arguments: downloadbuyreason7 - the description why is content is not for free. +* POST Arguments: downloadbuyprice7 - the price of this content in USD. +* POST Arguments: downloadgpgfingerprint7 - the gpg fingerprint of this download +* POST Arguments: downloadgpgsignature7 - the gpg signature of this download +* POST Arguments: downloadpackagename7 - the name of the package in the repository +* POST Arguments: downloadpackagerepository7 - the repository where the package is located +* POST Arguments: downloadname8 - the name of the downloadlink +* POST Arguments: downloadlink8 - the url of the downloadlink +* POST Arguments: downloaddistributiontype8 - the type of the distribution for the download. the types are described at downloaddistributiontype1. +* POST Arguments: downloadbuy8 - is this download free or paid. 0 - free, 1 - paid. +* POST Arguments: downloadbuyreason8 - the description why is content is not for free. +* POST Arguments: downloadbuyprice8 - the price of this content in USD. +* POST Arguments: downloadgpgfingerprint8 - the gpg fingerprint of this download +* POST Arguments: downloadgpgsignature8 - the gpg signature of this download +* POST Arguments: downloadpackagename8 - the name of the package in the repository +* POST Arguments: downloadpackagerepository8 - the repository where the package is located +* POST Arguments: downloadname9 - the name of the downloadlink +* POST Arguments: downloadlink9 - the url of the downloadlink +* POST Arguments: downloaddistributiontype9 - the type of the distribution for the download. the types are described at downloaddistributiontype1. +* POST Arguments: downloadbuy9 - is this download free or paid. 0 - free, 1 - paid. +* POST Arguments: downloadbuyreason9 - the description why is content is not for free. +* POST Arguments: downloadbuyprice9 - the price of this content in USD. +* POST Arguments: downloadgpgfingerprint9 - the gpg fingerprint of this download +* POST Arguments: downloadgpgsignature9 - the gpg signature of this download +* POST Arguments: downloadpackagename9 - the name of the package in the repository +* POST Arguments: downloadpackagerepository9 - the repository where the package is located +* POST Arguments: downloadname10 - the name of the downloadlink +* POST Arguments: downloadlink10 - the url of the downloadlink +* POST Arguments: downloaddistributiontype10 - the type of the distribution for the download. the types are described at downloaddistributiontype1. +* POST Arguments: downloadbuy10 - is this download free or paid. 0 - free, 1 - paid. +* POST Arguments: downloadbuyreason10 - the description why is content is not for free. +* POST Arguments: downloadbuyprice10 - the price of this content in USD. +* POST Arguments: downloadgpgfingerprint10 - the gpg fingerprint of this download +* POST Arguments: downloadgpgsignature10 - the gpg signature of this download +* POST Arguments: downloadpackagename10 - the name of the package in the repository +* POST Arguments: downloadpackagerepository10 - the repository where the package is located +* POST Arguments: downloadname11 - the name of the downloadlink +* POST Arguments: downloadlink11 - the url of the downloadlink +* POST Arguments: downloaddistributiontype11 - the type of the distribution for the download. the types are described at downloaddistributiontype1. +* POST Arguments: downloadbuy11 - is this download free or paid. 0 - free, 1 - paid. +* POST Arguments: downloadbuyreason11 - the description why is content is not for free. +* POST Arguments: downloadbuyprice11 - the price of this content in USD. +* POST Arguments: downloadgpgfingerprint11 - the gpg fingerprint of this download +* POST Arguments: downloadgpgsignature11 - the gpg signature of this download +* POST Arguments: downloadpackagename11 - the name of the package in the repository +* POST Arguments: downloadpackagerepository11 - the repository where the package is located +* POST Arguments: downloadname12 - the name of the downloadlink +* POST Arguments: downloadlink12 - the url of the downloadlink +* POST Arguments: downloaddistributiontype12 - the type of the distribution for the download. the types are described at downloaddistributiontype1. +* POST Arguments: downloadbuy12 - is this download free or paid. 0 - free, 1 - paid. +* POST Arguments: downloadbuyreason12 - the description why is content is not for free. +* POST Arguments: downloadbuyprice12 - the price of this content in USD. +* POST Arguments: downloadgpgfingerprint12 - the gpg fingerprint of this download +* POST Arguments: downloadgpgsignature12 - the gpg signature of this download +* POST Arguments: downloadpackagename12 - the name of the package in the repository +* POST Arguments: downloadpackagerepository12 - the repository where the package is located +* POST Arguments: description - a description text of the entry +* POST Arguments: summary - a short summary of the entry +* POST Arguments: licensetype - the license this content is under. get the possible values by calling /v1/content/licenses +* POST Arguments: license - the license text +* POST Arguments: feedbackurl - a link to the page where users can post feedback +* POST Arguments: homepage - a link to the homepage of the entry +* POST Arguments: homepagetype - the type of the link. get the possible values by calling /v1/content/homepages +* POST Arguments: homepage2 - a link to the homepage of the entry +* POST Arguments: homepagetype2 - the type of the link. +* POST Arguments: homepage3 - a link to the homepage of the entry +* POST Arguments: homepagetype3 - the type of the link. +* POST Arguments: homepage4 - a link to the homepage of the entry +* POST Arguments: homepagetype4 - the type of the link. +* POST Arguments: homepage5 - a link to the homepage of the entry +* POST Arguments: homepagetype5 - the type of the link. +* POST Arguments: homepage6 - a link to the homepage of the entry +* POST Arguments: homepagetype6 - the type of the link. +* POST Arguments: homepage7 - a link to the homepage of the entry +* POST Arguments: homepagetype7 - the type of the link. +* POST Arguments: homepage8 - a link to the homepage of the entry +* POST Arguments: homepagetype8 - the type of the link. +* POST Arguments: homepage9 - a link to the homepage of the entry +* POST Arguments: homepagetype9 - the type of the link. +* POST Arguments: homepage10 - a link to the homepage of the entry +* POST Arguments: homepagetype10 - the type of the link. +* POST Arguments: video1 - a link to the video file +* POST Arguments: video2 - a link to the video file +* POST Arguments: video3 - a link to the video file +* POST Arguments: version - the version of this entry +* POST Arguments: changelog - the changelog of this entry +* POST Arguments: donation - do you want donation for this entry? possible values are "yes" or "" for no donation. +* POST Arguments: donationreason - a reason we you want a donation +* POST Arguments: osbsproject - the opensuse build service project id +* POST Arguments: osbspackage - the opensuse build service package id +* Result: status xml +* Mandatory fields: "name" and "type" are mandatory fields +* Statuscodes: + * 100 - successful + * 101 - please specify all mandatory fields + * 102 - no permission to change content +* Example: <http://api.opendesktop.org/v1/content/add> +Example: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + </meta> + <data> + <content> + <id>1234567</id> + </content> + </data> + </ocs> + +#### edit + +Edit a content entry: + +* Syntax: v1/content/edit/"12345" +* HTTP Method: POST +* POST Arguments: name - the name of the entry +* POST Arguments: type - the type or category of the entry. call the categories method to get a list of all categories. +* POST Arguments: depend - the dependency of this entry. get the possible dependencies by calling /v1/content/dependencies +* POST Arguments: downloadtyp1 - the type of the first download. possible values are: 0 - use the uploaded file, 1 - use the downloadlink1, 2 - use the downloadpackagename and downloadrepository +* POST Arguments: downloadname1 - the name of the 1. downloadlink +* POST Arguments: downloadlink1 - the url of the downloadlink +* POST Arguments: downloaddistributiontype1 - the type of the distribution for the download. get the possible distributions by calling /v1/content/distributions +* POST Arguments: downloadbuy1 - is this download free or paid. 0 - free, 1 - paid. +* POST Arguments: downloadbuyreason1 - the description why is content is not for free. +* POST Arguments: downloadbuyprice1 - the price of this content in USD. +* POST Arguments: downloadgpgfingerprint1 - the gpg fingerprint of this download +* POST Arguments: downloadgpgsignature1 - the gpg signature of this download +* POST Arguments: downloadpackagename1 - the name of the package in the repository +* POST Arguments: downloadpackagerepository1 - the repository where the package is located +* POST Arguments: downloadname2 - the name of the downloadlink +* POST Arguments: downloadlink2 - the url of the downloadlink +* POST Arguments: downloaddistributiontype2 - the type of the distribution for the download. the types are described at downloaddistributiontype1. +* POST Arguments: downloadbuy2 - is this download free or paid. 0 - free, 1 - paid. +* POST Arguments: downloadbuyreason2 - the description why is content is not for free. +* POST Arguments: downloadbuyprice2 - the price of this content in USD. +* POST Arguments: downloadgpgfingerprint2 - the gpg fingerprint of this download +* POST Arguments: downloadgpgsignature2 - the gpg signature of this download +* POST Arguments: downloadpackagename2 - the name of the package in the repository +* POST Arguments: downloadpackagerepository2 - the repository where the package is located +* POST Arguments: downloadname3 - the name of the downloadlink +* POST Arguments: downloadlink3 - the url of the downloadlink +* POST Arguments: downloaddistributiontype3 - the type of the distribution for the download. the types are described at downloaddistributiontype1. +* POST Arguments: downloadbuy3 - is this download free or paid. 0 - free, 1 - paid. +* POST Arguments: downloadbuyreason3 - the description why is content is not for free. +* POST Arguments: downloadbuyprice3 - the price of this content in USD. +* POST Arguments: downloadgpgfingerprint3 - the gpg fingerprint of this download +* POST Arguments: downloadgpgsignature3 - the gpg signature of this download +* POST Arguments: downloadpackagename3 - the name of the package in the repository +* POST Arguments: downloadpackagerepository3 - the repository where the package is located +* POST Arguments: downloadname4 - the name of the downloadlink +* POST Arguments: downloadlink4 - the url of the downloadlink +* POST Arguments: downloaddistributiontype4 - the type of the distribution for the download. the types are described at downloaddistributiontype1. +* POST Arguments: downloadbuy4 - is this download free or paid. 0 - free, 1 - paid. +* POST Arguments: downloadbuyreason4 - the description why is content is not for free. +* POST Arguments: downloadbuyprice4 - the price of this content in USD. +* POST Arguments: downloadgpgfingerprint4 - the gpg fingerprint of this download +* POST Arguments: downloadgpgsignature4 - the gpg signature of this download +* POST Arguments: downloadpackagename4 - the name of the package in the repository +* POST Arguments: downloadpackagerepository4 - the repository where the package is located +* POST Arguments: downloadname5 - the name of the downloadlink +* POST Arguments: downloadlink5 - the url of the downloadlink +* POST Arguments: downloaddistributiontype5 - the type of the distribution for the download. the types are described at downloaddistributiontype1. +* POST Arguments: downloadbuy5 - is this download free or paid. 0 - free, 1 - paid. +* POST Arguments: downloadbuyreason5 - the description why is content is not for free. +* POST Arguments: downloadbuyprice5 - the price of this content in USD. +* POST Arguments: downloadgpgfingerprint5 - the gpg fingerprint of this download +* POST Arguments: downloadgpgsignature5 - the gpg signature of this download +* POST Arguments: downloadpackagename5 - the name of the package in the repository +* POST Arguments: downloadpackagerepository5 - the repository where the package is located +* POST Arguments: downloadname6 - the name of the downloadlink +* POST Arguments: downloadlink6 - the url of the downloadlink +* POST Arguments: downloaddistributiontype6 - the type of the distribution for the download. the types are described at downloaddistributiontype1. +* POST Arguments: downloadbuy6 - is this download free or paid. 0 - free, 1 - paid. +* POST Arguments: downloadbuyreason6 - the description why is content is not for free. +* POST Arguments: downloadbuyprice6 - the price of this content in USD. +* POST Arguments: downloadgpgfingerprint6 - the gpg fingerprint of this download +* POST Arguments: downloadgpgsignature6 - the gpg signature of this download +* POST Arguments: downloadpackagename6 - the name of the package in the repository +* POST Arguments: downloadpackagerepository6 - the repository where the package is located +* POST Arguments: downloadname7 - the name of the downloadlink +* POST Arguments: downloadlink7 - the url of the downloadlink +* POST Arguments: downloaddistributiontype7 - the type of the distribution for the download. the types are described at downloaddistributiontype1. +* POST Arguments: downloadbuy7 - is this download free or paid. 0 - free, 1 - paid. +* POST Arguments: downloadbuyreason7 - the description why is content is not for free. +* POST Arguments: downloadbuyprice7 - the price of this content in USD. +* POST Arguments: downloadgpgfingerprint7 - the gpg fingerprint of this download +* POST Arguments: downloadgpgsignature7 - the gpg signature of this download +* POST Arguments: downloadpackagename7 - the name of the package in the repository +* POST Arguments: downloadpackagerepository7 - the repository where the package is located +* POST Arguments: downloadname8 - the name of the downloadlink +* POST Arguments: downloadlink8 - the url of the downloadlink +* POST Arguments: downloaddistributiontype8 - the type of the distribution for the download. the types are described at downloaddistributiontype1. +* POST Arguments: downloadbuy8 - is this download free or paid. 0 - free, 1 - paid. +* POST Arguments: downloadbuyreason8 - the description why is content is not for free. +* POST Arguments: downloadbuyprice8 - the price of this content in USD. +* POST Arguments: downloadgpgfingerprint8 - the gpg fingerprint of this download +* POST Arguments: downloadgpgsignature8 - the gpg signature of this download +* POST Arguments: downloadpackagename8 - the name of the package in the repository +* POST Arguments: downloadpackagerepository8 - the repository where the package is located +* POST Arguments: downloadname9 - the name of the downloadlink +* POST Arguments: downloadlink9 - the url of the downloadlink +* POST Arguments: downloaddistributiontype9 - the type of the distribution for the download. the types are described at downloaddistributiontype1. +* POST Arguments: downloadbuy9 - is this download free or paid. 0 - free, 1 - paid. +* POST Arguments: downloadbuyreason9 - the description why is content is not for free. +* POST Arguments: downloadbuyprice9 - the price of this content in USD. +* POST Arguments: downloadgpgfingerprint9 - the gpg fingerprint of this download +* POST Arguments: downloadgpgsignature9 - the gpg signature of this download +* POST Arguments: downloadpackagename9 - the name of the package in the repository +* POST Arguments: downloadpackagerepository9 - the repository where the package is located +* POST Arguments: downloadname10 - the name of the downloadlink +* POST Arguments: downloadlink10 - the url of the downloadlink +* POST Arguments: downloaddistributiontype10 - the type of the distribution for the download. the types are described at downloaddistributiontype1. +* POST Arguments: downloadbuy10 - is this download free or paid. 0 - free, 1 - paid. +* POST Arguments: downloadbuyreason10 - the description why is content is not for free. +* POST Arguments: downloadbuyprice10 - the price of this content in USD. +* POST Arguments: downloadgpgfingerprint10 - the gpg fingerprint of this download +* POST Arguments: downloadgpgsignature10 - the gpg signature of this download +* POST Arguments: downloadpackagename10 - the name of the package in the repository +* POST Arguments: downloadpackagerepository10 - the repository where the package is located +* POST Arguments: downloadname11 - the name of the downloadlink +* POST Arguments: downloadlink11 - the url of the downloadlink +* POST Arguments: downloaddistributiontype11 - the type of the distribution for the download. the types are described at downloaddistributiontype1. +* POST Arguments: downloadbuy11 - is this download free or paid. 0 - free, 1 - paid. +* POST Arguments: downloadbuyreason11 - the description why is content is not for free. +* POST Arguments: downloadbuyprice11 - the price of this content in USD. +* POST Arguments: downloadgpgfingerprint11 - the gpg fingerprint of this download +* POST Arguments: downloadgpgsignature11 - the gpg signature of this download +* POST Arguments: downloadpackagename11 - the name of the package in the repository +* POST Arguments: downloadpackagerepository11 - the repository where the package is located +* POST Arguments: downloadname12 - the name of the downloadlink +* POST Arguments: downloadlink12 - the url of the downloadlink +* POST Arguments: downloaddistributiontype12 - the type of the distribution for the download. the types are described at downloaddistributiontype1. +* POST Arguments: downloadbuy12 - is this download free or paid. 0 - free, 1 - paid. +* POST Arguments: downloadbuyreason12 - the description why is content is not for free. +* POST Arguments: downloadbuyprice12 - the price of this content in USD. +* POST Arguments: downloadgpgfingerprint12 - the gpg fingerprint of this download +* POST Arguments: downloadgpgsignature12 - the gpg signature of this download +* POST Arguments: downloadpackagename12 - the name of the package in the repository +* POST Arguments: downloadpackagerepository12 - the repository where the package is located +* POST Arguments: description - a description text of the entry +* POST Arguments: summary - a short summary of the entry +* POST Arguments: licensetype - the license this content is under. get the possible values by calling /v1/content/licenses +* POST Arguments: license - the license text +* POST Arguments: feedbackurl - a link to the page where users can post feedback +* POST Arguments: homepage - a link to the homepage of the entry +* POST Arguments: homepagetype - the type of the link. get the possible values by calling /v1/content/homepages +* POST Arguments: homepage2 - a link to the homepage of the entry +* POST Arguments: homepagetype2 - the type of the link. +* POST Arguments: homepage3 - a link to the homepage of the entry +* POST Arguments: homepagetype3 - the type of the link. +* POST Arguments: homepage4 - a link to the homepage of the entry +* POST Arguments: homepagetype4 - the type of the link. +* POST Arguments: homepage5 - a link to the homepage of the entry +* POST Arguments: homepagetype5 - the type of the link. +* POST Arguments: homepage6 - a link to the homepage of the entry +* POST Arguments: homepagetype6 - the type of the link. +* POST Arguments: homepage7 - a link to the homepage of the entry +* POST Arguments: homepagetype7 - the type of the link. +* POST Arguments: homepage8 - a link to the homepage of the entry +* POST Arguments: homepagetype8 - the type of the link. +* POST Arguments: homepage9 - a link to the homepage of the entry +* POST Arguments: homepagetype9 - the type of the link. +* POST Arguments: homepage10 - a link to the homepage of the entry +* POST Arguments: homepagetype10 - the type of the link. +* POST Arguments: video1 - a link to the video file +* POST Arguments: video2 - a link to the video file +* POST Arguments: video3 - a link to the video file +* POST Arguments: version - the version of this entry +* POST Arguments: changelog - the changelog of this entry +* POST Arguments: donation - do you want donation for this entry? possible values are "yes" or "" for no donation. +* POST Arguments: donationreason - a reason we you want a donation +* POST Arguments: osbsproject - the opensuse build service project id +* POST Arguments: osbspackage - the opensuse build service package id +* POST Arguments: announceupdate - announce this edit on the frontpage. possible values are 1 - announce, 0 - not announce, the default is 1 +* Result: status xml +* Mandatory fields: "name" and "type" are mandatory fields +* Statuscodes: + * 100 - successful + * 101 - please specify all mandatory fields + * 102 - no permission to change content +* Example: <http://api.opendesktop.org/v1/content/edit/12345> +Example: + + <?xml version="1.0"?> + <ocs> + <status>ok</status> + <message></message> + </ocs> + +#### delete content entry + +Delete a content entry: + +* Syntax: v1/content/delete/"contentid" +* HTTP Method: POST +* Arguments: contentid - Id of a content +* Result: status xml +* Statuscodes: + * 100 - successful + * 101 - no permission to change content +* Example: <http://api.opendesktop.org/v1/content/delete/12345> +Example: + + <?xml version="1.0"?> + <ocs> + <status>ok</status> + <message></message> + </ocs> + +#### upload new download file + +Upload a new download file to a content: + +* Syntax: v1/content/uploaddownload/"contentid" +* HTTP Method: POST +* Arguments: contentid - Id of a content +* POST Arguments: localfile - The file to upload +* Result: status xml +* Statuscodes: + * 100 - successful + * 101 - upload error + * 102 - localfile not found + * 103 - no permission to change content +* Example: <http://api.opendesktop.org/v1/content/uploaddownload/12345> +Example: + + <?xml version="1.0"?> + <ocs> + <status>ok</status> + <message></message> + </ocs> + +#### delete download file + +Delete the download file from a content: + +* Syntax: v1/content/deletedownload/"contentid" +* HTTP Method: POST +* Arguments: contentid - Id of a content +* Result: status xml +* Statuscodes: + * 100 - successful + * 101 - no permission to change content +* Example: <http://api.opendesktop.org/v1/content/deletedownload/12345> +Example: + + <?xml version="1.0"?> + <ocs> + <status>ok</status> + <message></message> + </ocs> + +#### upload preview image + +Upload a new preview image for a content: + +* Syntax: v1/content/uploadpreview/"contentid"/"previewid" +* HTTP Method: POST +* Arguments: contentid - Id of a content +* Arguments: previewid - Id of the preview image. (1,2 or 3) +* POST Arguments: localfile - The imagefile to upload +* Result: status xml +* Statuscodes: + * 100 - successful + * 101 - localfile not found + * 102 - no permission to change content + * 103 - preview must be 1, 2 or 3 +* Example: <http://api.opendesktop.org/v1/content/uploadpreview/12345/1> +Example: + + <?xml version="1.0"?> + <ocs> + <status>ok</status> + <message></message> + </ocs> + +#### delete preview image + +Delete a preview image from a content: + +* Syntax: v1/content/deletepreview/"contentid"/"previewid" +* HTTP Method: POST +* Arguments: contentid - Id of a content +* Arguments: previewid - Id of the preview image. (1,2 or 3) +* Result: status xml +* Statuscodes: + * 100 - successful + * 101 - no permission to change content + * 102 - preview not found +* Example: <http://api.opendesktop.org/v1/content/deletepreview/12345/1> +Example: + + <?xml version="1.0"?> + <ocs> + <status>ok</status> + <message></message> + </ocs> + +#### getrecommendation + +Gets a list of cross selling for a contentid + +* Syntax: /v1/content/recommendations/"contentid" +* HTTP Method: GET +* URL Arguments: contentid - ID of an entry where you want to get similar or other recommended entries for. +* URL Arguments: page - The content page. You can control the size of a page with the pagesize argument. The first page is 0, the second is 1, ... +* URL Arguments: pagesize - The amount of entries per page. +* Result: content xml +* Statuscodes: + * 100 - successful + * 200 - too many API requests in the last 15 minutes from your IP address. please try again later. +* Example: <http://frank:password@api.opendesktop.org/v1/content/recommendations/123/?categories=1x2x3x4&page=1> Gets the second page of the list of recommendations for the content 123 from categories 1,2,3 and 4. +Example: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + <totalitems>2</totalitems> + <itemsperpage>10</itemsperpage> + </meta> + <data> + <content details="basic"> + <id>1422</id> + </content> + <content details="basic"> + <id>1223344</id> + </content> + </data> + </ocs> + +<a name="FAN"></a> +### FAN + + +#### get + +Gets a list of fans of a specific content entries. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. + +* Syntax: /v1/fan/data/"contentid" +* HTTP Method: GET +* URL Arguments: contentid - Id of the content entry where you want to get the fans is from. +* URL Arguments: page - The list page. You can control the size of a page with the pagesize argument. The first page is 0, the second is 1, ... +* URL Arguments: pagesize - The amount of entries per page. +* Result: fan xml +* Statuscodes: + * 100 - successful +* Example: <http://frank:password@api.opendesktop.org/v1/fan/data/123&page=1&pagesize=10> Gets the second page of the list of fans of the content with the id 123. The pagesize is 10 +Example: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + <totalitems>2</totalitems> + <itemsperpage>10</itemsperpage> + </meta> + <data> + <person details="fans"> + <personid>Frank</personid> + <timestamp>2009-08-18T10:40:09+02:00</timestamp> + </person> + <person details="fans"> + <personid>Test</personid> + <timestamp>2009-07-18T11:41:15+02:00</timestamp> + </person> + </data> + </ocs> + +#### isfan + +Check if the current user is fan of a specific content. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. + +* Syntax: /v1/fan/status/"contentid" +* HTTP Method: GET +* URL Arguments: contentid - Id of the content entry where you want to get the fan status from. +* Result: fan xml Possible stati are "fan" or "notfan" +* Statuscodes: + * 100 - successful +* Example: <http://frank:password@api.opendesktop.org/v1/fan/status/123> Checks if the user frank is a fan of the content 123 +Example: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + </meta> + <data> + <status>fan</status> + </data> + </ocs> + +#### add + +Become a fan of a specific content. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. + +* Syntax: /v1/fan/add/"contentid" +* HTTP Method: POST +* URL Arguments: contentid - Id of the content entry +* Result: fan xml +* Statuscodes: + * 100 - successful +* Example: <http://frank:password@api.opendesktop.org/v1/fan/add/123> The user frank becomes a fan of the content 123 +Example: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + </meta> + </ocs> + +#### remove + +Remove the user from the fans list of a specific content. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. + +* Syntax: /v1/fan/remove/"contentid" +* HTTP Method: POST +* URL Arguments: contentid - Id of the content entry +* Result: fan xml +* Statuscodes: + * 100 - successful +* Example: <http://frank:password@api.opendesktop.org/v1/fan/remove/123> The user frank is no longer a fan of the content 123 +Example: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + </meta> + </ocs> + +<a name="KNOWLEDGEBASE"></a> +### KNOWLEDGEBASE + + +#### list + +Gets a list of a specific set of knowledgebase entries. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. + +* Syntax: /v1/knowledgebase/data/ +* HTTP Method: GET +* URL Arguments: content - Id of the content entry if you want to get knowledgebase entries from a specific content entry. +* URL Arguments: type - Id of the category type. +* URL Arguments: search - a keyword you want find in the name, description or answer of a knowledgebase entry. +* URL Arguments: sortmode - The sortmode of the list. Possible values are: "new" - newest first or "alpha" - alphabetical +* URL Arguments: page - The list page. You can control the size of a page with the pagesize argument. The first page is 0, the second is 1, ... +* URL Arguments: pagesize - The amount of entries per page. +* Result: knowledgebase xml +* Statuscodes: + * 100 - successful +* Example: <http://frank:password@api.opendesktop.org/v1/knowledgebase/data?content=123&search=foo&sortmode=new&page=1> Gets the second page of the list of the newest knowledgebase entries from content 123 with the string foo in the name, description or answer. +Example: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + <totalitems>2</totalitems> + <itemsperpage>10</itemsperpage> + </meta> + <data> + <content details="detail"> + <id>1</id> + <status>not answered</status> + <contentid>12345</contentid> + <category>Application</category> + <user>testy</user> + <changed>2009-02-07T23:14:11+01:00</changed> + <name>app question</name> + <description>How can I ........</description> + <answer></answer> + <answeruser>testy2</answeruser> + <comments>0</comments> + <detailpage>http://www.opendesktop.org/content/show.php?action=knowledgebase&content=11&kbid=12345</detailpage> + </content> + <content details="detail">> + <id>2</id> + <status>answered</status> + <contentid>12345</contentid> + <category>other</category> + <user>testy</user> + <changed>2009-02-03T21:11:01+01:00</changed> + <name>app question 22</name> + <description>How can I 22........</description> + <answeruser>testy2</answeruser> + <answer></answer> + <comments>0</comments> + <detailpage>http://www.opendesktop.org/content/show.php?action=knowledgebase&content=11&kbid=12</detailpage> + </content> + </data> + +#### get + +Read one specific knowledgebase entry. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. + +* Syntax: /v1/knowledgebase/data/"contentid"/ +* HTTP Method: GET +* Arguments: knowledgebaseid - Id of a knowledgebase entry +* Result: knowledgebase xml +* Statuscodes: + * 100 - successful + * 101 - entry not found +* Example: <http://frank:password@api.opendesktop.org/v1/knowledgebase/data/12345> +Example: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + </meta> + <data> + <knowledgebase> + <id>1</id> + <status>not answered</status> + <contentid>12345</contentid> + <category>Application</category> + <user>testy</user> + <changed>2009-02-07T23:14:11+01:00</changed> + <name>app question</name> + <description>How can I ........</description> + <answeruser>testy2</answeruser> + <answer></answer> + <comments>0</comments> + <detailpage>http://www.opendesktop.org/content/show.php?action=knowledgebase&content=11&kbid=12345</detailpage> + </knowledgebase> + </data> + </ocs> + +#### add + +Add one specific knowledgebase entry. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. + +* Syntax: /v1/knowledgebase/data/ +* HTTP Method: POST +* POST Argument: subject - Subject of the new knowledgebase item +* POST Argument: message - Content of the new knowledgebase item +* POST Argument: content - id of the content entry to be added to if available +* POST Argument: category - Id of the category to be added to if available. +* Result: knowledgebase xml +* Statuscodes: + * 100 - successful + * 101 - please specify all mandatory fields +* Example: <http://frank:password@api.opendesktop.org/v1/knowledgebase/data> +Example: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + </meta> + </ocs> + +<a name="EVENT"></a> +### EVENT + + +#### list + +Gets a list of a specific set of events. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. + +* Syntax: /v1/event/data/ +* HTTP Method: GET +* URL Arguments: type - Id of the event type. +* URL Arguments: country - ISO code of the country. +* URL Arguments: startat - Earliest possible start date of the events. +* URL Arguments: search - a keyword you want find in the name or description of a event entry. +* URL Arguments: sortmode - The sortmode of the list. Possible values are: "new" - newest upcoming events first or "alpha" - alphabetical +* URL Arguments: page - The list page. You can control the size of a page with the pagesize argument. The first page is 0, the second is 1, ... +* URL Arguments: pagesize - The amount of entries per page. +* type 10: Party +* type 15: User Group +* type 20: Conference +* type 25: Developer Meeting +* type 50: Install Party +* type 1000: otherParty +* Result: event xml +* Statuscodes: + * 100 - successful +* Example: <http://frank:password@api.opendesktop.org/v1/event/data?country=us&startat=01-01-2009&type=10&search=foo&sortmode=new&page=1> Gets the second page of the list of the newest events of 2009 from type party in the US with the string foo in the name or description. +Example: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + <totalitems>2</totalitems> + <itemsperpage>10</itemsperpage> + </meta> + <data> + <event details="detail"> + <id>4</id> + <name>Test Party</name> + <category>Party</category> + <startdate>2010-08-02T00:00:00+02:00</startdate> + <enddate>2011-10-03T00:00:00+02:00</enddate> + <user>Frank</user> + <city>Stuttgart</city> + <country>Germany</country> + <longitude>9.183</longitude> + <latitude>48.767</latitude> + <changed>2009-05-18T14:03:55+02:00</changed> + <comments>2</comments> + <participants>2</participants> + <badge></badge> + <detailpage>http://www.opendesktop.org/events/?id=4</detailpage> + </event> + <event details="detail"> + <id>3</id> + <name>Another Party</name> + <category>Party</category> + <startdate>1979-01-01T01:00:01+01:00</startdate> + <enddate>1979-01-01T01:00:01+01:00</enddate> + <user>Frank</user> + <city>Stuttgart</city> + <country>Germany</country> + <longitude>1.2</longitude> + <latitude>1.1</latitude> + <changed>2009-05-16T00:25:31+02:00</changed> + <comments>0</comments> + <participants>1</participants> + <badge></badge> + <detailpage>http://www.opendesktop.org/events/?id=3</detailpage> + </event> + </data> + </ocs> + +#### get + +Read one specific event entry. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. + +* Syntax: /v1/event/data/"eventid"/ +* HTTP Method: GET +* Arguments: eventid - Id of a event entry +* Result: event xml +* Statuscodes: + * 100 - successful + * 101 - entry not found +* Example: <http://frank:password@api.opendesktop.org/v1/event/data/12345> +Example: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + </meta> + <data> + <event> + <id>6</id> + <name>bbb</name> + <description>here is the description text</description> + <category>Party</category> + <startdate>1970-01-01T00:00:00+01:00</startdate> + <enddate>1970-01-01T00:00:00+01:00</enddate> + <user>Frank</user> + <organizer></organizer> + <location></location> + <city></city> + <country>Germany</country> + <longitude>0</longitude> + <latitude>0</latitude> + <homepage></homepage> + <tel></tel> + <fax></fax> + <email></email> + <changed>2009-05-18T18:49:15+02:00</changed> + <comments>1</comments> + <participants>2</participants> + <detailpage>http://www.opendesktop.org/events/?id=6</detailpage> + <badge>http://www.opendesktop.org/CONTENT/event-badge/0/6.png</badge> + <image></image> + </event> + </data> + </ocs> + +#### add + +Add a new event entry. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. + +* Syntax: v1/event/add +* HTTP Method: POST +* POST Arguments: name - the name of the entry +* POST Arguments: category - the category of the event. possible values are: +* 10 - Party +* 15 - User Group +* 20 - Conference +* 25 - Developer Meeting +* 50 - Install Party +* 1000 - other +* POST Arguments: description - the description text of the event. +* POST Arguments: startdate - the startdate of the event. +* POST Arguments: enddate - the enddate of the event +* POST Arguments: organizer - the organizer of the event. +* POST Arguments: location - the location where the event takes place. +* POST Arguments: city - the city. +* POST Arguments: country - the 2 letter iso code of the country. +* POST Arguments: longitude - the longitude of the event. +* POST Arguments: latitude - the latitude of the event. +* POST Arguments: homepage - the homepage of the event. +* POST Arguments: tel - the telefon number. +* POST Arguments: fax - the fax number. +* POST Arguments: email - a contact email address. +* Result: status xml +* Mandatory fields: "name" and "category" are mandatory fields +* Statuscodes: + * 100 - successful + * 101 - please specify all mandatory fields + * 102 - no permission to add event +* Example: <http://api.opendesktop.org/v1/event/add> +Example: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + </meta> + <data> + <event> + <id>1234567</id> + </event> + </data> + </ocs> + +#### edit + +Edit a event entry. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. + +* Syntax: v1/event/edit/"12345" +* HTTP Method: POST +* POST Arguments: name - the name of the entry +* POST Arguments: category - the category of the event. possible values are: +* 10 - Party +* 15 - User Group +* 20 - Conference +* 25 - Developer Meeting +* 50 - Install Party +* 1000 - other +* POST Arguments: description - the description text of the event. +* POST Arguments: startdate - the startdate of the event. +* POST Arguments: enddate - the enddate of the event +* POST Arguments: organizer - the organizer of the event. +* POST Arguments: location - the location where the event takes place. +* POST Arguments: city - the city. +* POST Arguments: country - the 2 letter iso code of the country. +* POST Arguments: longitude - the longitude of the event. +* POST Arguments: latitude - the latitude of the event. +* POST Arguments: homepage - the homepage of the event. +* POST Arguments: tel - the telefon number. +* POST Arguments: fax - the fax number. +* POST Arguments: email - a contact email address. +* Result: status xml +* Mandatory fields: "name" and "category" are mandatory fields +* Statuscodes: + * 100 - successful + * 101 - please specify all mandatory fields + * 102 - no permission to change event +* Example: <http://api.opendesktop.org/v1/event/edit/12345> +Example: + + <?xml version="1.0"?> + <ocs> + <status>ok</status> + <message></message> + </ocs> + +#### delete event entry + +Delete a event entry. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. + +* Syntax: v1/event/delete/"contentid" +* HTTP Method: POST +* Arguments: eventid - Id of a event +* Result: status xml +* Statuscodes: + * 100 - successful + * 101 - no permission to change event +* Example: <http://api.opendesktop.org/v1/event/delete/12345> +Example: + + <?xml version="1.0"?> + <ocs> + <status>ok</status> + <message></message> + </ocs> + +<a name="COMMENTS"></a> +### COMMENTS + + +#### get + +Gets a list of comments. + +* Syntax: /v1/comments/data/"type"/"contentid"/"contentid2" +* HTTP Method: GET +* URL Arguments: type - Id of the content entry where you want to get the comments is from. +* URL Arguments: contentid - Id of the content entry where you want to get the comments is from. +* URL Arguments: contentid2 - Id of the content entry where you want to get the comments is from. +* URL Arguments: page - The list page. You can control the size of a page with the pagesize argument. The first page is 0, the second is 1, ... +* URL Arguments: pagesize - The amount of entries per page. +* Result: comments xml +* Statuscodes: + * 100 - successful +* Types: + * 1 - content + * 4 - forum + * 7 - knowledgebase + * 8 - event +* Example: <http://frank:password@api.opendesktop.org/v1/comments/data/1/123/0&page=1&pagesize=10> Gets the second page of the list of comments of the content with the id 123. The pagesize is 10 +Example: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + </meta> + <data> + <comment> + <id>234</id> + <subject>vfvvdsx</subject> + <text>vdxvvsx</text> + <childcount>0</childcount> + <user>test</user> + <date>2005-01-29T18:58:40+01:00</date> + <score>50</score> + </comment> + <comment> + <id>235</id> + <subject>vxvdfvd</subject> + <text>gfdgfdgfgfgf + </text> + <childcount>1</childcount> + <user>test</user> + <date>2005-01-29T19:17:06+01:00</date> + <score>60</score> + <children> + <comment> + <id>315</id> + <subject>Re: jjjjjjjjjjjjjjj</subject> + <text>gfdg</text> + <childcount>0</childcount> + <user>Frank</user> + <date>2007-03-13T21:34:43+01:00</date> + <score>40</score> + </comment> + </children> + </comment> + </data> + </ocs> + +#### add + +Add a comment. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. + +* Syntax: v1/comments/add +* HTTP Method: POST +* Arguments: type - type of comment +* Arguments: content - the content id where the comment belongs +* Arguments: content2 - the sub content id where the comment belongs +* Arguments: parent - the id of the parent comment if the new comment is a reply +* Arguments: subject - the subject of the comment +* Arguments: message - the message text of the comment +* Types: + * 1 - content + * 4 - forum + * 7 - knowledgebase + * 8 - event +* Result: status xml +* Statuscodes: + * 100 - successful + * 101 - content must not be empty + * 102 - message or subject must not be empty + * 103 - no permission to add a comment +* Example: <http://api.opendesktop.org/v1/comments/add> +Example: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + </meta> + </ocs> + +#### vote + +Vote for one specific comment. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. + +* Syntax: /v1/comments/vote/"commentsid" +* HTTP Method: POST +* Arguments: contentid - Id of a comment +* POST Arguments: vote - The vote. An integer between 0 to 100. 0 equals bad and 100 equals good +* Result: status xml +* Statuscodes: + * 100 - successful + * 101 - comment not found + * 200 - too many API requests in the last 15 minutes from your IP address. please try again later. +* Example: <http://api.opendesktop.org/v1/content/vote/12345> with the POST variable vote=4 +Example: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + </meta> + <data> + <comment> + <id>1234567</id> + </comment> + </data> + </ocs> + +<a name="PRIVATEDATA"></a> +### PRIVATE DATA + + +#### get attributes + +Gets the list of my personal extended attributes. You can store several attributes which are only readable to me. The attributes are key/value pairs with an "app" parameter as namespace. Store data which is only interesting for your application with your application name as a app namespace. If the data is of general interest use "global" as app parameter. The parameter "app" and "key" are optional in the url. So you access all the attributes from yourself or only the attributes from a specific application or the only the value of one specific key. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. + +* syntax: /v1/privatedata/getattribute/"app"/"key" +* HTTP method: GET +* Arguments: app - The application from which you want to get the attributes. This parameter is optional. +* Arguments: key - The key of the attribute you want to get. This parameter is optional. +* Statuscodes: + * 100 - successfull +Example: GET <http://frank:password@api.opendesktop.org/v1/privatedata/getattribute/parley/language> Get the value of the key language of the application parley from myself. Example: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + <totalitems>1</totalitems> + </meta> + <data> + <attribute> + <app>parley</app> + <key>language</key> + <value>english, german</value> + <lastmodified>2007-11-01T22:45:20+01:00</lastmodified> + </attribute> + </data> + </ocs> + +#### set attribute + +Set a attribute. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. + +* syntax: /v1/privatedata/setattribute/"app"/"key" +* HTTP method: POST +* Arguments: app - The application where you want to store this attribute at. +* Arguments: key - The key of the attribute. +* POST arguments: value - The value of the attribute. +* Statuscodes: + * 100 - successfull +Example: POST <http://frank:password@api.opendesktop.org/v1/privatedata/setattribute/parley/language> postdata: value="italian" Set the value of the key "language" of the application "parley" to "italian". Example: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + </meta> + </ocs> + +#### delete attribute + +Delete a attribute. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. + +* syntax: /v1/privatedata/deleteattribute/"app"/"key" +* HTTP method: POST +* Arguments: app - The application where the key is stored. +* Arguments: key - The key of the attribute. +* Statuscodes: + * 100 - successfull +Example: POST <http://frank:password@api.opendesktop.org/v1/privatedata/deleteattribute/parley/language> Delete the attribute with the key "language" and the application "parley". Example: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + </meta> + </ocs> + +<a name="FORUM"></a> +### FORUM + + +#### list + +Gets a list of forums. + +* syntax: /v1/forum/list +* HTTP Method: GET +* URL Arguments: page - The list page. You can control the size of a page with the pagesize argument. The first page is 0, the second is 1, +* URL Arguments: pagesize - The amount of entries per page. +* Result: comments xml +* Statuscodes: + * 100 - successful +Example: <http://frank:password@api.opendesktop.org/v1/forums/data&page=1&pagesize=10> Gets the second page of the list of forums. The pagesize is 10 + +Example: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + </meta> + <data> + <forum> + <id>234</id> + <name>vfvvdsx</name> + <description>test</description> + <date>2005-01-29T18:58:40+01:00</date> + <icon>http://forum.example.org/images/forum-img.png</icon> + <childcount>0</childcount> + <children></children> + <topics>123</topics> + </forum> + <forum> + <id>876</id> + <name>yheweq</name> + <description>foobar</description> + <date>2005-01-29T18:58:40+01:00</date> + <icon>http://forum.example.org/img/forum-icon.gif</icon> + <childcount>1</childcount> + <children> + <forum> + <id>234</id> + <name>cameras</name> + <description>new forum</description> + <date>2005-01-29T18:58:40+01:00</date> + <icon>http://forum.example.org/images/icon.jpg</icon> + <childcount>0</childcount> + <children></children> + <topics>5</topics> + </forum> + </children> + <topics>789</topics> + </forum> + </data> + </ocs> + +#### topics/list + +Gets a list of a specific set of topics. + +* syntax: /v1/forum/topics/list +* HTTP Method: GET +* URL Arguments: forum - Id of the forum you are requesting a list of. Not required if a search term is provided. +* URL Arguments: search - a keyword you want find in the name, +* URL Arguments: description or comment of a topic. Not required if a forum id is provided. +* URL Arguments: sortmode - The sortmode of the list. Possible values are: "new" - newest first or "alpha" - alphabetical +* URL Arguments: page - The list page. You can control the size of a page with the pagesize argument. The first page is 0, the second is 1, +* URL Arguments: pagesize - The amount of entries per page. +* Result: forum topic listing xml +* Statuscodes: + * 100 - successful +Example: <http://frank:password@api.opendesktop.org/v1/forum/topics/list?forum[]=123&search=foo&sortmode=new&page=1> Gets the second page of the list of the newest topics from forum 123 with the string foo in the subject, content or the comment. Additional forums can be specified to be searched by adding further &forum[]= entries to the request. + +Example: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + <totalitems>2</totalitems> + <itemsperpage>10</itemsperpage> + </meta> + <data> + <topic details="detail"> + <id>1</id> + <forumid>123</forumid> + <user>testy</user> + <changed>2009-02-07T23:14:11+01:00</changed> + <subject>Random forum post</subject> + <content>Just testing</content> + <comments>0</comments> + </topic> + </data> + +#### forum/topics/add + +Add a new topic to a forum. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. All arguments are mandatory. + +* syntax: /v1/forum/topic/add +* HTTP Method: POST +* POST Argument: subject - Subject of the new topic +* POST Argument: content - Content of the first post of the new topic +* POST Argument: forum - id of the forum entry to be added to if available +* Result: ocs xml +* Statuscodes: + * 100 - successful + * 101 - please specify all mandatory fields +Example: <http://frank:password@api.opendesktop.org/v1/forum/topic/add> + +Example: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + </meta> + </ocs> + +### BUILDSERVICE + +The build service module handles a user's access to build services, used to create distribution packages for the platforms supported by those services, and afterwards distribute to distribution sites which support the package formats produced by these various services. + + +#### Projects + + +##### create + +Create a new project for the authorized user, optionally inserting information into the project. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. + + * Syntax: /v1/buildservice/project/create + * HTTP method: POST + * Result: project id + * POST Argument: name - string, the project's human readable name + * POST Argument: version - string, the version string for this project + * POST Argument: license - string, with suggestions from the license list (see content/licenses) + * POST Argument: url - url, a web address for the project + * POST Argument: developers - string, a newline separated list of developers on the project. Should be in the form of "Developer Name <email@address>" + * POST Argument: summary - string, a short, one line description of the project. Note: no newlines accepted (if newlines are passed, they will be stripped out) + * POST Argument: description - string, a long description of the project + * POST Argument: requirements - string, describes the required packages for the project, if applicable + * POST Argument: specfile - string, the contents of the spec file + * Mandatory fields: name + * Result: + * projectid (int) + * Statuscodes: + * 100 - success + * 101 - required argument missing: name + * 110 - url was not an acceptable format + * 111 - developers was not in an acceptable format + * 112 - summary contained newlines +Example: POST <http://frank:password@api.opendesktop.org/v1/buildservice/project/create> postdata: name="A Project" developers[0][name]="Frank Karlitschek" developers[0][url]="[[mailto:karlitschek@kde.org|mailto:karlitschek@kde.org]]" developers[1][name]="Dan jensen" developers[1][url]="[[mailto:admin@leinir.dk|mailto:admin@leinir.dk]]" + +This creates a new project and inserts the two listed developers as information on the project. + +Example: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + </meta> + <data> + <projectid>122</projectid> + </data> + </ocs> + +##### get + +Get all information for a specified project. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. + + * Syntax: /v1/buildservice/project/get/"project" + * HTTP method: GET + * URL argument: project - the projectid of the project for which information should be fetched + * Mandatory fields: "project" + * Result: project xml - see buildservice/project/create for data types + * Statuscodes: + * 100 - success + * 101 - no such project + * 102 - project id should be an integer +Example: GET <http://frank:password@api.opendesktop.org/v1/buildservice/project/get/122> + +This might yield the following XML output: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + </meta> + <data> + <project> + <projectid>122</projectid> + <name>A Project</name> + <version>1.0pre1</version> + <license>Creative Commons Attribution Share-Alike 2.0</license> + <url>http://somesite.com/</url> + <developers>Frank Karlitschek <karlitschek@kde.org> + Dan Jensen <admin@leinir.dk></developers> + <summary>A neat little project which does something</summary> + <description>A long description of the project + + which even cleverly includes multiple lines</description> + <requirements></requirements> + <specfile># + # spec file for package a-project + # + # Copyright (C) 2010 Frank Karlitschek (mailto:karlitschek@kde.org) + # Copyright (C) 2010 Dan Jensen (mailto:admin@leinir.dk) + # + + Name: a-project + Summary: A neat little project which does something + + Version: 1.0pre1 + Release: 0 + License: Creative Commons Attribution Share-Alike 2.0 + Url: http://somesite.com/ + BuildRoot: /var/tmp/%name-root + Source: a-project-1.0pre1.tar.bz2 + + %description + A long description of the project + + which even cleverly includes multiple lines + + (etc etc...)</specfile> + </project> + </data> + </ocs> + +##### delete + +Delete a specific project and the uploaded source files. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. + + * Syntax: /v1/buildservice/project/delete/"project" + * HTTP method: POST + * URL argument: project - projectid, the id of the project to be deleted + * Statuscodes: + * 100 - success + * 101 - no such project + * 102 - project id should be an integer + * 110 - project delete failed (details in meta message) +Example: POST <http://frank:password@api.opendesktop.org/v1/buildservice/project/delete/122> + +This might yield the following XML output: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + </meta> + </ocs> + +##### edit + +Set any of the values found on a project. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. + + * Syntax: /v1/buildservice/project/edit/"project" + * HTTP method: POST + * URL argument: project - projectid, the id of the project to change details on + * POST Argument: name - string, the project's human readable name + * POST Argument: version - string, the version string for this project + * POST Argument: license - string, with suggestions from the license list (see content/licenses) + * POST Argument: url - url, a web address for the project + * POST Argument: developers - string, a newline separated list of developers on the project. Should be in the form of "Developer Name <email@address>" + * POST Argument: summary - string, a short, one line description of the project. Note: no newlines accepted (if newlines are passed, they will be stripped out) + * POST Argument: description - string, a long description of the project + * POST Argument: requirements - string, describes the required packages for the project, if applicable + * POST Argument: specfile - string, the contents of the spec file + * Mandatory fields: "project" + * Statuscodes: + * 100 - success + * 101 - no such project + * 102 - projectid no an int + * 110 - url was not an acceptable format + * 111 - developers was not in an acceptable format +Example: POST <http://frank:password@api.opendesktop.org/v1/buildservice/project/edit/122> postdata: name="A Project" summary="A neat little project which does something" + +This might yield the following XML output: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + </meta> + </ocs> + +##### list + +List all projects for the currently authorized user. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. + + * Syntax: /v1/buildservice/project/list + * URL argument: page - The content page. You can control the size of a page with the pagesize parameter. The first page is 0, the second is 1, ... + * URL argument: pagesize - The amount of entries your get per page. + * Result: projectlist xml + * HTTP method: GET + * Statuscodes: + * 100 - success +Example: GET <http://frank:password@api.opendesktop.org/v1/buildservice/project/list> + +This might yield the following XML output (where the user has exactly one project): + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + </meta> + <data> + <projectlist> + <project> + <projectid>122</projectid> + <name>A Project</name> + <version>1.0pre1</version> + <license>Creative Commons Attribution Share-Alike 2.0</license> + <url>http://somesite.com/</url> + <developers>Frank Karlitschek <karlitschek@kde.org> + Dan Jensen <admin@leinir.dk></developers> + <summary>A neat little project which does something</summary> + <description>A long description of the project + + which even cleverly includes multiple lines</description> + <requirements></requirements> + <specfile></specfile> + </project> + </projectlist> + </data> + </ocs> + +##### uploadsource + +Upload a new source bundle (a compressed file in .zip, .tar.gz or .tar.bz2 format) containing the source code of the project. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. + +Note: If the project has not had a source file uploaded yet, and the specfile data field for the project is empty (that is, nothing has been entered manually), this will also fill that field with an automatically generated spec file. + + * Syntax: /v1/buildservice/project/uploadsource/"project" + * HTTP method: POST + * URL argument: project - projectid, the id of the project to generate a spec file for + * POST argument: localfile - The source bundle to upload + * Mandatory fields: "project", "localfile" + * Result: specfile - string, the contents of generated specfile + * Statuscodes: + * 100 - success + * 101 - no such project + * 102 - project id should be an int + * 103 - source bundle file not correctly uploaded + * 104 - source bundle was an unrecognised format +Example: POST <http://frank:password@api.opendesktop.org/v1/buildservice/project/uploadsource/122> + +This might yield the following XML output: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + </meta> + </ocs> + +#### Remote Accounts + + +##### list + +Get a list of all the remote accounts a user has added references to. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. + + * Syntax: /v1/buildservice/remoteaccounts/list + * HTTP method: GET + * Result: remoteaccountslist xml + * id - remoteaccountid (int), the ID of the remote account entry + * type - int, which type of account we're dealing with (1 is buildservice, 2 is publisher) + * typeid - string, the ID of the remote service the account is with + * data - string, any arbitrary data you wish to associate with the account + * login - string, the user's login on the remote service + * password - string, the user's password on the remote service + * Statuscodes: + * 100 - success +Example: GET <http://frank:password@api.opendesktop.org/v1/buildservice/remoteaccounts/list> + +This might yield the following XML output: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + </meta> + <data> + <remoteaccountslist> + <remoteaccount> + <id>2</id> + <type>1</type> + <typeid>mbs</typeid> + <data></data> + <login>frank</login> + <password>password</password> + </remoteaccount> + <remoteaccount> + <id>7</id> + <type>2</type> + <typeid>1</typeid> + <data></data> + <login>frank</login> + <password>password</password> + </remoteaccount> + </remoteaccountslist> + </data> + </ocs> + +##### add + +Add a new remote account reference to a user. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. + + * Syntax: /v1/buildservice/remoteaccounts/add + * HTTP method: POST + * POST argument: type - int, which type of account we're dealing with (1 is buildservice, 2 is publisher) + * POST argument: typeid - string, the ID of the remote service the account is with + * POST argument: data - string, any arbitrary data you wish to associate with the account + * POST argument: login - string, the user's login on the remote service + * POST argument: password - string, the user's password on the remote service + * Mantadory fields: type, typeid + * Result: remoteaccountid + * Statuscodes: + * 100 - success + * 101 - no such service + * 102 - service id was not recognised +Example: POST <http://frank:password@api.opendesktop.org/v1/buildservice/remoteaccounts/add> postdata: type=1 typeid="mbs" + +This might yield the following XML output: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + </meta> + <data> + <remoteaccountid>7</remoteaccountid> + </data> + </ocs> + +##### edit + +Change the details of a specified remote account for the authenticated user. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. + + * Syntax: /v1/buildservice/remoteaccounts/edit/remoteaccountid + * HTTP method: POST + * URL argument: remoteaccountid - the ID of the remote account you wish to change details for + * POST argument: data - string, any arbitrary data you wish to associate with the account + * POST argument: login - string, the user's login on the remote service + * POST argument: password - string, the user's password on the remote service + * Mantadory fields: remoteaccountid + * Result: remoteaccountid + * Statuscodes: + * 100 - success + * 101 - no such remote account +Example: POST <http://frank:password@api.opendesktop.org/v1/buildservice/remoteaccounts/edit/7> postdata: login="frank" password="bet123ter" + +This might yield the following XML output: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + </meta> + </ocs> + +##### get + +Get the details of a specific remote account. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. + + * Syntax: /v1/buildservice/remoteaccounts/get/remoteaccountid + * HTTP method: GET + * Result: remoteaccount xml + * id - remoteaccountid (int), the ID of the remote account entry + * type - int, which type of account we're dealing with (1 is buildservice, 2 is publisher) + * typeid - string, the ID of the remote service the account is with + * data - string, any arbitrary data you wish to associate with the account + * login - string, the user's login on the remote service + * password - string, the user's password on the remote service + * Statuscodes: + * 100 - success + * 101 - no such remote account +Example: GET <http://frank:password@api.opendesktop.org/v1/buildservice/remoteaccounts/get/7> + +This might yield the following XML output: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + </meta> + <data> + <remoteaccount> + <id>7</id> + <type>2</type> + <typeid>1</typeid> + <data></data> + <login>frank</login> + <password>bet123ter</password> + </remoteaccount> + </data> + </ocs> + +##### remove + +Remove the specific remote account from the user's list of remote accounts. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. + + * Syntax: /v1/buildservice/remoteaccounts/remove/remoteaccountid + * HTTP method: POST + * Statuscodes: + * 100 - success + * 101 - no such remote account +Example: POST <http://frank:password@api.opendesktop.org/v1/buildservice/remoteaccounts/remove/7> + +This might yield the following XML output: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + </meta> + </ocs> + +#### Build Services + + +##### list + +Get a list of all the build services available. If the user is not authenticated the complete list of services is returned. If the user is authenticated the list is returned of build services that user is signed up for. Authentication is done by sending a Basic HTTP Authorisation header. + + * Syntax: /v1/buildservice/buildservices/list + * HTTP method: GET + * URL argument: page - The content page. You can control the size of a page with the pagesize parameter. The first page is 0, the second is 1, ... + * URL argument: pagesize - The amount of entries your get per page. + * Mandatory fields: none + * Result: buildservicelist xml + * id - int, alias of buildserviceid, the build service's ID + * name - string, human readable name of build service + * registrationurl - url, link to the service's registration page + * supportedtargets - list of targets, made up of an integer id and a string name + * Statuscodes: + * 100 - success +Example: GET <http://frank:password@api.opendesktop.org/v1/buildservice/buildservices/list> + +This might yield the following XML output: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + </meta> + <data> + <buildservices> + <buildservice> + <id>1</id> + <name>Some Build Service</name> + <registrationurl>http://bs.some.com/user/new</registrationurl> + <supportedtargets> + <target> + <id>1</id> + <name>i386</name> + </target> + <target> + <id>2</id> + <name>x86_64</name> + </target> + <target> + <id>3</id> + <name>armv5</name> + </target> + </supportedtargets> + </buildservice> + </buildservices> + </data> + </ocs> + +##### get + +Get a the information on a particular build service. + + * Syntax: /v1/buildservice/buildservices/get/"buildserviceid" + * HTTP method: GET + * URL argument: buildserviceid - the ID of the build service + * Mandatory fields: "buildserviceid" + * Result: buildservice xml + * id - int, alias of buildserviceid, the build service's ID + * name - string, human readable name of build service + * registrationurl - url, link to the service's registration page + * supportedtargets - list of targets, made up of an integer id and a string name + * Statuscodes: + * 100 - success + * 101 - no such build service +Example: GET <http://frank:password@api.opendesktop.org/v1/buildservice/buildservices/get/1> + +This might yield the following XML output: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + </meta> + <data> + <buildservice> + <id>1</id> + <name>Some Build Service</name> + <registrationurl>http://bs.some.com/user/new</registrationurl> + <supportedtargets> + <target> + <id>1</id> + <name>i386</name> + </target> + <target> + <id>2</id> + <name>x86_64</name> + </target> + <target> + <id>3</id> + <name>armv5</name> + </target> + </supportedtargets> + </buildservice> + </data> + </ocs> + +#### Build Jobs + + +##### list + +List the jobs a user has, optionally for a single project. If projectid is specified, only build jobs for that project are retruned. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. + + * Syntax: /v1/buildservice/jobs/list/"project" + * HTTP method: GET + * URL argument: project - projectid, the id of the project to list build jobs for + * URL argument: page - The content page. You can control the size of a page with the pagesize parameter. The first page is 0, the second is 1, ... + * URL argument: pagesize - The amount of entries your get per page. + * Mandatory fields: none + * Result: buildjoblist xml - a list of build job data + * Statuscodes: + * 100 - success + * 101 - no such project + * 102 - project id should be an int +Example: GET <http://frank:password@api.opendesktop.org/v1/buildservice/jobs/list/122> + +This might yield the following XML output: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + </meta> + <data> + <buildjobs> + <buildjob> + <id>12</id> + <project>122</project> + <buildservice>mbs</buildservice> + <target>2</target> + <name>armv5 job 12</name> + <status>1</status> + <progress>0.56</progress> + <url>http://bs.some.com/job/54322</url> + <message></message> + </buildjob> + <buildjob> + <id>18</id> + <project>122</project> + <buildservice>obs</buildservice> + <target>4</target> + <name>armv5 job 14</name> + <status>1</status> + <progress>0.88</progress> + <url>http://bs.some.com/job/54324</url> + <message></message> + </buildjob> + </buildjobs> + </data> + </ocs> + +##### create + +Create a new build job. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. + + * Syntax: /v1/buildservice/jobs/create/"project"/"buildservice"/"target" + * HTTP method: POST + * URL argument: project - projectid, the id of the project to create a new build job for + * URL argument: buildservice - buildserviceid, the id of the build service to create a new job for + * URL argument: target - string, the target of this job. Must be supported by the build service + * Mandatory fields: "project", "buildservice", "target" + * Result: id - int, aka buildjobid, the id of the newly created build job + * Statuscodes: + * 100 - success + * 101 - no such project + * 102 - project id should be an integer + * 103 - no such build service + * 104 - build service id should be an integer + * 105 - build service does not support target + * 106 - failed to create build job (further information in meta message) +Example: POST <http://frank:password@api.opendesktop.org/v1/buildservice/jobs/create/122/1/armv5> + +This might yield the following XML output: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + </meta> + <data> + <buildjobid>616</buildjobid> + </data> + </ocs> + +##### cancel + +Cancel a build job. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. + + * Syntax: /v1/buildservice/jobs/cancel/"buildjob" + * HTTP method: POST + * URL argument: buildjob - buildjobid, the id of the build which should be cancelled + * Mandatory fields: "buildjob" + * Statuscodes: + * 100 - success + * 101 - no such build job + * 102 - build job id should be an integer + * 103 - job not running + * 104 - failed (further information in meta message) +Example: POST <http://frank:password@api.opendesktop.org/v1/buildservice/jobs/cancel/616> + +This might yield the following XML output: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + </meta> + </ocs> + +##### get + +Get information about a build job. See also getoutput. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. + + * Syntax: /v1/buildservice/jobs/get/"buildjob" + * HTTP method: GET + * URL argument: buildjob - buildjobid, the id of the build job you wish to retrieve information about + * Mandatory fields: "buildjob" + * Result: buildjob xml + * name - string, a human-readable name for the build job + * status describes the current state of the build job, and is an enumeration over the following values + * 1 - Running + * 2 - Completed + * 3 - Failed + * progress - float, 0 to 1. If progress is unknown, 0 is passed + * url - url, link to the page on the build service which shows this particular job's status + * message - string, any message the build service might have + * Statuscodes: + * 100 - success + * 101 - no such build job + * 102 - build job id should be an integer +Example: GET <http://frank:password@api.opendesktop.org/v1/buildservice/jobs/get/616> + +This might yield the following XML output: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + </meta> + <data> + <buildjob> + <id>12</id> + <project>122</project> + <buildservice>mbs</buildservice> + <target>2</target> + <name>armv5 job 12</name> + <status>1</status> + <progress>0.56</progress> + <url>http://bs.some.com/job/54322</url> + <message></message> + </buildjob> + </data> + </ocs> + +##### getoutput + +Get the build output from a specific build job. This is the clear text version of the configuration, compilation and other steps. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. + + * Syntax: /v1/buildservice/jobs/getoutput/"buildjob" + * HTTP method: GET + * URL argument: buildjob - buildjobid, the id of the build job you wish to retrieve the output for + * Mandatory fields: "buildjob" + * Result: output - string, the output of the build service - full output, as in compiler output etc. + * Statuscodes: + * 100 - success + * 101 - no such build job + * 102 - build job id should be an integer +Example: GET <http://frank:password@api.opendesktop.org/v1/buildservice/jobs/getoutput/616> + +This might yield the following XML output: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + </meta> + <data> + <output>-- Found GCC: /usr/bin/gcc + -- Found X11: /usr/lib64/libX11.so + (etc etc) + </output> + </data> + </ocs> + +#### Publishing + + +##### getpublishingcapabilities + +List all the available publishers. In the case of an authenticated user, the function will return only the publishers that the user has an account with. Authentication is done by sending a Basic HTTP Authorisation header. + +Status 102 is informational and in essence is a success. It is meant as a convenient way of finding out whether to bother parsing the list of publishers. + + * Syntax: /v1/buildservice/publishing/getpublishingcapabilities + * HTTP method: GET + * URL argument: page - The content page. You can control the size of a page with the pagesize parameter. The first page is 0, the second is 1, ... + * URL argument: pagesize - The amount of entries your get per page. + * Result: + * publisheridlist - a list of publishers, see buildservice/publishing/getpublisher + * Statuscodes: + * 100 - success + * 101 - no such user + * 102 - user has not registered with any publishers +Example: GET <http://frank:password@api.opendesktop.org/v1/buildservice/publishing/getpublishingcapabilities> + +This might yield the following XML output: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + </meta> + <data> + <publishers> + <publisher> + <id>1</id> + <name>Some App Store</name> + <registrationurl>http://store.some.com/user/new</registrationurl> + <fields> + <field> + <name>Name</name> + <fieldtype>string</fieldtype> + <options></options> + <fieldsize>256</fieldsize> + <required>true</required> + </field> + <field> + <name>Description</name> + <fieldtype>longtext</fieldtype> + <options></options> + <fieldsize>4294967296</fieldsize> + <required>false</required> + </field> + <field> + <name>Category</name> + <fieldtype>item</fieldtype> + <options> + <option>Game</option> + <option>Productivity</option> + <option>Gadget</option> + </options> + <fieldsize>0</fieldsize> + <required>true</required> + </field> + </fields> + <supportedtargets> + <target>i386</target> + <target>x86_64</target> + <target>armv5</target> + </supportedtargets> + </publisher> + <publisher> + <id>2</id> + <name>Somewhere</name> + <registrationurl>http://store.some.where/register</registrationurl> + <fields></fields> + <supportedtargets> + <target>i386</target> + </supportedtargets> + </publisher> + </publishers> + </data> + </ocs> + +##### getpublisher + +Get the descriptive information about a publisher. + + * Syntax: /v1/buildservice/publishing/getpublisher/"publisher" + * HTTP method: GET + * URL argument: publisher - publisherid, the id of the publisher about whom to retrieve + * Mandatory fields: "publisher" + * Result: publisher xml + * name - string, the human-readable name of the field, also used as identifier + * registrationurl - url, an address to give to the user to allow for easy registration + * fields - a list of the supported fields + * id - publisherid, the publisher's ID + * name - string, human readable name + * fieldtype - type name, value from the following itemized list: + * string + * longtext - used for longer descriptions and the like + * integer + * float + * item - an item from the provided list of options + * boolean + * datetime + * url + * image + * options - a list of options. If this is populated on string type, use a combo box to provide the user with suggestions, but accept any string. If two items are present for integer and float values, they represent the lower and upper limits of the values respectively. In the case of a field of type image, the items will be, in order, maximum width and height in pixels, and maximum filesize in bytes. + * fieldsize - int, maximum number of bytes allowed, when applicable (this is 0 if not used) + * required - boolean, whether or not the publisher requires this field + * supportedtargets - list of targets, same naming as in jobs/getbuildcapabilities + * Statuscodes: + * 100 - success + * 101 - no such publisher + * 102 - publisher id should be an integer +Example: GET <http://frank:password@api.opendesktop.org/v1/buildservice/publishing/getpublisher/5> + +This might yield the following XML output: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + </meta> + <data> + <publisher> + <id>1</id> + <name>Some App Store</name> + <registrationurl>http://store.some.com/user/new</registrationurl> + <fields> + <field> + <name>Name</name> + <fieldtype>string</fieldtype> + <options></options> + <fieldsize>256</fieldsize> + <required>true</required> + </field> + <field> + <name>Description</name> + <fieldtype>longtext</fieldtype> + <options></options> + <fieldsize>4294967296</fieldsize> + <required>false</required> + </field> + <field> + <name>Category</name> + <fieldtype>item</fieldtype> + <options> + <option>Game</option> + <option>Productivity</option> + <option>Gadget</option> + </options> + <fieldsize>0</fieldsize> + <required>true</required> + </field> + </fields> + <supportedtargets> + <target>i386</target> + <target>x86_64</target> + <target>armv5</target> + </supportedtargets> + </publisher> + </data> + </ocs> + +##### publishtargetresult + +Publish the result of a specific build job to one publisher. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. + + * Syntax: /v1/buildservice/publishing/publishtargetresult/"buildjob"/"publisher" + * HTTP method: POST + * URL argument: buildjob - buildjobid, the id of the build job which the result should be published + * URL argument: publisher - publisherid, the id of the publisher to publish a result to + * Mandatory fields: "buildjob", "publisher" + * Statuscodes: + * 100 - success + * 103 - no such build job + * 104 - build job not completed + * 105 - build job id should be an integer + * 106 - no such publisher + * 107 - publisher id should be an integer + * 108 - publishing failed (further information in meta message) +Example: POST <http://frank:password@api.opendesktop.org/v1/buildservice/publishing/publishtargetresult/616/5> + +This might yield the following XML output: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + </meta> + </ocs> + +##### savefields + +TODO: This needs a publishing site association as well, otherwise we can't check the field type properly... + +Save field data relating to a particular project. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. + + * Syntax: /v1/buildservice/publishing/savefields/"project" + * HTTP method: POST + * URL argument: project - projectid, the id of the project to save field data for + * POST argument: fields - a list of field data: + * name - string, the name of the field (same identifier as publishing/getpublisher) + * fieldtype - string, the name of the data type, see list in publishing/getpublisher. This allows for two same-named fields to have different data if their field types are different. If the type is + * data - data according to fieldtype + * Mandatory fields: project, fields + * Statuscodes: + * 100 - success + * 101 - no such project + * 102 - project id should be an integer + * 103 - field data not correct (further information in meta message) + * 104 - field data missing (further information in meta message) +Example: POST <http://frank:password@api.opendesktop.org/v1/buildservice/publishing/savefields/122> postdata: fields[0]["name"]="Name" fields[0]["fieldtype"]="string" fields[0]["data"]="A Project" fields[1]["name"]="Category" fields[1]["fieldtype"]="item" fields[1]["data"]="Nifty" + +This might yield the following XML output: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>failed</status> + <statuscode>103</statuscode> + <message>The item "Nifty" does not exist in the list of possible options. The options are: "Game", "Productivity", "Gadget"</message> + </meta> + </ocs> + +##### getfields + +Get the field data from the previous publishing of a particular project. In the case of a project with no field data saved, an empty list will be returned. This should be interpreted as a success, as only saved data is returned, and data for any aditional fields is not included as empty, since the knowledge of which fields are required now is not available. Only authenticated users are allowed to access this method. Authentication is done by sending a Basic HTTP Authorisation header. + + * Syntax: /v1/buildservice/publishing/getfields/"project" + * HTTP method: GET + * URL argument: project - projectid, the id of the project to fetch old field data for + * Mandatory fields: "project" + * Result: fields xml - a list of field data: + * name - string, the name of the field (same identifier as publishing/getpublisher) + * fieldtype - string, the name of the data type, see list in publishing/getpublisher. This allows for two same-named fields to have different data if their field types are different. + * data - data according to fieldtype + * Statuscodes: + * 100 - success + * 101 - no such project + * 102 - project id should be an integer +Example: GET <http://frank:password@api.opendesktop.org/v1/buildservice/publishing/getfields/122> + +This might yield the following XML output: + + <?xml version="1.0"?> + <ocs> + <meta> + <status>ok</status> + <statuscode>100</statuscode> + <message></message> + </meta> + <data> + <fields> + <field> + <name>Name</name> + <fieldtype>string</fieldtype> + <data>A Project</data> + </field> + <field> + <name>Summary</name> + <fieldtype>string</fieldtype> + <data>A neat little project which does something</data> + </field> + <field> + <name>Category</name> + <fieldtype>item</fieldtype> + <data>Gadget</data> + </field> + </fields> + </data> + </ocs> + +--- + +[[CategoryHomepage]] diff --git a/Specifications/recent-file-spec.mdwn b/Specifications/recent-file-spec.mdwn new file mode 100644 index 00000000..bf8ce062 --- /dev/null +++ b/Specifications/recent-file-spec.mdwn @@ -0,0 +1,20 @@ + + +## Recent File Storage Specification + +Many applications choose to have a menu containing a list of recently used files, which can be used as an alternative to opening a file selector. GNOME, and KDE applications have done this for quite some time, and probably others have as well. This specification aims to do the following things: + + * Provide a standard mechanism for storing a list of recently used files (really, URIs) + * Allow for notification of changes in the list + +### Mailinglist + +Discussion of this specification should occur on [[xdg|http:/mailman/listinfo/xdg]]. +### CVS + +The [[CVS|http:GettingInvolved#CVS]] module for this spec is [[recent-file-spec|http://cvs.freedesktop.org/recent-files/recent-file-spec/]]. + + +### Spec + + * Version 0.2 - [[html (one page)|http://standards.freedesktop.org/recent-file-spec/recent-file-spec-0.2.html]] - [[html (multiple pages)|http://standards.freedesktop.org/recent-file-spec/0.2/]] - [[xml|http://standards.freedesktop.org/recent-file-spec/recent-file-spec-0.2.xml]]
\ No newline at end of file diff --git a/Specifications/secret-storage-spec.mdwn b/Specifications/secret-storage-spec.mdwn new file mode 100644 index 00000000..aaa0bea7 --- /dev/null +++ b/Specifications/secret-storage-spec.mdwn @@ -0,0 +1,25 @@ + + +## Secret Storage + +The Secrets API allows client applications to store secrets securely using a service running in the user's login session. + + +### Drafting Process + +This API is currently being drafted in cooperation by the [[GNOME Keyring|http://live.gnome.org/GnomeKeyring]] and the [[KDE Wallet|http://utils.kde.org/projects/kwalletmanager]] developers. Everyone's welcome to join the discussion and drafting process on our [[mailinglist|http://lists.freedesktop.org/mailman/listinfo/Authentication]]. + + +### Mailinglist + +Discussion of this specification should occur on the [[Authentication mailing list|http://lists.freedesktop.org/mailman/listinfo/Authentication]]. + + +### GIT + +The specifiation draft is currently hosted on a Gitorious branch of the xdg-specs repository: [[xdg-secrets-api branch|http://gitorious.org/+xdg-secrets-api/xdg-specs/secrets-xdg-specs]]. + + +### Spec + + * Version 0.1 Working Draft - [[html (multiple pages)|http://code.confuego.org/secrets-xdg-specs/]], [[xml (D-BUS Introspection)|http://www.gnome.org/~stefw/secrets/org.freedesktop.Secrets.xml]]
\ No newline at end of file diff --git a/Specifications/secret-storage-spec/secrets-api-0.1.html b/Specifications/secret-storage-spec/secrets-api-0.1.html new file mode 100644 index 00000000..a6065077 --- /dev/null +++ b/Specifications/secret-storage-spec/secrets-api-0.1.html @@ -0,0 +1,616 @@ +<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Secrets API Specification</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2"> +<style type="text/css"> +.synopsis, .classsynopsis +{ + background: #eeeeee; + border: solid 1px #aaaaaa; + padding: 0.5em; +} +.programlisting +{ + background: #eeeeff; + border: solid 1px #aaaaff; + padding: 0.5em; +} +.variablelist +{ + padding: 4px; + margin-left: 3em; +} +.variablelist td:first-child +{ + vertical-align: top; +} + +/* this is needed so that the local anchors are displayed below the naviagtion */ +@media screen { + sup a.footnote + { + position: relative; + top: 0em ! important; + } + div.refnamediv a[name], div.refsect1 a[name] + { + position: relative; + top: -4.5em; + } + table.navigation#top + { + margin-top: 0; + margin-bottom: 0; + top: 0; + left: 0; + height: 2em; + z-index: 1; + } + .navigation a + { + color: #770000; + } + .navigation a:visited + { + color: #550000; + } + td.shortcuts + { + color: #770000; + font-size: 80%; + white-space: nowrap; + } + div.refentry, div.chapter, div.reference, div.part, div.book, div.glossary, div.sect1, div.appendix, div.preface + { + position: relative; + z-index: 0; + } + div.glossary, div.index + { + position: relative; + top: 2em; + z-index: 0; + } + div.refnamediv + { + margin-top: 2em; + } + body + { + padding-bottom: 20em; + } +} +@media print { + table.navigation { + visibility: collapse; + display: none; + } + div.titlepage table.navigation { + visibility: visible; + display: table; + background: #ffeeee; + border: solid 1px #ffaaaa; + margin-top: 0; + margin-bottom: 0; + top: 0; + left: 0; + height: 2em; + } +} + +.navigation .title +{ + font-size: 200%; +} + + +div.gallery-float +{ + float: left; + padding: 10px; +} +div.gallery-float img +{ + border-style: none; +} +div.gallery-spacer +{ + clear: both; +} +a +{ + text-decoration: none; +} +a:hover +{ + text-decoration: underline; + color: #FF0000; +} + +div.table table +{ + border-collapse: collapse; + border-spacing: 0px; + border-style: solid; + border-color: #777777; + border-width: 1px; +} + +div.table table td, div.table table th +{ + border-style: solid; + border-color: #777777; + border-width: 1px; + padding: 3px; + vertical-align: top; +} + +div.table table th +{ + background-color: #eeeeee; +} + +hr +{ + color: #777777; + background: #777777; + border: 0; + height: 1px; + clear: both; +} + +.footer +{ + padding-top: 3.5em; + color: #777777; + text-align: center; + font-size: 80%; +} +</style> +<link rel="part" href="#description" title="PartI.API Documentation"><link rel="chapter" href="#id315029" title="Introduction"><link rel="chapter" href="#id310129" title="Secrets"><link rel="chapter" href="#id326331" title="Collection and Items"><link rel="chapter" href="#id286004" title="Lookup Attributes"><link rel="chapter" href="#sessions" title="Sessions"><link rel="chapter" href="#transfer-secrets" title="Transfer of Secrets"><link rel="chapter" href="#authentication-unlocking" title="Authentication or Unlocking"><link rel="chapter" href="#id284685" title="What's not included in the API"><link rel="chapter" href="#id284710" title="Notes for Service Implementors"><link rel="part" href="#ref-dbus-api" title="PartII.D-Bus API Reference"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="book" lang="en"><div class="titlepage"><div><div><table class="navigation" id="top" width="100%" cellpadding="2" cellspacing="0"><tr><th valign="middle"><p class="title">Secrets API Specification</p></th></tr></table></div><div><div class="authorgroup"><div class="author"><h3 class="author"><span class="firstname">Stef</span> <span class="surname">Walter</span></h3><div class="affiliation"><span class="jobtitle">GNOME Keyring Developer<br></span><div class="address"><p><br> + <code class="email"><<a class="email" href="mailto:stef@memberwebs.com">stef@memberwebs.com</a>></code><br> + </p></div></div></div><div class="author"><h3 class="author"><span class="firstname">Michael</span> <span class="surname">Leupold</span></h3><div class="affiliation"><span class="jobtitle">KWallet Developer<br></span><div class="address"><p><br> + <code class="email"><<a class="email" href="mailto:lemma@confuego.org">lemma@confuego.org</a>></code><br> + </p></div></div></div></div></div><div><p class="releaseinfo"> + Secrets 0.1 + + </p></div><div><p class="copyright">Copyright 2008-2009 The Secrets API Authors</p></div></div><hr></div><div class="toc"><dl><dt><span class="part"><a href="#description">I. API Documentation</a></span></dt><dd><dl><dt><span class="chapter"><a href="#id315029">Introduction</a></span></dt><dt><span class="chapter"><a href="#id310129">Secrets</a></span></dt><dt><span class="chapter"><a href="#id326331">Collection and Items</a></span></dt><dt><span class="chapter"><a href="#id286004">Lookup Attributes</a></span></dt><dt><span class="chapter"><a href="#sessions">Sessions</a></span></dt><dt><span class="chapter"><a href="#transfer-secrets">Transfer of Secrets</a></span></dt><dd><dl><dt><span class="sect1"><a href="#id285286">Negotiation of Algorithms</a></span></dt><dt><span class="sect1"><a href="#id285353">Algorithm: PLAIN</a></span></dt><dt><span class="sect1"><a href="#id330177">Algorithm: DH-GROUP-???+AES-128</a></span></dt></dl></dd><dt><span class="chapter"><a href="#authentication-unlocking">Authentication or Unlocking</a></span></dt><dt><span class="chapter"><a href="#id284685">What's not included in the API</a></span></dt><dt><span class="chapter"><a href="#id284710">Notes for Service Implementors</a></span></dt></dl></dd><dt><span class="part"><a href="#ref-dbus-api">II. D-Bus API Reference</a></span></dt><dd><dl><dt><span class="refentrytitle"><a href="#object-paths">Object Paths</a></span><span class="refpurpose"></span></dt><dt><span class="refentrytitle"><a href="#eggdbus-interface-org.freedesktop.Secrets.Collection">org.freedesktop.Secrets.Collection Interface</a></span><span class="refpurpose"> — Collection of items</span></dt><dt><span class="refentrytitle"><a href="#eggdbus-interface-org.freedesktop.Secrets.Item">org.freedesktop.Secrets.Item Interface</a></span><span class="refpurpose"> — Item wraps a secret</span></dt><dt><span class="refentrytitle"><a href="#eggdbus-interface-org.freedesktop.Secrets.Service">org.freedesktop.Secrets.Service Interface</a></span><span class="refpurpose"> — Manages collections and sessions</span></dt><dt><span class="refentrytitle"><a href="#eggdbus-interface-org.freedesktop.Secrets.Session">org.freedesktop.Secrets.Session Interface</a></span><span class="refpurpose"> — Client application session</span></dt><dt><span class="refentrytitle"><a href="#eggdbus-structmain-Secret">Secret Structure</a></span><span class="refpurpose"> — A secret</span></dt><dt><span class="refentrytitle"><a href="#eggdbus-enummain-Error">org.freedesktop.Secrets.Error.* Error Domain</a></span><span class="refpurpose"> — Errors</span></dt></dl></dd></dl></div><div class="part" lang="en"><div class="titlepage"><div><div><h1 class="title"><a name="description"></a>PartI.API Documentation</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="chapter"><a href="#id315029">Introduction</a></span></dt><dt><span class="chapter"><a href="#id310129">Secrets</a></span></dt><dt><span class="chapter"><a href="#id326331">Collection and Items</a></span></dt><dt><span class="chapter"><a href="#id286004">Lookup Attributes</a></span></dt><dt><span class="chapter"><a href="#sessions">Sessions</a></span></dt><dt><span class="chapter"><a href="#transfer-secrets">Transfer of Secrets</a></span></dt><dd><dl><dt><span class="sect1"><a href="#id285286">Negotiation of Algorithms</a></span></dt><dt><span class="sect1"><a href="#id285353">Algorithm: PLAIN</a></span></dt><dt><span class="sect1"><a href="#id330177">Algorithm: DH-GROUP-???+AES-128</a></span></dt></dl></dd><dt><span class="chapter"><a href="#authentication-unlocking">Authentication or Unlocking</a></span></dt><dt><span class="chapter"><a href="#id284685">What's not included in the API</a></span></dt><dt><span class="chapter"><a href="#id284710">Notes for Service Implementors</a></span></dt></dl></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="id315029"></a>Introduction</h2></div></div></div><p>The Secrets API allows client applications to store secrets securily in a + service running in the user's login session. </p><p>The secrets are usually stored in an encrypted manner by the service. The + service may need to be unlocked and/or authenticated by the user before the + secrets become available for retrieval by client applications.</p><p>The Secrets service stores a secret along with a set of lookup attributes. + The attributes can be used to lookup and retrieve a secret at a later date. The + lookup attributes are not treated as secret material, and the service may choose + to not encrypt attributes when storing them to disk.</p></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="id310129"></a>Secrets</h2></div></div></div><p>A secret is something an application wishes to store securely. A good example + is a password that an application needs to save and use at a later date.</p><p>Within this API a secret value is treated as an array of bytes. It is + recommended that a secret consist of user readable text, although this API has + no such requirement.</p><p>Applications wishing to store multiple values as part of a single secret, may + choose to use a textual format to combine these values into one. For example, the + 'desktop' key file format, or XML or another form of markup.</p><p>Secrets may be <GTKDOCLINK HREF="transfer-of-secrets">encrypted when transferred</GTKDOCLINK> + to the client application and vice versa.</p><p>The <a class="link" href="#eggdbus-structmain-Secret" title="Secret Structure">Secret structure</a> encapsulates + a secret value along with it's transfer encryption parameters.</p></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="id326331"></a>Collection and Items</h2></div></div></div><p>Each secret is stored together with + <GTKDOCLINK HREF="lookup-attributes">lookup attributes</GTKDOCLINK> and a label. These together + form an <a class="link" href="#eggdbus-interface-org.freedesktop.Secrets.Item" title="org.freedesktop.Secrets.Item Interface">item</a>.</p><p>A group of items together form a + <a class="link" href="#eggdbus-interface-org.freedesktop.Secrets.Collection" title="org.freedesktop.Secrets.Collection Interface">collection</a>. + A collection is similar in concept to the terms 'keyring' or 'wallet'.</p><p>Collections and items are represented as DBus objects, and each have their own + object paths. However these may change from time to time.</p><p>It is strongly recommended that client applications use + <GTKDOCLINK HREF="lookup-attributes">lookup attributes</GTKDOCLINK> to find items rather than + recording the object path of a stored item. This allows maximum interoperability.</p><p>An item or a collection may be initially in a locked state. When in a locked + state the item or collection may not be modified in any way, and the secret may not + be read. Client applications that require access to the secret of a locked item, or + desire to modify a locked item, should <a class="link" href="#authentication-unlocking" title="Authentication or Unlocking">unlock it before use</a>.</p><p>The service must prevent locked collections or items from modification. On + such an invalid access the + <a class="link" href="#eggdbus-constant-Error.org.freedesktop.Secrets.Error.IsLocked">IsLocked</a> + error should be raised.</p><p>Client applications without special requirements should store in the default + collection. Use the + <a class="link" href="#eggdbus-property-org.freedesktop.Secrets.Service:DefaultCollection" title='The "DefaultCollection" property'>DefaultCollection</a> + property on the Service interface to determine the default collection. In addition + the default collection is always accessible through a + <a class="link" href="#object-paths" title="Object Paths">specific object path</a>.</p><p>Client applications with special needs can create a new collection by calling the + <GTKDOCLINK HREF="eggdbus-property-org.freedesktop.Secrets.Service.CreateCollection">CreateCollection()</GTKDOCLINK> + method on the Service interface. A client application must have + <a class="link" href="#sessions" title="Sessions">opened a session</a> before a collection can be created. The </p><p>A collection may be marked as private on creation. A private collection and the + items within it may only be unlocked by the application that created the collection. + Service implementors may choose not to implement this feature and should ignore the + private argument when + <a class="link" href="#eggdbus-method-org.freedesktop.Secrets.Service.CreateCollection" title="CreateCollection ()">creating a collection</a>. + Client applications that demand this feature, should check the the + <a class="link" href="#eggdbus-property-org.freedesktop.Secrets.Collection:Private" title='The "Private" property'>Private property</a> + after creating a collection to see if the request for a private collection was ignored.</p><p>A collection can be deleted by calling the + <GTKDOCLINK HREF="eggdbus-property-org.freedesktop.Secrets.Collection.Delete">Delete()</GTKDOCLINK> + method on the Service interface. A client application must have + <a class="link" href="#sessions" title="Sessions">opened a session</a> before a collection can be created. + However the collection does not need to be unlocked. In addition private collections can + be deleted by any application.</p></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="id286004"></a>Lookup Attributes</h2></div></div></div><p>Attributes can and should be stored with a secret to facilitate lookup + of the secret at a later date.</p><p>An attribute constists of a name, and a value. Both parts are simple + strings.</p><p>The service may have additional requirements as to what can be present + in an attribute name. It is recommended that attribute names are human + readable, and kept simple for the sake of simplicity.</p><p>During a lookup, attribute names and values are matched via case-sensitive + string equality.</p><p>It's important to remember that attributes are not part of the secret. + Services implementing this API will probably store attributes in an unencrypted + manner in order to support simple and effecient lookups.</p></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="sessions"></a>Sessions</h2></div></div></div><p>A session is established between a client application and a service. A session + is used to unlock items and collections when necessary. It is also used to + <a class="link" href="#transfer-secrets" title="Transfer of Secrets">negotiate encryption of transferred secrets</a> + between the client application and the service.</p><p>A session is established by calling the service's + <a class="link" href="#eggdbus-method-org.freedesktop.Secrets.Service.OpenSession" title="OpenSession ()">OpenSession()</a> + method. Once established, a session is bound to calling application's connection to + the DBus session bus. Generally only one session can be established per client + application. Calling OpenSession() a second time results in an + <a class="link" href="#eggdbus-constant-Error.org.freedesktop.Secrets.Error.AlreadyExists">AlreadyExists</a> + error.</p><p>A session is closed when the client application disconnects from the DBus + session bus. Alternatively the client application can call the + <a class="link" href="#eggdbus-method-org.freedesktop.Secrets.Session.Close" title="Close ()">Close()</a> + method on the session interface. Once a session is closed all session specific + negotiations and authentication should be dropped by the service.</p></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="transfer-secrets"></a>Transfer of Secrets</h2></div></div></div><div class="toc"><dl><dt><span class="sect1"><a href="#id285286">Negotiation of Algorithms</a></span></dt><dt><span class="sect1"><a href="#id285353">Algorithm: PLAIN</a></span></dt><dt><span class="sect1"><a href="#id330177">Algorithm: DH-GROUP-???+AES-128</a></span></dt></dl></div><p>Since this is a D-Bus API, the data in all method calls and other accesses + in this API will go through multiple processes, and may be cached arbitrarily + by the OS or elsewhere.</p><p>The Secrets API has provision to encrypt secrets while in transit between + the service and the client application.</p><p>The encryption is not envisioned to withstand man in the middle attacks, or + other active attacks. It is envisioned to minimize storage of plain text secrets + in memory and prevent storage plain text storage of secrets in a swap file or other + caching mechanism.</p><p>Many client applications may choose not to make use of the provisions to + encrypt secrets in transit. In fact for applications unable to prevent their own + memory from being paged to disk (eg: Java, C# or Python apps), transfering + encrypted secrets would be an excersize of questionable value.</p><p>This API was desigened by GNOME and KDE developers with the goal of having + a common way to store secrets. It's predecessors are the desktop specific APIs + used by GNOME Keyring and KWallet.</p><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id285286"></a>Negotiation of Algorithms</h2></div></div></div><p>In order to encrypt secrets in transit, the service and the client + application must agree on an algorithm, and some algorithm specific + parameters (eg: a key).</p><p>The client application opens a <a class="link" href="#sessions" title="Sessions">session</a> + with the service, and then calls the + <a class="link" href="#eggdbus-method-org.freedesktop.Secrets.Session.Negotiate" title="Negotiate ()"> + Negotiate() method</a> on that session. The algorithms argument to the + Negotiate() method specifies a set of algorithms to be used together for + key agreement and encryption. The other arguments are algorithm specific.</p><p>If a service does not support a specific set of algorithms, a + <a class="link" href="#eggdbus-constant-Error.org.freedesktop.Secrets.Error.NotSupported">NotSupported</a> + error is returned, and the client is free to try another set of algorithms. + The <span class="emphasis"><em>PLAIN</em></span> algorithm is almost always supported.</p><p>An algorithm may require that the Negotiate() method is called multiple + times in succession to be complete. Each iteration transfers algorithm specific + data back forth between the service and the client.</p><p>Once an algorithm has been negotiated, it is used for all transfer of secrets + between the service and the client application in both directions. Algorithm + specific parameters may be transfered with each + <a class="link" href="#eggdbus-structmain-Secret" title="Secret Structure">secret</a>.</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id285353"></a>Algorithm: PLAIN</h2></div></div></div><table class="simplelist" border="0" summary="Simple list"><tr><td>Algorithm string: <span class="emphasis"><em>PLAIN</em></span></td></tr><tr><td><a class="link" href="#eggdbus-method-org.freedesktop.Secrets.Session.Negotiate" title="Negotiate ()"> + Negotiate input</a>: empty string</td></tr><tr><td><a class="link" href="#eggdbus-method-org.freedesktop.Secrets.Session.Negotiate" title="Negotiate ()"> + Negotiate output</a>: empty string</td></tr><tr><td><a class="link" href="#eggdbus-struct-Secret" title="The Secret Structure"> + Secret parameter</a>: empty string</td></tr></table><p>The plain algorithm does no encryption whatsoever.</p><p>It is strongly recommended that a service implementing this API support + the <span class="emphasis"><em>PLAIN</em></span> algorithm.</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id330177"></a>Algorithm: DH-GROUP-???+AES-128</h2></div></div></div><table class="simplelist" border="0" summary="Simple list"><tr><td>Algorithm string: <span class="emphasis"><em>DH-GROUP-???+AES-128</em></span></td></tr><tr><td><a class="link" href="#eggdbus-method-org.freedesktop.Secrets.Session.Negotiate" title="Negotiate ()"> + Negotiate input</a>: ???TODO??? </td></tr><tr><td><a class="link" href="#eggdbus-method-org.freedesktop.Secrets.Session.Negotiate" title="Negotiate ()"> + Negotiate output</a>: ???TODO???</td></tr><tr><td><a class="link" href="#eggdbus-struct-Secret" title="The Secret Structure"> + Secret parameter</a>: 16 byte AES Initialization Vector.</td></tr></table><p>TODO: Document</p></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="authentication-unlocking"></a>Authentication or Unlocking</h2></div></div></div><p>Some items and/or collections may be marked as locked by the service. + The secrets of locked items cannot be accessed. Locked items or collections + cannot be modified by the client application.</p><p>In order to unlock an item or collection a + <a class="link" href="#sessions" title="Sessions">session</a> is established by the client application, + and the + <a class="link" href="#eggdbus-method-org.freedesktop.Secrets.Session.BeginAuthenticate" title="BeginAuthenticate ()">BeginAuthenticate()</a> + method is called with one or more DBus object paths of items or collections. The + BeginAuthenticate() method is asynchronous and may return before the item is + actually unlocked.</p><p>The service will then unlock the item or collection, perhaps by prompting the + user for a password, or it could require use a hardware token of some sort.</p><p>After the service tries to unlock an item or collection, whether successfully + or unsuccessfully, the + <a class="link" href="#eggdbus-signal-org.freedesktop.Secrets.Session::Authenticated" title='The "Authenticated" signal'>Authenticated</a> + signal on the session interface is emitted.</p><p>The client application may, but is not required to, call the + <a class="link" href="#eggdbus-method-org.freedesktop.Secrets.Session.CompleteAuthenticate" title="CompleteAuthenticate ()">CompleteAuthenticate()</a> + method. One or more DBus object paths of items or collections that BeginAuthenticate() + was previously called with, can be passed in. The CompleteAuthenticate() returns the + items that were successfully authenticated. In addition if the unlock process is not + yet complete for some items or collections, the service should stop trying to ask the + user to unlock or authenticate them.</p><p>It's up to the service whether to unlock items individually, or collections as a + whole. The client application should act as if it must unlock each item individually.</p><p>A service may upon unlocking a collection, unlock all items in that collection. If + a service is not able to unlock an item individually, it should treat a request to unlock + an item as a request to unlock the connection that the item is in. The Authenticated signal + should however still be emitted for the individual items that were requested to be unlocked.</p><p>A service may choose to authenticate items or collections just for a single client + application. Alternatively the service may choose to allow any client application to access + items or collections authenticated by a single client application. A client application + should always be ready to call BeginAuthenticate() the secrets it needs, or objects it must + modify. It must not assume that an item is already unlocked for whatever reason.</p></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="id284685"></a>What's not included in the API</h2></div></div></div><p>A service may implement additional DBus interfaces for further capabilities not + included in this specification. Password management applications or other narrowly + focused tools should make use of these when necessary.</p><p>This specification does not mandate the use of master passwords to lock a + collection of secrets. The service may choose to implement any method for authenticating + secrets.</p><p>This specification does not mandate any form of access control. The service may + choose to allow certain applications to access a keyring, and others.</p><p>[TODO: complete]</p></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="id284710"></a>Notes for Service Implementors</h2></div></div></div><p>[TODO: complete]</p></div></div><div class="part" lang="en"><div class="titlepage"><div><div><h1 class="title"><a name="ref-dbus-api"></a>PartII.D-Bus API Reference</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="refentrytitle"><a href="#object-paths">Object Paths</a></span><span class="refpurpose"></span></dt><dt><span class="refentrytitle"><a href="#eggdbus-interface-org.freedesktop.Secrets.Collection">org.freedesktop.Secrets.Collection Interface</a></span><span class="refpurpose"> — Collection of items</span></dt><dt><span class="refentrytitle"><a href="#eggdbus-interface-org.freedesktop.Secrets.Item">org.freedesktop.Secrets.Item Interface</a></span><span class="refpurpose"> — Item wraps a secret</span></dt><dt><span class="refentrytitle"><a href="#eggdbus-interface-org.freedesktop.Secrets.Service">org.freedesktop.Secrets.Service Interface</a></span><span class="refpurpose"> — Manages collections and sessions</span></dt><dt><span class="refentrytitle"><a href="#eggdbus-interface-org.freedesktop.Secrets.Session">org.freedesktop.Secrets.Session Interface</a></span><span class="refpurpose"> — Client application session</span></dt><dt><span class="refentrytitle"><a href="#eggdbus-structmain-Secret">Secret Structure</a></span><span class="refpurpose"> — A secret</span></dt><dt><span class="refentrytitle"><a href="#eggdbus-enummain-Error">org.freedesktop.Secrets.Error.* Error Domain</a></span><span class="refpurpose"> — Errors</span></dt></dl></div><div class="refentry" lang="en"><a name="object-paths"></a><div class="titlepage"></div><p>The various DBus object paths used with the Secrets API are designed to be human + readable but not displayed to the user.</p><div class="refsect1" lang="en"><a name="id284749"></a><pre class="programlisting">/org/freedesktop/Secrets</pre><p>The object path for the service.</p></div><div class="refsect1" lang="en"><a name="id330445"></a><pre class="programlisting">/org/freedesktop/Secrets/collection/<span class="emphasis"><em>xxxx</em></span></pre><p>The object path for a collection, where <span class="emphasis"><em>xxxx</em></span> represents a + possibly encoded or truncated version of the initial label of the collection.</p></div><div class="refsect1" lang="en"><a name="id330463"></a><pre class="programlisting">/org/freedesktop/Secrets/collection/<span class="emphasis"><em>xxxx</em></span>/<span class="emphasis"><em>iiii</em></span></pre><p>The object path for an item, where <span class="emphasis"><em>xxxx</em></span> is the collection (above) + and <span class="emphasis"><em>iiii</em></span> is an auto-generated item specific identifier.</p></div><div class="refsect1" lang="en"><a name="id330487"></a><pre class="programlisting">/org/freedesktop/Secrets/session/<span class="emphasis"><em>ssss</em></span></pre><p>The object path for a session, where <span class="emphasis"><em>ssss</em></span> is an auto-generated + session specific identifier.</p></div><div class="refsect1" lang="en"><a name="id330504"></a><pre class="programlisting">/org/freedesktop/Secrets/default</pre><p>The default collection for client applications to store secrets is available under + this object path in addition to its real object path (above).</p></div></div><div class="refentry" lang="en"><a name="eggdbus-interface-org.freedesktop.Secrets.Collection"></a><div class="titlepage"></div><div class="refnamediv"><table width="100%"><tr><td valign="top"><h2><span class="refentrytitle">org.freedesktop.Secrets.Collection Interface</span></h2><p>org.freedesktop.Secrets.Collection Interface — Collection of items</p></td><td valign="top" align="right"></td></tr></table></div><div class="refsynopsisdiv"><h2>Methods</h2><pre class="synopsis"> +<a class="link" href="#eggdbus-method-org.freedesktop.Secrets.Collection.Delete" title="Delete ()">Delete</a> () +<a class="link" href="#eggdbus-method-org.freedesktop.Secrets.Collection.SearchItems" title="SearchItems ()">SearchItems</a> (IN Dict<String,String> fields, + OUT Array<ObjectPath> results) +<a class="link" href="#eggdbus-method-org.freedesktop.Secrets.Collection.CreateItem" title="CreateItem ()">CreateItem</a> (IN Dict<String,String> fields, + IN <a class="link" href="#eggdbus-struct-Secret" title="The Secret Structure">Secret</a> secret, + IN String label, + IN Boolean replace, + OUT ObjectPath item) + </pre></div><div class="refsect1" lang="en"><a name="id348033"></a><h2>Signals</h2><pre class="synopsis"> +<a class="link" href="#eggdbus-signal-org.freedesktop.Secrets.Collection::CreatedItem" title='The "CreatedItem" signal'>CreatedItem</a> (ObjectPath item) +<a class="link" href="#eggdbus-signal-org.freedesktop.Secrets.Collection::DeletedItem" title='The "DeletedItem" signal'>DeletedItem</a> (ObjectPath item) + </pre></div><div class="refsect1" lang="en"><a name="id348062"></a><h2>Properties</h2><pre class="synopsis"> +<a class="link" href="#eggdbus-property-org.freedesktop.Secrets.Collection:Items" title='The "Items" property'>Items</a> readable Array<ObjectPath> +<a class="link" href="#eggdbus-property-org.freedesktop.Secrets.Collection:Private" title='The "Private" property'>Private</a> readable String +<a class="link" href="#eggdbus-property-org.freedesktop.Secrets.Collection:Label" title='The "Label" property'>Label</a> readwrite String +<a class="link" href="#eggdbus-property-org.freedesktop.Secrets.Collection:Locked" title='The "Locked" property'>Locked</a> readable String +<a class="link" href="#eggdbus-property-org.freedesktop.Secrets.Collection:Created" title='The "Created" property'>Created</a> readable UInt64 +<a class="link" href="#eggdbus-property-org.freedesktop.Secrets.Collection:Modified" title='The "Modified" property'>Modified</a> readable UInt64 + </pre></div><div class="refsect1" lang="en"><a name="id348115"></a><h2>Description</h2><p> +A collection of items containing secrets. + </p></div><div class="refsect1" lang="en"><a name="id348130"></a><h2>Method Details</h2><div class="refsect2" lang="en"><a name="eggdbus-method-org.freedesktop.Secrets.Collection.Delete"></a><h3>Delete ()</h3><pre class="programlisting"> +Delete () + </pre><p> +Delete this collection. + </p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="eggdbus-method-org.freedesktop.Secrets.Collection.SearchItems"></a><h3>SearchItems ()</h3><pre class="programlisting"> +SearchItems (IN Dict<String,String> fields, + OUT Array<ObjectPath> results) + </pre><p> +Search for items in this collection matching the lookup fields. + </p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><p><span class="term"><code class="literal">IN Dict<String,String> <em class="parameter"><code>fields</code></em></code>:</span></p></td><td><p> +Fields to match. + </p></td></tr><tr><td><p><span class="term"><code class="literal">OUT Array<ObjectPath> <em class="parameter"><code>results</code></em></code>:</span></p></td><td><p> +Items that matched the fields. + </p></td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="eggdbus-method-org.freedesktop.Secrets.Collection.CreateItem"></a><h3>CreateItem ()</h3><pre class="programlisting"> +CreateItem (IN Dict<String,String> fields, + IN <a class="link" href="#eggdbus-struct-Secret" title="The Secret Structure">Secret</a> secret, + IN String label, + IN Boolean replace, + OUT ObjectPath item) + </pre><p> +Create an item with the given fields, secret and label. If replace is set, then it replaces an item already present with the same values for the fields. + </p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><p><span class="term"><code class="literal">IN Dict<String,String> <em class="parameter"><code>fields</code></em></code>:</span></p></td><td><p> +The lookup fields for the new item. + </p></td></tr><tr><td><p><span class="term"><code class="literal">IN <a class="link" href="#eggdbus-struct-Secret" title="The Secret Structure">Secret</a> <em class="parameter"><code>secret</code></em></code>:</span></p></td><td><p> +The secret to store in the new item. + </p></td></tr><tr><td><p><span class="term"><code class="literal">IN String <em class="parameter"><code>label</code></em></code>:</span></p></td><td><p> +The label for the new item. + </p></td></tr><tr><td><p><span class="term"><code class="literal">IN Boolean <em class="parameter"><code>replace</code></em></code>:</span></p></td><td><p> +Whether to replace an item with the same fields or not. + </p></td></tr><tr><td><p><span class="term"><code class="literal">OUT ObjectPath <em class="parameter"><code>item</code></em></code>:</span></p></td><td><p> +The new item, or previous item if replaced. + </p></td></tr></tbody></table></div></div></div><div class="refsect1" lang="en"><a name="id348414"></a><h2>Signal Details</h2><div class="refsect2" lang="en"><a name="eggdbus-signal-org.freedesktop.Secrets.Collection::CreatedItem"></a><h3>The "CreatedItem" signal</h3><pre class="programlisting"> +CreatedItem (ObjectPath item) + </pre><p> +A new item in this collection was created. + </p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><p><span class="term"><code class="literal">ObjectPath <em class="parameter"><code>item</code></em></code>:</span></p></td><td><p> +The item that was created. + </p></td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="eggdbus-signal-org.freedesktop.Secrets.Collection::DeletedItem"></a><h3>The "DeletedItem" signal</h3><pre class="programlisting"> +DeletedItem (ObjectPath item) + </pre><p> +An item in this collection was deleted. + </p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><p><span class="term"><code class="literal">ObjectPath <em class="parameter"><code>item</code></em></code>:</span></p></td><td><p> +The item that was deleted. + </p></td></tr></tbody></table></div></div></div><div class="refsect1" lang="en"><a name="id348534"></a><h2>Property Details</h2><div class="refsect2" lang="en"><a name="eggdbus-property-org.freedesktop.Secrets.Collection:Items"></a><h3>The "Items" property</h3><pre class="programlisting"> +Items readable Array<ObjectPath> + </pre><p> +Items in this collection. + </p></div><hr><div class="refsect2" lang="en"><a name="eggdbus-property-org.freedesktop.Secrets.Collection:Private"></a><h3>The "Private" property</h3><pre class="programlisting"> +Private readable String + </pre><p> +Whether this is a private collection or not. + </p></div><hr><div class="refsect2" lang="en"><a name="eggdbus-property-org.freedesktop.Secrets.Collection:Label"></a><h3>The "Label" property</h3><pre class="programlisting"> +Label readwrite String + </pre><p> +The displayable label of this collection. + </p></div><hr><div class="refsect2" lang="en"><a name="eggdbus-property-org.freedesktop.Secrets.Collection:Locked"></a><h3>The "Locked" property</h3><pre class="programlisting"> +Locked readable String + </pre><p> +Whether the collection is locked and must be authenticated by the client application. + </p></div><hr><div class="refsect2" lang="en"><a name="eggdbus-property-org.freedesktop.Secrets.Collection:Created"></a><h3>The "Created" property</h3><pre class="programlisting"> +Created readable UInt64 + </pre><p> +The unix time when the collection was created. + </p></div><hr><div class="refsect2" lang="en"><a name="eggdbus-property-org.freedesktop.Secrets.Collection:Modified"></a><h3>The "Modified" property</h3><pre class="programlisting"> +Modified readable UInt64 + </pre><p> +The unix time when the collection was last modified. + </p></div></div></div><div class="refentry" lang="en"><a name="eggdbus-interface-org.freedesktop.Secrets.Item"></a><div class="titlepage"></div><div class="refnamediv"><table width="100%"><tr><td valign="top"><h2><span class="refentrytitle">org.freedesktop.Secrets.Item Interface</span></h2><p>org.freedesktop.Secrets.Item Interface — Item wraps a secret</p></td><td valign="top" align="right"></td></tr></table></div><div class="refsynopsisdiv"><h2>Methods</h2><pre class="synopsis"> +<a class="link" href="#eggdbus-method-org.freedesktop.Secrets.Item.Delete" title="Delete ()">Delete</a> () + </pre></div><div class="refsect1" lang="en"><a name="id344432"></a><h2>Signals</h2><pre class="synopsis"> +<a class="link" href="#eggdbus-signal-org.freedesktop.Secrets.Item::changed" title='The "changed" signal'>changed</a> () + </pre></div><div class="refsect1" lang="en"><a name="id340577"></a><h2>Properties</h2><pre class="synopsis"> +<a class="link" href="#eggdbus-property-org.freedesktop.Secrets.Item:Locked" title='The "Locked" property'>Locked</a> readable Boolean +<a class="link" href="#eggdbus-property-org.freedesktop.Secrets.Item:Attributes" title='The "Attributes" property'>Attributes</a> readwrite Dict<String,String> +<a class="link" href="#eggdbus-property-org.freedesktop.Secrets.Item:Label" title='The "Label" property'>Label</a> readwrite String +<a class="link" href="#eggdbus-property-org.freedesktop.Secrets.Item:Secret" title='The "Secret" property'>Secret</a> readwrite <a class="link" href="#eggdbus-struct-Secret" title="The Secret Structure">Secret</a> +<a class="link" href="#eggdbus-property-org.freedesktop.Secrets.Item:Created" title='The "Created" property'>Created</a> readable UInt64 +<a class="link" href="#eggdbus-property-org.freedesktop.Secrets.Item:Modified" title='The "Modified" property'>Modified</a> readable UInt64 + </pre></div><div class="refsect1" lang="en"><a name="id344035"></a><h2>Description</h2><p> +An item contains a secret, lookup attributes and has a label. + </p></div><div class="refsect1" lang="en"><a name="id336696"></a><h2>Method Details</h2><div class="refsect2" lang="en"><a name="eggdbus-method-org.freedesktop.Secrets.Item.Delete"></a><h3>Delete ()</h3><pre class="programlisting"> +Delete () + </pre><p> +Delete this item. + </p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody></tbody></table></div></div></div><div class="refsect1" lang="en"><a name="id336736"></a><h2>Signal Details</h2><div class="refsect2" lang="en"><a name="eggdbus-signal-org.freedesktop.Secrets.Item::changed"></a><h3>The "changed" signal</h3><pre class="programlisting"> +changed () + </pre><p> +The item changed in some way. + </p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody></tbody></table></div></div></div><div class="refsect1" lang="en"><a name="id363759"></a><h2>Property Details</h2><div class="refsect2" lang="en"><a name="eggdbus-property-org.freedesktop.Secrets.Item:Locked"></a><h3>The "Locked" property</h3><pre class="programlisting"> +Locked readable Boolean + </pre><p> +Whether the item is locked and requires authentication, or not. + </p></div><hr><div class="refsect2" lang="en"><a name="eggdbus-property-org.freedesktop.Secrets.Item:Attributes"></a><h3>The "Attributes" property</h3><pre class="programlisting"> +Attributes readwrite Dict<String,String> + </pre><p> +The lookup attributes for this item. + </p></div><hr><div class="refsect2" lang="en"><a name="eggdbus-property-org.freedesktop.Secrets.Item:Label"></a><h3>The "Label" property</h3><pre class="programlisting"> +Label readwrite String + </pre><p> +The displayable label for this item. + </p></div><hr><div class="refsect2" lang="en"><a name="eggdbus-property-org.freedesktop.Secrets.Item:Secret"></a><h3>The "Secret" property</h3><pre class="programlisting"> +Secret readwrite <a class="link" href="#eggdbus-struct-Secret" title="The Secret Structure">Secret</a> + </pre><p> +The secret, usually transferred encrypted. + </p></div><hr><div class="refsect2" lang="en"><a name="eggdbus-property-org.freedesktop.Secrets.Item:Created"></a><h3>The "Created" property</h3><pre class="programlisting"> +Created readable UInt64 + </pre><p> +The unix time when the item was created. + </p></div><hr><div class="refsect2" lang="en"><a name="eggdbus-property-org.freedesktop.Secrets.Item:Modified"></a><h3>The "Modified" property</h3><pre class="programlisting"> +Modified readable UInt64 + </pre><p> +The unix time when the item was last modified. + </p></div></div></div><div class="refentry" lang="en"><a name="eggdbus-interface-org.freedesktop.Secrets.Service"></a><div class="titlepage"></div><div class="refnamediv"><table width="100%"><tr><td valign="top"><h2><span class="refentrytitle">org.freedesktop.Secrets.Service Interface</span></h2><p>org.freedesktop.Secrets.Service Interface — Manages collections and sessions</p></td><td valign="top" align="right"></td></tr></table></div><div class="refsynopsisdiv"><h2>Methods</h2><pre class="synopsis"> +<a class="link" href="#eggdbus-method-org.freedesktop.Secrets.Service.OpenSession" title="OpenSession ()">OpenSession</a> (OUT ObjectPath result) +<a class="link" href="#eggdbus-method-org.freedesktop.Secrets.Service.CreateCollection" title="CreateCollection ()">CreateCollection</a> (IN String label, + IN Boolean private) +<a class="link" href="#eggdbus-method-org.freedesktop.Secrets.Service.LockService" title="LockService ()">LockService</a> () +<a class="link" href="#eggdbus-method-org.freedesktop.Secrets.Service.SearchCollections" title="SearchCollections ()">SearchCollections</a> (IN Dict<String,String> fields, + OUT Array<ObjectPath> results, + OUT Array<ObjectPath> locked) +<a class="link" href="#eggdbus-method-org.freedesktop.Secrets.Service.RetrieveSecrets" title="RetrieveSecrets ()">RetrieveSecrets</a> (IN Array<ObjectPath> items, + OUT Array<<a class="link" href="#eggdbus-struct-Secret" title="The Secret Structure">Secret</a>> secrets) + </pre></div><div class="refsect1" lang="en"><a name="id337689"></a><h2>Signals</h2><pre class="synopsis"> +<a class="link" href="#eggdbus-signal-org.freedesktop.Secrets.Service::CollectionCreated" title='The "CollectionCreated" signal'>CollectionCreated</a> (ObjectPath collection) +<a class="link" href="#eggdbus-signal-org.freedesktop.Secrets.Service::CollectionDeleted" title='The "CollectionDeleted" signal'>CollectionDeleted</a> (ObjectPath collection) + </pre></div><div class="refsect1" lang="en"><a name="id336639"></a><h2>Properties</h2><pre class="synopsis"> +<a class="link" href="#eggdbus-property-org.freedesktop.Secrets.Service:Collections" title='The "Collections" property'>Collections</a> readable Array<ObjectPath> +<a class="link" href="#eggdbus-property-org.freedesktop.Secrets.Service:DefaultCollection" title='The "DefaultCollection" property'>DefaultCollection</a> readwrite ObjectPath + </pre></div><div class="refsect1" lang="en"><a name="id354846"></a><h2>Description</h2><p> +The Secrets service manages all the sessions and collections. + </p></div><div class="refsect1" lang="en"><a name="id354862"></a><h2>Method Details</h2><div class="refsect2" lang="en"><a name="eggdbus-method-org.freedesktop.Secrets.Service.OpenSession"></a><h3>OpenSession ()</h3><pre class="programlisting"> +OpenSession (OUT ObjectPath result) + </pre><p> +Open a unique session for the caller application. + </p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><p><span class="term"><code class="literal">OUT ObjectPath <em class="parameter"><code>result</code></em></code>:</span></p></td><td><p> +The object path of the session. + </p></td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="eggdbus-method-org.freedesktop.Secrets.Service.CreateCollection"></a><h3>CreateCollection ()</h3><pre class="programlisting"> +CreateCollection (IN String label, + IN Boolean private) + </pre><p> +Create a new collection with the specified access attributes + </p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><p><span class="term"><code class="literal">IN String <em class="parameter"><code>label</code></em></code>:</span></p></td><td><p> +The display name of the new collection + </p></td></tr><tr><td><p><span class="term"><code class="literal">IN Boolean <em class="parameter"><code>private</code></em></code>:</span></p></td><td><p> +Whether this is a private collection or not. + </p></td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="eggdbus-method-org.freedesktop.Secrets.Service.LockService"></a><h3>LockService ()</h3><pre class="programlisting"> +LockService () + </pre><p> +Lock down the entire service. Remove secrets from memory, lock all collections etc... + </p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="eggdbus-method-org.freedesktop.Secrets.Service.SearchCollections"></a><h3>SearchCollections ()</h3><pre class="programlisting"> +SearchCollections (IN Dict<String,String> fields, + OUT Array<ObjectPath> results, + OUT Array<ObjectPath> locked) + </pre><p> +Find items in any collection. + </p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><p><span class="term"><code class="literal">IN Dict<String,String> <em class="parameter"><code>fields</code></em></code>:</span></p></td><td><p> +Find secrets in any collection. + </p></td></tr><tr><td><p><span class="term"><code class="literal">OUT Array<ObjectPath> <em class="parameter"><code>results</code></em></code>:</span></p></td><td><p> +Items found. + </p></td></tr><tr><td><p><span class="term"><code class="literal">OUT Array<ObjectPath> <em class="parameter"><code>locked</code></em></code>:</span></p></td><td><p> +Items found that require authentication. + </p></td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="eggdbus-method-org.freedesktop.Secrets.Service.RetrieveSecrets"></a><h3>RetrieveSecrets ()</h3><pre class="programlisting"> +RetrieveSecrets (IN Array<ObjectPath> items, + OUT Array<<a class="link" href="#eggdbus-struct-Secret" title="The Secret Structure">Secret</a>> secrets) + </pre><p> +Retrieve multiple secrets from different items. + </p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><p><span class="term"><code class="literal">IN Array<ObjectPath> <em class="parameter"><code>items</code></em></code>:</span></p></td><td><p> +Items to get secrets for. + </p></td></tr><tr><td><p><span class="term"><code class="literal">OUT Array<<a class="link" href="#eggdbus-struct-Secret" title="The Secret Structure">Secret</a>> <em class="parameter"><code>secrets</code></em></code>:</span></p></td><td><p> +Secrets for the items, in order. + </p></td></tr></tbody></table></div></div></div><div class="refsect1" lang="en"><a name="id331565"></a><h2>Signal Details</h2><div class="refsect2" lang="en"><a name="eggdbus-signal-org.freedesktop.Secrets.Service::CollectionCreated"></a><h3>The "CollectionCreated" signal</h3><pre class="programlisting"> +CollectionCreated (ObjectPath collection) + </pre><p> +A collection was created. + </p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><p><span class="term"><code class="literal">ObjectPath <em class="parameter"><code>collection</code></em></code>:</span></p></td><td><p> +Collection that was created + </p></td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="eggdbus-signal-org.freedesktop.Secrets.Service::CollectionDeleted"></a><h3>The "CollectionDeleted" signal</h3><pre class="programlisting"> +CollectionDeleted (ObjectPath collection) + </pre><p> +A collection was deleted. + </p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><p><span class="term"><code class="literal">ObjectPath <em class="parameter"><code>collection</code></em></code>:</span></p></td><td><p> +Collection that was created + </p></td></tr></tbody></table></div></div></div><div class="refsect1" lang="en"><a name="id331684"></a><h2>Property Details</h2><div class="refsect2" lang="en"><a name="eggdbus-property-org.freedesktop.Secrets.Service:Collections"></a><h3>The "Collections" property</h3><pre class="programlisting"> +Collections readable Array<ObjectPath> + </pre><p> +The object paths of all collections (ie: keyrings) + </p></div><hr><div class="refsect2" lang="en"><a name="eggdbus-property-org.freedesktop.Secrets.Service:DefaultCollection"></a><h3>The "DefaultCollection" property</h3><pre class="programlisting"> +DefaultCollection readwrite ObjectPath + </pre><p> +The object path of the default collection, or an empty string if no collections exist. + </p></div></div></div><div class="refentry" lang="en"><a name="eggdbus-interface-org.freedesktop.Secrets.Session"></a><div class="titlepage"></div><div class="refnamediv"><table width="100%"><tr><td valign="top"><h2><span class="refentrytitle">org.freedesktop.Secrets.Session Interface</span></h2><p>org.freedesktop.Secrets.Session Interface — Client application session</p></td><td valign="top" align="right"></td></tr></table></div><div class="refsynopsisdiv"><h2>Methods</h2><pre class="synopsis"> +<a class="link" href="#eggdbus-method-org.freedesktop.Secrets.Session.Close" title="Close ()">Close</a> () +<a class="link" href="#eggdbus-method-org.freedesktop.Secrets.Session.Negotiate" title="Negotiate ()">Negotiate</a> (IN String algorithm, + IN Variant input, + OUT Variant output) +<a class="link" href="#eggdbus-method-org.freedesktop.Secrets.Session.BeginAuthenticate" title="BeginAuthenticate ()">BeginAuthenticate</a> (IN Array<ObjectPath> objects, + IN String window-id) +<a class="link" href="#eggdbus-method-org.freedesktop.Secrets.Session.CompleteAuthenticate" title="CompleteAuthenticate ()">CompleteAuthenticate</a> (IN Array<ObjectPath> objects, + IN Array<ObjectPath> authenticated) + </pre></div><div class="refsect1" lang="en"><a name="id367685"></a><h2>Signals</h2><pre class="synopsis"> +<a class="link" href="#eggdbus-signal-org.freedesktop.Secrets.Session::Authenticated" title='The "Authenticated" signal'>Authenticated</a> (ObjectPath object, + Boolean success) + </pre></div><div class="refsect1" lang="en"><a name="id358463"></a><h2>Description</h2><p> +A session tracks state between the service and a client application. + </p></div><div class="refsect1" lang="en"><a name="id362279"></a><h2>Method Details</h2><div class="refsect2" lang="en"><a name="eggdbus-method-org.freedesktop.Secrets.Session.Close"></a><h3>Close ()</h3><pre class="programlisting"> +Close () + </pre><p> +Close this session. + </p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="eggdbus-method-org.freedesktop.Secrets.Session.Negotiate"></a><h3>Negotiate ()</h3><pre class="programlisting"> +Negotiate (IN String algorithm, + IN Variant input, + OUT Variant output) + </pre><p> +Negotiate key agreement and encryption. + </p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><p><span class="term"><code class="literal">IN String <em class="parameter"><code>algorithm</code></em></code>:</span></p></td><td><p> +The algorithm the caller wishes to use. + </p></td></tr><tr><td><p><span class="term"><code class="literal">IN Variant <em class="parameter"><code>input</code></em></code>:</span></p></td><td><p> +Input arguments for the algorithm. + </p></td></tr><tr><td><p><span class="term"><code class="literal">OUT Variant <em class="parameter"><code>output</code></em></code>:</span></p></td><td><p> +Output of the negotiation. + </p></td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="eggdbus-method-org.freedesktop.Secrets.Session.BeginAuthenticate"></a><h3>BeginAuthenticate ()</h3><pre class="programlisting"> +BeginAuthenticate (IN Array<ObjectPath> objects, + IN String window-id) + </pre><p> +Start asynchronous authentication of objects for the caller. + </p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><p><span class="term"><code class="literal">IN Array<ObjectPath> <em class="parameter"><code>objects</code></em></code>:</span></p></td><td><p> +Objects to authenticate or unlock. + </p></td></tr><tr><td><p><span class="term"><code class="literal">IN String <em class="parameter"><code>window-id</code></em></code>:</span></p></td><td><p> +Platform specific window handle to use for showing any prompts. + </p></td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="eggdbus-method-org.freedesktop.Secrets.Session.CompleteAuthenticate"></a><h3>CompleteAuthenticate ()</h3><pre class="programlisting"> +CompleteAuthenticate (IN Array<ObjectPath> objects, + IN Array<ObjectPath> authenticated) + </pre><p> +Complete asynchronous authentication of objects for the caller. + </p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><p><span class="term"><code class="literal">IN Array<ObjectPath> <em class="parameter"><code>objects</code></em></code>:</span></p></td><td><p> +Objects to authenticate or unlock. + </p></td></tr><tr><td><p><span class="term"><code class="literal">IN Array<ObjectPath> <em class="parameter"><code>authenticated</code></em></code>:</span></p></td><td><p> +Objects that were successfully authenticated. + </p></td></tr></tbody></table></div></div></div><div class="refsect1" lang="en"><a name="id370774"></a><h2>Signal Details</h2><div class="refsect2" lang="en"><a name="eggdbus-signal-org.freedesktop.Secrets.Session::Authenticated"></a><h3>The "Authenticated" signal</h3><pre class="programlisting"> +Authenticated (ObjectPath object, + Boolean success) + </pre><p> +An object (collection or item) was authenticated. + </p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><p><span class="term"><code class="literal">ObjectPath <em class="parameter"><code>object</code></em></code>:</span></p></td><td><p> +The object that was authenticated. + </p></td></tr><tr><td><p><span class="term"><code class="literal">Boolean <em class="parameter"><code>success</code></em></code>:</span></p></td><td><p> +Whether the object was successfully unlocked. + </p></td></tr></tbody></table></div></div></div></div><div class="refentry" lang="en"><a name="eggdbus-structmain-Secret"></a><div class="titlepage"></div><div class="refnamediv"><table width="100%"><tr><td valign="top"><h2><span class="refentrytitle">Secret Structure</span></h2><p>Secret Structure — A secret</p></td><td valign="top" align="right"></td></tr></table></div><div class="refsect1" lang="en"><a name="id362378"></a><div class="refsect2" lang="en"><a name="eggdbus-struct-Secret"></a><h3>The Secret Structure</h3><p> + </p><pre class="programlisting"> +{ + String algorithm, + Array<Byte> parameters, + Array<Byte> value +} + </pre><p> + </p><p> +The <a class="link" href="#eggdbus-struct-Secret" title="The Secret Structure">Secret</a> type holds a (possibly encoded) secret. + </p><p> + </p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><p><span class="term"><code class="literal">String <em class="structfield"><code>algorithm</code></em></code></span></p></td><td><p> +Algorithm used to encode the secret value. + </p></td></tr><tr><td><p><span class="term"><code class="literal">Array<Byte> <em class="structfield"><code>parameters</code></em></code></span></p></td><td><p> +Algorithm dependent parameters for secret value encoding. + </p></td></tr><tr><td><p><span class="term"><code class="literal">Array<Byte> <em class="structfield"><code>value</code></em></code></span></p></td><td><p> +Possibly encoded secret value. + </p></td></tr></tbody></table></div><p> + </p></div></div></div><div class="refentry" lang="en"><a name="eggdbus-enummain-Error"></a><div class="titlepage"></div><div class="refnamediv"><table width="100%"><tr><td valign="top"><h2><span class="refentrytitle">org.freedesktop.Secrets.Error.* Error Domain</span></h2><p>org.freedesktop.Secrets.Error.* Error Domain — Errors</p></td><td valign="top" align="right"></td></tr></table></div><div class="refsect1" lang="en"><a name="id360559"></a><div class="refsect2" lang="en"><a name="eggdbus-errordomain-org.freedesktop.Secrets.Error."></a><h3>The org.freedesktop.Secrets.Error.* Error Domain</h3><p> + </p><pre class="programlisting"> +{ + org.freedesktop.Secrets.Error.AlreadyExists, + org.freedesktop.Secrets.Error.IsLocked, + org.freedesktop.Secrets.Error.NotSupported +} + </pre><p> + </p><p> +Errors returned by the Secrets API. + </p><p> + </p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><p><a name="eggdbus-constant-Error.org.freedesktop.Secrets.Error.AlreadyExists"></a><span class="term"><code class="literal">org.freedesktop.Secrets.Error.AlreadyExists</code></span></p></td><td><p> +An object (session, collection) already exists with the same name. + </p></td></tr><tr><td><p><a name="eggdbus-constant-Error.org.freedesktop.Secrets.Error.IsLocked"></a><span class="term"><code class="literal">org.freedesktop.Secrets.Error.IsLocked</code></span></p></td><td><p> +The object must be unlocked before this action can be carried out. + </p></td></tr><tr><td><p><a name="eggdbus-constant-Error.org.freedesktop.Secrets.Error.NotSupported"></a><span class="term"><code class="literal">org.freedesktop.Secrets.Error.NotSupported</code></span></p></td><td><p> +The algorithm is not supported. + </p></td></tr></tbody></table></div><p> + </p></div></div></div></div> + + </div> + </body></html> diff --git a/Specifications/shared-filemetadata-spec.mdwn b/Specifications/shared-filemetadata-spec.mdwn new file mode 100644 index 00000000..dda35d9a --- /dev/null +++ b/Specifications/shared-filemetadata-spec.mdwn @@ -0,0 +1,163 @@ + + +# Introduction + +There are a number of metadata frameworks and indexers such as [[Beagle|http://beaglewiki.org/Main_Page]], [[Kat|http://kat.mandriva.com/]], [[Strigi|http://strigi.sf.net/]] and [[GLScube|http://glscube.org/]], as well as a new freedesktop system [[Tracker|http://www.gnome.org/~jamiemcc/tracker/]], which is based on this spec and is currently under development. These frameworks provide a rich source of metadata about files including such things as the author of a document or the artist of an mp3 file. The purpose of this specification is to define a common metadata naming scheme that each framework can implement to allow applications to tap into this wealth of information. Some examples of interested applications would include filemanagers that want to display and allow editing of this metadata as well as providing integrated search functionality and virtual folder capability (IE folders whose file contents are defined by metadata rather than physical location). This specification will define a common set of "well-known" metadata. + +Also worth reading is [[Apple's spotlight metadata attributes reference|http://developer.apple.com/documentation/Carbon/Reference/MetadataAttributesRef/Reference/CommonAttrs.html]] + +[[CommonExtendedAttributes|CommonExtendedAttributes]] describes common extended attributes that can be used by indexers when retrieving metadata from files. + + +# Metadata + +Metadata is usually defined as data about data. In our case the metadata describes data about files that is often user visible in file managers, office applications, document viewers and audio players. Metadata can typically be viewed or written by selecting "properties" from the file menu of one of these applications. + +Whilst there are some standards for naming document metadata like [[Dublin Core|http://dublincore.org/documents/dces/]], most desktop applications use a propriety set of metadata names. This specification will attempt to define a common set of metadata using a mixture of [[Dublin Core|http://dublincore.org/documents/dces/]], [[ID3|http://en.wikipedia.org/wiki/Id3]] for audio files, [[EXIF|http://en.wikipedia.org/wiki/EXIF]] for image files as well as application specific metadata names. The purpose of these common metadata names is not just for the benefit of metadata frameworks and search engines but also for standardising the display of metadata in all applications. + + +## Metadata rules + +The only requirement for metadata names is that they are unique and do not overload or cause confusion with each other. To make this possible, all metadata is namespaced by an appropriate class based on the type of the file or the application name (if the metadata is application specific). + +This specification only defines a common subset of all possible metadata and is not designed to limit what metadata any file can have nor does it provide any formal names for custom or non-standard metadata other than a namespace class. + +None of the metadata defined in this specification is mandatory and the existence of any metadata is dependent on the framework being used and the files being indexed. + +All metadata defined here may be used in search strings. + +Only metadata that is not derived from the file or file contents may be editable in the interface (applications that want to change non-writable metadata need to modify the embedded metadata in the file's contents themselves). + + +## Metadata Data Types + +Metadata typically comes in a variety of formats and types. In order to facilitate efficient storage and querying, we need to define a group of data types and formats that all metadata we are interested can conform to. The basic data types specified here are: + +* String (variable length string - up to 16MB max in length) +* Array of String (comma delimited list of strings) +* Integer (signed 32 bit) +* UInt (unsigned 32 bit) +* Int64 (signed 64 bit) +* UInt64 (64 bit unsigned) +* Float (64 bit signed floating point number - system dependent double precision) +* Datetime (ISO 8601 format with timezone IE `YYYY-MM-DDThh:mm:ss+xx:yy` EG "2006-04-01T12:30+01:00") +Datetime values that contain no explicit timezone info are assumed to be in the user's timezone. + + +## Metadata Namespaces + +For all metadata, each metadata item needs to be namespaced with its class type using a "." qualifier (EG Audio.Artist represents the metadata Artist for an audio class file). Metadata that is strictly application specific should use a namespace class based on the application name (EG "Nautilus.Window_Geometry"). + +This specification defines the following built-in classes: + +* File +* Audio +* Doc +* Image + +## Generic File Metadata + +Generic file metadata is applicable to all files regardless of their format. The specified metadata uses a few [[Dublin Core|http://dublincore.org/documents/dces/]] based types where applicable with the rest being custom ones. Generic file metadata types are namespaced with the "File" class. Only some of the generic metadata may be writable. Custom metadata not listed below that is generic and applies to all files should also be namespaced with the "File" class unless it is strictly application specific. +[[!table header="no" class="mointable" data=""" + ** Name ** | ** Type ** | **Writable** | ** Description** + `File.Name` | string | No | File name excluding path but including the file extension + `File.Path` | string | No | full file path of file excluding the filename + `File.Link` | string | No | Uri of link target + `File.Format` | string | No | Mime type of the file or if a directory it should contain value "Folder" + `File.Size` | uint64 | No | size of the file in bytes or if a directory no. of items it contains + `File.Permissions` | string | No | Permission string in unix format eg "-rw-r--r--" + `File.Publisher` | string | Yes | Editable DC type for the name of the publisher of the file (EG dc:publisher field in RSS feed) + `File.Content` | string | No | File's contents filtered as plain text (IE as stored by the indexer) + `File.Description` | string | Yes | Editable free text/notes + `File.Keywords ` | array of string | Yes | Editable array of keywords + `File.Rank ` | integer | Yes | Editable file rank for grading favourites. Value should be in the range 1..10 + `File.IconPath ` | string | Yes | Editable file uri for a custom icon for the file + `File.SmallThumbnailPath` | string | Yes | Editable file uri for a small thumbnail of the file suitable for use in icon views + `File.LargeThumbnailPath` | string | Yes | Editable file uri for a larger thumbnail of the file suitable for previews + `File.Modified ` | datetime | No | Last modified datetime + `File.Accessed ` | datetime | No | Last access datetime +"""]] + + +## Audio Metadata + +Audio metadata is based on the widespread [[ID3.1|http://en.wikipedia.org/wiki/Id3]] tags embedded in mp3, ogg and similar files. These are already defined in that specification. All metadata in this section is prefixed with "Audio" and it is recommended that any other metadata not listed below also uses this prefix if its audio related (unless it is application specific). +[[!table header="no" class="mointable" data=""" + ** Name ** | ** Type ** | **Writable** | ** Description** + `Audio.Title ` | string | No | title of the track + `Audio.Artist` | string | No | artist of the track + `Audio.Album ` | string | No | name of the album + `Audio.AlbumArtist` | string | No | artist of the album + `Audio.AlbumTrackCount` | integer | No | total no. of tracks on the album + `Audio.TrackNo` | integer | No | position of track on the album + `Audio.DiscNo` | integer | No | specifies which disc the track is on + `Audio.Performer` | string | No | Name of the performer/conductor of the music + `Audio.TrackGain` | float | No | gain adjustment of track + `Audio.TrackPeakGain` | float | No | peak gain adjustment of track + `Audio.AlbumGain` | float | No | gain adjustment of album + `Audio.AlbumPeakGain` | float | No | peak gain adjustment of album + `Audio.Duration` | integer | No | duration of track in seconds + `Audio.ReleaseDate` | Datetime | No | date track was released + `Audio.Comment` | string | No | comments on the track + `Audio.Genre ` | string | No | type of music classification for the track as defined in ID3 spec + `Audio.Codec` | string | No | codec encoding description + `Audio.CodecVersion` | string | No | codec version + `Audio.Samplerate` | integer | No | samplerate in Hz + `Audio.Bitrate` | float | No | bitrate in kbps + `Audio.Channels` | integer | No | no. of channels in the audio (2 = stereo) + `Audio.LastPlay` | datetime | Yes | when track was last played + `Audio.PlayCount` | integer | Yes | No. of times the track has been played + `Audio.IsNew` | integer | Yes | set to "1" if track is new to the user. (default "0") + `Audio.MBAlbumID` | string | Yes | [[MusicBrainz|http://musicbrainz.org/]] album ID in UUID format + `Audio.MBArtistID` | string | Yes | [[MusicBrainz|http://musicbrainz.org/]] artist ID in UUID format + `Audio.MBAlbumArtistID` | string | Yes | [[MusicBrainz|http://musicbrainz.org/]] album artist ID in UUID format + `Audio.MBTrackID` | string | Yes | [[MusicBrainz|http://musicbrainz.org/]] track ID in UUID format + `Audio.Lyrics` | string | Yes | Lyrics of the track + `Audio.CoverAlbumThumbnailPath` | string | Yes | File path to thumbnail image of the cover album +"""]] + + +## Document Metadata + +For documents, applications have typically used a mixture of Dublin Core types and propriety types. In order to be consistent with them, we have based our metadata names likewise. We have also based these names on metadata names found in Open Office, Ms Word and PDF documents. All metadata in this section is prefixed with the "Doc" class and any other document based metadata should also have this prefix (unless it is application specific). All the metadata here is not editable through the interface as all of it is derived from the file contents. +[[!table header="no" class="mointable" data=""" + ** Name ** | ** Type ** | ** Description** + `Doc.Title` | string | Title of document + `Doc.Subject` | string | document subject + `Doc.Author` | string | name of the author + `Doc.Keywords` | string | string of keywords + `Doc.Comments` | string | user definable free text + `Doc.PageCount` | integer | no. of pages in document + `Doc.WordCount` | integer | total no. of chars in document + `Doc.Created ` | datetime | datetime document was originally +"""]] + + +## Image Metadata + +For images, most support the [[EXIF|http://en.wikipedia.org/wiki/EXIF]] standard and so this largely makes up this specification. SVG files have user definable non-standard metadata so a subset of Dublin Core is also provided here. All metadata in this section is prefixed with the "Image" class and any other image based metadata should also have this prefix (unless it is application specific). All the metadata here is not editable through the interface as all of it is derived from the file contents. +[[!table header="no" class="mointable" data=""" + ** Name ** | ** Type ** | ** Description** + `Image.Height` | integer | Height in pixels + `Image.Width` | integer | Width in pixels + `Image.Title` | string | Title of image + `Image.Album` | string | Name of an album the image belongs to + `Image.Date ` | datetime | datetime image was originally created + `Image.Keywords` | string | string of keywords + `Image.Creator` | string | name of the author + `Image.Comments` | string | user definable free text + `Image.Description` | string | description of the image + `Image.Software` | string | software used to produce/enhance the image + `Image.CameraMake` | string | make of camera used to take the image + `Image.CameraModel` | string | model of camera used to take the image + `Image.Orientation` | string | represents the orientation of the image wrt camera IE "top,left" or "bottom,right" + `Image.ExposureProgram` | string | The program used by the camera to set exposure when the picture is taken. EG Manual, Normal, Aperture priority etc + `Image.ExposureTime` | float | Exposure time used to capture the photo in seconds + `Image.Fnumber` | float | Diameter of the aperture relative to the effective focal length of the lens. + `Image.Flash` | integer | Set to 1 if flash was fired + `Image.FocalLength` | float | Focal length of lens in mm + `Image.ISOSpeed` | float | ISO speed used to acquire the document contents. For example, 100, 200, 400, etc + `Image.MeteringMode` | string | Metering mode used to acquire the image (IE Unknown, Average, [[CenterWeightedAverage|CenterWeightedAverage]], Spot, [[MultiSpot|MultiSpot]], Pattern, Partial) + `Image.WhiteBalance` | string | White balance setting of the camera when the picture was taken (auto or manual) + `Image.Copyright` | string | Embedded copyright message +"""]] diff --git a/Specifications/shared-mime-info-spec.mdwn b/Specifications/shared-mime-info-spec.mdwn new file mode 100644 index 00000000..e4f63820 --- /dev/null +++ b/Specifications/shared-mime-info-spec.mdwn @@ -0,0 +1,89 @@ + +[[!toc ]] + +**Download:** [[Download the MIME database package|Software/shared-mime-info]] + + +### Overview + +Many programs and desktops use the MIME system to represent the types of files. Frequently, it is necessary to work out the correct MIME type for a file. This is generally done by examining the file's name or contents, and looking up the correct MIME type in a database. + +For interoperability, it is useful for different programs to use the same database so that different programs agree on the type of a file, and new rules for determining the type apply to all programs. + +Here you will find: + + * A specification which describes how the new system works. + * A package containing a large number of common MIME types, created by converting the existing KDE and GNOME databases to the new format and merging them together, and software for updating the database. +The system allows the following types of operation: + + * A single place for applications to register information about MIME types: + * A **text/html** file should be described as an **HTML Page** in **English**. + * A way for applications to extend the rules for guessing the type of a file: + * Files with names matching ***.html** are **text/html** files. + * Files with **<html>** near the start are **text/html** files. + * The system is extensible, so other specifications can define extra information that can be added to a type: + * This **.desktop** file provides a way to view **text/html** files. +The system does not provide a mechanism for storing user preferences (Bob likes to view text/html files in Mozilla). See the [[MIME actions specification|Specifications/mime-actions-spec]] for that. + + +### Shared MIME database package + +The core database and the **update-mime-database** program for extending it are available from the [[software pages|Software/shared-mime-info]]. + +If you have added types that should go in the common freedesktop.org base list of types, you should create an enhancement request on [[the MIME bugtracker|https://bugs.freedesktop.org/buglist.cgi?product=shared-mime-info&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED]] with your new XML file. + + +### Tutorials + +Application authors and users who want to extend the database should read the [[Adding to the database tutorial|Specifications/AddingMIMETutor]]. This explains how to add information to the database such as: + +* **image/png** can be **edited** using the **Gimp**. +* **image/png** should be **described** in **English** as **"Portable Network Graphics file"**. +* Files whose **names** end in **.png** should have the type **image/png**. +If you want to _read_ the database instead (eg, to work out the MIME type of a file, or find a textual description of a type) then you should use one of the various libraries listed in the **Current implementors** section below, or read the full specification. + + +### Mailinglist + +Discussion of this specification should occur on [[xdg|http://www.freedesktop.org/mailman/listinfo/xdg]]. + + +### Git + +The [[Git|Infrastructure/git]] module for this code is [[xdg/shared-mime-info|http://cgit.freedesktop.org/xdg/shared-mime-info/]]. + + +### Current status + +The specification is now quite stable and not expected to change in incompatible ways. Integration with icon themes has not been finalised (and is not currently part of the specification). + + * ROX has used the system since ROX-Filer 1.3.3 (July 2002). + * GTK has support since version 2.4 (Mar 2004). + * GNOME uses the system since version 2.8 (Sep 2004). + * XFCE uses the system since version 4.2.0 (Jan 2005). + * KDE uses the system since version 4.0 (Jan 2007). + * LXDE has used the system since the initial release of PCManFM (2005). + * EDE uses the system since version 2.0-alpha (Apr 2009, but implemented in May 2007). +Current issues keeping this as 'draft' are: + + * The Desktop Base Directory Specification, which this relies on, is still a draft. + +### Full specification + + * Version 0.11 - [[html (one page)|http://standards.freedesktop.org/shared-mime-info-spec/shared-mime-info-spec-0.11.html]] - [[html (multiple pages)|http://standards.freedesktop.org/shared-mime-info-spec/0.11/]] - [[xml|http://standards.freedesktop.org/shared-mime-info-spec/shared-mime-info-spec-0.11.xml]] + * Version 0.12 - [[html (one page)|http://standards.freedesktop.org/shared-mime-info-spec/shared-mime-info-spec-0.12.html]] - [[html (multiple pages)|http://standards.freedesktop.org/shared-mime-info-spec/0.12/]] - [[xml|http://standards.freedesktop.org/shared-mime-info-spec/shared-mime-info-spec-0.12.xml]] + * Version 0.13 - [[html (one page)|http://standards.freedesktop.org/shared-mime-info-spec/shared-mime-info-spec-0.13.html]] - [[html (multiple pages)|http://standards.freedesktop.org/shared-mime-info-spec/0.13/]] - [[xml|http://standards.freedesktop.org/shared-mime-info-spec/shared-mime-info-spec-0.13.xml]] + * Version 0.14 - [[html (one page)|http://standards.freedesktop.org/shared-mime-info-spec/shared-mime-info-spec-0.14.html]] - [[html (multiple pages)|http://standards.freedesktop.org/shared-mime-info-spec/0.14/]] - [[xml|http://standards.freedesktop.org/shared-mime-info-spec/shared-mime-info-spec-0.14.xml]] + * Version 0.15 - [[html (one page)|http://standards.freedesktop.org/shared-mime-info-spec/shared-mime-info-spec-0.15.html]] - [[html (multiple pages)|http://standards.freedesktop.org/shared-mime-info-spec/0.15/]] - [[xml|http://standards.freedesktop.org/shared-mime-info-spec/shared-mime-info-spec-0.15.xml]] + * Version 0.16 - [[html (one page)|http://standards.freedesktop.org/shared-mime-info-spec/shared-mime-info-spec-0.16.html]] - [[html (multiple pages)|http://standards.freedesktop.org/shared-mime-info-spec/0.16/]] - [[xml|http://standards.freedesktop.org/shared-mime-info-spec/shared-mime-info-spec-0.16.xml]] + * Version 0.17 - [[html (one page)|http://standards.freedesktop.org/shared-mime-info-spec/shared-mime-info-spec-0.17.html]] - [[html (multiple pages)|http://standards.freedesktop.org/shared-mime-info-spec/0.17/]] - [[xml|http://standards.freedesktop.org/shared-mime-info-spec/shared-mime-info-spec-0.17.xml]] + * Version 0.18 - [[html (one page)|http://standards.freedesktop.org/shared-mime-info-spec/shared-mime-info-spec-0.18.html]] - [[html (multiple pages)|http://standards.freedesktop.org/shared-mime-info-spec/0.18/]] - [[xml|http://standards.freedesktop.org/shared-mime-info-spec/shared-mime-info-spec-0.18.xml]] + * [[History and related systems|Specifications/OtherSystems]] + +### Current implementors + + * [[xdgmime|http://cgit.freedesktop.org/xdg/xdgmime/]]: Reference implementation of the spec. It is dual licensed under the GNU-LGPL and AFL v2.0. It has no dependencies and is written in straight C. It is intended to be included by other libraries that want to support the standard. [[libxdg|https://github.com/vilkov/libxdg/wiki]]: This is a fork of the xdgmime library with additional implementation of [[MIME actions specification|Specifications/mime-actions-spec]], [[Desktop entry specification|Specifications/desktop-entry-spec]], [[Icon theme specification|Specifications/icon-theme-spec]] and [[Icon naming specification|Specifications/icon-naming-spec]]. It is dual licensed under the GNU-LGPL and AFL v2.0. It has no dependencies and is written in straight C. It is intended to be included by other libraries that want to support the standard. [[libsharedmime|http://www.memecode.com/libsharedmime.php]]: Another shared library to query the database. [[KDE|http://www.kde.org/]]: The KDE libraries implement the MIME spec to provide MIME information to all KDE applications. [[GTK+ file selector|http://www.gtk.org/]]: The new file selector in GTK+-2.4 uses the MIME spec to determine icons in it. [[MIME-Editor|http://rox.sourceforge.net/desktop/MIME-Editor]]: Graphical editor with a GTK interface, written in python. [[Perl module File::MimeInfo|http://search.cpan.org/search?query=File%3A%3AMimeInfo&mode=module]](CPAN): Provides a simple Perl interface to query the database. [[PHP library|http://www.liacs.nl/~dvbeelen/MIME.php.txt]]: Provides a simple PHP5 interface to query the database. [[ROX-Lib|http://rox.sourceforge.net/desktop/ROX-Lib]]: Provides a Python module to query the database. [[ROX-Filer|http://rox.sourceforge.net/desktop/ROX-Filer]]: Graphical file manager which uses the database to match filenames and provide textual descriptions for each type. [[gnome-vfs|http://www.gnome.org/]]: The GNOME VFS library provides mime information to all GNOME applications. [[Ruby library|http://code-monkey.de/?mime_info_rb]]: A Ruby module to query the database. [[jmimeinfo|http://hedges.net/archives/2006/11/08/java-shared-mime-info/]]: A Java library to query the database. [[PCManFM|http://pcmanfm.sourceforge.net/]]: Lightweight graphical file manager with tab-browsing which uses the database for all mime-type handling of files. There is a small GPL'd lib called libmimetype included in the source code of PCManFM. [[EDE|http://equinox-project.org]]: EDE library (edelib) provides mime information to all EDE specific applications. + +### Links to other specifications + + * [[Base directory specification|Specifications/basedir-spec]]: This is used to locate the MIME database. It lets the user override the system settings, and the system settings override the distribution settings. [[MIME actions specification|Specifications/mime-actions-spec]]: This specification describes how applications should be associated with MIME types. This covers both recording that an application is capable of opening files of a particular type, and configuring which application should be the default. [[Desktop entry specification|Specifications/desktop-entry-spec]]: There needs to be a way to indicate which applications can handle a file of a particular type. In the future, this will probably take the form of a link to a .desktop file, as shown in the tutorial above. [[Icon theme specification|Specifications/icon-theme-spec]]: This can be used to locate an icon to represent a given MIME type. The icon name is of the form **media-subtype** (for example: **text-plain**). If no specific icon is found, fallback to **media-x-generic** (eg, **text-x-generic**). See also the [[Icon naming specification|Specifications/icon-naming-spec]]. MIME type icon naming follows the proposal outlined in [[this thread|http://thread.gmane.org/gmane.comp.freedesktop.xdg/6680]]. [[A previous proposal|http://thread.gmane.org/gmane.comp.freedesktop.xdg/669/focus=832]] included a colon character which would have been problematic on Windows and MacOS X file systems.
\ No newline at end of file diff --git a/Specifications/sound-theme-spec.mdwn b/Specifications/sound-theme-spec.mdwn new file mode 100644 index 00000000..439a191e --- /dev/null +++ b/Specifications/sound-theme-spec.mdwn @@ -0,0 +1,38 @@ +# Sound Theme and Naming Specifications + +<http://freedesktop.org/wiki/Specifications> + + +## About + +A sound theme is a set of sounds, sharing similarities / instruments... The user can then select the sound theme that they want to use, and all applications will use sounds from the theme. This definition is similar to icon theme. + +These two specs are heavily based on the [["Icon Theme Specification"|Specifications/icon-theme-spec]], the [["Icon Naming Specification"|Specifications/icon-naming-spec]] and the [["Bango Project"|Bango]]. Comments are welcome! + + git clone git://git.infradead.org/users/elmarco/sound-theme-spec.git + + yelp $PWD/sound-theme-spec/spec/sound-theme-spec.xml + yelp $PWD/sound-theme-spec/spec/sound-naming-spec.xml + +## Mailing list + +Discussion of this specification should occur on [[xdg|http://freedesktop.org/mailman/listinfo/xdg]]. If you have comments to these specs or think a new name needs to be added to the sound-naming-spec, please don't hesitate to send a request by email. + + +## The Sound Theme Spec + +* Post-0.5 Snapshot (draft) - [[html|http://0pointer.de/public/sound-theme-spec.html]] + +## The Sound Naming Spec + +* Post-0.3 Snapshot (draft) - [[html|http://0pointer.de/public/sound-naming-spec.html]] + +## Known Implementation + +Libcanberra: <http://0pointer.de/lennart/projects/libcanberra/> + + +## XDG sound theme + +* <http://cgit.freedesktop.org/sound-theme-freedesktop/> +* <http://people.freedesktop.org/~mccann/dist/sound-theme-freedesktop-0.8.tar.bz2> diff --git a/Specifications/startup-notification-spec.mdwn b/Specifications/startup-notification-spec.mdwn new file mode 100644 index 00000000..2dd6fbe1 --- /dev/null +++ b/Specifications/startup-notification-spec.mdwn @@ -0,0 +1,20 @@ + + +## Startup Notification + +This document specifies a mechanism allowing a desktop environment to track application startup, to provide user feedback and other features. + + +### Mailinglist + +Discussion of this specification should occur on [[xdg|http:/mailman/listinfo/xdg]]. + + +### CVS + +The [[CVS|http:GettingInvolved#CVS]] module for this spec is [[startup-notification/doc|http://cvs.freedesktop.org/startup-notification/startup-notification/doc/]]. + + +### Spec + + * [[startup-notification-0.1.txt|http://standards.freedesktop.org/startup-notification-spec/startup-notification-0.1.txt]]
\ No newline at end of file diff --git a/Specifications/systemtray-spec.mdwn b/Specifications/systemtray-spec.mdwn new file mode 100644 index 00000000..6a600f47 --- /dev/null +++ b/Specifications/systemtray-spec.mdwn @@ -0,0 +1,22 @@ + + +## System Tray + +The system tray is an area on the dock or panel used to display unobtrusive notifications to the user. The tray contains small icons for each notification facility, and the icons can pop up "balloon messages." + + +### Mailinglist + +Discussion of this specification should occur on [[xdg|http:/mailman/listinfo/xdg]]. + + +### Git + +The [[Git|http:GettingInvolved#GIT]] module for this spec is in [[xdg-specs|http://cgit.freedesktop.org/xdg/xdg-specs/]]. + + +### Spec + + * Version 0.1 - [[html (one page)|http://standards.freedesktop.org/systemtray-spec/systemtray-spec-0.1.html]] - [[html (multiple pages)|http://standards.freedesktop.org/systemtray-spec/0.1/]] - [[xml|http://standards.freedesktop.org/systemtray-spec/systemtray-spec-0.1.xml]] + * Version 0.2 - [[html (one page)|http://standards.freedesktop.org/systemtray-spec/systemtray-spec-0.2.html]] - [[html (multiple pages)|http://standards.freedesktop.org/systemtray-spec/0.2/]] - [[xml|http://standards.freedesktop.org/systemtray-spec/systemtray-spec-0.2.xml]] + * Version 0.3 - [[html (one page)|http://standards.freedesktop.org/systemtray-spec/systemtray-spec-0.3.html]] - [[html (multiple pages)|http://standards.freedesktop.org/systemtray-spec/0.3/]] - [[xml|http://standards.freedesktop.org/systemtray-spec/systemtray-spec-0.3.xml]]
\ No newline at end of file diff --git a/Specifications/trash-spec.mdwn b/Specifications/trash-spec.mdwn new file mode 100644 index 00000000..a578b16d --- /dev/null +++ b/Specifications/trash-spec.mdwn @@ -0,0 +1,21 @@ + + +### Desktop Trash Can Specification + +The purpose of this Specification is to provide a common way in which all “Trash can” implementations should store, list, and undelete trashed files. By complying with this Specification, various Trash implementations will be able to work with the same devices and use the same Trash storage. For example, if one implementation sends a file into the Trash can, another will be able to list it, undelete it, or clear it from the Trash. + + +### Mailinglist + +Discussion of this specification should occur on [[xdg|http:/mailman/listinfo/xdg]]. + + +### CVS + +The [[CVS|http:GettingInvolved#CVS]] module for this spec is TBA. + + +### Spec + + * [[Latest version|http://www.ramendik.ru/docs/trashspec.html]] + * Version 0.7 - [[html (one page)|http://www.ramendik.ru/docs/trashspec.html]]
\ No newline at end of file diff --git a/Specifications/wm-spec.mdwn b/Specifications/wm-spec.mdwn new file mode 100644 index 00000000..f74ea088 --- /dev/null +++ b/Specifications/wm-spec.mdwn @@ -0,0 +1,46 @@ + + +## Window Manager Specification Project + +The Window Manager Specification is meant to unify the GNOME and KDE window manager hint conventions. Most of the design work takes place on _[[wm-spec-list@gnome.org|mailto:wm-spec-list@gnome.org]]_; you can subscribe to this list at [[http://mail.gnome.org/mailman/listinfo/wm-spec-list|http://mail.gnome.org/mailman/listinfo/wm-spec-list]]. To post without subscribing, subscribe to the no-traffic _[[post-only@gnome.org|mailto:post-only@gnome.org]]_ list. + + +### Mailinglist + +You can find archives of the WM spec list [[here|http://mail.gnome.org/archives/wm-spec-list/]]. + + +### CVS + +The [[CVS|http:GettingInvolved#CVS]] module for this spec is [[icccm-extensions/wm-spec|http://cvs.freedesktop.org/icccm-extensions/wm-spec/]]. + + +### Spec + +* Version 1.3 - [[html (one page)|http://standards.freedesktop.org/wm-spec/wm-spec-1.3.html]] - [[html (multiple pages)|http://standards.freedesktop.org/wm-spec/1.3/]] - [[xml|http://standards.freedesktop.org/wm-spec/wm-spec-1.3.xml]] +* Version 1.4.draft-2 - [[html (one page)|http://standards.freedesktop.org/wm-spec/wm-spec-1.4.html]] - [[html (multiple pages)|http://standards.freedesktop.org/wm-spec/1.4/]] - [[xml|http://standards.freedesktop.org/wm-spec/wm-spec-1.4.xml]] + +### Supporters + +This table is a (possibly incomplete) list of window managers that support this specification, with details about their level of support. +[[!table header="no" class="mointable" data=""" + **NAME** | **DETAILS** + `AfterStep` | [[wmprops.h|http://cvs.aftercode.net/cgi-bin/viewcvs.cgi/afterstep-stable/libAfterStep/wmprops.h?rev`HEAD&content-type`text/vnd.viewcvs-markup]] + `awesome` | [[ewmh.h|http://git.naquadah.org/?p=awesome.git;a=blob;f=ewmh.c;hb=HEAD]] + `Blackbox` (0.70.x+) | [[COMPLIANCE|http://blackboxwm.cvs.sourceforge.net/*checkout*/blackboxwm/blackbox/COMPLIANCE]] + `Compiz` | [[display.c|http://gitweb.freedesktop.org/?p=xorg/app/compiz.git;a=blob;f=src/display.c]] + `Edewm` (EDE) | [[COMPLIANCE|http://ede.svn.sourceforge.net/viewvc/ede/trunk/ede2/edewm/COMPLIANCE?view=markup]] + `Enlightenment (e16)` | [[COMPLIANCE|http://trac.enlightenment.org/e/browser/trunk/E16/e/COMPLIANCE]] + `FluxBox` | [[EWMH Support|http://fluxbox.sourceforge.net/docs/ewmh-support.html]] + `FVWM` (2.5.x) | [[ewmh.c|ftp://ftp.fvwm.org/pub/fvwm/devel/sources/fvwm/ewmh.c]] + `icewm` | [[wmmgr.h|http://cvs.sourceforge.net/viewcvs.py/icewm/icewm-1.2/src/wmmgr.h?view=markup]] + `Interface` | [[COMPLIANCE|http://cvs.sourceforge.net/viewcvs.py/interfacewm/interfacewm/Documents/COMPLIANCE]] + `KWin` (KDE) | [[COMPLIANCE|http://quickgit.kde.org/?p=kde-workspace.git&a=blob&f=kwin%2FCOMPLIANCE]] + `Matchbox` | [[COMPLIANCE|http://svn.o-hand.com/view/matchbox/trunk/matchbox-window-manager/COMPLIANCE?view=markup]] + `Metacity` (GNOME) | [[COMPLIANCE|http://svn.gnome.org/viewvc/metacity/trunk/COMPLIANCE?view=markup]] + `Openbox` | [[COMPLIANCE|http://git.icculus.org/?p=dana/openbox.git;a=blob;f=COMPLIANCE]] + `Sawfish` | [[display.c|http://svn.gnome.org/viewvc/sawfish/trunk/src/display.c?view=log]] + `whimsy` | [[ewmh.py|http://github.com/mackstann/whimsy/tree/master/whimsy/actions/ewmh.py]] + `wmii` | [[ewmh.c|http://code.google.com/p/wmii/source/browse/cmd/wmii/ewmh.c]] + `xfwm4` (Xfce) | [[COMPLIANCE|http://svn.xfce.org/svn/xfce/xfwm4/trunk/README]] +"""]] diff --git a/Specifications/xembed-spec.mdwn b/Specifications/xembed-spec.mdwn new file mode 100644 index 00000000..f75e55f4 --- /dev/null +++ b/Specifications/xembed-spec.mdwn @@ -0,0 +1,22 @@ + + +## XEmbed + +XEmbed is a protocol that uses basic X mechanisms such as client messages and reparenting windows to provide embedding of a control from one application into another application. + + +### Mailinglist + +Discussion of this specification should occur on [[xdg|http:/mailman/listinfo/xdg]]. + + +### CVS + +The [[CVS|http:GettingInvolved#CVS]] module for this spec is [[xembed|http://cvs.freedesktop.org/xembed/]]. + + +### Spec + +* [[Latest version|http://standards.freedesktop.org/xembed-spec/latest/]] + + * Version 0.5 - [[html (one page)|http://standards.freedesktop.org/xembed-spec/xembed-spec-0.5.html]] - [[html (multiple pages)|http://standards.freedesktop.org/xembed-spec/0.5/]] - [[xml|http://standards.freedesktop.org/xembed-spec/xembed-spec-0.5.xml]]
\ No newline at end of file diff --git a/Specifications/xsettings-spec.mdwn b/Specifications/xsettings-spec.mdwn new file mode 100644 index 00000000..c0a89867 --- /dev/null +++ b/Specifications/xsettings-spec.mdwn @@ -0,0 +1,21 @@ + + +## XSETTINGS + +The XSETTINGS protocol provides a mechanism for applications written with different toolkits to share simple configuration settings such as double-click-times and background colors. + + +### Mailinglist + +Discussion of this specification should occur on [[xdg|http:/mailman/listinfo/xdg]]. + + +### CVS + +The [[CVS|http:GettingInvolved#CVS]] module for this spec is [[xsettings|http://cvs.freedesktop.org/xsettings/]]. + + +### Spec + + * Version 0.5 - [[html (one page)|http://standards.freedesktop.org/xsettings-spec/xsettings-spec-0.5.html]] - [[html (multiple pages)|http://standards.freedesktop.org/xsettings-spec/0.5/]] - [[xml|http://standards.freedesktop.org/xsettings-spec/xsettings-spec-0.5.xml]] + * [[XSettingsRegistry|Specifications/XSettingsRegistry]] diff --git a/Standards.mdwn b/Standards.mdwn new file mode 100644 index 00000000..e69de29b --- /dev/null +++ b/Standards.mdwn diff --git a/Standards/bidi-spec.mdwn b/Standards/bidi-spec.mdwn new file mode 100644 index 00000000..e69de29b --- /dev/null +++ b/Standards/bidi-spec.mdwn diff --git a/Standards/direct-save.mdwn b/Standards/direct-save.mdwn new file mode 100644 index 00000000..e69de29b --- /dev/null +++ b/Standards/direct-save.mdwn diff --git a/Standards/icon-theme-spec.mdwn b/Standards/icon-theme-spec.mdwn new file mode 100644 index 00000000..e69de29b --- /dev/null +++ b/Standards/icon-theme-spec.mdwn diff --git a/TextLayout.mdwn b/TextLayout.mdwn new file mode 100644 index 00000000..34be2dad --- /dev/null +++ b/TextLayout.mdwn @@ -0,0 +1,27 @@ + + +## Free Desktop Text Layout Working Group + + +### Introduction + +At present, a given FLOSS-based desktop system will often have different programs using different text layout engines. Many GTK-based programs, including The Gimp and Inkscape, use Pango as the text layout engine. [[OpenOffice|OpenOffice]].org uses IBM's ICU text layout classes. KDE programs use Qt's layout engine. Other applications use homegrown text layout engines or take a hybrid approach. KOffice uses Qt's native shaping but has its own code for paragraph layout. And Scribus currently has its own code for the whole layout process but the development team is thinking about using a forked version of Qt's shaper. + +Because of differences in the layout engines operating "behind the scenes", different software can exhibit differing levels of support for complex text layout (CTL) scripts like Arabic or Kannada. Some scripts, like Myanmar, are currently hardly supported at all in the majority of software on FLOSS systems today. High-quality typography for Western scripts is also limited because access to advanced features such as optional letter forms and optional ligatures in [[OpenType|OpenType]] or Graphite fonts is not generally available in FLOSS software. + +The situation is confusing if you are a software developer who is new to the FLOSS world. It is even more confusing if you are an end-user trying to fathom why, for example, Arabic is rendered correctly in Inkscape, shows rendering artifacts on the diacritics in [[OpenOffice|OpenOffice]].org, and isn't even shaped correctly at all in Scribus even when using the very same [[OpenType|OpenType]] font in all three programs. + +[[HarfBuzz|HarfBuzz]] emerged out of our desire to unify the [[OpenType|OpenType]] text shaping logic among all Free Software implementation. Text Layout Summit emerged as a meeting place for interested parties to meet, exchange ideas, write code together, and in general advance the state of text layout in Free Software. + + +### Previous Summits + +**2011**. [[TextLayout2011|TextLayout2011]]. This year's Text Layout Summit was held in conjunction with the [[Desktop Summit|https://www.desktopsummit.org/]] conference, August 9-12, 2011, in Berlin, Germany. + +**2009**. [[TextLayout2009|TextLayout2009]]. This year's Text Layout Summit will be held in conjunction with the Libre Graphics Meeting (LGM) in Montréal May 6-7-8-9, 2009. + +**2008**. [[TextLayout2008|TextLayout2008]]. Planning page for the Text Layout Working Group's 2008 Meeting. + +**2007**. [[TextLayout2007|TextLayout2007]]. This year's Text Layout Summit is planned for Wednesday, July 4 through Friday, July 6, 2007 as part of the [[aKademy|http://akademy.kde.org/]] meeting in Glasgow. + +**2006**. [[2006 Summit in Boston|http://live.gnome.org/Boston2006/TextLayout/]]. The first Text Layout Summit occurred at the Gnome Live! conference in Boston in October, 2006. diff --git a/TextLayout2007.mdwn b/TextLayout2007.mdwn new file mode 100644 index 00000000..44f313ad --- /dev/null +++ b/TextLayout2007.mdwn @@ -0,0 +1,109 @@ + + +## 2007 Text Layout Summit + + +### Summary + +**When:** July 4-6, 2007 + +**Where:** aKademy Conference, Glasgow, Scotland. Venue: Strathclyde University. + +**Accomodation:** [[TextLayout2007Accomodation|TextLayout2007Accomodation]] + +**Attendees:** [[TextLayout2007Attendees|TextLayout2007Attendees]] + + +### Details + +This year's Text Layout Summit is planned for Wednesday, July 4 through Friday, July 6, 2007 as part of the [[aKademy|http://akademy.kde.org/]] meeting in Glasgow, Scotland. The venue will be at Strathclyde University. + +We are in BOF 3 which is room 10.01D on the 10th floor of Livingston Tower. + + +## Planning Meeting on IRC Thursday 2007.06.28 + +Meeting on Thursday 2007.06.28 at 2100UST [[TimeZones|http://www.timeanddate.com/worldclock/fixedtime.html?year=2007&month=6&day=28&hour=21&min=0&sec=0]] in the channel ##fonts on [[FreeNode|FreeNode]]. + + +## Presentations & Papers + +Presentation are available online at [[unifont.org Text Layout 2007|http://unifont.org/TextLayout2007/]] page. + +If you are planning to present a paper, please have a draft ready for posting on the web by June 30th, 2007. Send papers to ed dot trager at gmail dot com. + +Acceptable presentation formats include [[OpenOffice|OpenOffice]] OASIS .odp, PDF, and XHTML. + + +## Agenda Items + +* **[[HarfBuzz|HarfBuzz]]**. [[HarfBuzz|HarfBuzz]] is being designed as a unified [[OpenType|OpenType]] Text Shaper Library for the Free Desktop: + * **Current Status**. Simon Hausmann & Behdad Esfahbod will present on the current state of [[HarfBuzz|HarfBuzz]] development. + * **Next Steps.** We will have extended discussions on the development direction of [[HarfBuzz|HarfBuzz]]. + * **AAT**. Lars Knoll wants to eventually have AAT functionality included in [[HarfBuzz|HarfBuzz]]. + * **Disseminating [[HarfBuzz|HarfBuzz]]**. Discussion on what do we need to do to get major players like [[OpenOffice|OpenOffice]] and [[FireFox|FireFox]] interested in using [[HarfBuzz|HarfBuzz]] for text layout in the future? + * **Coding.** We also expect to devote time at the Summit to hacking on [[HarfBuzz|HarfBuzz]]. +* **M17n Multilingualization Library**: + * **Presentation** by Kenichi Handa. + * **Discussion** on including access to m17n functionality from within [[HarfBuzz|HarfBuzz]]. +* **Graphite**: + * **Presentation** by Sharon Correll, Graphite developer from SIL. + * **Discussion ** on providing access to Graphite functionality from within [[HarfBuzz|HarfBuzz]]. +* **ICU**: + * **Design Features** of ICU's Text Layout Engine. Presentation by Eric Mader. + * **Discussion** on what features and design aspects of ICU's layout engine ought to be incorporated into the [[HarfBuzz|HarfBuzz]] design. +* **IM-Bus**: IM-Bus is a new input method mediator being designed by James Su, the author of SCIM. Presentation prepared by James Su. +* **IPA Fonts and Licensing**: Presentation prepared by Hiroshi Miura of IPA Japan. + +## Draft Schedule + + +### Tuesday July 3rd + +* Evening get-together for early arrivals + +### Wednesday July 4th + +* 8:30 - 9:00 Coffee/ Setup / Seating +* 9:00 - 9:30 Intro / Keynote +* 9:30-10:30 Series of "Lightning Talks": + * OFL'ed Font Update + * IPA Font Update + * IM-BUS + * Fontima (Trager) + * Open Font Design Toolkit Update (yosch) + * OFLB (Open Font Library) Update (eimai) +* 10:30-10:45 Break +* 10:45-11:15 CJK Unifonts Project Outlook ([[Arne Götje)|http://unifont.org/TextLayout2007/presentations/ArneGotjeCJKUnifontsProjectOutlookJuneJuly2007.pdf]] +* 11:15-12:00 "Pan Unicode" Font Discussion (Ben Laenen) +* 12:00-13:30 Lunch +* 13:30-14:15 Design Features in ICU (Eric Mader) +* 14:15-15:00 State of [[HarfBuzz|HarfBuzz]] (including AAT integration) - Simon Hausmann with Behdad when he arrives +* 15:00-15:45 Graphite - Sharon Correll, SIL +* 15:45-16:30 m17n Font Layout Table: Knowledge Base for Complex Text - Kenichi Handa +* 16:30-16:45 New [[OpenType|OpenType]] features in Pango (Brief talk by Behdad) +* 16:45-18:00 - [[HarfBuzz|HarfBuzz]] Development and Integration Discussion +* 18:00+ Continue discussions over dinner ... + +### Thursday July 5th + +I think it would be good to have some social time on the day trip in the afternoon [[http://akademy.kde.org/codingmarathon/day-trip.php|http://akademy.kde.org/codingmarathon/day-trip.php]] [[[DanielGlassey|DanielGlassey]]] + +* 08:00 Early Start to accomodate day trip ... +* 09:00 - 12:00 [[HarfBuzz|HarfBuzz]] Unified Text Layout Engine Design Discussion +* 12:00 - 13:00 Lunch +* 13;00 Bonny Banks Day Trip: Busses leave Glasgow +* 17:00 Barbeque on the beach +* 20:00 Return + +### Friday July 6th + +* Text Layout Summit Coding Sessions + +## Relevant Mailing Lists + +* [[HarfBuzz|http://lists.freedesktop.org/mailman/listinfo/harfbuzz/]] -- Common [[OpenType|OpenType]] Layout engine for the Free Desktop +* [[OFL-discuss|http://openlists.sil.org/mailman/listinfo/ofl-discuss]] -- Open review and ongoing discussions around the SIL Open Font License +* [[DejaVu-fonts|https://lists.sourceforge.net/lists/listinfo/dejavu-fonts]] -- [[DejaVu|DejaVu]] fonts +* [[Fontconfig|http://lists.freedesktop.org/mailman/listinfo/fontconfig]] -- Font configuration and customization +* [[Silgraphite-devel|https://lists.sourceforge.net/lists/listinfo/silgraphite-devel]] -- SIL Graphite development
\ No newline at end of file diff --git a/TextLayout2008.mdwn b/TextLayout2008.mdwn new file mode 100644 index 00000000..e0936eeb --- /dev/null +++ b/TextLayout2008.mdwn @@ -0,0 +1,30 @@ + +This is the planning page for the Text Layout Working Group's 2008 meeting (TLM 2008). + +**Venue and Date** + +There is discussion about having TLM 2008 in conjunction with the [[Libre Graphics Meeting|http://www.libregraphicsmeeting.org/2008/]] in May, 2008 in Wrocław, Poland. (This venue is not yet confirmed). + +**Accomodations**: [[TextLayout2008Accomodation|TextLayout2008Accomodation]] **Attendees**: [[TextLayout2008Attendees|TextLayout2008Attendees]] + +**Draft Agenda** + +* [[HarfBuzz|HarfBuzz]]: + * Development state + * Documenting [[HarfBuzz|HarfBuzz]] +* [[HarfBuzz|HarfBuzz]] and Graphite Integration + * Where are we? + * What needs to be done? +**Presentations** + + * New Font Tools: + * Spiro + * Font Industry + * New Features in Fontforge + * Compedium of 3rd-party Perl / Python / etc. scripts and tools for font creation +**To Do List** + +* Funding discussions with LF +* Room discussions with LGM - assuming LGM is venue +* Have adequate video equipment set up and tested before meeting begins this year. + * Consider publication of videos on [[YouTube|YouTube]]. This could be done essentially immediately after a morning or afternoon session if we had a "[[YouTube|YouTube]] Ready" kind of camera.
\ No newline at end of file diff --git a/TextLayout2009.mdwn b/TextLayout2009.mdwn new file mode 100644 index 00000000..559f4e74 --- /dev/null +++ b/TextLayout2009.mdwn @@ -0,0 +1,34 @@ + +This is the planning page for the Text Layout and Typography Working Group's 2009 meeting (TLM 2009) to be held in conjunction with LGM in Montréal. + +**Venue and Date** + +The meeting will be held in conjunction with Libre Graphics Meeting (LGM) 2009 in Montréal, May 6-7-8-9. + +**Attendees**: + +**Confirmed:** Jon Phillips, Jonathan Kew, Nicolas Spalinger, Pierre Marchand, Joshua Hadley, Brian Kraimer + +**Probably Attending:** John Hudson, Ralph Giles + +**Probably Not Attending:** Sharon Correll, Eric Mader, Ed Trager, Behdad Esfahbod, Kenichi Handa + +**Confirmed Not Attending:** Ben Laenen, Arne Goetje + +**Draft Agenda** + +* Fill in here ... +**Presentations** + + * **Overview of Developments in the Open Font Community**: [[OpenFontLibrary|OpenFontLibrary]], webfonts, licensing advocacy, release best practises for font projects and font packaging teams efforts -- Nicolas Spalinger + * **Key Curry: Leveling the Playing Field of Participatory Democracy**: Brief introduction to Key Curry, a new AJAX-based virtual keyboard component for typing major and minor world language orthographies on the web -- Ed Trager +**Coding** + +The following people have expressed an interest in hacking on the following projects during the gathering: + + * **[[HarfBuzz|HarfBuzz]]**: Jonathan Kew + * **Undecided**: Kenichi Handa +**To Do List** + +* Room discussions with LGM +* Have adequate video/audio equipment set up and tested before meeting begins this year. Would be nice to have video or audio streaming that we could also publish on [[YouTube|YouTube]] afterwards.
\ No newline at end of file diff --git a/TextLayout2011.mdwn b/TextLayout2011.mdwn new file mode 100644 index 00000000..1aeebfbe --- /dev/null +++ b/TextLayout2011.mdwn @@ -0,0 +1,32 @@ + +This is the planning page for the Text Layout Summit 2011 meeting to be held in conjunction with Desktop Summit (combined GUADEC and aKademy) in Berlin. + +**Venue and Date** + +The meeting will be held in conjunction with [[Desktop Summit|http://www.desktopsummit.org/]] 2011 in Berlin, August 9 to 12. + +August 6,7,8 is the main Desktop Summit presentation days, and starting at 9th the conference is in BoF / hacking mode, so we have reserved a room for [[TextLayout|TextLayout]] during those days, but participants are welcome to arrive earlier and attend Desktop Summit. + +The meeting will take place in room 1.308/1. + +**Attendees**: + +Please register for the event on the [[Desktop Summit|http://www.desktopsummit.org/]] website. Registration is free. +[[!table header="no" class="mointable" data=""" + **Attendee** | **Arrival** | **Departure** + Behdad Esfahbod | Aug 7 | Aug 13 + Jiang Jiang | Aug 8 | Aug 12 + Lars Knoll | Aug 9 | Aug 10 + Daniel Glassey | Aug 5 | Aug 13 +"""]] + +**Coding** + +The following people have expressed an interest in hacking on the following projects during the gathering: + +* **[[HarfBuzz|HarfBuzz]]**: Behdad Esfahbod, Jiang Jiang, Lars Knoll +* **[[HarfBuzz|HarfBuzz]]-Indic**: Behdad Esfahbod +* **Pango-[[HarfBuzz|HarfBuzz]]**: Behdad Esfahbod +* **Qt-[[HarfBuzz|HarfBuzz]]**: Behdad Esfahbod, Jiang Jiang, Lars Knoll +* **Chromium-[[HarfBuzz|HarfBuzz]]**: Behdad Esfahbod +* **Undecided**: Daniel Glassey
\ No newline at end of file diff --git a/Translations.mdwn b/Translations.mdwn new file mode 100644 index 00000000..5b8e5ad6 --- /dev/null +++ b/Translations.mdwn @@ -0,0 +1,10 @@ + +There is currently no central place where various freedesktop.org packages can be translated. You should browse [[package pages|Software]] to look for indications about how to contribute translations for each project. + +However, you will be able to translate some freedesktop.org packages in the following infrastructures: + +* Translation Project ([[http://translationproject.org|http://translationproject.org]]): + * gstreamer, xdg-user-dirs, XKeyboardConfig, unicode-han-translation, unicode-translation +* Transifex.net ([[http://www.transifex.net|http://www.transifex.net]]): + * fprintd, shared-mime-infos, cups-pk-helper + Note that to participate to these package translations, you have to be a member of a team in the [[freedesktop.org Transifex project|http://www.transifex.net/projects/p/freedesktop/]].
\ No newline at end of file diff --git a/UsingCvs.mdwn b/UsingCvs.mdwn new file mode 100644 index 00000000..bd677d2c --- /dev/null +++ b/UsingCvs.mdwn @@ -0,0 +1,18 @@ +# Using anonymous CVS + + cvs -d:pserver:anoncvs@anoncvs.freedesktop.org:/cvs/<project> login + cvs -d:pserver:anoncvs@anoncvs.freedesktop.org:/cvs/<project> co <module> + +# Browsing CVS + +CVS Repositories can be browsed online from <http://webcvs.freedesktop.org/>. If you want to link to a particular project's repository, append the project name to the end of the URL (eg. <http://webcvs.freedesktop.org/xorg/>). + + +# Using developer CVS + +* Get a username: + * See <http://www.freedesktop.org/wiki/AccountRequests> for details. +* Using your username. + * `export CVS_RSH=ssh` + * `export CVSROOT=:ext:<developer>@cvs.freedesktop.org:/cvs/<project> cvs -z3 co <module>` + * If you specified a passphrase when running ssh-keygen, then you must enter that passphrase now. diff --git a/UsingGit.mdwn b/UsingGit.mdwn new file mode 100644 index 00000000..e69de29b --- /dev/null +++ b/UsingGit.mdwn diff --git a/WantedPages.mdwn b/WantedPages.mdwn new file mode 100644 index 00000000..cf4824fc --- /dev/null +++ b/WantedPages.mdwn @@ -0,0 +1,3 @@ +A list of non-existing pages including a list of the pages where they are referred to: + +[[!unlinkedpages]] diff --git a/WikiHomePage.mdwn b/WikiHomePage.mdwn new file mode 100644 index 00000000..a0f378ec --- /dev/null +++ b/WikiHomePage.mdwn @@ -0,0 +1,10 @@ + +A WikiHomePage is your personal page on a [[WikiWikiWeb|WikiWikiWeb]], where you could put information how to contact you, your interests and skills, etc. It is regarded as to be owned by the person that created it, so be careful when editing it. + +When you create one, put the the word Category****Homepage on it, like can be seen on this page. + + + +--- + + [[CategoryHomepage|CategoryHomepage]] diff --git a/WikiName.mdwn b/WikiName.mdwn new file mode 100644 index 00000000..285456d7 --- /dev/null +++ b/WikiName.mdwn @@ -0,0 +1,2 @@ + +A WikiName is a word that uses capitalized words. WikiName****s automagically become hyperlinks to the WikiName's page. See also [[HelpForBeginners|HelpForBeginners]], "[[ArbitraryPageNames|ArbitraryPageNames]]". diff --git a/WikiWikiWeb.mdwn b/WikiWikiWeb.mdwn new file mode 100644 index 00000000..15f5ecd3 --- /dev/null +++ b/WikiWikiWeb.mdwn @@ -0,0 +1,11 @@ + +The [[!c2 FrontPage desc="first ever wiki site"]] was founded in 1994 as an automated supplement to the [[!c2 PortlandPatternRepository desc="PortlandPatternRepository"]]. The site was immediately popular within the pattern community, largely due to the newness of the internet and a good slate of [[!c2 InvitedAuthors desc="InvitedAuthors"]]. The site was, and remains, dedicated to [[!c2 PeopleProjectsAndPatterns desc="PeopleProjectsAndPatterns"]]. + +[[!c2 WardCunningham desc="WardCunningham"]] created the site and the WikiWikiWeb machinery that operates it. He chose wiki-wiki as an alliterative substitute for quick and thereby avoided naming this stuff quick-web. An early page, [[!c2 WikiWikiHyperCard desc="WikiWikiHyperCard"]], traces wiki ideas back to a [[!c2 HyperCard desc="HyperCard"]] stack he wrote in the late 80's. + +See also one of these links: + +* [[http://www.c2.com/cgi/wiki|http://www.c2.com/cgi/wiki]] or [[!c2 FrontPage desc="FrontPage"]] +* get some answers on the [[!c2 WikiWikiWebFaq desc="WikiWikiWebFaq"]] +* get to know more about the [[!c2 WikiHistory desc="WikiHistory"]] +* [[Ward Cunningham Radio Interview|http://news.mpr.org/programs/futuretense/daily_rafiles/20011220.ram]]
\ No newline at end of file diff --git a/WindowMaker.mdwn b/WindowMaker.mdwn new file mode 100644 index 00000000..466dfe57 --- /dev/null +++ b/WindowMaker.mdwn @@ -0,0 +1,2 @@ + +-- Main.CharlieZ - 05 Oct 2003 diff --git a/conversion.mdwn b/conversion.mdwn new file mode 100644 index 00000000..3e959ced --- /dev/null +++ b/conversion.mdwn @@ -0,0 +1,9 @@ +# MoinMoin to Ikiwiki conversion + +If you have an account on Annarchy, you can help out with the conversion of this wiki. + +You can follow the [[page conversion|http://wiki.freedesktop.org/sitewranglers/wiki/moin2iki_page_selection/]] instructions using `PROJECT="ldtp"`. + +Here is a list of broken links, which should be a starting place for what needs converting: + +[[!brokenlinks]] diff --git a/gallium_interface.mdwn b/gallium_interface.mdwn new file mode 100644 index 00000000..e69de29b --- /dev/null +++ b/gallium_interface.mdwn diff --git a/index.mdwn b/index.mdwn new file mode 100644 index 00000000..f3a04ff1 --- /dev/null +++ b/index.mdwn @@ -0,0 +1,34 @@ +# Welcome to freedesktop.org + +freedesktop.org is open source / open discussion software projects working on interoperability and shared technology for X Window System desktops. The most famous [[X desktops|Desktops]] are [[GNOME|http://www.gnome.org]] and [[KDE|http://www.kde.org]], but developers working on any Linux/UNIX GUI technology are welcome to participate. + +freedesktop.org is building a base platform for desktop software on Linux and UNIX. The elements of this platform have become the backend for higher-level application-visible APIs such as Qt, GTK+, XUL, VCL, WINE, GNOME, and KDE. The base platform is both [[software|Software]] and [[specifications|Specifications]]. + + +## Software + +freedesktop.org hosts any "on-topic" software projects. If you have a project that fits into our mission and needs hosting, please make a request using our [[bugzilla|http://bugs.freedesktop.org]]. Mailing lists about freedesktop software are hosted [[here|http://lists.freedesktop.org/mailman/listinfo]]. + + +## Standards + +freedesktop.org is not a formal standards organization, though some see a need for one that covers some of the areas we are working on. For Linux operating system standards, look at the [[Linux Standard Base|http://www.linuxbase.org]] project. [[The X.Org Foundation|http://www.x.org]] and the [[IETF|http://www.ietf.org]] are other groups that do formal standards. The [[Free Standards Group|http://www.freestandards.org]] is one group that publishes "de jure" standards for free software; freedesktop.org is loosely affiliated with the FSG. + +Unlike a standards organization, freedesktop.org is a "collaboration zone" where ideas and code are tossed around, and de facto specifications are encouraged. The primary entry to these discussions is the [[xdg mailing list|http://lists.freedesktop.org/mailman/listinfo/xdg]]. + + +## Getting Involved + +You can get involved in a number of ways. See the [[MissionStatement]] for our principle activities. See [[GettingInvolved]] for concrete suggestions on how you can contribute. See [[AccountRequests]] for information on how to obtain commit access to a project. See [[NewProject]] for how to start a new project. + + +## Contacting freedesktop + +If you have any comments or questions about this site please send a message to the [[xdg list|http://lists.freedesktop.org/mailman/listinfo/xdg]]. + + +## Sponsors + +The freedesktop.org servers are generously hosted by [[Portland State University|http://www.pdx.edu]]. [[Intel|http://www.intel.com]], [[HP|http://www.hp.com]] and [[Google|http://www.google.com]] have sponsored the servers themselves and [[Collabora|http://www.collabora.com]] are sponsoring sysadmin time. + +This wiki is undergoing [[conversion]]. If you have a fd.o shell account, you can help! |
