# Installing the build tools

1. Get the cms build tools from the infrastructure SVN repository. These scripts will generate HTML from markdown files (among other things).  
    svn co https://svn.apache.org/repos/infra/websites/cms/build ~/cms/build

2. Read the instructions at http://www.apache.org/dev/cmsref.html#local-build

3. No, seriously, read the instructions. 

4. OK here's my version : 
    * The tools work on Ubuntu (and presumably any debian system). They should also work on Windows, but after some initial headaches, I gave up. YMMV. 
    * You'll need Python and Perl installed. 
    * For Python install : 
        * [setuptools] (http://pypi.python.org/pypi/setuptools)
        * pygments
        * ElementTree
        * Markdown
    * For Perl install :
        * XML::Atom::Feed
        * XML::RSS::Parser::Lite
        * XML::Parser::Lite
        * YAML
        * SVN::Client

    * I've included a shell script that should skip the next step. Edit ../openjpa/site/trunk/start_markdown.sh and change CMS_BUILD_PATH to point to the directory where you checked out the CMS tools.  Then run start_markdown.sh this will start the markdown daemon for you.  Skip the next bullet if this works for you. 

    * Now go to the directory where you checked out the build tools and run 
            export MARKDOWN_SOCKET=`pwd`/markdown.socket PYTHONPATH=`pwd`export 
            python markdownd.py

        This will start the markdown daemon process. 

    * Edit .../openjpa/site/trunk/build.sh to set the environment variables to match your environment, or manually run 
        build_site.pl --source-base ${path to site/trunk} --target-base ${path to site/trunk/target} 

    * If the markdown daemon process isn't running you'll get errors like this. 
        File content/openjpa-logo-contest---run-off.mdtext had processing errors: Error while rendering output to string
        Filter 'markdown' couldn't be found or an error occurred. The filter has to be in the Dotiac::DTL::Filter namespace
        Can't open markdown socket: No such file or directory at /home/mikedd/cms/cms/build/lib/Dotiac/DTL/Addon/markup.pm line 56

    * Now if you look at the target directory, you should see .html files for each page. 

    * edit the mdtext files, and repeat the build as needed. 


5. Here is the RedHat version of the install
    * Make sure you have Python 2.7.+ version install.
      * You will need 'a' version of Python to start off with. E.g. Python 2.4.*  
      * Go http://www.python.org/getit/ and download the "
          "Python 2.7.3 bzipped source tarball (for Linux, Unix or Mac OS X, more compressed)"
      * Unzip to a folder; follow the instructions in README. Basically
         * ./configure
         * make
         * make install

    * For Python install : 
        * [setuptools] (http://pypi.python.org/pypi/setuptools)
           $ sh setuptools-0.6c11-py2.7.egg
           $ sudo easy_install Pygments
           $ sudo easy_install ElementTree
           $ sudo easy_install Markdown

    * For Perl install :
           $ cpan XML::Atom::Feed
              *NOTE*
                Are you ready for manual configuration? [yes] no<cr>
                Shall I follow them and prepend them to the queue of modules we are processing right now? [yes] <cr>
              
              *NOTE* This install may fail with some component test failure. I rerun the install again and it get by.
                "Couldn't chdir /root/.cpan/build/DateTime-TimeZone-1.54: No such file or directory at /usr/lib/perl5/5.8.8/CPAN.pm line 2137"
           $ cpan XML::RSS::Parser::Lite
           $ cpan XML::Parser::Lite
           $ cpan YAML
           $ cpan SVN::Client  

    * Edit ../openjpa/site/trunk/start_markdown.sh and change CMS_BUILD_PATH to point to the directory where you checked out the CMS tools.
           $ $CMS_BUILD_PATH/start_markdown.sh
         This will start the MarkDown server in the background.
         
    * Edit ../openjpa/site/trunk/build.sh to set the environment variables to match your environment.
           i.e. CMS_BUILD_PATH, SOURCE and TARGET 

    * Run build.sh to convert *.mdtext to *.html in $TARGET
       The OpenJPA home page is in 
          $TARGET/content/index.html
    * Repeat the last step after make any changes to *.mdtext.

6. Set up Eclipse for the build
    * Start Eclipse in a new workspace (e.g. /root/tc/site)
    * Check out site/trunk content to workspace into project trunk
      E.g. svn co https://svn.apache.org/repos/asf/openjpa/site/trunk /root/tc/site/trunk
    * Select project trunk -> properties -> Java Build Path
      * change "Default output folder" from trunk/bin to trunk/target
    * Select project trunk -> properties -> Builders -> New -> Program -> Main
      * Name -> CMS_Builder
      * Location -> ${workspace_loc:/trunk/bld.oj.cms.sh}
      * Working Directory -> ${workspace_loc:/trunk}
    * Select project trunk -> properties -> Builders -> New -> Program -> Environment
      * Add CMS_BUILD_PATH = /root/cms/build
      * Add SOURCE = ${workspace_loc}/trunk
    * Select project trunk -> properties -> Builders -> New -> Program -> Build Options
      * Check "Specify working set for relevant resources" and select "Specifying Resources" to include only trunk/content
      
    * Before you can run the build, you need to run site/trunk/start_markdown.sh once to start the markdown daemon.
    
    * Now you can edit trunk/content/**/*.mdtext. To build, Ctrl-B or Project -> Build All, the
      new content can be found in trunk/target/content/**/*.html.