User:Clipka/Development - Revision history

Clipka: /* Adding New Source Files */

2010-12-22T15:25:04Z

Adding New Source Files

Clipka: /* Data Types */

2010-12-22T15:21:35Z

Data Types

Clipka at 15:22, 31 August 2010

2010-08-31T15:22:20Z

Clipka: Created page with '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. == Working with the Perforce Repository == ==…'

2010-08-31T12:33:37Z

Created page with '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. == Working with the Perforce Repository == ==…'

New page

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.

== 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 [http://www.ultraedit.com/ IDM]''' (the people that brought you UltraEdit), or '''''Beyond Compare'' from [http://www.scootersoftware.com 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.

@@ Line 91: / Line 91: @@
 === Data Types ===
-The following types should be avoided:
+==== Deprecated Types ====
-* UV_VECT
+The following types, while still in use by part of the code, should be avoided:
-Instead, use the following types:
+;UV_VECT
-* Vector2d
+Note that the recommended replacement types can be passed to functions expecting the respective deprecated type by using the dereference operator.
-Note that these types can be passed to functions expecting the respective deprecated type by using the dereference operator.
+==== Color Processing ====
-Furthermore, the following rules should be heeded:
+;COLC
-* Avoid ''Colour'' where ''RGBColour'' would suffice.
+;COLCSUM
-* Avoid integer types for boolean values; use ''bool'' instead.
+:''not implemented yet''
 == Working with the Perforce Repository ==

← Older revision		Revision as of 15:22, 31 August 2010
Line 1:		Line 1:
	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.		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.:
		+
		+	<source lang="c">
		+	for (int i = 0; i < count; i ++)
		+	{
		+	foo();
		+	bar();
		+	}
		+	</source >
		+
		+
		+	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.:
		+
		+	<source lang="c">
		+	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;
		+	}
		+	}
		+	</source>
		+
		+	* Namespace blocks are not indented.
		+	* Single statements are not enclosed in a block (unless syntactically required), e.g.:
		+
		+	<source lang="c">
		+	if (foobar)
		+	{
		+	Something();
		+	SomethingMore();
		+	}
		+	else
		+	SomethingElse();
		+	</source>
		+
		+	* 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.:
		+
		+	<source lang="c">
		+	if (foo < 10)
		+	DoThis();
		+	else if (foo < 20)
		+	DoThat();
		+	else if (foo < 30)
		+	DoNothing();
		+	else
		+	{
		+	if (errorHandler != NULL)
		+	errorHandler->handleError();
		+	}
		+	</source>
		+
		+	=== 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 ==		== Working with the Perforce Repository ==

@@ Line 177: / Line 177: @@
 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 source files to the corresponding '''Visual Studio''' projects - ''all'' the '''vs8, vs9 ''and'' vs10''' 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'''").