Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Added HACKING section to the manual.

  • Loading branch information...
commit b53c01d617c5e49a262da53c29767a5c72775d45 1 parent c7a37fa
Ivy Foster authored Shawn committed

Showing 1 changed file with 283 additions and 0 deletions. Show diff stats Hide diff stats

  1. +283 0 stumpwm.texi.in
283 stumpwm.texi.in
@@ -91,6 +91,7 @@ This document explains how to use The Stump Window Manager.
91 91 * Interacting With X11::
92 92 * Miscellaneous Commands::
93 93 * Hooks::
  94 +* Hacking::
94 95 * Command and Function Index::
95 96 * Variable Index::
96 97
@@ -139,6 +140,11 @@ Miscellaneous Commands
139 140 * Timers::
140 141 * Getting Help::
141 142
  143 +Hacking
  144 +
  145 +* General Advice::
  146 +* Using git with StumpWM::
  147 +
142 148 @end detailmenu
143 149 @end menu
144 150
@@ -1074,6 +1080,283 @@ $$$ *key-press-hook*
1074 1080 $$$ *root-click-hook*
1075 1081 $$$ *mode-line-click-hook*
1076 1082
  1083 +@node Hacking, Command and Function Index, Hooks, Top
  1084 +@chapter Hacking
  1085 +
  1086 +For those of you who have worked on Free Software projects before,
  1087 +this part should probably be fairly intuitive.
  1088 +
  1089 +@menu
  1090 +* General Advice::
  1091 +* Using git with StumpWM::
  1092 +@end menu
  1093 +
  1094 +@node General Advice, Using git with StumpWM, , Hacking
  1095 +@section Hacking: General Advice
  1096 +
  1097 +@enumerate
  1098 +
  1099 +@item
  1100 +Pay attention to file names and contents. If you're making changes to
  1101 +mode-line related code, don't put it in core.lisp. If you're
  1102 +introducing some completely new featureset, consider putting all of
  1103 +the new code in a new file.
  1104 +
  1105 +@item
  1106 +Does a command need to be user-visible ("interactive") or is it just
  1107 +called by other commands?
  1108 +
  1109 +@itemize
  1110 +@item
  1111 +If it's not going to be user-visible, you can just use the familiar
  1112 +(defun foo ()...) syntax.
  1113 +
  1114 +@item
  1115 +If you want the command to be used interactively, you use StumpWM's
  1116 +defcommand syntax, as in the examples below.
  1117 +
  1118 +@example
  1119 + (defcommand test (foo bar)
  1120 + ((:string "How you're going to prompt for variable foo: ")
  1121 + (:number "How you want to prompt for variable bar: "))
  1122 + "This command is a test"
  1123 + (body...))
  1124 +
  1125 + (defcommand test2 () ()
  1126 + "This is also a test"
  1127 + (body...))
  1128 +
  1129 + (defcommand title (args) (interactive-args)
  1130 + "Doc string"
  1131 + (body...))
  1132 +@end example
  1133 +
  1134 +...so basically, inside the first set of parentheses after the
  1135 +function name, you specify what (if any) arguments will be passed to
  1136 +the command. The second set of parentheses tells StumpWM how to get
  1137 +those arguments if they're not explicitly passed to the command. For
  1138 +example,
  1139 +
  1140 +@example
  1141 +((:string "What do you want to do: "))
  1142 +@end example
  1143 +
  1144 +...will read a string from the input the user provides. The quoted
  1145 +text is the prompt the user will see. Of course, if you were to, say,
  1146 +call the command test, as defined above, from another piece of code,
  1147 +it wouldn't give the prompt as long as you fed it arguments.
  1148 +@end itemize
  1149 +
  1150 +@item
  1151 +Note that all commands defined using the defcommand syntax are
  1152 +available both to be called with "C-t ;" and from within other lisp
  1153 +programs, as though they had been defun-ned (which, in fact, they
  1154 +have).
  1155 +
  1156 +@item
  1157 +Any code that depends on external libraries or programs that some
  1158 +users might not have installed should be placed in the contrib/
  1159 +directory.
  1160 +
  1161 +@item
  1162 +Don't be afraid to submit your patches to the StumpWM mailing list!
  1163 +It may not immediately make it into the official git repository, but
  1164 +individual users might find it useful and apply it to their own setup,
  1165 +or might be willing to offer suggestions on how to improve the code.
  1166 +
  1167 +@item
  1168 +Remember: StumpWM is designed to run on both clisp and on SBCL. If
  1169 +you must use code specific to one or the other, at the very least warn
  1170 +people that it only works with one lisp implementation. Better yet,
  1171 +figure out how to do it in the other distribution and write a
  1172 +statement like this:
  1173 +
  1174 +@example
  1175 +#+clisp
  1176 +(your-clisp-code)
  1177 +#+sbcl
  1178 +(your-sbcl-code)
  1179 +@end example
  1180 +
  1181 +...to wrap the code for each lisp. Of course, the best option is to
  1182 +find a way to use the same code for clisp and SBCL.
  1183 +@end enumerate
  1184 +
  1185 +@node Using git with StumpWM, , General Advice, Hacking
  1186 +@section Hacking: Using git with StumpWM
  1187 +
  1188 +For quite a while now, StumpWM has been using the git version control
  1189 +system for development. If you're one using one of the official
  1190 +releases or still using the now-obsolete CVS version, you can get the
  1191 +bleeding-edge source code from the official git repository with
  1192 +a single command:
  1193 +
  1194 +@example
  1195 +$ git clone git://git.savannah.nongnu.org/stumpwm.git
  1196 +@end example
  1197 +
  1198 +After this, you'll have a complete git repository, along with the
  1199 +complete revision history since the switch. Feel free to play around;
  1200 +git has some important features that actually make this safe!
  1201 +
  1202 +Before we get to that stuff, though, you're going to want to tell git
  1203 +about yourself so that your information is included in your commits
  1204 +and patches. The very minimum you're going to want to do is:
  1205 +
  1206 +@example
  1207 +$ git config --global user.name "Anne N. O'Nymous"
  1208 +$ git config --global user.email "anonymous@@foo.org"
  1209 +@end example
  1210 +
  1211 +Be sure to check out the manual for git-config--there are several
  1212 +options you might want to set, such as enabling colorized output or
  1213 +changing the editor and pager you use when making commits and viewing
  1214 +logs.
  1215 +
  1216 +For the sake of argument, let's say you want to make some major
  1217 +changes to both user.lisp and core.lisp, add a file called
  1218 +DANGEROUS_EXPERIMENT_DO_NOT_USE_OR_ELSE.lisp, and remove the manual
  1219 +because you're too 1337 for such things. However, you don't want to
  1220 +break your entire StumpWM setup and start over. Thankfully, you don't
  1221 +have to. Before you get started, issue this command from the stumpwm
  1222 +directory:
  1223 +
  1224 +@example
  1225 +$ git checkout -b experimental
  1226 +@end example
  1227 +
  1228 +You should now find yourself in a new branch, called experimental. To
  1229 +confirm this, type "git branch" (without the quotes); there should be
  1230 +an asterisk next to the branch you're currently viewing. At any time,
  1231 +you can type "git checkout master" to return to your master branch,
  1232 +and at any time you can have as many branches of the project as you
  1233 +like. If you want to create a new branch based not on the master
  1234 +branch but on your experimental branch, for example, you'd type:
  1235 +
  1236 +@example
  1237 +$ git checkout -b new-experiment experimental
  1238 +@end example
  1239 +
  1240 +This will place you in a newly-created branch called new-experiment
  1241 +which should be identical to your experimental branch as of the last
  1242 +commit (more on that soon). If you're actually typing out the
  1243 +directions, switch back to your old experimental branch like so:
  1244 +
  1245 +@example
  1246 +$ git checkout experimental
  1247 +@end example
  1248 +
  1249 +Anyway, now that you have a new branch, create that new file with the
  1250 +long name, which I'll just call danger.lisp for brevity. Make whatever
  1251 +changes you want to it, and when you're done, tell git about your new
  1252 +file.
  1253 +
  1254 +@example
  1255 +$ git add dangerous.lisp
  1256 +@end example
  1257 +
  1258 +Now, let's pretend you're done making changes. Tell git you're done
  1259 +for now:
  1260 +
  1261 +@example
  1262 +$ git commit -a
  1263 +@end example
  1264 +
  1265 +This will open up a prompt in your editor of choice for you to
  1266 +describe your changes. Try to keep the first line short, and then add
  1267 +more explanation underneath (for an example, run the command "git log"
  1268 +and take a look at some of the longer commit explanations). Save that
  1269 +file and then do this:
  1270 +
  1271 +@example
  1272 +$ git checkout master
  1273 +$ ls
  1274 +@end example
  1275 +
  1276 +...and look for your new file. It's not there! That's because you've
  1277 +done all of your work in another branch, which git is currently hiding
  1278 +from you so that you can "check out" the branch called "master." All
  1279 +is as it should be--your master repository is still safe.
  1280 +
  1281 +@example
  1282 +$ git checkout experimental
  1283 +@end example
  1284 +
  1285 +Now, delete manual.lisp and stumpwm.texi. That's right. Wipe them off
  1286 +the face of the Earth, or at least off the hard drive of your
  1287 +computer. When you're done, you don't have to tell git you've deleted
  1288 +them; it'll figure it out on its own (though things may not compile
  1289 +properly unless you edit Makefile.in and stumpwm.asd. Anyway, go ahead
  1290 +and edit core.lisp and user.lisp. Really break 'em. Run free! When
  1291 +you're done, do another commit, as above, and give it a stupid title
  1292 +like "lolz i b0rked stUmpwm guys wTF!?!?!!111!" Now try to compile.
  1293 +Just try. It won't work. If it does, you're some kind of savant or
  1294 +something. Keep up the good work. If you've actually managed to break
  1295 +StumpWM like you were supposed to, never fear! You have two options at
  1296 +this point.
  1297 +
  1298 +One is to go back to the master branch (with another git checkout) and
  1299 +just delete your experimental branch, like so:
  1300 +
  1301 +@example
  1302 +$ git branch -D
  1303 +@end example
  1304 +
  1305 +The "-D" means to force a delete, even if the changes you've made
  1306 +aren't available elsewhere. A "-d" means to delete the branch if and
  1307 +only if you've merged the changes in elsewhere.
  1308 +
  1309 +The other option is to create patches for each of your commits so far,
  1310 +delete the branch, and then apply any working/wanted patches in a new
  1311 +branch. Create your patches (after committing) like so:
  1312 +
  1313 +@example
  1314 +$ git format-patch -o patches origin
  1315 +@end example
  1316 +
  1317 +(Before doing that you can review your changes with "git log origin..")
  1318 +
  1319 +You can also use the format-patch command to create a patch of working
  1320 +code to send in to the mailing list.
  1321 +
  1322 +A developer might ask you to try out something they're working on. To
  1323 +fetch their master branch, you'd do this:
  1324 +
  1325 +@example
  1326 +$ git remote add -f -m master -t master foo git://bar.org/~foo/stumpwm
  1327 +@end example
  1328 +
  1329 +...where "foo" is the shorthand name you'll use to refer to that
  1330 +repository in the future. To checkout a local copy of that repository,
  1331 +you'd then do this:
  1332 +
  1333 +@example
  1334 +$ git checkout --track -b foo-master foo/master
  1335 +@end example
  1336 +
  1337 +...and could use "git pull foo" to update later while looking at that
  1338 +branch (and note that "git pull" with no arguments, in the master
  1339 +branch, will update your StumpWM from the official repository.
  1340 +
  1341 +Finally, if you want to move your experimental changes into your
  1342 +master branch, you'd checkout your master branch and run:
  1343 +
  1344 +@example
  1345 +$ git merge experimental
  1346 +@end example
  1347 +
  1348 +If there are file conflicts, "git diff" will show you where they are;
  1349 +you have to fix them by hand. When you're done, do another
  1350 +
  1351 +@example
  1352 +$ git commit -a
  1353 +@end example
  1354 +
  1355 +...to finalize the changes to your master branch. You can then delete
  1356 +your experimental branch. Alternately, you can wait until your changes
  1357 +(assuming you sent them in) make it into the official repository
  1358 +before deleting your experimental branch.
  1359 +
1077 1360 @node Command and Function Index, Variable Index, Hooks, Top
1078 1361 @unnumbered Command and Function Index
1079 1362 @printindex fn

0 comments on commit b53c01d

Please sign in to comment.
Something went wrong with that request. Please try again.