=head1 NAME

C::Blocks - embeding a fast C compiler directly into your Perl parser

=for html <a href="https://travis-ci.org/run4flat/C-Blocks"><img src="https://travis-ci.org/run4flat/C-Blocks.svg?branch=master"></a>

=head1 STATUS

Pre-Beta

=over

=item Better representation on CPAN Testers

Very few machines report this module as working on CPAN testers,
including nothing for a number of key platforms. This seems to crop up
on 64-bit operating systems in particular. Before clicking over to v0.5,
I want this to have passes on all major platforms.

=back

This project is currently pre-Beta. That means that I have nearly
managed to get it working on at least one Linux, Mac, and Windows
machine, and I have implemented the functionality and tests I had hoped
to implement in the Alpha stage. The present goal is to find and fix all
the ways that C::Blocks can break, i.e. expand
the test suite and get it to run it on as many platforms as
possible. Not only can you expect some segmentation faults on at least a
few operating system, but you can expect the current compiler setup API
to change once the distribution has reached a greater level of
stability. (The API will be ironed out during Beta.)

=head1 DESCRIPTION

This distribution contains C<C::Blocks>, a module that adds a few 
lexically scoped keywords to your Perl parser. These keywords delimit C 
code blocks, and (in the current implementation) the code within them 
is compiled during Perl's bytecode compilation phase. The keywords 
including C<cblock>, C<clex>, C<cshare>, and C<csub>. The keyword
C<cisa> provides a simple typemap-like system.

In addition, this distribution contains C<C::Blocks::PerlAPI>, which 
loads Perl's C API. I may eventually include similar modules for all 
standard C libraries, such as libstdio, libmath, etc. Since libperl is 
itself compiled with these libraries, I suspect that most of them will 
be redundant for most people.

It can be difficult to safely attach C structs to Perl variables. This
problem was solved for XS authors with the module L<XS::Object::Magic>.
This distribution provides a port of that module called
C<C::Blocks::Object::Magic>.

This distribution presently includes C<C::Blocks::StretchyBuffer>, which
provides a rudimentary vector type. It serves an important role as a
testing module. It will almost certainly be spun off into its own module
by the time C<C::Blocks> v1.0 is released, so you should not rely on its
presence in the base distribution.

=head1 BUILD NOTES

On Debian systems using system Perl (C<local::lib> or otherwise), the
bad-symbol auto-detection runs much, much faster if you have
C<libperl-dev> installed. This is strongly recommended, if possible. If
you use Perlbrew, it will not matter because your local Perl will have
libperl available.

=head1 GOALS AND MILESTONES

I have a number of goals I would like to accomplish for this project.
The basic set of milestones are (1) make it work, (2) test the heck out
of it, (3) settle on an API, and (4) decide whether to throw in the
kitchen sink.

=head2 Pre-Alpha

The goal during the pre-alpha stage is to get things mostly working on 
most platforms. Once this is accomplished, I will spin an Alpha release 
on CPAN. I declared victory on this stage when I got libperl caching 
working on all platforms, even though StretchyBuffer still gave trouble 
on Windows.

=head2 Alpha CPAN Release, v0.01 - 0.49

The goal during the alpha stage is to vastly expand the test suite to 
make sure that everything works properly. For the most part, this means 
writing lots of tests of Perl's own C API. Additional tests for things 
like scoping and memory duration could stand to be expanded as well. 
Once I feel the test suite is robust, I move on to v0.5, beta.

The API for tweaking the compiler will still be considered in flux, so 
substantial library development is discouraged during Alpha.

Also, I currently get a lot of warnings saying

 warning: assignment from incompatible pointer type

This is a bug with the underlying extended symbol table handling and
struct type checking. I would like this to be fixed sooner rather than
later.

=head2 Beta CPAN Release, v0.50 - v0.99

After the distribution hits v0.50, it'll be time to begin settling on 
an API to set up the compiler. The current API uses global variables, 
but this almost certainly can be done better.

With the settling of the API, I also hope to make it easier to write
libraries that are export wrappers. The simplest example would be
something that, for the moment, I am calling C<C::Blocks::lib>. This
module would make it easy to import a bunch of C::Blocks modules in
one shot, i.e.

 use C::Blocks::lib qw(perl gsl prima);

would be equivalent to

 use C::Blocks::libperl;
 use C::Blocks::libgsl;
 use C::Blocks::libprima;

Of course, I've not yet decided if I want to call all libraries 
C<lib...>, so this still needs some thought.

