# ***********************************************
# 
# !!!! DO NOT EDIT !!!!
# 
# This file was auto-generated by Build.PL.
# 
# ***********************************************
# 
# Licensed to the Apache Software Foundation (ASF) under one or more
# contributor license agreements.  See the NOTICE file distributed with
# this work for additional information regarding copyright ownership.
# The ASF licenses this file to You 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.

=encoding utf8

=head1 NAME

Clownfish::Docs::BuildingProjects - Building Apache Clownfish projects in C environments

=head1 DESCRIPTION

The following steps are required to build a project that uses
Apache Clownfish:

=over

=item *

Run the C<cfc> command-line application (Clownfish compiler) to
generate C headers, C source files, and documentation.

=item *

Include the C headers generated by the Clownfish compiler in your
own code to L<work with Clownfish objects|Clownfish::Docs::ClassIntro>.

=item *

Compile an additional C source file generated by CFC.

=item *

Link your object code, the object code from the generated file,
and the Clownfish runtime library.

=back

=head2 Running cfc

    cfc [--source=<dir>] [--include=<dir>] [--parcel=<name>]
        --dest=<dir>
        [--header=<file>] [--footer=<file>]

=head3 –source

Every C<--source> argument adds a directory to the list of source
directories to search for source parcels. For every source parcel
found, CFC generates C headers, a C source file, and documentation.

The source directories are scanned for Clownfish parcel definitions
(C<.cfp>), Clownfish headers (C<.cfh>), and standalone documentation
in Markdown format (C<.md>).

This option may be specified multiple times.

=head3 –include

Every C<--include> argument adds a directory to the list of include
directories. CFC generates C headers for parcels from an include
directory only if they’re required by a source parcel or if they’re
specified with the C<--parcel> option. Only C headers are generated
for included parcels, no C source code or documentation.

The include directories are scanned for Clownfish parcel
definitions (C<.cfp>) and Clownfish headers (C<.cfh>).

After the directories specified on the command-line, the following
directories are processed:

=over

=item *

Directories from the environment variable C<CLOWNFISH_INCLUDE>.
This variable contains a colon-separated list of directories.

=item *

On UNIX-like systems C</usr/local/share/clownfish/include> and
C</usr/share/clownfish/include>.

=back

This option may be specified multiple times.

=head3 –parcel

Adds a parcel to the list of prerequisite parcels to make sure that
its C headers are generated. This is useful when running without the
C<--source> option. For example, a project that doesn’t define its
own Clownfish classes can generate the C headers for the Clownfish
runtime with:

    cfc --parcel=Clownfish --dest=autogen

This option may be specified multiple times.

=head3 –dest

The destination directory for generated files. By convention,
the name C<autogen> is used.

CFC creates the following subdirectories in the destination
directory:

=over

=item *

C<include> contains generated C headers.

=item *

C<sources> contains generated C source files.

=item *

C<man> contains generated man pages.

=item *

C<share/doc/clownfish> contains generated HTML documentation.

=back

This option is required.

=head3 –header

Specifies a file whose contents are added as a comment on top of
each generated file.

=head3 –footer

Specifies a file whose contents are added as a comment on the
bottom of each generated file.

=head2 Including the generated C headers

The C header files generated with C<cfc> can be found in
C<autogen/include>. You should add this directory to your compiler’s
search path, for example using C<-Iautogen/include> under GCC.

One C header file is generated for every Clownfish header (.cfh) file.
C code that makes use of a class defined in the .cfh file must include
the respective C header. The Clownfish compiler also creates a few
other internal C header files.

=head2 Compiling the generated source files

C<cfc> creates one source file for every parcel in
C<autogen/sources/{parcel_nick}_parcel.c>. These files must be
compiled with C<autogen/include> added to the header search path.

=head2 Linking

When linking, add the object files of the CFC-generated code created
in the previous step. You must also link the shared library of the
Clownfish runtime (C<-lclownfish> under GCC).

