Here are the guidelines for being an Emacs pretester.If you would like to do this, say so, and I'll add you tothe pretest list. Information for Emacs PretestersThe purpose of Emacs pretesting is to verify that the new Emacsdistribution, about to be released, works properly on your system *withno change whatever*, when installed following the preciserecommendations that come with the Emacs distribution.Here are some guidelines on how to do pretesting so as to make ithelpful. All of them follow from common sense together with thenature of the purpose and the situation.Please save this file, and reread it when a new series of pretestsstarts.* Get the pretest from gnu/emacs/emacs-MM.NN.tar.gz andgnu/emacs/leim-MM.NN.tar.gz on alpha.gnu.org.* After a few days of testing, if there are no problems, please reportthat Emacs works for you and what configuration you are testing it on.* If you want to communicate with other pretesters, send mail toemacs-pretesters@gnu.org. I don't use that mailing list when I sendto you because I've found that mailing lists tend to amplify randomnoise into long discussions or even arguments, and that can waste alot of time. But when you have a reason to ask other pretesters forhelp, you can do it that way.* It is absolutely vital that you tell me about even the smallestchange or departure from the standard sources and procedure.Otherwise, you are not testing the same program that I asked you totest. Testing a different program is usually of no use whatever. Itcan even cause trouble if you fail to tell me that you tested someother program instead of what I am about to release. I might thinkthat Emacs works, when in fact it has not even been tried, and mighthave a glaring fault.* Don't use a site-load.el file or a site-init.el file when you pretest.Using either of those files means you are not testing Emacs as a typicalsite would use it.Actually, it does no harm to test Emacs with such customizations *aswell as* testing it "out of the box". Anything you do that could finda bug is useful, as long as you make sure I know exactly what you did.The important point is that testing with local changes is nosubstitute for testing Emacs exactly as it is distributed.* Even changing the compilation options counts as a change in theprogram. The Emacs sources specify which compilation options to use.Some of them are specified in makefiles, and some in machine-specificconfiguration files. They also give you ways to override this--but ifyou do, then you are not testing what ordinary users will do.Therefore, when pretesting, it is vital to test with the defaultcompilation options.(Testing with a different set of options can be useful *in addition*,but not *instead of* the default options.)* The machine and system configuration files of Emacs are parts ofEmacs. So when you test Emacs, you need to do it with theconfiguration files that come with Emacs.If Emacs does not come with configuration files for a certain machine,and you test it with configuration files that don't come with Emacs,this is effectively changing Emacs. Because the crucial fact aboutthe planned release is that, without changes, it doesn't work on thatmachine.To make Emacs work on that machine, I would need to install newconfiguration files. That is not out of the question, since it issafe--it certainly won't break any other machines that already work.But you will have to rush me the legal papers to give the FSFpermission to use such a large piece of text.* Look in the etc/MACHINES file.The etc/MACHINES file says which configuration files to use for yourmachine, so use the ones that are recommended. If you guess, you mightguess wrong and encounter spurious difficulties. What's more, if youdon't follow etc/MACHINES then you aren't helping to test that itsrecommendations are valid.The etc/MACHINES file may describe other things that you need to doto make Emacs work on your machine. If so, you should follow theserecommendations also, for the same reason.* Send your problem reports to emacs-pretest-bug@gnu.org, notbug-gnu-emacs.Sometimes I won't know what to do about a system-dependent issue, andI may need people to tell me what happens if you try a certain thingon a certain system. When this happens, I'll send out a query.* Don't delay sending information.When you test on a system and encounter no problems, please tell meabout it right away. That way, I will know that someone has testedEmacs on that kind of system.Please don't wait for several days "to see if it really works beforeyou say anything." Tell me right away that Emacs seems basically towork; then, if you notice a problem a few days later, tell meimmediately about that when you see it.It is okay if you double check things before reporting a problem, suchas to see if you can easily fix it. But don't wait very long. A goodrule to use in pretesting is always to tell me about every problem onthe same day you encounter it, even if that means you can't find asolution before you report the problem.I'd much rather hear about a problem today and a solution tomorrowthan get both of them tomorrow at the same time.* Make each bug report self-contained.If you refer back to another message, whether from you or from someoneelse, then it will be necessary for anyone who wants to investigatethe bug to find the other message. This may be difficult, it isprobably time-consuming.To help me save time, simply copy the relevant parts of any previousmessages into your own bug report.In particular, if I ask you for more information because a bug reportwas incomplete, it is best to send me the *entire* collection ofrelevant information, all together. If you send just the additionalinformation, that makes me do extra work. There is even a risk thatI won't remember what question you are sending me the answer to.* When you encounter a bug that manifests itself as a Lisp error,try setting debug-on-error to t and making the bug happen again.Then you will get a Lisp backtrace. Including that in your bug reportis very useful.* Debugging optimized code is possible, if you compile with GCC, butin some cases the optimized code can be confusing. If you are notaccustomed to that, recompile Emacs without -O. One way to do this is make clean make CFLAGS=-g* If you use X windows, it is a good idea to run Emacs under GDB (orsome other suitable debugger) *all the time*, at least whilepretesting.Then, when Emacs crashes, you will be able to debug the live process,not just a core dump. The `pr' command defined in src/.gdbinit is veryuseful in this case for examining Lisp_Object values as they wouldappear in Lisp.If you can't use `pr' because Emacs has got a fault already, orbecause you have only a core dump, you can use `xtype' to look at thetype of a value, and then choose one of the other commands `xsymbol',`xstring', `xcons', `xvector' and so on to examine the contents.I myself *always* run Emacs under GDB so that I can debug convenientlyif the occasion arises.* To get Lisp-level backtrace information within GDB,look for stack frames that call Ffuncall. Select them one by one in GDBand type this: p *args prThis will print the name of the Lisp function called by that levelof function calling.By printing the remaining elements of args, you can see the argumentvalues. Here's how to print the first argument: p args[1] prIf you do not have a live process, you can use xtype and the otherx... commands such as xsymbol to get such information, albeit lessconveniently.* Even with a live process, these x... commands are useful forexamining the fields in a buffer, window, process, frame or marker.Here's an example using concepts explained in the node "Value History"of the GDB manual to print the variable frame from this line inxmenu.c: buf.frame_or_window = Fcons (frame, prefix);First, use these commands: cd src gdb emacs b xmenu.c:1209 r -qThen type C-x 5 2 to create a new frame, and it hits the breakpoint: (gdb) p frame $1 = 1077872640 (gdb) xtype Lisp_Vectorlike PVEC_FRAME (gdb) xframe $2 = (struct frame *) 0x3f0800 (gdb) p *$ $3 = { size = 536871989, next = 0x366240, name = 809661752, [...] } (gdb) p $3->name $4 = 809661752Now we can use `pr' to print the name of the frame: (gdb) pr "emacs@steenrod.math.nwu.edu"* The Emacs C code heavily uses macros defined in lisp.h. So supposewe want the address of the l-value expression near the bottom of`kbd_buffer_store_event' from keyboard.c: XVECTOR (kbd_buffer_frame_or_window)->contents[kbd_store_ptr - kbd_buffer] = event->frame_or_window);XVECTOR is a macro, and therefore GDB does not know about it.GDB cannot evaluate p XVECTOR (kbd_buffer_frame_or_window).However, you can use the xvector command in GDB to get the sameresult. Here is how: (gdb) p kbd_buffer_frame_or_window $1 = 1078005760 (gdb) xvector $2 = (struct Lisp_Vector *) 0x411000 0 (gdb) p $->contents[kbd_store_ptr - kbd_buffer] $3 = 1077872640 (gdb) p &$ $4 = (int *) 0x411008* Here's a related example of macros and the GDB `define' command.There are many Lisp vectors such as `recent_keys', which contains thelast 100 keystrokes. We can print this Lisp vectorp recent_keysprBut this may be inconvenient, since `recent_keys' is much more verbosethan `C-h l'. We might want to print only the last 10 elements ofthis vector. `recent_keys' is updated in keyboard.c by the command XVECTOR (recent_keys)->contents[recent_keys_index] = c;So we define a GDB command `xvector-elts', so the last 10 keystrokesare printed by xvector-elts recent_keys recent_keys_index 10where you can define xvector-elts as follows: define xvector-elts set $i = 0 p $arg0 xvector set $foo = $ while $i < $arg2 p $foo->contents[$arg1-($i++)] pr end document xvector-elts Prints a range of elements of a Lisp vector. xvector-elts v n i prints `i' elements of the vector `v' ending at the index `n'. end* To debug what happens while preloading and dumping Emacs,do `gdb temacs' and start it with `r -batch -l loadup dump'.If temacs actually succeeds when running under GDB in this way, do nottry to run the dumped Emacs, because it was dumped with the GDBbreakpoints in it.* If you encounter X protocol errors, try evaluating (x-synchronize t).That puts Emacs into synchronous mode, where each Xlib call checks forerrors before it returns. This mode is much slower, but when you getan error, you will see exactly which call really caused the error.* If the symptom of the bug is that Emacs fails to respond, don'tassume Emacs is `hung'--it may instead be in an infinite loop. Tofind out which, make the problem happen under GDB and stop Emacs onceit is not responding. (If Emacs is using X Windows directly, you canstop Emacs by typing C-z at the GDB job.) Then try stepping with`step'. If Emacs is hung, the `step' command won't return. If it islooping, `step' will return.If this shows Emacs is hung in a system call, stop it again andexamine the arguments of the call. In your bug report, state exactlywhere in the source the system call is, and what the arguments are.If Emacs is in an infinite loop, please determine where the loopstarts and ends. The easiest way to do this is to use the GDB command`finish'. Each time you use it, Emacs resumes execution until itexits one stack frame. Keep typing `finish' until it doesn'treturn--that means the infinite loop is in the stack frame which youjust tried to finish.Stop Emacs again, and use `finish' repeatedly again until you get backto that frame. Then use `next' to step through that frame. Bystepping, you will see where the loop starts and ends. Also pleaseexamine the data being used in the loop and try to determine why theloop does not exit when it should. Include all of this information inyour bug report.* If certain operations in Emacs are slower than they used to be, hereis some advice for how to find out why.Stop Emacs repeatedly during the slow operation, and make a backtraceeach time. Compare the backtraces looking for a pattern--a specificfunction that shows up more often than you'd expect.If you don't see a pattern in the C backtraces, get some Lispbacktrace information by looking at Ffuncall frames (see above), andagain look for a pattern.When using X, you can stop Emacs at any time by typing C-z at GDB.When not using X, you can do this with C-g.* Configure tries to figure out what kind of system you have bycompiling and linking programs which calls various functions and looksat whether that succeeds. The file config.log contains any messagesproduced by compilers while running configure, to aid debugging ifconfigure makes a mistake. But note that config.cache reads:# Giving --cache-file=/dev/null disables caching, for debugging configure.or more simply,rm config.cache./configure* Always be precise when talking about changes you have made. Showthings rather than describing them. Use exact filenames (relative tothe main directory of the distribution), not partial ones. Forexample, say "I changed Makefile" rather than "I changed themakefile". Instead of saying "I defined the MUMBLE macro", send adiff.* Always use `diff -c' to make diffs. If you don't include context, itmay be hard for me to figure out where you propose to make thechanges. So I might have to ignore your patch.* When you write a fix, keep in mind that I can't install a changethat *might* break other systems without the risk that it will fail towork and therefore require an additional cycle of pretesting.People often suggest fixing a problem by changing config.h orsrc/ymakefile or even src/Makefile to do something special that aparticular system needs. Sometimes it is totally obvious that suchchanges would break Emacs for almost all users. I can't possibly makea change like that. All I can do is send it back to you and ask youto find a fix that is safe to install.Sometimes people send fixes that *might* be an improvement ingeneral--but it is hard to be sure of this. I can install suchchanges some of the time, but not during pretest, when I am trying toget a new version to work reliably as quickly as possible.The safest changes for me to install are changes to the s- and m-files. At least I know those can't affect most systems.Another safe kind of change is one that uses a conditional to makesure it will apply only to a particular kind of system. Ordinarily,that is a bad way to solve a problem, and I would want to find acleaner alternative. But the virtue of safety can make it superior atpretest time.* Don't try changing Emacs *in any way* unless it fails to work unchanged.* Don't even suggest changes to add features or make somethingcleaner. Every change I install could introduce a bug, so I won'tinstall a change during pretest unless I see it is *necessary*.* If you would like to suggest changes for purposes other than fixinguser-visible bugs, don't wait till pretest time. Instead, send themafter I have made a release that proves to be stable. Then I can giveyour suggestions proper consideration. If you send them at pretesttime, I will have to defer them till later, and that might mean Iforget all about them.* In some cases, if you don't follow these guidelines, yourinformation might still be useful, but I might have to do more work tomake use of it. Unfortunately, I am so far behind in my work that Ijust can't keep up unless you help me to do it efficiently.Some suggestions for debugging on MS Windows: Marc Fleischeuers, Geoff Voelker and Andrew InnesTo debug emacs with Microsoft Visual C++, you either start emacs fromthe debugger or attach the debugger to a running emacs process. Tostart emacs from the debugger, you can use the file bin/debug.bat. TheMicrosoft Developer studio will start and under Project, Settings,Debug, General you can set the command-line arguments and emacs'startup directory. Set breakpoints (Edit, Breakpoints) at Fsignal andother functions that you want to examine. Run the program (Build,Start debug). Emacs will start and the debugger will take control assoon as a breakpoint is hit.You can also attach the debugger to an already running emacs process.To do this, start up the Microsoft Developer studio and select Build,Start debug, Attach to process. Choose the emacs process from thelist. Send a break to the running process (Debug, Break) and you willfind that execution is halted somewhere in user32.dll. Open the stacktrace window and go up the stack to w32_msg_pump. Now you can setbreakpoints in emacs (Edit, Breakpoints). Continue the running emacsprocess (Debug, Step out) and control will return to emacs, until abreakpoint is hit.To examine the contents of a lisp variable, you can use the function'debug_print'. Right-click on a variable, select QuickWatch, andplace 'debug_print(' and ')' around the expression. Press'Recalculate' and the output is sent to the 'Debug' pane in the Outputwindow. If emacs was started from the debugger, a console window wasopened at emacs' startup; this console window also shows the output of'debug_print'. It is also possible to keep appropriately masked andtypecast lisp symbols in the Watch window, this is more convenientwhen steeping though the code. For instance, on enteringapply_lambda, you can watch (struct Lisp_Symbol *) (0xfffffff &args[0]).Local Variables:mode: textEnd:# arch-tag: caf47b2c-b56b-44f7-a760-b5bfbed15fd3