Another important thing that'll come either during Alpha or Beta is 
switching to C<call_checker> and C<call_parser>. I used the keyword API 
for prototyping because it was easy for me to get started, but the 
newer API is the preferred method for this sort of stuff.

Finally, I want to create a module that helps automate the symbol table 
load/dump functionality and symbol verification currently under 
development for use with libperl. Once it's working for libperl, I want 
to create author tools for L<Module::Build> and L<ExtUtils::MakeMaker> 
so that build-time symbol table caching is easy.

=head2 v1.0

When C::Blocks hits v1.0, it'll have a solid test suite and stable API.
From v1.0 onward, it'll simply be a question of what to include in the
distribution itself.

=over

=item Simple C-based Object System?

I plan to write a module that makes it easy to write single-inheritance 
object oriented C code. My current plans are to steal from Prima, which 
does this sort of thing exceptionally well.

=item XS::Object::Magic

I like XS::Object::Magic, and I think I'd like to distribute a 
C::Blocks module with that functionality within C::Blocks itself.

=item Generate Inline::C, XS, ExtUtils::Depends

Right now the C code gets compiled at Perl's parse time. Once the C 
code is out of the prototyping stage, it would be nice to be able to 
automatically extract it and generate .h and .c files that can be 
compiled by the system's optimizing compiler. I need to write author 
tools that would allow this to be done using Inline::C, or to generate 
XS files with the proper scoping. Of course, it would also make sense 
for the contents of those header files to be accessible to other XS 
authors via ExtUtils::Depends.

=item Utilize ExtUtils::Depends

There is a lot of overlap between C<C::Blocks> and ExtUtils::Depends, 
and undoubtedly users of C<C::Blocks> would like to have access to 
functions and data structures that are made available through 
ExtUtils::Depends. It would be nice to provide some sort of automatic 
C::Blocks wrapper for ExtUtils::Depends based modules.

=item Threadsafe

The Tiny C Compiler uses lots of global variables and is therefore not 
threadsafe. I would like to contribute back to the project by 
encapsulating all of that global state into the compiler state object, 
where it belongs. Others in the tcc community have expressed interest 
in getting this done, so it is a welcome contribution.

=back

=head1 SEE ALSO

This module uses a special fork of the Tiny C Compiler. The fork is 
located at L<https://github.com/run4flat/tinycc>, and is distributed 
through the Alien package provided by L<Alien::TinyCCx>. To learn more 
about the Tiny C Compiler, see L<http://bellard.org/tcc/> and 
L<http://savannah.nongnu.org/projects/tinycc>. The fork is a major 
extension to the compiler that provides extended symbol table support.

For other ways of compiling C code in your Perl scripts, check out
L<Inline::C>, L<FFI::TinyCC>, L<C::TinyCompiler>, and L<XS::TCC>.

For mechanisms for calling C code from Perl, see L<FFI::Platypus> and
L<FFI::Raw>.

If you just want to mess with C struct data from Perl, see 
L<Convert::Binary::C>.

If you're just looking to write fast code with compact data structures, 
L<http://rperl.org/> may be just the ticket. It produces highly 
optmized code from a subset of the Perl language itself.

=head1 AUTHOR

David Mertens (dcmertens.perl@gmail.com)

=head1 BUGS

Please report any bugs or feature requests for the Alien bindings at 
the project's main github page: 
L<http://github.com/run4flat/C-Blocks/issues>.

=head1 SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc C::Blocks

You can also look for information at:

=over 4

=item * The Github issue tracker (report bugs here)

L<http://github.com/run4flat/C-Blocks/issues>

=item * AnnoCPAN: Annotated CPAN documentation

L<http://annocpan.org/dist/C-Blocks>

=item * CPAN Ratings

L<http://cpanratings.perl.org/d/C-Blocks>

=item * Search CPAN

L<http://p3rl.org/C::Blocks>
L<http://search.cpan.org/dist/C-Blocks/>

=back

=head1 ACKNOWLEDGEMENTS

This would not be possible without the amazing Tiny C Compiler or the 
Perl pluggable keyword work. My thanks goes out to developers of both 
of these amazing pieces of technology.

=head1 LICENSE AND COPYRIGHT

Code copyright 2013-2015 Dickinson College. Documentation copyright
2013-2015 David Mertens.

This program is free software; you can redistribute it and/or modify it
under the terms of either: the GNU General Public License as published
by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.

=cut