Bootstrapping Plugins

Topics: Developer Forum
Feb 10, 2010 at 3:18 PM
Edited Feb 10, 2010 at 3:20 PM

Hi Eric,

The SHFBROOT environment variable is an awesome thing! This way, people can check-in SHFB directly into source control without the need to install to SHFB. Due to a recent feature request I fixed a bug that blocked a user of XSD Doc to also check-in the SHFB plug-in and successully using it.

During the bug fix I noticed that the SHFBROOT environment variable also allows me to use my plug-in during the build of my own plug-in. What sounds like a paradox actually makes a lot of sense. For example, my plug-in provides a way to document XML schemas using SHFB. The help file for my plug-in also wants to use that feature in order to document my MAML extensions. In addition, I am also providing a set of samples that show case my extension.

So I think it is very common problem for plug-in authors to use their own plug-ins during the build.

The build process accomplishes this by

  1. Compiling the plug-in.
  2. Copying the entire SHFB Installation to a temporary folder.
  3. Copying the plug-in into the temporary copy of SHFB.
  4. Invoking MSBuild to build the help file and passing the MSBuild property SHFBROOT pointing to the temporary copy of SHFB.

Basically, this works like a charme but it has two drawbacks:

  1. If my plug-in is already installed SHFB uses the installed one instead of the one that is contained side-by-side in the directory SHFBROOT points to. I guess your plug-in loader first loads all plug-ins under %ProgramData%\EWSoftware\Sandcastle Help File Builder\Components and Plug-Ins. Then it tries to load the ones in SHFBROOT and ignores any conflicts. I think it should be the other way around.
  2. It requires to copy the SHFB binaries to a temporary location in order to load plug-ins that are not installed.

I would propose introducing an additional environment variable that allows to specify a plug-in root, such as SHFBPLUGINROOT. Then I would expect SHFB to load plug-ins like this:

  1. If the SHFBPLUGINROOT is set, it loads all plug-ins contained in that directory (or any nested directory).
  2. Then it loads all plug-ins that reside side-by-side in SHFBROOT, ignoring all conflics with plug-ins that are already loaded in step 1.
  3. Then it loads all plug-ins from %ProgramData%\EWSoftware\Sandcastle Help File Builder\Components and Plug-Ins, ignoring all conflicts with plug-ins already loaded in steps 1 and 2.

Even with this new envrionment variable SHFBPLUGINROOT I still think that plug-ins from SHFBROOT should take precedence over the plug-ins from %ProgramData%\EWSoftware\Sandcastle Help File Builder\Components and Plug-Ins. If it would be the other way around (as it is now) installing plug-ins can break plug-ins that are contained in a local copy of SHFB comming from version control.

What do you think?

P.S. I hope this makes sense to you. If I did a bad job explaining, please let me know!

Coordinator
Feb 10, 2010 at 7:28 PM

That sounds fine.  I think I can just make it a general SHFBCOMPONENTROOT environment variable and apply the same logic for finding and loading build component info too.  By the way, thanks for the WiX setup project.  I finally got around to looking at WiX and will be using it for all subsequent releases to create the installer.

Eric

 

Feb 11, 2010 at 10:53 AM

Hi Eric,

EWoodruff wrote:

That sounds fine.  I think I can just make it a general SHFBCOMPONENTROOT environment variable and apply the same logic for finding and loading build component info too.

Oh yes - I always forget about the components. They should of course be handled the same way as plug-ins. Great that you like my idea!

EWoodruff wrote:

By the way, thanks for the WiX setup project.  I finally got around to looking at WiX and will be using it for all subsequent releases to create the installer.

You are welcome. I am happy to see that you found it useful and are even going to use it :-)

Best,
Immo