blib/lib/SPVM/Document/NativeClass.pm untested

filter: Statementstmt n/a Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub n/a Podpod n/a SCAR -
1 =head1 Name
2  
3 SPVM::Document::NativeClass - Native Classes
4  
5 =head1 Description
6  
7 A native class is the class implemented by a native language such as the C language and C++.
8  
9 =head1 Native Method Definition
10  
11 A native method is defined by L<native method attribute|SPVM::Document::Language::Class/"Method Attributes"> in an SPVM class file. It ends with a semicolon. A native method does not have its block.
12  
13 # SPVM/MyClass.spvm
14 class MyClass {
15 native static method sum : int ($num1 : int, $num2 : int);
16 }
17  
18 =head1 Native Config File
19  
20 A native config file is needed for a native class. The name of the config file is the same as the SPVM class name, but the extension C<.spvm> is replaced with C<.build>.
21  
22 # The name of a native config file
23 SPVM/MyClass.build
24  
25 A native config file is writen by Perl. It must end with a L<Builder::Config|SPVM::Builder::Config> object.
26  
27 A config file is executed by Perl's L<do|https://perldoc.perl.org/functions/do> function. The returned L<Builder::Config|SPVM::Builder::Config> object is used as the config for a native class.
28  
29 Exceptions:
30  
31 If the native config file does not exist, an exception is thrown.
32  
33 A config file must end with a L<Builder::Config|SPVM::Builder::Config> object. Otherwise, an exception is thrown.
34  
35 Examples:
36  
37 C99:
38  
39 my $config = SPVM::Builder::Config->new_c99;
40
41 $config;
42  
43 C++:
44  
45 my $config = SPVM::Builder::Config->new_cpp;
46
47 $config;
48  
49 =head1 Native Class
50  
51 A native class is the class implemented by a native language such as the C language and C++.
52  
53 The name of the native class file is the same as the SPVM class name, but the extension C<.spvm> is replaced with C<.> and L<extension of the native class|/"Native Class File Extension">.
54  
55 SPVM/MyClass.c
56  
57 =head2 Native Class File Extension
58  
59 The file extension of a native class is defined by L<Builder::Config#ext|SPVM::Builder::Config/"ext"> field in a config file.
60  
61 Examples:
62  
63 $config->ext('c');
64
65 $config->ext('cpp');
66
67 $config->ext('cc');
68
69 $config->ext('cu');
70  
71 Exceptions:
72  
73 If L<ext|SPVM::Builder::Config/"ext"> is defined, but its corresponding config file does not exist, an exception is thrown.
74  
75 =head2 Native Function
76  
77 A native function is a function defined in a native class.
78  
79 Examples:
80  
81 // SPVM/MyClass.c
82
83 #include "spvm_native.h"
84
85 int32_t SPVM__MyClass__sum(SPVM_ENV* env, SPVM_VALUE* stack) {
86
87 int32_t num1 = stack[0].ival;
88 int32_t num2 = stakc[1].ival;
89
90 int32_t total = num1 + num2;
91
92 stack[0].ival = total;
93
94 return 0;
95 }
96  
97 =head3 Native Function Name
98  
99 A native function must have the name following the rules below.
100  
101 =over 2
102  
103 =item * 1. Starts with C<SPVM__>.
104  
105 =item * 2. Followed by the SPVM class name, but C<::> is replaced with C<__>.
106  
107 =item * 3. Followed by C<__>.
108  
109 =item * 3. Followed by the name of the method.
110  
111 =back
112  
113 Exceptions:
114  
115 If the name of a native function is invalid, an exception is thrown.
116  
117 Examples:
118  
119 For example, if the class is C<MyClass::Math> and the method name is C<sum_value>, the name of the native function is C<SPVM__MyClass__Math__sum_value>.
120
121 # SPVM class
122 class MyClass::Math {
123 native method sum_value : void ();
124 }
125
126 // Native class
127 SPVM__MyClass__Math__sum_value(SPVM_ENV* env, SPVM_VALUE* stack) {
128
129 }
130  
131 =head2 Native API Header
132  
133 #include "spvm_native.h"
134  
135 C<spvm_native.h> is the header file for L<SPVM Native APIs|SPVM::Document::NativeAPI>.
136  
137 The following standard C headers are guaranteed to be available and can be used by default in your native code:
138  
139 #include <stdint.h>
140 #include <stdio.h>
141 #include <string.h>
142 #include <stdlib.h>
143 #include <inttypes.h>
144 #include <assert.h>
145  
146 These headers are highly portable and compatible with major compilers including GCC, Clang, and MSVC.
147  
148 =head2 Native Function Arguments
149  
150 A native function must have two arguments.
151  
152 int32_t SPVM__MyClass__sum(SPVM_ENV* env, SPVM_VALUE* stack) {
153
154 }
155  
156 The first argument C<env> is the current L<runtime environment|/"Runtime Environment">. This is the pointer to a value of C<SPVM_ENV> type.
157  
158 The second argument C<stack> is the current L<runtime stack|/"Runtime Stack">. This is is the pointer to the values of L<SPVM_VALUE|/"SPVM_VALUE Type"> type.
159  
160 The arguments given to this native function have been stored in the runtime stack.
161  
162 See L</"Getting Argument"> to get the values of the arguments.
163  
164 =head2 Native Function Return Value
165  
166 A native function must return a value of the C<int32_t> type.
167  
168 int32_t SPVM__MyClass__sum(SPVM_ENV* env, SPVM_VALUE* stack) {
169
170 # ...
171
172 return 0;
173 }
174
175 If an exception is thrown in this native method, the native function must return a non-zero value. Otherwise, must return 0.
176  
177 See L</"Exception"> for exception handling in native classes.
178  
179 =head2 SPVM_VALUE Type
180  
181 C<SPVM_VALUE> type is an union type in the C language.
182  
183 typedef union spvm_value SPVM_VALUE;
184
185 union spvm_value {
186 int8_t bval;
187 int16_t sval;
188 int32_t ival;
189 int64_t lval;
190 float fval;
191 double dval;
192 SPVM_OBJ* oval;
193 SPVM_REF* ref;
194 void* address;
195 int8_t* bref;
196 int16_t* sref;
197 int32_t* iref;
198 int64_t* lref;
199 float* fref;
200 double* dref;
201 };
202  
203 =head2 Getting Argument
204  
205 Arguments given to a native function have been stored in L<runtime stack|/"Runtime Stack"> I<stack>.
206  
207 int32_t SPVM__MyClass__sum(SPVM_ENV* env, SPVM_VALUE* stack) {
208
209 }
210  
211 Consider the following method definition.
212  
213 method foo ($args0 : int, $args1 : Point, $arg2 : Complex_2d);
214  
215 Do the following using the C<ival> field of L<SPVM_VALUE|/"SPVM_VALUE Type"> type to get the value of $args0 which type is int type.
216  
217 int32_t args0 = stack[0].ival;
218  
219 Do the following using the C<oval> field of L<SPVM_VALUE|/"SPVM_VALUE Type"> type to get the value of $args1 which type is L<Point|SPVM::Point> type.
220  
221 int64_t args1 = stack[1].oval;
222  
223 Do the following to get the values of $args2 which type is L<Complex_2d|SPVM::Complex_2d> multi-numeric type.
224  
225 double args2_re = stack[2].dval;
226 double args2_im = stack[3].dval;
227  
228 Note that the values of the multi-numeric type have been stored in the multiple values in the runtime stack. The length of the value in the runtime stack is the same as the length of the fields of the multi-numeric type.
229  
230 =head3 Getting byte Type Argument
231  
232 Use the C<bval> field of L<SPVM_VALUE|/"SPVM_VALUE Type"> type to get the value of the SPVM C<byte> type from an argument.
233  
234 int8_t args0 = stack[0].bval;
235  
236 =head3 Getting short Type Argument
237  
238 Use the C<sval> field of L<SPVM_VALUE|/"SPVM_VALUE Type"> type to get the value of the SPVM C<short> type from an argument.
239  
240 int16_t args0 = stack[0].sval;
241  
242 =head3 Getting int Type Argument
243  
244 Use the C<ival> field of L<SPVM_VALUE|/"SPVM_VALUE Type"> type to get the value of the SPVM C<int> type from an argument.
245  
246 int32_t args0 = stack[0].ival;
247  
248 =head3 Getting long Type Argument
249  
250 Use the C<lval> field of L<SPVM_VALUE|/"SPVM_VALUE Type"> type to get the value of the SPVM C<long> type from an argument.
251  
252 int64_t args0 = stack[0].lval;
253  
254 =head3 Getting float Type Argument
255  
256 Use the C<fval> field of L<SPVM_VALUE|/"SPVM_VALUE Type"> type to get the value of the SPVM C<float> type from an argument.
257  
258 float args0 = stack[0].fval;
259  
260 =head3 Getting double Type Argument
261  
262 Use the C<dval> field of L<SPVM_VALUE|/"SPVM_VALUE Type"> type to get the value of the SPVM C<double> type from an argument.
263  
264 double args0 = stack[0].dval;
265  
266 =head3 Getting Object Type Argument
267  
268 Use the C<oval> field of L<SPVM_VALUE|/"SPVM_VALUE Type"> type to get the value of an SPVM object type from an argument.
269  
270 void* args0 = stack[0].oval;
271  
272 =head3 Getting byte Reference Type Argument
273  
274 Use the C<bref> field of L<SPVM_VALUE|/"SPVM_VALUE Type"> type to get the value of an SPVM C<byte> reference type from an argument.
275  
276 int8_t* args0 = stack[0].bref;
277  
278 =head3 Getting short Reference Type Argument
279  
280 Use the C<sref> field of L<SPVM_VALUE|/"SPVM_VALUE Type"> type to get the value of an SPVM C<short> reference type from an argument.
281  
282 int16_t* args0 = stack[0].sref;
283  
284 =head3 Getting int Reference Type Argument
285  
286 Use the C<iref> field of L<SPVM_VALUE|/"SPVM_VALUE Type"> type to get the value of an SPVM C<int> reference type from an argument.
287  
288 int32_t* args0 = stack[0].iref;
289  
290 =head3 Getting long Reference Type Argument
291  
292 Use the C<lref> field of L<SPVM_VALUE|/"SPVM_VALUE Type"> type to get the value of an SPVM C<long> reference type from an argument.
293  
294 int64_t* args0 = stack[0].lref;
295  
296 =head3 Getting float Reference Type Argument
297  
298 Use the C<fref> field of L<SPVM_VALUE|/"SPVM_VALUE Type"> type to get the value of an SPVM C<float> reference type from an argument.
299  
300 float* args0 = stack[0].fref;
301  
302 =head3 Getting double Reference Type Argument
303  
304 Use the C<dref> field of L<SPVM_VALUE|/"SPVM_VALUE Type"> type to get the value of an SPVM C<double> reference type from an argument.
305  
306 double* args0 = stack[0].dref;
307  
308 =head3 Getting Multi-Numeric Type Arguments
309  
310 The values of an SPVM multi-numeric type from an argument have been stored to the multiple values in L<runtime stack|/"Runtime Stack">. the length of the values in the runtime stack is the same as the length of the fields of the SPVM multi-numeric type.
311  
312 For example, if the argument type is L<Complex_2d|SPVM::Complex_2d> type, these values have been stored to multiple fields the multiple values in the runtime stack.
313  
314 double args0_re = stack[0].dval;
315 double args0_im = stack[1].dval;
316  
317 =head2 Return Value
318  
319 If the reutrn type of an SPVM method is not the C<void> type, the first argument of L<runtime stack|/"Runtime Stack"> must be set to a return value.
320  
321 int32_t return_value = 5;
322
323 stack[0].ival = return_value;
324  
325 =head3 Setting Return Value of byte Type
326  
327 Use the C<bval> field of L<SPVM_VALUE|/"SPVM_VALUE Type"> type to set a return value of the SPVM C<byte> type.
328  
329 stack[0].bval = return_value;
330  
331 =head3 Setting Return Value of short Type
332  
333 Use the C<sval> field of L<SPVM_VALUE|/"SPVM_VALUE Type"> type to set a return value of the SPVM C<short> type.
334  
335 stack[0].sval = return_value;
336  
337 =head3 Setting Return Value of int Type
338  
339 Use the C<ival> field of L<SPVM_VALUE|/"SPVM_VALUE Type"> type to set a return value of the SPVM C<int> type.
340  
341 stack[0].ival = return_value;
342  
343 =head3 Setting Return Value of long Type
344  
345 Use the C<lval> field of L<SPVM_VALUE|/"SPVM_VALUE Type"> type to set a return value of the SPVM C<long> type.
346  
347 stack[0].lval = return_value;
348  
349 =head3 Setting Return Value of float Type
350  
351 Use the C<fval> field of L<SPVM_VALUE|/"SPVM_VALUE Type"> type to set a return value of the SPVM C<float> type.
352  
353 stack[0].fval = return_value;
354  
355 =head3 Setting Return Value of double Type
356  
357 Use the C<dval> field of L<SPVM_VALUE|/"SPVM_VALUE Type"> type to set a return value of the SPVM C<double> type.
358  
359 stack[0].dval = return_value;
360  
361 =head3 Setting Return Value of Object Type
362  
363 Use the C<oval> field of L<SPVM_VALUE|/"SPVM_VALUE Type"> type to set a return value of an SPVM object type.
364  
365 stack[0].oval = return_value;
366  
367 =head3 Setting Return Value of Multi-Numeric Type
368  
369 Multiple values in L<runtime stack|/"Runtime Stack"> are needed to be set to values of the field type of the multi-numeric type. The length of the values in the runtime stack is the same as the length of the fields of the SPVM multi-numeric type.
370  
371 There is an example in the case that the return type is L<Complex_2d|SPVM::Complex_2d>.
372  
373 double return_value_x;
374 double return_value_y;
375 stack[0].dval = return_value_x;
376 stack[1].dval = return_value_y;
377  
378 =head2 Native APIs
379  
380 L<Native APIs|SPVM::Document::NativeAPI> are the APIs written by the C language for SPVM operations. Native APIs can be called in native classes.
381  
382 =head3 Examples of Native APIs
383  
384 Create a Point object.
385
386 int32_t error_id = 0;
387 void* obj_point = env->new_object_by_name(env, stack, "Point", &error_id, __func__, FILE_NAME, __LINE__);
388 if (error_id) { return error_id; }
389  
390 Call a class method.
391  
392 int32_t error_id = 0;
393 int32_t total;
394 {
395 int32_t args_width = 2;
396 stack[0].ival = 5;
397 stack[1].ival = 10;
398 env->call_class_method_by_name(env, stack, "MyClass", "sum", args_width, &error_id, __func__, FILE_NAME, __LINE__);
399 if (error_id) { return error_id; }
400
401 total = stack[0].ival;
402 }
403  
404 Get the characters of a string.
405  
406 const char* chars = env->get_chars(env, stack, obj_string);
407  
408 Get the elements of an array of int type.
409  
410 int32_t* values = env->get_elems_int(env, stack, obj_array);
411  
412 =head2 Exception
413  
414 If a native method throws an exception, the native function must return a non-zero value, normally the basic type ID of an error class.
415  
416 A message can be set to L<exception variable|SPVM::Document::Language::ExceptionHandling/"Exception Variable">. If no message is set to L<exception variable|SPVM::Document::Language::ExceptionHandling/"Exception Variable">, a default exception message is set to it.
417  
418 env->set_exception(env, stack, env->new_string_nolen(env, stack, "An exception is thrown."));
419
420 return SPVM_NATIVE_C_BASIC_TYPE_ID_ERROR_CLASS;
421  
422 L<die|SPVM::Document::NativeAPI/"die"> native API can be used to throw an exception easily.
423  
424 return env->die("The value must be %d.", __func__, FILE_NAME, __LINE__, 3);
425  
426 =head2 Pointer Class
427  
428 An SPVM object can have a L<pointer value|/"Pointer Value">.
429  
430 If necessary, you can mark a class as a pointer class using L<pointer class attribute|SPVM::Document::Language::Class/"Class Attributes">.
431  
432 class MyClass : pointer {
433
434 }
435  
436 Examples of Pointer Classes:
437  
438 C<SPVM/MyTm.spvm>:
439  
440 class MyTm : pointer {
441
442 native static method new : MyTm ();
443
444 native method sec : int ();
445
446 native method DESTROY : ();
447 }
448  
449 C<SPVM/MyTm.c>:
450
451 static const char* FILE_NAME = "MyTm.c";
452
453 int32_t SPVM__MyTm__new(SPVM_ENV* env, SPVM_VALUE* stack) {
454
455 int32_t error_id = 0;
456
457 strcut tm* st_tm = (struct tm*)env->new_memory_block(env, stack, sizeof (struct tm));
458
459 void* obj_tm = env->new_object_by_name(env, stack, "MyTm", error_id, __func__, FILE_NAME, __LINE__);
460 if (error_id) { return error_id; }
461
462 env->set_pointer(env, stack, obj_tm, st_tm);
463
464 stack[0].oval = obj_tm;
465
466 return 0;
467 }
468
469 int32_t SPVM__MyTm__sec(SPVM_ENV* env, SPVM_VALUE* stack) {
470
471 void* obj_tm = stack[0].oval;
472
473 strcut tm* st_tm = (struct tm*)env->get_pointer(env, stack, obj_tm);
474
475 stack[0].ival = st_tm->tm_sec;
476
477 return 0;
478 }
479
480 int32_t SPVM__MyTm__DESTROY(SPVM_ENV* env, SPVM_VALUE* stack) {
481
482 void* obj_tm = stack[0].oval;
483
484 strcut tm* st_tm = (struct tm*)env->get_pointer(env, stack, obj_tm);
485
486 env->free_memory_block(env, stack, st_tm);
487
488 return 0;
489 }
490  
491 =head3 Pointer Value
492  
493 An object can have a pointer value. A pointer value is the address of a C/C++ object.
494  
495 See L<get_pointer|SPVM::Document::NativeAPI/"get_pointer"> native API to get a pointer value of an object.
496  
497 See L<set_pointer|SPVM::Document::NativeAPI/"set_pointer"> native API to set a pointer value of an object.
498  
499 =head2 Native Directory
500  
501 A native directory is the directory for native header files and native source files.
502  
503 The name of the native directory is the same as the SPVM class name, but the extension C<.spvm> is replaced with C<.native>.
504  
505 # The name of a native directory
506 SPVM/MyClass.native
507  
508 =head3 Native Header Files
509  
510 A native class can include native header files in the C<include> directory under the native directory.
511
512 # Native header files
513 SPVM/MyClass.native/include/foo.h
514 /dir/bar.h
515
516 // Native class
517 #include "foo.h"
518 #include "dir/bar.h"
519  
520 =head3 Native Source Files
521  
522 A native class can compile native source files in the C<src> directory under the native directory using L<add_source_file|SPVM::Builder::Config/"add_source_file"> in C<SPVM::Builder::Config> class.
523
524 # Native source files
525 SPVM/MyClass.native/src/foo.c
526 /dir/bar.c
527
528 # Native config file
529 my @source_files = ("foo.c", "dir/bar.c");
530 $config->add_source_file(@source_files);
531  
532 =head2 Scope
533  
534 A native function has its scope.
535  
536 L<enter_scope|SPVM::Document::NativeAPI/"enter_scope"> native API is called before the call of the native function.
537  
538 L<leave_scope|SPVM::Document::NativeAPI/"leave_scope"> native API is called after the call of the native function.
539  
540 You can create a scope and push objects to the L<native mortal stack|/"Native Mortal Stack">.
541  
542 int32_t mortal_stack_top = env->enter_scope(env, stack);
543
544 env->push_mortal(env, stack, object);
545
546 env->leave_scope(env, stack, mortal_stack_top);
547  
548 =head3 Native Mortal Stack
549  
550 A mortal stack is created for a L<runtime stack|/"Runtime Stack">.
551  
552 A mortal stack is the stack to save local variables to be destroyed at the end of the scope.
553  
554 =head2 Runtime Environment
555  
556 A runtime environement is created for an SPVM runtime.
557  
558 This is the pointer to the value of C<SPVM_ENV> type, normally named C<env>.
559  
560 SPVM_ENV* env;
561  
562 A runtime environement is given to the first argument of a native function.
563  
564 int32_t SPVM__MyClass__sum(SPVM_ENV* env, SPVM_VALUE* stack) {
565
566 }
567  
568 =head2 Runtime Stack
569  
570 A runtime stack represents the execution context of an SPVM program. It is created for each native thread or coroutine. The SPVM runtime automatically creates a primary runtime stack for the main thread.
571  
572 While it is named a "stack," it serves as a thread-local storage area that persists across function calls within the same execution unit. It is used to pass arguments to functions, receive return values, and store internal state specific to that thread, such as the L<exception variable|SPVM::Document::Language::ExceptionHandling/"Exception Variable"> and caller information.
573  
574 Technically, a runtime stack is a pointer to an array of L<SPVM_VALUE|/"SPVM_VALUE Type"> elements, and by convention, it is named C<stack>.
575  
576 SPVM_VALUE* stack;
577  
578 A runtime stack is passed as the second argument to all native functions:
579  
580 int32_t SPVM__MyClass__sum(SPVM_ENV* env, SPVM_VALUE* stack) { // ... }
581  
582 You can manually manage runtime stacks for new threads or coroutines using the L<new_stack|SPVM::Document::NativeAPI/"new_stack"> and L<free_stack|SPVM::Document::NativeAPI/"free_stack"> native APIs.
583  
584 =head3 Caller Stack
585  
586 The B<caller stack> is a special region within the L<runtime stack|/"Runtime Stack"> used to store the history of method calls. It allows the runtime to trace back the execution path when an exception occurs or when debugging.
587  
588 Each record in the caller stack consists of 4 elements (the record size is 4).
589  
590 =over 2
591  
592 =item * 0: caller_method_abs_name (The absolute name of the caller method, such as C<Foo#bar> or C<SPVM__Foo__bar>)
593  
594 =item * 1: caller_file (The file name of the caller)
595  
596 =item * 2: caller_line (The line number of the caller)
597  
598 =item * 3: current_method (The method currently being executed)
599  
600 =back
601  
602 Example:
603  
604 // Get the current depth of the caller stack
605 int32_t call_depth = env->get_call_depth(env, stack);
606
607 // Get the raw pointer to the caller information stack
608 SPVM_VALUE* caller_info_stack = env->get_caller_info_stack(env, stack);
609
610 // Get the size of each record (Normally 4)
611 int32_t record_size = env->get_caller_info_stack_record_size(env, stack);
612
613 // Traverse the caller stack to build a backtrace
614 for (int32_t i = 0; i < call_depth; i++) {
615 SPVM_VALUE* record = &caller_info_stack[i * record_size];
616
617 // Get caller information from the record
618 // caller_method_abs_name could be "Foo#bar" or "SPVM__Foo__bar"
619 const char* caller_method_abs_name = (const char*)record[0].address;
620 const char* caller_file = (const char*)record[1].address;
621 int32_t caller_line = record[2].ival;
622
623 // Get the current method information from the pointer
624 SPVM_NATIVE_METHOD* current_method = (SPVM_NATIVE_METHOD*)record[3].address;
625 const char* current_method_abs_name = env->api->method->get_abs_name(env->runtime, current_method);
626
627 // Process the information (e.g., printing a trace)
628 }
629  
630 =head2 Arguments Width
631  
632 The width of the arguments is the length in units of L<SPVM_VALUE|/"SPVM_VALUE Type"> type.
633  
634 If the type is a multi-numeric type, the width of the arguments is the length of the fields of the multi-numeric type. Otherwise, it is 1.
635  
636 Consider the following method definition.
637  
638 method foo ($args0 : int, $args1 : Point, $arg2 : Complex_2d);
639  
640 The argument width of the C<int> type is 1.
641  
642 The argument width of the object type L<Point|SPVM::Point> is 1.
643  
644 The argument width of the multi-numeric type L<Complex_2d|SPVM::Complex_2d> is the length of its field. It is 2.
645  
646 So the width of the arguments is totally 4.
647  
648 =head2 Native Motal Stack
649  
650 A native mortal stack is a stack that is used by L<enter_scope|SPVM::Document::NativeAPI/"enter_scope"> native API and L<leave_scope|SPVM::Document::NativeAPI/"leave_scope"> native API.
651  
652 A L<runtime stack|/"Runtime Stack"> has one native mortal stack.
653  
654 =head2 Compilation and Link
655  
656 A native class and native source files are compiled to object files and are linked and a shared library is generated.
657  
658 The extension of a shared library is C<.so> in Linux and UNIX, C<.dylib> in Mac, C<.dll> in Windows.
659  
660 Object files and a shared library file are output to the build directory.
661  
662 If the L<SPVM_BUILD_DIR|SPVM::Document::EnvironmentVariables/"SPVM_BUILD_DIR"> environment variable is defined, it is used as the build directory. If it does not exist, it is created.
663  
664 If the C<SPVM_BUILD_DIR> environment variable is not defined, a temporary directory is created at the beginning of the program, and the path is set to the environment variable.
665  
666  
667 Normally, C<~/.spvm_build> is used as the build directory.
668  
669 # Example
670 export SPVM_BUILD_DIR=~/.spvm_build
671  
672 =head2 Dependency Resolution
673  
674 The dependencies of compilation and link of a L<native class|/"Native Class">, L<native header files|/"Native Header Files">, and L<native source files|/"Native Source Files"> are resolved by the following rules.
675  
676 =over 2
677  
678 =item * If the version of SPVM is newer, the compilation and the link are performed.
679  
680 =item * If the modification time of a native config file is newer than the generated dynamic library, the compilation and the link are performed.
681  
682 =item * If the max of the modification time of the object files generated by compiliation is newer than the generated dynamic library, the link is performed.
683  
684 =item * If the modification time of a native class is newer than the object file generated from the native class, the compilation is performed.
685  
686 =item * If the modification time of a native source file is newer than the generated object file, the compilation is performed.
687  
688 =item * If the max of the modification time of header source files is newer than the object file generated from a native source file, the compilation of the native source file is performed.
689  
690 =back
691  
692 =head1 Native Types
693  
694 These types are used in the Native API.
695  
696 If C<SPVM_NATIVE_TYPE_STRICT> is defined, these types are defined as pointer types to opaque structures for strict type checking. Otherwise, they are defined as C<void>.
697  
698 =head2 SPVM_NATIVE_ALLOCATOR
699  
700 The native type for the allocator. See L<SPVM::Document::NativeAPI::Allocator>.
701  
702 =head2 SPVM_NATIVE_STRING_BUFFER
703  
704 The native type for the string buffer. See L<SPVM::Document::NativeAPI::StringBuffer>.
705  
706 =head2 SPVM_NATIVE_COMPILER
707  
708 The native type for the compiler. See L<SPVM::Document::NativeAPI::Compiler>.
709  
710 =head2 SPVM_NATIVE_CLASS_FILE
711  
712 The native type for the class file. See L<SPVM::Document::NativeAPI::ClassFile>.
713  
714 =head2 SPVM_NATIVE_RUNTIME
715  
716 The native type for the runtime. See L<SPVM::Document::NativeAPI::Runtime>.
717  
718 =head2 SPVM_NATIVE_BASIC_TYPE
719  
720 The native type for the basic type. See L<SPVM::Document::NativeAPI::BasicType>.
721  
722 =head2 SPVM_NATIVE_CLASS_VAR
723  
724 The native type for the class variable. See L<SPVM::Document::NativeAPI::ClassVariable>.
725  
726 =head2 SPVM_NATIVE_FIELD
727  
728 The native type for the field. See L<SPVM::Document::NativeAPI::Field>.
729  
730 =head2 SPVM_NATIVE_METHOD
731  
732 The native type for the method. See L<SPVM::Document::NativeAPI::Method>.
733  
734 =head2 SPVM_NATIVE_ARG
735  
736 The native type for the argument. See L<SPVM::Document::NativeAPI::Argument>.
737  
738 =head2 SPVM_NATIVE_MUTEX
739  
740 The native type for the mutex. See L<SPVM::Document::NativeAPI::Mutex>.
741  
742 =head2 SPVM_NATIVE_OPCODE
743  
744 The native type for the opcode.
745  
746 =head2 SPVM_OBJ
747  
748 The native type for the SPVM object. See L<SPVM::Document::NativeClass>.
749  
750 =head2 SPVM_REF
751  
752 The native type for the SPVM reference.
753  
754 =head1 Resource
755  
756 A native class can use native header files and native source files writen by native langauges such as the C language and C++ using L<SPVM::Builder::Config#use_resource|SPVM::Builder::Config/"use_resource">.
757  
758 # MyClass.build
759 $config->use_resource("Resource::Zlib");
760
761 // MyClass.c
762 #include "zlib.h"
763  
764 For details, see L<SPVM::Document::Resource>.
765  
766 =head1 Distribution
767  
768 A distribution for a native class can be generated by L<spvmdist> command.
769
770 # C
771 spvmdist --native c --user-name="Yuki Kimoto" --user-email="kimoto.yuki@gmail.com" MyNativeClass
772
773 # C++
774 spvmdist --native c++ --user-name="Yuki Kimoto" --user-email="kimoto.yuki@gmail.com" MyNativeClass
775  
776 A native class file and a config file only can be added to an existing distribution.
777  
778 # C
779 spvmdist --only-lib-files --native c --user-name="Yuki Kimoto" --user-email="kimoto.yuki@gmail.com" MyNativeClass lib
780
781 # C++
782 spvmdist --only-lib-files --native c++ --user-name="Yuki Kimoto" --user-email="kimoto.yuki@gmail.com" MyNativeClass lib
783  
784 =over 2
785  
786 =item * L<spvmdist>
787  
788 =back
789  
790 =head1 See Also
791  
792 =head2 Documents
793  
794 =over 2
795  
796 =item * L<SPVM::Document::Language::Class>
797  
798 =item * L<SPVM::Document>
799  
800 =back
801  
802 =head2 Config
803  
804 =over 2
805  
806 =item * L<SPVM::Builder::Config>
807  
808 =item * L<SPVM::Builder::Config::Exe>
809  
810 =back
811  
812 =head2 Native APIs
813  
814 =over 2
815  
816 =item * L<SPVM::Document::NativeAPI>
817  
818 =item * L<SPVM::Document::NativeAPI::Method>
819  
820 =item * L<SPVM::Document::NativeAPI::ClassVariable>
821  
822 =item * L<SPVM::Document::NativeAPI::Allocator>
823  
824 =item * L<SPVM::Document::NativeAPI::Compiler>
825  
826 =item * L<SPVM::Document::NativeAPI::Internal>
827  
828 =item * L<SPVM::Document::NativeAPI::Mutex>
829  
830 =item * L<SPVM::Document::NativeAPI::Field>
831  
832 =item * L<SPVM::Document::NativeAPI::BasicType>
833  
834 =item * L<SPVM::Document::NativeAPI::Runtime>
835  
836 =item * L<SPVM::Document::NativeAPI::Type>
837  
838 =item * L<SPVM::Document::NativeAPI::StringBuffer>
839  
840 =item * L<SPVM::Document::NativeAPI::ModuleFile>
841  
842 =item * L<SPVM::Document::NativeAPI::ClassFile>
843  
844 =item * L<SPVM::Document::NativeAPI::Argument>
845  
846 =item * L<Examples using native methods|https://github.com/yuki-kimoto/SPVM/tree/master/examples/native>
847  
848 =back
849  
850 =head2 Resource
851  
852 =over 2
853  
854 =item * L<SPVM::Document::Resource>
855  
856 =back
857  
858 =head1 Copyright & License
859  
860 Copyright (c) 2023 Yuki Kimoto
861  
862 MIT License