From 94ad83d9ada547dd4bc60643210fbc5b2f3da603 Mon Sep 17 00:00:00 2001 From: Bryce Denney Date: Sat, 17 Nov 2001 17:15:38 +0000 Subject: [PATCH] - include ../include/defs.sgm - add vasudeva as editor - add section about setting up cvs write access - add fixmes on most other sections --- bochs/doc/docbook/development/development.dbk | 211 ++++++++++++++++-- 1 file changed, 196 insertions(+), 15 deletions(-) diff --git a/bochs/doc/docbook/development/development.dbk b/bochs/doc/docbook/development/development.dbk index ddd7f6548..76e884871 100644 --- a/bochs/doc/docbook/development/development.dbk +++ b/bochs/doc/docbook/development/development.dbk @@ -1,12 +1,18 @@ - + + +%bochsdefs; + +]> Bochs Developers Guide @@ -14,58 +20,226 @@ This is the top level file for the Bochs Developers Manual. KevinLawton BryceDenney MichaelCalabrese + Vasudeva Resources for developers -
All the resources for users - - -
+ +The development guide describes resources that are intended for developers +in particular. Many Bochs resources are also covered in the User Guide, +including compile instructions, bochsrc options, how to find the mailing +lists, etc. + -
CVS - - how to browse on web interface - anonymous CVS (read only) - write access CVS (must be officially a developer) - how to make a patch using CVS - -
+ +
Setting up CVS write access + +If you are an official SourceForge developer, then you can use CVS with write +access. The CVS contains the most recent copy of the source code, and with +write access you can upload any changes you make to the CVS server for others +to use. A few extra steps are required the first time you use CVS write +access. + + +
Install ssh and cvs + +First you need to install both cvs (Concurrent Version System) and ssh (Secure +Shell). These are already installed on many UNIX systems and also Cygwin +(win32 platform). If not, you can install binaries or compile cvs and ssh +yourself. The links below should help you get going. + + + CVS software and instructions are available at www.cvshome.org. + A free version of secure shell called OpenSSH is at www.openssh.org. + OpenSSH requires a library called OpenSSL from www.openssl.org. Be sure to install OpenSSL before trying to compile OpenSSH. + +
+ +
ssh to cvs.sf.net + +Next, you need to use secure shell to connect to cvs.sf.net. This step is a +little strange, because you can't actually log in and get a shell prompt. All +that will happen, when you get the username and password right, is that it +will create a home directory on that machine for you. That's it! If you try +it again, it will say "This is a restricted Shell Account. You cannot execute +anything here." At this point, you've succeeded and you never have to do +this step again, ever. + + + ssh sfusername@cvs.sf.net + + + + +Replace sfusername with your Source Forge username, +of course. The first time, you will probably get a message like + +The authenticity of host 'cvs.sf.net' can't be established. +Are you sure you want to continue? + +Just type yes. When it asks for a password, be sure to type your source +forge password. If you have trouble logging in, be sure to use your SOURCE +FORGE username and password in the ssh line, which isn't necessarily the same +as your local username and password. Add the "-v" option to ssh to see more +information about what is failing. If you have ssh version 2, it is possible +that you might need to add "-1" to the ssh command to force it to use the +version 1 protocol.
+ +
Set CVS_RSH environment variable to ssh + +Every time you connect to the Source Forge CVS server (including cvs update, +stat, commit, etc.), you must set the CVS_RSH environment variable to ssh. So +just take the time now to add one of these lines to your .bashrc/.cshrc, so +that the CVS_RSH setting will be there every time you log in. + + + + export CVS_RSH=ssh (bash syntax) + setenv CVS_RSH ssh (csh syntax) + +
+ +
cvs checkout + +Finally, you should be able to do the checkout! If you already have a bochs +subdirectory directory, move it out of the way because the checkout will +overwrite it. + + + + export CVSROOT=":ext:sfusername@cvs.bochs.sourceforge.net:/cvsroot/bochs" + cvs -z3 checkout bochs + sfusername@cvs.sf.net's password: <--type your password + + + +In the CVSROOT variable, replace sfusername with your SF username. There's +no need to add CVSROOT to your rc files because CVS will remember it +after the checkout. The -z3 (optional) just adds some compression to make +the checkout go faster. Once all the files have been downloaded, you will +have a bochs directory which is checked out with write access! + +
+ +
+ +
Using CVS write access + +
Checking in files + +Once you have a bochs directory with cvs write access, you can compile the +files, edit them, test them, etc. See the documentation section, "Tracking +the source code with CVS" for more info on CVS, in the User Manual. +(FIXME: add cross reference) But what's new and different is that you can now +do cvs commits. When a file is all fixed and ready to share with the rest of +the world, you run a commit command to upload your version to the server. +First, it's good to do a cvs update to make sure nobody else has changed it +since you downloaded it last. + + + + $ cvs update file.cc + sfusername@cvs.sf.net's password: <--type your password + $ cvs commit file.cc + sfusername@cvs.sf.net's password: <--type your password + [editor opens. type log message, save, and exit.] + + + +When CVS starts an editor, The default is usually vi. If you want a different +editor, set the EDITOR environment variable to the name of your preferred +editor. When you're done, just save the file and quit the editor. Unless +there's some problem, you will see a message that says what the new revision +number for the file is, and then "done". If while you're editing the log +message, you decide that you don't want to commit after all, don't save the +file. Quit the editor, and when it asks where the log message went, tell it +to abort. + + + +Here is an example of a successful checkin: + + + $ cvs commit misc.txt + sfusername@cvs.sf.net's password: <--type your password + [edit log msg] + Checking in misc.txt; + /cvsroot/bochs/bochs/doc/docbook/misc.txt,v <-- misc.txt + new revision: 1.6; previous revision: 1.5 + done + + +And here is an aborted one: + + + $ cvs commit misc.txt + sfusername@cvs.sf.net's password: <--type your password + [quit editor without saving] + Log message unchanged or not specified + a)bort, c)ontinue, e)dit, !)reuse this message unchanged for remaining dirs + Action: a + cvs [commit aborted]: aborted by user + + + +
+ +
SourceForge bug, feature, and patch trackers + &FIXME;
+ +
Ideas for other sections + + +Ideas: +- how to browse code with cvsweb +- how to find an identifier, variable, or specific text in the code +- write access CVS (must be an official developer on SF) +- how to make patches with CVS + + +
+ About the code
Directory Structure + &FIXME; cpu directory does this, iodev does that, gui does that
-
Confure Scripting +
Configure Scripting + &FIXME; configure script, makefiles, header files
Log Functions + &FIXME; log functions: what is a panic, what is an error, etc.
Emulator Objects + &FIXME; objects that do all the work (cpu, mem)
timers + &FIXME;
@@ -73,18 +247,22 @@ This is the top level file for the Bochs Developers Manual. Debugger
compile with debugger support + &FIXME;
get started in debugger + &FIXME;
command reference + &FIXME;
techniques + &FIXME;
@@ -92,16 +270,19 @@ This is the top level file for the Bochs Developers Manual. Coding
coding conventions + &FIXME;
patches: + &FIXME; how to make, where to submit, what happens then?
life cycle of a CVS release + &FIXME;