1Clownfish::Docs::BuildiUnsgePrroCjoencttrsi(b3u)ted PerlClDoowcnufmiesnht:a:tDioocns::BuildingProjects(3)
2
3
4

NAME

6       Clownfish::Docs::BuildingProjects - Building Apache Clownfish projects
7       in C environments
8

DESCRIPTION

10       The following steps are required to build a project that uses Apache
11       Clownfish:
12
13       •   Run the "cfc" command-line application (Clownfish compiler) to
14           generate C headers, C source files, and documentation.
15
16       •   Include the C headers generated by the Clownfish compiler in your
17           own code to work with Clownfish objects.
18
19       •   Compile an additional C source file generated by CFC.
20
21       •   Link your object code, the object code from the generated file, and
22           the Clownfish runtime library.
23
24   Running cfc
25           cfc [--source=<dir>] [--include=<dir>] [--parcel=<name>]
26               --dest=<dir>
27               [--header=<file>] [--footer=<file>]
28
29       –source
30
31       Every "--source" argument adds a directory to the list of source
32       directories to search for source parcels. For every source parcel
33       found, CFC generates C headers, a C source file, and documentation.
34
35       The source directories are scanned for Clownfish parcel definitions
36       (".cfp"), Clownfish headers (".cfh"), and standalone documentation in
37       Markdown format (".md").
38
39       This option may be specified multiple times.
40
41       –include
42
43       Every "--include" argument adds a directory to the list of include
44       directories. CFC generates C headers for parcels from an include
45       directory only if they’re required by a source parcel or if they’re
46       specified with the "--parcel" option. Only C headers are generated for
47       included parcels, no C source code or documentation.
48
49       The include directories are scanned for Clownfish parcel definitions
50       (".cfp") and Clownfish headers (".cfh").
51
52       After the directories specified on the command-line, the following
53       directories are processed:
54
55       •   Directories from the environment variable "CLOWNFISH_INCLUDE".
56           This variable contains a colon-separated list of directories.
57
58       •   On UNIX-like systems "/usr/local/share/clownfish/include" and
59           "/usr/share/clownfish/include".
60
61       This option may be specified multiple times.
62
63       –parcel
64
65       Adds a parcel to the list of prerequisite parcels to make sure that its
66       C headers are generated. This is useful when running without the
67       "--source" option. For example, a project that doesn’t define its own
68       Clownfish classes can generate the C headers for the Clownfish runtime
69       with:
70
71           cfc --parcel=Clownfish --dest=autogen
72
73       This option may be specified multiple times.
74
75       –dest
76
77       The destination directory for generated files. By convention, the name
78       "autogen" is used.
79
80       CFC creates the following subdirectories in the destination directory:
81
82       •   "include" contains generated C headers.
83
84       •   "sources" contains generated C source files.
85
86       •   "man" contains generated man pages.
87
88       •   "share/doc/clownfish" contains generated HTML documentation.
89
90       This option is required.
91
92       –header
93
94       Specifies a file whose contents are added as a comment on top of each
95       generated file.
96
97       –footer
98
99       Specifies a file whose contents are added as a comment on the bottom of
100       each generated file.
101
102   Including the generated C headers
103       The C header files generated with "cfc" can be found in
104       "autogen/include". You should add this directory to your compiler’s
105       search path, for example using "-Iautogen/include" under GCC.
106
107       One C header file is generated for every Clownfish header (.cfh) file.
108       C code that makes use of a class defined in the .cfh file must include
109       the respective C header. The Clownfish compiler also creates a few
110       other internal C header files.
111
112   Compiling the generated source files
113       "cfc" creates one source file for every parcel in
114       "autogen/sources/{parcel_nick}_parcel.c". These files must be compiled
115       with "autogen/include" added to the header search path.
116
117   Linking
118       When linking, add the object files of the CFC-generated code created in
119       the previous step. You must also link the shared library of the
120       Clownfish runtime ("-lclownfish" under GCC).
121
122
123
124perl v5.36.0                      2023-01-2C0lownfish::Docs::BuildingProjects(3)