I am currently working on a C++ project and I have to say that C++ isn’t an inch better than Ada. Consider the following code:

#include <Windows.h>

namespace Geometry {
  class Polyline { };
}

using Geometry::Polyline;

namespace OtherNS {
  Polyline* get() {
    return NULL;
  }
}

Trying to compile this code gives you the following error message (on Visual C++ 2010):

using_test.cpp(10): error C2143: syntax error : missing ';' before '*'
using_test.cpp(10): error C4430: missing type specifier - int assumed. Note: C++ does not support default-int
using_test.cpp(10): error C4430: missing type specifier - int assumed. Note: C++ does not support default-int

What? Syntax error? And then you start looking where you missed a ;.

The problem, however, is completely different. It’s because there is a function called Polyline() defined somewhere in Windows.h and now the compiler tries to use this function as return type instead of the class Polyline (but doesn’t say anything about that). <irony>This, of course, becomes totally clear just by reading this extremely meaningful error message.</irony> *sigh*

GCC isn’t better here (in case you were blindly blaming Microsoft for writing bad error messages):

error: ‘Polyline’ does not name a type

By the way, the problem can be solved by placing the using statement inside the OtherNS namespace.

The whole problem was a result of me thinking that C++ references (&) are just pointers (*) that have some restrictions (e.g. they can’t be NULL). Wrong! What’s even worse: They’re sometimes just pointers with some restriction. This makes them work in some cases but fail in others.

Let me take you on my journey and you’ll hopefully avoid this (very subtle) mistake in your work.

The Basic Idea

Let’s examine the basic (and partially constructed) idea. Say, you have two classes, BaseClass and its child ChildClass:

class BaseClass { };
class ChildClass : public BaseClass { };

Furthermore, say we have a pointer to an instance of ChildClass called g_somePointer.

// Exists as long as the program runs.
// NOTE: This is stored as a BaseClass pointer.
BaseClass* g_somePointer = new ChildClass();

Now imagine, you want to write a wrapper class around another class providing you with a reference to this pointer g_somePointer. Let’s reduce the code to the function returning the reference (called getReference()) and the function wrapping it (called getReferenceWrapper()):

typedef BaseClass* BaseClassPointer;

const BaseClassPointer& getReference() {
  // now "ref" is just another name for "g_somePointer"
  const BaseClassPointer& ref = g_somePointer;
  return ref;
}

const BaseClassPointer& getReferenceWrapper() {
  const BaseClassPointer& ref = getReference();
  return ref;
}

The last thing is some testing code which simply calls the wrapper function and does something with the returned pointer:

void main() {
  const BaseClassPointer& ref = getReferenceWrapper();
  ref->doSomething();
}

Executing this code will work as intended (but only tested with Visual C++ 2010 and g++ 4.6.1). ref in main() will “contain” the address to the ChildClass instance – the same as stored in g_somePointer.

Two Little Changes Turn the World Upside Down

Now, for some reason you want to change the variable type of g_somePointer from BaseClass* to ChildClass*:

// Exists as long as the program runs.
ChildClass* g_somePointer = new ChildClass();

The program will compile fine (even with the highest compiler warning level) and running the program will – at least with the compilers mentioned above – work as intended.

Let’s introduce a second – as it seems – totally unrelated change to the implementation of getReferenceWrapper(), adding a new local variable:

#include <string>

...

const BaseClassPointer& getReferenceWrapper() {
  std::string someString = "ignore me"; // <-- this is new

  const BaseClassPointer& ref = getReference();
  return ref;
}

This shouldn’t have any impact on the program, should it?

With me asking this question you probably already know the answer. Executing the program now should give you a segmentation fault/access violation.

What has happened? This second change seemed totally unrelated. Let’s debug the program. I’ll only show the relevant code and mark the current execution position with an arrow:

const BaseClassPointer& getReferenceWrapper() {
  std::string someString = "ignore me";

  const BaseClassPointer& ref = getReference();
  return ref; // <---
}

At this line (return ref;) ref still contains the correct address.

const BaseClassPointer& getReferenceWrapper() {
  std::string someString = "ignore me";

  const BaseClassPointer& ref = getReference();
  return ref;
} // <---

At this line, the content of ref suddenly has changed to some invalid garbage. “What’s going on here?” you might ask.

The Cause

It may have looked like nothing but the actual cause for the problem was changing the data type of g_somePointer to ChildClass*. Let’s explore this.

First, the current implementation of getReference() is hiding the problem from the compiler. That’s why it can’t issue a warning (and neither Visual C++ nor g++ will).

const BaseClassPointer& getReference() {
  const BaseClassPointer& ref = g_somePointer;
  return ref;
}

Let’s change this implementation to an equivalent (and more simple) one:

const BaseClassPointer& getReference() {
  return g_somePointer;
}

Now the compiler will give you a warning:

• Visual C++: warning C4172: returning address of local variable or temporary

• g++: warning: returning reference to temporary [enabled by default]

Important: Don’t be as stupid as I was and try to “fix” the warning by using my initial implementation of getReference(). This warning is there for a reason and the reason is not that the compiler is too dumb to figure out what to do.

The compiler is telling you here that you’re returning a reference to a local variable. This is always a bad thing. The questions now are:

• Why is this a bad thing?

• Where does the local variable or temporary (variable) come from?

Note: You won’t get this warning if you change the data type of g_somePointer back to BaseClass*. So, under some conditions the current implementation of getReference() is actually valid.

Why is this a bad thing? (Stack Frames)

If you already know why returning a reference to a local variable is a bad thing (or if you just accept this fact), skip this section. If not, read on.

The problem here is that local variables reside on the so called “stack” (or “call stack”). This is a continuous section of memory that grows with each function that is called (and also shrinks again once the function returns). The following image shows the call stack for a function (= subroutine) named DrawLine(), called from a function named DrawSquare():

As you can see, there are two stack frames here (blue and green) – on for each function. Each stack frame contains the “Locals” (i.e. the local variables, such as “ref”) of the associated function. The stack frame (and with it the locals) of DrawLine() (the callee) is stored above the locals of DrawSquare() (the caller). Currently the function DrawLine() is being executed, indicated by the position of the “Stack Pointer”. When DrawLine() returns, the stack pointer will move to the top of DrawSquare()‘s stack frame (the blue section). When this happens the stack frame of DrawLine() (the green section) will become invalid. Invalid here means that the memory section previously occupied by the stack frame (green section) must not be used anymore. If DrawSquare() now calls another function, this new function’s stack frame will replace the content in the green section with its own content.

Now, if you have a reference (or a pointer for that matter) to a local variable of DrawLine(), this reference will “point” to some content that’s no longer available. And that’s bad. The values of these references will change just by calling a function that doesn’t even know these references. On the other hand, if you don’t call another function, your code may work (just like our example code above did before introducing the local variable someString) and hide the problem. Small code changes or turning on code optimizations (like when switching from debug to release build) may (or may not) surface the problem again. This kind of problem is a real pain, as you can imagine.

Where does the local variable or temporary (variable) come from?

Back to the warning. We’re being told by the compiler that we’re returning a temporary (i.e. a “variable” automatically created by the compiler). Where does this temporary come from?

Remember that the warning doesn’t appear when g_somePointer has the type BaseClass* (but it does appear if it has the data type ChildClass*). Here’s what the compiler basically converts the new implementation of getReference() into (I’ve actually extended the code a little bit to better show the problem):

BaseClass* g_somePointer;

const BaseClassPointer& getReference() {
  // temporary is just another name for g_somePointer
  BaseClassPointer& temporary = g_somePointer;
  return temporary;
}

Now, when you change g_somePointer‘s data type to ChildClass*, the compiler will convert the implementation into something slightly different:

ChildClass* g_somePointer;

const BaseClassPointer& getReference() {
  // The "static_cast" isn't technically needed here.
  // It's just here to show that a cast is done here.
  BaseClass* localPointer = static_cast<BaseClass*>(g_somePointer);

  // temporary now is another name for localPointer (and no longer for g_somePointer)
  BaseClassPointer& temporary = localPointer;
  return temporary;
}

Here the compiler creates a local variable containing the pointer to the base class of ChildClass. This is required because in C++ the pointer to a base class doesn’t necessarily have to have the same address as the pointer to a child class. This is especially true when the child class inherits from multiple base classes. See this example:

