From owner-freebsd-doc Sat Oct 9 9:40:47 1999 Delivered-To: freebsd-doc@freebsd.org Received: from freefall.freebsd.org (freefall.FreeBSD.ORG [204.216.27.21]) by hub.freebsd.org (Postfix) with ESMTP id E0B57154EF for ; Sat, 9 Oct 1999 09:40:02 -0700 (PDT) (envelope-from gnats@FreeBSD.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.9.3/8.9.2) id JAA43641; Sat, 9 Oct 1999 09:40:02 -0700 (PDT) (envelope-from gnats@FreeBSD.org) Received: from terrapin.ru.ac.za (terrapin.ru.ac.za [146.231.128.6]) by hub.freebsd.org (Postfix) with ESMTP id 2E362151DD for ; Sat, 9 Oct 1999 09:30:50 -0700 (PDT) (envelope-from nbm@mithrandr.moria.org) Received: from duca.dialup.ru.ac.za ([146.231.98.24] helo=mithrandr.moria.org) by terrapin.ru.ac.za with esmtp (Exim 3.03 #1) id 11ZzOL-0002Mb-00 for FreeBSD-gnats-submit@freebsd.org; Sat, 09 Oct 1999 18:30:42 +0200 Received: (qmail 76654 invoked by uid 1001); 9 Oct 1999 16:23:35 -0000 Message-Id: <19991009162335.76653.qmail@mithrandr.moria.org> Date: 9 Oct 1999 16:23:35 -0000 From: nbm@rucus.ru.ac.za Reply-To: nbm@rucus.ru.ac.za To: FreeBSD-gnats-submit@freebsd.org X-Send-Pr-Version: 3.2 Subject: docs/14237: programming-tools article markup changes Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org >Number: 14237 >Category: docs >Synopsis: programming-tools article markup changes >Confidential: no >Severity: non-critical >Priority: low >Responsible: freebsd-doc >State: open >Quarter: >Keywords: >Date-Required: >Class: change-request >Submitter-Id: current-users >Arrival-Date: Sat Oct 9 09:40:01 PDT 1999 >Closed-Date: >Last-Modified: >Originator: Neil Blakey-Milner >Release: FreeBSD 4.0-CURRENT i386 >Organization: Rhodes University Computer Users' Society >Environment: FreeBSD mithrandr.moria.org 4.0-CURRENT FreeBSD 4.0-CURRENT #2: Wed Sep 29 17:30:21 SAST 1999 root@mithrandr.moria.org:/usr/src/sys/compile/MITHRANDR i386 >Description: Introduce un--wrap lists &prompt entities introduced. >How-To-Repeat: >Fix: cvs diff: Diffing . Index: article.sgml =================================================================== RCS file: /home/nbm/ncvs/doc/en_US.ISO_8859-1/articles/programming-tools/article.sgml,v retrieving revision 1.8 diff -u -r1.8 article.sgml --- article.sgml 1999/10/04 22:04:28 1.8 +++ article.sgml 1999/10/09 14:26:02 @@ -118,13 +118,12 @@ To get one of these packages, all you need to do is to click on the hotlink for the package, then run -$ pkg_add package name +&prompt.root; pkg_add package name as root. Obviously, you will need to have a fully functional FreeBSD 2.1.0 or later system for the package to work! - BASIC @@ -206,7 +205,6 @@ - @@ -309,13 +307,14 @@ Fortunately, almost all this detail is hidden from you, as cc is a front end that manages calling all these programs with the right arguments for you; simply typing -$ cc foobar.c + +&prompt.user; cc foobar.c will cause foobar.c to be compiled by all the steps above. If you have more than one file to compile, just do something like -$ cc foo.c bar.c +&prompt.user; cc foo.c bar.c Note that the syntax checking is just that—checking the syntax. It will not check for any logical mistakes you may have made, @@ -337,8 +336,8 @@ the mists of history. -$ cc foobar.c executable is a.out -$ cc -o foobar foobar.c executable is foobar +&prompt.user; cc foobar.c executable is a.out +&prompt.user; cc -o foobar foobar.c executable is foobar @@ -349,7 +348,7 @@ a Makefile. -$ cc -c foobar.c +&prompt.user; cc -c foobar.c This will produce an object file (not an @@ -373,7 +372,7 @@ works properly. -$ cc -g foobar.c +&prompt.user; cc -g foobar.c This will produce a debug version of the @@ -401,7 +400,7 @@ version. -$ cc -O -o foobar foobar.c +&prompt.user; cc -O -o foobar foobar.c This will produce an optimised version of @@ -461,7 +460,7 @@ what you may be using in a few years time? -$ cc -Wall -ansi -pedantic -o foobar foobar.c +&prompt.user; cc -Wall -ansi -pedantic -o foobar foobar.c This will produce an executable foobar @@ -490,7 +489,7 @@ last library on the command line. -$ cc -o foobar foobar.c -lm +&prompt.user; cc -o foobar foobar.c -lm This will link the math library functions into @@ -505,9 +504,9 @@ on FreeBSD. -$ cc -o foobar foobar.cc -lg++ For FreeBSD 2.1.6 and earlier -$ cc -o foobar foobar.cc -lstdc++ For FreeBSD 2.2 and later -$ c++ -o foobar foobar.cc +&prompt.user; cc -o foobar foobar.cc -lg++ For FreeBSD 2.1.6 and earlier +&prompt.user; cc -o foobar foobar.cc -lstdc++ For FreeBSD 2.2 and later +&prompt.user; c++ -o foobar foobar.cc Each of these will both produce an executable @@ -529,23 +528,31 @@ Common <command>cc</command> Queries and Problems -Q. I am trying to write a program which uses the + + + +I am trying to write a program which uses the sin() function and I get an error like this. What does it mean? + /var/tmp/cc0143941.o: Undefined symbol `_sin' referenced from text segment - - -A. When using mathematical functions like + + +When using mathematical functions like sin(), you have to tell cc to -link in the math library, like so: +link in the math library, like so: -$ cc -o foobar foobar.c -lm - - -Q. All right, I wrote this simple program to practice using +&prompt.user; cc -o foobar foobar.c -lm + + + + + +All right, I wrote this simple program to practice using . All it does is raise 2.1 to the power of 6. + #include <stdio.h> @@ -557,31 +564,40 @@ return 0; } + and I compiled it as: + -$ cc temp.c -lm +&prompt.user; cc temp.c -lm + like you said I should, but I get this when I run it: + -$ ./a.out +&prompt.user; ./a.out 2.1 ^ 6 = 1023.000000 - This is not the right answer! What is going on? - -A. When the compiler sees you call a function, it checks if it + + +When the compiler sees you call a function, it checks if it has already seen a prototype for it. If it has not, it assumes the function returns an int, which is definitely not what you want here. - -Q. So how do I fix this? - -A. The prototypes for the mathematical functions are in + + + + +So how do I fix this? + + +The prototypes for the mathematical functions are in math.h. If you include this file, the compiler will be able to find the prototype and it will stop doing strange things to your calculation! + #include <math.h> #include <stdio.h> @@ -589,94 +605,125 @@ int main() { ... - After recompiling it as you did before, run it: + -$ ./a.out +&prompt.user; ./a.out 2.1 ^ 6 = 85.766121 - If you are using any of the mathematical functions, always include math.h and remember to link in the math library. - -Q. I compiled a file called foobar.c and I + + + + +I compiled a file called foobar.c and I cannot find an executable called foobar. Where's it gone? - -A. Remember, cc will call the executable + + +Remember, cc will call the executable a.out unless you tell it differently. Use the option: + -$ cc -o foobar foobar.c +&prompt.user; cc -o foobar foobar.c - - -Q. OK, I have an executable called foobar, + + + + +OK, I have an executable called foobar, I can see it when I run ls, but when I type in foobar at the command prompt it tells me there is no such file. Why can it not find it? - -A. Unlike MS-DOS, Unix does not look in the + + +Unlike MS-DOS, Unix does not look in the current directory when it is trying to find out which executable you want it to run, unless you tell it to. Either type ./foobar, which means run the file called foobar in the current directory, or change your PATH environment variable so that it looks something like + bin:/usr/bin:/usr/local/bin:. + The dot at the end means look in the current directory if it is not in any of the others. - -Q. I called my executable test, but + + + + +I called my executable test, but nothing happens when I run it. What is going on? - -A. Most Unix systems have a program called + + +Most Unix systems have a program called test in /usr/bin and the shell is picking that one up before it gets to checking the current directory. Either type: + -$ ./test +&prompt.user; ./test + or choose a better name for your program! - -Q. I compiled my program and it seemed to run all right at + + + + +I compiled my program and it seemed to run all right at first, then there was an error and it said something about core dumped. What does that mean? - -A. The name core dump dates back to the + + +The name core dump dates back to the very early days of Unix, when the machines used core memory for storing data. Basically, if the program failed under certain conditions, the system would write the contents of core memory to disk in a file called core, which the programmer could then pore over to find out what went wrong. - -Q. Fascinating stuff, but what I am supposed to do now? - -A. Use gdb to analyse the core (see + + + +Fascinating stuff, but what I am supposed to do now? + + +Use gdb to analyse the core (see ). - -Q. When my program dumped core, it said something about a + + + + +When my program dumped core, it said something about a segmentation fault. What's that? - -A. This basically means that your program tried to perform some sort + + +This basically means that your program tried to perform some sort of illegal operation on memory; Unix is designed to protect the operating system and other programs from rogue programs. Common causes for this are: + Trying to write to a NULL pointer, eg + char *foo = NULL; strcpy(foo, "bang!"); - + Using a pointer that hasn't been initialised, eg + char *foo; strcpy(foo, "bang!"); + The pointer will have some random value that, with luck, will point into an area of memory that isn't available to your program and the kernel will kill your program before @@ -686,51 +733,68 @@ mysteriously. Trying to access past the end of an array, eg + int bar[20]; -bar[27] = 6; +bar[27] = 6; Trying to store something in read-only memory, eg + char *foo = "My string"; strcpy(foo, "bang!"); + Unix compilers often put string literals like "My string" into read-only areas of memory. Doing naughty things with malloc() and free(), eg + char bar[80]; free(bar); + or + char *foo = malloc(27); free(foo); free(foo); - + - + Making one of these mistakes will not always lead to an error, but they are always bad practice. Some systems and compilers are more tolerant than others, which is why programs that ran well on one system can crash when you try them on an another. - -Q. Sometimes when I get a core dump it says bus + + + + +Sometimes when I get a core dump it says bus error. It says in my Unix book that this means a hardware problem, but the computer still seems to be working. Is this true? - -A. No, fortunately not (unless of course you really do have a hardware + + +No, fortunately not (unless of course you really do have a hardware problem…). This is usually another way of saying that you accessed memory in a way you shouldn't have. - -Q. This dumping core business sounds as though it could be quite + + + + +This dumping core business sounds as though it could be quite useful, if I can make it happen when I want to. Can I do this, or do I have to wait until there's an error? - -A. Yes, just go to another console or xterm, do -$ ps + + +Yes, just go to another console or xterm, do +&prompt.user; ps + to find out the process ID of your program, and do -$ kill -ABRT pid + +&prompt.user; kill -ABRT pid + where pid is the process ID you looked up. @@ -738,6 +802,9 @@ loop, for instance. If your program happens to trap SIGABRT, there are several other signals which have a similar effect. + + + @@ -751,14 +818,18 @@ When you're working on a simple program with only one or two source files, typing in -$ cc file1.c file2.c + +&prompt.user; cc file1.c file2.c + is not too bad, but it quickly becomes very tedious when there are several files—and it can take a while to compile, too. One way to get around this is to use object files and only recompile the source file if the source code has changed. So we could have something like: -$ cc file1.o file2.o … file37.c &hellip + +&prompt.user; cc file1.o file2.o … file37.c &hellip + if we'd changed file37.c, but not any of the others, since the last time we compiled. This may speed up the compilation quite a bit, but doesn't solve the typing @@ -805,8 +876,10 @@ Example of using <command>make</command> Here's a very simple make file: + foo: foo.c cc -o foo foo.c + It consists of two lines, a dependency line and a creation line. The dependency line here consists of the name of the program @@ -840,14 +913,17 @@ Another useful property of makefiles is that the targets don't have to be programs. For instance, we could have a make file that looks like this: + foo: foo.c cc -o foo foo.c install: - cp foo /home/me + cp foo /home/me We can tell make which target we want to make by typing: -$ make target + +&prompt.user; make target + make will then only look at that target and ignore any others. For example, if we type make foo with the makefile above, make will ignore the install target. @@ -886,11 +962,11 @@ BSD-based systems like FreeBSD come with some very powerful ones as part of the system. One very good example of this is the FreeBSD ports system. Here's the essential part of a typical ports -Makefile: +Makefile: MASTER_SITES= ftp://freefall.cdrom.com/pub/FreeBSD/LOCAL_PORTS/ DISTFILES= scheme-microcode+dist-7.3-freebsd.tgz -.include <bsd.port.mk> +.include <bsd.port.mk> Now, if we go to the directory for this port and type make, the following happens: @@ -965,7 +1041,9 @@ The version of make that comes with FreeBSD is the Berkeley make; there is a tutorial for it in /usr/share/doc/psd/12.make. To view it, do -$ zmore paper.ascii.gz + +&prompt.user; zmore paper.ascii.gz + in that directory. Many applications in the ports use GNU @@ -979,7 +1057,9 @@ you will have to edit the dir file in the /usr/local/info directory to add an entry for it. This involves adding a line like + * Make: (make). The GNU Make utility. + to the file. Once you have done this, you can type info and then select make from the menu (or in @@ -998,10 +1078,13 @@ The debugger that comes with FreeBSD is called gdb (GNU debugger). You start it up by typing -$ gdb progname + +&prompt.user; gdb progname + although most people prefer to run it inside Emacs. You can do this by: -M-x gdb RET progname RET + +M-x gdb RET progname RET Using a debugger allows you to run the program under more controlled circumstances. Typically, you can step through the program @@ -1035,7 +1118,8 @@ gdb. It will work without, but you'll only see the name of the function you're in, instead of the source code. If you see a line like: -… (no debugging symbols found) …when + +… (no debugging symbols found) …when gdb starts up, you'll know that the program wasn't compiled with the option. @@ -1058,6 +1142,7 @@ Here's a simple example of how to spot a mistake in a program with gdb. This is our program (with a deliberate mistake): + #include <stdio.h> int bazz(int anint); @@ -1074,20 +1159,20 @@ printf("You gave me %d\n", anint); return anint; } - This program sets i to be 5 and passes it to a function bazz() which prints out the number we gave it. When we compile and run the program we get -$ cc -g -o temp temp.c -$ ./temp + +&prompt.user; cc -g -o temp temp.c +&prompt.user; ./temp This is my program -anint = 4231 +anint = 4231 That wasn't what we expected! Time to see what's going -on!$ gdb temp +on!&prompt.user; gdb temp GDB is free software and you are welcome to distribute copies of it under certain conditions; type "show copying" to see the conditions. There is absolutely no warranty for GDB; type "show warranty" for details. @@ -1102,7 +1187,7 @@ This is my program Program prints out (gdb) s step into bazz() bazz (anint=4231) at temp.c:17 gdb displays stack frame -(gdb) +(gdb) Hang on a minute! How did anint get to be @@ -1110,12 +1195,15 @@ in main()? Let's move up to main() and have a look. -(gdb) up Move up call stack +(gdb) up Move up call stack #1 0x1625 in main () at temp.c:11 gdb displays stack frame (gdb) p i Show us the value of i -$1 = 4231 gdb displays 4231 +$1 = 4231 gdb displays 4231 + + Oh dear! Looking at the code, we forgot to initialise i. We meant to put + … main() { int i; @@ -1123,6 +1211,7 @@ i = 5; printf("This is my program\n"); &hellip + but we left the i=5; line out. As we didn't initialise i, it had whatever number happened to be in that area of memory when the program ran, which in this case @@ -1154,12 +1243,15 @@ To examine a core file, start up gdb in the usual way. Instead of typing break or run, type + (gdb) core progname.core + If you're not in the same directory as the core file, you'll have to do dir /path/to/core/file first. You should see something like this: -$ gdb a.out + +&prompt.user; gdb a.out GDB is free software and you are welcome to distribute copies of it under certain conditions; type "show copying" to see the conditions. There is absolutely no warranty for GDB; type "show warranty" for details. @@ -1169,7 +1261,7 @@ Program terminated with signal 11, Segmentation fault. Cannot access memory at address 0x7020796d. #0 0x164a in bazz (anint=0x5) at temp.c:17 -(gdb) +(gdb) In this case, the program was called a.out, so the core file is called @@ -1182,11 +1274,12 @@ stack in a complex program. The bt command causes gdb to print out a back-trace of the call stack: + (gdb) bt #0 0x164a in bazz (anint=0x5) at temp.c:17 #1 0xefbfd888 in end () #2 0x162c in main () at temp.c:11 -(gdb)The end() function is called when +(gdb)The end() function is called when a program crashes; in this case, the bazz() function was called from main(). @@ -1204,13 +1297,15 @@ What you do is start up another gdb, use ps to find the process ID for the child, and -do(gdb) attach pid +do(gdb) attach pid + in gdb, and then debug as usual. That's all very well, you're probably thinking, but by the time I've done that, the child process will be over the hill and far away. Fear not, gentle reader, here's how to do it (courtesy of the gdb info pages): + &hellip if ((pid = fork()) < 0) /* _Always_ check this */ error(); @@ -1222,6 +1317,7 @@ &hellip } else { /* parent */ &hellip + Now all you have to do is attach to the child, set PauseMode to 0, and wait for the sleep() call to return! @@ -1259,6 +1355,7 @@ It's impossible even to summarise everything Emacs can do here, but here are some of the features of interest to developers: + Very powerful editor, allowing search-and-replace on @@ -1289,7 +1386,7 @@ You can read Usenet news and mail while your program is compiling. -And doubtless many more that I've overlooked. +And doubtless many more that I've overlooked. Emacs can be installed on FreeBSD using the Emacs @@ -1386,7 +1483,6 @@ Unfortunately, there's far too much here to explain it in detail; however there are one or two points worth mentioning. - Everything beginning with a ; is a @@ -1423,7 +1519,9 @@ We enable Emacs's ability to act as a server, so that if you're doing something outside Emacs and you want to edit a file, you can just type in -$ emacsclient filename + +&prompt.user; emacsclient filename + and then you can edit the file in your Emacs!Many Emacs users set their EDITOR environment to @@ -1431,11 +1529,10 @@ to edit a file. - A sample <filename>.emacs</filename> file -;; -*-Emacs-Lisp-*- +;; -*-Emacs-Lisp-*- ;; This file is designed to be re-evaled; use the variable first-time ;; to avoid any problems with this. @@ -1509,9 +1606,9 @@ (autoload 'ediff-buffers "ediff" "Intelligent Emacs interface to diff" t) (autoload 'ediff-files "ediff" "Intelligent Emacs interface to diff" t) (autoload 'ediff-files-remote "ediff" - "Intelligent Emacs interface to diff") + "Intelligent Emacs interface to diff") -(if first-time +(if first-time (setq auto-mode-alist (append '(("\\.cpp$" . c++-mode) ("\\.hpp$" . c++-mode) @@ -1613,9 +1710,9 @@ (defun previous-error (n) "Visit previous compilation error message and corresponding source code." (interactive "p") - (next-error (- n))) + (next-error (- n))) -;; Misc... +;; Misc... (transient-mark-mode 1) (setq mark-even-if-inactive t) (setq visible-bell nil) @@ -1716,7 +1813,7 @@ ;; All done (message "All done, %s%s" (user-login-name) ".") - + @@ -1735,16 +1832,20 @@ usually end in .el, short for Emacs Lisp. For example, if whizbang is a FreeBSD port, we can locate these files by doing -$ find /usr/ports/lang/whizbang -name "*.el" -print + +&prompt.user; find /usr/ports/lang/whizbang -name "*.el" -print + and install them by copying them into the Emacs site Lisp directory. On FreeBSD 2.1.0-RELEASE, this is /usr/local/share/emacs/site-lisp. So for example, if the output from the find command was + /usr/ports/lang/whizbang/work/misc/whizbang.el + we would do -$ cp /usr/ports/lang/whizbang/work/misc/whizbang.el /usr/local/share/emacs/site-lisp +&prompt.root; cp /usr/ports/lang/whizbang/work/misc/whizbang.el /usr/local/share/emacs/site-lisp Next, we need to decide what extension whizbang source files have. Let's say for the sake of argument that they all end in @@ -1755,11 +1856,13 @@ Find the auto-mode-alist entry in .emacs and add a line for whizbang, such as: + … ("\\.lsp$" . lisp-mode) ("\\.wiz$" . whizbang-mode) ("\\.scm$" . scheme-mode) … + This means that Emacs will automatically go into whizbang-mode when you edit a file ending in .wiz. @@ -1767,10 +1870,12 @@ Just below this, you'll find the font-lock-auto-mode-list entry. Add whizbang-mode to it like so: + ;; Auto font lock mode (defvar font-lock-auto-mode-list (list 'c-mode 'c++-mode 'c++-c-mode 'emacs-lisp-mode 'whizbang-mode 'lisp-mode 'perl-mode 'scheme-mode) "List of modes to always start in font-lock-mode") + This means that Emacs will always enable font-lock-mode (ie syntax highlighting) when editing a .wiz file. >Release-Note: >Audit-Trail: >Unformatted: To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message