Difference between revisions of "Replaceable User Files"
m |
|||
(20 intermediate revisions by 3 users not shown) | |||
Line 1: | Line 1: | ||
− | |||
[[Category:Extending EiffelStudio]] | [[Category:Extending EiffelStudio]] | ||
[[Category:EiffelStudio]] | [[Category:EiffelStudio]] | ||
− | |||
− | With the release of EiffelStudio 6.2 came the notion of user files, or user replaceable files. These are configuration files and the like the end-user (that's you) can author to override a matching file found in the stock EiffelStudio installation. | + | With the release of [[:Category:EiffelStudio|EiffelStudio]] [[EiffelStudio 6.2 Releases|6.2]] came the notion of user files, or user replaceable files. These are configuration files, and the like, the end-user (that's you) can author to override a matching file found in the stock [[:Category:EiffelStudio|EiffelStudio]] installation. |
− | + | The advantages of such a mechanism are numerous; per-user configuration, user extensibility, customize/change an installation without touching the installation, augmenting the installation with additional files and folders, ... | |
− | == User | + | == User Files == |
+ | |||
+ | User files and folders can replace or augment files found under the installation under ''[[Environment Variables#Core Variables|$ISE_EIFFEL]]/studio''. The following indicates the corresponding user paths to place installation user replacement/augment files (''X.X'' indicates the ''Major.Minor'' version number of the compiler): | ||
+ | |||
+ | * Under '''Windows''' the default location for Eiffel user files is ''%HOMEDRIVE%\%HOMEPATH%\My Documents\Eiffel User Files\X.X\studio'' | ||
+ | |||
+ | * Under '''Unix/Linux''' the default location is ''~/.es/Eiffel User Files/X.X/studio'' | ||
+ | |||
+ | * Under '''Mac OS X''' the default location is ''~/Eiffel User Files/X.X/studio'' | ||
+ | |||
+ | If any of these location do not suit your needs, set the environment variable [[Environment Variables#Optional Variables|ISE_USER_FILES]] to point to the user files folder. Defining [[Environment Variables#Optional Variables|ISE_USER_FILES]] means user replacement/augmented files will be located under [[Environment Variables#Optional Variables|$ISE_USER_FILES]]/studio. | ||
+ | |||
+ | To replace an install file with a user file simply mirror the directory structure found under ''[[Environment Variables#Core Variables|$ISE_EIFFEL]]/studio'' in the user files folder, as explained above. Create or place a file with the same name in the user files respective folder and it will be utilized instead of the stock installed edition. It's that simple! | ||
+ | |||
+ | {{Note|If running a workbench version of [[:Category:EiffelStudio|EiffelStudio]] or the Eiffel compiler remember to place user files under the user file folder with a '' (workbench)'' suffix for Windows, and ''_workbench" suffix for non Windows. <br/>I.E. Under Linux place user files under ''~/.es_workbench/Eiffel User Files/X.X/studio'' instead of ''~/.es/Eiffel User Files/X.X/studio''.<br/> If the [[Environment Variables#Optional Variables|$ISE_USER_FILES]] environment variable has been defined then the suffix is not used because of the explicit use of an overriding the default value with an [[Environment Variables|environment variable]].}} | ||
+ | |||
+ | === User Folders === | ||
In some cases, user files can be found in a user folder and will not be used to replace stock installation files but to augment a stock collection of files with a user set. This functionality can be found when working with [[Code Templates|code templates]]. Templates work a little differently because the folder under the installation does not have to be mirrored in the user files folder. Instead under the user folder there is a separate ''templates'' folder used to contain any and all code templates for tools like the [[Contract Tool|contract tool]] and the [[Eiffel Editor|editor]]. | In some cases, user files can be found in a user folder and will not be used to replace stock installation files but to augment a stock collection of files with a user set. This functionality can be found when working with [[Code Templates|code templates]]. Templates work a little differently because the folder under the installation does not have to be mirrored in the user files folder. Instead under the user folder there is a separate ''templates'' folder used to contain any and all code templates for tools like the [[Contract Tool|contract tool]] and the [[Eiffel Editor|editor]]. | ||
Line 14: | Line 28: | ||
Not all files are currently supported with user files, just a select number of configuration files and template files. For all new developments, user files should be supported if applicable. | Not all files are currently supported with user files, just a select number of configuration files and template files. For all new developments, user files should be supported if applicable. | ||
− | For now there is no support for those version of EiffelStudio built using the Unix Layout. Unix layouts distribute files across the system and prevent a clean and reliable means to replicate an EiffelStudio installation, required to detect and utilize user files | + | For now there is no support for those version of [[:Category:EiffelStudio|EiffelStudio]] built using the [[LinuxUnixLayout|Unix Layout]]. [[LinuxUnixLayout|Unix layouts]] distribute files across the system and prevent a clean and reliable means to replicate an [[:Category:EiffelStudio|EiffelStudio]] installation, required to detect and utilize user files. |
== Working with User Files == | == Working with User Files == | ||
− | Most of the well know directories and files for the Eiffel compiler are located in a common class call <e>EIFFEL_ENV</e>, which is part of the environment library found in the EiffelStudio framework folder at ''[[Environment Variables#Auxiliary Variables|$EIFFEL_SRC]]/framework/environment''. There are effective implementations of <e>EIFFEL_ENV</e>; <e>EC_EIFFEL_LAYOUT</e> and <e>ES_EIFFEL_LAYOUT</e> used respectively in the Eiffel compiler and EiffelStudio. | + | Most of the well know directories and files for the Eiffel compiler are located in a common class call <e>EIFFEL_ENV</e>, which is part of the environment library found in the [[:Category:EiffelStudio|EiffelStudio]] framework folder at ''[[Environment Variables#Auxiliary Variables|$EIFFEL_SRC]]/framework/environment''. There are effective implementations of <e>EIFFEL_ENV</e>; <e>EC_EIFFEL_LAYOUT</e> and <e>ES_EIFFEL_LAYOUT</e> used respectively in the Eiffel compiler and [[:Category:EiffelStudio|EiffelStudio]]. |
− | {{Note|These classes need a little refactoring because most of the accessor functions live in <e>EIFFEL_ENV</e> instead of the more appropriate effective implementation class. It's just something to be aware of | + | {{Note|These classes need a little refactoring because most of the accessor functions live in <e>EIFFEL_ENV</e> instead of the more appropriate effective implementation class. It's just something to be aware in case of future changes.}} |
− | Most classes can access a single per-process instance of <e>EIFFEL_ENV</e> through inheriting <e>EIFFEL_LAYOUT</e> and accessing <e>eiffel_layout</e> or using it as a client. A single instance is used because (a) there are parts of the Eiffel system that have no idea if they are running inside EiffelStudio or as a TTY compiler (b) there are performance overheads | + | Most classes can access a single per-process instance of <e>EIFFEL_ENV</e> through inheriting <e>EIFFEL_LAYOUT</e> and accessing <e>eiffel_layout</e>, or alternatively using it as a client. A single instance is used because (a) there are parts of the Eiffel system that have no idea if they are running inside the graphical [[:Category:EiffelStudio|EiffelStudio]] IDE or as a TTY compiler (b) there are performance overheads when initializing <e>EIFFEL_ENV</e> so it's desirable to create and initialize the object once and once only. |
− | <e>EIFFEL_ENV</e> contains the two necessary functions to map an installation | + | <e>EIFFEL_ENV</e> contains the two necessary functions to map an installation file or folder to a user file or folder; <e>user_priority_file_name</e> and <e>user_priority_path</e> for retrieving a user file location and a folder path respectively. These functions take an absolute path and return either an existing user based location, or <e>Void</e> if no user specific file or folder was found. |
− | + | === Implementing User File Replacement === | |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | Here's an example of utilizing user files as found in <e>EIFFEL_ENV</e>: | |
− | + | <e> | |
− | + | compiler_configuration: FILE_NAME | |
− | + | -- Platform specific system level resource specification file | |
− | + | -- ($ISE_EIFFEL/eifinit/application_name/spec/$ISE_PLATFORM) | |
− | + | require | |
− | + | is_valid_environment: is_valid_environment | |
− | + | once | |
− | + | create Result.make_from_string (eifinit_path) | |
− | + | Result.set_file_name ("general") | |
+ | Result.add_extension ("cfg") | ||
+ | if is_user_files_supported then | ||
+ | -- Check user override file. | ||
+ | if attached user_priority_file_name (Result, True) as l_user then | ||
+ | Result := l_user | ||
+ | end | ||
+ | end | ||
+ | ensure | ||
+ | not_result_is_empty: not Result.is_empty | ||
+ | end | ||
</e> | </e> | ||
+ | |||
+ | In the example the path to ''general.cfg'' is built, which will be the normal default file used from the installation. A check is done to ensure the notion of user files is supported and being so, a check to see if there is a user specific version under the user folder. In the event that there is a user ''general.cfg'' file then it will be taken over the installed ''general.cfg''. In the example above the first argument represents the string path to map to a specific user file and the second Boolean argument indicates if a user file name should only be returned if the file actually exist. | ||
+ | |||
+ | The use of <e>user_priority_path</e> is exactly the same way, but typically user folders are used to augment the contents of the respective installation folder instead of the replacing the content. |
Latest revision as of 04:19, 21 January 2016
With the release of EiffelStudio 6.2 came the notion of user files, or user replaceable files. These are configuration files, and the like, the end-user (that's you) can author to override a matching file found in the stock EiffelStudio installation.
The advantages of such a mechanism are numerous; per-user configuration, user extensibility, customize/change an installation without touching the installation, augmenting the installation with additional files and folders, ...
Contents
User Files
User files and folders can replace or augment files found under the installation under $ISE_EIFFEL/studio. The following indicates the corresponding user paths to place installation user replacement/augment files (X.X indicates the Major.Minor version number of the compiler):
- Under Windows the default location for Eiffel user files is %HOMEDRIVE%\%HOMEPATH%\My Documents\Eiffel User Files\X.X\studio
- Under Unix/Linux the default location is ~/.es/Eiffel User Files/X.X/studio
- Under Mac OS X the default location is ~/Eiffel User Files/X.X/studio
If any of these location do not suit your needs, set the environment variable ISE_USER_FILES to point to the user files folder. Defining ISE_USER_FILES means user replacement/augmented files will be located under $ISE_USER_FILES/studio.
To replace an install file with a user file simply mirror the directory structure found under $ISE_EIFFEL/studio in the user files folder, as explained above. Create or place a file with the same name in the user files respective folder and it will be utilized instead of the stock installed edition. It's that simple!
Note: If running a workbench version of EiffelStudio or the Eiffel compiler remember to place user files under the user file folder with a (workbench) suffix for Windows, and _workbench" suffix for non Windows.
I.E. Under Linux place user files under ~/.es_workbench/Eiffel User Files/X.X/studio instead of ~/.es/Eiffel User Files/X.X/studio.
If the $ISE_USER_FILES environment variable has been defined then the suffix is not used because of the explicit use of an overriding the default value with an environment variable.
User Folders
In some cases, user files can be found in a user folder and will not be used to replace stock installation files but to augment a stock collection of files with a user set. This functionality can be found when working with code templates. Templates work a little differently because the folder under the installation does not have to be mirrored in the user files folder. Instead under the user folder there is a separate templates folder used to contain any and all code templates for tools like the contract tool and the editor.
Limitations
Not all files are currently supported with user files, just a select number of configuration files and template files. For all new developments, user files should be supported if applicable.
For now there is no support for those version of EiffelStudio built using the Unix Layout. Unix layouts distribute files across the system and prevent a clean and reliable means to replicate an EiffelStudio installation, required to detect and utilize user files.
Working with User Files
Most of the well know directories and files for the Eiffel compiler are located in a common class call EIFFEL_ENV
, which is part of the environment library found in the EiffelStudio framework folder at $EIFFEL_SRC/framework/environment. There are effective implementations of EIFFEL_ENV
; EC_EIFFEL_LAYOUT
and ES_EIFFEL_LAYOUT
used respectively in the Eiffel compiler and EiffelStudio.
Note: These classes need a little refactoring because most of the accessor functions live in
EIFFEL_ENV
instead of the more appropriate effective implementation class. It's just something to be aware in case of future changes.
Most classes can access a single per-process instance of EIFFEL_ENV
through inheriting EIFFEL_LAYOUT
and accessing eiffel_layout
, or alternatively using it as a client. A single instance is used because (a) there are parts of the Eiffel system that have no idea if they are running inside the graphical EiffelStudio IDE or as a TTY compiler (b) there are performance overheads when initializing EIFFEL_ENV
so it's desirable to create and initialize the object once and once only.
EIFFEL_ENV
contains the two necessary functions to map an installation file or folder to a user file or folder; user_priority_file_name
and user_priority_path
for retrieving a user file location and a folder path respectively. These functions take an absolute path and return either an existing user based location, or Void
if no user specific file or folder was found.
Implementing User File Replacement
Here's an example of utilizing user files as found in EIFFEL_ENV
:
compiler_configuration: FILE_NAME -- Platform specific system level resource specification file -- ($ISE_EIFFEL/eifinit/application_name/spec/$ISE_PLATFORM) require is_valid_environment: is_valid_environment once create Result.make_from_string (eifinit_path) Result.set_file_name ("general") Result.add_extension ("cfg") if is_user_files_supported then -- Check user override file. if attached user_priority_file_name (Result, True) as l_user then Result := l_user end end ensure not_result_is_empty: not Result.is_empty end
In the example the path to general.cfg is built, which will be the normal default file used from the installation. A check is done to ensure the notion of user files is supported and being so, a check to see if there is a user specific version under the user folder. In the event that there is a user general.cfg file then it will be taken over the installed general.cfg. In the example above the first argument represents the string path to map to a specific user file and the second Boolean argument indicates if a user file name should only be returned if the file actually exist.
The use of user_priority_path
is exactly the same way, but typically user folders are used to augment the contents of the respective installation folder instead of the replacing the content.