4.7 KiB
Development concepts for libcasio
As a follow-up for user-concepts
in the user guide, here's a few concepts
and decisions that have been taken for the development.
File organization
There are many, many files in libcasio, and that's because I try to keep the project clean and organized. This file is an attempt at describing how the files are organized and where you can find or should put anything here.
There are a few main files and folders:
docs/
-
The library documentation, written using Sphinx.
include/
-
The public headers to use with the library (not including internal headers).
src/
-
The sources and internal headers.
tools/
,configure
,Makefile
,Makefile.vars
,Makefile.msg
-
Build utilities.
README.md
,CONTRIBUTING.md
,LICENSE.md
-
Basic to-read files.
In the include/
folder, there is the main header the
user is supposed to include, libcasio.h
, and a subfolder,
which contains all of the headers specific to modules. It is organized
as in src/
, in modules which represent the abstraction the
module defines. For example, src/stream/
and
include/libcasio/stream.h
are related to the
libcasio-specific stream which defines platform-agnostic functions to
the system-specific utilities.
In the source folder, the internals.h
header is the
general internal header which is included in every source file in the
project (sometimes using a module or submodule specific header which
defines some more specific things afterwards). It contains general
utilities such as reliable endian management macros, reliable integer
types, and so on.
Function declarations and definitions
For portability (e.g. call conventions and other compiler-specific mess), libcasio uses a few macros for declaring and defining functions that you are expected to use if you ought to add some stuff:
OF(ARGS)
This is a macro originally from Zlib. It is used on function declarations for compatibility with K&R (pre-ANSI) C, which didn't support arguments definition for them. Without the macro, you might have done:
#if defined(__STDC__) && __STDC__
int my_function(int arg, char const *carg);
#else
int my_function(); /* K&R */
#endif
Instead, with this macro, you can just do:
int my_function
((int arg, char const *carg)); OF
CASIO_EXTERN(TYPE)
Declare or define a function exported or ought to be. For example, with a declaration and a definition:
(int) my_function
CASIO_EXTERN((int arg1, int arg2));
OF
(int) my_function(int arg1, int arg2)
CASIO_EXTERN{
return (arg1 + arg2);
}
Which can be resolved as one of the following (not exhaustive):
/* Within normal circumstances. */
extern int my_function(int arg1, int arg2);
/* Oh, we're on good ol' Windows! Let's set a call convention
* explicitely so we don't run into problems. */
extern int WINAPI my_function(int arg1, int arg2);
CASIO_NORETURN
Use instead of CASIO_EXTERN
for functions that are not supposed to
return, e.g. if they exit()
or abort()
. For
example:
CASIO_NORETURN panic_and_set_fire_to_the_computer((char const *msg)); OF
CASIO_LOCAL(TYPE)
Use for defining a function internal to the file. For example, with a declaration and a definition:
(int) my_function(int arg1, int arg2);
CASIO_LOCAL
(int) my_function(int arg1, int arg2)
CASIO_LOCAL{
return (arg1 - arg2);
}
Which can be resolved as one of the following (not exhaustive):
/* Within normal circumstances. */
static int my_function(int arg1, int arg2);
CASIO_HOOK(TYPE)
Equivalent of CASIO_LOCAL
for functions that ought to be used as
hooks, i.e. callbacks for libcasio.
CASIO_HOOK_TYPE(TYPE)
Extern function as a type, for using hook functions as callbacks
within typedef
or other type definitions. For example:
typedef CASIO_EXTERN_TYPE(int) my_function_t
((int arg1, int arg2)); OF
CASIO_EXTERN_TYPE(TYPE)
Equivalent of CASIO_HOOK_TYPE
for exported functions to be used
and stored as hooks.
CASIO_DEPRECATED
Prefix for function declarations and definitions which will be marked as deprecated for the compiler (if it supports it). For example:
(char const *) do_not_use_this_function
CASIO_DEPRECATED CASIO_EXTERN((char const *s));
OF
(char const *) do_not_use_this_function(char const *s)
CASIO_DEPRECATED CASIO_EXTERN{
return (s + strlen(s));
}