Name

SPVM::Builder::Config::Linker - Config for Linking Native Classes

Inheritance

SPVM::Builder::Config::Base

Fields

ld

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

Gets and sets ld field, a linker name.

Examples:

$config->ld('g++');

hint_cc

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

Gets and sets hint_cc field, a compiler name that is used as a hint for the linker.

The linker may use this field to determine how to link object files created by this compiler.

Examples:

$config->hint_cc('gcc');

lib_dirs

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

Gets and sets lib_dirs field, an array reference containing library search directories.

The values of this field are converted to -L options when the arguments of the linker "ld" are created.

# -L /path1 -L /path2
$config->lib_dirs(['/path1', '/path2']);

libs

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

Gets and sets libs field, an array reference containing library names such as z, and png or SPVM::Builder::LibInfo objects.

The values of this field are converted to -l options when the arguments of the linker "ld" are created.

See "Library Path Resolution" about resolving library paths.

Examples:

# -l libz -l libpng
$config->libs(['z', 'png']);

ldflags

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

Gets and sets ldflags field, an array reference containing arguments of the linker "ld".

dynamic_lib_ldflags

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

Gets and sets dynamic_lib_ldflags field, an array reference containing arguments of the linker "ld" for dynamic libraries.

This field is automatically set and users nomally do not change it.

thread_ldflags

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

Gets and sets thread_ldflags field, an array reference containing arguments of the linker "ld" for threads.

This field is automatically set and users nomally do not change it.

exe_libbcrypt_ldflags

my $exe_libbcrypt_ldflags = $config->exe_libbcrypt_ldflags;
$config->exe_libbcrypt_ldflags(['-lbcrypt']);

Gets and sets the exe_libbcrypt_ldflags field, an array reference containing linker arguments for the bcrypt library used for executable files.

Note that these flags are only added when the "output_type" is exe.

libcpp_ldflags

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

Gets and sets libcpp_ldflags field, an array reference containing arguments of the linker "ld" for the C++ standard library.

dynamic_lib_libcpp_ldflags

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

Gets and sets dynamic_lib_libcpp_ldflags field, an array reference containing arguments of the linker "ld" for the C++ standard library used for dynamic libraries.

exe_libcpp_ldflags

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

Gets and sets exe_libcpp_ldflags field, an array reference containing arguments of the linker "ld" for the C++ standard library used for executable files.

static_lib_braces

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

Gets and sets static_lib_braces field, an array reference containing a pair of arguments to start statically linking and end it.

The library name added by the "add_static_lib" are surrounded by the values of the pair.

# -Wl,-Bstatic -llibfoo -Wl,-Bdynamic
$config->static_lib_braces(['-Wl,-Bstatic', '-Wl,-Bdynamic']);
$config->add_static_lib('foo');

This field is automatically set and users nomally do not change it.

This field only works correctly in Linux/Unix.

Mac does not support these options. If you want to search a static library, create a new library search directory, copy a static library to there, and add the new library search directory.

# /path_for_static_lib/libz.a
$config->add_lib_dir('/path_for_static_lib');
$config->add_lib('z');

MinGW on Windows supports these options, but instead of linking statically, it links dynamically with absolute paths. This is usually not the intended behavior. If you want to do static linking on Windows, you need to use -static option.

ld_optimize

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

Gets and sets ld_optimize field, an argument of the linker "ld" for optimization.

Examples:

$config->ld_optimize("-O3");

before_link_cbs

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

Gets and sets before_link_cbs field, an array reference containing callbacks called just before the link command "ld" is executed.

These callbacks are executed even if the link command is not actually executed because of caching.

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

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

after_link_cbs

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

Gets and sets after_link_cbs field, an array reference containing callbacks called just after the link command "ld" is executed.

These callbacks are executed even if the link command is not actually executed because of caching.

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

The 2nd argument of the callback is an SPVM::Builder::LinkInfo object.

output_type

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

Gets and sets output_type field, a type of the output file "output_file" generated by the linker "ld".

If thie field is exe, the output file is an executable file.

If thie field is dynamic_lib, the output file is a dynamic link library.

copyright_print_ldflags

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

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

warn_ldflags

my $warn_ldflags = $config->warn_ldflags;
$config->warn_ldflags(['-Wl,--warn-common']);

Gets and sets the warn_ldflags field, an array reference containing linker arguments for warning settings.

debug_info_ldflags

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

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

