1# Joe's Own Editor Installation Instructions 2 3## Typical Installation 4 5 ./configure --prefix=/usr --sysconfdir=/etc 6 7 - executables in /usr/bin 8 - man pages in /usr/man 9 - configuration files in /etc/joe 10 - syntax files in /usr/share/joe 11 12 make 13 14 sudo make install 15 16For OS X, use: 17 18 sudo LC_ALL=C make install 19 20(This fixes an issue where sed on OS X is unhappy with binary files and will 21be fixed in the next release of JOE. If you tried 'make' without the 22LC_ALL=C, you may have to delete the source distribution directory and start 23over). 24 25You may have to delete or update user custom configuration files (otherwise 26new features will not work): 27 28 rm ~/.joerc 29 rm ~/.jmacsrc 30 rm ~/.rjoerc 31 rm ~/.jstarrc 32 rm ~/.jpicorc 33 34## Mercurial 35 36### Developer checkout 37 38 hg clone ssh://jhallen@hg.code.sf.net/p/joe-editor/mercurial joe-editor-mercurial 39 40### Read-only checkout 41 42 hg clone http://hg.code.sf.net/p/joe-editor/mercurial joe-editor-mercurial 43 44### Update to the branch you want to build 45 46 hg update -C default Not yet released main-line branch 47 48 hg update -C joe-3 Released branch for joe-3.x 49 50### Run autotools to build configure scripts 51 52 ./autojoe 53 54 (You might find that you need to install automake and autoconf 55 first). 56 57## Installation procedure 58 59To create a Cygwin binary distribution, use the 'cygbuild' script 60instead of these instructions. 61 62JOE uses the GNU Automake and Autoconf suites to build itself. 63 64Usually you want JOE to use the terminfo database. JOE needs 65a termcap emulation library to do this. In modern versions of 66UNIX, this library is part of ncurses so you need the ncurses 67library: 68 69 apt-get install ncurses-dev 70 71Run configure script, type one of these: 72 73 Normal installation: 74 75 ./configure --prefix=/usr --sysconfdir=/etc 76 77 - executables in /usr/bin 78 - man pages in /usr/man 79 - configuration files in /etc/joe 80 - syntax files in /usr/share/joe 81 82 Install into your home directory: 83 84 ./configure --prefix=$HOME 85 86 - executables in ~/bin 87 - man pages in ~/man 88 - configuration files in ~/etc/joe 89 - syntax files in ~/share/joe 90 91 Install into /usr/local: 92 93 ./configure 94 95 - executables in /usr/local/bin 96 - man pages in /usr/local/man 97 - configuration files in /usr/local/etc/joe 98 - syntax files in /usr/local/share/joe 99 100For Cygwin, I've found that you need to add 101 "--disable-curses --disable-termcap" to the above commands. 102 103Build JOE, type: 104 105 make 106 107Optionally strip JOE of debugging information: 108 109 strip joe 110 111Install JOE, type one of: 112 113 sudo make install (system installation) 114 115 make install (home directory) 116 117Delete or update user custom configuration files (otherwise new features 118will not work): 119 120 rm ~/.joerc 121 rm ~/.jmacsrc 122 rm ~/.rjoerc 123 rm ~/.jstarrc 124 rm ~/.jpicorc 125 rm -r ~/.joe 126 127Try running JOE: 128 129 joe 130 131Note: please install xterm version 212 or higher, and use these 132xterm 'configure' options: 133 134 --enable-256-color 135 136 --enable-paste64 137 138'--enable-paste64' allows you to use JOE's '-joexterm' option (see JOERC 139file), which allows mouse left and middle button cut & paste to work with 140properly with JOE. 141 142## Common ./configure options 143 144 To force JOE to use /etc/termcap file using its built-in termcap file parser 145 (which is useful if you want to compile JOE so that it doesn't depend on any 146 libraries other than libc and libm): 147 148 ./configure --disable-curses --disable-termcap 149 150 (--disable-termcap prevents JOE from using the termcap emulation functions 151 in the -ltermcap library. --disable-curses prevents JOE from using the 152 termcap emulation functions in the -lcurses library). 153 154 Otherwise, JOE tries to use the terminfo database via termcap 155 emulation routines: see man tgetent, tgetstr, tgoto, etc. (JOE has its 156 own implementation of "curses", so curses is not required except to get 157 access to the terminfo database). 158 159 Note that even if you don't have an /etc/termcap file, JOE will run: it 160 will assume that the terminal is "ANSI" (but you need to compile it this 161 way for it to be able to use the builtin ANSI termcap entry- if it's 162 compiled for terminfo, it can not use its built-in termcap entry). 163 164 Note for MIPS/SGI: to get a 64-bit JOE, do this: 165 CC=cc CFLAGS=-64 ./configure ... 166 167## Maximize warnings 168 169Developers may want to try to maximize compiler warnings from gcc: 170 171One way is to provide the CFLAGS enviroment variable to configure: 172 173 CFLAGS='-g -Wall -Wconversion -Wunused -Wwrite-strings -Wstrict-overflow=4 -Wmissing-include-dirs -Winit-self -Wundef -Wlogical-op -Wmissing-declarations -Wformat -Wmissing-format-attribute -Wformat-nonliteral -Wformat-security -Wswitch-enum -Wshadow' ./configure ... 174 175Another is to edit CFLAGS in the joe/Makefile: 176 177 CFLAGS = -g -Wall -Wconversion -Wunused -Wwrite-strings \ 178 -Wstrict-overflow=4 -Wmissing-include-dirs -Winit-self -Wcast-qual \ 179 -Wundef -Wlogical-op -Wmissing-declarations -Wformat \ 180 -Wmissing-format-attribute -Wformat-nonliteral \ 181 -Wswitch-enum -Wshadow 182 183(Try adding -Wextra and -Wformat-security for even more warnings) 184 185It's a good idea to verify that JOE can be compiled with C++. The C++ 186front-end sometimes finds different problems than the C front-end. 187 188 CC = g++ 189 190It's a good idea to see what warnings occur when -m32 is added. This 191can reveal some conversion warnings. 192 193## Verify the installation 194 195A number of features should be tested: 196 197### Shell windows: 198 199Please test the installation by trying the shell command: ^K ' A shell 200prompt should appear in the window and you should be able to type "ls". If 201not, two things could be broken: 202 203JOE could not open a pseudo terminal (pty), which is unfortunately one of 204the two most incompatible parts of the UNIX API. Take a look at tty.c- 205there are several methods for opening the pty: mess with the "#ifdefs" until 206you find a method which works (and send a bug report for your operating 207system). 208 209The SHELL environment variable is not set or exported (Cygwin has this 210problem). Put: 211 212 export SHELL=/bin/bash 213 setenv SHELL /bin/bash 214 215In you .profile or .cshrc file and send mail to the Cygwin mailing list 216so that they fix this problem. 217 218### Process groups: 219 220Once you have a shell window open, try to suspend JOE: ^K Z. Then resume 221it: "fg". The shell window should still be active. If not, your operating 222system is not handling process groups properly. Look for the setsid() or 223setprgp() system calls in tty.c (this is the other most incompatible part of 224the UNIX API). Currently process groups appear to be broken in Cygwin (so 225if you suspend JOE, any shells get killed). 226 227### Resize windows 228 229Try resizing the terminal emulator window: JOE should resize itself to 230properly fit. If this doesn't work, either ttgtsz() (in tty.c) is not 231reading the size properly, or the SIGWINCH signal is not being received 232by JOE (the handler is winchd() in tty.c). 233 234### Baud rate: 235 236JOE cares about the baud rate as reported by "stty": 237 238 38400 or above: Joe does not issue scrolling commands 239 240 9600 - 19200: Joe issues scrolling commands, but does 241 not delay. 242 243 0 - 4800: Joe defeats output buffering by sleeping 244 after every chunk of data is sent to the 245 screen, by the amount of time that the data 246 should take to get there as determined by 247 the baud rate. This allows typeahead to 248 interrupt the screen update process: If you 249 hit Page Down 100 times, only the final 250 contents of the screen get sent to the 251 terminal, otherwise you have to wait for all 252 100 pages to get to the screen before you 253 can do anything. 254 255Sleeping should really be used at 9600 baud, but too many systems use 9600 256as the default speed for terminal emulators. If you are using a real serial 257link to a real terminal, you may want to adjust these thresholds: search for 258"9600" in tty.c. 259 260### Padding 261 262Ideally either terminals can keep up with the baud rate or they backpressure 263the computer using hardware flow control (RTS and CTS pins on RS-232 264connector). 265 266If not, there are two options, both bad: 267 268Use XON/XOFF (^S/^Q) flow control: this works, but ^S causes the screen to 269freeze, which freaks out new users, plus ^S is the search key in "jmacs". 270 271Use padding: the termcap database indicates how long each command should 272take. If padding is enabled, JOE will send enough NUL characters after each 273command to account for this time. You need set the DOPADDING environment 274variable or use the -dopadding option. 275 276You should just buy a modern terminal :-) 277 278### Usage 279 280USAGE: joe filename [filename ...] 281 282 Optionally precede each filename with +nnn to start at specified line number. 283 284 Options: 285 286 -mid Cursor is recentered when scrolling is necessary 287 -marking Text between ^KB and cursor is highlighted (use with -lightoff) 288 -asis Characters 128 - 255 shown as-is 289 -force Force final newline when files are saved 290 -nobackups If you don't want backup files to be created 291 -lightoff Turn off highlighting after block copy or move 292 -exask ^KX always confirms file name 293 -beep Beep on errors and when cursor goes past extremes 294 -nosta Disable top-most status line 295 -keepup %k and %c status line escape sequences updated frequently 296 -pg nnn No. lines to keep for PgUp/PgDn 297 -csmode ^KF after a previous search does a ^L instead 298 -backpath path Directory to store backup files 299 -nonotice Disable copyright notice 300 -noxon Attempt to turn off ^S/^Q processing 301 -orphan Put extra files given on command line in orphaned buffers 302 instead of in windows 303 -dopadding Output pad characters (for when there is no tty handshaking) 304 -lines nnn Set no. screen lines 305 -baud nnn Set baud rate for terminal optimizations 306 -columns nnn Set no. screen columns 307 -help Start with help on 308 -skiptop nnn Don't use top nnn lines of the screen 309 310 Options before each file name: 311 312 -wordwrap Wordwrap 313 -autoindent Auto indent 314 -overwrite Overtype mode 315 -lmargin nnn Left margin 316 -rmargin nnn Right margin 317 -tab nnn Tab width 318 -indentc nnn Indentation character (32 for space, 9 for tab) 319 -istep nnn Number of indentation columns 320 -french One space after '.', '?' and '!' for wordwrap 321 and paragraph reformat instead of two. Joe 322 does not change the spacing you give, but 323 sometimes it must put spacing in itself. This 324 selects how much is inserted. 325 -spaces TAB inserts spaces instead of tabs. 326 -linums Enable line numbers on each line 327 -rdonly File is read-only 328 -crlf File is uses CR-LF at ends of lines (MS-DOS files) 329 330 These options can also be set in the joerc file. The NOXON, LINES, 331COLUMNS, DOPADDING and BAUD options can also be set with environment 332variables. 333 334 The JOETERM environment variable can be set to override the TERM 335environment variable. 336 337### IMPORTANT 338 339The baud rate must be correctly set or either typeahead will not interrupt 340the screen update and scrolling wont be used or there will be annoying 341delays in the screen update. If you can't set the baud rate correctly with 342'stty', give a numeric value in the environment variable 'BAUD' or to the 343command line options '-baud'. 344 345The baud rate '38400' or 'extb' means infinite to joe. Use it for X windows 346and hardware console ttys. No delays will be generated and scrolling will 347not be used. 348 349The baud rate '19200' or 'exta' means that joe will use scrolling, but will 350not delay. 351 352Use the LINES and COLUMNS environment variables or the -lines and -columns 353command line options if you need the terminal size to be different than 354whatever the termcap entry or stty reports. 355 356Since most people use terminal emulators, JOE does not send out pad 357characters. If you're using a real terminal and the padding matters, set 358the environment variable DOPADDING or give the command line option 359-dopadding. 360 361If you want joe to try to disable ^S/^Q processing, set the environment 362variable NOXON or command line option -noxon. 363 364A termcap file is included with JOE. You might consider updating your own 365termcap file with the entries in it, particularly if you use ANSI/VT100ish 366terminals. JOE understands some capabilities which are not usually supplied 367in normal termcap (see below). 368 369## VARIATIONS 370 371### Termcap/Terminfo 372 373JOE prefers to use the termcap terminal capability database. It 374attempts to find this file in: 375 376 $HOME/.termcap Personal .termcap in your home directory 377 /etc/joe/termcap Joe's termcap file 378 /etc/termcap Normal system termcap file 379 380Joe copies its own termcap file to /usr/local/lib/termcap (or 381wherever the system-wide joerc file is going to go) when 'make install' is 382run. 383 384Termcap is better than terminfo because it is a more open standard. 385Programs can directly access the termcap database and future versions of 386terminfo may require programs to use curses. The only argument in 387terminfo's favor is that it is faster than termcap. To fix this problem, 388JOE will use a termcap index file if it exists and if it is up to date. 389 390This is the procedure to make the termcap index file: 391 392 make termidx 393 ./termidx </etc/termcap >/etc/termcap.idx 394 395The /etc/termcap.idx is a text file which you can look at if you're 396curious. 397 398JOE supports the GNU extensions to the termcap language and also 399understands several new capabilities: 400 401 AL DL IC DC RI LE UP DO SF SR 402 403 Versions of the standard capabilities which accept 404 an argument. For example, RI with and argument of 405 7 should move the cursor 7 positions to the right. 406 407 rr 408 409 Set this flag if the cursor is restricted to move 410 only within the scrolling regions. This is an optional 411 mode on vt220s and several clones assume that this 412 mode is always on. 413 414 cV 415 416 Like the 'cv' capability, but the cursor goes to the 417 beginning of the specified line. Like 'ESC [ n H' in 418 ansi/vt100. 419 420## BROKEN TERMINALS 421 422"Joe does not update the screen correctly in Procomm" 423"My Xenix console does not scroll correctly" 424 425Old versions of Procomm, many other DOS comm programs and nearly every 426PC-UNIX console (with the exception of Linux) does not emulate VT100s 427properly. There are usually one or more problems: 428 429 1) Tabs are destructive 430 431 2) Tabs are destructive when inverse mode is set 432 433 3) Scrolling regions are not supported 434 435 4) Cursor positioning is scrolling region relative instead of 436 screen relative. 437 438 5) Some other program set the tab-stops to something other than 439 one tab stop every 8 columns. 440 441 6) The erase commands (ESC [ J and ESC [ K) fill with inverse 442 video blanks instead of plain blanks when inverse mode is set. 443 444 7) Backspace is destructive 445 446Procomm 2.3 works fine- but make sure you have DEC VT100 selected, not 'ANSI 447BBS' and also that backspace (BS) is set to 'non-destructive'. If you must 448use an old version of Procomm, try using the 'ansisys' or 'nansisys' termcap 449entry. Unix consoles usually do not have scrolling regions, but instead 450have insert and delete line commands. The 'fansi' entry and ones derived 451from it will work correctly. These termcap entries are provided in the 452termcap file which came with joe. If at all possible have your sysadmin 453install these entries in '/etc/termcap'. Even if your system normally uses 454the terminfo database, you can copy Joe's termcap file into 455/etc/termcap. 456 457"I don't have root access and can't update the system's termcap file. How 458 do I get only Joe to use a different termcap entry?" 459 460"My system uses terminfo. How do I get only Joe to use a different termcap 461 entry?" 462 463What you should do is copy the termcap file which is provided with joe into 464'.termcap' of your home directory. Now suppose you want Joe to use the 465'fansi' termcap entry: 466 467If you use csh or tcsh, place this in your .cshrc file: 468 469 setenv JOETERM fansi 470 471If you use sh, ksh or bash, place this in your .profile file: 472 473 JOETERM=fansi; export JOETERM 474 475"I don't have root access and can't update the system's termcap file. How 476 do I get all of my programs to use one of Joe's termcap entries?" 477 478Again, copy termcap into '.termcap' in your home directory, but set the 479environment variables like this: 480 481 setenv TERMCAP $HOME/.termcap 482 setenv TERM fansi 483 484"My system uses terminfo... how do I get all of my programs to use one of 485 Joe's termcap entries?" 486 487First, compile joe for terminfo. You then have to 'tic' the terminfo 488version of joe's termcap file into your account. These are the commands for 489doing this: 490 491 1) cd 492 2) mkdir .info 493 3) setenv TERMINFO $HOME/.info 494 495 (or 496 497 TERMINFO=$HOME/.info; export TERMINFO 498 499 if you use bash, sh or ksh) 500 501 4) tic joe/terminfo 502 503Then put the 'setenv TERMINFO $HOME/.info' line into your .login file or 504'TERMINFO=$HOME/.info; export TERMINFO' in your .profile. Now all of your 505programs should look up the 'TERM' in your own personal terminfo database. 506