Fire Tips: References and Hint Paths

Fire does a number of nice little things to make it easier to work with references and hint paths.

To recap, the compiler and IDE use two different mechanisms to locate a reference for a project: They can check a range of globally configured paths and defaults (which can be seen in the Preferences dialog), or they can use a Hint Path configured on the reference to locate the file directly.

As the name indicates, this path is merely a hint: it doesn't matter of the path is wrong as long as the compiler can find the reference somehow. But it can help point the compiler in the right direction, or to the right version of the file.

So what does Fire do special here?

First, Fire shows a couple of annotations on reference soon the Solution Tree. If a reference has a hint path, you will see one of three possible bits of text.

Relative or Absolute?

If the hint path is a path relative to the project, Fire will show ".../", to indicate the relative nature of the path. If a path is absolute, it will show "/...", instead.

This can be very helpful, because whether you want absolute to relative paths depends a lot on the kind of file you are referencing. Is it a binary thats stored somewhere as part of or protect, possibly committed to version control and shared with others? You probably want relative hint path. On the other hand if it's a binary stored in some more arbitrary location on your disk, with no fixed relationship to your project (such as /Users/MySelf/3rdPartyLibraries), maybe an absolute path would be better.

When you add new references, Fire uses a very simple logic to determine whether to use an absolute hint path by default: If the path can be expressed relatively by three or fewer ../, it will be added relative; if not, it assumes the reference is "far away form you project" and uses an absolute path, instead.

Luckily, you can easily switch between the two, simply my right-clicking the reference in Fire and choosing "Make Hint Path Relative" or "Make Hint Path Absolute", respectively.

You can also remove the hint path altogether, by choosing "Drop Hint Path" – telling Fire to rely on finding the file globally from now on.

Windows Paths

Sometimes you'll be opening projects from your friends or colleagues working on Windows, and they may have absolute Windows-style Hint Paths. Of course those paths won't work on the Mac, but Fire alerts you to their presence by showing "X:\..." behind the reference.

You cannot convert these paths to relative (because the path is "wrong" by definition, Fire has no base from which to correct it), but of course you can remove them with the "Drop Hint Path" menu.

Adding Hint Paths

Sometimes you have a reference without a hint path (or a wrong one), but want to add one to point the compiler to the right file. Easy: simply drag the file from Finder onto the Reference node in the Solution Tree. Fire will notice the reference already exists, and rather than adding it again it will add (or update) the hint path to match the new file.

This is very helpful if you are switching between two different versions of a library, for example.

Reveal in Finder

Want to know where a particular reference was resolved to? Selecting a reference will show a special view in the main area that, among other things, shows the final, actual path where the reference was found – whether from hint path or otherwise. You can also right-click and choose "Reveal in Finder" to go right to the file.

Other Annotations.

Fire shows you also if a reference is set to Copy Local (only relevant on .NET and Java, right now), by displaying, well, "Copy Local" behind it. You can toggle this from the right-click menu, and well.

Finally, if a reference is conditional (something you can currently only set up by messing with the project file manually, but which the compiler and IDE will honor, if present), it will show a "~" symbol next to it.

And there's More...

Of clourse there's a lot more about References we haven't covered yet, such as the "Manage References" dialog, the option of viewing source for references, and more.

Read all about References in Elements, on our docs site here.