| 1 | package SPVM::Builder::Util::API; | ||
| 2 | |||
| 3 | 685 | ▶ | use strict; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 4 | 756 | ▶ | use warnings; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 5 | 1119 | ▶ | use SPVM::Builder::Util; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 6 | 902 | ▶ | use SPVM::Builder::Config::Util; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 7 | |||
| 8 | 217 | ▶ | sub create_make_rule_native { SPVM::Builder::Util::create_make_rule_native(@_) } |
|
Subroutine
create_make_rule_native: not called CC=1 SCAR=0.0
Pod
documented
| |||
| 9 | |||
| 10 | 217 | ▶ | sub create_make_rule_precompile { SPVM::Builder::Util::create_make_rule_precompile(@_) } |
|
Subroutine
create_make_rule_precompile: not called CC=1 SCAR=0.0
Pod
documented
| |||
| 11 | |||
| 12 | 227 | ▶ | sub create_make_rule_parallel { SPVM::Builder::Util::create_make_rule_parallel(@_) } |
|
Subroutine
create_make_rule_parallel: called CC=1 SCAR=0.0
Pod
documented
| |||
| 13 | |||
| 14 | 2358 | ▶ | sub create_default_config { SPVM::Builder::Util::create_default_config(@_) } |
|
Subroutine
create_default_config: called CC=1 SCAR=0.0
Pod
documented
| |||
| 15 | |||
| 16 | 227 | ▶ | sub get_cpu_count { SPVM::Builder::Util::get_cpu_count(@_) } |
|
Subroutine
get_cpu_count: called CC=1 SCAR=0.0
Pod
documented
| |||
| 17 | |||
| 18 | 228 | ▶ | sub search_gnu_make_command { SPVM::Builder::Util::search_gnu_make_command(@_) } |
|
Subroutine
search_gnu_make_command: called CC=1 SCAR=0.0
Pod
documented
| |||
| 19 | |||
| 20 | 685 | 1; | |
| 21 | |||
| 22 | =head1 Name | ||
| 23 | |||
| 24 | SPVM::Builder::Util::API - Builder Utility APIs | ||
| 25 | |||
| 26 | =head1 Description | ||
| 27 | |||
| 28 | The SPVM::Builder::Util::API module has the public utility functions to build SPVM native classes and SPVM precompilation classes. | ||
| 29 | |||
| 30 | =head1 Usage | ||
| 31 | |||
| 32 | my $native_make_rule = SPVM::Builder::Util::API::create_make_rule_native('MyClass'); | ||
| 33 | |||
| 34 | my $precompile_make_rule = SPVM::Builder::Util::API::create_make_rule_precompile('MyClass'); | ||
| 35 | |||
| 36 | =head1 Functions | ||
| 37 | |||
| 38 | =head2 create_make_rule_native | ||
| 39 | |||
| 40 | my $make_rule = SPVM::Builder::Util::API::create_make_rule_native($class_name, $options); | ||
| 41 | |||
| 42 | Creates a string of C<make> commands for generating a dynamic library for a L<native class|SPVM::Document::NativeClass> given the class name $class_name, and returns it. | ||
| 43 | |||
| 44 | A native class must have at least one method with L<native attribute|SPVM::Document::Language::Class/"Method Attributes">. | ||
| 45 | |||
| 46 | C<$options> is a hash reference. The available options are the same as those for L</create_make_rule_parallel>. | ||
| 47 | |||
| 48 | Note that the following option is automatically set: | ||
| 49 | |||
| 50 | =over 2 | ||
| 51 | |||
| 52 | =item * C<native_classes> | ||
| 53 | |||
| 54 | This option is automatically set to C<[$class_name]>. | ||
| 55 | |||
| 56 | =back | ||
| 57 | |||
| 58 | Examples: | ||
| 59 | |||
| 60 | # Makefile.PL | ||
| 61 | sub MY::postamble { | ||
| 62 | |||
| 63 | my $make_rule = ''; | ||
| 64 | |||
| 65 | # Native compile make rule | ||
| 66 | $make_rule .= SPVM::Builder::Util::API::create_make_rule_native('Foo'); | ||
| 67 | |||
| 68 | return $make_rule; | ||
| 69 | } | ||
| 70 | |||
| 71 | =head2 create_make_rule_precompile | ||
| 72 | |||
| 73 | my $make_rule = SPVM::Builder::Util::API::create_make_rule_precompile($class_name, $options); | ||
| 74 | |||
| 75 | Creates a string of C<make> commands for generating a dynamic library for a precompilation class given the class name $class_name, and returns it. | ||
| 76 | |||
| 77 | A precompilation class must have at least one method with L<precompile attribute|SPVM::Document::Language::Class/"Method Attributes">. | ||
| 78 | |||
| 79 | C<$options> is a hash reference. The available options are the same as those for L</create_make_rule_parallel>. | ||
| 80 | |||
| 81 | Note that the following option is automatically set: | ||
| 82 | |||
| 83 | =over 2 | ||
| 84 | |||
| 85 | =item * C<precompile_classes> | ||
| 86 | |||
| 87 | This option is automatically set to C<[$class_name]>. | ||
| 88 | |||
| 89 | =back | ||
| 90 | |||
| 91 | Examples: | ||
| 92 | |||
| 93 | # Makefile.PL | ||
| 94 | sub MY::postamble { | ||
| 95 | |||
| 96 | my $make_rule = ''; | ||
| 97 | |||
| 98 | # Precompile make rule | ||
| 99 | $make_rule .= SPVM::Builder::Util::API::create_make_rule_precompile('Foo'); | ||
| 100 | |||
| 101 | return $make_rule; | ||
| 102 | } | ||
| 103 | |||
| 104 | =head2 create_default_config | ||
| 105 | |||
| 106 | my $config = SPVM::Builder::Util::API::create_default_config(); | ||
| 107 | |||
| 108 | Creates a default config, and returns it. It is an L<SPVM::Builder::Config> object. | ||
| 109 | |||
| 110 | Currently the default config is created by the following operation. | ||
| 111 | |||
| 112 | my $config = SPVM::Builder::Config->new_c99; | ||
| 113 | |||
| 114 | =head2 get_cpu_count | ||
| 115 | |||
| 116 | my $cpu_count = SPVM::Builder::Util::API::get_cpu_count(); | ||
| 117 | |||
| 118 | Returns the number of CPU cores on the current system. | ||
| 119 | |||
| 120 | This function detects the available CPU count in a platform-independent way (Windows, Linux, macOS, etc.). | ||
| 121 | |||
| 122 | If the CPU count cannot be determined, it returns 1. | ||
| 123 | |||
| 124 | =head2 create_make_rule_parallel | ||
| 125 | |||
| 126 | my $make_rule = SPVM::Builder::Util::API::create_make_rule_parallel($options); | ||
| 127 | |||
| 128 | Creates a string of C<make> commands for generating dynamic libraries for multiple native classes and precompile classes in parallel, and returns it. | ||
| 129 | |||
| 130 | C<$options> is a hash reference. | ||
| 131 | |||
| 132 | Options: | ||
| 133 | |||
| 134 | The following options are the same as those for L<SPVM::Builder::API#build_parallel_dynamic_lib_dist|SPVM::Builder::API/"build_parallel_dynamic_lib_dist"> function. | ||
| 135 | |||
| 136 | =over 2 | ||
| 137 | |||
| 138 | =item * C<build_dir> | ||
| 139 | |||
| 140 | The default value is C<".spvm_build">. | ||
| 141 | |||
| 142 | =item * C<output_dir> | ||
| 143 | |||
| 144 | The default value is C<"blib/lib">. | ||
| 145 | |||
| 146 | =item * C<jobs> | ||
| 147 | |||
| 148 | =item * C<config_global_file> | ||
| 149 | |||
| 150 | =item * C<native_classes> | ||
| 151 | |||
| 152 | =item * C<native_classes_file> | ||
| 153 | |||
| 154 | =item * C<precompile_classes> | ||
| 155 | |||
| 156 | =item * C<precompile_classes_file> | ||
| 157 | |||
| 158 | =back | ||
| 159 | |||
| 160 | The following options are specific to this method: | ||
| 161 | |||
| 162 | =over 2 | ||
| 163 | |||
| 164 | =item * C<dependent_files> | ||
| 165 | |||
| 166 | An array reference of dependency file paths for the C<make> target. These files are treated as normal dependencies. | ||
| 167 | |||
| 168 | $options->{dependent_files} = ['SPVM.xs']; | ||
| 169 | |||
| 170 | =item * C<order_only_dependent_files> | ||
| 171 | |||
| 172 | An array reference of order-only dependency file paths for the C<make> target. These files must exist before the target is built, but their modification times do not trigger a rebuild. | ||
| 173 | |||
| 174 | $options->{order_only_dependent_files} = ['$(INST_DYNAMIC)']; | ||
| 175 | |||
| 176 | =item * C<class_search_dir> | ||
| 177 | |||
| 178 | An array reference of include directories (corresponding to C<-I> options) for the Perl interpreter. | ||
| 179 | |||
| 180 | $options->{class_search_dir} = ['lib', 'ext/lib']; | ||
| 181 | |||
| 182 | =back | ||
| 183 | |||
| 184 | Examples: | ||
| 185 | |||
| 186 | # Makefile.PL | ||
| 187 | sub MY::postamble { | ||
| 188 | |||
| 189 | my $make_rule = ''; | ||
| 190 | |||
| 191 | # Parallel build make rule | ||
| 192 | $make_rule .= SPVM::Builder::Util::API::create_make_rule_parallel({ | ||
| 193 | native_classes => [ | ||
| 194 | 'Foo', | ||
| 195 | 'Bar', | ||
| 196 | ], | ||
| 197 | precompile_classes => [ | ||
| 198 | 'Baz', | ||
| 199 | ], | ||
| 200 | dependent_files => ['SPVM.xs'], | ||
| 201 | order_only_dependent_files => ['$(INST_DYNAMIC)'], | ||
| 202 | }); | ||
| 203 | |||
| 204 | return $make_rule; | ||
| 205 | } | ||
| 206 | |||
| 207 | =head2 search_gnu_make_command | ||
| 208 | |||
| 209 | my $gnu_make_command = SPVM::Builder::Util::API::search_gnu_make_command(); | ||
| 210 | |||
| 211 | Searches for a GNU Make command available in the current environment. | ||
| 212 | |||
| 213 | This function iterates through potential command names (C<gmake>, C<make>) and | ||
| 214 | verifies if they are actually GNU Make by executing a temporary Makefile | ||
| 215 | containing GNU-specific syntax (the C<$(info ...)> function). | ||
| 216 | |||
| 217 | The name of the GNU Make command (e.g., C<'gmake'> or C<'make'>) if found and | ||
| 218 | verified. Returns C<undef> otherwise. | ||
| 219 | |||
| 220 | =head1 Copyright & License | ||
| 221 | |||
| 222 | Copyright (c) 2023 Yuki Kimoto | ||
| 223 | |||
| 224 | MIT License | ||