{namespace project_config}

/***/
{template .soyweb}
  {call buck.page}
    {param title: 'project_config()' /}
    {param prettify: true /}
    {param content}

{call buck.rule}
{param overview}
A <code>project_config()</code> rule is used to specify the information needed
to generate the configuration files for an IDE so the primary build target 
(and optionally its tests) of a BUCK file can be built using that IDE.

<p>Note that there may only be one <code>project_config()</code> rule per 
BUCK file.</p>
{/param}

{param args}

{call buck.arg}
  {param name: 'src_target' /}
  {param desc}
  A build rule that will serve as the basis of the generated project. 
  Currently, it must be one of: <code>java_library()</code>, 
  {sp}<code>java_test()</code>, <code>android_library()</code>, or 
  {sp}<code>android_binary()</code>. The generated IDE project will be of a 
  type that corresponds to the type of the rule.

  <p>Also, the <code>deps</code> of this rule will determine the other IDE 
  projects on which the IDE project for this rule depends. 
  Note that this is a heuristic, but it appears to work reasonably well, 
  in practice.</p>
  {/param}
{/call}

{call buck.arg}
  {param name : 'src_roots' /}
  {param default : '[]' /}
  {param desc}
  The root directories of the source code that correspond to 
  {sp}<code>src_target</code>. 
  Values may include:
  <ul>
    <li>
      <code>None</code> There are no source roots. This could happen if 
      {sp}<code>src_target</code> identifies an Android library project that 
      is purely resources and no Java code.
    </li>
    <li>
      <code>[]</code> The directory that contains the build file is a Java 
      package. In this case, the root of the package must be one of the 
      ancestor directories. 
      Buck can deduce where the root of the package is by using the 
      {sp}<code>src_roots</code> property in the <code>[java]</code> section 
      of the <code>.buckconfig</code>.
    </li>
    <li>
      <code>['src']</code>  The <code>src</code> directory under the build file 
      directory is a source root. This list may contain multiple elements, but 
      in practice, it should almost always contain at most one element. 
      This option supports a list to allow generated source code to be checked in
      alongside the hand-written source of imported projects. 
      In this case, <code>src_roots</code> would be
      {sp}<code>['src', 'src-gen']</code>.
    </li>
  </ul>
  {/param}
{/call}

{call buck.arg}
  {param name : 'test_target' /}
  {param default : 'None' /}
  {param desc}
  If specified, a complementary tests project for <code>src_target</code>. 
  In IntelliJ, source and test code can be grouped together in the same module 
  while having different classpaths. 
  In Eclipse, source and test code are often in separate projects because they 
  need to have different classpaths.
  {/param}
{/call}

{call buck.arg}
  {param name : 'test_roots' /}
  {param default : '[]' /}
  {param desc}
  Same as <code>src_roots</code>, but for <code>test_target</code>.
  {/param}
{/call}

{/param} // close args

{param examples}

{literal}<pre class="prettyprint lang-py">
project_config(
  src_target = ':lib-base',
  src_roots = [ 'src' ],
  test_target = ':tests',
  test_root = 'tests',
)
</pre>{/literal}
{/param}

{/call} // close buck.rule

    {/param}
  {/call}
{/template}