From 67aaf7afea67a8d4fbb35d1323909647db3ff779 Mon Sep 17 00:00:00 2001 From: Ivy Foster Date: Tue, 18 Mar 2008 01:02:18 -0400 Subject: [PATCH] Documentation improvements - Created HACKING with some information about StumpWM-specific code such as defcommand, as well as some general pointers about working on StumpWM that may seem like common sense and a section on effectively using git. - Edited README a little bit, added info. on using asdf-install to install cl-ppcre on clisp. - Um, added self to AUTHORS (I think that's the protocol...feel free to undo if not; did this less out of desire for credit than so questions RE: contributions could be directed more easily) and lined up the columns a bit. --- .gitignore | 1 + AUTHORS | 43 +++++---- HACKING | 300 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ README | 36 +++++-- 4 files changed, 348 insertions(+), 32 deletions(-) create mode 100644 HACKING diff --git a/.gitignore b/.gitignore index 9d11a6f..68ff6c2 100644 --- a/.gitignore +++ b/.gitignore @@ -15,3 +15,4 @@ version.lisp stumpwm-*.tgz stumpwm-*.tgz.sig .dotest +patches diff --git a/AUTHORS b/AUTHORS index b5359d6..91f7050 100644 --- a/AUTHORS +++ b/AUTHORS @@ -1,28 +1,29 @@ The Stump Window Manager Authors -------------------------------- -Shawn Betts sabetts at gmail com -Ryan M. Golbeck rmgolbeck at uwaterloo ca -Manuel Giraud manuel.giraud at cetp ipsl fr -Andreas Scholta andreas.scholta at gmail com -Philippe Brochard hocwp at free fr -Matthew Kennedy mkennedy at gentoo org -Phil Gregory phil_g at pobox com -Jeremy Hankins nowan at nowan org -Martin Bishop martinbishop at bellsouth net -David Hansen david.hansen at gmx net -Gwern Branwen gwern0 at gmail com -Jay Belanger belanger at truman edu -Magnus Henoch mange at freemail hu +Shawn Betts sabetts at gmail com +Ryan M. Golbeck rmgolbeck at uwaterloo ca +Manuel Giraud manuel.giraud at cetp ipsl fr +Andreas Scholta andreas.scholta at gmail com +Philippe Brochard hocwp at free fr +Matthew Kennedy mkennedy at gentoo org +Phil Gregory phil_g at pobox com +Jeremy Hankins nowan at nowan org +Martin Bishop martinbishop at bellsouth net +David Hansen david.hansen at gmx net +Gwern Branwen gwern0 at gmail com +Jay Belanger belanger at truman edu +Magnus Henoch mange at freemail hu Johannes Weiner -Luca Capello luca at pca it +Luca Capello luca at pca it Luigi Panzeri -James Wright james at chumsley org -Jonathan Liles wantingwaiting at users sf net +James Wright james at chumsley org +Jonathan Liles wantingwaiting at users sf net Istvan Marko -Tassilo Horn tassilo at member dot fsf dot org -Morgan Veyret patzy at appart kicks-ass net -Antonis Antoniadis cereal.killer.rules at gmail com +Tassilo Horn tassilo at member dot fsf dot org +Morgan Veyret patzy at appart kicks-ass net +Antonis Antoniadis cereal.killer.rules at gmail com Jeronimo Pellegrini j_p at aleph0 info -James Wright james at chumsley org -Vitaly Mayatskikh v.mayatskih at gmail com +James Wright james at chumsley org +Vitaly Mayatskikh v.mayatskih at gmail com +Ivy Foster ivy dot foster at gmail dot com diff --git a/HACKING b/HACKING new file mode 100644 index 0000000..17624a8 --- /dev/null +++ b/HACKING @@ -0,0 +1,300 @@ + Hacking the Stump Window Manager + -------------------------------- + +Table of Contents +----------------- + +1) Background and Scope +2) Obtaining StumpWM +3) Hacking StumpWM +4) Using git With StumpWM +5) References (not explicitly cited) +6) Footnotes + + +Background and Scope +-------------------- + +StumpWM is a window manager written in Common Lisp. According to the +StumpWM homepage[1]: + + Stumpwm attempts to be customizable yet visually minimal. There + are no window decorations, no icons, and no buttons. It does have + various hooks to attach your personal customizations, and + variables to tweak. + + * Hack the good hack + * debug your good hack + * customize your window manager + + while it's running. That's right. With a 100% Common Lisp window + manager there's no stopping the hacks. Just re-eval and GO! + +That's all well and good, but just how do you get started on the good +hack? How do you let others know how good your hack is? This document +should hopefully get you started writing your very own code to use +with the Stump Window Manager. + +This is not an introduction to Common Lisp, mind you; there is already +a wealth of information available on the Internet dealing with that +subject. For more information on that, please see the Common Lisp +Wiki[2] or your favorite Internet search engine. + +The goal here is an introduction to StumpWM coding in particular as +well as some information on effectively using git, the version control +system used by StumpWM's authors. + +Obtaining StumpWM +----------------- + +StumpWM can be obtained from the StumpWM homepage[1]. For detailed +installation instructions, please see the README file that you should +have received along with this HACKING file. + + +Hacking StumpWM +--------------- + +For those of you who have worked on Free Software projects before, +this part should probably be fairly intuitive. + +- Pay attention to file names and contents. If you're making changes + to mode-line related code, don't put it in core.lisp. If you're + introducing some completely new featureset, consider putting all of + the new code in a new file. + +- Does a command need to be user-visible ("interactive") or is it + just called by other commands? + + - If it's not going to be user-visible, you can just use the + familiar (defun foo ()...) syntax. + + - If you want the command to be used interactively, you use + StumpWM's defcommand syntax, as in the examples below. + + (defcommand test (foo bar) + ((:string "How you're going to prompt for variable foo: ") + (:number "How you want to prompt for variable bar: ")) + "This command is a test" + (body...)) + + (defcommand test2 () () + "This is also a test" + (body...)) + + (defcommand title (args) (interactive-args) + "Doc string" + (body...)) + + ...so basically, inside the first set of parentheses after the + function name, you specify what (if any) arguments will be passed + to the command. The second set of parentheses tells StumpWM how to + get those arguments if they're not explicitly passed to the + command. For example, + + ((:string "What do you want to do: ")) + + ...will read a string from the input the user provides. The quoted + text is the prompt the user will see. Of course, if you were to, + say, call the command test, as defined above, from another piece + of code, it wouldn't give the prompt as long as you fed it + arguments. + + Note that all commands defined using the defcommand syntax are + available both to be called with "C-t ;" and from within other + lisp programs, as though they had been defun-ned (which, in fact, + they have). + +- Any code that depends on external libraries or programs that some + users might not have installed should be placed in the contrib/ + directory. + +- Don't be afraid to submit your patches to the StumpWM mailing + list[3]! It may not immediately make it into the official git + repository, but individual users might find it useful and apply it + to their own setup, or might be willing to offer suggestions on how + to improve the code. + +- Remember: StumpWM is designed to run on both clisp and on SBCL. If + you must use code specific to one or the other, at the very least + warn people that it only works with one lisp implementation. Better + yet, figure out how to do it in the other distribution and write + a statement like this: + + #+clisp + (your-clisp-code) + #+sbcl + (your-sbcl-code) + + ...to wrap the code for each lisp. Of course, the best option is to + find a way to use the same code for clisp and SBCL. + + +Using git With StumpWM +---------------------- + +This next part is long, sorry. The rationale for this is that +people working on StumpWM are likely to have some degree of experience +at least looking at code, but might not necessarily have experience +with this particular method of version control (or any method, for +that matter). And I concentrate on branching in this part because (a) +I think it's cool, and (b) it allows people to be creative and take +risks without having to worry about messing up their whole install. + +For quite a while now, StumpWM has been using the git version control +system[4] for development. If you're one using one of the official +releases or still using the now-obsolete CVS version, you can get the +bleeding-edge source code from the official git repository with +a single command: + +$ git clone git://git.savannah.nongnu.org/stumpwm.git + +After this, you'll have a complete git repository, along with the +complete revision history since the switch. Feel free to play around; +git has some important features that actually make this safe! + +Before we get to that stuff, though, you're going to want to tell git +about yourself so that your information is included in your commits +and patches. The very minimum you're going to want to do is: + +$ git config --global user.name "Anne N. O'Nymous" +$ git config --global user.email "address@hidden" + +Be sure to check out the manual for git-config--there are several +options you might want to set, such as enabling colorized output or +changing the editor and pager you use when making commits and viewing +logs. + +For the sake of argument, let's say you want to make some major +changes to both user.lisp and core.lisp, add a file called +DANGEROUS_EXPERIMENT_DO_NOT_USE_OR_ELSE.lisp, and remove the manual +because you're too 1337 for such things. However, you don't want to +break your entire StumpWM setup and start over. Thankfully, you don't +have to. Before you get started, issue this command from the stumpwm +directory: + +$ git checkout -b experimental + +You should now find yourself in a new branch, called experimental. To +confirm this, type "git branch" (without the quotes); there should be +an asterisk next to the branch you're currently viewing. At any time, +you can type "git checkout master" to return to your master branch, +and at any time you can have as many branches of the project as you +like. If you want to create a new branch based not on the master +branch but on your experimental branch, for example, you'd type: + +$ git checkout -b new-experiment experimental + +This will place you in a newly-created branch called new-experiment +which should be identical to your experimental branch as of the last +commit (more on that soon). If you're actually typing out the +directions, switch back to your old experimental branch like so: + +$ git checkout experimental + +Anyway, now that you have a new branch, create that new file with the +long name, which I'll just call danger.lisp for brevity. Make whatever +changes you want to it, and when you're done, tell git about your new +file. + +$ git add dangerous.lisp + +Now, let's pretend you're done making changes. Tell git you're done +for now: + +$ git commit -a + +This will open up a prompt in your editor of choice for you to +describe your changes. Try to keep the first line short, and then add +more explanation underneath (for an example, run the command "git log" +and take a look at some of the longer commit explanations). Save that +file and then do this: + +$ git checkout master +$ ls + +...and look for your new file. It's not there! That's because you've +done all of your work in another branch, which git is currently hiding +from you so that you can "check out" the branch called "master." All +is as it should be--your master repository is still safe. + +$ git checkout experimental + +Now, delete manual.lisp and stumpwm.texi. That's right. Wipe them off +the face of the Earth, or at least off the hard drive of your +computer. When you're done, you don't have to tell git you've deleted +them; it'll figure it out on its own (though things may not compile +properly unless you edit Makefile.in and stumpwm.asd. Anyway, go ahead +and edit core.lisp and user.lisp. Really break 'em. Run free! When +you're done, do another commit, as above, and give it a stupid title +like "lolz i b0rked stUmpwm guys wTF!?!?!!111!" Now try to compile. +Just try. It won't work. If it does, you're some kind of savant or +something. Keep up the good work. If you've actually managed to break +StumpWM like you were supposed to, never fear! You have two options at +this point. + +One is to go back to the master branch (with another git checkout) and +just delete your experimental branch, like so: + +$ git branch -D + +The "-D" means to force a delete, even if the changes you've made +aren't available elsewhere. A "-d" means to delete the branch if and +only if you've merged the changes in elsewhere. + +The other option is to create patches for each of your commits so far, +delete the branch, and then apply any working/wanted patches in a new +branch. Create your patches (after committing) like so: + +$ git format-patch -o patches origin + +(Before doing that you can review your changes with "git log origin..") + +You can also use the format-patch command to create a patch of working +code to send in to the mailing list. + +A developer might ask you to try out something they're working on. To +fetch their master branch, you'd do this: + +$ git remote add -f -m master -t master foo git://bar.org/~foo/stumpwm + +...where "foo" is the shorthand name you'll use to refer to that +repository in the future. To checkout a local copy of that repository, +you'd then do this: + +$ git checkout --track -b foo-master foo/master + +...and could use "git pull foo" to update later while looking at that +branch (and note that "git pull" with no arguments, in the master +branch, will update your StumpWM from the official repository. + +Finally, if you want to move your experimental changes into your +master branch, you'd checkout your master branch and run: + +$ git merge experimental + +If there are file conflicts, "git diff" will show you where they are; +you have to fix them by hand. When you're done, do another + +$ git commit -a + +...to finalize the changes to your master branch. You can then delete +your experimental branch. Alternately, you can wait until your changes +(assuming you sent them in) make it into the official repository +before deleting your experimental branch. + + +References (not explicitly cited) +--------------------------------- + +- The StumpWM source code +- http://www.kernel.org/pub/software/scm/git/docs/tutorial.html +- http://stumpwm.antidesktop.net/cgi-bin/wiki/Git + +Footnotes +--------- + +[1] http://www.nongnu.org/stumpwm +[2] http://www.cliki.net +[3] http://lists.nongnu.org/mailman/listinfo/stumpwm-devel +[4] http://git.or.cz diff --git a/README b/README index 3e7f86d..e1ab208 100644 --- a/README +++ b/README @@ -15,21 +15,35 @@ Build & Start Stumpwm Prerequisites ============= -* a common lisp distribution. clisp or SBCL both work. +* a common lisp distribution. clisp and SBCL both work. * clx * cl-ppcre If you intend to use sbcl you need to install portable-clx. If you're -using clisp, make sure it is at least version 1.42 and has been +using clisp, make sure you use at least version 1.42 and that clisp is compiled with new-clx. As of clisp 1.42, new-clx works fine with stumpwm. Any version before that is too buggy to run stumpwm. You can use asdf-install to install lisp libraries: -$ sbcl -* (require 'asdf) -* (require 'asdf-install) -* (asdf-install:install 'clx) -* (asdf-install:install 'cl-ppcre) + $ sbcl + * (require 'asdf) + * (require 'asdf-install) + * (asdf-install:install 'clx) + * (asdf-install:install 'cl-ppcre) + +If using clisp, you'll need to install asdf first to use asdf-install. + $ mkdir -p ~/.cl/asdf && cd ~/.cl + $ wget http://cclan.cvs.sourceforge.net/*checkout*/cclan/asdf/asdf.lisp -O ~/.cl/asdf/asdf.lisp + $ echo "(load #p\"/home/USER/.cl/asdf/asdf\")" >> ~/.clisprc.lisp + $ mkdir -p ~/.cl/systems + $ echo "(push #p\"/home/USER/.cl/systems\" asdf:*central-registry*)" >> ~/.clisprc.lisp + $ wget http://common-lisp.net/project/asdf-install/asdf-install_latest.tar.gz + $ tar xf asdf-install_latest.tar.gz + $ ln -s ~/.cl/asdf-install/asdf-install/asdf-install.asd ~/.cl/systems/ + $ clisp + * (asdf:operate 'asdf:compile-op 'asdf-install) + * (asdf:operate 'asdf:load-op 'asdf-install) + * (asdf-install:install :cl-ppcre) Your operating system distribution may also have these libraries available. @@ -45,7 +59,8 @@ If there's already a configure script then just run it. $ ./configure -By default stumpwm elects sbcl. You can explicitely use clisp this way: +By default stumpwm elects sbcl. If you have both installed, you can +explicitly select clisp like so: $ ./configure --with-lisp=clisp @@ -63,7 +78,7 @@ of the stumpwm/ directory. Now that you have a binary, call it from your ~/.xinitrc file: -$ echo /path/to/stumpwm > ~/.xinitrc +$ echo /path/to/stumpwm >> ~/.xinitrc $ startx Hopefully that will put you in X running stumpwm! @@ -91,6 +106,5 @@ There's a #stumpwm channel on irc.freenode.net, too. Questions? ---------- -See http://stumpwm.nongnu.org/community.html for information on +See http://stumpwm.nongnu.org/community.html for more information on contacting stumpwm developers and users. - -- 1.5.3.7