File Coverage

blib/lib/C/TinyCompiler.pm
Criterion Covered Total %
statement 23 23 100.0
branch n/a
condition n/a
subroutine 8 8 100.0
pod n/a
total 31 31 100.0


line stmt bran cond sub pod time code
1             package C::TinyCompiler;
2              
3 1     1   28464 use 5.010;
  1         4  
  1         43  
4 1     1   5 use strict;
  1         2  
  1         35  
5 1     1   5 use warnings;
  1         6  
  1         31  
6 1     1   5 use Carp;
  1         2  
  1         91  
7 1     1   873 use Alien::TinyCC;
  1         32146  
  1         69  
8              
9 1     1   14 use warnings::register;
  1         2  
  1         195  
10              
11             =head1 NAME
12              
13             C::TinyCompiler - Full C JIT compiling using the Tiny C Compiler
14              
15             =head1 VERSION
16              
17             Version 0.04
18              
19             =cut
20              
21             BEGIN {
22 1     1   3 our $VERSION = '0.04';
23 1     1   7 use XSLoader;
  1         2  
  1         35  
24 1         1126 XSLoader::load 'C::TinyCompiler', $VERSION;
25             }
26              
27             =head1 SYNOPSIS
28              
29             Compile C-code in memory at runtime.
30              
31             ## A really basic example ##
32            
33             use strict;
34             use warnings;
35             use C::TinyCompiler;
36            
37             # Build a compiler context
38             my $context = C::TinyCompiler->new();
39            
40             # Add some code (but don't compile yet)
41             $context->code('Body') = q{
42             void say_hi() {
43             printf("Hello from C::TinyCompiler!\n");
44             }
45             };
46            
47             # Compile our C code
48             $context->compile;
49            
50             # Call our function
51             $context->call_void_function('say_hi');
52            
53            
54             ## Make a function that takes arguments ##
55            
56             # Use the C::TinyCompiler::Callable package/extension
57             $context = C::TinyCompiler->new('C::TinyCompiler::Callable');
58            
59             # Add a function that does something mildly useful
60             $context->code('Body') = q{
61             C::TinyCompiler::Callable
62             double positive_pow (double value, int exponent) {
63             double to_return = 1;
64             while (exponent --> 0) to_return *= value;
65             return to_return;
66             }
67             };
68            
69             # Compile our C code
70             $context->compile;
71            
72             # Retrieve a subref to our function
73             my $pow_subref = $context->get_callable_subref('positive_pow');
74            
75             # Exercise the pow subref
76             print "3.5 ** 4 is ", $pow_subref->(3.5, 4), "\n";
77            
78            
79             ## Throw exceptions ##
80            
81             # Use the C::TinyCompiler::Callable and
82             # C::TinyCompiler::Perl::Croak packages/extensions
83             $context = C::TinyCompiler->new( qw< ::Callable ::Perl::Croak > );
84            
85             # Add a positive, integer pow() function
86             $context->code('Body') = q{
87             C::TinyCompiler::Callable
88             double positive_pow (double value, int exponent) {
89             if (exponent < 0) {
90             croak("positive_pow only accepts non-negative exponents");
91             }
92             double to_return = 1;
93             while (exponent --> 0) to_return *= value;
94             return to_return;
95             }
96             };
97            
98             ## Interface with PDL data ##
99            
100             $context = C::TinyCompiler->new('::Callable');
101            
102             # Create a sequence of prime numbers:
103             $context->code('Body') = q{
104             C::TinyCompiler::Callable
105             void prime_sequence (int * output, int length) {
106             /* Always start with 2 */
107             output[0] = 2;
108            
109             int n_filled = 1;
110             int candidate = 3;
111            
112             while(n_filled < length) {
113             for (int divisor_idx = 0; divisor_idx < n_filled; divisor_idx++) {
114             if (candidate % output[divisor_idx] == 0) goto NEXT_NUMBER;
115             if (output[divisor_idx] * output[divisor_idx] > candidate) break;
116             }
117             output[n_filled] = candidate;
118             n_filled++;
119            
120             NEXT_NUMBER: candidate++;
121             }
122             }
123             };
124            
125             # Compile our C code
126             $context->compile;
127            
128             # Retrieve a subref to our function
129             my $prime_sequence = $context->get_callable_subref('prime_sequence');
130            
131             # Allocate some memory for the operation
132             use PDL;
133             my $primes = zeroes(long, 20);
134            
135             # Exercise the subref to create the first 20 primes
136             $prime_sequence->($primes->get_dataref, $primes->nelem);
137             print "First 20 primes are $primes\n";
138              
139             =head1 DESCRIPTION
140              
141             This module provides Perl bindings for the Tiny C Compiler, a small, ultra-fast
142             C compiler that can compile in-memory strings of C code, and produce machine
143             code in memory as well. In other words, it is a full C just-in-time compiler. It
144             works for x86 and ARM processors. The jit-compilation capabilities offered by
145             this module are known to work on Windows, Linux, and Mac OS X.
146              
147             The goal for this family of modules is to not only provide a useful interface to
148             the compiler itself, but to also provide useful mechanisms for building
149             libraries that utilize this module framework. Eventually I would like to see a
150             large collection of pre-canned data structures and associated algorithms that
151             can be easily assembled together for fast custom C code. I would also like to
152             see C::TinyCompiler modules for interfacing with Perl-based C libraries such as
153             PDL, Prima, and Imager, or major Alien libraries such as SDL, OpenGL, or
154             WxWidgets. But this is only the early stages of development, and the key modules
155             that provide useful functionality are:
156              
157             =over
158              
159             =item L
160              
161             This module lets you write functions in C that can be invoked from Perl, much
162             like L.
163              
164             =item L
165              
166             This module provides a data structure that handles I like a C array but
167             has additional functionality to dynamically change the length, retrieve the
168             current length, and push and pop data at the end.
169              
170             =item L
171              
172             This module provides an interface to Perl's C-level C and C
173             functions, as well as their v-prefixed variants. This way, you can safely throw
174             exceptions from your TinyCompiler-compiled C code.
175              
176             =back
177              
178             =head1 PRE-COMPILE METHODS
179              
180             The compiler context has three main events that divide the usage into two
181             stages. Those events are creation, compilation, and destruction. Between
182             creation and compilation you can do many things to the compiler context to
183             prepare it for compilation, like adding library paths, setting and unsetting
184             C<#define>s, and adding code. After compilation, you can retrieve symbols (which
185             is how you get at the code or globals that you just compiled) and execute
186             compiled functons
187              
188             =head2 new
189              
190             Creates a new Tiny C Compiler context. All compiling and linking needs to be run
191             in a context, so before creating any new code, you'll need to create one of
192             these.
193              
194             Arguments are simply the names of packages that you want applied to your
195             compiler context. For example,
196              
197             my $context = C::TinyCompiler->new('::Perl::SV');
198             my $context = C::TinyCompiler->new('::Perl::SV', '::Perl::AV');
199              
200             C::TinyCompiler packages are to C::TinyCompiler what modules are to Perl. They
201             add some sort of functionality to the compiler context, whether that's a set of
202             functions or some fancy source filtering. To learn more about adding packages to
203             your compiler context, see L.
204              
205             =cut
206              
207             my %is_valid_location = map { $_ => '' } qw(Head Body Foot);
208              
209             sub new {
210             my $class = shift;
211            
212             # Create a new context object with the basics
213             my $self = bless {
214             has_compiled => 0,
215             error_message => '',
216             # Code locations
217             %is_valid_location,
218             # include paths
219             include_paths => [],
220             sysinclude_paths => [],
221             # library stuff
222             libraries => [],
223             library_paths => [],
224             # symbols (like function pointers)
225             symbols => {},
226             # Preprocessor definitions:
227             pp_defs => {},
228             };
229            
230             # Add Mac typedefs:
231             $self->{Head} = line_number(__LINE__) . q{
232             /* http://comments.gmane.org/gmane.comp.compilers.tinycc.devel/325 */
233             typedef unsigned short __uint16_t, uint16_t;
234             typedef unsigned int __uint32_t, uint32_t;
235             typedef unsigned long __uint64_t, uint64_t;
236            
237             #line 1 "whatever comes after Mac typedefs"
238             } if $^O =~ /darwin/;
239            
240             # Process any packages:
241             $self->apply_packages(@_);
242            
243             # Return the prepared object:
244             return $self;
245             }
246              
247             # Report errors if they crop-up:
248             sub report_if_trouble {
249             my ($self, $to_say) = @_;
250             my $msg = $self->get_error_message;
251            
252             # Don't do anything if we have nothing to worry about.
253             return unless $msg;
254            
255             # Handle warnings more gently than errors:
256             if ($msg =~ /warning/) {
257             $to_say =~ s/MESSAGE/$msg/;
258             warnings::warnif('Warning ' . $to_say);
259             }
260             else {
261             $to_say =~ s/MESSAGE/$msg/;
262             croak('Error ' . $to_say);
263             }
264             }
265              
266             sub get_error_message {
267             my $self = shift;
268             my $msg = $self->{error_message};
269             $self->{error_message} = '';
270             return $msg;
271             }
272              
273             =head2 add_include_paths, add_sysinclude_paths
274              
275             Adds include paths or "system" include paths to the compiler context. For
276             example,
277              
278             $context->add_include_paths qw(C:\my\win32\headers /my/linux/headers);
279              
280             Include paths are places to search when you say C<< #include >> or
281             C<$include "mylib.h"> in your C source. The only difference between a system
282             include path and a regular include path is that all regular include paths are
283             searched before any system include paths. Other important things to know include
284              
285             =over
286              
287             =item Quote-includes check '.' but angle-bracket includes do not
288              
289             The only difference between saying C<#include "mylib.h"> and
290             C<< #include >> is that the first one always looks for F
291             in the current working directory before checking the include paths, whereas
292             the second one only checks the include paths. By I,
293             I mean the working directory when the L function is invoked.
294              
295             =item Adding to the path is like using C<-I>
296              
297             Adding include paths is similar to the C<-I> command line argument that
298             you get with most (all?) compilers.
299              
300             =item First added = first checked
301              
302             Suppose you have files F and F and you add both C
303             and C to your list of include paths. Which header will you get? The
304             compiler will search through the include paths starting with the first path
305             added. In other words, if your file layout looks like this:
306              
307             foo/
308             bar.h
309             baz/
310             bar.h
311              
312             then this series of commands will pull in F rather than
313             F:
314              
315             use File::Spec;
316             $context->add_include_paths('foo', File::Spec->catfile('foo', 'baz'));
317             $context->code('Head') .= {
318             #include "bar.h"
319             };
320              
321             =item The last include path is checked before the first sysinclude path
322              
323             When your C code has C<#include "lib.h"> or C<< #include >>, the search
324             process starts off looking in all directories that are in the include path list,
325             followed by all the directories in the system include path list. This is
326             important if you are writing a C::TinyCompiler package. If you want your user to potentially
327             override a header file by adding an include path, you should specify any special
328             include paths with the sysinclude.
329              
330             =item Backslashes and qw(), q()
331              
332             As a notational convenience, notice that you do not need to escape the
333             backslashes for the Windows path when you use C. That makes Windows paths
334             easier to read, especially when compared to normal single and double quoted
335             strings.
336              
337             =item Nonexistent paths are OK
338              
339             Adding nonexistent paths will not trigger errors nor cause the compiler to
340             croak, so it's ok if you throw in system-dependent paths. It may lead to a minor
341             performance hit when the compiler searches for include files, but that's not
342             likely to be a real performance bottleneck.
343              
344             =item Path-separators are OK, but not cross-platform
345              
346             It is safe to submit two paths in one string by using the system's default path
347             separator. For example, this works on Linux:
348              
349             # Linux
350             $context->add_include_paths('/home/me/include:/home/me/sources');
351             # Windows
352             $context->add_include_paths('C:\\me\\include;C:\\me\\sources');
353              
354             However, the path separator is system-specific, i.e. not cross-platform. Use
355             sparingy if you want cross-platform code.
356              
357             =item No known exceptions
358              
359             There is a line of code in these bindings that check for bad return values, and
360             if triggered it will issue an error that reads thus:
361              
362             Unkown tcc error including path [%s]
363              
364             However, as of the time of writing, C::TinyCompiler will never trigger that error, so I find
365             it highly unlikely that you will ever see it. If you do, these docs and the code
366             need to be updated to query the source of the error and be more descriptive.
367              
368             =item Set paths before compiling
369              
370             This should be obvious, but it's worth pointing out that you must set the
371             include paths before you L. If you try to set include paths after
372             compilation, you will not cause any change in the context's state; if you have
373             warnings enabled, you will get a message like:
374              
375             Adding include paths after the compilation phase has no effect.
376              
377             or
378              
379             Adding sysinclude paths after the compilation phase has no effect.
380              
381             =back
382              
383             =cut
384              
385             sub _add_paths {
386             my ($self, $type) = (shift, shift);
387            
388             # Give a warning if the compiler has already run.
389             if ($self->has_compiled) {
390             warnings::warnif("Adding $type paths after the compilation phase has no effect.");
391             }
392             else {
393             push @{$self->{"${type}_paths"}}, @_;
394             }
395             }
396              
397             sub add_include_paths {
398             my $self = shift;
399             $self->_add_paths('include', @_);
400             }
401              
402             sub add_sysinclude_paths {
403             my $self = shift;
404             $self->_add_paths('sysinclude', @_);
405             }
406              
407             =head2 add_library_paths
408              
409             Adds library paths, similar to using C<-L> for most compilers. For example,
410              
411             $context->add_library_paths('C:\\mylibs', '/usr/home/david/libs');
412              
413             would be equivalent to saying, on the command line:
414              
415             cc ... -LC:\\mylibs -L/usr/home/david/libs ...
416              
417             Notice that the paths are not checked for existence before they are added. Also,
418             adding library paths after the compilation phase has no effect and, if you have
419             warnings enabled, will issue this statement:
420              
421             Adding library paths after the compilation phase has no effect.
422              
423             =cut
424              
425             sub add_library_paths {
426             my $self = shift;
427             $self->_add_paths('library', @_);
428             }
429              
430             =head2 add_librarys
431              
432             Adds the libraries, similar to using C<-l> for most compilers. For example,
433              
434             $context->add_librarys('gsl', 'cairo');
435              
436             would be equivalent to saying, on the command line:
437              
438             cc ... -llibgsl -llibcairo ...
439              
440             You must perform all additions before the compilation phase.
441              
442             If the compiler cannot find one of the requested libraries, it will croak saying
443              
444             Unable to add library %s
445              
446              
447             =cut
448              
449             sub add_librarys {
450             my $self = shift;
451             if ($self->has_compiled) {
452            
453             }
454             push @{$self->{libraries}}, @_;
455             }
456              
457              
458             =head2 define
459              
460             This defines a preprocessor symbol (not to be confused with L,
461             which adds a symbol to the compiler lookup table). It takes the preprocessor
462             symbol name and an optional string to which it should be expanded. This
463             functions much like the C<-D> switch for most (all?) compilers. In this way,
464             having this in your Perl code
465              
466             $context->define('DEBUG_PRINT_INT(val)'
467             , 'printf("For " #val ", got %d\n", val)');
468              
469             gives similar results as having this at the top of your C code:
470              
471             #define DEBUG_PRINT_INT(val) printf("For " #val ", got %d\n", val)
472              
473             In fact, tcc (and thus C::TinyCompiler) even supports variadic macros, both
474             directly in C code and using this method.
475              
476             =for details
477             The above statements are covered in the test suite, 112-compile-define.t
478              
479             Normally in C code, you might have such a definition within a C<#ifdef> block
480             like this:
481              
482             #ifdef DEBUG
483             # define DEBUG_PRINT_INT(val) printf("For " #val ", got %d\n", val)
484             #else
485             # define DEBUG_PRINT_INT(val)
486             #endif
487              
488             Since you control what gets defined with your Perl code, this can be changed to
489             something like this:
490              
491             if ($context->{is_debugging}) {
492             $context->define('DEBUG_PRINT_INT(val)'
493             , 'printf("For " #val ", got %d\n", val)');
494             }
495             else {
496             $context->define('DEBUG_PRINT_INT(val)');
497             }
498              
499             Another nicety of Perl-side macros is that they can be defined as multi-line
500             more cleanly. For example, this C macro
501              
502             #define DEBUG_PRINT_INT(val) \
503             do { \
504             printf("For " #val ", got %d\n", val); \
505             } while (0)
506              
507             can be notated with a Perl-side define simply as
508              
509             $context->define ('DEBUG_PRINT_INT(val)' => q{
510             do {
511             printf("For " #val ", got %d\n", val);
512             } while (0)
513             });
514              
515             There are differences between how Perl-side and C-side macro definitions
516             operate, but arguably the
517             most important is that the second form lets you query the definition from Perl.
518             The overhead involved for such queries likely makes C<#define> statements in
519             C code are marginally faster than Perl-side defines, but I have a hard time
520             believing that is a real bottleneck in your code. I suggest you optimize this
521             for developer time, not execution time.
522              
523             If you do not provide a symbol, an empty string will be used instead. This
524             varies slightly form the C usage, in which case if you provide a null
525             pointer, the string "1" is used. Thus, if you want a value of "1", you will need
526             to explicitly do that.
527              
528             If you attempt to modify a preprocessor symbol that has already been defined,
529             the behavior will depend on whether or not you have enabled C
530             warnings. These warnings are enabled if you say C in your code, so
531             if you are like most people, these are probably on by default. If you want to
532             suppress redefinition warnings for a small chunk of code, you should say
533             something like this:
534              
535             ...
536             {
537             no warnings 'C::TinyCompiler';
538             $context->define('symbol', 'new_value');
539             }
540             ...
541              
542             Also, this function will croak if you attempt to modify a preprocessor symbol
543             after you have compiled your code, saying:
544              
545             Error defining [$symbol_name]:
546             Cannot modify a preprocessor symbol
547             after the compilation phase
548              
549             If you want to check if the context has compiled, see L.
550              
551             =cut
552              
553             sub define {
554             my $self = shift;
555             my $symbol_name = shift;
556             my $set_as = shift || '';
557            
558             # Give a warning if the compiler has already run.
559             if ($self->has_compiled) {
560             warnings::warnif("Setting preprocessor definition for $symbol_name after the compilation phase has no effect");
561             }
562             else {
563             # Set the value in the compiler state:
564             warnings::warnif("Redefining $symbol_name")
565             if exists $self->{pp_defs}->{$symbol_name};
566             $self->{pp_defs}->{$symbol_name} = $set_as;
567             }
568             }
569              
570             =head2 is_defined
571              
572             Returns a boolean value indicating whether or not the given preprocessor symbol
573             has been defined using the L method. You can call this method both
574             before and after compiling your code, but this is not aware of any C<#define>
575             statements in your C code.
576              
577             For example:
578              
579             $context->define('DEBUGGING', 2);
580            
581             # ...
582            
583             if ($context->is_defined('DEBUGGING')) {
584             # More debugging code here.
585             }
586              
587             =cut
588              
589             sub is_defined {
590             my ($self, $symbol_name) = @_;
591             return exists $self->{pp_defs}->{$symbol_name};
592             }
593              
594             =head2 definition_for
595              
596             If you defined the given preprocessor macro using the L method, this
597             returns the (unexpanded) preprocessor definition that you supplied. If the macro
598             was not defined using L (or has subsequently been Ld), this
599             function will return Perl's C.
600              
601             For example:
602              
603             $context->define('DEBUGGING', 2);
604            
605             # ...
606            
607             if ($context->definition_for('DEBUGGING') > 2) {
608             # Debugging code for highly debuggish setting
609             }
610              
611             Bear in mind a number of important aspects of how this works. First, if the
612             value is not defined, you will get an undefined value back; using this in a
613             mathematical expression or trying to convert it to a string will make Perl
614             grumble if you C. Second, the values of 0 or the blank string
615             (blank strings are the default values if no value is supplied when you call
616             L) are valid values even though these are false in boolean context.
617             Thus, if you simply want to know if a preprocessor symbol is defined, you should
618             use L instead. That is to say:
619              
620             # BAD UNLESS YOU REALLY MEAN IT
621             if ($context->definition_for('DEBUGGING')) {
622             # ...
623             }
624            
625             # PROBABLY WHAT YOU MEANT TO SAY
626             if ($context->is_defined('DEBUGGING')) {
627             # ...
628             }
629              
630             =cut
631              
632             sub definition_for {
633             my ($self, $symbol_name) = @_;
634             return $self->{pp_defs}->{$symbol_name};
635             }
636              
637             =head2 undefine
638              
639             Undefines the given preprocessor symbol name. Remember that this happens before
640             any of the code has been compiled; you cannot call this dynamically in the
641             middle of the compilation process.
642              
643             This should not throw any errors. In particular, it should not gripe at you if
644             the symbol was not defined to begin with. However, it is still possible for
645             something deep inside tcc to throw an error, in which case you will get an
646             error message like this:
647              
648             Error undefining preprocessor symbol [%s]: %s
649              
650             But I don't expect that to happen much.
651              
652             =cut
653              
654             sub undefine {
655             my ($self, $symbol_name) = @_;
656            
657             # Give a warning if the compiler has already run.
658             if ($self->has_compiled) {
659             warnings::warnif("Removing preprocessor definition for $symbol_name after the compilation phase has no effect");
660             }
661             else {
662             delete $self->{pp_defs}->{$symbol_name};
663             }
664             }
665              
666             =head2 code
667              
668             XXX THIS INTERFACE IS LIKELY TO CHANGE IN THE NEAR FUTURE XXX
669              
670             This lvalue sub lets you get, set, append to, and otherwise modify the contents
671             of the code in each of three regions. Any value is allowed so long as the
672             compile-phase can retrieve a useful string. This means that you can even set
673             the different code sections to be objects.
674              
675             The location is the first argument and is a string, so the convention might look
676             something like this:
677              
678             $context->code('Head') = q{
679             double my_dsum(double, double);
680             };
681              
682             though I generally recommend that you append to each section rather than
683             overwriting. To append to the Body section, for example, you would say:
684              
685             $context->code('Body') .= q{
686             double my_dsum(double a, double b) {
687             return a+b;
688             }
689             };
690              
691             You can even hammer on these sections with a regular expression:
692              
693             $context->code('Head') =~ s/foo/bar/g;
694              
695             Valid locations include:
696              
697             =over
698              
699             =item Head
700              
701             Should come before any function definitions. Appropriate for function and global
702             variable declarations.
703              
704             =item Body
705              
706             Should contain function definitions.
707              
708             =item Foot
709              
710             Should come after function definitions. I'm not actually sure what should go
711             here, but I thought it might come in handy. :-)
712              
713             =back
714              
715             You can use whichever form of capitalization you like for the sections, so
716             C, C, and C are all valid.
717              
718             If you have a compiler error, line numbers will be meaningless if you do not
719             tell the compiler the line on which the code is run. To do this properly, use
720             L, discussed below.
721              
722             working here - note that warnings are not issued for changing code values after
723             the compilation phase, but such changes can have no effect.
724              
725             =cut
726              
727             # Valid locations are defined in %is_valid_location, created near the
728             # constructor.
729              
730             sub code :lvalue {
731             my ($self, $location) = @_;
732             # Canonicalize the location:
733             $location = ucfirst lc $location;
734            
735             # Make sure they supplied a meaningful location:
736             croak("Unknown location $location; must be one of "
737             . join(', ', keys %is_valid_location))
738             unless exists $is_valid_location{$location};
739            
740             $self->{$location};
741             }
742              
743             =head2 line_number
744              
745             Build a line number directive for you. Use like so:
746              
747             $context->code('Body') .= C::TinyCompiler::line_number(__LINE__) . q{
748             void test_func (void) {
749             printf("Success!\n");
750             }
751             };
752              
753             Suppose you have an error in your code and did not use this (or some other
754             means) for indicating your line numbers. The offending code could be
755              
756             $context->code('Body') .= q{
757             void test_func (void {
758             printf("Success!\n");
759             }
760             };
761              
762             which, you will notice, forgets to close the parenthesis in the function
763             definition. This will raise an error that would look like this:
764              
765             Unable to compile at Body line 2: parameter declared as void
766              
767             Although it tells you the section in which the error occurred, if you have a
768             complex script that adds code in many places, you may have no idea where to find
769             offending addition in your Perl code. Fortunately, C (and Perl) allows
770             you to give hints to the compiler using a C<#line> directive, which is made even
771             easier with this function. Without C, you would say something like:
772              
773             $context->code('Body') .= "\n#line " . (__LINE__+1) . ' "' . __FILE__ . q{"
774             ... code goes here ...
775             };
776              
777             and then your error reporting would say where the error occurred with respect to
778             the line in your script. That formula is long-winded and error prone, so you can
779             use this useful bit of shorthand instead:
780              
781             $context->code('Body') .= C::TinyCompiler::line_number(__LINE__) . q{
782             ... code goes here ...
783             };
784              
785             Still not awesome, but at least a little better.
786              
787             =cut
788              
789             sub line_number {
790             my ($line) = @_;
791             # The line needs to be incremented by one for the bookkeeping to work
792             $line++;
793             # Get the source filename using caller()
794             my (undef, $filename) = caller;
795             # Escape backslashes:
796             $filename =~ s/\\/\\\\/g;
797             return "\n#line $line \"$filename\"";
798             }
799              
800             =head2 apply_packages
801              
802             Adds the given packages to this compiler context. The names should be the name
803             of the Perl package that has the functions expected by the C::TinyCompiler
804             package mechanisms:
805              
806             $context->apply_packages qw(C::TinyCompiler::Perl::SV C::TinyCompiler::Perl::AV);
807              
808             The C is optional, so this is equivalent to:
809              
810             $context->apply_packages qw(::Perl::SV ::Perl::AV);
811              
812             Options are package-specific strings and should be specified after the
813             package name and enclosed by parentheses:
814              
815             $context->apply_packages qw(::Perl::SV(most) ::Perl::AV(basic))
816              
817             You can call this function multiple times with different package names. However,
818             a package will only be applied once, even if you specify different package
819             options. Thus, the following will not work:
820              
821             $context->apply_packages '::Perl::SV(basic)';
822             $context->apply_packages '::Perl::SV(refs)';
823              
824             Instead, you should combine these options like so:
825              
826             $context->apply_packages '::Perl::SV(basic, refs)';
827              
828             B that you can put spaces between the package name, the parentheses, and
829             the comma-delimited options, but C will not do what you mean in that case.
830             In other words, this could trip you up:
831              
832             $context->apply_packages qw( ::Perl::SV(basic, refs) );
833              
834             and it will issue a warning resembling this:
835              
836             Error: right parenthesis expected in package specification '::Perl::SV(basic,'
837              
838             Again, these are OK:
839              
840             $context->apply_packages qw( ::Perl::SV(basic) );
841             $context->apply_packages '::Perl::SV (basic)';
842              
843             but this is an error:
844              
845             $context->apply_packages qw( ::Perl::SV (basic) );
846              
847             and will complain saying:
848              
849             Error: package specification cannot start with parenthesis: '(basic)'
850             Is this supposed to be an option for the previous package?
851              
852             For more discussion on packages, see L.
853              
854             =cut
855              
856             sub apply_packages {
857             my ($self, @packages) = @_;
858            
859             # Run through all the packages and apply them:
860             PACKAGE: for my $package_spec (@packages) {
861             # Check for errors:
862             croak("Error: right parenthesis expected in package specification '$package_spec'")
863             if ($package_spec =~ /\(/ and $package_spec !~ /\)/);
864             croak("Error: package specification cannot start with parenthesis: '$package_spec'\n"
865             . "\tIs this supposed to be an option for the previous package?")
866             if ($package_spec =~ /^\s*\(/);
867            
868             # strip spaces
869             $package_spec =~ s/\s//g;
870             # Add C::TinyCompiler if it starts with ::
871             $package_spec = 'C::TinyCompiler' . $package_spec
872             if index ($package_spec, ':') == 0;
873             # Pull out the package options:
874             my @options;
875             if ($package_spec =~ s/\((.+)\)$//) {
876             my $options = $1;
877             @options = split /,/, $options;
878             }
879            
880             # Skip if already applied
881             next PACKAGE if $self->is_package_known($package_spec);
882            
883             # Pull in the package if it doesn't already exist:
884             unless ($package_spec->can('apply')) {
885             # All this mumbo jumbo is used to ensure that we get proper line
886             # number reporting if the package cannot be use'd.
887             eval '#line ' . (__LINE__-1) . ' "' . __FILE__ . "\"\nuse $package_spec";
888             croak($@) if $@;
889             }
890            
891             # Make sure we don't have any conflicting packages:
892             if ($package_spec->conflicts_with($self, keys %{$self->{applied_package}})
893             or grep {$_->conflicts_with($self, $package_spec)} keys %{$self->{applied_package}}
894             ) {
895             # If there's a conflict, then mark the package as blocked
896             $self->block_package($package_spec);
897             }
898             else {
899             # Apply the package, storing the options (for use later under the
900             # symbol application).
901             $package_spec->apply($self, @options);
902             $self->{applied_package}->{$package_spec} = [@options];
903             }
904             }
905             }
906              
907             =head1 MANAGING PACKAGES
908              
909             Certain packages require other packages, and some packages do not play nicely
910             together. The current package management system is not very sophisticated, but
911             it does provide a means for packages to indicate dependencies and conflicts with
912             others. In general, all of this should be handled by the packages and manual
913             intervention from a user should usually not be required.
914              
915             As far as the compiler is concerned, a package can be in one of three
916             states: (1) applied, (2) blocked, or (3) unknown. An applied package is any
917             package that you have applied directly or which has been pulled in as a package
918             dependency (but which has not been blocked). A blocked package is one that
919             should should not be applied. An unknown package is one that simply has not
920             been applied or blocked.
921              
922             As an illustration of this idea, consider the L package and the
923             light-weight sub-packages like L. The light-weight packages
924             provide a exact subset of L, so if L is loaded, the
925             sub-packages need to ensure that they do not apply themselves or, if they have
926             already been applied, that they remove themselves. This check and manipulation
927             occurs during the sub-packages' call to C
928              
929             =head2 is_package_applied, is_package_blocked, is_package_known
930              
931             Three simple methods to inquire about the status of a package. These return
932             boolean values indicating whether the package (1) is currently being applied,
933             (2) is currently blocked, or (3) is either being applied or blocked.
934              
935             =cut
936              
937             sub is_package_applied {
938             my ($self, $package) = @_;
939             return exists $self->{applied_package}->{$package};
940             }
941              
942             sub is_package_blocked {
943             my ($self, $package) = @_;
944             return exists $self->{blocked_package}->{$package};
945             }
946              
947             sub is_package_known {
948             my ($self, $package) = @_;
949             return $self->is_package_applied($package)
950             or $self->is_package_blocked($package);
951             }
952              
953             =head2 block_package
954              
955             Blocks the given package and removes its args from the applied package list if
956             it was previously applied.
957              
958             =cut
959              
960             sub block_package {
961             my ($self, $package) = @_;
962             delete $self->{applied_package}->{$package};
963             $self->{blocked_package}->{$package} = 1;
964             }
965              
966             =head2 get_package_args
967              
968             Returns the array ref containing the package arguments that were supplied when
969             the package was applied (or an empty array ref if the package was never applied
970             or has subsequently been blocked). This is the actual array reference, so any
971             manipulations to this array reference will effect the reference returned in
972             future calls to C.
973              
974             =cut
975              
976             sub get_package_args {
977             my ($self, $package) = shift;
978             return $self->{applied_package}->{$package} || [];
979             }
980              
981             =head1 COMPILE METHODS
982              
983             These are methods related to compiling your source code. Apart from C,
984             you need not worry about these methods unless you are trying to create a C::TinyCompiler
985             package.
986              
987             =head2 compile
988              
989             Concatenates the text of the three code sections, jit-compiles them, applies all
990             symbols from the included packages, and relocates the code so that symbols can
991             be retrieved. In short, this is the transformative step that converts your code
992             from ascii into machine.
993              
994             This step does far more than simply invoke libtcc's compile function. At the
995             time of writing, tcc only supports a single uncompiled compiler state at a time.
996             To properly handle this, C::TinyCompiler defers creating the actuall TCCState
997             object as long as possible. Calling the C method on your compiler
998             context actually performs these steps:
999              
1000             =over
1001              
1002             =item 1. Create TCCState
1003              
1004             An actual TCCState struct is created, to which the following operations are
1005             applied.
1006              
1007             =item 2. Apply preprocessor definitions, paths, libraries
1008              
1009             All preprocessor defintions, include paths, library paths, and libraries are
1010             added to the compiler state.
1011              
1012             =item 3. Invoke preprocessing methods of all C::TinyCompiler packages
1013              
1014             Packages can perform preprocessing on the compiler context (and in particular,
1015             the code strings) just before the actual compilation step. This allows them to
1016             dynmically add or remove elements to your code, like source-filters. Or they
1017             could hold off to perform other changes to the compiler context until just
1018             before the compilation step, although this is generally not needed.
1019              
1020             =item 4. Code assembly and compilation
1021              
1022             The code is assembled and compiled.
1023              
1024             =item 5. Apply symbols and relocate the machine code
1025              
1026             Symbols (such as dynamically loaded functions) are applied, the final machine
1027             code is relocated, and the memory pages holding that code are marked as
1028             executable.
1029              
1030             =back
1031              
1032             This means that nearly all of the interaction with libtcc itself is deferred
1033             until you call this function. As each of those interactions could encounter
1034             trouble, this function may croak for many reasons.
1035              
1036             =over
1037              
1038             =item This context has already been compiled
1039              
1040             You are only allowed to compile a context once.
1041              
1042             =item Error defining processor symbol :
1043              
1044             tcc encountered trouble while trying to define the given preprocessor symbol.
1045             Duplicate preprocessor symbols should not occurr at this stage, so this error
1046             likely means that your definition is malformed.
1047              
1048             =item Error adding include path(s):
1049             =item Error adding library path(s):
1050              
1051             An include path, sysinclude path, or library path gave trouble. The tcc source
1052             code has no code path that should issue this error, so this should never happen.
1053             If it does, either you really messed something up, or there's a bug in this
1054             module. :-)
1055              
1056             =item Error adding library(s):
1057              
1058             tcc encountered trouble adding one or more of your specified libraries. Hopefully
1059             the message explains the trouble well enough.
1060              
1061             =item Unable to compile ...
1062              
1063             If your code has a syntax error or some other issue, you will get this message.
1064             If the reported line numbers do not help, consider using L to
1065             improve line number reporting.
1066              
1067             =item Error adding symbol(s):
1068              
1069             If you specify symbols that have already been defined elsewhere, the compiler
1070             will thwart your attempts with this message. Make sure that you have not defined
1071             a like-named symbol already. In particular, be sure not to define a symbol that
1072             was defined already by one of your packages.
1073              
1074             =item Unable to relocate:
1075              
1076             The last step in converting your C code to machine-executable code is relocating
1077             the bytecode. This could fail, though I do not understand compilers well enough
1078             to explain why. If I had to guess, I would say you probably ran out of memory.
1079             (Sorry I cannot provide more insight into how to fix this sort of problem.
1080             Feedback for a better explanation would be much appreciated. :-)
1081              
1082             =back
1083              
1084             =cut
1085              
1086             sub compile {
1087             my $self = shift;
1088            
1089             # Make sure we haven't already compiled with this context:
1090             croak('This context has already been compiled') if $self->has_compiled;
1091            
1092             # Create the actual TCCState object:
1093             $self->_create_state;
1094            
1095             # Apply the #defines and add the #include paths
1096             my %defs = %{$self->{pp_defs}};
1097             while (my ($name, $value) = each %defs) {
1098             $self->_define($name, $value);
1099             $self->report_if_trouble("defining preprocessor symbol [$name]: MESSAGE");
1100             }
1101             $self->_add_include_paths(@{$self->{include_paths}});
1102             $self->_add_sysinclude_paths(@{$self->{sysinclude_paths}});
1103             $self->report_if_trouble("adding include path(s): MESSAGE");
1104            
1105             # Add the library stuff:
1106             $self->_add_library_paths(@{$self->{library_paths}});
1107             $self->report_if_trouble("adding library path(s): MESSAGE");
1108             $self->_add_libraries(@{$self->{libraries}});
1109             $self->report_if_trouble("adding library(s): MESSAGE");
1110            
1111             # Allow packages to perform any preprocessing they may want:
1112             while (my ($package, $options) = each %{$self->{applied_package}}) {
1113             $package->preprocess($self, @$options);
1114             }
1115            
1116             # Assemble the code (with primitive section indicators) and compile!
1117             eval {
1118             my $code = '';
1119             for my $section (qw(Head Body Foot)) {
1120             $code .= "#line 1 \"$section\"\n" . $self->{$section};
1121             }
1122             $self->_compile($code);
1123             1;
1124             } or do {
1125             # We ran into a problem! This exception will only get tripped if
1126             # libtcc's compile function returned nonzero, which means there was
1127             # an error. Warnings do not cause _compile to throw exceptions. So,
1128             # report the compiler issue as reported from the compiled line:
1129             my $message = $self->get_error_message;
1130             if ($message) {
1131             # Fix the rather terse line number notation:
1132             $message =~ s/:(\d+:)/ line $1/g;
1133             # Change "In file included..." to "in file included..."
1134             $message =~ s/^I/i/;
1135             # Remove "error" in "... 13: error: ..."
1136             $message =~ s/: error:/:/;
1137             # Finally, die:
1138             die "Unable to compile $message\n";
1139             }
1140            
1141             # Otherwise report an unknown compiler issue, indicating the line in the
1142             # Perl script that called for the compile action:
1143             croak("C::TinyCompiler weird internal error: Unable to compile for unknown reasons");
1144             };
1145             # Report any warnings
1146             $self->report_if_trouble('compiling: MESSAGE');
1147            
1148             # Apply the pre-compiled symbols (function pointers, etc):
1149             while (my ($package, $options) = each %{$self->{applied_package}}) {
1150             $package->apply_symbols($self, @$options);
1151             }
1152             # Apply any other symbols that were added:
1153             $self->_add_symbols(%{$self->{symbols}});
1154             $self->report_if_trouble("adding symbol(s): MESSAGE");
1155              
1156             # Relocate
1157             eval {
1158             $self->_relocate;
1159             1;
1160             } or do {
1161             # We ran into a problem! Report the relocation issue, if known:
1162             $self->report_if_trouble("relocating: MESSAGE");
1163             # Report an unknown relocation issue if not known:
1164             croak("C::TinyCompiler weird internal error: Unable to relocate for unknown reasons");
1165             };
1166            
1167             # Mark the compiler as post-compile
1168             $self->{has_compiled} = 1;
1169             }
1170              
1171             =head2 add_symbols
1172              
1173             Adds symbols to a compiler context. This function expects the symbols as
1174              
1175             symbol_name => pointer
1176              
1177             pairs. By I, I mean any C thing that you want to give a name in your
1178             compiler context. That is, you can add a function to your compiler context that
1179             was compiled elsewhere, or tell the compiler context the location of some
1180             variable that you wish it to access as a global variable.
1181              
1182             This function requires that you send a true C pointer that points to your
1183             symbol. This only makes sense if you have a way to get C pointers to your
1184             symbols. This would be the case if you have compiled code with a separate C::TinyCompiler
1185             context (in which case you would use L to retrieve that pointer),
1186             or if you have XS code that can retrieve a pointer to a function or global
1187             variable for you.
1188              
1189             working here - add examples, and make sure we can have two compiler contexts at
1190             the same time.
1191              
1192             For example, the input should look like this:
1193              
1194             $context->add_symbols( func1 => $f_pointer, max_N => $N_pointer);
1195              
1196             If you fail to provide key/value pairs, this function will croak saying
1197              
1198             You must supply key => value pairs to add_symbols
1199              
1200             =cut
1201              
1202             sub add_symbols {
1203             my $self = shift;
1204            
1205             # working here - not sure if it's safe to add symbols after relocation.
1206            
1207             croak('You must supply key => value pairs to add_symbols')
1208             unless @_ % 2 == 0;
1209            
1210             my %symbols = @_;
1211             while (my ($symbol, $pointer) = each %symbols) {
1212             # Track the symbols, warning on redefinitions
1213             warnings::warnif("Redefining $symbol")
1214             if exists $self->{symbols}->{$symbol};
1215             $self->{symbols}->{$symbol} = $pointer;
1216             }
1217             }
1218              
1219             =head1 POST-COMPILE METHODS
1220              
1221             These are methods you can call on your context after you have compiled the
1222             associated code.
1223              
1224             =head2 get_symbols
1225              
1226             Retrieves the pointers to a given list of symbols and returns a key/value list
1227             of pairs as
1228              
1229             symbol_name => pointer
1230              
1231             =cut
1232              
1233             sub get_symbols {
1234             croak('Cannot retrieve symbols before compiling') unless $_[0]->has_compiled;
1235             goto &_get_symbols;
1236             }
1237              
1238             =head2 get_symbol
1239              
1240             Like L, but only expects a single symbol name and only returns the
1241             pointer (rather than the symbol name/pointer pair). For example,
1242              
1243             $context->code('Body') .= q{
1244             void my_func() {
1245             printf("Hello!\n");
1246             }
1247             };
1248             $context->compile;
1249             my $func_pointer = $context->get_symbol('my_func');
1250              
1251             =cut
1252              
1253             sub get_symbol {
1254             my ($self, $symbol_name) = @_;
1255             croak("Cannot retrieve symbol $symbol_name before compiling")
1256             unless $self->has_compiled;
1257             my (undef, $to_return) = $self->get_symbols($symbol_name);
1258             return $to_return;
1259             }
1260              
1261             =head2 call_void_function
1262              
1263             Takes the name of a compiled function and calls it without passing any
1264             arguments. In other words, this assumes that your function has the following
1265             definition:
1266              
1267             void my_func (void) {
1268             ...
1269             }
1270              
1271             This is pretty dumb because it is nearly impossible to pass parameters into the
1272             function, but is useful for testing purposes. Note that if you try to call it
1273             before you have compiled, you will get this message:
1274              
1275             Cannot call a function before the context has compiled.
1276              
1277             =cut
1278              
1279             sub call_void_function {
1280             my ($self, $function) = @_;
1281            
1282             # Make sure we've compiled
1283             croak('Cannot call a function before the context has compiled.')
1284             unless $self->has_compiled;
1285            
1286             # Call the XS function:
1287             $self->_call_void_function($function);
1288             }
1289              
1290             =head2 is_compiling
1291              
1292             An introspection method to check if the context is currently in the compile
1293             phase. This is particularly useful for packages whose behavior may depend on
1294             whether they are operating pre-compile, post-compile, or during compile.
1295              
1296             =cut
1297              
1298             sub is_compiling {
1299             my $self = shift;
1300             return exists $self->{_state} and not $self->{has_compiled};
1301             }
1302              
1303             =head2 has_compiled
1304              
1305             An introspection method to check if the context has compiled it code or not. You
1306             are still allowed to modify the content of your code sections after compilation,
1307             but you will not be able to recompile it.
1308              
1309             =cut
1310              
1311             sub has_compiled {
1312             my $self = shift;
1313             return $self->{has_compiled};
1314             }
1315              
1316             # working here - consider using namespace::clean?
1317              
1318             =head1 Writing Functions
1319              
1320             Working here. Sorry. :-)
1321              
1322             =head1 TODO
1323              
1324             Add docs for report_if_error and get_error_message
1325              
1326             Research and add C if it seems appropriate.
1327              
1328             =head1 AUTHOR
1329              
1330             David Mertens, C<< >>
1331              
1332             =head1 BUGS
1333              
1334             Please report any bugs or feature requests at the project's main github page:
1335             L.
1336              
1337             =head1 SUPPORT
1338              
1339             You can find documentation for this module with the perldoc command.
1340              
1341             perldoc C::TinyCompiler
1342              
1343              
1344             You can also look for information at:
1345              
1346             =over 4
1347              
1348             =item * The Github issue tracker (report bugs here)
1349              
1350             L
1351              
1352             =item * AnnoCPAN: Annotated CPAN documentation
1353              
1354             L
1355              
1356             =item * CPAN Ratings
1357              
1358             L
1359              
1360             =item * Search CPAN
1361              
1362             L
1363             L
1364              
1365             =back
1366              
1367             =head1 ACKNOWLEDGEMENTS
1368              
1369             The tcc developers who have continued refining and improving the wonderlul
1370             little compiler that serves as the basis for this project!
1371              
1372             =head1 LICENSE AND COPYRIGHT
1373              
1374             Portions of this code are copyright 2011-2013 Northwestern University.
1375             Portions of this code are copyright 2013 Dickinson College.
1376             Documentation copyright 2011-2013 David Mertens.
1377              
1378             This program is free software; you can redistribute it and/or modify it
1379             under the terms of either: the GNU General Public License as published
1380             by the Free Software Foundation; or the Artistic License.
1381              
1382             See http://dev.perl.org/licenses/ for more information.
1383              
1384              
1385             =cut
1386              
1387             1; # End of TCC