diff --git a/INSTALL b/INSTALL index 25dc699dc0..b869e76a74 100644 --- a/INSTALL +++ b/INSTALL @@ -1,215 +1,5 @@ -Installing BOINC - -This document describes the generic installation procedure for BOINC - -The installation procedure itself is broken into seven steps - - 1. Downloading the Source - 2. Ensuring proper programs are installed - 3. Setting environment variables - 4. Configuration - 5. Building - 6. Testing (optional but strongly recommended) - 7. Final install (optional) - -Please note that BOINC currently only supports the targets all clean install -uninstall tar and client_tar. Currently, BOINC is installed into the -/usr/local/boinc/ directory structure. To install BOINC into a different -directory structure, the macro INSTALL_DIR needs to be edited in all -Makefile.in files. - -------------------------------------------------------------------------------- -Downloading the Source - -BOINC is distributed via CVS, tarballs compressed with gzip, and Windows -zip files. - -The BOINC distribution includes the scheduling servers, both in CGI and FastCGI -versions, the application library, the client, the test scripts, sample -applications, and test scripts. - -Unpack the distribution in one directory using the commands - % gunzip boinc.tar.gz - % tar xf boinc.tar - -If installing from CVS, download the entire CVS tree. - -If installing on Windows, unzip boinc.zip or boinc.tar.gz. Next, unzip -win_build.zip inside the BOINC directory. - -If installing on Mac OS X, unzip boinc.zip or boinc.tar.gz. Next, unstuff -mac_build.sit inside the BOINC directory. - -------------------------------------------------------------------------------- -Ensuring proper programs are installed - -In order for the BOINC server to run, Apache web server and mySQL database -server must both be installed and shared memory must be enabled, with a shared -memory segment size of at least 32 megabytes (more is reccomended). - -It is highly reccomended that PHP be installed, as the test scripts and web -administration are written in PHP and will not be usable without PHP installed. - -Apache should be configured to allow POST. - -------------------------------------------------------------------------------- -Setting environment variables - -BOINC depends on several environment variables to compile and run. - -BOINC_DOWNLOAD_DIR /usr/local/boinc/download -This directory should be set to be web accessible via Apache. If you plan on -using a different directory, be sure to set the BOINC_DOWNLOAD_DIR properly -so as to point to the correct directory. It is important that this directory -is different from the BOINC_UPLOAD_DIR. - -BOINC_UPLOAD_DIR /usr/local/boinc/upload -This directory should be set to be web accessible via Apache. If you plan on -using a different directory, be sure to set the BOINC_UPLOAD_DIR properly -so as to point to the correct directory. It is important that this directory is -different from the BOINC_DOWNLOAD_DIR. - -BOINC_PLATFORM_NAME -This is set when configure is run in the client directory. It is used by the -client to determine the name of the BOINC client. - -BOINC_EMAIL mgary@ssl.berkeley.edu -This is currently used by one of the test scripts. It is not critical for the -running of BOINC. - -BOINC_KEY_DIR /usr/local/boinc/key_dir -This should be set to a directory in which the public and private keys for -BOINC are to be created. If you wish to place this in a different directory, -change the variable appropriately. - -BOINC_SHMEM_KEY 0xdadacafe -This should be set to any 32 bit hex value desired. To run multiple instances -of BOINC on one machine, each instance needs to have a different BOINC_SHMEM_KEY -compiled into it. - -BOINC_DB_NAME boinc -This should be set to a valid database name for mySQL. - -BOINC_USER user -This should be set to the user name of the person running BOINC. - -BOINC_UPLOAD_URL http://localhost/cgi-bin/file_upload_handler -This should be set to the url of a valid cgi directory where the BOINC -scheduling server cgi scripts are located. - -BOINC_DOWNLOAD_URL http://localhost/download -This should be set to the url of the BOINC_DOWNLOAD_DIR. - -BOINC_MASTER_URL http:\\\/\\\/localhost\\\/index.html -This should be set to the master url of your project. The master url is a file -that contains xml tags with information about where scheduling servers can be -found. A sample scheduler tag would be -http://localhost/cgi-bin/cgi -where the url contained within the scheduler tags points to the BOINC -scheduling server cgi scripts. - -------------------------------------------------------------------------------- -Configuration - -Like most open source software, BOINC must be configured before it can be -built. This document describes the recommended configuration procedure for -both native and cross targets. - -We use srcdir to refer to the toplevel source directory for BOINC. - -In general, BOINC need not be built into a seperate directory from the source. - -Second, when configuring a native system, either cc or gcc must be in your path -or you must set CC in your environment variables before running configure. -Otherwise, the configuration scripts may fail. - -To configure BOINC: - - % cd srcdir - % ./configure - -------------------------------------------------------------------------------- -Building - -Now that BOINC is configured, you are ready to build BOINC. - -Some commands executed when making BOINC may fail (return a nonzero status) and -be ignored by make. - -It is normal to have compiler warnings when compiling certain files. The most -common of these warnings is statement with no effect, due to the use of assert -in the scheduling server, and can be safely ignored. - -To make BOINC: - - % cd srcdir - % make - -------------------------------------------------------------------------------- -Testing - -Once BOINC has been built, environment variables are set, and permissions have -been granted, we encourage you to run tests to ensure that BOINC is working -properly before being installed. The tests are located in the srcdir/test/ -directory, and are all php scripts. - -test_suite.php -This is a script that will run several of the scripts within the test -directory. If there are any file mismatches or errors, there has likely been an -error in setting up BOINC. - -test_uc.php -This is a script that runs the uc application. The files should match upon -completion of the script. - -test_concat.php -This sript is similar to the test_uc.php script, except that it runs the concat -application. - -test_water.php -This script tests some of the water mark funtionality in the BOINC client. If -test_uc.php does not work, this script will also fail. - -test_rsc.php -This script tests to ensure that the server will not send unfeasable work units -to a client. Should this script fail, it is either due to your computer having -more than 1 terabyte of available memory and similar amounts of available disk -space or improper configuration of BOINC. - -test_api.php -This script should run even if BOINC has been installed improperly. As long as -a build has occurred, this script should work. This script tests the api and -a restartible minimal application without an end-to-end test of BOINC. - -test_uc_slow.php -This script is similar to the test_uc.php script, except that it uses the -uc_slow application. The client must be run manually for this script. Currently -there is a bug in BOINC that causes this script to fail. - -test_stderr.php -This script uses the uc application to check client error reporting. - -------------------------------------------------------------------------------- -Installing - -Now that BOINC has been built and tested, you can optionally install it in -/usr/local/boinc. - -If the location of any of the CGI elements of the scheduling server are to be -changed, the appropriate environment variables must be updated and the code -must be rebuilt with - $ cd srcdir; make clean; configure; make - -You can install BOINC in /usr/local/boinc with - - % cd srcdir; make install - -You may also want to run the test scripts now that you have installed BOINC to -ensure that all environment variables have been properly set and compiled into -the code. - -------------------------------------------------------------------------------- - -If you had any issues with BOINC, please let us know. If you come across any -bugs, please post them to our bugtraq or email us. +BOINC documentation is kept online at +http://boinc.berkeley.edu/create_project.html +The documentation is also part of the source tree +(in the doc/ directory). diff --git a/INSTALL_CLIENT b/INSTALL_CLIENT deleted file mode 100644 index 36d948d12c..0000000000 --- a/INSTALL_CLIENT +++ /dev/null @@ -1,89 +0,0 @@ -Installing the BOINC client - -This document describes the generic installation procedure for the BOINC client - -The installation procedure itself is broken into four steps - - 1. Downloading the Source - 2. Configuration - 3. Building - 4. Running the BOINC client - -Please note that BOINC currently only supports the targets all clean install -uninstall tar and zip. Currently, BOINC is installed into the /usr/local/boinc/ -directory structure. To install BOINC into a different directory structure, -the macro INSTALL_DIR needs to be edited in the client/Makefile.in file. - -------------------------------------------------------------------------------- -Downloading the Source - -BOINC is distributed via CVS, tarballs compressed with gzip, and Windows -zip files. - -The BOINC client distribution includes the core client and the application -library. - -Unpack the distribution in one directory using the commands - % gunzip boinc_client.tar.gz - % tar xf boinc_client.tar - -If installing from CVS, the boinc/client, boinc/api, boinc/lib, and -boinc/RSAEuro directories must be downloaded. The boinc/doc directory may be -downloaded if documentation is desired. - -If installing on Windows, unzip boinc_client.zip or boinc_client.tar.gz. -Next, unzip win_build.zip inside the BOINC directory. - -If installing on Mac OS X, unzip boinc_client.zip or boinc_client.tar.gz. -Next, unstuff mac_build.sit inside the BOINC directory. - -------------------------------------------------------------------------------- -Configuration - -Like most open source software, BOINC must be configured before it can be -built. This document describes the recommended configuration procedure for -both native and cross targets. - -We use srcdir to refer to the toplevel source directory for BOINC. - -In general, BOINC need not be built into a seperate directory from the source. - -Second, when configuring a native system, either cc or gcc must be in your path -or you must set CC in your environment variables before running configure. -Otherwise, the configuration scripts may fail. - -To configure the BOINC client: - - % cd srcdir/client - % ./configure - -------------------------------------------------------------------------------- -Building - -Now that BOINC is configured, you are ready to build BOINC - -Some commands executed when making BOINC may fail (return a nonzero status) and -be ignored by make. - -It is normal to have compiler warnings when compiling certain files. These -warnings can be safely ignored unless you are a member of the development team. - -To make the BOINC client: - - % cd srcdir/client - % make - -------------------------------------------------------------------------------- -Running the BOINC client - -The first time the BOINC client is run, it will prompt the user for some -information, including the master url of the project the user wishes to join -and an authenticator. The file will then attempt to contact the master url -to get information about scheduling servers and attempt to begin -working on the project. After this first time running, the output from the -BOINC client may be redirected to /dev/null. The client can accept two -command line options, -exit_when_idle, which will cause the client to exit -when a scheduling server replies with a no work available message, and the --exit_after N, which will cause the client to exit after approximately N -seconds. It is recommended that a value of N greater than 100 be given when -using this option. diff --git a/checkin_notes b/checkin_notes index b89b9442c6..246ccab839 100755 --- a/checkin_notes +++ b/checkin_notes @@ -2938,3 +2938,17 @@ David Jan 13 2003 test/ test.inc test_loop.php + +David Jan 14 2003 + - Removed INSTALL_CLIENT and gutted INSTALL + + NOTE: all docs should be in HTML + NOTE: spell-check all new documents + + INSTALL + INSTALL_CLIENT (removed) + doc/ + boinc_dev.html + road_map.html + single_host_server.html + test.html diff --git a/doc/boinc_dev.html b/doc/boinc_dev.html index 6194064bdb..08515246ac 100644 --- a/doc/boinc_dev.html +++ b/doc/boinc_dev.html @@ -16,9 +16,12 @@ Before sure that you understand exactly how BOINC is intended to work (for both participants and developers) before getting into the source code. +

