website/src/code/build_noise.1.rb website/src/code/build_noise.2.rb website/src/code/build_noise.3.1.rb website/src/code/build_noise.3.2.rb website/src/code/build_noise.3.3.rb website/src/code/build_noise.3.4.rb website/src/code/build_noise.3.rb website/src/code/build_noise.4.rb website/src/code/build_noise.5.rb website/src/code/build_noise.6.rb website/src/code/build_noise.7.rb website/src/code/build_noise.definitions.rb website/src/code/build_noise.rb website/src/code/build_noise.source.rb @@ -3,3 +3,4 @@ html doc pkg test/generated +publish .gitignore @@ -11,7 +11,8 @@ task :default => :test # The tests wrap and load C++ wrapper code constantly. # When running all the tests at once, we very quickly run # into problems where Rice crashes because -# a given C++ class is already wrapped. So we need to run the +# a given C++ class is already wrapped, or glibc doesn't like our +# unorthodox handling of it's pieces. So we need to run the # tests individually desc "Run the tests" task :test do @@ -31,18 +32,29 @@ end RUBYFORGE_USERNAME = "jameskilton" PROJECT_WEB_PATH = "/var/www/gforge-projects/rbplusplus" -desc "Update the website" -task :upload_web => :rdoc do |t| - unless File.directory?("publish") - mkdir "publish" +namespace :web do + desc "Build website" + task :build => :rdoc do |t| + cd "website" do + sh "webgen" + end + + unless File.directory?("publish") + mkdir "publish" + end + sh "cp -r website/output/* publish/" + sh "cp -r html/* publish/rbplusplus/" + end + + desc "Update the website" + task :upload => "web:build" do |t| + Rake::SshDirPublisher.new("#{RUBYFORGE_USERNAME}@rubyforge.org", PROJECT_WEB_PATH, "publish").upload end - cd "website" do - sh "webgen" + + desc "Clean up generated website files" + task :clean do + rm_rf "publish" end - sh "cp -r website/out/* publish/" - sh "cp -r html/* publish/rbplusplus/" -# Rake::SshDirPublisher.new("#{RUBYFORGE_USERNAME}@rubyforge.org", PROJECT_WEB_PATH, "publish").upload -# rm_rf "publish" end spec = Gem::Specification.new do |s| Rakefile @@ -1,2 +1,2 @@ -out +output webgen.cache website/.gitignore @@ -55,5 +55,6 @@ a img:hover {background:#d85d5d; border-color:#d85d5d;} #content h1 {margin:0; color:#d85d5d; font-size:3.6em; letter-spacing:-4px; text-align:center;} #content h2 {margin:0; color:#808080; font-weight:normal; font-size:2em; letter-spacing:-2px; text-align:center;} #content h3 {margin:20px 0 10px 0; color:#d85d5d; font-weight:normal; font-size: 2em; letter-spacing:-2px;} +#content h4 {margin:0; color:#404040; font-weight:bold; font-size: 1.25em;} #siteInfo {padding-top: 3em;} website/src/default.css @@ -8,10 +8,21 @@ <meta name="author" content="Your Name" /> <meta name="generator" content="webgen - http://webgen.rubyforge.org" /> <link rel="stylesheet" type="text/css" href="{relocatable: default.css}" /> + <link rel="stylesheet" type="text/css" href="{resource: {name: webgen-css}}"/>  <title>{title:}</title> + + <style> + .CodeRay .code { + font-size: 12px; + } + + .CodeRay .no { + display: none; + } + </style> </head> <body> @@ -21,7 +32,7 @@ <h2>Ruby extensions have never been so easy</h2> <div id="menu"> - {menu: {max_levels: 1}} + {menu: vertical} </div> </div> @@ -38,13 +49,20 @@ </p> <ul> <li><a href="http://rubyforge.org/projects/rbplusplus">Rubyforge Project Page</a></li> - <li><a href="http://github.com/jameskilton/rbplusplus">Rb++ Github</a></li> - <li><a href="http://github.com/jameskilton/rbgccxml">RbGCCXML Github</a></li> + </ul> + + <p> + The source code for all related rb++ projects are hosted on GitHub + </p> + <ul> + <li><a href="http://github.com/jameskilton/rbplusplus">Rb++</a></li> + <li><a href="http://github.com/jameskilton/rbgccxml">RbGCCXML</a></li> + <li><a href="http://github.com/jameskilton/gccxml_gem">gccxml_gem</a></li> </ul> </div> <div id="content"> - <webgen:block name="content" /> + {block:} <div id="siteInfo"> <p>© 2008 Jason Roelofs | Generated by <a href="http://webgen.rubyforge.org">webgen</a> | Design by <a href="http://andreasviklund.com">Andreas Viklund</a>.</p> website/src/default.template @@ -1,8 +1,136 @@ --- -title: rb++ / rbgccxml -in_menu: true -routed_title: Rb++ +title: Rb++ +inMenu: true +orderInfo: 1 --- -## Rb++ +<h1>Rb++</h1> -<a href="rbplusplus/index.html">RDocs</a> +<h3>Synopsis</h3> + +Rb++ is a code generation system using <a href="rbgccxml.html">RbGCCXML</a> and +<a href="http://rice.rubyforge.org" target="_blank">Rice</a> to make the creation +of Ruby extensions as easy as possible. + +<h3>Documentation</h3> + +View the projects RDocs <a href="rbplusplus/index.html">here</a>. + +<h3>Example</h3> + +To give an idea of how easy it is to wrap C++ libraries into Ruby extensions, we'll +go through the wrapping of the <a href="http://libnoise.sourceforge.net/" target="_blank"> +libnoise</a> library, a library built to easily generate coherent noise. + +This libnoise wrapper is a part of the under-development <a href="http://github.com/jameskilton/ogrerb/tree/master">Ogre.rb</a> library. The following code will only run under the Ogre.rb environment so feel free to check out the project and follow along. + +We'll start by showing the full source code of the wrapper, which will then be broken down by each important +part. + +<h4>First, the code</h4> + +{includeFile: {filename: code/build_noise.rb, processOutput: false, escapeHTML: false, highlight: ruby}} + +<br/> +At first glance, this is probably quite overwhelming, but it breaks down into two very easy-to-understand sections: <a href="#source">souce code / compilation setup</a> and <a href="#definitions">wrapping definitions</a>. + +<a name="source"></a> +<h4>Source Code / Compliation Setup</h4> + +{includeFile: {filename: code/build_noise.source.rb, processOutput: false, escapeHTML: false, highlight: ruby}} + +<br/> +This section of the code constitutes the Setup portion of the wrapper. We'll go through each line to understand what all +is happening here. + +<br/> +{includeFile: {filename: code/build_noise.1.rb, processOutput: false, escapeHTML: false, highlight: ruby}} + +<br/> +All extensions start with this declaration. The string passed in will be the final name of the extension. In this case, +this will generate an extension named "noise.so". + +<br/> +{includeFile: {filename: code/build_noise.2.rb, processOutput: false, escapeHTML: false, highlight: ruby}} + +<br/> +The Working Directory is the place where all generated code is placed. By default, the Working Directory is "generated", local +to the ruby script. In the case that this is not sufficient, such as this wrapper, use this attribute to set another +directory. + +Please note that all directories used in the script should be full paths to prevent problems, though this is not required. + +<br/> +{includeFile: {filename: code/build_noise.3.rb, processOutput: false, escapeHTML: false, highlight: ruby}} + +<br/> +Here we have the bulk of the required setup for this wrapper to function properly. Extension#sources is the method that controls +configuration of what source code is to be wrapped, where such code is to be found, any extra code to be added to the extension, +and how compilation works (flags, etc). We'll go through each part on it's own. + +<br/> +{includeFile: {filename: code/build_noise.3.1.rb, processOutput: false, escapeHTML: false, highlight: ruby}} + +<br/> +The first argument to Extension#sources is the only one required. It is where you specify what source header files are to be +parsed for function / class / method definitions to wrap into an extension. Here, because libnoise gives us a "noise.h" file +that itself includes the rest of the headers, we only need to specify this one file. Noiseutils is a seperate, downloadable +set of utility methods and classes that we also want to put in our extension, so we specify its header here as well. + +*Note* For any and all places where file paths are expected, said paths can be in one of these forms: + +* Straight string, like "/path/to/file.h" +* Glob, such as "/where/headers/are/*.h" +* An array of strings ["/here/header1.h", "/there/header2.h", ...] +* An array of globs ["/usr/lib/library/*.h", "/usr/lib/other_lib/*.hpp"] + +<br/> +{includeFile: {filename: code/build_noise.3.2.rb, processOutput: false, escapeHTML: false, highlight: ruby}} + +<br/> +These three options map directly onto compiler flags. + +* :include_paths are added to -I +* :library_paths are added to -L +* :libraries are added to -l + +If you are getting errors about GCCXML being unable to find certain source files, :include_paths helps with fixing +this as well. + +<br/> +{includeFile: {filename: code/build_noise.3.3.rb, processOutput: false, escapeHTML: false, highlight: ruby}} + +<br/> +This option is simply allowing you to specify extra C++ source files that need to be copied into the working directory and +compiled in with the extension, but not necessarily parsed and wrapped. + +"custom_to_from_ruby.{c,h}pp" here is currently how you would handle any requirement of writing C++ wrapper code that rb++ doesn't +handle automatically. The contents of these files are on github: + +* <a href="http://github.com/jameskilton/ogrerb/tree/master/wrappers/noise/code/custom_to_from_ruby.hpp">custom_to_from_ruby.hpp</a> +* <a href="http://github.com/jameskilton/ogrerb/tree/master/wrappers/noise/code/custom_to_from_ruby.cpp">custom_to_from_ruby.cpp</a> + +In this case, there is some duplication between :include_source_files, the first argument of Extension#sources, and (further along +in this tutorial) :includes, which should be minimized in future versions of rb++. For now, the duplication is unfortunately +required for this wrapper to compile and run properly. + +<br/> +{includeFile: {filename: code/build_noise.3.4.rb, processOutput: false, escapeHTML: false, highlight: ruby}} + +<br/> +The final option given to Extension#sources fits in with :include_source_files above. When there's a header file that needs +to be included in all of the generated source files (such as custom_to_from_ruby.hpp), it must be specified with this +option. As said before, this will most likely made simplier and cleaner in the next release of rb++. + +With this, Rb++ is fully configured to create an extension from C++ source code. However, because C++ features and standards and Ruby features and standards don't often match up, Rb++ makes available many tools for manipulating the resulting extension to fit the Ruby-way. + +<a name="definitions"></a> +<h4>Wrapping Definitions</h4> + +{includeFile: {filename: code/build_noise.definitions.rb, processOutput: false, escapeHTML: false, highlight: ruby}} + +<br/> +The rest of the code handles defining the final Ruby extension. Rb++'s API is meant to be as simple and obvious as possible, +though there are some nuances that need to be explained. + +<br/> +{includeFile: {filename: code/build_noise.4.rb, processOutput: false, escapeHTML: false, highlight: ruby}} website/src/index.page @@ -1,7 +1,7 @@ --- -title: rb++ / rbgccxml -in_menu: true -routed_title: RbGCCXML +title: RbGCCXML +inMenu: true +orderInfo: 2 --- ## RbGCCXML website/src/rbgccxml.page publish/andreas07.css publish/browserfix.css publish/default.css publish/images/bodybg.gif publish/images/example.jpg publish/images/sidebarbg.gif publish/index.html publish/rbgccxml.html publish/rbgccxml/index.html publish/rbplusplus/classes/Inflector.html publish/rbplusplus/classes/Inflector/Inflections.html publish/rbplusplus/classes/RbGCCXML.html publish/rbplusplus/classes/RbGCCXML/Class.html publish/rbplusplus/classes/RbGCCXML/Function.html publish/rbplusplus/classes/RbGCCXML/Node.html publish/rbplusplus/classes/RbPlusPlus.html publish/rbplusplus/classes/RbPlusPlus/Builders.html publish/rbplusplus/classes/RbPlusPlus/Builders/Base.html publish/rbplusplus/classes/RbPlusPlus/Builders/ClassBuilder.html publish/rbplusplus/classes/RbPlusPlus/Builders/EnumerationBuilder.html publish/rbplusplus/classes/RbPlusPlus/Builders/ExtensionBuilder.html publish/rbplusplus/classes/RbPlusPlus/Builders/ModuleBuilder.html publish/rbplusplus/classes/RbPlusPlus/Builders/TypesManager.html publish/rbplusplus/classes/RbPlusPlus/ConfigurationError.html publish/rbplusplus/classes/RbPlusPlus/Extension.html publish/rbplusplus/classes/RbPlusPlus/RbModule.html publish/rbplusplus/classes/RbPlusPlus/Writers.html publish/rbplusplus/classes/RbPlusPlus/Writers/Base.html publish/rbplusplus/classes/RbPlusPlus/Writers/ExtensionWriter.html publish/rbplusplus/classes/RbPlusPlus/Writers/MultipleFilesWriter.html publish/rbplusplus/classes/RbPlusPlus/Writers/SingleFileWriter.html publish/rbplusplus/created.rid publish/rbplusplus/files/README.html publish/rbplusplus/files/lib/inflections_rb.html publish/rbplusplus/files/lib/inflector_rb.html publish/rbplusplus/files/lib/rbplusplus/builders/base_rb.html publish/rbplusplus/files/lib/rbplusplus/builders/class_rb.html publish/rbplusplus/files/lib/rbplusplus/builders/enumeration_rb.html publish/rbplusplus/files/lib/rbplusplus/builders/extension_rb.html publish/rbplusplus/files/lib/rbplusplus/builders/module_rb.html publish/rbplusplus/files/lib/rbplusplus/builders/types_manager_rb.html publish/rbplusplus/files/lib/rbplusplus/extension_rb.html publish/rbplusplus/files/lib/rbplusplus/module_rb.html publish/rbplusplus/files/lib/rbplusplus/rbplusplus_rb.html publish/rbplusplus/files/lib/rbplusplus/transformers/class_rb.html publish/rbplusplus/files/lib/rbplusplus/transformers/constructor_rb.html publish/rbplusplus/files/lib/rbplusplus/transformers/function_rb.html publish/rbplusplus/files/lib/rbplusplus/transformers/method_rb.html publish/rbplusplus/files/lib/rbplusplus/transformers/module_rb.html publish/rbplusplus/files/lib/rbplusplus/transformers/node_cache_rb.html publish/rbplusplus/files/lib/rbplusplus/transformers/node_rb.html publish/rbplusplus/files/lib/rbplusplus/transformers/node_reference_rb.html publish/rbplusplus/files/lib/rbplusplus/transformers/rbgccxml_rb.html publish/rbplusplus/files/lib/rbplusplus/writers/base_rb.html publish/rbplusplus/files/lib/rbplusplus/writers/extension_rb.html publish/rbplusplus/files/lib/rbplusplus/writers/multiple_files_writer_rb.html publish/rbplusplus/files/lib/rbplusplus/writers/single_file_writer_rb.html publish/rbplusplus/files/lib/rbplusplus_rb.html publish/rbplusplus/fr_class_index.html publish/rbplusplus/fr_file_index.html publish/rbplusplus/fr_method_index.html publish/rbplusplus/index.html publish/rbplusplus/rdoc-style.css website/Rakefile 61e0b4e0ecf3f23db79d240a2b85dcf7976ea539 Jason Roelofs jameskilton@gmail.com http://github.com/jameskilton/rbplusplus/commit/11bba6ce0f225515365feaa3e9a0bebb2189dfd3 11bba6ce0f225515365feaa3e9a0bebb2189dfd3

2008-07-18T11:55:07-07:00

publish dir to be ignored, got site going with webgen 0.4.7 5333af82b05bcfb617a737ea0a913e96de3ca1f7 Jason Roelofs jameskilton@gmail.com