forked from metaeducation/ren-c
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Turn README.md into mostly a redirect page
Because the README.md is in the repository (and held also to the 80 column rule), it is not convenient to update like a wiki or Trello. This reduces the amount of content in the file. Ultimately it should have examples of how to call the library when that is ready to publish.
- Loading branch information
1 parent
ed0ea34
commit 3e770e8
Showing
1 changed file
with
55 additions
and
150 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,182 +1,87 @@ | ||
|  | ||
| ![Ren-C Logo][100] | ||
|
|
||
| # Ren/C | ||
| [](https://travis-ci.org/metaeducation/ren-c) | ||
| [![Build Status][101]](https://travis-ci.org/metaeducation/ren-c) | ||
|
|
||
| **Ren/C** is an interim fork of the open sourced | ||
| [Rebol](http://en.wikipedia.org/wiki/Rebol) codebase. It has many goals: | ||
|
|
||
| * To create a library form of the interpreter, which is focused on providing | ||
| the full spectrum of Rebol's internals to other projects. This is to open | ||
| up possibilities for linking to new IDEs, debuggers, and consoles (such as | ||
| [Ren Garden](https://www.youtube.com/watch?v=0exDvv5WEv4)). It will also be | ||
| the basis for language bindings like [Ren/C++](http://rencpp.hostilefork.com/). | ||
| **Ren-C** is an interim fork of the [Apache 2.0 open-sourced][1] [Rebol][2] codebase. The | ||
| goal of the project isn't to be a new language or a different console, rather to provide | ||
| a smooth API for embedding a Rebol interpreter in C programs. This API would offer | ||
| nearly the full range of power that is internally offered to the core, making it | ||
| easy to write new clients or REPLs using it. | ||
|
|
||
| * To un-fork the divergence between the community build of Rebol based on the | ||
| [12-Dec-2012 open-sourced code](http://www.rebol.com/cgi-bin/blog.r?view=0519) | ||
| and the codebase built on pre-open-source code at Saphirion, later maintained | ||
| by [Atronix Engineering](http://atronixengineering.com/downloads.html). | ||
| [1]: http://www.rebol.com/cgi-bin/blog.r?view=0519 | ||
| [2]: https://en.wikipedia.org/wiki/Rebol | ||
|
|
||
| * To accelerate the process by which consensus features and fixes are | ||
| integrated into the language. Though debates continue over features in | ||
| [Rebol and Red Chat](http://rebolsource.net/go/chat-faq), many changes are | ||
| ready and agreed upon -- some submitted as patches. Yet they haven't had a | ||
| focal location where they can be launched and people get new builds. | ||
| Because the API is not fully ready for publication, the current way to explore the new | ||
| features of Ren-C is using the `r3` console built by the makefile. It should function | ||
| nearly identically (though it has been extended through user contribution to support a | ||
| multi-line continuation method similar to Rebol2.) For those interested in a more | ||
| novel application of the Ren-C library, see the C++ binding and [Ren Garden][3]. | ||
|
|
||
| * To integrate the test suite into the build, and make the bar obvious that | ||
| contributions must meet by keeping it at zero errors. The Valgrind and | ||
| Address Sanitizer tools are being integrated into the build and test process, | ||
| with modifications to the code to prevent masking bugs. | ||
| [3]: http://rencpp.hostilefork.com | ||
|
|
||
| * To provide an option for stable open-source bootstrapping to be used by the | ||
| [Red Language](http://www.red-lang.org/p/about.html), which is currently | ||
| bootstrapped from closed-source Rebol 2. *(Red's roadmap goal is to move | ||
| directly to a self-hosting state from the Rebol 2 codebase. This may be | ||
| a poorer option than moving to an improved Rebol 3 as an interim step.)* | ||
| In the process of designing the library, Ren-C also aspires to solve several of the | ||
| major outstanding design problems that were left unfinished in the R3-Alpha codebase. | ||
| Several of these problems have been solved already--and for progress and notes on | ||
| these issues, a [Trello board][4] is frequently updated to reflect a summary of | ||
| some of the changes. | ||
|
|
||
| [4]: https://trello.com/b/l385BE7a/rebol3-porting-guide-ren-c-branch | ||
|
|
||
| ## Building | ||
|
|
||
| First get the sources -- either from cloning the repository with git, or | ||
| [Downloading a ZIP](https://github.com/metaeducation/ren-c/archive/master.zip). | ||
| Next you need to [get a pre-built Rebol 3 interpreter](http://rebolsource.net), | ||
| rename it to `r3-make` or `r3-make.exe`, and put it in the `%make/` | ||
| subdirectory. | ||
|
|
||
| Then run: | ||
|
|
||
| make -f makefile.boot | ||
|
|
||
| The platform to target will be assumed to be the same as the build type of | ||
| the `r3-make` you use. If your needs are more complex *(such as doing a | ||
| cross-compilation, or if the `system/version` in your r3-make doesn't match | ||
| the target you want)*, refer to the bootstrap makefile | ||
| [`%src/make/makefile.boot`](https://github.com/metaeducation/ren-c/blob/master/make/makefile.boot). | ||
|
|
||
|
|
||
| ## Methodology | ||
|
|
||
| The Atronix/Saphirion build diverged from Rebol at a point in time prior to | ||
| its release as an Apache-licensed open-source project. Their build had a | ||
| graphical user interface and several other additional features, but was only | ||
| available for Windows and Linux. | ||
|
|
||
| Ren/C split out a "Core" build from the Atronix/Saphirion branch, which runs | ||
| as a console process and does not require GUI support. It was then audited to | ||
| build under strict ANSI C89, C99, and C11. It also added the *option* to build | ||
| as strict ISO C++98, C++11, and C++14. The goal is to take advantage of | ||
| stronger type-checking and metaprogramming, while still retaining the ability | ||
| to do a complete build on very old compilers when `__cplusplus` is not defined. | ||
|
|
||
| Consequently, Ren/C brings all the non-GUI features added by Atronix and | ||
| Saphirion to core builds for other systems (OS/X 32-bit and 64-bit, HaikuOS, | ||
| Raspberry Pi, etc.) It also allows users who are not interested in the GUI to | ||
| use lighter builds on Windows and Linux. | ||
|
|
||
| Besides building under these ranges of languages, Ren/C can do so under both | ||
| GCC and Clang with zero warnings (with as strict warnings as reasonable). | ||
| [Significant changes](https://github.com/metaeducation/ren-c/pull/12) are | ||
| needed to do this, which are being given heavy thought on how to make things | ||
| simpler, clearer, and better-checked. Across the board the code is more | ||
| readable than what came in, with notable simplifications and improved checks. | ||
| In doing this work, the hope is to provide an artifact that would rally common | ||
| usage between the [mainline builds][5], community builds, and those made by | ||
| [Atronix Engineering][6] and [Saphirion AG][7]. | ||
|
|
||
| *(Note: Ultimately the goal is that Ren/C will not be something Rebol end-users | ||
| will be aware of, but a library facing those building software that links to | ||
| the evaluator. Hence systems like Rebol and Ren Garden would be branded as | ||
| interfaces and consoles using the core interpreter, and Ren/C would contain | ||
| no 'main.c'. Getting to that point will take a while, and in the meantime | ||
| Ren/C produces a traditional Rebol executable as part of its build process.)* | ||
| [5]: http://rebolsource.net | ||
| [6]: http://www.atronixengineering.com/downloads | ||
| [7]: http://development.saphirion.com/rebol/saphir/ | ||
|
|
||
| For more information, please visit the FAQ: | ||
|
|
||
| ## Features | ||
| https://github.com/metaeducation/ren-c/wiki/FAQ | ||
|
|
||
| New features available in Ren/C's console builds vs. the open-sourced Rebol | ||
| codebase of 12-Dec-2012 are: | ||
| Feel free to add your own questions to the bottom of the list. | ||
|
|
||
| * HTTPS support as a protocol written in Rebol code, empowered by underlying | ||
| cryptography libraries incorporated the C code. (Originally contributed by | ||
| Saphirion.) | ||
|
|
||
| * A foreign function interface | ||
| (["FFI"](https://en.wikipedia.org/wiki/Foreign_function_interface)), which | ||
| allows Rebol to load a shared library and then directly call functions in it. | ||
| This implementation is based on [libffi](http://sourceware.org/libffi/), | ||
| and brings new datatypes for interfacing with native libraries, such as | ||
| LIBRARY!, ROUTINE!, and STRUCT!. (Originally contributed by Atronix.) | ||
|
|
||
| > Note: Building Ren/C with the FFI currently requires additional steps or | ||
| > package, installation, as the FFI library has not been extracted into code | ||
| > following Rebol's build process. | ||
| * `CALL` with support for standard input/output redirection (also known as | ||
| `/INPUT`, `/OUTPUT`, and `/ERROR`). (Originally contributed by Atronix.) | ||
|
|
||
| * UDP Network Scheme (Originally contributed by Atronix.) | ||
|
|
||
| * Serial port support on Linux and Windows. (Originally written by Carl | ||
| Sassenrath, completed & integrated by Joshua Shireman, extended by Atronix.) | ||
|
|
||
| * Ability to make use of native 64-bit math builtins provided by the | ||
| compiler/math library, where available. (Originally contributed by Atronix.) | ||
|
|
||
|
|
||
| ## Platforms | ||
| ## Community | ||
|
|
||
| As of 16-Jul-2015, Ren/C has been verified as reaching the goal of building | ||
| across the standards-compliant spectrum of C or C++ without warnings on | ||
| these desktop platforms: | ||
| To promote the Rebol community's participation in public forums, development discussion | ||
| for Ren-C generally takes place in the [Rebol and Red StackOverflow Chat][8]. | ||
|
|
||
| * Linux 32-bit x86 (`OS_ID=0.4.04`) | ||
| * Linux 64-bit x86 (`OS_ID=0.4.40`) | ||
| * Windows 32-bit x86 (`OS_ID=0.3.01`) | ||
| * Windows 64-bit x86 (`OS_ID=0.3.40`) | ||
| * OS/X 32-bit x86 (`OS_ID=0.2.05`) | ||
| * OS/X 64-bit x86 (`OS_ID=0.2.40`) | ||
| [8]: http://rebolsource.net/go/chat-faq | ||
|
|
||
| It has additionally been built for: | ||
| It is also possible to contact the developers through the [Ren-C GitHub Issues][9] | ||
| page. This should be limited to questions regarding the Ren-C builds specifically, as | ||
| overall language design wishes and debates are kept in the `rebol-issues` repository | ||
| of Rebol's GitHub. | ||
|
|
||
| * Linux 32-bit ARM, on Raspberry Pi (`OS_ID=0.4.20`) | ||
| * OS/X 32-bit PowerPC (`OS_ID=0.2.04`) | ||
| * HaikuOS 32-bit x86 (`OS_ID=0.5.75`) | ||
| * SyllableOS Desktop 32-bit x86 (`OS_ID=0.14.01`) | ||
| [9]: https://github.com/metaeducation/ren-c/issues | ||
|
|
||
| Here are the warnings enabled (manually in the makefile, at the moment): | ||
|
|
||
| > --pedantic -Wextra -Wall -Wchar-subscripts -Wwrite-strings | ||
| > -Wdeclaration-after-statement -Wundef -Wformat=2 -Wdisabled-optimization | ||
| > -Wcast-qual -Wlogical-op -Wstrict-overflow=5 -Wredundant-decls -Woverflow | ||
| > -Wpointer-arith -Wall -Wparentheses -Wmain -Wsign-compare -Wtype-limits | ||
| > -Wpointer-sign | ||
| ## Building | ||
|
|
||
| These warnings are disabled (manually in the makefile, at the moment): | ||
| First get the sources -- from cloning the repository with `git`, or downloading a ZIP: | ||
|
|
||
| > -Wno-unused-variable -Wno-unused-parameter -Wno-long-long -Wno-switch | ||
| https://github.com/metaeducation/ren-c/archive/master.zip | ||
|
|
||
| Next you need to [get a pre-built R3-Alpha interpreter](http://rebolsource.net), rename | ||
| it to `r3-make` or `r3-make.exe`, and put it in the `%make/` subdirectory. | ||
|
|
||
| ## Viability | ||
| Then run: | ||
|
|
||
| It's important to mention that the features written by Saphirion and Atronix | ||
| were added using a methodology driven more by customer needs vs. philosophical | ||
| or language purity. Several of the features rely on an incomplete codec | ||
| extension model in Rebol 3, which was neither clearly articulated, nor is it | ||
| apparent what separation of concerns it set out to guarantee. Many other | ||
| aspects -- such as adding additional device ports -- is not as decoupled or | ||
| modular as it should be. | ||
| make -f makefile.boot | ||
|
|
||
| Disclaimer aside, the features reflect concrete needs of the user base, and | ||
| *have been used in deployment*. While the implementations may not be perfect, | ||
| they're building in a more rigorous compilation environment, and have already | ||
| been organized a bit. So they can be studied for the proper model of extension | ||
| and extraction, starting from a basis of code that does function. | ||
| The platform to target will be assumed to be the same as the build type of the | ||
| `r3-make` you use. If your needs are more complex *(such as doing a cross-compilation, | ||
| or if the `system/version` in your r3-make doesn't match the target you want)*, refer | ||
| to the bootstrap makefile `%src/make/makefile.boot`: | ||
|
|
||
| https://github.com/metaeducation/ren-c/blob/master/make/makefile.boot | ||
|
|
||
| ## Community | ||
| *(Note: Ren-C's build process cannot be performed with Rebol2. It requires R3-Alpha | ||
| or Ren-C itself. However, it can build using an old pre-open-source R3-Alpha A111.)* | ||
|
|
||
| If you have been invited as a stakeholder in this project with write | ||
| access to the repository, it is not necessarily for your C programming | ||
| skillset. Rather it is a way of asking for your buy-in with a sort of | ||
| "paying it forward" and trusting you with the power to (for instance) | ||
| triage and dismiss issues out of the Issue ticketing database. | ||
|
|
||
| Discussion for this project is on | ||
| [SO Chat](http://rebolsource.net/go/chat-faq). | ||
| [100]: https://raw.githubusercontent.com/metaeducation/ren-c/master/ren-c-logo.png | ||
| [101]: https://travis-ci.org/metaeducation/ren-c.svg?branch=master |