+ +Core client +

diff --git a/doc/road_map.html b/doc/road_map.html index 861ba237e3..0643c73ac0 100644 --- a/doc/road_map.html +++ b/doc/road_map.html @@ -2,28 +2,21 @@

Source code road map

-Unpacking the BOINC source code -creates the following directories: -

-boinc/
-    RSAEuro/
-    api/
-    apps/
-    client/
-        win/
-        mac/
-    db/
-    doc/
-    html_ops/
-    html_user/
-    lib/
-    sched/
-    sched_fcgi/
-    test/
-    tools/
-
+BOINC is distributed via CVS, tarballs compressed with gzip, and Windows +zip files. + -The directory contents are as follows: +

+Unpacking the BOINC source code creates the following directories:

RSAEuro/
A public-domain RSA implementation. @@ -59,3 +52,11 @@ and file upload handler as Fast CGI programs.
tools/
Operational utility programs.
+

+On UNIX systems, the BOINC software (both server and client) +can be built by typing +

+  configure
+  make
+
+in the top directory. diff --git a/doc/single_host_server.html b/doc/single_host_server.html index 9b122b4f58..abb7cce190 100644 --- a/doc/single_host_server.html +++ b/doc/single_host_server.html @@ -19,8 +19,10 @@ Install the following software on the server host: +Your operating system must have shared memory enabled, with +a max shared segment size of at least 32 MB.

