#summary Explanation of Pas2C and how to build it

#labels Phase-Implementation

==Introduction==

Pas2C is an alternative way to build the engine. It is disabled by default.

Pas2C is intended to be used when building the engine natively (e.g. with !FreePascal) fails for some reason. However, Pas2C does have some limitations and you should try to first build Hedgewars normally before attempting a Pas2C build.

Pas2C is our hand-written Pascal-to-C-compiler. It works by converting all Pascal code to C, and then compiling the C code with a C compiler. Pas2C itself is written in Haskell. Yes, we're a little crazy. :-)

==Limitations==

The Pas2C build currently doesn't support the video recorder. A warning will be printed if you try to build a Pas2C build with video recorder support anyway.

== Building ==

===Caveats===

Note! In version 1.0.0, if your `LOCALE` is set to `C`, building will fail with an error like this:

{{{

Preprocessing 'uSound.pas'... pas2c: /builddir/build/BUILD/hedgewars-src-1.0.0/hedgewars/uSound.pas: hGetContents: invalid argument (invalid byte sequence)

}}}

This is because Wuzzy accidentally added Unicode characters in the Pascal source code, something which Pas2C doesn't like.

If you have this problem, run this shell script in the root of the source directory before building:

{{{

for file in hedgewars/uSound.pas hedgewars/uStats.pas; do

    iconv -f utf-8 -t ascii//TRANSLIT $file -o $file.tmp;

    mv $file.tmp $file;

done

}}}

This will be fixed in the next version.

===Automatic===

Configure with `cmake -DBUILD_ENGINE_C=1` and then run `make`.

===Manual run===

Run from the `tools` folder

{{{

ghc -e pas2C \"hwengine\"" pas2c.hs

}}}

You can replace "hwengine" with any other module.

Every pas file will be converted to a .c/.h version in the `hedgewars` folder. In case no output is produced something has gone wrong.

Use `clang` to compile, `gcc` compatibility is not yet achieved. We are curious to hear about `icc` and `msvc` (not that we expect anything...)

==Development==

There are some special files that you need to know:

  * `project_files/hwc/rtl/fpcrtl.h` - contains definitions of external functions defined inside custom pascal units (e.g. `SDLh.pas`);

  * `hedgewars/pas2cSystem.pas` - contains definitions of external functions defined outside our own pascal units (e.g. png and gl units, bundled with !FreePascal);

  * `hedgewars/pas2cRedo.pas` - contains definitions of internal fpc units (provided by the `rtl`) which get a `fpcrtl_` prefix.

If you need to hide portions of code from Pas2C just wrap it with `${IFNDEF PAS2C}...{$ENDIF}`.

To ensure compability with Pas2C, you also must obey the rules stated here: [PascalSyntax]