![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to INSTALL CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSD / contrib / emacs|
Return to INSTALL CVS log | Up to [CSRG BSD Unix] / 43BSD / contrib / emacs |
1.1 root 1: GNU Emacs Installation Guide
2: Copyright (c) 1985 Richard M. Stallman
3:
4: Permission is granted to anyone to make or distribute verbatim copies
5: of this document as received, in any medium, provided that the
6: copyright notice and permission notice are preserved,
7: and that the distributor grants the recipient permission
8: for further redistribution as permitted by this notice.
9:
10: Permission is granted to distribute modified versions
11: of this document, or of portions of it,
12: under the above conditions, provided also that they
13: carry prominent notices stating who last changed them,
14: and that any new or changed statements about me (Richard Stallman)
15: or my activities are approved by me.
16:
17:
18: PREPARATION
19:
20: 0) Make sure your system has enough swapping space allocated
21: to handle a program whose pure code is 400k bytes or
22: and whose data area is at least 150k and can reach 600k
23: bytes or much more. If the swapping space is insufficient, you
24: will get an error in the command temacs -l loadup inc dump,
25: found in $BUILD/src/ymakefile, or possibly when running the
26: final dumped Emacs.
27:
28: 1) Choose a place in the file structure for the main directory
29: of Emacs code to reside. This will ultimately have
30: subdirectories named info, lisp, etc, etc. Call this name
31: $EMACS. Let $BUILD stand for the name the directory has now.
32:
33: 2) Copy $BUILD/src/config.h.dist to config.h, and edit it to
34: set the right options for your system. The file
35: $BUILD/etc/MACHINES may help you decide what to put there.
36:
37: 3) Copy $BUILD/src/paths.h.dist to paths.h, and edit it to
38: contain the correct directory names: $EMACS/lisp for the
39: directory for Lisp libraries, and $EMACS/etc for the
40: directory for executables and text files.
41:
42: Emacs will use these names once it has been built.
43: During building, Emacs searches the directory ../lisp for
44: Lisp files before the directories specified in paths.h, and
45: executable files are found in ../etc. So the main Emacs
46: directory $BUILD can be anywhere while Emacs is built, but
47: must be renamed to $EMACS afterwards in order for Emacs to
48: work properly.
49:
50: 4) Look at $BUILD/lisp/paths.el; if some of those values
51: are not right for your system, create a file
52: $BUILD/lisp/site-init.el containing Lisp code to override them.
53: You would use the Lisp function `setq'. For example,
54:
55: (setq news-inews-program "/usr/bin/inews")
56:
57: is how you would override the default value of the
58: variable news-inews-program (which is "/usr/local/inews").
59:
60: 5) Put into $BUILD/lisp/site-init.el any Lisp code
61: you want loaded into Emacs before it is dumped out.
62:
63: This file is nonexistent in the distribution.
64: You do not need to create it, if you have nothing
65: to put in it.
66:
67: 6) Decide what compiler switches to use.
68: You might want to replace the `-g' in the file $BUILD/src/ymakefile
69: with `-O'. If you are not running on 4.2 on a vax,
70: it is possible that no debugger you have will be able
71: to run Emacs with its symbol table, so you might as well
72: use `-O' instead. If you do have a debugger that works,
73: it is probably best to use `-g' so that you are not
74: helpless in the face of a problem.
75:
76: 7) Refer to the file $BUILD/etc/TERMS for information on
77: fields you may wish to add to various termcap entries.
78:
79: BUILDING GNU EMACS
80: The steps below are done by the shell script `build-install'.
81:
82: 1) Cd to $BUILD/etc and run `make'.
83: This creates files named `ctags' and `etags' and `loadst'
84: and `make-docfile' and `digest-doc' and `test-distrib'.
85:
86: 2) Cd to $BUILD/src and Run `make'
87: This refers to files in the $BUILD/lisp and $BUILD/etc subdirectories
88: using names ../lisp and ../etc.
89:
90: This creates a file $BUILD/src/xemacs which is the runnable Emacs,
91: assigning it a new version number by incrementing the version
92: stored in $BUILD/lisp/version.el.
93:
94: It also creates a file in $BUILD/etc, whose name is
95: DOC followed by the current Emacs version.
96: This file contains documentation strings for all the
97: functions in Emacs. Each time you run make to make a new xemacs,
98: a new DOC file with a new name is made. You must keep
99: the DOC file for an Emacs version as long as you keep using
100: that Emacs version.
101:
102:
103: INSTALLATION
104: The steps below are done by the shell script `build-install'.
105:
106: 0) mv $BUILD $EMACS if $BUILD and $EMACS are not the same.
107: This moves the main Emacs directory to the name you have told
108: Emacs (via paths.h) it is going to have.
109:
110: 1) Move the file $EMACS/xemacs to /usr/local/bin/emacs,
111: or some other name in users' search paths.
112: `xemacs' has an alternate name $EMACS/src/emacs-EMACSVERSION;
113: you may wish to make a symbolic link
114: named /usr/local/bin/emacs pointing to that alternate name,
115: as an easy way of installing different versions.
116:
117: You can delete $EMACS/src/temacs.
118:
119: 3) Move the programs ctags and etags from $EMACS/etc
120: to /usr/local/bin. These programs are run by users as shell commands.
121:
122: The program $EMACS/etc/loadst is invoked by Emacs when appropriate.
123:
124: The programs $EMACS/etc/make-docfile and $EMACS/etc/test-distrib
125: are not used any more; they were used in building Emacs.
126:
127: $EMACS/etc/digest-doc can be used to convert DOC into a
128: file for users to read. There is no important reason to move it.
129:
130: 4) The files in $EMACS/src subdirectory, except for xemacs,
131: are not used by Emacs once it is built.
132:
133:
134: LOSSAGES
135: Known possible problems building and running GNU Emacs
136:
137: * In the 4.3bsd distribution, you will get some spurious warning messages
138: saying `BSD redefined' or `BSD4_3 redefined' from the C compiler while
139: building Emacs. These are due to a last minute surprise in the 4.3
140: header files which we did not have time to correct for. For now,
141: please disregard the messages.
142:
143: * Watch out for .emacs files and EMACSLOADPATH environment vars
144:
145: These control the actions of Emacs.
146: ~/.emacs is your Emacs init file.
147: EMACSLOADPATH overrides which directories the function
148: "load" will search.
149:
150: If you observe strange problems, check for these and get rid
151: of them, then try again.
152:
153: * Fatal signal in the command temacs -l loadup inc dump
154:
155: This has been known to happen due to insufficient swapping
156: space available on the machine.
157:
158: On 68000's, it has also happened because of bugs in the
159: subroutine `alloca'. Verify that `alloca' works right, even
160: for large blocks (many pages).
161:
162: * test-distrib says that the distribution has been clobbered
163: * or, temacs prints "Command key out of range 0-127"
164: * or, temacs runs and dumps xemacs, but xemacs totally fails to work.
165: * or, temacs gets errors dumping xemacs
166:
167: This can be because the .elc files have been garbled. Do not be
168: fooled by the fact that most of a .elc file is text: these are
169: binary files and can contain all 256 byte values.
170:
171: In particular `shar' cannot be used for transmitting GNU Emacs.
172: It typically truncates "lines". What appear to be "lines" in
173: a binary file can of course be of any length. Even once `shar'
174: itself is made to work correctly, `sh' discards null characters
175: when unpacking the shell archive.
176:
177: I have also seen character \177 changed into \377. I do not know
178: what transfer means caused this problem. Various network
179: file transfer programs are suspected of clobbering the high bit.
180:
181: The only verified ways to transfer GNU Emacs are `tar'
182: and rcp or internet ftp between two Unix systems, or chaosnet
183: cftp using raw mode.
184:
185: If you have a copy of Emacs that has been damaged in its
186: nonprinting characters, you can fix them:
187:
188: 1) Record the names of all the .elc files.
189: 2) Delete all the .elc files.
190: 3) Recompile alloc.c with a value of PURESIZE twice as large.
191: You might as well save the old alloc.o.
192: 4) Remake xemacs. It should work now.
193: 5) Running xemacs, do Meta-x byte-compile-file repeatedly
194: to recreate all the .elc files that used to exist.
195: 6) Reinstall the old alloc.o (undoing changes to alloc.c if any)
196: and remake temacs.
197: 7) Remake xemacs. It should work now, with valid .elc files.
198:
199: * temacs prints "Pure Lisp storage exhausted"
200:
201: This means that the Lisp code loaded from the .elc and .el
202: files during temacs -l loadup inc dump took up more
203: space than was allocated.
204:
205: This could be caused by
206: 1) adding code to the preloaded Lisp files
207: 2) adding more preloaded files in loadup.el
208: 3) having a site-init.el which loads files.
209: Note that ANY site-init.el is nonstandard;
210: if you have received Emacs from some other site
211: and it contains a site-init.el file, consider
212: deleting that file.
213: 4) getting the wrong .el or .elc files
214: (not from the directory you expected).
215: 5) deleting some .elc files that are supposed to exist.
216: This would cause the source files (.el files) to be
217: loaded instead. They take up more room, so you lose.
218:
219: * Changes made to .el files do not take effect.
220:
221: You may have forgotten to recompile them into .elc files.
222: Then the old .elc files will be loaded, and your changes
223: will not be seen. To fix this, do M-x byte-recompile-directory
224: and specify the directory that contains the Lisp files.
225:
226: * The dumped Emacs (xemacs) crashes when run, trying to write pure data.
227:
228: Two causes have been seen for such problems.
229:
230: 1) On a system where getpagesize is not a system call, it is defined
231: as a macro. If the definition (in both unexec.c and malloc.c) is wrong,
232: it can cause problems like this. You might be able to find the correct
233: value in the man page for a.out (5).
234:
235: 2) Some systems allocate variables declared static among the
236: initialized variables. Emacs makes all initialized variables in most
237: of its files pure after dumping, but the variables declared static and
238: not initialized are not supposed to be pure. On these systems you
239: may need to add "#define static" to the m- or the s- file.
240:
241: * rmail gets error getting new mail
242:
243: rmail gets new mail from /usr/spool/mail/$USER using a program
244: called movemail. This program interlocks with /bin/mail using
245: the protocol defined by /bin/mail, which involves creating a
246: lock file. It must be able to write in /usr/spool/mail
247: in order to do this.
248:
249: You may have to change config.h to #define MAIL_USE_FLOCK
250: if your system is configured to use flock to interlock
251: access to mail files.
252:
253: * Emacs spontaneously displays "I-search: " at the bottom of the screen.
254:
255: This means that Control-S/Control-Q "flow control" is being used.
256: C-s/C-q flow control is bad for Emacs editors because it takes away
257: C-s and C-q as user commands. Since editors do not output long streams
258: of text without user commands, there is no need for a user-issuable
259: "stop output" command in an editor; therefore, a properly designed
260: flow control mechanism would transmit all possible input characters
261: without interference. Designing such a mechanism is easy, for a person
262: with at least half a brain.
263:
264: There are three possible reasons why flow control could be taking place:
265:
266: 1) Terminal has not been told to disable flow control
267: 2) Insufficient padding for the terminal in use
268: 3) Some sort of terminal concentrator or line switch is responsible
269:
270: First of all, many terminals have a set-up mode which controls
271: whether they generate flow control characters. This must be
272: set to "no flow control" in order for Emacs to work. Sometimes
273: there is an escape sequence that the computer can send to turn
274: flow control off and on. If so, perhaps the termcap `ti' string
275: should turn flow control off, and the `te' string should turn it on.
276:
277: Once the terminal has been told "no flow control", you may find it
278: needs more padding. The amount of padding Emacs sends is controlled
279: by the termcap entry for the terminal in use, and by the output baud
280: rate as known by the kernel. The shell command `stty' will print
281: your output baud rate; `stty' with suitable arguments will set it if
282: it is wrong. Setting to a higher speed causes increased padding. If
283: the results are wrong for the correct speed, there is probably a
284: problem in the termcap entry. You must speak to a local Unix wizard
285: to fix this. Perhaps you are just using the wrong terminal type.
286:
287: For terminals that lack a "no flow control" mode, sometimes just
288: giving lots of padding will prevent actual generation of flow control
289: codes. You might as well try it.
290:
291: If you are really unlucky, your terminal is connected to the computer
292: through a concentrator which sends flow control to the computer, or it
293: insists on sending flow control itself no matter how much padding you
294: give it. You are screwed! You should replace the terminal or
295: concentrator with a properly designed one. In the mean time,
296: some drastic measures can make Emacs semi-work.
297:
298: One drastic measure to ignore C-s and C-q, while sending enough
299: padding that the terminal will not really lose any output.
300: Ignoring C-s and C-q can be done by using keyboard-translate-table
301: to map them into an undefined character such as C-^ or C-\. Sending
302: lots of padding is done by changing the termcap entry.
303:
304: An even more drastic measure is to make Emacs understand flow control.
305: Do (set-input-mode nil t). Emacs will then interpret C-s and C-q as
306: flow control commands. You will lose the ability to use them for
307: Emacs commands. Also, as a consequence of using CBREAK mode, the
308: terminal's Meta-key, if any, will not work, and C-g will be liable to
309: cause a loss of output which will produce garbage on the screen. You
310: can use keyboard-translate-table to map two other input characters
311: (such as C-^ and C-\) into C-s and C-q, so that you can still search
312: and quote.
313:
314: I have no intention of ever redisigning the Emacs command set for
315: the assumption that terminals use C-s/C-q flow control. This
316: flow control technique is a bad design, and terminals that need
317: it are bad merchandise and should not be purchased. If you can
318: get some use out of GNU Emacs on inferior terminals, I am glad,
319: but I will not make Emacs worse for properly designed systems
320: for the sake of inferior systems.
321:
322: * Control-S and Control-Q commands are ignored completely.
323:
324: For some reason, your system is using brain-damaged ^S/^Q flow
325: control despite Emacs's attempts to turn it off. Perhaps your
326: terminal is connected to the computer through a concentrator
327: that wants to use flow control.
328:
329: You should first try to tell the concentrator not to use flow control.
330: If you succeed in this, try making the terminal work without
331: flow control, as described in the preceding section.
332:
333: If that line of approach is not successful, map some other characters
334: into C-s and C-q using keyboard-translate-table. I suggest C-^ and
335: C-\.
336:
337: * Screen is updated wrong, but only on one kind of terminal.
338:
339: This could mean that the termcap entry you are using for that
340: terminal is wrong, or it could mean that Emacs has a bug handing
341: the combination of features specified for that terminal.
342:
343: The first step in tracking this down is to record what characters
344: Emacs is sending to the terminal. Execute the Lisp expression
345: (open-termscript "./emacs-script") to make Emacs write all
346: terminal output into the file ~/emacs-script as well; then do
347: what makes the screen update wrong, and look at the file
348: and decode the characters using the manual for the terminal.
349: There are several possibilities:
350:
351: 1) The characters sent are correct, according to the terminal manual.
352:
353: In this case, there is no obvious bug in Emacs, and most likely you
354: need more padding, or possibly the terminal manual is wrong.
355:
356: 2) The characters sent are incorrect, due to an obscure aspect
357: of the terminal behavior not described in an obvious way
358: by termcap.
359:
360: This case is hard. It will be necessary to think of a way for
361: Emacs to distinguish between terminals with this kind of behavior
362: and other terminals that behave subtly differently but are
363: classified the same by termcap; or else find an algorithm for
364: Emacs to use that avoids the difference. Such changes must be
365: tested on many kinds of terminals.
366:
367: 3) The termcap entry is wrong.
368:
369: See the file TERMS in this directory for information on changes
370: that are known to be needed in commonly used termcap entries
371: for certain terminals.
372:
373: 4) The characters sent are incorrect, and clearly cannot be
374: right for any terminal with the termcap entry you were using.
375:
376: This is unambiguously an Emacs bug, and can probably be fixed
377: in termcap.c, tparam.c, term.c, scroll.c, cm.c or dispnew.c.
378:
379: * Output from Control-V is slow.
380:
381: On many bit-map terminals, scrolling operations are fairly slow.
382: Often the termcap entry for the type of terminal in use fails
383: to inform Emacs of this. The two lines at the bottom of the screen
384: before a Control-V command are supposed to appear at the top after
385: the Control-V command. If Emacs thinks scrolling the lines is fast,
386: it will scroll them to the top of the screen.
387:
388: If scrolling is slow but Emacs thinks it is fast, the usual reason is
389: that the termcap entry for the terminal you are using does not
390: specify any padding time for the `al' and `dl' strings. Emacs
391: concludes that these operations take only as much time as it takes to
392: send the commands at whatever line speed you are using. You must
393: fix the termcap entry to specify, for the `al' and `dl', as much
394: time as the operations really take.
395:
396: Currently Emacs thinks in terms of serial lines which send characters
397: at a fixed rate, so that any operation which takes time for the
398: terminal to execute must also be padded. With bit-map terminals
399: operated across networks, often the network provides some sort of
400: flow control so that padding is never needed no matter how slow
401: an operation is. You must still specify a padding time if you want
402: Emacs to realize that the operation takes a long time. This will
403: cause padding characters to be sent unnecessarily, but they do
404: not really cost much. They will be transmitted while the scrolling
405: is happening and then discarded quickly by the terminal.
406:
407: Most bit-map terminals provide commands for inserting or deleting
408: multiple lines at once. Define the `AL' and `DL' strings in the
409: termcap entry to say how to do these things, and you will have
410: fast output without wasted padding characters. These strings should
411: each contain a single %-spec saying how to send the number of lines
412: to be scrolled. These %-specs are like those in the termcap
413: `cm' string.
414:
415: You should also define the `IC' and `DC' strings if your terminal
416: has a command to insert or delete multiple characters. These
417: take the number of positions to insert or delete as an argument.
418:
419: A `cs' string to set the scrolling region will reduce the amount
420: of motion you see on the screen when part of the screen is scrolled.
421:
422: * You type Control-H (Backspace) expecting to delete characters.
423:
424: Put `stty dec' in your .login file and your problems will disappear
425: after a day or two.
426:
427: The choice of Backspace for erasure was based on confusion, caused by
428: the fact that backspacing causes erasure (later, when you type another
429: character) on most display terminals. But it is a mistake. Deletion
430: of text is not the same thing as backspacing followed by failure to
431: overprint. I do not wish to propagate this confusion by conforming
432: to it.
433:
434: For this reason, I believe `stty dec' is the right mode to use,
435: and I have designed Emacs to go with that. If there were a thousand
436: other control characters, I would define Control-h to delete as well;
437: but there are not very many other control characters, and I think
438: that providing the most mnemonic possible Help character is more
439: important than adapting to people who don't use `stty dec'.
440:
441: If you are obstinate about confusing buggy overprinting with deletion,
442: you can redefine Backspace in your .emacs file:
443: (global-set-key "\b" 'delete-backward-char)
444: You may then wish to put the function help-command on some
445: other key. I leave to you the task of deciding which key.
446:
447: * ld complains because `alloca' is not defined on your system.
448:
449: Alloca is a library function in 4.2bsd, which is used very heavily by
450: GNU Emacs. Use of malloc instead is very difficult, as you would have
451: to arrange for the storage to be freed, and do so even in the case of
452: a longjmp happening inside a subroutine. Many subroutines in Emacs
453: can do longjmp.
454:
455: If your system does not support alloca, try defining the symbol
456: C_ALLOCA in the m-...h file for that machine. This will enable the use
457: in Emacs of a portable simulation for alloca. But you will find that
458: Emacs's performance and memory use improve if you write a true
459: alloca in assembler language.
460:
461: alloca (N) should return the address of an N-byte block of memory
462: added dynamically to the current stack frame.
463:
464: * Vax C compiler bugs affecting Emacs.
465:
466: You may get one of these problems compiling Emacs:
467:
468: foo.c line nnn: compiler error: no table entry for op STASG
469: foo.c: fatal error in /lib/ccom
470:
471: These are due to bugs in the C compiler; the code is valid C.
472: Unfortunately, the bugs are unpredictable: the same construct
473: may compile properly or trigger one of these bugs, depending
474: on what else is in the source file being compiled. Even changes
475: in header files that should not affect the file being compiled
476: can affect whether the bug happens. In addition, sometimes files
477: that compile correctly on one machine get this bug on another machine.
478:
479: As a result, it is hard for me to make sure this bug will not affect
480: you. I have attempted to find and alter these constructs, but more
481: can always appear. However, I can tell you how to deal with it if it
482: should happen. The bug comes from having an indexed reference to an
483: array of Lisp_Objects, as an argument in a function call:
484: Lisp_Object *args;
485: ...
486: ... foo (5, args[i], ...)...
487: putting the argument into a temporary variable first, as in
488: Lisp_Object *args;
489: Lisp_Object tem;
490: ...
491: tem = args[i];
492: ... foo (r, tem, ...)...
493: causes the problem to go away.
494: The `contents' field of a Lisp vector is an array of Lisp_Objects,
495: so you may see the problem happening with indexed references to that.
496:
497: * 68000 C compiler problems
498:
499: Various 68000 compilers have different problems.
500: These are some that have been observed.
501:
502: ** Using value of assignment expression on union type loses.
503: This means that x = y = z; or foo (x = z); does not work
504: if x is of type Lisp_Object.
505:
506: ** "cannot reclaim" error.
507:
508: This means that an expression is too complicated. You get the correct
509: line number in the error message. The code must be rewritten with
510: simpler expressions.
511:
512: ** XCONS, XSTRING, etc macros produce incorrect code.
513:
514: If temacs fails to run at all, this may be the cause.
515: Compile this test program and look at the assembler code:
516:
517: struct foo { char x; unsigned int y : 24; };
518:
519: lose (arg)
520: struct foo arg;
521: {
522: test ((int *) arg.y);
523: }
524:
525: If the code is incorrect, your compiler has this problem.
526: In the XCONS, etc., macros in lisp.h you must replace (a).u.val with
527: ((a).u.val + coercedummy) where coercedummy is declared as int.
528:
529: This problem will not happen if the m-...h file for your type
530: of machine defines NO_UNION_TYPE. That is the recommended setting now.
531:
532: * C compilers lose on returning unions
533:
534: I hear that some C compilers cannot handle returning
535: a union type. Most of the functions in GNU Emacs return
536: type Lisp_Object, which is currently defined as a union.
537:
538: This problem will not happen if the m-...h file for your type
539: of machine defines NO_UNION_TYPE. That is the recommended setting now.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.