Grafpup Development

Grafpup Development

Overview

Packaging Applications

Grafbuild
Package Standards
Compiler Flags

Writing Applications

Shell Scripting
PuppyBasic
Tcl/Tk and Gnocl
Compiled Programs

Submissions

Submitting Packages
Submitting Artwork

Licensing Issues

Documentation

Further Reading

Overview

Grafpup Linux started out it's life around the fall of 2005, as a simple remaster of Puppy Linux. At that time it was basically just my attempt to customize the distro to suit my tastes. As such there was not a whole lot that was different between them at first, and there was only one person actively working on the project for quite some time. As time has rolled on, however, Grafpup has become more and more a separate project and is now drawing a fair amount of attention not only among users but also developers.
As of right now Grafpup is still a small project with one primary developer, but there are a growing number of people among the community who are contributing to it's development in various ways. Some are writing or tweaking scripts and other programs. A couple are working on artwork and design, while a small handful are now also creating packages (a role that used to be filled exclusively by myself). This page is an attempt to give some guidance for those efforts.
Top

Packaging applications

    Grafpup-2.xx has been built on top of Puppy Linux, which in turn was built from source packages using the T2 build system. To make it easy for users to compile software for the system there is a special add on module called devx_xxx.sfs, where the xxx stands for the three digit version number. It is fairly easy to install and use. Just download it to wherever your grf_save file is located and reboot. You should then have a working compiler.
    Note that in some cases you may also need to install development packages in order to compile against their headers. For instance, some software like Gaim will require the Seamonkey headers, which are located in the seamonkey_dev package.
    Once the development module is installed you should have a working compiler, and you can compile packages using "./configure && make && make install". However, there are some tools built into Grafpup which will aid in making the process a little smoother and automatically collecting the installed files for package creation, which I will explain in a bit more detail below. You will also have both cvs and subversion programs and the headers for the entire base system, including the kernel headers.
Top

The Grafbuild system

    I have created a few utilities to partially automate package creation from source code. These tools are in addition to the utilities offered in Puppy Linux and are complementary to what they can do. However, these tools assume that the package is built using the traditional gnu tools. If the package uses an alternative build system like scons or cmake, then you will have to build the package manually.
    When you first open a source package and want to compile it into usable binaries, more than likely the first step is to run the configure script that comes with the source package. Most packages will accept a number of options passed to the configure script, which you can learn more about by typing "configopts" in the terminal. This simple little script will run "./configure --help" and dump it's output into a file, then open that file in a text editor for you to read. Note that if you acquire your sources through subversion or cvs you will more than likely be required to run either "./autogen.sh" or "./bootstrap" first, in order to create the configure script.
    Once you have determined the options you want the package to be built with, you can build the package using grafbuild. The grafbuild script can accept any options you would pass to configure and will perform all the steps required to install the binaries on your system automatically. It will also collect all of the installed files and put them into a "grafbuild" subdirectory inside the source tree, splitting them further into subdirectories for the executable package, development headers, and language files. It will also save your configure options to a text file inside the grafbuild directory, so you will know how you built the package and be able to repeat it next time. As a last step grafbuild will ask you whether or not to run the dir2pet script to create PET packages out of the grafbuild subdirectories. This stage, however, is not always desirable because there may be some further tweaking that needs to be done before the packages are created.
    For added convenience you can also create a text file called "grafbuild.conf" in the top level of the source package and list the options you want to configure the package with in the file. Grafbuild will read the file and run configure with those options, plus it will add in any other options you specify on the command line. If you need to rebuild for any reason, you can take the "options" file out of the grafbuild subdirectory, which was created when the package was first installed, and move it to the top level as "grafbuild.conf" and the package will be built with the same options. I often use this feature when a package has a very long list of options which it can be built with. A good example would be php, which has literally dozens of configuration options.
Top

Package standards and good practices

    Once you have finished running grafbuild there may very well be some things that need to be tweaked a bit. For instance, you may need to add a menu entry by creating a ".desktop" file in /usr/share/applications, or you may want to supply a help file. In many cases applications will come with a unix man page, which is often enough help. However, first it must be converted to html and placed into the proper location in the filesystem. I've created a bit of a shortcut here as well. Say you have a total of five man pages in /usr/man/man1 and /usr/man/man5. Go into the "man1" subdirectory and type "manconv", then do the same in "man5". All of the pages will be converted using the man2html program, and you can then move them to the proper location in /usr/share/doc.
    Menu entries may also need to be tweaked a bit in order to work properly with Grafpup's menu system. You can open up a .desktop file in any text editor to make any needed changes. Quite often the execute command will be given with a %f tagged onto the end, which must be stripped off. This is used by KDE and Gnome desktop environments but will only confuse things with openbox or lxpanel. Also, icons should not be specified with their full path. They should instead just name an icon, which will usually be in /usr/share/pixmaps.
    Speaking of icons, they can be placed in the top level of the package directory. During installation the icons will then automatically be moved to the proper location.
    Another thing you may need to do is to create a post installation and/or a post uninstall script. A good example would be the script fn or dbus, which creates a unique system id for your computer. Some daemons like mysql will have to create a user on the system for their process to run as. It is good form to remove such changes if a package is uninstalled, hence the post uninstall script. These scripts should be named "pinstall.sh" and "puninstall.sh" and placed into the top level of the package.