class BaseClass1 { };
class BaseClass2 { };
class ChildClass : public BaseClass1, public BaseClass2 { };

ChildClass* ptr = new ChildClass();
BaseClass2* basePtr = ptr;
// now possibly: "basePtr != ptr"

Because of this address change the compiler can’t just use g_somePointer for temporary. It needs to cast the instance first and then store it in some variable (here: localPointer). It than creates the reference to this local variable, which is bad as explained in the previous section.

Side note: Adding the local variable someString to getReferenceWrapper() broke the code above because std::string is a class that has a destructor. The destructor is “just” a method (function) which is automatically called when the object (someString) goes out of scope. As I explained in the previous section, calling a function overwrites the call stack above the current function’s stack frame (i.e. the green part in the image above), thereby overwriting the memory section containing the address to the base class of g_somePointer (to which our reference pointed).

Working Example

I’ve attached the whole code of the example so that you can try it out for yourself.

reference_problem.cpp

Summary

Returning a reference to a pointer will result in “unpredictable” (or at least undefined) behavior when the reference’s type is a base type of the pointer’s data type.

The following code will work (although you might consider it fragile)…

BaseClass* g_somePointer = ...
typedef BaseClass* BaseClassPointer;

const BaseClassPointer& getRef() {
  return g_somePointer; // works
}

… whereas the following code won’t (i.e. results in unpredictable behavior). Note that just the data type of g_somePointer changed to ChildClass*:

ChildClass* g_somePointer = ...  // <-- different
typedef BaseClass* BaseClassPointer;

const BaseClassPointer& getRef() {
  return g_somePointer; // illegal - introduces local variable
}

This code is illegal because the compiler needs introduce a temporary, local variable in getRef() to store the resulting address of the (static) cast from ChildClass* to BaseClass*. And then the function returns a reference to this local variable instead of a reference to g_somePointer.

CodeProject

Mit diesem Bild werden Besucher der englischen Wikipedia am heutigen 18. Januar 2012 begrüßt. Grund: Protest gegen die US-Gesetzesentwürfe SOPA (Stop Online Piracy Act) und PIPA (ProtectIP Act). Einen guten (englisch-sprachigen) Artikel hat die Electronic Frontier Foundation dazu verfasst: How PIPA and SOPA Violate White House Principles Supporting Free Speech and Innovation.

Irgendwie kommt mir das doch alles sehr bekannt vor.

The help page for IDisposable provides the code for IDisposable‘s default implementation pattern in C#. This article will explain each part of it step by step and also provide the equivalent C++/CLI code in each step.

Summary – for the impatient

Here’s the summary of this article for those who don’t want to read the actual explanations.

Rules:

• For a class owning managed resources, implement IDisposable (but not a finalizer).

• For a class owning at least one unmanaged resource, implement both IDisposable and a finalizer.

C# code:

class DataContainer : IDisposable {
  public void Dispose() {
    Dipose(true);
    GC.SuppressFinalizer(this);
  }

  ~DataContainer() { // finalizer
    Dispose(false);
  }

  protected virtual void Dispose(bool disposing) {
    if (m_isDisposed)
      return;

    if (disposing) {
      // Dispose managed data
      //m_managedData.Dispose();
    }
    // Free unmanaged data
    //DataProvider.DeleteUnmanagedData(m_unmanagedData);
    m_isDisposed = true;
  }

  private bool m_disposed = false;
}

C++/CLI code:

ref class DataContainer {
public:
  ~DataContainer() {
    if (m_isDisposed)
       return;

    // dispose managed data
    //delete m_managedData;
    this->!DataContainer(); // call finalizer
    m_isDisposed = true;
  }

  // Finalizer
  !DataContainer() {
    // free unmanaged data
    //DataProvider::DeleteUnmanagedData(m_unmanagedData);
  }

private:
  bool m_isDisposed; // must be set to false
};

The Root of all Evil

In C#, all classes are managed by the garbage collector. However, some things just can’t be expressed in pure managed code. In these cases you’ll need to store unmanaged data in a managed class. Examples are file handles, sockets, or objects created by unmanaged functions/frameworks.

So, here’s an example of a C# class containing unmanaged data:

class DataContainer {
  public DataContainer() {
    m_unmanagedData = DataProvider.CreateUnmanagedData();
  }

  private IntPtr m_unmanagedData;
}

The equivalent C++/CLI example would look like this:

ref class DataContainer {
public:
  DataContainer() {
    m_unmanagedData = DataProvider::CreateUnmanagedData();
  }

private:
  IntPtr m_unmanagedData;
};

The question now is: When gets the unmanaged data deleted?

Finalizer

Since our class DataContainer is a managed class, it is managed by .NET’s garbage collector. When the garbage collector determines that our instance of DataContainer is no longer needed, the object’s finalizer is called. So, that’s are good point to delete our unmanaged data.

Note: Finalizers are also called non-deterministic destructors because the programmer has no influence over when the garbage collector will call the finalizer (once the object went out of scope). For deterministic destructors (explained in the next section), on the other hand, the programmer has full control when they are called.

In C# the finalizer method (internally named Finalize()) is created by using C++’s destructor notation (~DataContainer):

class DataContainer {
  public DataContainer() {
    m_unmanagedData = DataProvider.CreateUnmanagedData();
  }

  ~DataContainer() {
    DataProvider.DeleteUnmanagedData(m_unmanagedData);
  }

  private IntPtr m_unmanagedData;
}

In C++/CLI the notation ~DataContainer() is already reserved for deterministic destructors (because all destructors are deterministic in C++). So, here we must use the notation !DataContainer instead:

ref class DataContainer {
public:
  DataContainer() {
    m_unmanagedData = DataProvider::CreateUnmanagedData();
  }

  !DataContainer() {
    DataProvider.DeleteUnmanagedData(m_unmanagedData);
  }

private:
  IntPtr m_unmanagedData;
};