Directory structure

diff --git a/doc/test.html b/doc/test.html index 7886468651..ffbd7835da 100644 --- a/doc/test.html +++ b/doc/test.html @@ -88,61 +88,56 @@ class Project { // represents a project function add_user($user); // add a User to project's DB function add_app($app); // add an application function add_app_version($app_version); // add an app version - function install(optional: $echeduler_file); - //set up directories and DB. If $scheduler_file is provided, then - //there will be installed schedulers at the directories pointed by - //the schedulers + function install(optional: $scheduler_file); + //set up directories and DB. If $scheduler_file is provided, then + //there will be installed schedulers at the directories pointed by + //the schedulers function start(); // start feeder function stop(); // stop feeder - function compare_file($out, $correct); // verify that a result file - // matches a known-correct file - function check_results($n, $result); // check that there are n results - // and that they match "result" - // (for all fields that are defined) + function compare_file($out, $correct); + // verify that a result file matches a known-correct file + function check_results($n, $result); + // check that there are n results + // and that they match "result" + // (for all fields that are defined) - //The functions below are used to interrupt or remove certain - //functionalities of the project for a desired time in order to be - //able to test persistance across these failures. All the - //parameters of the functions below are optional. If $time is not - //then action will be taken immediately, otherwise we sleep for - //$time seconds and then take action. $cgi_num,$download_dir_num, - //$handler_num refer to the number of the corresponding parts of - //the system to be disabled temporarily. if they are not - //the default cgi, download, and file_upload_handler respectively. - //multiple cgis can be handles with passing in a file with - //scheduler_urls to project->install. Multiple download URLS are - //handled by adding a numer in between the download_url and the - //file to be downloaded in the wu_template file of the Work class - //for example: 0/, in which - //a link from project_dir/download0/ will be added to project_dir/download - //Similiar action can be taken by modifying the result_template file - //of a Work class to handle multiple upload URLs: - //for example: 0, in which case - //file_upload_handler0 will be added to project_dir/cgi + // The functions below are used to interrupt or remove certain + // functionalities of the project for a desired time in order to be + // able to test persistence across these failures. All the + // parameters of the functions below are optional. + // $cgi_num,$download_dir_num, + // $handler_num refer to the number of the corresponding parts of + // the system to be disabled temporarily. if they are not + // the default cgi, download, and file_upload_handler respectively. + // multiple cgis can be handles with passing in a file with + // scheduler_urls to project->install. Multiple download URLS are + // handled by adding a numer in between the download_url and the + // file to be downloaded in the wu_template file of the Work class + // for example: 0/, in which + // a link from project_dir/download0/ will be added to project_dir/download + // Similiar action can be taken by modifying the result_template file + // of a Work class to handle multiple upload URLs: + // for example: 0, in which case + // file_upload_handler0 will be added to project_dir/cgi - function delete_masterindex($time) //deletes the index.php for - //this project - function reestablish_masterindex($time) //reestablished the master - //index.php - function delete_scheduler($time,$cgi_num) - //deletes project_dir/cgi/cgi$cgi$num - function reinstall_scheduler($time,$cgi_num) - //copies the cgi program into - //project_dir/cgi/cgi$cgi$num - function delete_downloaddir($time,$download_dir_number) - //removes - //project_dir/download$download_dir_num - function reinstall_downloaddir($time,$download_dir_num) - //reestablished - //project_dir/download$download_dir_num - function remove_file_upload_handler($time,$handler_num) - //deletes - //project_dir/cgi/file_upload_handdler$handler_num - function reinstall_file_upload_handler($time, $handler_num) - //reinstalls - //project_dir/cgi/file_upload_handdler$handler_num - function kill_file_upload_hanlder() //blocks until a file_upload_handler is - //running in the system, kills it and returns + function delete_masterindex() + //deletes the index.php for this project + function reestablish_masterindex() + //reestablished the master index.php + function delete_scheduler($cgi_num) + //deletes project_dir/cgi/cgi$cgi$num + function reinstall_scheduler($cgi_num) + //copies the cgi program into project_dir/cgi/cgi$cgi$num + function delete_downloaddir($download_dir_number) + //removes project_dir/download$download_dir_num + function reinstall_downloaddir($download_dir_num) + //reestablished project_dir/download$download_dir_num + function remove_file_upload_handler($handler_num) + //deletes project_dir/cgi/file_upload_handler$handler_num + function reinstall_file_upload_handler($handler_num) + //reinstalls project_dir/cgi/file_upload_handler$handler_num + function kill_file_upload_handler() //blocks until a file_upload_handler is + //running in the system, kills it and returns } class User { // represents an account on a project @@ -157,9 +152,9 @@ class Host { // represents a (virtual) host function install(); //There are two run functions, one that blocks until the client - //being run by this host finishes exection: run() and then there + //being run by this host finishes execution: run() and then there //run_asynch which spawns a new php process running the client - //and returns to the thread of exection of the parent php process + //and returns to the thread of execution of the parent php process //the php process_id of the child. This process_id can then be //used for a call to pcntl_waitpid() to block until the execution //of the client. @@ -352,18 +347,21 @@ You have to run the client yourself, kill and restart it a few times. feasible work units.
  • test_pers.php: tests the persistent file transfers for -download and upload. It interrupts them in the middle and makes +download and upload. +It interrupts them in the middle and makes sure that the filesize never decreases along interrupted transfers.
  • test_masterurl_failure.php: tests the exponential backoff mechanism on the client in case of master IURL failures. -This test is not automated. It has to be run, and then client.out -(in the host directory) must be looked at to examine wether everything +This test is not automated. +It has to be run, and then client.out +(in the host directory) must be looked at to examine whether everything is working correctly.
  • test_sched_failure.php:tests the exponential backoff mechanism -on the client in case of scheduling server failures.This test is not -automated. It has to be run, and then client.out (in the host -directory) must be looked at to examine wether everything +on the client in case of scheduling server failures. +This test is not automated. +It has to be run, and then client.out (in the host +directory) must be looked at to examine whether everything is working correctly.