$FG HOME: Difference between revisions

From FlightGear wiki
Jump to navigation Jump to search
mNo edit summary
m (Update macOS hidden folder information)
 
(24 intermediate revisions by 7 users not shown)
Line 1: Line 1:
'''$FG_HOME''' is a placeholder variable representing the path to where user-specific FlightGear data is stored (not application data). Unlike $FG_ROOT, $FG_HOME is NOT an environment variable that needs to be specifically configured for FlightGear to work. $FG_HOME is the only place were FlightGear data is written to, $FG_ROOT is generally read-only.
<!-- Broken image [[File:Fghome.png|400px|right|Screen shot showing structure of [[$FG_HOME]] ]] -->
[[File:Fghome-3.7.png|400px|right|Screen shot showing typical structure [[$FG_HOME]]]]


$FG_HOME is only used to refer to the OS-specific location for some settings/folders. The actual location of $FG_HOME will be determined by the fgfs binary during startup, it is a name for a directory that varies with the various operating systems supported by FG (Windows, OSX and Linux) and it stores information between sessions, such as: configuration/preferences, properties marked with the "user-archive" attribute and aircraft-specific settings (using the data helper class in aircraft.nas). $FG_HOME is also the location for the SQLite-based NavDB cache.
The [[Environment variables|environment variable]]<code>'''$FG_HOME'''</code> is a '''setting''' indicating the main location where user-specific FlightGear data is stored (not application data). <code>$FG_HOME</code> is a notable place were FlightGear data is written to. <code>$FG_HOME</code> is also where large amounts of data downloaded by FlightGear like [[TerraSync]] scenery or Aircraft data is written to, by default.  


($FG_HOME and the '''/sim/fg-home''' property should be considered read-only, because they cannot be affected during startup or at runtime)
<code>$FG_HOME</code> should not be confused with  <code>[[$FG_ROOT]]</code>, which is generally read-only.


