.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "CCCONFIG 1p"
.TH CCCONFIG 1p 2024-03-07 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
ccconfig \- Get Convert::Binary::C configuration for a compiler
.SH SYNOPSIS
.IX Header "SYNOPSIS"
ccconfig \fIoptions\fR [\-\- compiler\-options]
.PP
\&\fIoptions\fR:
.PP
.Vb 3
\&  \-c
\&  \-\-cc             compiler   compiler executable to test
\&                              default: auto\-determined
\&  
\&  \-o
\&  \-\-output\-file    file       output filename
\&                              default: output to stdout
\&
\&  \-f
\&  \-\-output\-format  format     output format
\&                              default: dumper
\&
\&  \-\-basename       name       basename of the temporary test files
\&                              default: _t_e_s_t
\&
\&  \-I
\&  \-\-inc\-path       path       manually set compiler include path
\&
\&  \-\-preprocess     rule       compiler rule for preprocessing
\&  \-\-compile\-obj    rule       compiler rule for compiling objects
\&  \-\-compile\-exe    rule       compiler rule for compiling executables
\&
\&  \-\-c\-ext          ext        extension of C source files
\&  \-\-pp\-ext         ext        extension of preprocessor output files
\&  \-\-obj\-ext        ext        extension of object files
\&  \-\-exe\-ext        ext        extension of executable files
\&
\&  \-\-nodelete                  don\*(Aqt delete temporary files
\&  \-\-norun                     don\*(Aqt try to run executables
\&  \-\-quiet                     don\*(Aqt display anything
\&  \-\-nostatus                  don\*(Aqt display status indicator
\&  
\&  \-\-version                   print version number
\&  
\&  \-\-debug                     debug mode
.Ve
.PP
Placeholders allowed in compiler rules:
.PP
.Vb 5
\&  %c    C source file
\&  %o    object file
\&  %e    executable file
\&  %i    preprocessor output file
\&  |     result is written to stdout (only at end of rule)
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
\&\f(CW\*(C`ccconfig\*(C'\fR will try to determine a usable configuration for
Convert::Binary::C from testing a compiler executable. It is not
necessary that the binaries generated by the compiler can be
executed, so \f(CW\*(C`ccconfig\*(C'\fR can also be used for cross-compilers.
.PP
This tool is still experimental, and you should neither rely
on its output without checking, nor expect it to work in your
environment.
.SH OPTIONS
.IX Header "OPTIONS"
.ie n .SS """\-\-cc"" compiler"
.el .SS "\f(CW\-\-cc\fP compiler"
.IX Subsection "--cc compiler"
This option allows you to explicitly specify a compiler
executable. This is especially useful if you don't want
to use your system compiler. If this options is not given,
\&\f(CW\*(C`ccconfig\*(C'\fR tries to guess a compiler.
.ie n .SS """\-\-output\-file"" file"
.el .SS "\f(CW\-\-output\-file\fP file"
.IX Subsection "--output-file file"
Write Convert::Binary::C configuration to the specified
file. The default is to write the configuration to \f(CW\*(C`stdout\*(C'\fR.
.ie n .SS """\-\-output\-format"" format"
.el .SS "\f(CW\-\-output\-format\fP format"
.IX Subsection "--output-format format"
Specify the output format of the Convert::Binary::C configuration.
The following formats are currently supported:
.PP
.Vb 2
\&  dumper      Output a %config hash using Data::Dumper
\&  require     Output in a format suitable for require
.Ve
.PP
The default is \f(CW\*(C`dumper\*(C'\fR.
.ie n .SS """\-\-basename"" name"
.el .SS "\f(CW\-\-basename\fP name"
.IX Subsection "--basename name"
Allows you to change the base name of the temporary test files.
This is used along with the various \f(CW\*(C`\-ext\*(C'\fR options to build
the filenames of C source files, preprocessor output files,
object files and executables.
.ie n .SS """\-\-inc\-path"" path"
.el .SS "\f(CW\-\-inc\-path\fP path"
.IX Subsection "--inc-path path"
This option allows you to manually set the include path of the
compiler. This is useful if \f(CW\*(C`ccconfig\*(C'\fR cannot determine the
include path automatically, most probably because it cannot
parse the preprocessor output. This option can be specified
more than once.
.ie n .SS """\-\-preprocess"" rule"
.el .SS "\f(CW\-\-preprocess\fP rule"
.IX Subsection "--preprocess rule"
Using this option, you can specify a \fIrule\fR that \f(CW\*(C`ccconfig\*(C'\fR
uses to run the compiler to get preprocessor output. Most
compilers write the preprocessor output to standard output
when given the \f(CW\*(C`\-E\*(C'\fR option, i.e.
.PP
.Vb 1
\&  cc \-E foo.c
.Ve
.PP
will preprocess \fIfoo.c\fR to standard output. The corresponding
rule for \f(CW\*(C`ccconfig\*(C'\fR would be:
.PP
.Vb 1
\&  ccconfig \-\-preprocess=\*(Aq\-E %c |\*(Aq
.Ve
.PP
The <%c> will be replaced with the C source filename, and the
pipe symbol signals that the result will be written to standard
output.
.PP
The following placeholders can be used in \f(CW\*(C`ccconfig\*(C'\fR rules:
.PP
.Vb 4
\&  %c    C source file
\&  %o    object file
\&  %e    executable file
\&  %i    preprocessor output file
.Ve
.PP
Usually, \f(CW\*(C`ccconfig\*(C'\fR tries to figure out the correct rules on
its own.
.ie n .SS """\-\-compile\-obj"" rule"
.el .SS "\f(CW\-\-compile\-obj\fP rule"
.IX Subsection "--compile-obj rule"
Like \f(CW\*(C`\-\-preprocess\*(C'\fR, this option allows you to define a rule
for how to compile an object file. For most compilers, this rule
will be something like
.PP
.Vb 1
\&  ccconfig \-\-compile\-obj=\*(Aq\-c \-o %o %c\*(Aq
.Ve
.ie n .SS """\-\-compile\-exe"" rule"
.el .SS "\f(CW\-\-compile\-exe\fP rule"
.IX Subsection "--compile-exe rule"
Like \f(CW\*(C`\-\-preprocess\*(C'\fR, this option allows you to define a rule
for how to compile an executable file. For most compilers, this
rule will be something like
.PP
.Vb 1
\&  ccconfig \-\-compile\-exe=\*(Aq\-o %e %c\*(Aq
.Ve
.PP
Note that it is sufficient to specify either \f(CW\*(C`\-\-compile\-obj\*(C'\fR
or \f(CW\*(C`\-\-compile\-exe\*(C'\fR. So if your compiler can only create object
files, that's just fine.
.ie n .SS """\-\-c\-ext"""
.el .SS \f(CW\-\-c\-ext\fP
.IX Subsection "--c-ext"
This option is used along with \f(CW\*(C`\-\-basename\*(C'\fR to build the name
of a C source file. This is usually set to \f(CW\*(C`.c\*(C'\fR.
.ie n .SS """\-\-pp\-ext"""
.el .SS \f(CW\-\-pp\-ext\fP
.IX Subsection "--pp-ext"
This option is used along with \f(CW\*(C`\-\-basename\*(C'\fR to build the name
of a preprocessor output file.
.ie n .SS """\-\-obj\-ext"""
.el .SS \f(CW\-\-obj\-ext\fP
.IX Subsection "--obj-ext"
This option is used along with \f(CW\*(C`\-\-basename\*(C'\fR to build the name
of an object file.
.ie n .SS """\-\-exe\-ext"""
.el .SS \f(CW\-\-exe\-ext\fP
.IX Subsection "--exe-ext"
This option is used along with \f(CW\*(C`\-\-basename\*(C'\fR to build the name
of an executable file.
.ie n .SS """\-\-nodelete"""
.el .SS \f(CW\-\-nodelete\fP
.IX Subsection "--nodelete"
Don't attempt to delete temporary files that have been created
by the compiler. Normally, \f(CW\*(C`ccconfig\*(C'\fR will look for all files
with the same basename as the temporary test file and delete
them.
.ie n .SS """\-\-norun"""
.el .SS \f(CW\-\-norun\fP
.IX Subsection "--norun"
You can specify this option if the executables generated
by your compiler cannot be run on your machine, i.e. if
you have a cross-compiler. However, \f(CW\*(C`ccconfig\*(C'\fR will
automatically find out that it cannot run the executables.
.PP
When this option is set, a different set of algorithms is
used to determine a couple of configuration settings. These
algorithms are all based upon placing a special signature
in the object file. They are less reliable that the standard
algorithms, so you shouldn't use them unless you have to.
.ie n .SS """\-\-quiet"""
.el .SS \f(CW\-\-quiet\fP
.IX Subsection "--quiet"
Don't display anything except for the final configuration.
.ie n .SS """\-\-nostatus"""
.el .SS \f(CW\-\-nostatus\fP
.IX Subsection "--nostatus"
Hide the status indicator. Recommended if you want to
redirect the script output to a file:
.PP
.Vb 1
\&  ccconfig \-\-nostatus >config.pl 2>ccconfig.log
.Ve
.ie n .SS """\-\-version"""
.el .SS \f(CW\-\-version\fP
.IX Subsection "--version"
Writes the program name, version and path to standard
output.
.ie n .SS """\-\-debug"""
.el .SS \f(CW\-\-debug\fP
.IX Subsection "--debug"
Generate tons of debug output. Don't use unless you know
what you're doing.
.SH EXAMPLES
.IX Header "EXAMPLES"
Normally, a simple
.PP
.Vb 1
\&  ccconfig
.Ve
.PP
without arguments is enough if you want the configuration for
your system compiler. While \f(CW\*(C`ccconfig\*(C'\fR is running, it will
write lots of status information to \f(CW\*(C`stderr\*(C'\fR. When it's done,
it will usually dump a Perl hash table to \f(CW\*(C`stdout\*(C'\fR which can
be directly used as a configuration for Convert::Binary::C.
.PP
If you want the configuration for a different compiler,
or \f(CW\*(C`ccconfig\*(C'\fR cannot determine your system compiler
automatically, use
.PP
.Vb 1
\&  ccconfig \-c gcc32
.Ve
.PP
if your compiler's name is \f(CW\*(C`gcc32\*(C'\fR.
.PP
If you want to pass additional options to the compiler, you
can do so after a double-dash on the command line:
.PP
.Vb 1
\&  ccconfig \-\- \-g \-DDEBUGGING
.Ve
.PP
or
.PP
.Vb 1
\&  ccconfig \-c gcc32 \-\- \-ansi \-fshort\-enums
.Ve
.PP
If you'd like to interface with the Perl core, you may find
a suitable configuration using something like:
.PP
.Vb 2
\&  ccconfig \-\-cc=\`perl \-MConfig \-e \*(Aqprint $Config{cc}\*(Aq\` \e
\&           \-\- \`perl \-MConfig \-e \*(Aqprint $Config{ccflags}\*(Aq\`
.Ve
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright (c) 2002\-2020 Marcus Holland-Moritz. All rights reserved.
This program is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
See Convert::Binary::C.