Name

SPVM::Builder::Config - Config for Compiling and Linking Native Classes

Description

SPVM::Builder::Config is a class to manage the configurations for compiling and linking native classes (C, C++, etc.).

An instance of this class holds compiler settings (managed by SPVM::Builder::Config itself), linker and resource settings (inherited from SPVM::Builder::Config::Linker), and configuration loading and common settings (inherited from SPVM::Builder::Config::Base).

Within a configuration file (.config), you can customize the build environment by accessing methods from all of these hierarchical levels.=head1 Usage

use SPVM::Builder::Config;

# Create a config
my $config = SPVM::Builder::Config->new;

# C99
my $config = SPVM::Builder::Config->new_c99;

# C++
my $config = SPVM::Builder::Config->new_cpp;

# C++11
my $config = SPVM::Builder::Config->new_cpp11;

# C++17
my $config = SPVM::Builder::Config->new_cpp17;

# Optimize
$config->optimize("-O2");

# Optimize with debug mode
$config->optimize("-O0 -g");

# Add ccflags
$config->add_ccflag("-DFOO");

$config->add_define("FOO");

# Add source files
$config->add_source_file("foo.c", "bar.c", "baz/baz.c");

# Add libraries
$config->add_lib("gdi32", "d2d1", "Dwrite");

# Add ldflags
$config->add_ldflag("-pthread");

# Use resource
$config->use_resource("Resource::MyResource");

Inheritance

SPVM::Builder::Config::Linker

Class Hierarchy

1. SPVM::Builder::Config::Base

The base class for all configuration classes. It provides the "loading configuration files" mechanism and manages common settings shared across all build phases, such as class_name, force, and quiet.

2. SPVM::Builder::Config::Linker

This class manages settings for "linking" (converting object files to shared libraries or executables) and "resource management". Fields like ld, libs, ldflags, and resources are defined in this class. Inherits SPVM::Builder::Config::Base.

3. SPVM::Builder::Config

This class primarily manages settings for "compilation" (converting C/C++ source files to object files). Inherits SPVM::Builder::Config::Linker and SPVM::Builder::Config::Base.

Fields

ext

my $ext = $config->ext;
$config->ext($ext);

Gets and sets ext field, the extension of a native class.

Examples:

# MyClass.c
$config->ext('c');

# MyClass.cpp
$config->ext('cpp');

# MyClass.cc
$config->ext('cc');

# MyClass.cu
$config->ext('cu');

# MyClass.m
$config->ext('m');

cc

my $cc = $config->cc;
$config->cc($cc);

Gets and sets cc field, a compiler name.

Examples:

# gcc
$config->cc('gcc');

# g++ for C++
$config->cc('g++');

# nvcc for CUDA/GUP
$config->cc('nvcc');

include_dirs

my $include_dirs = $config->include_dirs;
$config->include_dirs($include_dirs);

Gets and sets include_dirs field, an array reference containing header file search directories.

The values of this field are converted to -I options when the arguments of the compiler "cc" are created.

# -I /path1 -I /path2
$config->include_dirs(['/path1', '/path2']);

spvm_core_include_dir

my $spvm_core_include_dir = $config->spvm_core_include_dir;
$config->spvm_core_include_dir($spvm_core_include_dir);

Gets and sets spvm_core_include_dir field, an SPVM core header file search directory.

The value of this field is converted to -I option when the arguments of the compiler "cc" are created.

native_include_dir

my $native_include_dir = $config->native_include_dir;
$config->native_include_dir($native_include_dir);

Gets and sets native_include_dir field, a native header file search directory.

The value of this field is converted to -I option when the arguments of the compiler "cc" are created.

native_src_dir

my $native_src_dir = $config->native_src_dir;
$config->native_src_dir($native_src_dir);

Gets and sets native_src_dir field, a native source file search directory.

ccflags

my $ccflags = $config->ccflags;
$config->ccflags($ccflags);

Gets and sets ccflags field, an array reference containing arugments of the compiler "cc".

defines

my $defines = $config->defines;
$config->defines($defines);

Gets and sets defines field, an array reference containing the values of -D arugments of the compiler "cc".

