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! 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.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

16.2 Hacking: Using git with StumpWM

For quite a while now, StumpWM has been using the git version control system 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 "anonymous@foo.org"

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; 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

Then 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

Here, “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

$ git checkout --track -b foo-master foo/master

Later you could use git pull foo to update 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.

[ < ]

[ > ]

[ << ]

[ Up ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

16.3 Sending Patches

When sending patches to the mailing list for inclusion in StumpWM, there are a few guidelines that will make everything go smoother.

Make sure it applies clean to the main git repository
Ensure that you aren’t introducing tabs, extra blank lines, or whitespace at the end of lines.
Ensure your patch doesn’t contain irrelevant indenting or reformatting changes.
Try to make your patch address a single issue. If your patch changes two unrelated issues, break them into two seperate patches that can stand on their own.
Don’t send intermediate patches. When you’re working on a feature you might make several commits to your local repository as you refine it and work out the bugs. When it’s polished and ready to ship, send it as one patch! Sometimes it makes sense to send it as multiple patches if each patch contains a discrete feature or bug fix that can stand on its own. If one of your patches changes code that was added or modified in an earlier patch, consider merging them together and sending them as one.

[ << ]

[ >> ]

[Top]

[Contents]

[Index]

[ ? ]

This document was generated by David Bjergaard on November 1, 2014 using texi2html 1.82.