Top

Optimizations and file locations

When creating packages for yourself they can be built and optimized in any way that suits you. However, for a package which will be redistributed there are a few guidelines which should be followed. Puppy is compiled for an i486 architechture, meaning it will run on not only a 486 processor but also anything newer. However, I personally think that Grafpup would not be a great system to run on a machine that old, so the standard is instead to compile with the flags "--host=i586-t2-linux-gnu" or "--build=i586-t2-gnu-linux", depending on which is recognized by the package. This optimizes for i586 and newer instruction sets. Now, a 586 processor would not make a good machine to run image editing applications on, or multimedia applications in general. However Grafpup is versatile enough that I do run it on a couple old AMD K6's.
Going just a bit further, there are some standard locations I like to have certain files installed to. My preference is that anything X-windows or WindowManager related should install into /usr/X11R7, although there are a couple exceptions like KDE which goes in /opt/kde. Most every other package can be compiled with "--prefix=/usr", although /usr/local is also acceptable. In all cases you should put configuration files into /etc and local state files (logfiles, lockfiles) into /var. This can usually be accomplished with the options "--sysconfdir=/etc --localstatedir=/var". If you are compiling some server and it uses a unix socket, the socket should go into /tmp.
Top

Writing applications for Grafpup

Puppy and Grafpup both contain a healthy number of applications that are specific to the breed. They have been developed by enthusiasts specifically for our system and are highly optimized for it. If you have a desire to do some programming by all means your efforts would be welcomed and encouraged. Every attempt has been made to create a system which provides a lot of easy to use utilities and languages, while staying within the constraints of the small base size. This restriction unfortunately means that some popular languages like ruby and python are not included in the default installation, but there are others which are that are quite usable as well as being space and resource efficient.

Shell scripting

    The best way to start, especially to those who are new to Linux or computing, is shell scripting. This is basically just stringing commands together which could be run in a terminal, and for that reason has the added benefit of making it easy to test and troubleshoot your programs. For those who think that you cannot develop powerful applications this way just take a look at some of the custom applications already in Grafpup, like the network wizard. The wizard is entirely a bash script, but takes advantage of several of our gui utilities like gtkdialog and Xdialog. Other examples would be the package manager, PBcdripper, and the cd burning program Grafburn.
    Speaking of gui utilities you have quite a large number of them available for your use in Grafpup. They range from the incredibly simple to extremely complex in what they can achieve. Here is a rundown, in approximate order of complexity and power.
     Gxmessage is an xmessage clone with a few added features. It is primarilyuseful for message boxes and very small wizards, but also has an input widget for typing in text.
    Xdialog is a gui clone of the console program "dialog" with a few extra widgets and features. This program has become somewhat common and recognizable on Linux, however Puppy and Grafpup use a modified version which is built against gtk2 libraries for a much nicer looking interface. It has also been specially patched to fix bugs which are present in the regular source distribution.
    Gins is a very small binary which can be run from shell scripts and is basically an interpreter for .glade files, which are created using the glade gui designer. This is somewhat buggy still and not yet recommended.
    Gtkdialog is probably the most powerful tool available through regular shell scripting, which can be used to create some very complex gui designs. It is however somewhat clunky to program with an xml syntax that is widely disliked by many users. Even so, gtkdialog has a lot of very interesting and useful features like the ability to use .glade files and several widgets which are not available via the other gui tools for shell scripts. Two good examples would be the tabframe and the new style gtk file selector widget. This is actually the place I would recommend starting.
    A few tips on preferred conventions here. Often icons will be used in your interface designs, whether they be for buttons, menu items, or just decoration. Gtkdialog gives you several different ways to add pixmap images, but for things like menu icons and buttons I prefer you use stock gtk icons rather than getting the icons from a file. This makes your programs more portable and also ensures they will reflect the icon theme which the user has chosen to use. For specifics on how this is done see the gtkdialog documentation and examples.