symbol_strip_ldflags

my $symbol_strip_ldflags = $config->symbol_strip_ldflags;
$config->symbol_strip_ldflags(['-s']);

Gets and sets the symbol_strip_ldflags field, an array reference containing linker arguments to strip symbols.

libgcc_ldflags

my $libgcc_ldflags = $config->libgcc_ldflags;
$config->libgcc_ldflags(['-lgcc']);

Gets and sets the libgcc_ldflags field, an array reference containing linker arguments for the gcc library.

dynamic_lib_libgcc_ldflags

my $dynamic_lib_libgcc_ldflags = $config->dynamic_lib_libgcc_ldflags;
$config->dynamic_lib_libgcc_ldflags(['-lgcc']);

Gets and sets the dynamic_lib_libgcc_ldflags field, an array reference containing linker arguments for the gcc library used for dynamic libraries.

Note that these flags are only added when the "output_type" is dynamic_lib.

exe_libgcc_ldflags

my $exe_libgcc_ldflags = $config->exe_libgcc_ldflags;
$config->exe_libgcc_ldflags(['-lgcc']);

Gets and sets the exe_libgcc_ldflags field, an array reference containing linker arguments for the gcc library used for executable files.

Note that these flags are only added when the "output_type" is exe.

libbcrypt_ldflags

my $libbcrypt_ldflags = $config->libbcrypt_ldflags;
$config->libbcrypt_ldflags(['-lbcrypt']);

Gets and sets the libbcrypt_ldflags field, an array reference containing linker arguments for the bcrypt library.

dynamic_lib_libbcrypt_ldflags

my $dynamic_lib_libbcrypt_ldflags = $config->dynamic_lib_libbcrypt_ldflags;
$config->dynamic_lib_libbcrypt_ldflags(['-lbcrypt']);

Gets and sets the dynamic_lib_libbcrypt_ldflags field, an array reference containing linker arguments for the bcrypt library used for dynamic libraries.

Note that these flags are only added when the "output_type" is dynamic_lib.

extra_ldflags

my $extra_ldflags = $config->extra_ldflags;
$config->extra_ldflags(['-lextra']);

Gets and sets the extra_ldflags field, an array reference containing extra linker arguments.

dynamic_lib_extra_ldflags

my $dynamic_lib_extra_ldflags = $config->dynamic_lib_extra_ldflags;
$config->dynamic_lib_extra_ldflags(['-lextra']);

Gets and sets the dynamic_lib_extra_ldflags field, an array reference containing extra linker arguments used for dynamic libraries.

Note that these flags are only added when the "output_type" is dynamic_lib.

exe_extra_ldflags

my $exe_extra_ldflags = $config->exe_extra_ldflags;
$config->exe_extra_ldflags(['-lextra']);

Gets and sets the exe_extra_ldflags field, an array reference containing extra linker arguments used for executable files.

Note that these flags are only added when the "output_type" is exe.

lib_dir_option_name

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

Gets and sets lib_dir_option_name field, a string that is an option name to specify a library search path.

dynamic_lib_ext

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

Gets and sets dynamic_lib_ext field, the extension of a dynamic library such as so or dll.

The dot . is not included.

static_lib_ext

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

Gets and sets static_lib_ext field, the extension of a static library such as a or lib.

The dot . is not included.

exe_ext

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

Gets and sets exe_ext field, the extension of an executable file such as exe.

The dot . is not included.

lib_prefix

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

Gets and sets lib_prefix field, the prefix of a library name such as lib.

lib_option_suffix

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

Gets and sets lib_option_suffix field, the suffix of a library name such as .lib.

lib_option_name

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

Gets and sets lib_option_name field, a string that is an option name to specify a library name.

ld_output_option_name

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

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

output_dir

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

Gets and sets output_dir field, an output directory for the linker "ld".

This field is automatically set and users nomally do not change it.

output_file

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

Gets and sets output_file field. A path of a dinamic link library or an executable file generated by the linker "ld".

This field is automatically set and users nomally do not change it.

external_object_files

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

Gets and sets external_object_files field, an array reference containing additinal external object files linked to an executable file.

long_option_sep

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

Gets and sets long_option_sep field, a string that is a separator between an option name and its value.

Class Methods

new

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

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

Field Default Values:

• "ld"

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

• "ldflags"

  []

• "ld_optimize"

  "-O2"

• "output_type"

  "dynamic_lib"

