@@ -1 +1,56 @@
1−# purecc
1+[](http://purescript.org)
2+
3+This is an experimental C++(11+)/native compiler backend for [PureScript](https://github.com/purescript/purescript). It attempts to generate "sane", debuggable, and portable C++ code as an intermediate language, which is then compiled to a native executable binary. This enables easy interoperability with existing C/C++ frameworks and libraries on a number of platforms.
4+
5+---
6+
7+#### Performance
8+
9+* No runtime system (beyond some support classes and the standard C++(11+) runtime library)
10+* For automatic memory management, uses native C++(11+) reference counting (`std::shared_ptr`)
11+* Uses PureScript's normal tail call optimization techniques for generated C++ code
12+
13+#### Differences from PureScript:
14+
15+* Foreign imports are C++(11+) (or C) instead of JavaScript ([FFI examples](https://github.com/andyarvanitis/purescript-native/wiki/FFI_Examples))
16+* Compiler is `purecc` instead of `purs`, `make` is recommended for building
17+* No C++-specific REPL
18+
19+#### Other notes:
20+
21+* PureScript arrays are implemented using [`std::deque`](http://en.cppreference.com/w/cpp/container/deque) (random access *O(1)*)
22+* `String` types are implemented using either C-strings (for literals) or `std::string`
23+* `Number` is C++ `double`, `Int` is C++ `int`, `Char` is `std::string` (single utf-8 entity), `Boolean` is `bool`
24+
25+#### Future ideas:
26+
27+* Nice facilities (modules) for concurrency/parallelism, using `std::thread`, `std::async`, etc. under the hood
28+* `BigInt` via GNU GMP (or an alternative)
29+
30+#### Requirements
31+
32+* [Haskell Stack](https://docs.haskellstack.org/en/stable/README/) (if you're running macOS 10.13+, you can use pre-built binaries from [here](https://github.com/andyarvanitis/purescript-native/releases/))
33+* A C++11-capable toolchain, e.g. recent versions of clang, gcc, Microsoft Visual Studio 2015
34+* GNU Make is the default supported build tool, but you should be able to use your favorite C++ build system, tools, debuggers, etc.
35+
36+#### Getting Started
37+This assumes you are running OS X or a Unix-like system (Linux, *BSD, etc.).
38+
39+If you're running macOS 10.13+ (High Sierra or later), you can avoid building it yourself by using these [pre-built snapshot binaries](https://github.com/andyarvanitis/purescript-native/releases/), but make sure you've installed a recent version of [purescript](https://github.com/purescript/purescript/releases) first.
40+
41+1. Make sure you have developer tools for your system installed. For OS X, you'll need a recent version of Xcode. For Linux, etc., you need gcc 4.9.2 or later, including g++ support. You can also use clang 3.5 or later, but it still requires gcc for its C++ standard libraries.
42+
43+2. Create a working directory wherever you like, and a `src` subdirectory under it, which will be where you will place your own PureScript source files.
44+
45+3. Under your working directory, also create an `ffi` subdirectory, which will be where you will place your own C/C++ FFI source files.
46+
47+4. Copy the [`Makefile`](https://github.com/andyarvanitis/purescript-native/blob/native-dump-corefn/support/Makefile) into your working directory.
48+
49+5. Use PureScript's standard `psc-package` utility to add and manage package dependencies.
50+
51+6. You should now be ready to build a PureScript program.
52+ * As stated above, place your source file(s) in the working directory's `src` subdirectory and execute `make`. If your machine has multiple cores, you might want to use `make -jN`, where `N` is the number of cores.
53+
54+ * This will generate the C++ source tree for your program and then build an executable binary. The resulting executable will be in the `bin` subdirectory under the output directory and called `main` (so `output/bin/main`, by default). Source files will be in output/src/...
55+
56+---