Issue:
- The majority, if not all, of the developers on the FlightGear project are Linux developers. (Which isn't a bad thing.)
- The Windows development, installation, and user paradigms are significantly different than the various Linux paradigms.
- The result of this is that the developers and package maintainers who build the Windows installers make assumptions about how the packages should install and run that are not necessarily true within the Windows environment.
- This also results in a, (ahem!), "less than optimal" installation, configuration, and run-time experience for the Windows user.
Therefore, the purpose of this document is to illustrate the various "best-practices" that help you as developers, package maintainers, and configuration managers develop installers and executables that work efficiently and smoothly within the Windows environment.
The result of all this will be to help:
- Make it easier for the typical Windows user to successfully install and use FlightGear - which will help expand adoption of this excellent software.
- Reduce maintenance headaches since - being installed correctly the first time - there is less to go wrong.
- Make it easier to maintain when something does go wrong, since the necessary information will be more easily found.
- Significantly improve the over-all user experience, helping to improve the reputation of Open Source (FOSS) software in general.
It might be interesting to note that, at the very least, some of these ideas can be carried back to the Linux installs as well.
Topic #1: Installation "Bitness"
It is important to carefully distinguish "bitness" (processor word-size), when installing any kind of software. The best-practices for respecting processor word-size during installation can be summed up by the following:
- Make sure that you do not accidentally install software that depends on a 64 bit system on a 32 bit O/S. (I am sure there are API calls, or installer macros that can be used to test for this and throw the appropriate errors.)
- If installing a 32 bit binary on a 64 bit system, make sure to install into the "Program Files (86)" directory as the "Program Files" directory is exclusively reserved for 64 bit executables on 64 bit systems.
- TEST: If there is a C:\Program Files (86)\ directory, it is very likely a 64 bit system.
Even though you can install executables wherever you wish, and they will still work, installing them to the correct executable folders will help people understand if they are 64 or 32 bit executables later on.
Note:
This test will also work with earlier versions of Windows. Since they are all 32 bit systems, the installer will never find the "Program Files(86)" folder. (There is an exception: Win XP-64. IMHO, anyone who is still running WinXP-64 is an absolutely blithering idiot, and deserves what he gets.)
Topic #2: Correct Usage of the Program Files and Program Data folders
(Note: This particular issue still catches even seasoned Windows developers. )
In Linux, a user process automatically has write privileges in a number of different directories all over the filesystem. Unlike Linux, the write scope for a non-elevated, (non root), process in later versions of Windows is very narrowly defined.
Here is how the write-scope of these directories are defined:
- Rule 1: NEVER, NEVER, EVER place anything in the Program Files directories except for STATIC binaries and STATIC data.
- Rule 2: Non-elevated programs or processes should NEVER try to write to either the program files or program data directories.
- Hint #1: If you find any program artifacts or fragments in the system's Virtual Store, then you need to move whatever you found there out of the directory that was moved - as this means that a non-elevated process tried to write somewhere it was not allowed to write.
- Hint #2: FlightGear is a non-elevated process, so it should never try to write to either program files, or program data, (or sub-directories of these two directories). Particularly, FlightGear should not try to use Program Files or Program Data as data storage.
"Static" executables, binaries, or data, are program objects that never change except if the program is patched, updates are applied, or the program itself is upgraded to a new version. (i.e. an elevated-process installer is used to modify them)
Note:
Even though earlier versions of Windows, (XP and earlier), do not enforce this, this is still an excellent "best-practice" that will work on these systems as well. Not to mention that it's a good thing to have a consistent install path and process.
Topic #3: Correct Placement of Volatile Program or User Data
Here are some tips on how to place volatile data in a Windows system so that it is easily modified by user processes, easily found, and easily maintained.
- A user's home directory is absolutely guaranteed to be writable by that user.
- In all versions of Windows the system variable "%userprofile%" returns the fully qualified path to the user's home directory. (i.e. In XP, 2000, or ME, %userprofile% is set to "C:\Documents and Settings\{username}". In Vista, Win-7, and Win-8, %userprofile% is set to "C:\Users\{username}"). It is useful to note that a "cd %userprofile%" command will always take you to the current user's home directory.
- It is a best-practice to create a specific subdirectory in the user's home folder to act as a container for all of the program's files, (i.e. "%userprofile%\FlightGear"), with specific main subfolders underneath it, like "Terrasync", "Aircraft", "Scenery", "Settings", (which should be the default location of the settings.fgrun file), etc.
- Installer Tip: These directories should be created, and the program default path parameters should be set to match them at install time. Likewise, the Terrasync directory should be set at install time as well.
Topic #4: Clear the VirtualStore
Verify, and if necessary clear, any cruft from the user's Virtual Store directory.
- There is a "feature" in Windows Vista and later - if a non-elevated process tries to access what the operating system considers a "protected" area, a copy is created, placed in the virtual store, and the process is given access to that instead.
- Though the actual, literal, path to the virtualized data is "C:\Users\{user}\AppData\Local\VirtualStore\Program Files\FlightGear\(etc)" the process using that data actually sees the data within the virtual store as "C:\Program Files\FlightGear\(etc)". In other words, the running, non-elevated process has no clue that it is actually running out of the virtual store.
- To make things even MORE interesting, updating the data within the real directory DOES NOT update the data within the Virtual Store. The result is that if an update, or re-install is done, and there is old data in the virtual store, the running executable will never see the new data. ( ) (See my blog posting on this exact issue at http://www.qatechtips.com/2010/01/windows-7-windows-vista-virtual-store.html)
As a result of this, the package maintainer that creates the Windows installer package must manually navigate to the Virtual Store by using the literal path for the user installing the package, (C:\Users\{user}\AppData\Local\VirtualStore), see if there is any Program Files [86] or Program Data cruft for FlightGear, and physically and manually remove it.
It should also be noted that if this rule - checking for the existence of cruft in the VirtualStore - is tried on earlier versions of Windows, it will also work. Since there is no VirtualStore directory, the program path followed will always be the "nothing found so there is nothing to remove" path.
Topic #5: Separate configuration from running the program
Running the program and configuring the program should be two completely separate and distinct things.
- It makes absolutely no sense whatsoever that the user should have to go through (almost) every configuration setting, every time when he wants to launch the program.
- There should be two executable paths within the startup menu for FlightGear: A "Configuration" executable that brings up the configuration dialogs, and a "FlightGear" executable - which should be represented by the icon on the desktop - that launches the actual "fly the damn airplane already!!" program.
- Most Windows users, not to mention the majority of reviewers, will do this exactly TWICE, and then say PUNT THIS!
Topic #6: Use the Windows path syntax
The directory configuration dialogs should use Windows default path syntax instead of the Unix syntax
- The directory configuration dialogs currently use the "Unix" style path syntax, (/xxx/yyy/zzz - using the forward slash).
- Windows systems have always used the "DOS" style path syntax, (..\xxx\yyy\zzz - using the back-slash).
- Defaulting to the Windows style paths will allow the user to cut-and-paste literal pathnames from windows or dialogs and use them in the configuration dialog un-changed.
- The current method requires the user to use the "browse" feature to find the path so that the path syntax is in Unix format.
Topic #7: Eliminate the Command Dialog
The background command dialog should not be shown to eliminate confusion.
- Having the background command dialog showing is distracting, visually noisy, and can cause confusion among users who are not used to seeing something like this.
- If something like this is ABSOLUTELY NECESSARY, (which I doubt, since it appears to never be used in normal use), this can be directed to a log-file somewhere.
Topic #8: Sensible Defaults at Installation
The installer should set, and enable, sensible defaults.
- The installer should create all the top-level data container directories, (Terrasync, Aircraft, Scenery, etc), within the FlightGear container directory. (See the example directory screen-shot located at http://www.mediafire.com/view/?2c2daupsyxa4pk7)
- The setup default directory paths should be set to the locations established above.
- Any directories that require special "marking" or "enabling", (such as the Terrasync directory), should be marked or enabled by default.
- The location of the "settings.fgrun" file should be located within the $FG_ROOT/Settings directory by default. (instead of the FlightGear program directory!)
- The program should set a reasonable "default" airport, (some small airport out in the middle of nowhere), in a reasonable default aircraft, (the Cessna 172R is a good choice). I have had the program - at initial startup - want to put me smack-dab in the middle of San-Francisco Intl. in a Boeing 777! Yikes!
- The program should set initial aircraft and flying defaults at the "fantasy" level. That is: perfect weather, easy flight settings, auto-coordination, inexhaustible fuel, crashes do no damage, etc. etc. etc. This allows the neophyte user to "get his hands dirty" relatively quickly with a minimum of frustration, allowing him to increase the realism settings as he grows more proficient. Of course, the experienced flight simmer already knows how to set things to his liking, set up multi-player, etc.
In essence, the ideal Windows setup would have the system set up in such a way that the typical user would be able to launch the program, crank up the throttle, and get into the air with an absolute minimum of trouble.
I am sure I will think of a few more things as I continue to work with FlightGear - so I may wish to update this.
What say ye?
Jim (JR)