diff --git a/bochs/doc/docbook/user/user.dbk b/bochs/doc/docbook/user/user.dbk index bc4dca208..9990652bc 100644 --- a/bochs/doc/docbook/user/user.dbk +++ b/bochs/doc/docbook/user/user.dbk @@ -1,7 +1,7 @@ @@ -997,21 +997,26 @@ a transcript of a successful compilation from start to finish. There is a script called configure which tests your -machine, C/C++ compiler and libraries to automatically configure Bochs -on your system. If you run configure with no arguments -after it, defaults will be used for all settings. To change the -settings, you can run configure again with more options to -override the usual defaults. You can get a list of valid configure options -by typing configure --help. All configure options -are documented in a later section. - +machine, C/C++ compiler and libraries to discover what settings should work on +your system. If you run configure with no arguments after +it, defaults will be used for all settings. To change the settings, you can +run configure again with options that override the +defaults. You can get a list of valid configure options by typing +configure --help. All configure options are documented in a +later section. Among other things, the configure script tries to guess your compiler and a set of compile options that work. If you want to control this, set these environment variables before running configure: CC, CXX, CFLAGS, -CXXFLAGS. The bash commands for setting the +CXXFLAGS. The bash/ksh + +In csh and variants, use the syntax setenv VARIABLE value to change environment +variables. + + +commands for setting the environment variables are: export CC=egcs @@ -1028,13 +1033,11 @@ it creates a Makefile in every source code directory, and creates as preprocessor #defines. The sources are ready to compile. - -
Configure Shortcut Scripts (optional) In the Bochs sources, there are a series of scripts called .conf.platform. -These scripts run the configure script for you, with a set of +These scripts run configure script for you, with a set of options that appropriate for that platform. Examples include .conf.linux, .conf.win32-vcpp, @@ -1044,17 +1047,90 @@ Run a shortcut script using Bourne shell, like this: sh .conf.win32-vcpp -If you use a shortcut script, the script does the configure step for you. +If you use a shortcut script, you don't need to run configure manually. +If a shortcut script is "almost right" for you, just edit it and then run +it!
-
make +
+ + +
Make -The make command reads the &Makefile; in each source -directory to know how to build Bochs. A &Makefile; tells which files -depend on which other files, what commands to use to compile and link -the code, and more. After you have run configure, -just type make to build the source code. +The make command compiles Bochs. Make is a program +used by many software projects that reads the &Makefile; in each source +directory and follows the instructions that it finds there. A &Makefile; tells +which files depend on which other files, what commands to use to compile and +link the code, and more. After you have finished the configure step, just type +make to build the source code. + + + +The reason that make is so popular is that it is smart about when to compile +and when not to compile. If you run make once, it compiles every file. But +when you run it again, it checks to see if any source files have been modified; +if not, there's nothing to do! For example, the &Makefile; says that +main.o depends on main.cc. Knowing +this, it will only compile main.cc if it is newer than +main.o. + + + +Of course, make can only do the right thing if the &Makefile; lists all the +dependencies correctly, so human error can sometimes lead make astray. +If make refuses to build something that you think it should, or you +are getting strange compile errors, try doing make all-clean +and then make again. All-clean means to clean up +the compiled files in every subdirectory, while make clean +means to clean up just the current directory + + +This is different from the terminology of some other projects, and it may cause +confusion. Sometimes "clean" implies that all subdirectories are affected. + +. However, it's important to note that make +all-clean leaves the configuration intact. You do not have +to run configure again. + + + +If you're really in the mood for cleaning, make dist-clean +erases all the configuration information too. In theory, after a dist-clean +your directory should look much like when you first untarred it or checked it +out. There's usually some extra stuff lying around, but the &Makefile; tries +at least to erase any files that it created. + + +
+ +
Make Install + +Once the program has been built, the next step is typically to run +make install to copy the executables, documentation, and +other required files into a public place so that all users can use it. +&FIXME; + +
+ +
Compile Problems + + +what if configure fails? +- tar up config.* and send to bochs-testing@tlw.com +- report the problem with a source forge bug report. + +what if make fails? +- try make all-clean and make again +- use configure options to disable options. For example, if errors in +fpu/fpu_system.h, you could try --disable-fpu. +- search for the error on the Bochs website (bug reports, patches) +- if familiar with C++, many minor problems can be corrected +- move toward more stable code. if it's CVS, see if a release version will + compile. Report problem to bochs-developers. +- report the problem with a source forge bug report. + +
@@ -1062,8 +1138,6 @@ just type make to build the source code. Things to not forget: - What to report if configure fails: Tar up config.* and send to - bochs-testing@tlw.com What to try if make fails: turn off configure options, look at SF bugs and patches section to see if it's a known problem, try to fix it yourself, if using CVS version try