Creating the header

The core GNUstep libraries implement the OpenStep APIs and the newer Cocoa APIs introduced by Apple. The fact that these APIs have been produced by a litigious company, and the GNUstep project is used all over the world, means that we have to be a careful as possible to avoid the possibility of legal action being taken against GNUstep for copyright infringement in any country.

So ... we clearly can't simply copy Apple header files, but must produce our own header files which are functionally equivalent but as different as reasonably possible from the the Apple ones.

The easiest way to see how to do things is simply to look at a gnustep-base or gnustep-gui header file, but this article aims to point out key facts:

We use a standard header at the top of the file, which identifies the file, the copyright ownership (Free Software foundation), the author(s) etc.

We bracket the entire header in preprocessor conditionals to prevent it being used twice if included using the #include mechanism rather than #import.

We #import <GNUstepBase/GSVersionMacros.h> to get version management macros, and we use them to ensure that the header contents are only seen by applications which want to use the version of the API that Apple introduced the class in.

We include a fragment of code at start and end to ensure that the header can be read properly by a C++ compiler.

We list method names within the file as two groups (class methods, and then instance methods) with alphabetical order within each group ... this differs from Apples' usual practice of putting methods together in functional groups.

We use different formal argument names to those that apple use, since changing these does does not effect function of the API.

We use the GNUstep coding standards for line length, the use of white space and indentation. This means individual method names formatted differently than in Apple headers.

We put documentation in comments before each class and before each method (historically the documentation was often put in the source files, but in the header is better).

We hide instance variables by using a private pointer to the actual instance variables (unless we are certain we will never need to add more instance variables in later releases).

We use #if...#else...#endif to deal with Objective-C language variations ... most people don't use the more recent additions Apple have made to the Objective-C language, and you must assume that the header file will be read by a compiler which doesn't support those features, so you need to have alternatives which will work with other compiler versions.

Have a look at gnustep-base/Headers/Foundation/NSOperation.h as an example.