File and symbol naming scheme

MulleObjC is the point where we move from the C compiler to the Objective-C compiler, coming up from mulle-objc-runtime. But there are C functions, that can be callable from C only, which we like to expose. These functions may be callable without the Objective-C runtime properly setup (like NSRange inline functions).

Symbol

Name

Classes, protocols etc. are the usual mix of lower-camel-case (e.g. retainCount) and upper-camel-case (e.g. NSObject).

The Apple ObjC Functions are written in upper-camel-case like NSExtraRefCount. Picking up on this, all functions that deal with id/Class as types are also camel-cased.

The mulle-objc-runtime doesn't really deal with id/Class, that's part of MulleObjC.

Functions dealing with structs and other scalars use lowercase and underscores, except if they are part of a family of functions that are camel-cased.

Prefix

Functions that are not Apple compatible, must not start with "NS". Methods that are in are Apple compatible clases but not compatible with Apple should start with an underscore. E.g. [NSObject _rootClass].

Source File

Case

Objective-C files are always camel-cased for historical reasons. C files are always underscore with 'hyphen' (instead of underscore), except when they contain camel-case functions (s.a.)

Prefix

Apple compatible classes/protocol need to keep the "NS" prefix, but non compatible classes should not use the "NS" prefix to keep them distinct. That where the "MulleObjC" prefix comes into play.

Apple structs like NSRange also keep the camel-case in their C files, though these are C only. Now what prefix does MulleObjC use for non-compatible C files. "mulle-objc" is unfortunately somewhat tainted by the mulle-objc-runtime already, but alas it is the logical choice.

Header

Private

Private headers have a "-private.h" suffix. They can only include other private files. This is so, that private headers do not accidentally circumvent the proper "mulle-objc-runtime" inclusion path. Also private files are placed in a separate folder, so inclusion of other project files is tricky anyway.

Name

If the header contains any "NS" prefixed stuff, the source also gets a "NS" prefix and is therefore camelCased. It is not possibly to discern by the header name, if it contains Objective-C code or not. This distinction is provided to the user with the various envelope headers (see: Header Provisioning).

If that header did not historically exist in the Apple Foundation, it gets a "MulleObjC" prefix instead.

There is no way to distinguish, that a C header belongs to mulle-objc-runtime, MulleObjC or MulleFoundation. That is intentional because of the motility concept, that sources should be movable to another library without edits.

What would be great to provide for C is:

• headers that are compilable with C (no #import f.e.) that are not tied to the runtime
• headers that are compilable with C (no #import f.e.) that are tied to the runtime (i.e. mulle_objc_get_universe, -lmulle-objc-runtime)

What would be great to provide for ObjC is a set of headers, that do not include the full runtime headers and dependents. Because of their pollution of the namespace, downstream sources are getting too many implicit definitions and dependencies (e.g. mulle-buffer could be exchanged in the future for something else).

But that doesn't work at the moment, though work has started with <mulle-objc-runtime/mulle-objc-runtime-minimal.h>.

Header Provisioning

Header	Provides
include.h	All C libraries that MulleObjC C files depend on and that must be exposed upwards. This will not include <mulle-objc-runtime/mulle-objc-runtime.h>. For reasons see Why is ...
MulleObjC.h	include.h with all public headers. For Objective-C consumption only.
minimal.h	All C headers with minimal MulleObjC/mulle-objc-runtime tie-in. Includes include.h.
mulle-objc.h	include.h with all MulleObjC C compatible headers. For C consumption that requires the runtime. Will include <mulle-objc-runtime/mulle-objc-runtime.h>.

minimal.h is for use with C code, that wants to pick some C only feature (like NSRange) but doesn't want to link with the Objective-C runtime. Also maybe there is no Objective-C compiler available.

mulle-objc.h is for people that do not have an Objective-C compiler, but want to link against the mulle-objc-runtime. Maybe a different language using the runtime ?

ifdef double inclusion shield

The scheme is to replace '-' with '_' and a trailing .h with __h__:

echo "mulle-objc-foo.h" | sed -e 's/-/_/g' -e 's/\.h$/__h__/'
mulle_objc_foo__h__

You should be careful with file names, since mulle-objc-runtime uses the same scheme. For the motility aspect, it's not a splendid idea to use different prefixes. Though it would be workable.