optimize

my $optimize = $config->optimize;
$config->optimize($optimize);

Gets and sets optimize field, an arugment of the compiler "cc" for optimization.

Examples:

$config->optimize('-O3 -DNDEBUG');
$config->optimize('-O2');
$config->optimize('-g3 -O0');

position_independent_code_ccflags

my $flags = $config->position_independent_code_ccflags;
$config->position_independent_code_ccflags(['-fPIC']);

Gets or sets the compiler flags required to generate Position Independent Code (PIC). This is typically an array reference containing flags like -fPIC, which are necessary for building libraries intended for dynamic linking.

thread_ccflags

my $thread_ccflags = $config->thread_ccflags;
$config->thread_ccflags($thread_ccflags);

Gets and sets thread_ccflags field, an array reference containing arugments of the compiler "cc" for threads.

extra_ccflags

my $extra_ccflags = $config->extra_ccflags;
$config->extra_ccflags(['-Wno-unused-variable']);

Gets and sets extra_ccflags field, an array reference containing extra arguments of the compiler "cc".

ndebug_ccflags

my $ndebug_ccflags = $config->ndebug_ccflags;
$config->ndebug_ccflags(['-DNDEBUG']);

Gets and sets ndebug_ccflags field, an array reference containing compiler flags to deactivate debug features like assert. This field is typically used to provide -DNDEBUG for production builds.

std

my $std = $config->std;
$config->std($std);

Gets and sets std field, a language standard.

This field is converted to -std option when the arguments of the compiler "cc" are created.

Examples:

# -std=c99
$config->std('c99');

# -std=cpp
$config->std('cpp');

# -std=cpp11
$config->std('cpp11');

# -std=cpp17
$config->std('cpp17');

source_files

my $source_files = $config->source_files;
$config->source_files($source_files);

Gets and sets source_files field, an array reference containing relative paths of native source file file from "native_src_dir" field.

before_compile_cbs

my $before_compile_cbs = $config->before_compile_cbs;
$config->before_compile_cbs($before_compile_cbs);

Gets and sets before_compile_cbs field, an array reference containing callbacks called just before the compile command "cc" is executed.

These callbacks are executed only if an object file is actually generated.

The 1th argument of the callback is an SPVM::Builder::Config object.

The 2th argument of the callback is an SPVM::Builder::CompileInfo object.

cc_input_dir

my $cc_input_dir = $config->cc_input_dir;
$config->cc_input_dir($cc_input_dir);

Gets and sets cc_input_dir field, an input directory for the compiler "cc".

cc_output_dir

my $cc_output_dir = $config->cc_output_dir;
$config->cc_output_dir($cc_output_dir);

Gets and sets cc_output_dir field, an output directory for the compiler "cc".

language

my $language = $config->language;
$config->language($language);

Gets and sets the language field.

The language of the source files.

One of the following languages can be specified:

• c

  C language

• cpp

  C++ language

dialect

my $dialect = $config->dialect;
$config->dialect($dialect);

Gets and sets the dialect field.

The dialect of the language.

You can specify any dialect name, but the following names are reserved for specific compilers or toolchains:

Each unit of a dialect name must consist of lowercase alphanumeric characters (a-z0-9).

Multiple units can be combined using a hyphen (-) to represent sub-dialects, such as arduino-avr, esp32-s3, or cuda-sm80.

You can specify any dialect name, but the following names are reserved for specific compilers or toolchains:

• C Based Dialects

  • Languages

    • objc

      Objective-C language

  • Shaders

    • glsl

      Vulkan/OpenGL Shading Language. (Requires glslc)

  • Microcontrollers

    • arduino

      Arduino dialect. Requires avr-gcc or arm-none-eabi-gcc.

    • esp32

      ESP32 specific dialect. Requires xtensa-esp32-elf-gcc.

    • pic

      Microchip PIC dialect. Requires xc8, xc16, or xc32.

    • avr

      Raw AVR dialect. Requires avr-gcc.