• "copyright_print_ldflags"

  []

• "warn_ldflags"

  []

• "debug_info_ldflags"

  []

• "symbol_strip_ldflags"

  Windows:

  ["-s"]

  Other OSs:

  []

• "libgcc_ldflags"

  []

• "dynamic_lib_libgcc_ldflags"

  []

• "exe_libgcc_ldflags"

  []

• "libbcrypt_ldflags"

  []

• "dynamic_lib_libbcrypt_ldflags"

  []

• "extra_ldflags"

  []

• "dynamic_lib_extra_ldflags"

  []

• "exe_extra_ldflags"

  []

• "dynamic_lib_ldflags"

  Windows:

  ["-mdll"]

  Other OSs:

  ["-shared"]

• "thread_ldflags"

  Windows:

  ["-pthread", "-Wl,-Bstatic", "-lwinpthread", "-Wl,-Bdynamic"]

  Other OSs:

  ["-pthread"]

• "exe_libbcrypt_ldflags"

  Windows:

  ["-lbcrypt"]

  Other OSs:

  []

• "libcpp_ldflags"

  Windows:

  ["-Wl,-Bstatic", "-lstdc++", "-lgcc", "-Wl,-Bdynamic"]

  Other OSs:

  ["-lstdc++"]

• "dynamic_lib_libcpp_ldflags"

  []

• "exe_libcpp_ldflags"

  []

• "static_lib_braces"

  ["-Wl,-Bstatic", "-Wl,-Bdynamic"]

• "lib_dirs"

  []

• "libs"

  []

• "lib_prefix"

  "lib"

• "lib_option_name"

  "-l"

• "lib_option_suffix"

  ""

• "lib_dir_option_name"

  "-L"

• "dynamic_lib_ext"

  $Config{dlext} without the leading dot.

• "exe_ext"

  $Config{_exe} without the leading dot. If $Config{_exe} is an empty string, it is set to undef.

• "ld_output_option_name"

  "-o"

• "before_link_cbs"

  []

• "after_link_cbs"

  []

• "hint_cc"

  The default value is clang++ if $Config{gccversion} contains clang (case-insensitive). Otherwise, it is g++.

• "long_option_sep"

  "="

Instance Methods

add_ldflag

$config->add_ldflag(@ldflags);

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

add_lib_dir

$config->add_lib_dir(@lib_dirs);

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

add_lib

$config->add_lib(@libs);

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

Examples:

$config->add_lib('gsl');
$config->add_lib('gsl', 'z');
$config->add_lib(
  SPVM::Builder::LibInfo->new(config => $config, name => 'gsl'),
  SPVM::Builder::LibInfo->new(config => $config, name => 'z', is_abs => 1),
);

add_lib_abs

$config->add_lib_abs(@libs);

Adds @libs to the end of "libs" field with SPVM::Builder::LibInfo#is_abs field set to a true value.

If a value in @libs is not an SPVM::Builder::LibInfo object, an SPVM::Builder::LibInfo object is created from the library name.

If the library is located in your user directory, it is good to use "add_lib_abs" method instead of "add_lib" method.

This is because if the generated dynamic link library has a relative path, that path cannot be resolved when it is loaded.

For system libraries, there is no problem because the linker knows the search directory for the library.

add_static_lib

$config->add_static_lib(@libs);

Adds @libs to the end of "libs" field with SPVM::Builder::LibInfo#is_static field set to a true value.

If a value in @libs is not an SPVM::Builder::LibInfo object, an SPVM::Builder::LibInfo object is created from the library name.

Examples:

$config->add_static_lib('gsl');
$config->add_static_lib('gsl', 'z');

add_static_lib_abs

$config->add_static_lib_abs(@libs);

Adds @libs to the end of "libs" field with SPVM::Builder::LibInfo#is_static field and SPVM::Builder::LibInfo#is_abs field set to a true value.

If a value in @libs is not an SPVM::Builder::LibInfo object, an SPVM::Builder::LibInfo object is created from the library name.

add_before_link_cb

$config->add_before_link_cb(@before_link_cbs);

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

Examples:

$config->add_before_link_cb(sub {
  my ($config, $link_info) = @_;
  
  my $object_files = $link_info->object_files;
  
  # Do something
  
});

add_after_link_cb

$config->add_after_link_cb(@after_link_cbs);

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

Examples:

$config->add_after_link_cb(sub {
  my ($config, $link_info) = @_;
  
  my $object_files = $link_info->object_files;
  
  # Do something
  
});

