A free-time project.

This code is untested. Most of it has been coded on a couch. Some of it may be kind of stupid, too.

I've found a bunch of bugs, bad assumptions, and generally-dumb ideas in my code. There's no reason why someone else won't find more that I've missed.

Unless otherwise stated in a file, this project is licensed under the Apache License, Version 2.0, the text of which can be found at the previous link, or in the LICENSE file.

Each code file has its license located at the top of the file. If any file is missing its license, it should be considered to be licensed under the Apache License, Version 2.0.

FlightlessManicotti is intended for use across many architectures and operating systems. While all attempts will be made to keep compatibility with the widest range of platforms, the project does have priorities.

• x86/x64
• ARM
• PPC

• MacOS
• iOS
• Android
• Windows
• Linux

All dependencies are included within the repository, and are built as part of the standard build process.

• amp revision a84380c
• nedmalloc revision 3f80a00
• uthash revision 22bf8c9
• LuaJIT version 2.0.0-beta10
• MicroAllocator version 5
• OpenCTM version 1.0.3
• FreeImage version 3.15.3

At its core, FlightlessManicotti is an implementation of several ideas and architectural-philosophies that my colleagues, and I have talked about over beer for several years.

• Target many-core platforms.
• Be able to run in a single thread.
• Trust the programmer.
• Minimize memory [re]allocation.
• Be nice to the data cache.
• Use SIMD-friendly data-structures.

• Communicate with other sub-systems asynchronously.
• Empower the scripter.

Keep it small. Keep it simple. Keep it fast.

The runtime is a shared library, but can be compiled as a static library if necessary for the target-platform. The runtime is fast, minimal, and focused on real-time tasks.

The runtime appears to be 'missing' several features which you would expect.

• Resource loading.
• String management.
• File format conversion.

This is intentional. These are not real-time tasks and should, instead, be performed in script.

Scripting will never be fast enough.

That may not be true, but it is the philosophy for scripting in FlightlessManicotti. The runtime is coded with the assumption that scripting will never be fast enough for real time, so lets not try to do it in real time. This makes it possible to handle scripting tasks in a thread, if the platform supports it, or allows it to be processed synchronously.

The overwhelming majority of communication to-and-from script will be done via queues using a producer-consumer relationship. Immediate, synchronous handling of events is possible, however it is discouraged unless there is no other way of accomplishing the task.

The runtime is not overly concerned about the language used to implement the event handlers. This is intentional, because while FlightlessManicotti uses Lua as a scripting language, by default, there is no reason why a different mechanism for handling events should be prohibited.

Don't.

The philosophy for memory allocation in FlightlessManicotti is: don't.

Unfortunately one can only go so far using this methodology, and so several allocators exist. Each allocation function has a purpose and the allocators are function-pointers which can be reassigned by the user. All allocation from the runtime must use these allocators.

Todo: Ensure SWIG, and all libs use these functions.

The kl_heap_alloc and kl_heap_free functions allocate and free memory aligned on a 16-byte boundary.

These function pointers default to results from the nedmalloc library.

The kl_heap_aligned_alloc and kl_heap_aligned_free functions allocate and free memory which is aligned to a boundary other than 16-bytes. kl_heap_aligned_alloc will assert if an alignment of 16-bytes is requested, as you should be using kl_heap_alloc instead.

These function pointers default to a function which manually aligns results from the nedmalloc library.

The kl_micro_alloc and kl_micro_free functions allocate and free memory which is 256-bytes or smaller. Any allocation greater than 256-bytes will cause an assertion.

These function pointers default to results from the MicroAllocator library.

Tools used to build FlightlessManicotti.

Currently FlightlessManicotti uses SCons to do the build.

• It works pretty well.
• Integrates easily with SWIG.
• I dislike other build systems more than SCons.

FlightlessManicotti uses SWIG to wrap structures and functions for use in Lua.

FlightlessManicotti will use LLVM and Clang to compile in order to perform static analysis, and link-time code generation.

Currently Clang can be used to compile by uncommenting a line in the top-level SConscript file, but no static analysis has been attempted yet.

FlightlessManicotti uses Doxygen to generate documentation.

FlightlessManicotti includes a slightly-modified version of the doxygen-lua project. The modifications are based on revision 2c33a4a.

This is included with FlightlessManicotti and is located at tools/doxygen-lua

The use of C for the runtime is as much a philosophical choice as it is practical. The runtime is intended to be fast, portable, and minimalistic.

If you are implementing a feature in the runtime, and saying to yourself, "Gosh, self, I wish I was using a higher-level language," than you should re-consider implementing the feature in script. For example: The runtime does not do file parsing. Instead it provides functions for allocating, and filling the data-structures it requires. File parsing is a non-realtime task, and as such it is not performed by the runtime.

• Portable.
• Fast.
• Just about everything can bind to it.
• Doesn't lend itself to over-engineering.

• Be reasonable about line length -- try and stay under 80-ish.
• Three shall be the number of the spaces used to indent, and the number of the spaces used to indent shall be three. Tabs are right out.
• There will be no space between a function-name, and the opening parenthesis.
• Curley-brackets will begin on the line following statement, unless the entire statement can fit on a single line.
• Blocks of code following case and default statements inside a switch statement should either be inline, or begin a new curley-bracket block, with the break inside the scope block.

Comments must use C style comments /* ... */

All Doxygen tags should use the @ character to denote a tag, for example @tag

/**< Inline doccumentation will use this notation. */

/**
 * Autobrief is a single line that ends with a peroid.
 *
 * Detailed description may be many lines, but in between
 * section there should be a blank line.
 *
 * @note Note blocks come after details.
 *
 * @attention Attention blocks come after note blocks.
 *            If you need more than one line for any tag,
 *            it should be indented past that tag.
 *
 * @param name Parameters should be doccumented as such, and if
 *        they require multiple lines, only indent past the 'param'. 
 * @return Return value should be specified in the same section as 
 *         the parameters.
 */

Use standard types unless not possible. This is a short table of types and the header needed to use them.

• You will align your memory.
• You will use restrict (this is defined to KL_RESTRICT for portability).
• You will use const.

• Prefix all exposed symbol names with 'kl', and an underscore between 'kl' and the symbol name. kl_foo()
• Postfix all exposed types with '_t'. kl_script_context_t

The scripting language for FlightlessManicotti is Lua, using LuaJIT.

• Small.
• Written in C.
• Portable.
• Performs well on embedded devices.
• Has compatible licensing.
• Powerful.

I haven't used Lua enough yet to put together a code convention.

• Be reasonable about line length -- try and stay under 80-ish.
• Three shall be the number of the spaces used to indent, and the number of the spaces used to indent shall be three. Tabs are right out.

Doxygen support for Lua is achieved using lua2dox

Doxygen comments will use this notation --!

All Doxygen tags should use the @ character to denote a tag, for example @tag

• Pat Wilson

• Robert Blanchet
• Clark Fagot
• Mark Frohnmayer
• Ben Garney
• Andy Maloney
• Brian Richardson
• Alex Scarborough
• John Quigley