Build errors for Flare project controlled with ClearCase

[Nita Beck]

Hi all,

I have a very perplexing problem.

Background: I've spent a few months (!) researching version-controlling Flare projects (source, not output) with ClearCase. I've got ClearCase Remote Client on my laptop, and my client has ClearCase Explorer on his desktop. In both cases, we're using the latest versions of ClearCase, and we're both using Flare 7.

In Flare, I've created a global project and two local projects for testing, and I've seeded all three test projects in ClearCase. I did not use any plug-in with Flare ('cause for the life of us, we have been unsuccessful in locating one). I used ClearCase's UI directly.

On my laptop, I have joined the ClearCase (UCM) projects and have created development streams to the global project and the two local projects, so I've got all three on my local hard drive. I have checked a number of files out of ClearCase for each local project, including each one's import file, target, TOC, and several topic files.

On my client's desktop, I've done exactly the same.

On my laptop, I have made sure that the import file in each local project can find the global project. Everything imports perfectly from the global project, including a master page. (The local projects do not have local master pages.) I am able to build WebHelp output from both local projects, perfectly. During the build, I can watch all the lovely messages telling me that the master page is being applied to topics.

On my client's desktop, I've done exactly the same. However, the build process for both local projects fails when it tries to process the first topic with the master page. The last build message before the “Aborted” message says that Flare is unable to find the master page. Yet we can see the master page in the Content Explorer, right where the import originally put it. In Flare, we can open the master page. We can see the master page in Windows Explorer. We can open it with Notepad++. It's there, it's there, it's there. So why is Flare saying it is unable to find the master page?

BTW, as a test, we made a copy of the two local projects from the ClearCase development streams and threw them in temp folders on my client's machine. Voila, the builds worked.

Any geniuses out there with ideas? (If our collective brain has none, I'll open a support ticket...)

[LTinker68]

I've never used ClearCase so I don't know how it works. I don't use source control with Flare, but we do have StarTeam here for some of the software guys, and I occasionally use it. In StarTeam, you specify where the "working" folders are on your computer, but you specify that within StarTeam, so when you check files in and out of StarTeam, it knows where to look for them on your local computer. If ClearCase works the same way, then the first thing that came to mind is wondering if the "working" folders need to be specified in the same location on each computer so that the path is essentially identical. It doesn't seem like you should need to do that, because Flare should be looking for the masterpage relative to where the topic is located in the project, not where the project folder is stored on the computer, but perhaps using source control puts more info in the project than you can see and the info doesn't match between the two computers.

Which means you can't put the working folders on your desktop or your "MyProjects" folder, etc., since your profile has your name and the other computer would have another user's name in the profile. So your working folder would need to be specified off the root C:\ drive, in the exact same path down on both computers. For example, C:\HelpProjects\ProjectA.

I could be totally off base, but that was the first thought that came to mind.

[Nita Beck]

Lisa, you can be counted on to make informed suggestions, given your genius status. But alas, I don't think you'll win a cigar on that one

Per ClearCase's documentation, the paths don't have to be the same on each machine. In fact, the paths MUST be different because the paths to the development streams include the ClearCase user's name. In the case of my laptop, the path to a development stream (i.e., the working version of the Flare project on my hard drive) is something like "n.beck_ProductA_V1_Doc" while on my client's machine is "l.rund_ProductA_V1_Doc". All the folders within each of those folders is identical, of course. And for the imports in the local projects, I make sure to check out the import files and modify their absolute paths to the global project so the builds will work. Just can't fathom why it builds on my machine work but not on my clients.

FWIW, I'm using Windows 7 and he's using XP.

[LTinker68]

I wasn't talking about it being an issue on ClearCase's side. I was talking about on Flare's side. Even though Flare might not display the full path when you're in the authoring environment, it might still remember the top most folders and be looking for them when it builds. If you created the project on your computer then checked it into ClearCase initially from your computer, then there might be some data saved with the project that when someone else copies/checks out to their computer doesn't match.

But that was just a guess, so yes, I might be totally off base.

[Nita Beck]

Definitely worth examining when I'm onsite again tomorrow. Thanks, as always, Lisa.

EDIT: I just looked under the hood (i.e., in the code) of the target in my version of the project, and all the paths, including the path to the master page, are relative. Tomorrow I'll do the same in my client's version of the project on his machine. I suspect I'll find the same.

[LTinker68]

If you're familiar navigating the registry, you might check there, too. Theoretically that still shouldn't be the problem, because if it's going to write to the registry it should do so after you first bind to source control and therefore be relative to the source control on that computer, but if for some reason Flare is hard-coding a full path in the registry and that path is saved somewhere in the binding info for the project, then perhaps it's causing a problem when it's checked out on a different computer.

If the project did originate on your computer and was then bound to source control, then you can always try it in reverse -- create a test project on the other computer, bind it to source control, and see if you have problems building that project on your computer after checking out copies of everything.

[Nita Beck]

...because if it's going to write to the registry it should do so after you first bind to source control and therefore be relative to the source control on that computer, but if for some reason Flare is hard-coding a full path in the registry and that path is saved somewhere in the binding info for the project, then perhaps it's causing a problem when it's checked out on a different computer.

Still researching this problem, being onsite today at my client's. I'll post back what we find. However, I'm skeptical as well about the registry, given I did not bind the project from within Flare to ClearCase. All the source-controlling is done outside of Flare, directly in the ClearCase interface. Nonetheless, we'll explore that avenue.

And your suggestion to put an entirely different Flare project created from my client's machine into ClearCase and then see how that project behaves on my laptop is an excellent one.

[Andrew]

Like Lisa, I know nothing about ClearCase. However, since everything except Flare's build process appears to find and see the masterpage, and you have checked your stylesheets / target / project to ensure that the link is in fact correct, it's possible that the masterpage isn't *really* the problem at all, but merely a symptom.

Not sure how easy it would be to do this, but unset the masterpage (so none of your topics is applying a masterpage) and see if that resolves the issue. It's a shot in the dark, but if there is something else going on, I wouldn't be surprised to see some other error come up next.

[Nita Beck]

Andrew, you are brilliant to suggest that the supposedly missing master page was merely a symptom. Mystery is now solved, and the bottom line is that the error was human error, specifically, MY error.

On my client's machine, I made a copy of the master page, kept it in the same location, and pointed the target to this copy. Tried to build; got same failure. In the copy of the master page, I deleted proxies one at a time, rebuilding after each. Voila, after removing the relationship table proxy, the build succeeded.

So I went looking for the relationship table file that was supposed to be in the Project Organizer/Advanced folder, and it was MISSING. And that's when I remembered that I had not put the relationship table file into ClearCase in the first place, so when we joined the ClearCase project from my client's machine in order for him to have a wokring copy of the Flare project, the relationship table file didn't exist. And that ultimately caused the error.

The same relationship table file DOES exist on my machine, as I started the project on my machine, but I never put that relationship table file into ClearCase. I never did so because my intention is not to use it going forward... but I had forgotten that I had used a relationship proxy on the master page.

Thanks so much to you and to Lisa.

[LTinker68]

Make sure you submit that as a bug report to MadCap. The fact that the master page wasn't missing is obviously a bad error to show in the build process when in fact it was an element of the master page that was missing.

[Nita Beck]

Lisa, I will indeed. And besides not giving good build error messages, when I examined the target file, I saw that the Relationship Table tab didn't show a thing, no "(missing) blah blah blah" the way Flare shows that a stylesheet or TOC or whatever is missing.