Emacs on Aqua Version 8.0.2 **************************** Adrian Robert , October 2005 This is a port of GNU Emacs 20.7 (http://ftp.gnu.org/pub/gnu/emacs/) based on the earlier Rhapsody, OpenStep, and NeXTstep versions. It runs on GNUstep and MacOS X. Those primarily responsible for the port (in chronological order) were: Carl Edman Michael Brouwer Christian Limpach Scott Bender Christophe de Dinechin GNU Emacs is due to Richard Stallman and company. The GNUstep port was made possible through the assistance of Adam Fedor, Fred Kiefer, M. Uli Klusterer, Alexander Malmberg, and Jonas Matton. Riccardo Mottola helped with compatibility with MacOS versions 10.1 and 10.2, and GNUstep on platforms other than Linux. (PLEASE SEE "USAGE NOTES" BELOW FOR TIPS ON USING EMACS ON AQUA.) Status ====== It is very stable on OS X Panther, largely stable on OS X Tiger (usually OK for hours / tens of buffers), and stable on some GNUstep installations. It should work on Jaguar and Panther but testing is not very extensive there, and you may need to recompile yourself. If you experience a problem on MacOS, please make sure you are running the latest release of your version (run software update) before reporting any bugs. Requirements ============ MacOS X 10.1-10.4 (see notes above) - or - GNUstep "Startup" 0.12 or later; ART back-end recommended (needs 0.13 or later if freetype is 2.1.8 or later) Linux, NetBSD, and FreeBSD have all been reported to work. Binary Releases =============== Mac OS X: A disk image is available from the download site. GNUstep/Linux: Debian: http://gnu.ethz.ch/debian/emacs/ Others: Compilation from source is required for now. The binary packages include this README plus the application (".app"). Copy this to an applications directory on your hard drive. After starting up the program, choose "Info about Emacs for *Step" from the Help menu (OS X) or Info menu (GNUstep). Also, read the section "Usage Notes" below. Source Release ============== Download tar.bz2 from download site. Unpack with "tar jxf emacs-20.7_ns-8.0.tar.bz2". (.bz2 is bzip2 highly compressed format.) Quick Installation from Source ============================== 1) Change to Aqua subdirectory (MacOS X) or GNUstep subdirectory (GNUstep). 2) Run ./compile there. 3) Copy build/Emacs.app into an apps directory such as /Applications. Step 2 runs configure and make. After completes you can run build/Emacs.app. (You can also do development after step 2 -- see below.) The installation will also link in /usr/local/share/emacs/site-lisp to the application. If you prefer something other than this (e.g, /usr/share/emacs/site-lisp), you will need to change this manually. See "Usage Notes" below for more information. Manual Installation from Source =============================== If something goes wrong above or you want to do the steps manually for customization or development purposes, do the following. First, run the "compile" script (see above) once. Then look at config.log in the top-level emacs directory, and decide if you want to change the arguments. You can rerun configure and run 'make' manually in this directory or in the 'src' subdirectory to refresh {Aqua|GNUstep}/build/Emacs.app. (Or edit the "compile" script.) On OS X you can also open Aqua/Emacs.pbproj (make sure this uses Xcode on 10.3+) and build it again there. Note, ZeroLink currently does not work with Emacs owing to the use of private_extern in the code as well as some other, unidentifiable problem. ProjectBuilder on 10.2 and 10.1 should work, though you might get complaints at startup. In any case, you cannot build a working binary only using Xcode/PB -- you must run the compile script at least once beforehand to set up the lisp resources. On GNUstep, you CAN'T use ProjectCenter, since PC cannot work with files outside of its project directory. Usage Notes =========== Preferences Panel ----------------- Most of the settings described below may be accessed through the Preferences panel, under the 'Emacs' menu or Cmd-, as for other OS X applications. Note, the Preferences panel has a couple of known issues: 1) After pushing the 'Default Font' button, you must click on an Emacs frame before selecting a font. 2) After pushing the help ('?') button, you must click on an Emacs frame and drag the cursor or hit a key to show the help. Also, for cases where you set things _without_ using the Preferences panel (such as popping up the Font or Color panels independently), you must explicitly choose 'Save Preferences' from the Help menu to save the settings. Fonts ----- Font can be set using the Font Panel (accessible through Preferences or by Cmd-t or under Windows menu). After you find a font you like, select "Save Preferences" from the Help menu (OS X), or Info menu (GNUstep). This saves a number of miscellaneous display parameters relating to fonts, colors, and window sizes. Fixed width fonts should be used, though some variable-width fonts will work on GNUstep and OS X Panther+. Fonts that look good on OS X include Monaco, Courier, Osaka Regular-Mono (come with OS X), Anonymous, Excalibur Monospace, and ProFont (get from web or Emacs on Aqua download site). Note, on OS X Jaguar and earlier, some fonts at some sizes will be misaligned vertically. This is a known issue. In any case, if things look non-optimal, use Cmd-t, select a different font, and possibly Save Preferences and restart. ProFont: http://www.tobiasjung.net/profont/ http://www.tobiasjung.net/download.php?file=ProFont-Distribution-2.2.sit http://www.tobiasjung.net/download.php?file=MProFont.zip Anonymous: http://www.ms-studio.com/FontSales/anonymous.html http://www.ms-studio.com/FontSales/Resources/AnonymousTT.sit.hqx Excalibur monospace: http://www.a1fonts.com/download.htm?id=5242 Chica mono: http://www.a1fonts.com/download.htm?id=4383 Proggy: http://www.proggyfonts.com/index.php?menu=download Rendering of non-Latin text should work provided the font supports it. Emacs supports the concept of "fontsets" which automatically select the correct font for rendering each character, however this is not working yet in Emacs.app. You must select a suitable font for the language being edited manually. Antialiasing can be turned off on OS X Panther and above or GNUstep by defaults write Emacs GSFontAntiAlias NO Also on Panther+, Quickdraw-based font smoothing (less heavy antialiasing) can be selected with defaults write Emacs UseQuickdrawSmoothing YES Restarts are needed for these to take effect. Internationalized Text ---------------------- Rendering of non-ASCII characters, including Latin and CJK, is supported, however there are some shortcomings: no fontset support (must manually set appropriate font for frame) and no composition (Korean, Thai, Lao, etc.). LEIM (Library of Emacs Input Methods) is included and seems to work in limited testing, but YMMV. Note, on GNUstep, rendering of non-Latin Text is currently only working under the Art back-end. Colors ------ Colors can be customized using the color panel. Pull it up from the Preferences panel, or hit Shift-Cmd-C or choose it from the Windows menu, then choose colors and drag them to the active frame. Drag to a face to change that face's foreground color, or drag to a blank area to change the color of default (non-face) text. Hold down shift when dragging to change background colors. Drag onto the cursor to change the cursor's foreground color only. Choose Save Preferences from the Help menu to save for future sessions. Transparency ------------ The Color panel does not let you set transparency. To get a transparent window, use M-x set-background-color, and enter a color of the form ARGBAARRGGBB, where 'AA' is the alpha value in hex (00 for completely transparent, FF for completely opaque), and RRGGBB is the hex color value. For example, ARGBDDFFFFFF Cursor ------ Cursor drawing works differently than in Emacs under X -- the character beneath the cursor is not reverse-video'd. This is in order to support additional cursor types under *Step, but it means some color combinations you are accustomed to may not work. Mouse ----- Wheel mouse support is included in ns-startup.el (in Resources/share/emacs/20.7/site-lisp, loaded on startup). If something doesn't work, take a look at this file, figure out what you need to change, and let me know. Keys ---- "Alt" or "Opt" should be acting as Emacs "meta", while "Cmd" should be acting as itself. Try setting the 'AlternateIsMeta' default (accessible through the Preferences panel) if something is amiss, such as you need alt/opt for text input. Most standard OS X / GNUstep command keys are active. Note that panels for loading/saving files are used if you use these keys instead of the standard emacs versions. E.g., Ctrl-x,Ctrl-s will let you type in a file name, while Cmd-o (or using the menu) will pop up a panel. Clipboard --------- On GNUstep, you can transfer text to/from the primary X selection (instead of the clipboard) using Cmd-c and Cmd-y (instead of Meta-w and Ctrl-y). Cmd-c actually copies text to both primary and clipboard selection. Path ---- On OS X, if you start Emacs by clicking the icon, the executable path is not propagated to emacs. This can cause packages that depend on external binaries, such as SQL interfaces and email clients, to fail to find them. The solution is to place a special "plist" file at ~/.MacOSX/environment.plist. Emacs.app includes a utility to create such a file. Run it from the Terminal: /Applications/Emacs.app/Contents/MacOSX/bin/mac-fix-env (Replace "/Applications" with wherever you installed Emacs.) This puts your current path in that shell into the env file. You must log out and log back in to your OS X session for this to take effect. Lisp Packages ------------- A couple of useful lisp packages are bundled in the version-specific site-lisp directory (Emacs.app/Resources/share/emacs/20.7/site-lisp). These are activated by ns-startup.el, also in that directory. Edit that file to comment out anything you don't want. Currently included: - tramp 2.1 (last version to work with emacs-20) - objc-mode (better than built-in) - mic-paren (more sophisticated paren highlighting) It is recommended you customize tramp to suit your needs: M-x customize-group tramp To turn off highlighting of contents between parentheses, use M-x customize-group mic-paren-matching Note, if you use the same .emacs file with emacs-21, you'll find the following construct useful: (if (eq emacs-major-version '20) ((lambda () ; emacs 20 specific stuff )) ((lambda () ; emacs 21 specific stuff )) ) See the info file accessible through the command 'info-ns-emacs' (or the Help/Info menu), for more information. Troubleshooting =============== On GNUstep, if your ./configure run does not result in a mention of "Doug Lea malloc", you may have problems. This is the libc built-in version and the only one successfully tested. (The others might be interfering with something in GNUstep's mem allocation infrastructure.) If the emacs you build crashes on startup or shortly thereafter, try adjusting this. If 'info-ns-emacs' doesn't work, the problem is either Emacs is pointed to somewhere other than your system info directory, or the info file did not get installed. Emacs should be looking in .../Emacs.app/Contents/Resources/info. For other issues, please check "Known Current Problems" below before reporting a bug. Release History =============== 2004/10/7 8.0-pre1 Initial support for GNUstep. 2004/11/4 8.0-pre2 Restored functionality on OS X (menu code cleanup). Improved scrollbar handling and paste from other applications. File icons obtained properly from NSWorkspace. Dropped Gorm and Nib files. Background refresh bug fixed (in GNUstep). Various small fixes and code cleanups. Now starts up under Art. 2005/01/27 8.0-pre3 Bold and italic faces supported. Cursor and mouse highlighting rendering bugs fixed. Drag/drop and cut/paste interaction w/external apps fixed. File load/save panels available. Stability and rendering speed improvements. Some ObjC and VC mode bugs fixed. 2005/02/27 8.0-rc1 Dynamic path detection at startup so Emacs.app can be moved anywhere. Added binary packages and simplified source installation to running two scripts. Thorough cleanup of menu code; now fully functional. Fixed all detected memory leaks. Minor frame focus and title bugs fixed. 2005/03/30 8.0-rc2 "Configure" info directory now uses dynamic path setting, so info files can go under .app. Improved select() handling and PTY fixes so shell mode and tramp run smoothly. Significant rendering optimizations under GNUstep, and now works under Art backend. Non-Latin text rendering works (but not fontsets), and LEIM is bundled. UTF8 is used for clipboard interaction. Arrow cursor now used on scrollbar. objc-mode and tramp now bundled in site-lisp. 2005/05/30 8.0-rc3 Fixed bug with parsing of "easymenu" menus. Many problems with modes such as SLIME, MatLab, and Planner go away. Improved scrollbar handling and rendering speed. Color panel and other bug fixes. mac-fix-env utility. Font handling improvements (OS X 10.3, 10.4): - heed 'GSFontAntiAlias' default - heed system antialiasing threshold - added 'UseQuickdrawSmoothing' default to invoke less heavy antialiasing 2005/07/05 8.0-rc4 Added a Preferences panel. Cleaned up rendering for synthetic italic fonts. Further improved menu parsing. Use system highlight color. Added previous- and next-mark history navigation commmands bound to M-p,M-n. Miscellaneous bug fixes. 2005/08/04 8.0-rc5 All internal string handling changed to UTF-8. This means menu items, color and color list names, and a few other things will now display properly. It does NOT mean UTF-8 filenames are displayed correctly in the minibuffer. Also relating to UTF-8, contents of files using this coding can now be displayed (though not auto-recognized; add extensions to your default coding alist). Limited mac-roman support was also added (also sans recognition). Certain characters are not displayed properly due to a translation problem. (UTF-8 based on work by Otfried Cheong; mac-roman from emacs-21.) Partial support for "dead-key" handling now added. Transparency (e.g., M-x set-background-color ARGB88FFFFFF) improved: only the background is made transparent. Cursor drawing glitches fixed. Preferences handling improved. Fixed some portability problems on Tiger and Puma. 2005/09/12 8.0 Bundled ispell on OS X. Minor bug fixes and stability improvements. Compiles under gcc-4. 2005/09/26 8.0.1 Correct clipped rendering for synthetic italics. Include the info directory. Fix grabenv. Bundle whitespace package. 2005/11/05 8.0.2 Correct rendering for wide characters during cursor movement. Fix bungled hack in ispell bundling. Window size now displayed on resizes under OS X. Known issues (won't fix): ======================== 1) Mode-specific: Ediff control window displayed incorrectly on GNUstep and causes crashes on GNUstep and OS X. Work-around: ediff is set by default to not put up a separate control frame. Make sure this does not get overridden in your .emacs by a setting to ediff-setup-windows-multiframe. 2) Rendering: Sometimes a character gets chopped off when scrolling, or weird color effects happen when typing. Scrolling in horizontally- then vertically-split windows (C-x,3 C-x,2) in some cases overwrites scrollbars (problem is ns_ins_del_lines() is being called improperly by redisplay engine; need to work around). 3) Non-latin text: no fontset support, and some keyboards and/or dead keys not handled properly. Mac-roman support is partial. Rendering doesn't work under GNUstep/xlib. 4) Menus: Second-level easymenu submenus not pulled out as tearoffs, nor do their entries work. Some menus seem to need an extra request to update in lisp after a buffer switch. In particular, imenu Index and Buffers are at fault. Also, menu item enabled state not updated. (If invoking a menu item just beeps, scroll the buffer and try again.) 5) Startup on OS X: open file by open -a Emacs.app or double-click in Finder) fails. 5) Exec-image dumping not working (loads all lisp from scratch at startup). Dumping is disabled on purpose because I could not get it working early on. It is possible it could work now under Linux, but the difference in startup speed does not seem worth it. (Loading libs from typical .emacs takes more time.) Under OS X, there are problems in connection with the Carbon code underlying the menu implementation, though apparently these were solved in emacs-21. (WON'T FIX.) Developer Notes (*Step Version of Emacs) ======================================== The diff relative to the stock emacs-20.7 contains small modifications to a number of files, but the main implementation is in the files beginning with 'ns' under src and lisp. The main C file is "nsterm.m" and the main lisp file is "term/ns-win.el". These are both modeled after the 'x' versions for X11. "nsfns.m" contains most of the lisp function implementations, and also parallels the x version. More information is available through 'M-x info-ns-emacs', or looking at the file "man/ns-emacs.texi" in the source. The way things work generally is that generic code in lisp and in some C files like keyboard.c, xdisp.c, and dispnew.c run the main event loop and view/controller logic, then make calls out to the nsxxx.m files to do final rendering and/or event registration. In nsterm.m, [NSApplication -run] (actually [EmacsApp -run] is repeatedly called and then halted when an NSApplicationDefined event is received, so that emacs's own event loop (the main one) can continue. Menus are constructed in lisp (see lisp/ns-menu-bar.el) and then translated to NS menus in nsmenu.m, from the call to set_frame_menubar(). Their invocation causes a lisp mouse event which ends up being converted into a _key_ event which gets passed by keyboard.c back to the lisp. Welcome to emacs. The services menu is actually set up in nsfns.m, not nsmenu.m (interpret_services_menu()). See the comments in nsfns for more info. Patches are very welcome. Please send to arobert at cogsci.ucsd.edu. Developer Notes (GNU Emacs in general) ====================================== Some people have been asking about a quickstart reference for understanding the structure of the emacs code. I haven't found such a beast myself, and given what I know of the nature of the Emacs developer community it might not exist. So I'm trying to collect some notes here both for this purpose and to aid me in my forgetfulness.. See the file "src/FILE_DESC.txt" to get an overview of the C files. However, it might help to read the below before looking that over. Emacs contains some C code (in src/), a Lisp interpreter (written in C, also in src/), and some Lisp code (in lisp/). In fact there is much more Lisp than C, and the general approach is to do as much as possible in Lisp, which is easier to write, test, and debug. The C is mainly responsible for the low-level graphics layer, the OS interface, the Lisp interpreter, and any speed-critical tasks. Although the main event loop is run in C, the Lisp side of the code is essentially "in charge", handling primary functionality and calling out to C subroutines where needed. These subroutines make up most of the contents of files named "---fns.c", where "fns" means "functions", but they also occur elsewhere. C routines are made accessible from Lisp by declaring them using a special macro ("DEFUN") defined in 'lisp.h'. Data structures in lisp are allocated by lisp_malloc in alloc.c. These are stored not as pointers, but as integers in which some of the high bits are used to mark the structure type and other info. This leads to a problem which never became relevant until recently: the high bits of the address are discarded, so if they were non-zero (i.e., the memory was allocated from an upper portion of the machine address space), the actual address is lost. VALIDATE_LISP_STORAGE is called to check that this doesn't happen. Usually everything is fine, but unfortunately most memory debugging tools, such as electric fence, valgrind, dmalloc, etc. tend to allocate memory that is out of this range, and hence can't be used to debug emacs. (You get a segfault actually, because VALIDATE_LISP_STORAGE is not always called when it should be, a bug fixed only in emacs-21). The other unusual aspect of the Emacs code is the "terminal" infrastructure -- the code is structured to share as much code as possible between Emacs running in a text terminal, in an X window, in Microsoft Windows, and on NeXTstep. Each windowing system, including NeXTstep, is made up of several files on the C side: ---faces.c Face attribute display (syntax-specific coloring, fonts, etc.). ---fns.c Lisp interface. ---menu.c Menu-related functionality. ---select.c Text selection-related functionality. ---term.c Main heavy-lifting UI code. Some UIs have additional files. On the Lisp side, each window system UI has a main file in lisp/term that more or less corresponds to the ---term.c file on the C side. This file is called xxx-win.el. Other Lisp files for a UI are prefixed with the same prefix this one is, e.g., other NeXTstep-specific files besides "ns-win.el" include "ns-menu-bar.el", "ns-syntax.el", etc.. Developer Notes (Emacs 21 Prospects) ==================================== Investigations revealed at least two main points of change from Emacs-20 to Emacs-21: the redisplay code and the face implementation (supporting variable-size glyphs in version 21). Furthermore support for displaying images in buffers was implemented, together with displaying certain types of backgrounds to text. None of this represents a fundamental problem for the OpenStep APIs, but it will take a fair amount of work.