Top

Puppybasic

Puppybasic is a modification of wxbasicscript created for Puppy Linux by Mark Ulrich. This is a rather powerful scripting language in the Basic style with full access to many graphical widgets. Mark has also written a rather large number of applications using his utilities, many of which you can find in Grafpup or in it's repositories. Some good documentation can be found on the web at http://noforum.de/wxBasicscript-documentation/wxbasicscript/index.htm. Note that although several of the major applications which are written in Puppybasic have been removed from the iso recently, the platform is still supported and developers are encouraged to learn and to use it.
Top

Tcl/Tk and Gnocl

The scripting language tcl is quite well loved by those who know how to use it, and probably with good reason. The code is small and elegant but there is almost no limit to the applications that can be created in tcl. The graphical widget set tk runs on top of tcl and has a large number of widgets available for gui design. A good example of what can be achieved in tcl is mut, written by Jessy Liley. Mut is a disc mounter and a way to access all kinds of removable media like flash drives and cameras. A good tutorial for those who want to learn tcl/tk is online at http://www.tcl.tk/man/tcl8.5/tutorial/tcltutorial.html.
Adding another twist to tcl is Gnocl, which is a way to use tcl to write gtk2 applications. You get the same kind of compact code and all the power of tcl, but the resulting applications will match very closely with the majority of the applications on the system.
Top

Compiled programs

For those who prefer to write applications that will run in binary form, please go right ahead because there's nothing stopping you. Once the compiler has been installed via the devx module you basically have a full development environment. For programming gtk applications glade is available via the package manager, and for those who prefer c++ programs you might try using the fluid interface designer, which generates code for fltk based applications. At some point in the future I may even make qt designer available.
Top

Submitting packages

Right now there is no standard location to upload packages for consideration. If you are serious about contributing to the project just get in touch with me and we will work something out. I run an ftp server out of my home and have in the past created accounts for certain members of the community. This is probably my preferred way of doing things since they will be uploaded to the same computer I use for developing the system and can be kept in one unified location until I find the time to check things over.
Alternatively you can post your work to some server and tell me where it is. The problem is that then I have to go fetch it, and sometimes things fall through the cracks this way. I am often away from home for several days at a time so I have to leave myself notes about things, and usually the list gets pretty long before I make it back home.
Top

Submitting artwork

    Another one of the aims of the Grafpup project is to make the distro beautiful. Several people have submitted artwork for this purpose, to the great improvement of the distribution. Examples of things which could be beautified are wallpapers, gtk themes, window manager themes, the bootup splash, or just think of something. The website itself could also use a lot of improvement, but that is already being taken care of by one of our members.
    Submitting artwork is pretty easy. Just register for an account on the gallery and upload your images there. If you want to work on a specific part just send me a PM via the forum so we can talk about it. Sometimes certain things will need to be created with certain specs.
    I like to archive things well when it comes to Grafpup. For that reason I would appreciate it if you could send your working image files along with the finished ones. For instance if you are creating a multiple layered image in Gimp please send both a finished jpeg and the unflattened xcf file.
    For things like themes it can get a little more complicated. Your best bet would be to contact me directly on the forum about getting your files to me, via pm.
Top

Licensing

My preference for Grafpup is to keep the majority of the applications under one of the versions of the gpl. If an application has a different license then please do let me know about it. There are times when a proprietary application is the best one for the job, such as Opera or XnView. However, all software offered in the distro and in the package repo must at all times be legal. My preference goes in this order.

GPL 1,2, or 3
BSD style license
freeware license

For items other than software like icons, images, or maybe fonts other licenses are appropriate. A few good examples would be the creative commons or open font licenses. In all cases I prefer that things are licensed under some type of open license and that appropriate source files are avialable as well. In the case of most software programs this is the c and c++ files as well as associated Makefiles that are used to generate the binaries. In the case of an icon or image this might be an svg file, xcf (gimp) file, or some other format that retains things like layer information and the original image scale.
In all cases when submitting a binary package please submit the source as well, plus any patches you may have applied. It is my intention to try and maintain strict gpl compliance with Grafpup.
Top

Documentation

If you have an interest in helping out with Grafpup, but are not confident in your technical skills, then please consider helping with documentation. There is a real need to update certain bits of information both in the live cd and online. In fact, a lot of documentation just plain hasn't been written yet.
The most pressing portions right now are the "howto" section in the help docs that are included in the live cd. These are all still Puppy specific still so a lot of the information in them does not apply to Grafpup. What's worse, they're terribly out of date.
Top