• C++ Based Dialects

  • Languages

    • objcpp

      Objective-C++ language

  • Shaders

    • metal - Apple Metal Shading Language. (Based on C++14. Requires metal compiler)

  • GPU Computing

    • cuda - NVIDIA CUDA dialect. (Requires nvcc)

    • hip - AMD ROCm HIP dialect. (Requires hipcc)

    • sycl - SYCL dialect for heterogeneous computing. (Requires dpc++)

  • Hardware Logic Design (FPGA)

    • hls - High-Level Synthesis dialect. (Usually based on C++. Requires v++)

copyright_print_ccflags

my $copyright_print_ccflags = $config->copyright_print_ccflags;
$config->copyright_print_ccflags(['-nologo']);

Gets and sets the copyright_print_ccflags field, an array reference containing compiler arguments to control the printing of the copyright banner or logo (e.g., -nologo in MSVC).

language_ccflags

my $language_ccflags = $config->language_ccflags;
$config->language_ccflags($language_ccflags);

Gets and sets language_ccflags field, an array reference containing arguments of the compiler "cc" for language.

arch_ccflags

my $arch_ccflags = $config->arch_ccflags;
$config->arch_ccflags($arch_ccflags);

Gets and sets arch_ccflags field, an array reference containing arguments of the compiler "cc" for CPU architecture or host environment.

warn_ccflags

my $warn_ccflags = $config->warn_ccflags;
$config->warn_ccflags(['-Wall', '-Wextra']);

Gets and sets the warn_ccflags field, an array reference containing compiler arguments for warning settings.

debug_info_ccflags

my $debug_info_ccflags = $config->debug_info_ccflags;
$config->debug_info_ccflags(['-g']);

Gets and sets the debug_info_ccflags field, an array reference containing compiler arguments for generating debug information.

source_encoding_ccflags

my $source_encoding_ccflags = $config->source_encoding_ccflags;
$config->source_encoding_ccflags(['-finput-charset=UTF-8']);

Gets and sets the source_encoding_ccflags field, an array reference containing compiler arguments for source file encoding settings.

function_level_linking_ccflags

my $function_level_linking_ccflags = $config->function_level_linking_ccflags;
$config->function_level_linking_ccflags(['-Gy']);

Gets and sets the function_level_linking_ccflags field, an array reference containing compiler arguments to enable function-level linking (e.g., -Gy in MSVC).

This allows the linker to optimize the executable size by removing unreferenced functions.

cpp_exception_handling

my $cpp_exception_handling = $config->cpp_exception_handling;
$config->cpp_exception_handling(1);

Gets and sets the cpp_exception_handling field, a boolean value that indicates whether C++ exception handling is enabled.

If this value is true, the compiler is configured to support C++ exceptions (e.g., -EHsc in MSVC, -fexceptions in GCC). Defaults to undef.

library_linkage_ccflags

my $library_linkage_ccflags = $config->library_linkage_ccflags;
$config->library_linkage_ccflags(['-MT']);

Gets and sets the library_linkage_ccflags field, an array reference containing compiler arguments to specify the library linkage (e.g., static or dynamic linking).

These flags are passed to the compiler "cc" to determine how libraries (such as the C runtime library) are linked. For example, -MT or -MD in MSVC.

cc_output_option_name

my $cc_output_option_name = $config->cc_output_option_name;
$config->cc_output_option_name($cc_output_option_name);

Gets and sets cc_output_option_name field, a string that is an option name to specify a compiler output file name.

Class Methods

new

my $config = SPVM::Builder::Config->new(%fields);

Creates a new SPVM::Builder::Config object. This method calls the new method of the super class SPVM::Builder::Config::Linker.

Default settings for the GCC or Clang compiler are performed.

Field Default Values:

• "cc"

  undef

• "ccflags"

  []

• "defines"

  []

• "optimize"

  "-O3"

• "copyright_print_ccflags"

  []

• "language_ccflags"

  []

• "arch_ccflags"

  []

• "warn_ccflags"

  []

• "debug_info_ccflags"

  []

• "source_encoding_ccflags"

  []

• "function_level_linking_ccflags"

  []

• "cpp_exception_handling_ccflags"

  Windows:

  ['-D__USE_MINGW_ANSI_STDIO']

  Other OSs:

  []

• "library_linkage_ccflags"

  []