'''Note that the [[Fgfsrc]] config file will not actually be saved in $FG_HOME, but just in $HOME'''
<code>$FG_HOME</code> is normally used to refer to the operating system specific location for some settings/folders. Its default value is determined by the <code>fgfs</code> binary during startup and is a directory that varies with the operating system supported by FG (Windows, OS X and Linux). ''It is [https://sourceforge.net/p/flightgear/mailman/message/34995089/ highly recommended] to rely on the default value (i.e., not setting <code>$FG_HOME</code> yourself in any way), unless you Really Know What You Are Doing™.''  
===Common paths===
* '''Linux:''' ~/.fgfs/
* '''Mac OS X:''' <tt>~/Library/Application Support/FlightGear</tt> (to learn more about viewing hidden folders, see [http://www.mikesel.info/show-hidden-files-mac-os-x-10-7-lion/])
: As all future FlightGear versions will take their preferences from here, it is a good idea to have their access available easily.
: Desktop/Finder/Go/Go to Folder is where you need to start.
: When given the option, input:  ~/Library/Application Support/FlightGear
: It is probably a good idea to have '~/Library/Application Support/FlightGear' saved on a Stickies note just in case you forget it.
: If you want/need to refer to any of these files frequently, you could make an alias of a file, or the whole folder, and place it somewhere easier to access. TerraSync data is also stored inside the user's home folder, in the 'only' location we are permitted to write too, $HOME/Library/Application Support/FlightGear. To be technical, that's the value of '$FG_HOME', which is where we store all temporary / user-local data such as saved prefs, TerraSync files and aircraft-specific config state. The OSX launcher doesn't actually set this path (any more), this location is the default used by FlightGear itself. You can of course override these paths and set FG_HOME or the TerraSync path manually, from the command line or a config file, but the defaults should 'do what you want'.


* '''Windows:''' <tt>%APPDATA%\flightgear.org\</tt>
Very advanced users (i.e. power users and developers) who wish to run parallel installs of FlightGear can specify a different <code>$FG_HOME</code> for each install as described below.  
: %APPDATA% is another environment variable that depends on your Windows version. On XP and older, it can be found under <tt>C:\Documents and Settings\{username}\Application Data</tt>. On Vista and later it can be found under <tt>C:\Users\{username}\AppData\Roaming</tt>. The folder is hidden by default; see [http://windows.microsoft.com/en-US/windows-vista/show-hidden-files these instructions] to unhide the folder.


You can determine the location of your $FG_HOME by using the [[Property browser|property tree browser]] and checking the value of '''/sim/fg-home''', the '''/sim/''' branch is also the place where you can find other folders, such as fg-root, fg-scenery and the current working directory (fg-current).
{{note|The <code>/sim/fg-home</code> property should be considered read-only, for similar reasons why <code>$FG_HOME</code> shouldn't be explicitly set by users.}}
{{note|FlightGear reads the <code>[[Fgfsrc|fgfsrc]]</code> config file from <code>$FG_HOME</code> if it exists (<tt>fgfsrc</tt> without any leading dot), in addition to <tt>.fgfsrc</tt> from <code>$HOME</code> (with a leading dot in this case).}}
 
== Content ==
In <code>$FG_HOME</code> is information stored between sessions.  That information is for example configuration/preferences, properties marked with the <code>user-archive</code> attribute and aircraft-specific settings (using the data helper class in <code>aircraft.nas</code>).  <code>$FG_HOME</code> is also the location for the SQLite-based [[Navdata cache|navdata cache]].
 
== Common paths ==
You can determine the location of your <code>$FG_HOME</code> by using the [[property browser]] and checking the value of <code>/sim/fg-home</code>, but the usual paths are shown below.
 
You can also use the [[Nasal Console]] to print out <code>$FG_HOME</code>:
<syntaxhighlight lang="nasal">
var path = getprop("/sim/fg-home");
print("Your $FG_HOME is at: ", path);
</syntaxhighlight>
 
The <code>/sim/</code> property subtree is also the place where you can find other folders, such as <code>fg-root</code>, <code>fg-scenery</code> and the current working directory (<code>fg-current</code>).
 
=== Linux ===
<code>~/.fgfs/</code>
 
=== Mac OS X ===
<code>~/Library/Application Support/FlightGear</code> (`~/Library` is a hidden folder by default. In versions of macOS newer than 10.12, you can use the shortcut `Cmd + Shift + .` to view hidden folders. For older versions, see [http://www.mikesel.info/show-hidden-files-mac-os-x-10-7-lion/])
 
As all future FlightGear versions will take their preferences from here, it is a good idea to have their access available easily.
 
Desktop/Finder/Go/Go to Folder is where you need to start.
 
When given the option, input:  <code>~/Library/Application Support/FlightGear</code>
 
It is probably a good idea to have <code>~/Library/Application Support/FlightGear</code> saved on a Stickies note just in case you forget it.
 
If you want/need to refer to any of these files frequently, you could make an alias of a file, or the whole folder, and place it somewhere easier to access. TerraSync data is stored in <code>$FG_HOME/TerraSync</code> in the default configuration, see [[TerraSync]] for details.
 
=== Windows ===
 
==== FlightGear 2020.3 and later ====
<code>%userprofile%\FlightGear</code>
 
<code>%userprofile%</code> is the directory that contains the [https://docs.microsoft.com/en-us/previous-versions/windows/desktop/legacy/bb776892(v=vs.85) Windows user profile] ([http://web.archive.org/web/20210320110758/https://docs.microsoft.com/en-us/previous-versions/windows/desktop/legacy/bb776892%28v=vs.85%29 perm])<code>.</code>Ways to find the<code>%userprofile%</code> directory: 1). Press <code>Windows key+R</code>or bring up the RUN box. Type <code>%userprofile%</code> to open. 2). In command prompt, type <code>cd</code> <code>%userprofile%</code>
 
<code>%userprofile%</code> is<code>%homedrive%\Users\''User name''</code> by default. Usually on most peoples systems: <Code>%homedrive%</Code> is C:\.
 
For example if your user profile was called <code>MyUserProfile</code>, it would most often be located under <code>C:\Users\MyUserProfile</code> . Then the path to <code>$FG_HOME</code> would be <code>C:\Users\MyUserProfile\FlightGear.</code>
 
In 2020.3.x the [[FlightGear Qt launcher|qt-launcher]] will notify users who have data in the old location under <code>%userprofile%\Documents\FlightGear</code>, and prompt users to move files to the new location under <code>%userprofile%\FlightGear</code>.
 
==== FlightGear 3.0 and later ====
<code>%userprofile%\Documents\FlightGear</code>
 
<code>%userprofile%</code> is <code>%homedrive%\Users\''User name''</code> by default, and <Code>%homedrive%</code> is usually C:\.
 
==== Before FlightGear 3.0 ====
<code>%APPDATA%\flightgear.org\</code>
 
<code>%APPDATA%</code> is another environment variable that depends on your Windows version. On XP and older, it can be found under <code>C:\Documents and Settings\''User name''\Application Data</code>. On Vista and later it can be found under <code>C:\Users\''User name''\AppData\Roaming</code>. The folder is hidden by default. See [http://windows.microsoft.com/en-US/windows-vista/show-hidden-files these instructions] to show the folder.
 
== Use in troubleshooting ==
As one user once said, "When in doubt delete <code>$FG_HOME</code>". Many problems, including corrupted databases, broken [[TerraSync]] and many others can be fixed by deleting <code>fgfs_0.txt</code>, <code>fgfs.txt</code>, <code>terrasync_cache</code>, and the [[Navdata cache|navdata cache]].
 
When you encounter problems, try deleting the files, but '''always''' keep the <code>[[Commonly used debugging tools#fgfs.log|fgfs.log]]</code> and <code>fgfs_0.log</code> log files to help in troubleshooting.
 
== Power Users ==
 
=== Parallel installs of FlightGear ===
Note you can also override FG_HOME in the environment, to have totally distinct installs - this would be my recommend approach to running multiple versions in parallel.
(The installers will always replace the stable / dev version as other commenters pointed out, so you can't use those so easily, you need to copy files around - I'm nota Windows expert so I don't know if there something that could be changed or improved here)
If you start multiple instances (the same version or different) of FGFS using the same value of FG_HOME (whether that be the default or a custom one), we use a lock file to ensure only one (the first) has write access. The rest will go into read-only mode, and as you can maybe guess, treat FG_HOME as read-only.
Sharing of aircraft / scenery is entirely about which paths are configured, BTW. However, one final caveat is that having multiple instances both running TerraSync, using the same terrasync dir, would likely act a bit funny. It ought to actually work, but it might download some things twice, and it's not a tested or supported configuration for the moment.<ref>{{cite web
  |url    =  https://forum.flightgear.org/viewtopic.php?p=304170#p304170
  |title  =  <nowiki> Re: Is it possible to install multiple instanes of FG in Win </nowiki>
  |author =  <nowiki> zakalawe </nowiki>
  |date  =  Jan 25th, 2017
  |added  =  Jan 25th, 2017
  |script_version = 0.40
  }}</ref>
 
Using the same [[TerraSync|TerraSyn]]<nowiki/>c directory can save a lot of downloading and disk space. You can use the --terrasync-dir=path [[Command line options|command line]] option. For example --terrasync-dir=C:\Path\to\my\separate\terrasync\folder\TerraSync. It's possible to add this option in the <code>Settings > Additional Settings</code> section of the [[qt-launcher]].
 
== Related content ==
=== Wiki articles ===
* [[FlightGear configuration via XML]]
* [[$FG_ROOT]]
* [[Property browser]]
* [[Properties persistent between sessions]]
 
=== References ===
{{Appendix}}


[[Category:Special directories|HOME]]
[[Category:Special directories|HOME]]
[[Category:Environment variables]]

Latest revision as of 22:12, 21 January 2024

Screen shot showing typical structure $FG_HOME

The environment variable$FG_HOME is a setting indicating the main location where user-specific FlightGear data is stored (not application data). $FG_HOME is a notable place were FlightGear data is written to. $FG_HOME is also where large amounts of data downloaded by FlightGear like TerraSync scenery or Aircraft data is written to, by default.

$FG_HOME should not be confused with $FG_ROOT, which is generally read-only.

$FG_HOME is normally used to refer to the operating system specific location for some settings/folders. Its default value is determined by the fgfs binary during startup and is a directory that varies with the operating system supported by FG (Windows, OS X and Linux). It is highly recommended to rely on the default value (i.e., not setting $FG_HOME yourself in any way), unless you Really Know What You Are Doing™.

Very advanced users (i.e. power users and developers) who wish to run parallel installs of FlightGear can specify a different $FG_HOME for each install as described below.

Note  The /sim/fg-home property should be considered read-only, for similar reasons why $FG_HOME shouldn't be explicitly set by users.
Note  FlightGear reads the fgfsrc config file from $FG_HOME if it exists (fgfsrc without any leading dot), in addition to .fgfsrc from $HOME (with a leading dot in this case).

Content

In $FG_HOME is information stored between sessions. That information is for example configuration/preferences, properties marked with the user-archive attribute and aircraft-specific settings (using the data helper class in aircraft.nas). $FG_HOME is also the location for the SQLite-based navdata cache.

Common paths

You can determine the location of your $FG_HOME by using the property browser and checking the value of /sim/fg-home, but the usual paths are shown below.

You can also use the Nasal Console to print out $FG_HOME:

var path = getprop("/sim/fg-home");
print("Your $FG_HOME is at: ", path);

The /sim/ property subtree is also the place where you can find other folders, such as fg-root, fg-scenery and the current working directory (fg-current).

Linux

~/.fgfs/

Mac OS X

~/Library/Application Support/FlightGear (`~/Library` is a hidden folder by default. In versions of macOS newer than 10.12, you can use the shortcut `Cmd + Shift + .` to view hidden folders. For older versions, see [1])

As all future FlightGear versions will take their preferences from here, it is a good idea to have their access available easily.

Desktop/Finder/Go/Go to Folder is where you need to start.

When given the option, input: ~/Library/Application Support/FlightGear

It is probably a good idea to have ~/Library/Application Support/FlightGear saved on a Stickies note just in case you forget it.

If you want/need to refer to any of these files frequently, you could make an alias of a file, or the whole folder, and place it somewhere easier to access. TerraSync data is stored in $FG_HOME/TerraSync in the default configuration, see TerraSync for details.

Windows

FlightGear 2020.3 and later

%userprofile%\FlightGear

%userprofile% is the directory that contains the Windows user profile (perm).Ways to find the%userprofile% directory: 1). Press Windows key+Ror bring up the RUN box. Type %userprofile% to open. 2). In command prompt, type cd %userprofile%

%userprofile% is%homedrive%\Users\User name by default. Usually on most peoples systems: %homedrive% is C:\.

For example if your user profile was called MyUserProfile, it would most often be located under C:\Users\MyUserProfile . Then the path to $FG_HOME would be C:\Users\MyUserProfile\FlightGear.

In 2020.3.x the qt-launcher will notify users who have data in the old location under %userprofile%\Documents\FlightGear, and prompt users to move files to the new location under %userprofile%\FlightGear.

FlightGear 3.0 and later

%userprofile%\Documents\FlightGear

%userprofile% is %homedrive%\Users\User name by default, and %homedrive% is usually C:\.

Before FlightGear 3.0

%APPDATA%\flightgear.org\

%APPDATA% is another environment variable that depends on your Windows version. On XP and older, it can be found under C:\Documents and Settings\User name\Application Data. On Vista and later it can be found under C:\Users\User name\AppData\Roaming. The folder is hidden by default. See these instructions to show the folder.

Use in troubleshooting

As one user once said, "When in doubt delete $FG_HOME". Many problems, including corrupted databases, broken TerraSync and many others can be fixed by deleting fgfs_0.txt, fgfs.txt, terrasync_cache, and the navdata cache.

When you encounter problems, try deleting the files, but always keep the fgfs.log and fgfs_0.log log files to help in troubleshooting.

Power Users

Parallel installs of FlightGear

Note you can also override FG_HOME in the environment, to have totally distinct installs - this would be my recommend approach to running multiple versions in parallel. (The installers will always replace the stable / dev version as other commenters pointed out, so you can't use those so easily, you need to copy files around - I'm nota Windows expert so I don't know if there something that could be changed or improved here) If you start multiple instances (the same version or different) of FGFS using the same value of FG_HOME (whether that be the default or a custom one), we use a lock file to ensure only one (the first) has write access. The rest will go into read-only mode, and as you can maybe guess, treat FG_HOME as read-only. Sharing of aircraft / scenery is entirely about which paths are configured, BTW. However, one final caveat is that having multiple instances both running TerraSync, using the same terrasync dir, would likely act a bit funny. It ought to actually work, but it might download some things twice, and it's not a tested or supported configuration for the moment.[1]

Using the same TerraSync directory can save a lot of downloading and disk space. You can use the --terrasync-dir=path command line option. For example --terrasync-dir=C:\Path\to\my\separate\terrasync\folder\TerraSync. It's possible to add this option in the Settings > Additional Settings section of the qt-launcher.

Related content

Wiki articles

References

References