C++ Portability Rules - 1

8. Use the common denominator between members of a C/C++ compiler family.

 

For many of the compiler families we use, the implementation of the C and C++ compilers are completely different, sometimes this means that there are things you can do in the C language, that you cannot do in the C++ language on the same machine. One example is the 'long long' type. On some systems (IBM's compiler used to be one, but I think it's better now), the C compiler supports long long, while the C++ compiler does not. This can make porting a pain, as often times these types are in header files shared between C and C++ files. The only thing you can do is to go with the common denominator that both compilers support. In the special case of long long, we developed a set of macros for supporting 64 bit integers when the long long type is not available. We have to use these macros if either the C or the C++ compiler does not support the special 64 bit type. 

 

9. Don't put C++ comments in C code.

 

The quickest way to raise the blood pressure of a Netscape Unix engineer is to put C++ comments (// comments) into C files. Yes, this might work on your Microsoft Visual C compiler, but it's wrong, and is not supported by the vast majority of C compilers in the world. Just do not go there. 

 

Many header files will be included by C files and included by C++ files. We think it's a good idea to apply this same rule to those headers. Don't put C++ comments in header files included in C files. You might argue that you could use C++ style comments inside #ifdef __cplusplus blocks, but we are not convinced that is always going to work (some compilers have weird interactions between comment stripping and pre-processing), and it hardly seems worth the effort. Just stick to C style /**/ comments for any header file that is ever likely to be included by a C file. 

 

10. Don't put carriage returns in XP code. 

 

While this is not specific to C++, we have seen this as more of an issue with C++ compilers, see Use the common denominator between members of a C/C++ compiler family. In particular, it causes bustage on at least the IRIX native compiler.

 

On unix systems, the standard end of line character is line feed ('\n'). The standard on many PC editors is carriage return and line feed ("\r\n"), while the standard on Mac is carriage return ("\r"). The PC compilers seem to be happy either way, but some Unix compilers just choke when they see a carriage return (they do not recognize the character as white space). So, we have a rule that you cannot check in carriage returns into any cross platform code. This rule is not enforced on the Windows front end code, as that code is only ever compiled on a PC. The Mac compilers seem to be happy either way, but the same rule applies as for the PC - no carriage returns in cross platform code.

 

MacCVS, WinCVS, and cygwin CVS when configured to use DOS line endings automatically convert to and from platform line endings, so you don't need to worry. However, if you use cygwin CVS configured for Unix line endings, or command line cvs on Mac OS X, you need to be somewhat careful.

 

11. Put a new line at end-of-file.

 

Not having a new-line char at the end of file breaks .h files with the Sun WorkShop compiler and it breaks .cpp files on HP. 

 

12. Don't put extra top-level semi-colons in code.

 

Non-portable example: 

 

  int

  A::foo()

  {

  };

 

This is another problem that seems to show up more on C++ than C code. This problem is really a bit of a drag. That extra little semi-colon at the end of the function is ignored by most compilers, but it is not permitted by the standard and it makes some compilers report errors (in particular, gcc 3.4, and also perhaps old versions of the AIX native compiler). Don't do it. 

Portable example: 

 

  int

  A::foo()

  {

  }

 

13. C++ filename extension is .cpp.

 

This one is another plain annoying problem. What's the name of a C++ file? file.cpp, file.cc, file.C, file.cxx, file.c++, file.C++? Most compilers could care less, but some are very particular. We have not been able to find one file extension which we can use on all the platforms we have ported Mozilla code to. For no great reason, we've settled on file.cpp, probably because the first C++ code in Mozilla code was checked in with that extension. Well, it's done. The extension we use is .cpp. This extension seems to make most compilers happy, but there are some which do not like it. On those systems we have to create a wrapper for the compiler (see STRICT_CPLUSPLUS_SUFFIX in ns/config/rules.mk and ns/build/*), which actually copies the file.cpp file to another file with the correct extension, compiles the new file, then deletes it. If in porting to a new system, you have to do something like this, make sure you use the #line directive so that the compiler generates debug information relative to the original .cpp file. 

 

14. Don't mix varargs and inlines. 

 

Non-portable example: 

 

  class FooBar {

    void va_inline(char* p, ...) {

      // something

    }

  };

 

The subject says it all, varargs and inline functions do not seem to mix very well. If you must use varargs (which can cause portability problems on their own), then ensure that the vararg member function is a non-inline function. 

Portable example: 

 

  // foobar.h

  class FooBar {

      void 

 va_non_inline(char* p, ...);

  };

 

  // foobar.cpp

  void 

  FooBar::va_non_inline(char* p, ...)

  {

 // something

  }

 

15. Don't use initializer lists with objects.

 

Non-portable example: 

 

  FooClass myFoo = {10, 20};

 

Some compilers won't allow this syntax for objects (HP-UX won't), actually only some will allow it. So don't do it. Again, use a wrapper function, see Don't use static constructors. 