Note: Although you can declare a finalizer public in C++/CLI, it won’t be. So, don’t bother with its visibility. (In C# you get a compiler error when specifying anything but private visibility for the finalizer.)

IDisposable

Since finalizers are non-deterministic, you have no control over when they will be called. When working with unmanaged data it may, however, be desirable to control the point of time when this unmanaged data will be deleted. The easiest way to do this: create a method for that.

The .NET framework provides a standard name for this method: Dispose(), defined by the IDisposable interface. This method is also called a “deterministic destructor” (whereas finalizers are non-deterministic destructors). Here’s the implementation in C#:

class DataContainer : IDisposable {
  public DataContainer() {
    m_unmanagedData = DataProvider.CreateUnmanagedData();
  }

  public void Dispose() {
    if (m_isDisposed)
       return;

    DataProvider.DeleteUnmanagedData(m_unmanagedData);
    m_isDisposed = true;
  }

  private bool m_sDisposed= false;
  private IntPtr m_unmanagedData;
}

In C# you can either call the Dispose() method directly or use a using block. Note that we’ve added m_isDisposed to prevent the programmer from calling Dispose() multiple times.

In C++/CLI the Dispose() method is automatically created (and IDisposable is implemented) when creating a destructor (~DataContainer):

ref class DataContainer {
public:
  DataContainer() : m_isDisposed(false) {
    m_unmanagedData = DataProvider::CreateUnmanagedData();
  }

  ~DataContainer() {
    if (m_isDisposed)
       return;

    DataProvider::DeleteUnmanagedData(m_unmanagedData);
    m_isDisposed = true;
  }

private:
  bool m_isDisposed;
  IntPtr m_unmanagedData;
};

In C++/CLI a deterministic destructor (or the Dispose() method) is called automatically when:

• a class instance is on the stack (instead of the managed heap) and goes out of scope

• a class instance is on the managed heap and gets deleted via delete myVar;

This is identical with how you would “call” destructors in C++.

Combining Dispose and Finalizer

Since the programmer can forget to call Dispose(), it’s important to free unmanaged data in the finalizer (as well) to avoid memory leaks. So, often you want to combine Dispose() and the finalizer. Here’s how.

In C#, simply call Dispose() from the finalizer. Note that the finalizer will be called in any case, so the unmanaged data is freed even if the programmer forgets to call Dispose().

class DataContainer : IDisposable {
  public DataContainer() {
    m_unmanagedData = DataProvider.CreateUnmanagedData();
  }

  public void Dispose() {
    if (m_isDisposed)
      return;

    DataProvider.DeleteUnmanagedData(m_unmanagedData);
    m_isDisposed = true;
  }

  // Finalizer
  ~DataContainer() {
    Dispose();
  }

  private bool m_disposed = false;
  private IntPtr m_unmanagedData;
}

In C++/CLI we do the opposite: we call the finalizer (which isn’t possible in C#). This way is the cleaner. I’ll explain this a little later on.

ref class DataContainer {
public:
  DataContainer() : m_isDisposed(false) {
    m_unmanagedData = DataProvider::CreateUnmanagedData();
  }

  ~DataContainer() {
    if (m_isDisposed)
       return;

    this->!DataContainer();
    m_isDisposed = true;
  }

  // Finalizer
  !DataContainer() {
    DataProvider::DeleteUnmanagedData(m_unmanagedData);
  }

private:
  bool m_isDisposed;
  IntPtr m_unmanagedData;
};

Managed Data

Beside unmanaged data, a managed class can also contain managed data, i.e. instances of managed classes implementing IDisposable. Managed data is different from unmanaged data in that it should be disposed in Dispose() but not in the finalizer. This is because instances of managed classes may already have been garbage collected when the finalizer runs.

To avoid code duplication, Dispose() and the finalizer should be implemented like this (in pseudo-code):

void Dispose() {
  DisposeAllManagedData();
  Finalizer();
}

void Finalizer() {
  FreeAllUnmanagedData();
}

This is why I called the C++/CLI way the “cleaner” way above. It implements the whole thing just like our pseudo-code:

ref class DataContainer {
public:
   ...

  ~DataContainer() {
    if (m_isDisposed)
       return;

    delete m_managedData; // dispose managed data
    this->!DataContainer(); // call finalizer
    m_isDisposed = true;
  }

  // Finalizer
  !DataContainer() {
    DataProvider::DeleteUnmanagedData(m_unmanagedData); // free unmanaged data
  }

private:
  bool m_isDisposed;
  IntPtr m_unmanagedData;
  IDisposable^ m_managedData;
};

In C#, on the other hand, we can’t call the finalizer. So, we need to add a helper method called Dispose(bool):

class DataContainer : IDisposable {
  ...

  public void Dispose() {
    Dipose(true);
  }

  ~DataContainer() {
    Dispose(false);
  }

  protected virtual void Dispose(bool disposing) {
    if (m_isDisposed)
      return;

    if (disposing) {
      m_managedData.Dispose();
    }
    DataProvider.DeleteUnmanagedData(m_unmanagedData);
    m_isDisposed = true;
  }

  private bool m_disposed = false;
  private IntPtr m_unmanagedData;
  private IDisposable m_managedData;
}

Note: The method Dispose(bool) is virtual. The idea behind this is that child classes can override this method to perform their own disposing. See below for more information. Note also that the C++/CLI compiler automatically creates this method when a class has a destructor. You can’t, however, use this method directly. It’s only visible from C# (or Visual Basic).

SuppressFinalize

The default dispose implementation pattern (as shown in IDisposable’s help page) also adds the line GC.SuppressFinalize(this); to the Dispose() method. What does this method do and why do we need it?

GC.SuppressFinalize() simply prevents the finalizer from being called. Since the finalizer’s only task is to free unmanaged data, it doesn’t need to be called if Dispose() was already called (and already freed all unmanaged data by calling the finalizer). Using GC.SuppressFinalize() give a small performance improvement but nothing more.

In C# the Dispose() method changes like this:

  public void Dispose() {
    Dipose(true);
    GC.SuppressFinalize(this);
  }

In C++/CLI the destructor doesn’t change at all. That’s because the C++/CLI compiler automatically adds this code line to the destructor. (You can read about this and see a decompiled destructor here. Search for “SuppressFinalize”.)

  ~DataContainer() {
    if (m_isDisposed)
       return;

    delete m_managedData; // dispose managed data
    this->!DataContainer(); // call finalizer
    m_isDisposed = true;
    // GC.SuppressFinalize(this) is automatically inserted here
  }

Inheritance

The default dispose implementation pattern used in the previous sections create a method called Dispose(bool). This method is protected virtual and is meant to be overridden by child classes – in case they need to dispose some data of their own.

In C#, an implementation must

1. first check whether it already has been disposed,
2. then dispose everything,

3. and then call the base method.

The base method is called last to ensure that child classes are disposed before their parent classes. This is how destructors work in C++ and Dispose() mimics this behavior.

  protected virtual void Dispose(bool disposing) {
    if (m_isDisposed)
      return;

    if (disposing) {
      m_managedData.Dispose();
    }
    DataProvider.DeleteUnmanagedData(m_unmanagedData);
    m_isDisposed = true;

    // Dispose parent classes after child classes
    base.Dispose(disposing);
  }

Note: Each child class must manage its own m_isDisposed field.

In C++/CLI, again, the destructor remains the same. This is because it mimics the C++ destructor’s behavior which automatically calls its parent destructor.

  ~DataContainer() {
    if (m_isDisposed)
       return;

    delete m_managedData; // dispose managed data
    this->!DataContainer(); // call finalizer
    m_isDisposed = true;
    // GC.SuppressFinalize(this) is automatically inserted here
    // Base destructor is automatically called here
  }

When to Use IDisposable: 3 easy rules

At this point I’d like to cite three easy rules when to use IDisposable. These rules were created by Stephen Cleary and I take no credit for them. I do, however, disagree with some statements (such as “No classes should be responsible for multiple unmanaged resources.”) and have adopted the rules in this case (see the link for the original description).

Rule 1: Don’t do it (unless you need to).

There are only two situations when IDisposable does need to be implemented:

• The class owns unmanaged resources.

• The class owns managed (IDisposable) resources.

Rule 2: For a class owning managed resources, implement IDisposable (but not a finalizer)

This implementation of IDisposable should only call Dispose() for each owned resource. It should not set anything to null.

The class should not have a finalizer.

Rule 3: For a class owning at least one unmanaged resource, implement both IDisposable and a finalizer

The finalizer should free the unmanaged resource, Dispose should dispose any managed resource and then call the finalizer.

CodeProject

BTW, ich mag Facebook.

(via Geek & Poke)

Note: This only applies to C++ and C++/CLI projects. .NET projects (C# and Visual Basic) don’t have that many options to be tweaked and (therefore?) can’t have shared settings.

Note 2: This article describes property sheets as they appear in Visual Studio 2010. They may work slightly different in other versions of Visual Studio.

The Property Manager

While property sheets (file extension: .props) are simply XML files and therefore could be edited with a simple text editor, Visual Studio also provides an editor for property sheets. This editor is available through the so called Property Manager. To display the Property Manager pane, in the menu go to View –> Other Windows –> Property Manager.

Note: Property sheet files share the same XML syntax as .vcxproj files.

This will open the Property Manager pane. For just one project (here called MainConsoleProj), the contents of the Property Manager will look like this:

Let’s examine what you see here:

1. On the top (icon: ) you see our project. If there were more projects in the solution, they’d listed here as well.
2. On the next level there are all configurations of the project on all supported platforms (icon: ). There are usually the configurations “Debug” and “Release” on the platform “Win32″. These are the same configurations you have available in the project settings in the Configuration drop-down field. To keep things simply, from now on in this article a configuration-platform combination will be called just “configuration”.

3. On the inner-most level you have the actual property sheets.

Let’s examine the property sheets a bit closer:

• There are two kinds of property sheets. I couldn’t find their official names, so let’s call them Base Property Sheets (icon: ) and Custom Property Sheets (icon: ). You can edit only custom property sheets. Base property sheets are read-only.
• Property sheets have an order in which they’re evaluated. This is important, if two property sheets define a value for the same setting. The order can be seen in the Property Manager and is bottom up. So in the image above, for the “Debug” configuration first Core Windows Libraries is evaluated, then Unicode Support and so forth. We’ll examine the effects of this order a little later.

• Property sheets belong to a certain configuration (such as “Debug|Win32″). The stack of property sheets defines the value that can be inherited for this specific configuration (i.e. that’s what you get when you choose <inherit from parent or project defaults> for a value in the project settings).

Note: The property sheet Microsoft.Cpp.Win32.user is located somewhere in the current user’s application settings. It’s contents therefore will be different for each user. By keeping it the top item in every configuration you allow the user to override any option, if necessary, without needing to change the project file.

Creating a shared property sheet

The first step is to create a new property sheet file. To do this, right-click on the project and choose Add New Project Property Sheet. This will add a new property sheet to all configurations of the project. In this article, we’ll called the file commons.props and place it in a directory called shared-properties directly in the solution directory.

Note: You can also right-click on a configuration and choose the same menu item. In this case the new property sheet will only be added to the selected configuration. You can, of course, add this property sheet later to the other configurations as well.

As mentioned before, we want to keep the property sheet Microsoft.Cpp.Win32.user the top item in every configuration. So, select an instance of the new property sheets and click on the down arrow in the Property Manager’s toolbar. Repeat this also for the property sheet(s) in the other configuration(s).

The result then should look like this:

Editing a property sheet

To edit a property sheet (file), simply double-click on it in the Property Manager.

Note: The same property sheet file can be listed multiple times in the Property Manager. Editing one “instance” of this file will, of course, update all other “instances” as well (since all “instances” share the same file).

This will pop up a dialog that’s very similar to the “Project Settings” dialog of a C++ project. Note that since the property sheet file itself isn’t bound to any specified project kind or configuration, the dialog may display more options than are actually available to the project the property sheet is currently associated with.

Let’s demonstrate the effect of a property sheet with compiler switch Warning Level. But before we start editing the property sheet, we need to revert this switch’s its default value. To do this, open up the project settings for the current project (for example by select the project in the Property Manager and select Properties from the context menu). Then select All Configurations from the Configuration drop-down box and go to C++ –> General. Then make sure that Warning Level is inheriting the default value (which should be Level1 (/W1)). If it’s not, its value will be printed in bold. In this case, click on the down arrow in the value field and select <inherit from parent or project defaults> (see screenshot).

After clicking on Apply, the result should look like this:

Now, again, open the property sheet editor for the common property sheet we created earlier. There, set the Warning Level to Level3 (/W3). Then click OK.

Note: You may need to save the property sheet manually. For this, use the Save button in the Property Manager’s toolbar.

When you now open the project’s settings again, you should see that the inherited value (not in bold) of Warning Level changed from level 1 to level 3.

That’s the effect of the property sheet. You can define as many settings in a single property sheet file as you want. Then you can add the same property sheet file to multiple project thereby sharing this set of common project settings among all projects.

Note: A value of a setting specified in a property sheet is only used in a project, when there isn’t a custom value (printed in bold) assigned to this setting in the project settings. To take the value of the property sheet (instead of defining a value in the project file), select <inherit from parent or project defaults> from the drop-down menu of this setting.

Property Sheet Order

As mentioned earlier, the property sheets are applied in a certain order – from bottom to top as shown in Property Manager. When editing a property sheet, each setting already displays the inherited value – unless the property sheet defines its own value.

So, lets have a look at the property sheet Microsoft.Cpp.Win32.user (in one of the configurations). It still should be the top item in the stack. The value for Warning Level is already Level3 (/W3). It’s inherited from one of the property sheets below – our “common” sheet in this case.

Now lets swap the common sheet with the Microsoft.Cpp.Win32.user sheet. This will move the common sheet to a position above of Microsoft.Cpp.Win32.user. Again, open the Microsoft.Cpp.Win32.user sheet. The Warning Level is now Level1 (/W1), as it’s no longer inherited from the common sheet. In fact, the common sheet now inherits its values from the Microsoft.Cpp.Win32.user sheet.

Custom Variables (a.k.a. Macros)

It’s possible to define your own custom variables (like the pre-defined $(OutDir) or $(SolutionDir)). These variables are called “Macros” in Visual Studio. To define one, open the property sheet editor and go to User Macros. There, you can add new macros with the Add Macro button. These macros then appear in the Macros section that is available when editing free text properties (such as paths).

Inheriting From Other Property Sheets

Property sheets can inherit their values from other property sheets. You can either specify this inheritance …

• in a project file: This is accomplished by adding the inherited property sheet to the Property Manager and move it below the inheriting property sheet.

• in a property sheet file: To do this, right-click on the inheriting property sheet file in the Property Manager and choose Add ... Property Sheet and select/create the inherited property sheet. The inherited property sheet is now being displayed as child node of the inheriting property sheet (see screenshot).

The XML code for inheritance is:

<ImportGroup Label="PropertySheets">
  <Import Project="commons.props" />
</ImportGroup>

Conditional Properties

Property sheets can also contain conditional property values. This means that the value of a property depends on some other value. Usually, this is used to place values for debug and release builds in the same property sheet file. Unfortunately, you can edit these conditions in Visual Studio’s property editor. You need to use a text editor.

Note: When you’ve modified a property sheet outside of Visual Studio, you need to close the solution(s) it belongs to and reopen them afterwards. Otherwise Visual Studio won’t detect the changes to the property sheet.

First, you can define conditions on single properties by using the Condition attribute:

<Optimization Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'">Disabled</Optimization>

On the other hand, if you want to group several properties for a certain configuration, you can also add the Condition attribute to container elements (here: <ItemDefinitionGroup>):

<ItemDefinitionGroup Condition="'$(Configuration)|$(Platform)'=='Release|Win32'">
  <ClCompile>
    <PreprocessorDefinitions>QT_NO_DEBUG;QT_NO_DEBUG_OUTPUT;NDEBUG;%(PreprocessorDefinitions)</PreprocessorDefinitions>
  </ClCompile>
  <Link>
    <GenerateDebugInformation>false</GenerateDebugInformation>
  </Link>
</ItemDefinitionGroup>

You can find more information about conditions in the article “MSBuild Conditions” on MSDN.

Property Sheet XML Structure

Property sheet files are XML files. The root element is called <Project> and in most cases you’ll work with the child elements <ItemDefinitionGroup> and <PropertyGroup>. It’s not always clear, in which kind of group to place a certain element. The easiest way to figure this out is to set the desired element in the project settings of a C++ project and then view the project file in a text editor. This is possible because property sheets and C++ project files (.vcxproj) use the same XML schema.

Additionally, you can have a look at the XML tag descriptions on MSDN, although there aren’t that descriptive.

CodeProject

This article describes the problem and shows solutions.

For the impatient

For those of you that don’t want to read the whole article, here’s the summary:

• Library providing method with native type:

  • Native types outside a C++/CLI project need to be made public in a C++/CLI project via #pragma make_public(Type)
  • Native types inside a C++/CLI project need to be made public via keyword public.
  • This pragma has to be written in the .h file
  • To prevent C3767, include the .h file before the pragma (i.e. don’t just use a forward declaration).

• Library using the method:

  • Needs to include .h file of native type
  • Forward declaration may not be enough (gives linker warning)

  • If the native type is defined inside a C++/CLI project, the project must be reference in the project settings via “Add Reference” as well as “Linker –> Input”.

Preparation

To illustrate the problem, we first create some projects that we can use as basis. Each project will only contain one or two classes, so nothing fancy here. I’ll assume you know how to create projects and how to enable and disable the /clr compiler switch to create C++/CLI and pure C++ project respectivly.

The first project (called “NativeLib”) is a pure C++ (no C++/CLI) and DLL project which provides a native (unmanaged) class called MyNativeClass. This class is the type that will later be passed across assembly boundaries. Here’s the source code (for the meaning of NATIVE_LIB_EXPORT, see Projects in Visual C++ 2010 – Part 1: Creating a DLL project):

// MyNativeClass.h
#pragma once

#ifdef COMPILE_NATIVE_LIB
  #define NATIVE_LIB_EXPORT __declspec(dllexport)
#else
  #define NATIVE_LIB_EXPORT __declspec(dllimport)
#endif

class NATIVE_LIB_EXPORT MyNativeClass {
public:
  MyNativeClass(int val);

  int getValue() const;

private:
  int m_value;
};

// MyNativeClass.cpp
#include "MyNativeClass.h"

MyNativeClass::MyNativeClass(int val) {
  this->m_value = val;
}

int MyNativeClass::getValue() const {
  return this->m_value;
}

That’s it for the first project. The second project (named “ManagedProviderLib”; C++/CLI project) will provide the managed class ManagedProvider with a method the returns a pointer MyNativeClass. Here’s the source code:

// ManagedProvider.h
#pragma once

class MyNativeClass;

public ref class ManagedProvider {
public:
  ManagedProvider();

  MyNativeClass* getNativeClass();

private:
  MyNativeClass* m_nativeClass;
};

// ManagedProvider.cpp
#include "ManagedProvider.h"
#include <MyNativeClass.h>

ManagedProvider::ManagedProvider() {
  this->m_nativeClass = new MyNativeClass(42);
}

MyNativeClass* ManagedProvider::getNativeClass() {
  return this->m_nativeClass;
}

This should be pretty straight forward. Additionaly you need to add the project “NativeLib” to the include and library directories of “ManagedProviderLib”.

Here’s the final project structure:

NativeLib (pure C++)
  +- MyNativeClass.h
  +- MyNativeClass.cpp
ManagedProviderLib (C++/CLI)
  +- ManagedProvider.h
  +- ManagedProvider.cpp

The Problem

After we’ve created our skeletan projects, let’s explore the actual problem.

What does work

First, let’s create an example that does work. For this, we create a C++/CLI class called InternalTestClass and add it to the “ManagedProviderLib” project. This class will inherit ManagedProvider and have a method (doSomething()) that calls ManagedProvider::getNativeClass(). The project structure now is:

NativeLib (pure C++)
  +- MyNativeClass.h
  +- MyNativeClass.cpp
ManagedProviderLib (C++/CLI)
  +- ManagedProvider.h
  +- ManagedProvider.cpp
  +- InternalTestClass.h
  +- InternalTestClass.cpp

And here’s the source code for InternalTestClass:

// InternalTestClass.h
#pragma once
#include "ManagedProvider.h"

public ref class InternalTestClass : ManagedProvider {
public:
  void doSomething();
};

// InternalTestClass.cpp
#include "InternalTestClass.h"

void InternalTestClass::doSomething() {
  MyNativeClass* nativeClass = getNativeClass();
}

##doSomething()## doesn’t do anything useful, but the point is that the project compiles. So, this shows that we can return the pointer to a native class here.

What doesn’t work a.k.a “The Problem”

Now, after having a working example, we’ll explore the actual problem. For this, we create a new C++/CLI project (called “ManagedExternalLib”) and add a managed class called ExternalTestClass. This will have the same code as InternalTestClass. The only difference is that ExternalTestClass is in a different project than its base class ManagedProvider. Here’s the project structure:

NativeLib (pure C++)
  +- MyNativeClass.h
  +- MyNativeClass.cpp
ManagedProviderLib (C++/CLI)
  +- ManagedProvider.h
  +- ManagedProvider.cpp
  +- InternalTestClass.h
  +- InternalTestClass.cpp
ManagedExternalLib (C++/CLI)
  +- ExternalTestClass.h
  +- ExternalTestClass.cpp

And here’s the source code:

// ExternalTestClass.h
#pragma once

public ref class ExternalTestClass : ManagedProvider {
public:
  void doSomething();
};

// ExternalTestClass.cpp
#include "ExternalTestClass.h"

class MyNativeClass;

void ExternalTestClass::doSomething() {
  // Compiler error C3767 - candidate function(s) not accessible
  MyNativeClass* nativeClass = getNativeClass();
}

In a pure C++ class, this would compile – regardless of whether the “NativeLib” project is on the include and library path or not. We have a forward declaration of MyNativeClass and since we only work with the pointer of this class, we don’t need to know its size (which would be provided by including “MyNativeClass.h”). Also, since we don’t call any methods of MyNativeClass we don’t need the import lib of “NativeLib”.

But then this error doesn’t indicate a missing include file nor is it a linker error. Instead the error suggests that the method we want to call isn’t accessible (read: it’s private or internal). However, that’s not the case here.

The Solution

The actual problem is not that the (C++/CLI) method is private but that MyNativeClass (pure C++) is private. That’s even mentioned (very briefly though) in C3767′s description page:

C3767 may also be caused by a breaking change: native types are now private by default in a /clr compilation;

So, even if the native type was exported (via __declspec(dllexport)) in the native library, it can be made private by a managed library. (The reason behind this seems to be that the C++/CLI compiler generates thin (managed) wrappers around native types so that they can be called from managed code. See here for more information.)

Native Types From Pure C++ Projects

If the native type is defined in a pure C++ project (or in a framework for which you only have the header files), use #pragma make_public(Type). You should place it in the .h after after including its header. So, our example code for ManagedProvider.h changes to this:

// ManagedProvider.h
#pragma once

#include "MyNativeClass.h"  // <-- this is new (was "class MyNativeClass;" before)
#pragma make_public(MyNativeClass) // <-- this is new

public ref class ManagedProvider {
  ...
};

Notes:

• Using make_public in a .cpp file instead of an .h file may result in the linker error LNK2022 (metadata operation failed).

• The code above swapped the forward declaration (class MyNativeClass.h) with the #include statement. This is to be on the safe side. Forward declarations work in some cases, while they don’t work in others (resulting again in C3767 compiler errors).

Compiling the whole solution now will give you a linker warning LNK4248 (unresolved typeref token). To fix this, you need to include the type’s .h file instead of just creating a forward reference. So, our “ExternalTestClass.cpp” changes to this:

// ExternalTestClass.cpp
#include "ExternalTestClass.h"

#include <MyNativeClass.h> // <-- new; was "class MyNativeClass;" before

void ExternalTestClass::doSomething() {
  MyNativeClass* nativeClass = getNativeClass();
}

Of course, this also allows you to actually do something (e.g. call methods) with the nativeClass pointer.

Note: If you only want to store a pointer to a native class (i.e. don’t do anything with it), you don’t need to link against the native type’s .lib file.

Native Types From C++/CLI Projects

The pragma make_public is used for native types defined in header file you can’t change. If, on the other hand, the native type is part of your C++/CLI project (“ManagedProviderLib” in this case), you can prefix the class definition with the keyword public (like you would for a managed type):

// MySecondNativeClass.h
#pragma once

#ifdef COMPILE_PRODUCER_LIB
  #define PRODUCER_LIB_EXPORT __declspec(dllexport)
#else
  #define PRODUCER_LIB_EXPORT __declspec(dllimport)
#endif

// Note that this is still a native type.
public class PRODUCER_LIB_EXPORT MySecondNativeClass {
  ...
};

This keyword is only available in C++/CLI projects and has the same effect like make_public. Unfortunately, I wasn’t able to get this example working, because I couldn’t figure out a way to export the methods of that type. I’ll update this section if I find some new information on that topic. (I’ve raised this question at stackoverflow.com.)

To use this type in another C++/CLI project, you need to reference the assembly’s .lib (here “ManagedProviderLib.lib”) twice in the project settings (here: of “ManagedExternalLib”):

1. Add a reference to the dependency project (here “ManagedProviderLib.lib”) in “Common Properties” –> “Framework and References” via “Add Reference…”.

2. Also Add a reference to the dependency project in “Linker” –> “Input” –> “Additional Dependencies”.

I’m not sure whether linking the same .lib file twice is a bug or working as intended, but surely it’s not very intuitive.

Source Code

I’ve created a small solution (for Visual Studios 2010) that contains the example source code described in this article.

CLIAssemblyCrossBoundaryTest.zip

History

• 2012-01-09 : Fixed using a native type from a C++/CLI project
• 2012-01-09 : No longer suggests forward declarations for public native types

• 2012-01-09 : Published

CodeProject

Determine your Java version

Apple uses a different versioning system for Java than Oracle. For example, on my system the actual Java version is “1.6.0_29″ (determined by calling java -version from a terminal), but this version comes as “Java for Mac OS X 10.7 Update 1″ through Apple’s Software Update.

To find out which Java Update you’re running, go to the System Preferences and click Software Update.

Then you click on Installed Software and search the list for the latest Java update (here “Update 1″).

That’s the “Java version” you need to know.

Downloading the JDK

When working with Java, you need to distinguish two Java software package types:

• JRE: The “Java Runtime Environment” is necessary to run Java application. You cannot, however, compile Java programs with just the JRE.

• JDK: The “Java Development Kit” is required when you want to compile Java programs. The JDK includes the JRE, and also comes with Java’s source code.

Remark: Eclipse comes with its own Java compiler. That’s why you don’t need to install a JDK to create Java programs with Eclipse. Eclipse doesn’t ship with the Java source code though. That’s why we still need the JDK.

The JDK for Mac OS X comes as “Java Developer Package”. You can download it here:

http://connect.apple.com/

You’ll need an AppleID to download the JDK. Fortunately, it’s free but you still need to register it. (Tip: You can use the same you use in the iTunes Store.) After logging in, type “java developer package” in the search field (see screenshot).

Make sure the you download the Java Developer Package matching your Java version. In my case, this is “Mac OS X 10.7 Update 1″.

Note: Don’t confuse “10.7″ for Java 7. It’s still Java 6. (So don’t download a “10.6″ version when you’re running Mac OS X Lion.)

Then install the JDK. This will install the JDK under:

/Library/Java/JavaVirtualMachines/

Note: There’s also the directory /System/Library/Frameworks/JavaVM.framework/. However, this directory seems to be deprecated.

The Java source code will be located here:

/Library/Java/JavaVirtualMachines/<javaversion>.jdk/Contents/Home/src.jar

Check an already installed JDK

To check whether you’ve already installed a JDK, check the list of installed updates (see above) for an entry called “Java Developer Package”.

Note: Unfortunately, the Java Developer Package listed in the list doesn’t have any (visible) version information attached to it. I’m not sure whether the JDK will be updated automatically when a new version becomes available.

To check the actual Java version of the installed JDK, go to /Library/Java/JavaVirtualMachines/ and check whether a package called like “1.6.0_29-b11-402.jdk” can be found there. In this example, the Java version would be “1.6.0_29″.

Using the JDK in Eclipse

On Mac OS X, Eclipse provides an automatic way to determine the directory of the installed JDK. Go to the Eclipse Settings and open Java –> Installed JREs.

Then, by clicking on the Search... button, would find the newly installed JDK. Unfortunately, there seems to be a bug in Eclipse Ingido (3.7 – and probably in earlier versions, too) that prevents this button from working correctly. Clicking on it doesn’t do anything when there’s already one (and only one) JRE listed here; see screenshot.

To fix this problem, do the following:

1. Duplicate the existing entry (by hitting the Duplicate... button)
2. Delete the original entry; it’s the one with checked checkbox in front of it.
3. Then click Search.... This should add two new entries to the list (see next screenshot).
4. Delete the entry you’ve created in step 1 (i.e. the duplicate of the original entry).
5. Check one of the remaining entries. Note: The new two entries are linked. If you check one, both will be checked. Also, you can’t delete the entry for /System/Library/Java/.... Trying to do so will delete the other entry.
6. Close the Settings dialog with OK.

7. Restart Eclipse. This will remove the wrong entry (the one for /System/Library/Java/...) from the list.

The list of installed JREs then should look like this:

Manually adding a JDK

If you want (for any reason) to add the JDK manually, here’s how to do this:

1. Go to Installed JREs in the Eclipse Settings.
2. Click Add...
3. Choose “MacOS X VM” and hit Next...
4. Specify /Library/Java/JavaVirtualMachines/<javaversion>.jdk/Contents/Home/ under JRE Home. Note: You need to type/paste the directory directly into the field. You can’t use the Directory... as the directories in the JavaVirtualMachines directory are so called “Mac OS X packages”. These directories are displayed as files and you can’t browse their contents from within the dialog.

5. Give the JDK a meaningful name and hit Finish.

Changelog

What changed?

• 2011-12-30: Published

Requirements

This article assumes that you…

• … know your way around your operating system (Windows, Mac OS X, …)
• … know what an IP address is and what’s it used for

• … have installed a hyper visor (e.g. VMWare, Parallels, or Virtual Box) and created a virtual machine with it.

That’s basically it.

The Goal

The goal is to be able to do something like this:

$ ping ubuntu-server
PING ubuntu-server (10.211.55.2): 56 data bytes
64 bytes from 10.211.55.2: icmp_seq=0 ttl=64 time=0.479 ms
64 bytes from 10.211.55.2: icmp_seq=1 ttl=64 time=0.348 ms
64 bytes from 10.211.55.2: icmp_seq=2 ttl=64 time=0.452 ms

Here, we used the DNS name of our virtual server (called ubuntu-server) to do a ping. We didn’t need to know its IP address – which is the point of using DNS names. So, how does one assign such a name to a virtual server? That’s what this article is about.

The Short Version

If you really know your way around your OS, here’s the short version of what we’re going to do:

1. Assign a static IP address to the virtual machine (from within the virtual machine; see reasoning below)

2. Add an entry to the OS’ hosts file

The remainder of this article describes the points above in more detail.

Assign a static IP address

To assign a static IP address (i.e. one that stays the same every time you start your virtual machine) one can think of two ways of doing this:

1. Let the virtual machine (i.e. the simulated computer) decide what IP address to use.

2. Let the hyper visor (i.e. the simulating program) decide what IP address to use.

In my opinion that latter would be the cleaner way. Simply tell your hyper visor software what IP address to assign to the virtual machine. Unfortunately that’s no that simple. A virtual machine could itself simulate multiple network adapters where each one would acquire an IP address. Which of these adapters then would the hyper visor assign the static IP address to? That’s probably why none of the hyper visors I used provided an option for this (at least none that’s easily reachable).

So, the way to go is to let the virtual machine (i.e. the simulated computer) decide which IP address to use.

Free some IP addresses (from the DHCP server)

To use an IP address we first need to make sure that there are IP addresses free to be used. By default, at least in Parallels Desktop, the DHCP server take up all available IP addresses in the specified IP range. So let’s change that. (This probably requires all virtual machines to be shut down.)

In Parallels Desktop, go to the program’s settings (not the settings of the virtual machine), then to Advanced and click on Change Settings... (as shown in the first screenshot). This will open the network settings. There you select the network type you used for your virtual machine (either Shared or Host-Only) and change the last number group of the IPv4 DHCP start address. I’ve set it to 20 in the screenshot above. This will free the first 20 IP addresses (1 – 19) so that they can be used as static IP addresses.

Assign the static IP address in the virtual machine

Next, start the virtual machine you want to assign a name to. Here you need to assign it one of the IP addresses we’ve just freed. This procedure highly depends on the operating system your virtual machine is running. So, I’ve compile a small list of how to do this on some of the popular operating systems:

• Windows XP
• Windows 7
• Ubuntu with graphical desktop

• Ubuntu/Debian with console only

What to enter:

• IP address: The IP address you want to assign to the virtual machine. It doesn’t really matter which one you choose as long as it’s not used for any other virtual machine. (You may start with number 1 for the last number block.) In my case, I’ve assigned the address “10.211.55.2″ to the virtual machine.
• Subnet Mask: Should be “255.255.255.0″, unless you know what you’re doing.
• Gateway: The IP address of the virtual router of your hyper visor. In Parallels Desktop this is the first IP address of the IP range specified in the options. In my case, this is “10.211.55.20″ (see the screenshot above).

• DNS Server: This is usally the same address as the gateway.

Add IP address to hosts

The last step is to add the newly assign static IP address to the hosts file of the host OS (i.e. not the guest OS). Fortunately, this file has the same format on most operating systems (including Windows, Mac OS, and Linux). Only the directory where to find it is different:

• Windows: %SystemRoot%\system32\drivers\etc\hosts
• Linux/Mac OS X: /etc/hosts

• Other operating systems and more details

The format of the hosts is quite simple. Each line contains of a IP address and the DNS name(s) that are assigned to it. For example:

10.211.55.2  ubuntu-server

On Mac OS X I recommend using TextWrangler. It’s a free text editor for Mac OS X that allows you to edit hidden and locked files (both applies to the hosts file). I’ve created an article for this topic here.

After you’ve changed the hosts file, you may need to run the following command (from the “Terminal”):

$ dscacheutil -flushcache

Now you should be able to ping your virtual machine by using its name rather than its IP address.

Important: Make sure that you don’t use the AppStore version as this version doesn’t allow editing locked files. (Apple’s store guidelines prohibit this.)

First, select File –> Open... from the menu. Then, since system configuration files are often hidden or in hidden folders, select Show hidden items at the bottom of the “Open” dialog.

Then open the file you want to edit. You may notice that the file is in read-only mode (represented by the icon in the upper left corner).

To switch to write mode, either click this icon or start editing the file’s content. In both cases you’ll be asked to unlock the file. After that, you can edit the file.

When you’re done, simply save the file. You’ll be asked for your password since you’re editing a system file (that doesn’t belong to you). And that’s it.

Note: The AppStore version doesn’t ask you for your password but instead asks you to save the file under a different name.

Click here to view the embedded video.

The Problem

Despite the fact the Android is (supposed to be) an open source project, the downloads don’t include the source code of Android. So, when opening an Android class in Eclipse, you may see something like this:

To solve this problem you had to manually download the whole Android source code (which contains much more than just the Java source code files) and then manually assemble a source files directory from the Java files scattered throughout the Android source tree. Very tedious and certainly not very simple.

The Solution

Fortunately, there is a Google Code project named “adt-addons” aiming to solve this problem. The project actually consists of several Eclipse plugins, but the one you want is called “Android Sources”. You can either search the instructions on the project page, or follow them (nicely formatted) here.

Basically what you need is to install the “Android Sources” plugin (about 170 MB). Here’s the update URL:

http://adt-addons.googlecode.com/svn/trunk/source/com.android.ide.eclipse.source.update/

After installing the plugin, simply restart Eclipse and the Android source code is already attached to the Android classes.

• Subclipse: Subversion support
• MercurialEclipse: Mercurial support
• ExploreFS: This plugin allows you to open a file in Windows Explorer/Finder through the context menu.
• CheckStyle: This plugins allows you define more precise rules for your code style. If a rule is violated, a warning is issued.

• TestNG: Unit testing framework (much like JUnit)

To see what plugins have already been installed, go to Help –> Install new software… and click on What is already installed? at the bottom of the dialog.

Here at work I have a C++ project with about 50 .cpp files in it. The project uses the Qt library and all files only include the absolute minimum of header files required. Without precompiled headers, compiling the project takes about 56 seconds. With precompiled headers, the compile time goes down to about 7 seconds. That’s eight times faster.

Related Articles:

• Projects in Visual C++ 2010 – Part 1: Creating a DLL project

• Projects in Visual C++ 2010 – Part 2: Project Dependencies

The procedure described here only applies to Visual C++ (if I’m correct since version 6.0). However, other C++ compilers may provide similar functionality.

The Problem

The problem precompiled headers solve is the long compile time when compiling a C++ project. (Note that other languages such as Java or C# don’t have this problem.) The underlying problem is the #include <...> statement. This simply copies the whole content of the file included into the source file. While one header file may not be that big, it may also include other header files. When using a framework (such as Qt or even Win32), one include statement will import a huge amount of source code. And this huge amount is what takes so long when compiling a C++ project. Furthermore, if this huge amount gets included in every source code file, all of it has to be compiled again for every source file.

So, the idea is to (pre)compile these huge amount of source code once, and then reuse it in every source code file of the project. This drastically reduces the compile time required.

Specifying the precompiled header (stdafx.h)

To be able to use a precompiled header in Visual C++, one first needs to specify which headers shall be precompiled. Visual C++ only allows one precompiled header file per project. By default, it’s called stdafx.h. This name can be changed in the project settings under “C++” –> “Precompiled Headers” –> “Precompiled Header File”.

The limitation that only one precompiled header is allowed is no real limitation because you can include any header file from within the precompiled header. For example, a precompiled header may look like this (for using the Qt framework):

#pragma message("Compiling precompiled headers.\n")

#include <QtCore>
#include <QtXml>
#include <QtGui>

So when this header is precompiled, all included headers will be precompiled as well. Thus, the more of the headers you use in your project are specified here, the faster the other files in the project compile. Note that including more header files than are actually used is not a problem.

You may also note the #pragma statement on the first line. This is just “helper statement”. With it, every time the precompiled header is compiled, the specified message will be printed to the build output. If you see this message twice or more while compiling a single project, something is wrong. (In most cases you won’t see the message at all because the precompiled header is already compiled.)

Using the Precompiled Header

Whether to use a precompiled header or not can be specified per project as well as per file. When you want to use a precompiled header in a project, you usually say “Use” for the whole project and then exclude certain .cpp file that shall not use the precompiled header. Both options are in the same section – it just depends on whether you open the project settings or the file settings (both being available through their context menus).

To enable precompiled headers in a project (or file), open the project settings (or file settings) and select “Use” under “C++” –> “Precompiled Headers” –> “Precompiled Header”. Also make sure, that you’ve selected “All Configurations” from the “Configuration” dropdown field. (Note that the option “Create” will be used below.)

The next thing you need to do is to #include "..." the precompiled header file in every source file (.cpp). You shouldn’t (can’t?) include it in the header files (.h) but only in the .cpp file. Also, the include statement must be the first statement in the file (only comments or whitespace is allowed above it). This is because Visual C++ assumes that everything before the include statement is already compiled.

So the beginning of a .cpp file in your project may look like this:

// File with some fancy functions.
#include "stdafx.h"
#include "myfancefunctions.h"
...

Note that the name of the precompiled header file is the one you specified above (or “stdafx.h” by default).

Compiling the Header

By now, we’ve specified which headers are to be compile and where these headers will be used. The last step is to actually compile the precompiled header. Without this you’ll get a “Cannot open precompiled header file” error message when compiling the project.

For this you need to add a new .cpp file to your project. By convention, it has the same name as the precompiled header but that’s no strict requirement. This file only needs to contain one statement:

// stdafx.cpp
#include "stdafx.h"

Next, you need to go to the file’s settings (via context menu) and change the value of “Precompiled Header” from “Use” to “Create”.

That’s it. Now, when compiling the project again for the first time, the precompiled header will be created. After that, compiling the other source files should be significantly faster than before. Also the precompiled header will only be compiled on the first run. After that it won’t be compiled again (which would somehow defeat its purpose) unless either the “stdafx.cpp” or “stdafx.h” file is modified.

CodeProject

Referencing a library in C++ (or, more specific, with Visual C++) is somewhat cumbersome – or should I say, used to be somewhat cumbersome. Fortunately, with the release of Visual C++ 2010 this has been greatly simplified. This article first shows the old way and then describes the new (simple) way.

Related Articles:

• Projects in Visual C++ 2010 – Part 1: Creating a DLL project

• Projects in Visual C++ 2010 – Part 3: Precompiled Headers

The setup

For the discussion of this article assume we have two projects:

• MyLibrary

• MyProgram (which uses MyLibrary)

The project “MyLibrary” compiles into a DLL library (although a static .lib might also work) and “MyProgram” is just a regular .exe project.

The Code: MyLibrary

“MyLibrary” uses the code from the first part of this series. It provides a class called PrintableInt which wraps an integer and provides a method to convert it into a string.

// PrintableInt.h
#pragma once

#include <string>

#ifdef COMPILE_MYLIBRARY
  #define MYLIBRARY_EXPORT __declspec(dllexport)
#else
  #define MYLIBRARY_EXPORT __declspec(dllimport)
#endif

class MYLIBRARY_EXPORT PrintableInt {
public:
  // Constructor
  PrintableInt(int value);
  // Converts the int into a string.
  std::string toString() const;
private:
  int m_value;
};

// PrintableInt.cpp
#include "stdafx.h"
#include "PrintableInt.h"
#include <sstream>

PrintableInt::PrintableInt(int value) {
  m_value = value;
}

std::string PrintableInt::toString() const {
  std::ostringstream builder;
  builder << m_value;
  return builder.str();
}

Again, this (and the project “MyProgram” as well) use a precompiled header file named “stdafx.h”. Precompiled headers are explained in another article.

The Code: MyProgram

The project “MyProgram” is a “Win32 Console Application” project and just contains some test code in its main function:

#include "stdafx.h"
#include <iostream>
#include "PrintableInt.h"

int _tmain(int argc, _TCHAR* argv[]) {
  PrintableInt test(5);
  std::cout << test.toString() << std::endl;
  return 0;
}

This simply prints a “5″ on the console.

The old way

In Visual C++ 2008 or earlier, to define a project dependency several steps needed to be executed (in no particular order). These steps are described below. Note that these steps still work in Visual C++ 2010.

Step: Specify Build Order

To determine the order in which the projects of the solution will be built, project dependencies need to be specified. This way dependencies will be built before the projects that use them.

To specify a dependency, select “Project Dependencies…” from a project’s context menu. Then check all projects the current project depends on.

Step: Specify Include Path

You also need to specify to path where to find the header files of the library project you want to use. This makes it possible to specify a header file by just using "PrintableInt.h" instead of "../MyLibrary/PrintableInt.h".

To do this, open the settings of the project that wants to use the library and specify the path under “Additional Include Directories”. You should also make sure that you’ve selected “All Configurations” from the “Configuration” dropdown field (see screenshot).

Step: Specify Lib File

The last step is to specify the path to the .lib file of the library project. Note that even DLL projects will create a .lib file so that your project can link against the DLL automatically.

To specify the .lib file, again go to the project settings, but this time go to Linker –> Input and specify the file under “Additional Dependencies”. Note that you’ll need (or probably want) to specify different .lib files for the “Debug” and the “Release” configuration. The screenshot below shows the value for the “Debug” configuration.

The New Way

Since Visual C++ 2010 there is a new, simpler way to specify a project dependency. With this way, unfortunately you still need to specify the include path to the library project (see above) but all other steps are simplified.

To reference a dependency the new way, choose “References…” from the project’s context menu. This will open up the project settings with the section “Framework and References” being selected. There click on “Add New Reference…” and then select the project you want to use in the current project.

And that’s it. Your project should now compile.

Besides being easier to use, the new way has also another advantage: The information about project dependencies are now stored in the project file instead of the solution file (which is the case with the way described in Step: Specify Build Order). This way you can use a library project that has some dependencies itself in several different solutions and always have the dependencies already set up correctly. (With the old way you had to recreate the dependencies for each solution manually.)

Note: There are two options – available in the project settings – that influence how these references work. Both can be found under “Linker” –> “General”:

• Ignore Import Library: This is specified in the library project. When this is set, the .lib file generated by the project won’t be used automatically by projects that depend on it. (Default: No)

• Link Library Dependencies: This is the opposite of the other option. It’s specified on the project that uses other projects. If set to “No”, dependencies won’t be linked automatically. (Default: Yes)

What’s not working

Unfortunately, there’s one details that make the new way a little more difficult to use again. *sigh* The problem: Visual Studio won’t copy the DLL files of the referenced libraries to the output folder automatically. Here’s what the documentation says about that:

Dynamic link libraries are not loaded by the executable until runtime. You must tell the system where to locate MathFuncsDll.dll. This is done using the PATH environment variable. To do this, from the Property Pages dialog, expand the Configuration Properties node and select Debugging. Next to Environment, type in the following: PATH=<path to MathFuncsDll.dll file>, where <path to MathFuncsDll.dll file> is replaced with the actual location of MathFuncsDll.dll. Press OK to save all the changes made.

There are several possible solutions for this problem (although, theoretically, this problem shouldn’t arise in the first place):

• Set the output directory to be the same as the directory where the DLL files are compiled to. (recommended)

• Use the “PATH” like describes in the documentation.

CodeProject

Related articles:

• Projects in Visual C++ 2010 – Part 2: Project Dependencies

• Projects in Visual C++ 2010 – Part 3: Precompiled Headers

Library Projects

Library projects are projects that usually contain reusable functions or classes. They’re a great way of structuring a big project. In Visual C++ (or in C++ in general) there are two types of libraries: static libraries and dynamic libraries.

Static libraries (.lib) are “merged” into the final .exe file when the whole project is compiled. Therefore, for the outside user, this library type isn’t visible.

Dynamic libraries (.dll) on the other hand remain separate from the final .exe file in their own files. (See more information here.)

In this article we’ll create a dynamic library.

Creating the Library Project

To create a library project in Visual C++ 2010 (that is a part of Visual Studio 2010) in an existing solution, choose Add –> New Project... from the solution’s context menu in the “Solution Explorer” window.

Alternatively you can create a new solution by using File –> New –> Project.... Either way will open up the “Add New Project” dialog. Here you choose “Class Library” (in section Other Languages –> Visual C++) and specify a new for the project. This name will also be the name of the DLL file.

After hitting “Ok”, your new class library project will be created. By default, it’ll create a dynamic library. To make it a static library project, head to the project’s settings (available through the project’s context menu) and set Configuration Type to Static library (.lib) (see screenshot).

You may also want to review the setting Common Language Runtime Support. If enabled (switch /clr), this will allow you to create .NET classes in this project. For a pure C++ project, however, you may want to disable CLR support (as shown in the screenshot above).

Writing a Reusable Class

The purpose of a library is to provide (potentially) reusable functions and/or classes. So, let’s create a simple reusable class.

The new class is called PrintableInt. It wraps an integer and provides a toString() method that will convert the integer into a string.

// PrintableInt.h
#pragma once

#include <string>

class PrintableInt {
public:
  // Constructor
  PrintableInt(int value);
  // Converts the int into a string.
  std::string toString() const;
private:
  int m_value;
};

// PrintableInt.cpp
#include "stdafx.h"
#include "PrintableInt.h"
#include <sstream>

PrintableInt::PrintableInt(int value) {
  m_value = value;
}

std::string PrintableInt::toString() const {
  std::ostringstream builder;
  builder << m_value;
  return builder.str();
}

The library should now compile without problems.

Note that the .cpp file include a file called stdafx.h. This is a so called “precompiled header file”. This feature is explained in another article. It should, however, work out-of-the-box in your project.

Exporting Classes

By default, all classes and functions defined in a library project are “internal”. That means that another project can’t use them. To change this, classes (or function) that are to be used by other project must be “exported”. In Visual C++ you do this with __declspec(dllexport).

Now, you could specify the export like this:

// PrintableInt.h
class __declspec(dllexport) PrintableInt {
  ...
}

However, since all projects using this library will most likely use the same header file (PrintableInt.h), this would mean that even the “using” projects would export the class as well. Of course, this is not what we want. Instead you create a macro and use it like this:

// PrintableInt.h

#ifdef COMPILE_MYLIBRARY
  #define MYLIBRARY_EXPORT __declspec(dllexport)
#else
  #define MYLIBRARY_EXPORT __declspec(dllimport)
#endif

class MYLIBRARY_EXPORT PrintableInt {
  ...
}

For this to work, you add the preprocessor definition COMPILE_MYLIBRARY to the library project (but not to the projects using the library). This way MYLIBRARY_EXPORT will be replaced by __declspec(dllexport) when compiling the library project and by __declspec(dllimport) when using the project (from another project). To specify this preprocessor, go to the library project’s settings and enter the name COMPILE_MYLIBRARY in the field “Preprocessor Definitions”. You should also make sure to select “All Configuration” from the “Configuration” dropdown field (see screenshot) so that this definition gets added to the Debug and Release configuration.

Note: The keyword __declspec(...) is a Microsoft specific extension to C++ (see here). So it only works in Visual C++. There is an alternative (more portable?) way to specify which classes/functions are to be exported. For this, a “Module-Definition File” (.def) needs to be created. However, creating such a file is more tedious than specifying the export statement directly in the code. For more information, see this article.

Now, when you compile the library project, an additional .lib file will be created. This file is used to import the exported classes/functions in another project. (If you don’t export anything, the file won’t be created.) How to do this, is explained in part two of this mini series.

dllimport necessary?

The example above specifies that __declspec(dllimport) is to be used when using the library project. You may notice that this isn’t necessary in the above example. However, it doesn’t hurt either.

This statement becomes important though when you export templated classes. To demonstrate this, change PrintableInt like this:

// PrintableInt.h
#pragma once

#include <string>

#ifdef COMPILE_MYLIBRARY
  #define MYLIBRARY_EXPORT __declspec(dllexport)
#else
  #define MYLIBRARY_EXPORT //__declspec(dllimport)
#endif

template<int T>
class MYLIBRARY_EXPORT PrintableInt {
public:
  // Constructor
  PrintableInt(int value);
  // Converts the int into a string.
  std::string toString() const;
private:
  int m_value;
};

// PrintableInt.cpp
#include "stdafx.h"
#include "PrintableInt.h"
#include <sstream>

template<int T>
PrintableInt<T>::PrintableInt(int value) {
  m_value = value;
}

template<int T>
std::string PrintableInt<T>::toString() const {
  std::ostringstream builder;
  builder << m_value;
  return builder.str();
}

This adds the type parameter T to the class. Note that __declspec(dllimport) has been commented out to demonstrate the problem.

Note: The type parameter T serves no purpose in this implementation. It’s just there to demonstrate the problem.

Now, assume another project using the library project like this:

#include <iostream>
#include "PrintableInt.h"

int _tmain(int argc, _TCHAR* argv[]) {
  PrintableInt<6> test(5);
  std::cout << test.toString() << std::endl;
  return 0;
}

Without “dllimport” compiling this project will result in (rather cryptic) linker errors – namely “unresolved external symbol”. Uncommenting __declspec(dllimport) in PrintableInt.h again solves this problem.

CodeProject