From 3e770e8d8b8552f33039f073e4862c74096f33b5 Mon Sep 17 00:00:00 2001 From: Hostile Fork Date: Thu, 14 Jan 2016 03:00:20 -0500 Subject: [PATCH] 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. --- README.md | 205 +++++++++++++++--------------------------------------- 1 file changed, 55 insertions(+), 150 deletions(-) diff --git a/README.md b/README.md index f5a2172833..6dfbc180b7 100644 --- a/README.md +++ b/README.md @@ -1,182 +1,87 @@ -![Ren/C logo](https://raw.githubusercontent.com/metaeducation/ren-c/master/ren-c-logo.png) +![Ren-C Logo][100] # Ren/C -[![Build Status](https://travis-ci.org/metaeducation/ren-c.svg?branch=master)](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