|
Wheefun I/O Library
0.0.5
Useful I/O Primitives.
|
The Wheefun I/O library (WFIO) is a collection of I/O primitives for providing simplified, multiplatform I/O manipulation. This code can be used in your projects to not only provide I/O functionality, but share this functionality between projects. WFIO is object-oriented and supports the authoring of new device classes through a simple interface.
This library is licensed under the GNU GPL v3 with the Classpath Exception. It is believed by some that linking against a library creates a derivative work; the Classpath Exception is meant to allow for people who want to use WFIO in an unadultered manner to freely distribute such works under their own licensing terms, as long as:
If you have not modified WFIO and are using it as is, then it is sufficient to provide a hyperlink to a copy that is available at the time of writing (e.g., the main Sourceforge site) to meet the "written offer" criterion. Otherwise, you should either provide the modified sources in whole or contribute it upstream so that it may be integrated into the main source code.
The C programming language offers abstract file access via its standard I/O (STDIO) interface; however, this is not easily translated to other device types such as sockets, pipes, or in-memory buffers. Other programming languages (such as C++ or Java) provide these abstractions, but these may not play so well with a C program without an additional interface. Furthermore, many operating systems provide a much more flexible device interface (such as POSIX's STREAMS interface) which are not universally available. Importantly, some environments may not even provide explicit support for files, leaving the details of implementing I/O as a purely platform-dependent task.
WFIO is meant to bridge this gap. It may not support every device type out of the box, but it does provide a mechanism by which this can be implemented in an abstract manner and shared between projects. Consider the following use case: Project A contains such a device, and project B provides functionality that applies to certain devices in general (e.g., compression). By using WFIO, Project A's device implementation can be supplied to Project B without either knowing about the other. This allows for algorithm-centric libraries to be created such that the device library only has to be implemented once.
Additionally, there are many tasks which are difficult to do portably and which the C89 standard library provides no built-in provision for. In particular, there is no such facility for operating on binary streams from the standpoint of reading primitive objects from it, like reading an IEEE754 floating point number or a little-endian 32-byte integer. Although STDIO can and frequently does operating in buffered mode, a generic buffer implementation is not provided and code must be written to facilitate this. WFIO's core provides code to deal with these situations.
Notably, WFIO is designed to be modular so that unwanted features do not lead to increased binary bloat. The comparatively tiny wfio core module amounts to tens of kilobytes in size, whereas additional functionality (such as network operations) can be included in as necessary. This can be important on constrained systems where memory is at a premium and where optimization for size may be critical to deployment.
libwfion moduleThe listed versions of these programming languages are guaranteed to be supported by WFIO:
Other languages may be supported indirectly through one of these interfaces. In the future, bindings for other languages (such as Perl and R) are planned to be added.
Support for STDIO devices are gauranteed for environments which support it. Explicit support for operating-system specific devices are provided as follows:
Because of difficulties in the author compiling MacOS X binaries, this has not yet been attempted. The suspicion is that this may work; however, this is not something that has been confirmed. Be warned that support for UNIX-like operating systems has only been tested in GNU/Linux and that any guarantees about WFIO's functionality assume a compliant POSIX implementation as a precondition.
WFIO takes the approach of dividing its functionaliy into several modular link libraries. The following C libraries are either implemented or planned:
wfio - Core functionality, including basic file devices.wfion - Support for encoding additional, less used numeric formats (not yet implemented).wfioc - Support for communications devices such as serial ports and sockets. (not yet implemented)wfiot - Extended text manipulation functionality (not yet implemented).The wfiox should additionally be linked in for C++ libraries. This is required because some compilers add additional symbols which are expected for C++ code which could otherwise break C code.
Installing WFIO varies according to the platform it is compiled on. It's primary dependency is the Wheefun C Compiler Info library. Other dependencies may be required for additional language bindings or on some operating systems.
Currently, the only method of obtaining WFIO is by downloading the sources through the associated Subversion repository and compiling it. For instructions in obtaining the source code, please follow the instructions in the aforementioned link.
For most platforms, CMake will be the preferred way to build WFIO. Once CMake is installed, type the following at a console:
$ cmake .
This will build a makefile from CMakeLists.txt. Assuming that the default generator is used (the above command will do this), you may then simply build the library in the fashion normal for your platform. On UNIX systems (herein assumed), this is as simple as invoking make:
$ make
This performs an out-of-source build, the results of which are located in the build/ subdirectory of the project root. You may not have faith in the current implementation of WFPTK on your platform; if this is the case, a "test" target is provided to ensure that WFIO actually works:
$ make test
When you are satisfied that WFPTK is operating correctly, you will probably want to install it. An install target is provided for this purpose; by default, it will go into wherever non-core libraries go (usually /usr/local on UNIX systems). Normal users rarely have permission to install to this directory, thus it may be useful to escalate privileges:
$ sudo make install
In the future, a project named Ballpeen is intended to replace CMake. When this happens, CMake support will be deprecated but will be slowly phased out as the major platforms gain support for Ballpeen. As it has not been yet implemented, CMake remains the major build method.
Visual Studio 2017 includes the ability to directly open CMake files. This is the preferred method of working with MSVC / Visual Studio if not directly through CMake. You will likely need to directly set the path to WFCNO when generating the CMake configuration.
Currently, MS-DOS support is planned to be achieved only through the use of DJGPP. This is a port of the GNU Compiler Collection which includes gmake and even a C11 compiler. Because CMake does not work in DOS, a different build system is used. In order to bootstrap it, use the following command:
$ bootdos.bat djgpp
This will create a gmake Makefile in the root directory and will create another file, make.prf, which contains a profile for the bid. You may edit this file to add variables to be used by gmake; if you want to install WFIO here, you must set the PREFIX variable to a path to perform the installation.
WFIO will compile with DOSBox 0.74 using DJGPP; however, it is known to be prone to crashing in the middle of builds. Alternatively, it may be possible to cross-compile WFIO; however, this has not been explored.
WFIO uses Doxygen for consolidating and generating documentation. Currently, Doxygen is optional and is located in build/doc. This project additionally uses Markdown to provide material that cannot be provided in the code.
1.8.13