Clownf...rojects(3pm)

🎀 NAME 🎀

Clownfish::Docs::BuildingProjects — it's giving building Clownfish projects in C environments, bestie 💖

---

✨ DESCRIPTION ✨

Okay so listen, bestie — if you wanna build a project that uses Clownfish, there's a lil checklist and you gotta do all of it, no skipping steps 🙈 Here's the vibe:

• Run the cfc command-line application (that's the Clownfish compiler, slay) to generate C headers, C source files, and documentation. ✨
• Include the C headers generated by the Clownfish compiler in your own code so you can actually work with Clownfish objects 🫶
• Compile an additional C source file generated by CFC. Yes, additional. It's part of the package, trust.
• Link your object code, the object code from the generated file, and the Clownfish runtime library. All three. Periodt. 💅

---

🦋 Running cfc 🦋

Here's the whole shape of the command, so you know what we're working with:

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

Now let's break down every single flag, because they all matter, no cap:

• --source — every --source argument adds a directory to the list of source directories to search for source parcels 👑 For every source parcel it finds, CFC generates C headers, a C source file, and documentation.

The source directories get scanned for Clownfish parcel definitions (.cfp), Clownfish headers (.cfh), and standalone documentation in Markdown format (.md). Iconic little trio tbh.

This option may be specified multiple times 💖

• --include — every --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 --parcel option. And heads up bestie: only C headers get generated for included parcels — no C source code, no documentation. That's just how it is 🫠

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

After the directories you specified on the command-line, these directories get processed too:

• Directories from the environment variable CLOWNFISH_INCLUDE. This variable contains a colon-separated list of directories.
• On UNIX-like systems, /usr/local/share/clownfish/include and /usr/share/clownfish/include.

This option may be specified multiple times 💜

• --parcel — adds a parcel to the list of prerequisite parcels, so you can make sure its C headers get generated. This is the move when you're running without the --source option, fr fr. 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 🌸

• --dest — the destination directory for generated files. By convention, the name autogen is used.

CFC creates these subdirectories inside the destination directory:

• include contains generated C headers.
• sources contains generated C source files.
• man contains generated man pages.
• share/doc/clownfish contains generated HTML documentation.

This option is required. Not optional. Not "we'll figure it out later." Required. 😭

• --header — specifies a file whose contents are added as a comment on top of each generated file 🎀
• --footer — specifies a file whose contents are added as a comment on the bottom of each generated file 🎀

---

🌈 Including the generated C headers 🌈

The C header files generated with cfc live in autogen/include. You should add this directory to your compiler's search path — for example using -Iautogen/include under GCC. Easy. Cute. Done. ✨

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 — that's not a suggestion, that's the law 💅 The Clownfish compiler also creates a few other internal C header files, because it's extra like that.

---

🧚 Compiling the generated source files 🧚

cfc creates one source file for every parcel in autogen/sources/{parcel_nick}_parcel.c ⭐

These files must be compiled with autogen/include added to the header search path. Don't forget it or the compiler will simply choose violence 😭

---

💀 Linking 💀

When linking, add the object files of the CFC-generated code you created in the previous step. You must also link the shared library of the Clownfish runtime — that's -lclownfish under GCC 👑

---

That's the whole thing, bestie — go build something iconic 🦋💖

This lil page is perl v5.42.3, dated 2026-09-02, and it's part of the User Contributed Perl Documentation — 3pm girlies, we ride at dawn 💅✨