README

   1
   2 The Lightweight C++ Preprocessor
   3 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   4
   5 The lightweight c++ preprocessor adds a rich set of extensions
   6 to the C programming language -- some of which are borrowed from
   7 C++ and some new ones.
   8
   9 Supported Systems
  10 -----------------
  11
  12 lwc has only been tested on a gcc-3.2/glibc system.
  13 Anything else may not work.
  14
  15 In order to run lwc there must be a C preprocessor "cpp"
  16 In order to use the code produced by lwc
  17  the compiler must support C99 and some common GNU-C extensions
  18  and the linker must support ".gnu.linkonce" sections
  19
  20 Install
  21 -------
  22
  23 To install lwc type 'make'
  24
  25 Hopefully the executable "lwc" will appear in objdir.
  26
  27
  28 Running
  29 -------
  30 The simple way to use lwc is with the command:
  31
  32         lwc file.c
  33
  34 The command line arguments of lwc are the same of
  35 the C preprocessor 'cpp'.
  36
  37 The generated C code is printed on stdout.
  38
  39 Output
  40 ------
  41
  42 Usually in makefiles lwc code will be compiled with two
  43 targets:
  44
  45         file.o: file.i
  46                 gcc file.i -o file.o -fexceptions
  47
  48         file.i: file.c header.h
  49                 lwc file.c > file.i
  50
  51 It's a very good idea to have the latest version of "indent".
  52 lwc does not detect all errors and very often you may have
  53 to browse through the generated C code to see what's wrong.
  54
  55 In this first release of lwc, debugging information is compiled in
  56 and you can create a file /tmp/LWCD_OUTPUT_INDENTED to force
  57 lwc to automatically pass the output through "indent".
  58 (create this file right now if you want)
  59
  60 If the version of indent in your system is < 2 then you'd better
  61 download the latest version which is >= 2.2.9
  62 Old versions can't format compound statements in expressions.
  63
  64 What can you do with lwc
  65 ------------------------
  66
  67 1. Program !
  68
  69 2. Study C++ to C conversion basics
  70
  71 3. Add new features to the lwc language
  72
  73 4. Do advanced OOP language research / test new stuff for the next C++
  74 draft!
  75
  76 5. ??
  77
  78 6. Profit!
  79
  80 Programming
  81 -----------
  82
  83   Unlike other languages you are not forced to use OOP features.
  84 You can simply use lwc for the structure-by-reference convenience,
  85 for the member functions or even just for the ability to omit
  86 'struct' and 'enum'.  You are not forced to consider "everything is
  87 an object".
  88
  89   If you want to use lwc for programming read the short tutorial in 'doc'
  90 and have a look at the sample lwc programs included in the package.
  91
  92   At the moment lwc may support some weird things and may not support others.
  93 For an example of "weird thing", a structure can be declared in a cast.
  94
  95   The fact that this works does not mean you should do it: It may be disabled
  96 in a future version and your program will no longer compile.
  97 So use common sense.  lwc works fine with all the reasonable things you may
  98 ever need to do.
  99
 100   If you are distributing executables then you can go directly into using lwc.
 101
 102   If you don't want to bother with executables and you prefer giving the
 103 source, then you should know that lwc needs to be installed on the
 104 target system.  The C code produced from lwc is preprocessed and therefore
 105 very possibly not portable.  Of course you can demand library/architecture
 106 compatibility, but this is as bad as executables.
 107
 108  On the other hand, because lwc functions can call normal C functions
 109 you can include plain C files in your lwc code, which are wrappers
 110 to the system's libraries.  lwc code can call these wrappers instead
 111 of including system header files.
 112
 113  In this sense lwc gives a new meaning to open source.  It is possible
 114 to distribute only the generated C files and not the lwc ones.  This way
 115 others can study the code but they can't edit it.  We are against that.
 116 But it is possible to give the lwc code by request to track the hacker base.
 117
 118 Adding new Features
 119 -------------------
 120                 ``making standards is quite a challenge.
 121                   breaking through them is quite another''
 122
 123   Adding new features to the language is very easy.  We can have delegates
 124 tomorrow.  C++-like templates *are* possible. It's also easy to implement
 125 operator overloading for all the operators, pointer-to-member operators,
 126 contracts, attributes, properties, singletons  and generally everything
 127 you see in other programming languages.
 128
 129   On the other hand, it is believed that designing a programming language is not
 130 only about the imagination to conceive features but also about the wisdom
 131 to avoid some of them.  This is the K&R logic as displayed in the excellent
 132 book "The C Programming Language".  We wouldn't want to become the most
 133 over-bloated programming language of the world - C is a spartan language
 134 afterall...
 135
 136 Anyway, there's a mailing list for lwc news, bugs, devel and discussion at:
 137
 138         http://mail.nongnu.org/mailman/listinfo/lwc-list
 139
 140 Bugs
 141 ----
 142
 143   If lwc crashes or produces invalid C code, be patient. Please post a
 144 report to the mailing list and it will be fixed ASAP.
 145
 146 Credits
 147 -------
 148
 149 lwc initial versions written & Copyright (C) 2003, 2004 Stelios Xanthakis.
 150
 151 lwc latest download: http://students.ceid.upatras.gr/~sxanth/lwc/