User:Clipka/Development

This is a page I started to collect a few things that might be helpful for fellow POV-Ray developers. It's a bit messy at present.

Coding Style

At different times, different people used different coding styles for different portions of POV-Ray's codebase, so there is currendly a hodgepodge of various coding styles. To stop proliferation and further explosion of the set of coding styles, here are a few rules to adhere when coding for POV-Ray:

• When modifying existing code, adapt to the existing style(s). While it would be nice to have a consistent coding style for all of POV-Ray's source files, it is even more important to retain per-file or at least per-function consistency of style. Of couse if a function is a hodgepodge of styles already, it makes sense to go for "the" POV-Ray style.
• If there's particularly good reason to make an exception from the recommended coding style, do so. These rules are guidelines, not laws.

Whitespace

POV-Ray C++ source and header files use the following rules regarding whitespace use:

• For general indentation, tabs are used, with one tab per indentation level.
• For in-line horizontal alignment, spaces are used.
• For horizontally aligning the start of a line with a feature on the preceding line, the same number of tabs are used as in that preceding line, followed by as many spaces as necessary for the desired alignment.

Note that when these rules are followed, the actual size of a tab is completely irrelevant, and is therefore left up to the individual developer.

People not accustomed to these rules may experience them as pretty cumbersome. To make their life easier, there exists a small tool in the Perforce repository at povray/smp/tools/tabifyer, which will attempt to convert all whitespace according to these rules, and usually does quite a decent (albeit not perfect) job at it. The tool presumes a tab size of 4, but can easily be adjusted for any other tab size at compile time.

Blocks

Block layout follows the Allman style (aka ANSI style), i.e. opening and closed braces are placed on a separate line each, with all lines in between - but not the braces themselves - being indented, e.g.:

for (int i = 0; i < count; i ++)
{
    foo();
    bar();
}

The following additional rules apply:

• In block structures that contain labels or label-like keywords - that is, class definitions and switch blocks - the labels are indented by one level, while the remaining code is indented by two levels, e.g.:

class Foo
{
    public:
        void Bar ();
    private:
        int foobar;
}

void Foo::Bar ()
{
    switch (foobar)
    {
        case FNORD:
            printf("This value does not exist.\n");
            break;
        default:
            printf("%d\n", foobar);
            break;
    }
}

• Namespace blocks are not indented.
• Single statements are not enclosed in a block (unless syntactically required), e.g.:

if (foobar)
{
    Something();
    SomethingMore();
}
else
    SomethingElse();

• For an else branch comprised of just an if statement, typically the familiar chained else if layout is used, though nested layout may be appropriate in some cases, too, e.g.:

if (foo < 10)
    DoThis();
else if (foo < 20)
    DoThat();
else if (foo < 30)
    DoNothing();
else
{
    if (errorHandler != NULL)
        errorHandler->handleError();
}

Data Types

The following types should be avoided:

• UV_VECT
• VECTOR
• COLOUR
• RGB

Instead, use the following types:

• Vector2d
• Vector3d
• Colour
• RGBColour

Note that these types can be passed to functions expecting the respective deprecated type by using the dereference operator.

Furthermore, the following rules should be heeded:

• Avoid Colour where RGBColour would suffice.
• Avoid integer types for boolean values; use bool instead.

Working with the Perforce Repository

General Recommendations

Get a decent interactive diff tool. Aside from just showing differences between two files, here are a few features you might want to keep your eyes peeled for:

• Optionally ignore unimportant differences, such as comment or whitespace changes.
• Manually adjust file alignment.
• Manually merge files.
• Edit files in-place.
• Compare directory trees.
• Synchronize directory trees.

I recommend investing some $30-$50 into a shareware tool such as UltraCompare from IDM (the people that brought you UltraEdit), or Beyond Compare from Scooter Software (my personal favorite), both of which go way beyond the above "shopping list". You'll probably find they're worth every cent of their price, and then some.

Building for Linux

To build a Linux version from the repository, you need to:

• Retrieve the desired revision from Perforce.
• Run "./unix/prebuild.sh".
• Follow the steps as outlined in "./INSTALL"

Adding New Source Files

When adding new source files, please make sure to:

• Add the source files to the corresponding Visual Studio projects - both the vs8 and vs9 version. (You may want to use a diff tool to update the project you're not using yourself: There are only few differences between the respective project files.) Please also make sure to strip the "Relase-SSE2|x64" configuration from the modified project file before checking it in; while Visual Studio keeps auto-generating that configuration, we don't actually want it in the repository. (Again, a diff tool comes in handy.)
• Add the standard POV-Ray comment block to the head of your files. (Don't forget to fill in the proper file name.)
• After marking the files for add in Perforce, change the Perforce filetype; for C++ source and header files, we want base type "text" with the "+k" option enabled ("ktext").

When someone else has added new source files, people compiling for Linux will have to:

• Run "./unix/prebuild.sh" to re-generate the makefiles.