blib/lib/SPVM/Builder/Util/API.pm

filter: Statementstmt 100% 19 / 19 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 80.0% 8 / 10 Podpod 100% 6 / 6 totaltotal 94.2% 33 / 35 CC 1 SCAR 0.0
CC
1
Cov
100%
BEGIN
1.0
BEGIN
1.0
BEGIN
1.0
CRAP 1.0
« blib/script/spvmdist ↑ Summary blib/lib/SPVM/Builder/Config/Exe.pm »
1 package SPVM::Builder::Util::API;
2  
3 491 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 668 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 1091 ▶use SPVM::Builder::Util;
Subroutine BEGIN: called CC=1 SCAR=0.0
6 791 ▶use SPVM::Builder::Config::Util;
Subroutine BEGIN: called CC=1 SCAR=0.0
7  
8 300 ▶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 300 ▶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 310 ▶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 4029 ▶sub create_default_config { SPVM::Builder::Util::create_default_config(@_) }
Subroutine create_default_config: called CC=1 SCAR=0.0
Pod documented
15  
16 310 ▶sub get_cpu_count { SPVM::Builder::Util::get_cpu_count(@_) }
Subroutine get_cpu_count: called CC=1 SCAR=0.0
Pod documented
17  
18 311 ▶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 491 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
« blib/script/spvmdist ↑ Summary blib/lib/SPVM/Builder/Config/Exe.pm »