Always have a default constructor. 

 

Always have a default constructor, even if it doesn't make sense in terms of the object structure/hierarchy. HP-UX will barf on statically initialized objects that don't have default constructors. 

C++ Portability Rules

1. Be very careful when writing C++ templates. 

 

Don't use C++ templates unless you do only things already known to be portable because they are already used in Mozilla (such as patterns used by nsCOMPtr or CallQueryInterface) or are willing to test your code carefully on all of the compilers we support and be willing to back it out if it breaks. 

 

2. Don't use static constructors.

 

Non-portable example: 

 

  FooBarClass static_object(87, 92);

 

  void

  bar()

  {

    if (static_object.count > 15) {

       ...

    }

  }

 

Static constructors don't work reliably either. A static initialized object is an object which is instanciated at startup time (just before main() is called). Usually there are two components to these objects. First there is the data segment which is static data loaded into the global data segment of the program. The second part is a initializer function that is called by the loader before main() is called. We've found that many compilers do not reliably implement the initializer function. So you get the object data, but it is never initialized. One workaround for this limitation is to write a wrapper function that creates a single instance of an object, and replace all references to the static initialized object with a call to the wrapper function: 

Portable example: 

 

  static FooBarClass* static_object;

 

  FooBarClass*

  getStaticObject()

  {

    if (!static_object)

      static_object = 

 new FooBarClass(87, 92);

    return static_object;

  }

 

  void

  bar()

  {

    if (getStaticObject()->count > 15) {

      ...

    }

  }

 

3. Don't use exceptions.

 

Exceptions are another C++ feature which is not very widely implemented, and as such, their use is not portable C++ code. Don't use them. Unfortunately, there is no good workaround that produces similar functionality. 

 

One exception to this rule (don't say it) is that it's probably ok, and may be necessary to use exceptions in some machine specific code. If you do use exceptions in machine specific code you must catch all exceptions there because you can't throw the exception across XP (cross platform) code. 

 

4. Don't use Run-time Type Information.

 

Run-time type information (RTTI) is a relatively new C++ feature, and not supported in many compilers. Don't use it. 

 

If you need runtime typing, you can achieve a similar result by adding a classOf() virtual member function to the base class of your hierarchy and overriding that member function in each subclass. If classOf() returns a unique value for each class in the hierarchy, you'll be able to do type comparisons at runtime. 

 

5. Don't use C++ standard library features, including iostream

 

Using C++ standard library features involves significant portability problems because newer compilers require the use of namespaces and of headers without .h, whereas older compilers require the opposite. This includes iostream features, such as cin and cout.

 

Furthermore, using the C++ standard library imposes difficulties on those attempting to use Mozilla on small devices.

 

There is one exception to this rule: it is acceptable to use placement new. To use it, include the standard header by writing #include NEW_H.

 

6. Don't use namespace facility.

 

Support of namespaces (through the namespace and using keywords) is a relatively new C++ feature, and not supported in many compilers. Don't use it. 

 

7. main() must be in a C++ file.

 

The first C++ compiler, Cfront, was in fact a very fancy preprocessor for a C compiler. Cfront reads the C++ code, and generates C code that would do the same thing. C++ and C startup sequences are different (for example static constructor functions must be called for C++), and Cfront implements this special startup by noticing the function called "main()", converting it to something else (like "__cpp__main()"), adding another main() that does the special C++ startup things and then calls the original function. Of course for all this to work, Cfront needs to see the main() function, hence main() must be in a C++ file. Most compilers lifted this restriction years ago, and deal with the C++ special initialization duties as a linker issue. But there are a few commercial compilers shipping that are still based on Cfront: HP, and SCO, are examples. 

 

So the workaround is quite simple. Make sure that main() is in a C++ file. On the Unix version of Mozilla, we did this by adding a new C++ file which has only a few lines of code, and calls the main main() which is actually in a C file.