Let's make an outline of the things that should be in a "ISV Guide to GNOME".
ISV is "Independent Software Vendor", or anyone who writes apps against the GNOME platform to distribute them independently. That includes open source developers!
Quick links:
GnomeGoals may be a good starting point for tasks that may interest ISVs.
Miscellaneous
On 2005/Aug/03, Adobe hosted a web seminar on the problems they had when porting Acrobat Reader to GNU/Linux: http://lists.osdl.org/pipermail/isv_discussion/2005-June/000018.html
BrianCameron: Note that much of the information in this guide is already documented in the GNOME 2.6 System Admistrators Guide. This document unfortunately also contains some interfaces which are not stable and do not work in the latest GNOME builds (such as how to integrate a launcher into the panel). Perhaps it might be easier to create an ISV Guide using this document as a starting point, or copy-paste the information from that guide. I imagine that the ISV Guide will replace this document when it is finished.
Problems which ISVs face
Uncertainty about which version(s)/parts of GNOME to target. What's the GNOME version which the most number of people have installed?
- Does ABI apply to the whole GNOME stack, or to what parts? Should ISV's avoid using certain API?
Some issues are not to do with GNOME but must be tackled anyway - no ISV purely targets GNOME, usually they target GNU/Linux+GNOME, or some subset of GNU/Linux distributions. Issues that affect GNU/Linux should also be tackled then, otherwise the guide would be not be a complete guide and ISVs would still be stumbling around in the dark, giving users a poor experience:
- Binary compatibility. Build once, and run on newer or older versions within the same major release.
http://mail.gnome.org/archives/gtk-devel-list/2004-April/msg00177.html
- Binary relocatability (install to any prefix) - needs glib support really
- How to distribute binaries (installers, package management, end user ease of use issues)
- File installation locations and file formats. Examples: to integrate into the GNOME menu, you must install *.desktop files; to integrate into the MIME-type database; many GNOME programs have glade files, etc. It is a problem for ISV's if the location or format of files needed for integration change in ways that are not backwards-compatible. It should be clear where to install images, pixmaps, icons, sound files, capplets, etc. The ISV guide should also recommend the best place to integrate common filetypes that are not necessarily integration points with other programs. An example would be glade files. Many GNOME applications, for example, install their glade files to /usr/share/programname/*.glade, but perhaps /usr/share/glade/programname would be a better place for keeping the /usr/share directory from getting cluttered.
- GNOME installs a lot of configuration files on the system, and the user's $HOME directory. The guide should clarify which of these files are safe for the ISV to customize, what sort of customizations are supported, and which are not.
- Do we need a "GNOME and GNU/Linux"/"GNOME and Solaris" sections of the guide?
Lack of programming documentation.
Lack of "overview of the platform" documentation.
MikeHearn: Porting from Win32 to GTK+ ... do we need advice and examples of how to port things like Win32 file association/menu code to GNOME and/or how to integrate the GTK+ mainloop with the Win32 main loop so dual code can exist during the transition?
Outline for the guide
Basic integration
Registering a .desktop file. Rationale: users need to be able to run the program.
- Common gotchas: typos in categories (eg using Games intead of Game) / wrong categories / default menu setups that ignore your entry or put it under "Other"
- Compatibility with older KDE desktops
Registering MIME types. Rationale: that's how the file manager will know how to launch your program for the files it creates.
Common gotcha: how to support older GNOME versions, KDE <4.0 does not use freedesktop.org MIME system. Autopackage project has some XSL:T which can transform freedesktop.org MIME XML files into KDE 3.x equivalents.
Registering icons for launchers/mime types. Rationale: this is how the user will see the files in the file manager.
- There is some confusion here w.r.t GNOME/KDE compatibility. Icons for mime types are not used unless they have a gnome- prefix.
- Common gotchas: not touching root directory of theme, not providing enough icons of the right size, icons not fitting in with the default GNOME artwork. Maybe we need some advice on how to draw generically pretty icons that look OK with the most common icon themes?
MikeHearn wrote a script to make icon theme compliance easier: http://cvs.sunsite.dk/viewcvs.cgi/autopackage/apbuild/make-icons
Basic cut and paste of text. Rationale: this is how users transfer text from the rest of the desktop into the program, and vice-versa.
UTF8_STRING as the preferred method.
Mention the clipboard specification, and how it differs from traditional use of the PRIMARY selection in X.
Mention that as a nice touch, you can also use the clipboard manager spec to make sure the clipboard retains its contents after your application exits.
Encoding for file names. Rationale: all of GNOME expects filenames to be encoded in a certain way.
Documentation for G_FILENAME_ENCODING and the obsolete G_BROKEN_FILENAMES
Explanation of filename encodings and the Glib functions to handle them FIXME: those online docs need to be regenerated; they don't include figures and they are outdated with respect to CVS.
Does the window manager specification come into play here? I.e. so that legacy applications won't do idiotic things with respect to window hints, full-screen mode, transient windows, etc.
- Deeper integration with the desktop
- Startup notification - FIXME: link to freedesktop.org standard, mention the implementation library. Mention initial app startup, and how to use the library for when the app is already open but it is asked to load another document from Nautilus.
- Basic drag-and-drop
- We support Motif and XDND
- The most basic types are text (UTF8_STRING), and text/uri-list.
- FIXME: link to XDND; mention that major toolkits normally implement this.
- Thumbnailers (gnome-thumbnail and the framework to plug your own thumbnailers)
Common dialogs (file chooser, print)? OpenOffice.org and Firefox integrate them.
- Overview of the GNOME platform
- What functionality we provide, which libraries you use for what features.
- List the freedesktop.org standards which we implement.
- FIXME: which ones?
- Writing new applications for GNOME
- Things to keep in mind
- Accessibility
- Internationalization
- Themes (including a11y themes like large print / high contrast / inverse)
- GNOME Human Interface Guidelines
- Things to keep in mind
- Common problems
- Filename encodings
- Menu items not appearing, appearing in the wrong place, icons not appearing
Status of the guide
The guide lives in CVS in the "gnome-isv-guide" module. An HTML version gets posted periodically to here.
I want to maintain the actual text of the guide in there. I want to structure the guide as a series of tasks that ISVs can do to integrate their apps gradually into GNOME: "install a .desktop file", "install MIME definitions and icons", "support cut&paste". Since at this point I am not completely sure about the actual order for those tasks, I'd like to play with that order here in the wiki: that's what the Outline section is about.
In the outline, you'll see that I have several chapters: "Basic integration", "Deeper integration", etc. The idea is that those chapters are milestones that ISVs can achieve and get meaningful results: "Basic integration" is about the very minimum you need to do to let users run your software and manage the files it produces, plus minimal interoperability like cut&paste of text. "Deeper integration" is about the the things that start to make for a "nice app": drag and drop, installing a thumbnailer for the file manager, supporting the recent-files specification, etc. We will probably continue with very specific chapters: "Multimedia: if your app makes noises, this is the sound architecture you should use"; "Printing: use CUPS", etc.
Encryption Logic
ISV's need to be aware of what encryption logic exists in the GNOME stack since it may affect export licenses. This only affects ISV's who intend to ship the logic containing the encryption logic, typically a GNOME distribution vendor.
gnome-keyring
gnome-keyring versions before 2.20 used to have its own AES/MD5/SHA crypto code. This prevented some ISVs, such as Sun Microsystems, from shipping gnome-keyring without a custom patch. gnome-keyring now uses libgcrypt for its crypto needs and no crypto algorithms are present in its code.
See also
IdealDeveloperDocumentation: I think the ISV guide would be an extra chapter in that high level documentation, mentioning existing sections, and adding details such as window manager specifications and the HIG.