• "position_independent_code_ccflags"

  Windows:

  []

  Other OSs:

  ["-fPIC"]

• "thread_ccflags"

  ["-pthread"]

• "extra_ccflags"

  []

• "ndebug_ccflags"

  ["-DNDEBUG"]

• "include_dirs"

  []

• "spvm_core_include_dir"

  The SPVM core header file search directory.

• "native_include_dir"

  The directory described in "Native Header Files" in SPVM::Document::NativeClass.

• "native_src_dir"

  The directory described in "Native Source Files" in SPVM::Document::NativeClass.

• "source_files"

  []

• "before_compile_cbs"

  []

• "cc_output_option_name"

  "-o"

new_c

my $config = SPVM::Builder::Config->new_c;

Calls "new" method and sets "ext" field to c, "language" field to c, "cc" field to a C++ compiler, and returns the return value of "new" method.

new_c99

my $config = SPVM::Builder::Config->new_c99;

Calls "new_c" method and sets "std" field to c99, and returns the return value of "new_c" method.

new_c11

my $config = SPVM::Builder::Config->new_c11;

Calls "new_c" method and sets "std" field to c11, and returns the return value of "new_c" method.

new_cpp

my $config = SPVM::Builder::Config->new_cpp;

Calls "new" method and sets "ext" field to cpp, "language" field to cpp, "cc" field to a C++ compiler, and "ld" field to a C++ linker, and returns the return value of "new" method.

If $Config{gccversion} contains clang, "cc" field and "ld" field are set to clang++. Otherwise, "cc" field and "ld" field are set to g++.

new_cpp11

my $config = SPVM::Builder::Config->new_cpp11;

Calls "new_cpp" method and sets "std" field to c++11, and returns the return value of "new_cpp" method.

new_cpp14

my $config = SPVM::Builder::Config->new_cpp14;

Calls "new_cpp" method and sets "std" field to c++14, and returns the return value of "new_cpp" method.

new_cpp17

my $config = SPVM::Builder::Config->new_cpp17;

Calls "new_cpp" method and sets "std" field to c++17, and returns the return value of "new_cpp" method.

Instance Methods

add_ccflag

$config->add_ccflag(@ccflags);

Adds @ccflags to the end of "ccflags" field.

add_define

$config->add_define(@defines);

Adds @defines to the end of "defines" field.

add_include_dir

$config->add_include_dir(@include_dirs);

Adds @include_dirs to the end of "include_dirs" field.

add_source_file

$config->add_source_file(@source_files);

Adds @source_files to the end of "source_files" field.

Examples:

$config->add_source_file('foo.c', 'bar.c');

add_before_compile_cb

$config->add_before_compile_cb(@before_compile_cbs);

Adds @before_compile_cbs to the end of "before_compile_cbs" field.

Examples:

$config->add_before_compile_cb(sub {
  my ($config, $compile_info) = @_;
  
  my $cc_command = $compile_info->to_command;
  
  # Do something
});

clear_system_fields

$config->clear_system_fields;

Clears the fields that are set by default for a specific environment.

These fields might be updated in the future to support appropriate settings for different environments.

This method calls the clear_system_fields method of the SPVM::Builder::Config::Linker class to clear linker settings.

Then it clears the compiler settings whose field names are returned by the get_cc_system_field_names method by setting them to [].

get_cc_system_field_names

my $field_names = $config->get_cc_system_field_names;

Returns the field names of the compiler settings that are set by default for a specific environment.

These fields might be updated in the future to support appropriate settings for different environments.

The field names returned by this method are used by the clear_system_fields method to clear the compiler settings.

The following field names are returned:

• position_independent_code_ccflags

• thread_ccflags

• extra_ccflags

• ndebug_ccflags

• copyright_print_ccflags

• language_ccflags

• arch_ccflags

• warn_ccflags

• debug_info_ccflags

• source_encoding_ccflags

• function_level_linking_ccflags

• cpp_exception_handling_ccflags

• library_linkage_ccflags

Copyright & License

Copyright (c) 2023 Yuki Kimoto

MIT License

cpanm SPVM

perl -MCPAN -e shell
install SPVM