$FG HOME: Difference between revisions

From FlightGear wiki
Jump to navigation Jump to search
(not an environment variable ...really)
m (Update macOS hidden folder information)
 
(35 intermediate revisions by 8 users not shown)
Line 1: Line 1:
'''$FG_HOME''' is an placeholder variable representing the path to where user-specific data is stored (not application data). $FG_HOME is NOT an environment variable that needs to be specifically configured for FlightGear to work, unlike [[$FG_ROOT]]. $FG_HOME is only used to refer to the OS-specific location for some settings/folders.
<!-- 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]]]]


Basically, it is a name for a directory that varies with the operating system and stores information between sessions: configuration/preferences, properties marked with the "user-archive" attribute and aircraft-specific settings (using the data helper class in aircraft.nas).  
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.  


===Common paths===
<code>$FG_HOME</code> should not be confused with  <code>[[$FG_ROOT]]</code>, which is generally read-only.
* '''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/])
<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™.''
: 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.
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.
: 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.
{{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.}}
: 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.
{{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).}}
* '''Windows:''' <tt>%APPDATA%\flightgear.org\</tt>
 
: %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</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.
== 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