README.txt

   1 ==============
   2 Blocks Runtime
   3 ==============
   4 This project provides a convenient way to install the BlocksRuntime library
   5 from the compiler-rt project (see http://compiler-rt.llvm.org/).
   6
   7 Several systems (Linux, FreeBSD, MacPorts, etc.) provide the clang compiler
   8 either preinstalled or as an available package which has Blocks support
   9 (provided the -fblocks compiler option is used).
  10
  11 Unfortunately, those installer packages do not provide the Blocks runtime
  12 library.
  13
  14 On the other hand, the compiler-rt library can be downloaded and does contain
  15 the Blocks runtime support if properly enabled in the cmake build file.
  16
  17 By default, however, the compiler-rt library also builds a compiler runtime
  18 support library which is undesirable.
  19
  20 This project contains only the BlocksRuntime files (in the BlocksRuntime
  21 subdirectory) along with tests (in the BlocksRuntime/tests subdirectory) and
  22 the original CREDITS.TXT, LICENSE.TXT and README.txt from the top-level
  23 compiler-rt project (which have been placed in the BlocksRuntime subdirectory).
  24
  25 -------
  26 License
  27 -------
  28 The compiler-rt project (and hence the BlocksRuntime since it's a part of that
  29 project) has a very liberal dual-license of either the UIUC or MIT license.
  30 The MIT license is fully GPL compatible (and pretty much compatible with just
  31 about everything), so there should be no problems linking the
  32 libBlocksRuntime.a library with your executable.  (Note that on the FSF's site
  33 [http://www.gnu.org/licenses/license-list.html], you find the MIT license under
  34 the 'X11 License' section.)  See the LICENSE.TXT file in the BlocksRuntime
  35 subdirectory for all the details.
  36
  37 --------
  38 Building
  39 --------
  40 Since there are only two files to build, a makefile didn't seem warranted.  A
  41 special config.h file has been created to make the build work.  Build the
  42 libBlocksRuntime.a library by running:
  43
  44   ./buildlib
  45
  46 The gcc compiler will be used by default, but you can do "CC=clang ./buildlib"
  47 for example to use the clang compiler instead.  Note that neither make nor
  48 cmake are needed (but ar and ranlib will be used but they can also be changed
  49 with the AR and RANLIB environment variables similarly to the way the compiler
  50 can be changed).
  51
  52 IMPORTANT Mac OS X Note:  If you are building this library on Mac OS X (presumably
  53 to use with a clang built with MacPorts or otherwise obtained), you probably want
  54 a fat library with multiple architectures in it.  You can do that with the CFLAGS
  55 variable like so:
  56
  57   CFLAGS='-O2 -arch x86_64 -arch ppc64 -arch i386 -arch ppc' ./buildlib
  58
  59 -------
  60 Testing
  61 -------
  62 Skip this step at your peril!  It's really quite painless.  You see it's
  63 possible that the underlying blocks ABI between the blocks runtime files
  64 provided in this project and the blocks ABI used by your version of the clang
  65 compiler to implement the -fblocks option have diverged in an incompatible way.
  66 If this has happened, at least some of the tests should fail in spectacular
  67 ways (i.e. bus faults).  For that reason skipping this step is not recommended.
  68
  69 You must have the clang compiler with -fblocks support installed for this step
  70 (if you don't have a clang compiler with -fblocks support available, why bother
  71 installing the Blocks runtime in the first place?)  Run the tests like so:
  72
  73   ./checktests
  74
  75 Problems are indicated with a line that starts "*** ^FAILURE:".  You will
  76 probably see one of these when the copy-block-literal-rdar6439600.c test is
  77 run.  Yes, this is a real failure.  No it's not a bug in the Blocks runtime
  78 library, it's actually a bug in clang.  You may want to examine the
  79 copy-block-literal-rdar6439600.c source file to make sure you fully grok the
  80 failure so you can avoid getting burned by it in your code.  There may be a fix
  81 in the clang project by now (but as of the clang 2.9 release it still seems to
  82 fail), however it may be a while until it rolls downhill to your clang package.
  83
  84 Note that if you have an earlier version of clang (anything before version 2.8
  85 see clang -v) then clang++ (C++ support) is either incomplete or missing and
  86 the few C++ tests (.C extension) will be automatically skipped (if clang++ is
  87 missing) or possibly fail in odd ways (if clang++ is present but older than
  88 version 2.8).
  89
  90 ----------
  91 Installing
  92 ----------
  93 Assuming that you have built the library (with ./buildlib) and are satisfied it
  94 works (./checktests) then it can be installed with:
  95
  96   sudo ./installlib
  97
  98 The default installation prefix is /usr/local, but can be changed to /myprefix
  99 like so:
 100
 101   sudo sh -c 'prefix=/myprefix ./installlib'
 102
 103 The include file (Block.h) is installed into $prefix/include and the library
 104 (libBlocksRuntime.a) into $prefix/lib by default.  (Those can also be changed
 105 by setting and exporting includedir and/or libdir in the same way prefix can be
 106 changed.)
 107
 108 If you want to see what will be installed without actually installing use:
 109
 110   ./installlib --dry-run
 111
 112 -----------
 113 Sample Code
 114 -----------
 115 After you have installed the Blocks runtime header and library, you can check
 116 to make sure everything's working by building the sample.c file.  The
 117 instructiions are at the top of the file (use head sample.c to see them) or
 118 just do this:
 119
 120   clang -o sample -fblocks sample.c -lBlocksRuntime && ./sample
 121
 122 If the above line outputs "Hello world" then your Blocks runtime support is
 123 correctly installed and fully usable.  Have fun!
 124
 125 Note that it's possible to use the Blocks runtime without installing it into
 126 the system directories.  You simply need to add an appropriate -I option to
 127 find the Block.h header when you compile your source(s).  And a -L option to
 128 find the libBlocksRuntime.a library when you link your executable.  Since
 129 libBlocksRuntime.a is a static library no special system support will be needed
 130 to run the resulting executable.
 131
 132 -------------
 133 Documentation
 134 -------------
 135 You can find information on the Blocks language extension at these URLs
 136
 137   http://clang.llvm.org/docs/LanguageExtensions.html#blocks
 138   http://clang.llvm.org/docs/BlockLanguageSpec.txt
 139   http://developer.apple.com/library/mac/documentation/Cocoa/Conceptual/Blocks
 140   http://developer.apple.com/library/mac/documentation/cocoa/Conceptual/Blocks/Blocks.pdf