use_resource

my $resource = $config->use_resource($resource_name);
my $resource = $config->use_resource($resource_name, %options);

Loads a resource given a resource class name, and returns it. The return value is an SPVM::Builder::Resource object.

Examples:

$config->use_resource('Resource::MyResource');

get_resource

my $resource = $config->get_resource($resource_name);

Gets a resource loaded by "use_resource" method given a resource name, and returns it. The return value is an SPVM::Builder::Resource object.

get_resource_names

my $resource_names = $config->get_resource_names;

Returns resource names loaded by "use_resource" method.

get_ld_system_field_names

my $field_names = $config->get_ld_system_field_names;

Returns the field names of the linker 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 linker settings.

The following field names are returned:

• dynamic_lib_ldflags

• thread_ldflags

• libcpp_ldflags

• exe_libbcrypt_ldflags

• dynamic_lib_libcpp_ldflags

• exe_libcpp_ldflags

• copyright_print_ldflags

• warn_ldflags

• debug_info_ldflags

• symbol_strip_ldflags

• libgcc_ldflags

• dynamic_lib_libgcc_ldflags

• exe_libgcc_ldflags

• libbcrypt_ldflags

• dynamic_lib_libbcrypt_ldflags

• extra_ldflags

• dynamic_lib_extra_ldflags

• exe_extra_ldflags

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 clears the linker settings whose field names are returned by the get_ld_system_field_names method by setting them to [].

• "thread_ldflags"

• "dynamic_lib_ldflags"

• "copyright_print_ldflags"

• "warn_ldflags"

• "debug_info_ldflags"

• "symbol_strip_ldflags"

• "libgcc_ldflags"

• "dynamic_lib_libgcc_ldflags"

• "exe_libgcc_ldflags"

• "libbcrypt_ldflags"

• "dynamic_lib_libbcrypt_ldflags"

• "extra_ldflags"

• "dynamic_lib_extra_ldflags"

• "exe_extra_ldflags"

• "libcpp_ldflags"

• "dynamic_lib_libcpp_ldflags"

• "exe_libcpp_ldflags"

• "exe_libbcrypt_ldflags"

add_external_object_file

$config->add_external_object_file(@external_object_files);

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

create_option

my $option = $config->create_option("-std", "c11");

Builds a command line option from the option name and the value.

If the length of the option name (excluding leading - and /) is 1, the option name and the value are connected without a separator.

# Results in "-Ic:/path"
my $option = $config->create_option("-I", "c:/path");

If the length of the option name is greater than 1, they are connected using "long_option_sep".

# Results in "-std=c11" (if long_option_sep is "=")
my $option = $config->create_option("-std", "c11");

This method is useful for supporting different compiler conventions such as GCC/Clang and MSVC.

create_option_short

my $option = $config->create_option_short("-I", "c:/path");

Builds a command line option by connecting the option name and the value directly without a separator.

# Results in "-Ic:/path"
my $option = $config->create_option_short("-I", "c:/path");

# Results in "-Foc:/path" (Useful for MSVC even if the option name length > 1)
my $option = $config->create_option_short("-Fo", "c:/path");

create_option_long

my $option = $config->create_option_long("-std", "c11");

Builds a command line option by connecting the option name and the value using "long_option_sep".

# Results in "-std=c11" (if long_option_sep is "=")
my $option = $config->create_option_long("-std", "c11");

# Results in "-out:c:/path" (if long_option_sep is ":")
my $option = $config->create_option_long("-out", "c:/path");

Library Path Resolution

The following is the rule of library path resolution.

Library names are converted to SPVM::Builder::LibInfo objects.

If SPVM::Builder::LibInfo#is_abs field is a false value, the linker "ld" resolves libaray paths.

If SPVM::Builder::LibInfo#is_abs field is a true value, libaray paths are resolved by the following rules.

A library is searched in the library search directories contained in "lib_dir" field from the beginning.

If SPVM::Builder::LibInfo#is_static field is a false value, the search is performed in the order of a dynamic library, a static library.

If SPVM::Builder::LibInfo#is_static field is a true value, the search is performed only in static libraries.

If a library is found, -l option of the linker "ld" is created using the found absolute path.

Copyright & License

Copyright (c) 2023 Yuki Kimoto

MIT License

cpanm SPVM

perl -MCPAN -e shell
install SPVM