R3 Host Kit
| Contents | ||
Details related to building the REBOL host environment.
The A104 and A105 Host-Kit changes are disruptive.
See the change log and blogs for notes and diagrams.
A107 changes the defines used to build the host-kit. This doc might be inaccurate and will be updated.
Start Here
What is it?
The Host-Kit lets you build custom versions of REBOL 3, making it possible to add your own special C and REBOL code functions, or embed REBOL itself within other programs.
See embedded extensions for documentation on how to add custom extensions at program startup time.
Reporting Problems
R3 Chat is the primary archive for notes, comments, feedback, and changes. To get started, type "chat" at the R3 prompt. Most users only need about five commands. Type "help" to get R3 DevBase Chat Forum. In chat, type 32 to enter the Host-Kit (Host-Lib) topic.
Other Info
See the REBOL 3 Change Log: 2010 for details about each release.
Open developer notes and suggestions can be found at www.rebol.net/wiki/R3_Host_Kit_Addendum. It's not official, but can be useful.
Quick Builds
As of A105 we've started including various project make files:
- MS Visual C 9
Open make-vc9 dir, click and build. - MS Visual C 6
Open make-vc6 dir, click and build. - CodeBlocks
Open make-cbp dir. Copy up one dir and build. - GCC Makefile
In make-gcc dir. Copy up one dir and build.
Then, to run R3, you must have the r3lib.dll in the same directory as the exe.
Custom Builds
To create your own project makefile, you can follow these basic steps (Win32 example):
- Add these source files
- src/os .c files, but not files that begin with "host-ext" or "host-init"
- src/os/win32 .c files
- src/agg .cpp files, but not agg-freetype (used for Linux, etc.)
- For compiler preprocessor
- Add include path: ..\include
- Define: UNICODE and REB_LIB
- For compiler code generation
- Select 4 byte alignment (packed)
- Select the multi-threaded runtime DLL
- For linker
- Add library path: ..\lib
- Add libraries: r3lib.lib wsock32.lib (if missing)
- To run
- Copy ..\lib\r3lib.lib to your exe directory
- Run the exe
For Linux, BSD, OS X, and other systems, it's roughly the same, but include agg-freetype and not agg-truetype for fonts.
Build Details
The R3 build philosophy is to keep it simple and it is our goal to keep it that way.
Keep in mind that we build R3 on different operating systems. What may work in one, doesn't always work in another. Therefore, we try to stick with basic make methods.
MinGW C
The distribution includes a standard makefile that you can use for Unix-like systems including MinGW (Min-GNU for Windows). We assume you've already downloaded and set-up MinGW, including the necessary environment variables.
Now, do this:
- In mingw/bin copy ming32-make.exe to just make.exe.
- In a command shell, go to your r3 dir and type "make".
- Watch it compile and link.
- Type "r3" to run the new r3 exe.
Note that in the default configuration, the DLL is linked at run time. So, it needs to be in the same dir as r3.exe. Of course, you can build-it-in if you want it as a single exe.
MS Visual Studio
We've included two project files; one for VC9 the other for VC6.
If you make changes, be sure to use UNICODE and proper struct alignment, or your build will be defective.
If you create a new project file, follow the bullet points listed above.
Linux
The distribution includes a standard makefile. The build is very easy to do.
- Type: make
- The compiler should run and link with the .so and produce an executable.
- You can either install the .so, or keep it local (advised for now).
For a local .so you will need to add your local dir to the loader's lib path, for example:
LD_LIBRARY_PATH=.:$LD_LIBRARY_PATH export LD_LIBRARY_PATH
Or, you can make a lib/ dir, such as ~/lib and put it there.
Important Notes
Memory Allocation
The OS and the REBOL lib use different memory allocation methods. In addition, some OSes (or other environments, like web browsers) may require specific methods of allocation for special management.
Currently, we use this simple rule: Use the OS allocator for OS data; use the REBOL allocator for REBOL data. Don't mix the two.
It's probably going to get more complex as we go. More info will be posted here.
Dealing with Unicode
Unicode complicates a lot of things, especially on Win32. There are some critical things to know, and not all of us have a strong desire to learn them, but unfortunately, you need at least the basics.
First, if you're using Windows, then you must define the UNICODE symbol in order to be directed to the correct system APIs. If you're using Linux, BSD, or other systems that are based on UTF-8, then this is not required, but be sure to keep in mind that a single "character" may require multiple bytes. Be sure to learn the basics of UTF-8 because it changes a lot of the rules of strings that you may be used to.
Also, we avoid using the C char datatype, except when we know for sure that the data will always be ASCII or UTF-8. And, even then, we don't use the datatype directly.
Normally, we abstract the character datatype with these defines:
| Datatype | Description |
|---|---|
| REBYTE | A byte, always 8 bits. Can be used for UTF-8 or ASCII. |
| REBCHR | An OS char. On Win32 this is a wide-char. On Linux or BSD, it's just a char (UTF-8). This is important for host code that may be shared on more than just one OS. |
| REBUNI | A REBOL Unicode char. Currently, this is 16 bits, but we may have builds that allow 32 bits, so you must use this typedef or you'll get yourself in trouble later. |
We'll be expanding this section as needed.
64 Bit Integers
Some older compilers are a bit odd in how they deal with 64 bit integers. We support them by using typedefs for integers. Take a look at reb-c.h for the definitions. Note that these oddities apply to not only the type names, but also to constant definitions.
Large Files on Linux
In order to access large files on Linux, a special flag is used to modify the API for 64 bit file offsets. When you compile source modules (R3 devices) that access files, you must provide this compiler option:
-D_FILE_OFFSET_BITS=64
This is provided in the standard makefile that comes in the tar package.
Coding Rules
There are some coding rules to keep the code base clean (from becoming a mishmash of different styles and methods which ultimately results in code that's difficult to maintain.)
We're going to be strict and snobby on this. A strict set of rules makes it possible for all of us to read and manage the code (rather than just those who have sufficient time and patience.)
These basic rules are listed at the top of every .c file:
- Keep code clear and simple.
- Document unusual code, reasoning, or gotchas.
- Use same style for code, vars, indent(4), comments, etc.
- Keep in mind Linux, OS X, BSD, big/little endian CPUs.
- Test everything, then test it again.
Especially study the style of the code, including naming, indentation, placement of braces, format of comments, etc. Be sure to set your editor for tab-size 4, with real tabs (not spaced tabs.) If your editor can't do that, then you need to find a better editor.
There are a few additional rules (which Carl will append to as they come up):
- Words in all identifiers are separated with underscores "_". (There are a few exceptions where needed, such as for the primary typedefs.)
- Globals variables and functions capitalize the first letter of each word. Locals don't
- DEFINEs are entirely uppercase.
- Function names are verb-noun style (just like they are in REBOL code). There are a few exceptions, at times, but not many.
- We avoid using the C stdlib except when absolutely necessary. We don't use sprintf(), scanf(), case-tables, etc. However, in the host code, we may relax this requirement if you can make a good argument as to why you need a specific function.
And, please keep other operating systems in mind! If you are writing code specific to Win32, put it in the os/win32 directory. Don't make the situation difficult for people who use other systems.
Licensing
For the binary, you can freely publish and use REBOL 3 for commercial and non-commercial uses. That's how most developers will use it.
For the source, contributions are strongly encouraged for the benefit of the entire REBOL community. Everyone appreciates good code and all contributions will be incorporated into the licenses outlined below. That is, you are contributing both the code and all rights to that code. In this way a simple licensing method is made possible.
For the source code, there will be two licenses. The first allows usage and reuse of the code as desired, with attribution and same license, even for usage outside of REBOL. The second allows usage, but restricts reuse only with the REBOL language from RT. In other words if MS wants to write R++, then they need to write their own code for some parts or contact RT for a special licence. Hey, RT's got to pay its bills somehow.
The precise official language of the licenses will be posted on www.rebol.com.