maven-plugins/cruisecontrol/xdocs/faq.fml

<?xml version="1.0" encoding="ISO-8859-1"?>

<!--
/*
 * Copyright 2001-2005 The Apache Software Foundation.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
 -->

<!-- $Id: faq.fml,v 1.7 2004/05/05 07:34:38 brett Exp $ -->
<faqs title="Frequently Asked Questions">

  <part id="General">
    <title>General</title>

    <faq id="change-template">
      <question>How do I change the template used to generate <code>cruisecontrol.xml</code> configuration file?</question>
      <answer>
        If you specify your own <code>maven.cruisecontrol.template</code>, then that will be used
        instead.  If you want to wrap all of your logic up in your own plugin so that
        you don't have to set each project individually, then add this goal to your plugin's
        plugin.jelly file:
<source><![CDATA[
<preGoal name="cruisecontrol:configure">
	<maven:set plugin="maven-cruisecontrol-plugin" 
			property="maven.cruisecontrol.template"
        	value="${plugin.resources}/custom_cruisecontrol.jsl"/>
</preGoal>]]></source>
      </answer>
    </faq>

    <faq id="pass-in-values">
      <question>How do I pass in my own values in my cruisecontrol.jsl?</question>
      <answer>
        Just setup in your project or plugin your own properties like: myplugin.cruisecontrol.mailhost=localhost
        and then just use <code>mailhost=${myplugin.cruisecontrol.mailhost}</code> in your cruisecontrol.jsl!
      </answer>
    </faq>

    <faq id="crossplatform">
      <question>I am running Cruise on both a Linux and Window's boxes, how can I be crossplatform?</question>
      <answer>
        I specified it like this in my own plugin, this would work in your maven.xml as well:
        <p>
          <source><![CDATA[
<preGoal name="cruisecontrol:validate">
  <ant:echo message="Generating CruiseControl configuration for ${systemScope['os.name']} platform. "/>
  <j:choose>
    <j:when test="${systemScope['os.name'].startsWith('Windows')}">
      <ant:property name="maven.cruisecontrol.home" value="${anite.cruisecontrol.windows.home}"/>
      <ant:property name="anite.cruisecontrol.mavenscript" value="${myplugin.cruisecontrol.windows.mavenscript}"/>
    </j:when>
    <j:otherwise>
      <ant:property name="maven.cruisecontrol.home" value="${myplugin.cruisecontrol.linux.home}"/>
      <ant:property name="myplugin.cruisecontrol.mavenscript" value="${myplugin.cruisecontrol.linux.mavenscript}"/>
    </j:otherwise>
  </j:choose>
  <ant:echo message="maven.cruisecontrol.template:${maven.cruisecontrol.template}"/>
</preGoal>]]></source>
        </p>
      </answer>
    </faq>

    <faq id="setup">
      <question>
        How do I setup my project to be built using Cruise Control?
      </question>
      <answer>
        <ul>
          <li>Install Cruise Control.  Preferably on a different machine.</li>
          <li>
            Checkout the project into the 
            <code>${maven.cruisecontrol.checkout.dir}</code>.  The checkout 
            should be done as the same user defined in project.xml.  This is 
            because the SCM plugin <strong>must</strong> be able to keep the
            project in sync with the repository.
          </li>
          <li>
            Using Maven and the cruisecontrol plugin, update the CruiseControl
            configuration file.
          </li>
          <li>Restart CruiseControl</li>
        </ul>
      </answer>
    </faq>

    <faq id="whenToRebuild">
      <question>
        How often should I update the CruiseControl configuration file?
      </question>
      <answer>
        Since there is limited information in the file, not very often.  You
        should regenerate the file when:
        <ul>
          <li>Source repository configuration changes</li>
          <li>Developer email address changes</li>
          <li>Directories on used by Cruise Control change, i.e. the logs
              directory
          </li>
          <li>Project goals change</li>
          <li>List of dependent project change</li>
        </ul>
      </answer>
    </faq>

    <faq id="editConfigFile">
      <question>
        Do I need to edit the CruiseControl configuration file?
      </question>
        By default no, since much of the information in the file originates
        in properties and project.xml.  For changes that affect the generation
        of the project or projects, you may want to create you own template. 
        If you have dependencies defined, then you need to ensure the order 
        of the projects in the file corresponds with the order the project
        should be built.
      <answer>
      </answer>
    </faq>

  </part>

  <part id="Multiprojects">
    <title>Multiprojects</title>

    <faq id="multiple-projects">
      <question>How can I generate just a single configuration file for multiple projects?</question>
      <answer>
        A neat trick of the cruisecontrol plugin is that if you specify a single configuration 
        file for all your projects, then the plugin will just install/update the one your are
        working on. 
        However the cruisecontrol plugin does not currently support having one CC project 
        definitions per Maven subproject. The currently recommended solution is to have one CC 
        project for your multiproject (i.e. viewing the multiproject project as one project only).
      </answer>
    </faq>
    
  </part>

</faqs>