Update of /cvsroot/quantlibaddin/QuantLibAddin/Docs/pages In directory sc8-pr-cvs7.sourceforge.net:/tmp/cvs-serv1420/Docs/pages Added Files: build.quantlib.docs build.sourceforge.anonymous.docs build.sourceforge.developer.docs build.tutorial.docs build.vc.docs Log Message: add Build Tutorial (previously called Workstation Document) to the QuantLibAddin documentation --- NEW FILE: build.tutorial.docs --- /*! \page build_tutorial Build Tutorial This document explains how to configure your computer so that you can access the QuantLib CVS source code repository on SourceForge and build QuantLib. This is a three step process:<br> 1) install Visual C++<br> 2) set up SourceForge access - either anonymous or developer<br> 3) build QuantLib (including ObjectHandler and QuantLibAddin) Please follow the links at left for step by step instructions. */ --- NEW FILE: build.sourceforge.developer.docs --- /*! \page build_sourceforge_developer SourceForge Developer Access This document explains how to set up your computer to access the QuantLib CVS source code repository on the SourceForge web server. This procedure is for developer (write) access; if you only need anonymous (read) access then please refer instead to the document \ref sourceforge_anonymous. The steps in the process are: - set up a SourceForge account - install and configure Putty. This software allows you to connect to the SourceForge server. Putty includes a utility called Pageant which handles the connection to SourceForge via SSH (secure remote login). - install TortoiseCVS, a Windows client for the CVS (Concurrent Version System) source code control used by SourceForge for the QuantLib library - connect to SourceForge and check out a local copy of the QuantLib source code \section sec_sf_account SourceForge Account On the <a href="http://sourceforge.net">SourceForge</a> web site, set up an account. Ask the administrator to grant you developer access to the QuantLib project. \section sec_sf_putty Putty \subsection sec_sf_puttyinstall Installation Go to the <a href="http://www.chiark.greenend.org.uk/~sgtatham/putty/">Putty website</a> and download and install Putty. Use the complete Windows binary installation, <tt>putty-0.58-installer.exe</tt>. \subsection sec_sf_key SourceForge Key Setup Next you need to use Puttygen (included with Putty) to set up your SourceForge key. This is a two step procedure: - use Puttygen to generate a private key - upload the corresponding public key to the SourceForge website Step by step instructions are provided at <a href="http://sourceforge.net/docs/F02/en/#keygen_putty">this document</a> on the SourceForge website. \subsection sec_sf_pageantconfig Pageant Configuration Now launch the Pageant application (incuded with Putty). Pageant will minimize itself onto your toolbar: <img src="images/pageant_icon.jpg"> Double click on the icon, choose Add Key, and browse your way to the private key file created previously. Click close. \subsection sec_sf_puttyconfig Putty Configuration Next you need to configure some login sessions for SourceForge. Two sessions are required: - a shell, allowing you to log in to the command line on the QuantLib webserver - a CVS session allowing you to access the source code repository These sessions are configured using the main Putty application. Launch Putty. To configure the shell session: Under <tt>Connection/Data</tt>, enter your SourceForge username: <img src="images/putty_shell_data.jpg"> Under <tt>Connection/Proxy</tt>, configure the proxy server as shown: <img src="images/putty_shell_proxy.jpg"> Now go to the main Session dialog. Enter the hostname and port as shown. Then under <tt>'Saved Sessions'</tt>, type in the name <tt>qlshell</tt> and hit <tt>Save</tt>. <img src="images/putty_shell_session.jpg"> Now set up the CVS session. With the settings from qlshell still loaded, change the hostname as shown. Then under <tt>'Saved Sessions'</tt>, change the name to <tt>qlcvs</tt> and hit <tt>Save</tt>. <img src="images/putty_cvs_session.jpg"> \subsection sec_sf_testconfig Test Configurations Now you need to do a quick test to confirm that your configurations are set up correctly. Right click on the Pageant icon on the toolbar. Under 'Saved Sessions', click on qlshell. <img src="images/pageant_session.jpg"> This should bring you to the command line on the SourceForge server. Close the window. <img src="images/sf_shell.jpg"> Do the same for qlcvs. SourceForge should allow you to connect, SourceForge then immediately terminates your session as interactive sessions are not permitted on the CVS server. This error message is the expected behavior, and indicates that your CVS session is configured correctly. <img src="images/sf_cvs.jpg"> \section sec_sf_cvs TortoiseCVS This section explains how to install, configure, and use TortoiseCVS, the graphical interface for the source code version system. TortoiseCVS connects to SourceForge using the Putty configuration which you created above. \subsection sec_sf_cvsinstall Installation The TortoiseCVS site is <a href="http://www.tortoisecvs.org/">here</a>. The standard download file attempts to perform the installation interactively against the TortoiseCVS website, and will not work because of the firewall, so instead you need to use the TortoiseCVS Windows Installer (.msi file) which is a standalone local installation. The .msi installer (<tt>TortoiseCVS-1.8.25.msi</tt>) is available <a href="http://sourceforge.net/project/showfiles.php?group_id=142108">here</a>. \subsection sec_sf_configuration Configuration Go into TortoiseCVS preferences - either by right clicking in Windows Explorer and accessing the CVS menu, or by launching Tortoise Preferences from the Start Menu. Under the Tools tab, change the SSH application to plink as shown: <img src="images/tortoise_preferences.jpg"> \subsection sec_sf_checkout Usage Set aside an area of your hard drive where you will keep your local copy of QuantLib. Right click on the folder and launch "CVS Checkout". <img src="images/tortoise_checkout.jpg"> Configure Tortoise as shown and click OK: <img src="images/tortoise_configure.jpg"> TortoiseCVS installs the QuantLib source code tree to your hard drive. Repeat the procedure for ObjectHandler and QuantLibAddin. You're now ready to proceed with building QuantLib. Later you will want to amend the source code and commit your changes back to the CVS repository. For this please refer to the TortoiseCVS documentation. */ --- NEW FILE: build.sourceforge.anonymous.docs --- /*! \page build_sourceforge_anonymous SourceForge Anonymous Access This document explains how to set up your computer to access the QuantLib CVS source code repository on the SourceForge web server. This procedure is for anonymous access which allows you to acquire from CVS the latest copy of the QuantLib development environment. Anonymous access does not allow you to make changes to the QuantLib CVS repository, if you require write access please see instead the document \ref sourceforge_developer. \section sec_sfa_cvs TortoiseCVS This section explains how to install, configure, and use TortoiseCVS, the graphical interface for the source code version system. \subsection sec_sfa_cvsinstall Installation The TortoiseCVS site is <a href="http://www.tortoisecvs.org/">here</a>. The standard download file attempts to perform the installation interactively against the TortoiseCVS website, and will not work because of the firewall, so instead you need to use the TortoiseCVS Windows Installer (.msi file) which is a standalone local installation. The .msi installer (<tt>TortoiseCVS-1.8.25.msi</tt>) is available <a href="http://sourceforge.net/project/showfiles.php?group_id=142108">here</a>. \subsection sec_sfa_configuration Configuration In order to configure TortoiseCVS you need to \li create a configuration file <tt>.cvsrc</tt> in your TortoiseCVS home directory \li execute a login command to establish your connection to the server First you need to identify the location of your TortoiseCVS home directory. TortoiseCVS determines the home directory by concatenating the environment variables <tt>HOMEDRIVE</tt> and <tt>HOMEPATH</tt>. On my machine the TortoiseCVS home directory is <tt>N:\\</tt>. In the TortoiseCVS home directory, create a file called <tt>.cvsrc</tt> with the following contents (all on one line): \code cvs -d:pserver;proxy=XXX; proxyport=3128;proxyuser=XXX;proxypassword=XXX: ano...@cv...:443/cvsroot/quantlib \endcode In the string above you need to overwrite XXX with the servername, username and password that you use to connect to the proxy web server. Now you need to execute the login command. This needs to be done once only to cache information relating to your CVS connection. Execute the following command at the DOS prompt: <tt> "C:\Program Files\TortoiseCVS\cvs.exe" login </tt> When prompted for a password, hit enter. If a popup window appears prompting you for a password a second time, just leave the password field blank and click OK. \subsection sec_sfa_checkout Usage Set aside an area of your hard drive where you will keep your local copy of QuantLib. Right click on the folder and launch "CVS Checkout". <img src="images/tortoise_checkout.jpg"> Configure Tortoise as shown and click OK: <img src="images/tortoise_anonymous_configure.jpg"> TortoiseCVS installs the QuantLib source code tree to your hard drive. Repeat the procedure for ObjectHandler and QuantLibAddin. You're now ready to proceed with building QuantLib. */ --- NEW FILE: build.quantlib.docs --- /*! \page build_quantlib Building QuantLib This document explains how to build QuantLib (including ObjectHandler and QuantLibAddin). Each step is documented in detail: \ref sec_ql_python \n \ref sec_ql_boost \n \ref sec_ql_runtime \n \ref sec_ql_naming \n \ref sec_ql_quantlib \n \ref sec_ql_quantlibtestsuite \n \ref sec_ql_quantlibfunctions \n \ref sec_ql_log4cxx \n \ref sec_ql_objecthandler \n \ref sec_ql_quantlibaddin \n \ref sec_ql_usage \n \ref sec_ql_links \n \section sec_ql_python Install Python Both Boost and srcgen (described below) require you to have Python installed on your machine. Please go to the <a href="http://www.python.org/">python website</a> and download and install Python. \section sec_ql_boost Install and Build Boost QuantLib depends on the Boost library. Procedures for downloading and installing Boost may be found at: <a href="http://www.boost.org/more/getting_started.html">http://www.boost.org/more/getting_started.html</a>. Below is a brief summary of the procedure, assuming the use of the VC8 compiler: \li Download Boost from <a href="www.boost.org">www.boost.org</a>: get the latest version of the \c boost package and the ntx86 binary version of the \c boost-jam package (<tt>boost_1_33_1.exe</tt> and <tt>boost-jam-3.1.12-1-ntx86.zip</tt> respectively at the time of this writing). \li Run <tt>boost_1_33_1.exe</tt> and it will extract files to a folder of your choice (for this example it's assumed to be <tt>C:\\Projects</tt>) creating a boost_1_33_1 subfolder. Yor Boost top level dir will be <tt>C:\\Projects\\boost_1_33_1</tt>. \li Now unzip <tt>boost-jam-3.1.12-1-ntx86.zip</tt> and copy the extracted <tt>bjam.exe</tt> file into <tt>C:\\Projects\\boost_1_33_1</tt>. \li From the Start menu access <tt>Programs | Microsoft Visual Studio 2005 | Microsoft Visual Studio 2005 Command Prompt</tt>. Change the directory, selecting your Boost top level directory <tt>C:\\Projects\\boost_1_33_1</tt> \li run the command: \code C:\\Projects\\boost_1_33_1>bjam "-sTOOLS=vc-8_0" install \endcode This command will create the Boost include directory <tt>C:\\Boost\\include\\boost-1_33_1</tt> and the Boost library directory <tt>C:\\Boost\\lib</tt>. Relax: it takes a long while. \li You need to configure VC8 with the location of the Boost header files. Under <tt>Tools/Options/Projects and Solutions/VC++ Directories</tt>, select Include files and specify the path to the top level directory containing the Boost header files <tt>C:\\Boost\\include\\boost-1_33_1</tt>: <img src="images/boost_include_path.jpg"> \li You need to configure VC8 with the location of the Boost lib files. Under <tt>Tools/Options/Projects and Solutions/VC++ Directories</tt>, select Library files and specify the path to the top level directory containing the Boost lib files <tt>C:\\Boost\\lib</tt>: <img src="images/boost_lib_path.jpg"> \section sec_ql_runtime A Note on Runtime Libraries You are now ready to build QuantLib. You need to compile the following projects: - <a href="http://quantlib.org/">QuantLib</a> - the core C++ analytics library - log4cxx - a logging framework, used by ObjectHandler - <a href="http://quantlib.org/objecthandler/">ObjectHandler</a> - an object repository - <a href="http://quantlib.org/quantlibaddin/">QuantLibAddin</a> - an Excel Addin for QuantLib These projects are available with four different runtime libraries (configurations): Debug, Debug CRTDLL, Release, and Release CRTDLL. The Debug and Release configurations are statically linked to the Microsoft C Runtime environment. The CRTDLL configurations are dynamically linked, meaning that your executable will have a run-time dependency on the Microsoft C Runtime DLLs. All four of the above projects must be built with the same runtime library. This example assumes the use of configuration <b>Release</b>. \section sec_ql_naming A Note on VC Workspace Naming Conventions QuantLib uses the following conventions for naming VC workspaces: <table> <tr><td><b>VC version</b></td><td><b>Workspace Name</b></td></tr> <tr><td>6</td><td>xxx.dsp</td></tr> <tr><td>7</td><td>xxx.sln</td></tr> <tr><td>8</td><td>xxx_vc8.sln</td></tr> </table> As you're using VC8 be sure to open the workspaces named with the <b>_vc8.sln</b> suffix. \section sec_ql_quantlib Install and Build QuantLib Previously you used TortoiseCVS to download the QuantLib source code to your hard drive. Included in the download is the QuantLib VC8 workspace file <tt>QuantLib_vc8.sln</tt>. This file resides in the top level QuantLib directory. Launch VC8 and load the QuantLib project. Ensure that runtime library <tt>Release</tt> is selected, highlight the <tt>QuantLib</tt> project, and select <tt>Build/Build QuantLib</tt>: <img src="images/ql_build.jpg"> The build process creates file <tt>QuantLib\\lib\\QuantLib-vc80-mt-s-0_3_13.lib</tt>. Create environment variable <tt>QL_DIR</tt> and set it equal to the path to the top-level QuantLib directory. The compilation of QuantLibAddin will rely on the value of <tt>QL_DIR</tt> in order to locate the QuantLib headers and lib file. In other words the QuantLibAddin compilation will expect to find - QuantLib header files in directory <tt>\$(QL_DIR)\\include</tt> - QuantLib lib file <tt>QuantLib-vc80-mt-s-0_3_13.lib</tt> in directory <tt>\$(QL_DIR)\\lib</tt> \section sec_ql_quantlibtestsuite Run the QuantLib Testsuite It's a good idea to verify the status of the QuantLib library by compiling the testsuite. This will run the testsuite executable automatically (should take less than half an hour in Release configuration, few hours in Debug) and report something like: \code 1>Auto run test 1>===================================== 1>Testing QuantLib-vc80-mt-s-0_3_13.lib 1>===================================== 1>Running moreThan200 test cases... 1>Platform: Win32 1>Compiler: Microsoft Visual C++ version 8.0 1>STL : Dinkumware standard library version 405 1>Boost : 1.33.1 1>Testing Barone-Adesi and Whaley approximation for American options... [...] 1>Testing old-style Monte Carlo multi-factor pricers... 1> 1>Tests completed in XX m 1>Test suite "QuantLib test suite" passed with: 1> moreThan200 assertions out of moreThan200 passed 1> moreThan200 test cases out of moreThan200 passed 1>Build log was saved at 1>"file://c:\Projects\QuantLib\test-suite\build\vc80\Release\BuildLog.htm" 1>testsuite - 0 error(s), 0 warning(s) \endcode \section sec_ql_quantlibfunctions Build QuantLibFunctions Still in the QuantLib workspace, under configuration <tt>Release</tt>, choose solution <tt>QuantLibFunctions</tt>, and do <tt>Build/Build QuantLibFunctions</tt>. The build process creates file <tt>QuantLib\\lib\\QuantLibFunctions-vc80-mt-s-0_3_13.lib</tt>. \section sec_ql_log4cxx Install and Build log4cxx Next you need to build log4cxx, the logging framework used by ObjectHandler. log4cxx is not included in the CVS source tree that you downloaded with TortoiseCVS, you need to download log4cxx from the QuantLib website. Go to the <a href="http://sourceforge.net/project/showfiles.php?group_id=12740">QuantLib downloads page</a>, and under the ObjectHandler section, get file <tt>log4cxx-0.9.7.zip</tt> and unzip it to your hard drive. In VC8, open the log4cxx VC8 workspace <tt>log4cxx-0.9.7\\msvc\\log4cxx_vc8.sln</tt>. Choose configuration <tt>Release</tt>, solution <tt>static</tt>, and do <tt>Build/Build Static</tt>. The build process creates file <tt>log4cxx-0.9.7\\msvc\\lib\\log4cxxs-vc80-mt-s.lib</tt>. Create environment variable <tt>LOG4CXX_DIR</tt> and set it equal to the path to the top-level log4cxx directory. \section sec_ql_objecthandler Install and Build ObjectHandler In VC8, open the ObjectHandler VC8 workspace <tt>ObjectHandler\\ObjectHandler_vc8.sln</tt>. Choose configuration <tt>Release</tt>, solution <tt>ohxllib</tt>, and do <tt>Build/Build ohxllib</tt>. The build process creates file <tt>ObjectHandler\\ohxl\\ohxllib\\lib\\ObjectHandler-vc80-mt-s-0_1_4.lib</tt>. Create environment variable <tt>OBJECT_HANDLER_DIR</tt> and set it equal to the path to the top-level ObjectHandler directory. \section sec_ql_quantlibaddin Install and Build QuantLibAddin Before building QuantLibAddin you must first generate the QuantLibAddin source code. In VC8, open the QuantLibAddin VC8 workspace <tt>QuantLibAddin\\QuantLibAddin_vc8.sln</tt>. Choose configuration <tt>All</tt>, solution <tt>srcgen</tt>, and do <tt>Build/Build srcgen</tt>. The build process outputs source code files to the QuantLibAddin directory tree. Now choose configuration <tt>Release</tt>, solution <tt>AddinExcelStatic</tt>, and do <tt>Build/Build AddinExcelStatic</tt>. The build process creates the QuantLibAddin XLL file <tt>QuantLibAddin\\Addins\\Excel\\xll\\QuantLibAddinStatic-vc80-mt-s-0_3_13.xll</tt>. \section sec_ql_usage Usage To launch the QuantLibAddin Excel addin: - start Excel - load the addin <tt>QuantLibAddin\\Addins\\Excel\\xll\\QuantLibAddinStatic-vc80-mt-s-0_3_13.xll</tt> - load a sample spreadsheet e.g. <tt>QuantLibAddin\\Clients\\Excel\\QLADemo.xls</tt> - hit <tt>Ctrl-Alt-F9</tt> to force a recalculation of all formulas If you want to have the QuantLibAddin XLL loaded every time you start Excel, you can accomplish this as follows: \li start Excel \li ensure that at least one workbook is loaded - creating a new empty workbook if necessary \li do <tt>Tools/Add-Ins</tt>, and click the Browse button \li browse your way to the QuantLibAddin XLL and click OK \section sec_ql_links Links For further information please consult the following links: - <a href="http://quantlib.org/">QuantLib home page</a> - <a href="http://quantlib.org/reference/faq.html">general QuantLib FAQ</a> - <a href="http://quantlib.org/developerFAQ.shtml">QuantLib developer FAQ</a> - <a href="http://quantlib.org/objecthandler">ObjectHandler home page</a> - <a href="http://quantlib.org/quantlibaddin">QuantLibAddin home page</a> - <a href="http://quantlib.org/quantlibaddin/faq.html">QuantLibAddin FAQ</a> */ --- NEW FILE: build.vc.docs --- /*! \page build_vc Visual C++ This page explains how to install Visual C++ (also known as VC8 - a component of Microsoft Visual Studio 2005 Professional Edition). \section sec_vc_xpsp2 Windows XP Service Pack 2 A prerequisite for VC8 is Windows XP Service Pack 2, the disk (Italian or English) is included in the Visual Studio pack. Run the installation for XP SP2 and reboot. \section sec_vc_vc8 VC8 >From the disk launch <tt>D:\\VS\\SETUP.EXE</tt>, when prompted to choose <tt>default/full/custom</tt> installation, choose custom, and configure the next screen as shown: <img src="images/VC8_custom.jpg"> */ |
