eiffel-org/documentation/current/solutions/iron-eiffel-package-repository.wiki

[[Property:title|IRON: Eiffel package repository]]
[[Property:link_title|IRON packages]]
[[Property:weight|0]]
[[Property:uuid|17d54aa0-3d7f-4993-2ad6-423bd0cedd44]]
{{ReviewRequested}}

==Purpose==

The purpose of IRON is to be an easy-to-use facility for using and sharing libraries of quality Eiffel components.  It automates many of the tasks involved with maintaining such libraries, and provides a consistent method of doing so with minimal effort.

===Empowering Teams of Developers===

One area that teams of developers sometimes struggle with is how to share the same Eiffel Configuration File (.ECF file --  which has a function similar to a "solution" file in a Microsoft Visual Studio project), while having libraries installed in different places on the different computers used by the team.  Prior to IRON, the traditional solution was to use environment variables.  For example, when a library could be installed in different places on different team members’ computers, an environment variable would be created for it (on each system using the .ECF file).  And then, the environment variable is included in the .ECF file like this:

:<library name="presentation" location="$FSD_EIFFEL\presentation\presentation.ecf"/>
:<library name="awts" location="$LIBRARIES\Eiffel\AWTS\library\awts_library.ecf"/>
:<library name="cot" location="$LIB_COT\cot.ecf"/>
:etc.

After a few projects have been undertaken, and maintenance continues on the prior projects, the number of these variables start to add up quickly.  A dozen or more such variables per system was not uncommon.  And while it permitted individual programmers to manage the location of the libraries on their own systems, it quickly became unwieldy to coordinate among a team of programmers.

IRON has made it possible to simplify this scenario significantly.  Simply move commonly-used libraries onto an IRON server and place the path to their respective .ECF files in your project .ECF files and voila!  The paths to the above libraries then becomes something like this instead:

:<nowiki>http://iron.eiffel.com/13.11/crystal_clear_research/lib/presentation/presentation.ecf</nowiki>
:<nowiki>http://iron.eiffel.com/13.11/crystal_clear_research/lib/awts/awts.ecf</nowiki>
:<nowiki>http://iron.eiffel.com/13.11/crystal_clear_research/lib/cot/cot.ecf</nowiki>

And the need for a cumbersome set of environment variables disappears!

For those systems where the location of the library matters (e.g. for backups), the ISE_IRON_PATH environment variable can be established before the IRON packages are installed.  For others, they just install the package.  IRON and EiffelStudio take care of the remaining details.  And all developers on a project simply share the same .ECF file with no further worry about where the libraries are.


==Origin of the Name IRON==
 
The name Eiffel was chosen to reflect the elegance and soundness of constructing large, complex software systems, with '''simple, individual components, each of which is a unit by itself and has its own existence, and can be tested for integrity as a separate unit, but its role in the larger scheme of things is to be used as a "building block"''' for constructing high-integrity software systems.  The picture on the front of the book ''[[uuid:496983ef-b86e-772e-16b9-39b37ef80e37|Object-Oriented Software Construction, 2nd Edition]]'' illustrates this.
 
This of course is intentionally meant as a direct parallel to the famous structure built by the architect and civil engineer Alexandre Gustave Eiffel.  This structure was constructed with '''simple, individual components, each of which was a unit by itself and had its own existence and integrity as a separate unit, but its role in the larger scheme of things was to be used as a "building block"''' for constructing a high-integrity structure:  the Eiffel Tower.
 
As a parallel to this, "IRON", as a name, was chosen to reflect the fact that the individual building blocks were themselves made from iron.  In the Eiffel world, constructing a large complex software system is done with libraries of high-quality reusable components.  Thus, the "building blocks" are made from iron, and software systems are made from those building blocks.  Hence, IRON provides the "raw material" from which complex Eiffel systems are developed.


==Package Repository vs Library Repository==

Certainly the IRON repository is a repository of Eiffel libraries.  However, sometimes libraries are used together, or cross reference one another, and thus are appropriate to be delivered together as a unit.  Sometimes libraries also need to include other types of files, such as external .C files that may need to be compiled on the local platform to make .LIB or .OBJ files available to the linker (.a or .o on Unix and Linux systems), scripts or executables that need to be run as part of the installation process (e.g. to generate other files required by the library, install environment variables, generate source code from LEX files), or tool kits that are part of, or needed by, the library.   Since the IRON repository permits programmers to install software components in “units”, and since sometimes those units can contain more than one library, as well as other types of files, a new term was required to convey this concept:  package.

{{Definition|package|a downloadable unit of software from an IRON repository that contains one or more Eiffel libraries and their related files.}}


==What Is IRON?==
 
IRON is a facility that permits Eiffel programmers to easily install, remove, update, list, examine, search and share Eiffel packages.  Additionally, it permits easy maintenance of a local list of IRON repositories.  A default IRON server is provided (http://iron.eiffel.com) and a default repository is added automatically by the iron executable, based on the version of EiffelStudio that installed the iron executable.  Example:  http://iron.eiffel.com/13.11 .

The IRON facility consists of three parts:

* A default server at http://iron.eiffel.com/ (provides the web api and web interface for the repositories that are stored there;  you can add other IRON servers as they become available).

* The “iron” executable utility on the local machine (installed with EiffelStudio, the program that interacts with the web api).

* Within EiffelStudio and the Eiffel compiler, is the ability to read and use IRON references from the Eiffel Configuration File (.ECF).  (This integration will be expanded in future EiffelStudio releases.)


==How to Use==


1.

(Optional)  Create an IRON path environment variable on your system:  either ISE_IRON_PATH or IRON_PATH.  Set its value to the location you have designated for the IRON package repository on your local system.  If the path does not already exist, it will be created by the local IRON executable.  Example:

:Variable name:    ISE_IRON_PATH
:Variable value:     E:\Dev\Libraries\Eiffel\iron\

If you do not define one of these environment variables, the location used is:

:<My_Documents>\Eiffel User Files\<EiffelStudio_Version>\iron\
 

2.

Using the EiffelStudio command prompt (installed with EiffelStudio), execute the IRON command to install the packages you want to use:

:iron  install  <package_name>

(This step may be automated in EiffelStudio in the future.)


3.

If the package is simply an Eiffel library with its own .ECF file, then in each Eiffel project that uses that library, under

:Project Settings -> <target_name> -> Groups -> Libraries

right-click Libraries and add a library with the "Location" value referencing the .ECF file for that library.  You can use one of three methods for this -- all behave identically:
 
:a.	The recommended method is to use the IRON server's path to the .ECF file.  Example:

:::<nowiki>http://iron.eiffel.com/13.11/com.eiffel/library/base/base.ecf</nowiki>

::In this case, EiffelStudio will discover where the local IRON library is installed, and will compile with the local library files.

:b.	Set your ISE_LIBRARY environment variable to

:::<nowiki>http://iron.eiffel.com/13.11/com.eiffel</nowiki>

::and ensure your .ECF file points to a library with location

:::$ISE_LIBRARY\library\base\base.ecf

::(remove other references to a “base” library if they exist).

:c.	Use the traditional local path to the library's .ECF file.  Examples:

:::E:\Dev\Libraries\Eiffel\iron\packages\base\base.ecf
::or
:::$ISE_IRON_PATH\packages\base\base.ecf
::or
:::"C:\Users\user_name\Documents\Eiffel User Files\13.11\iron\packages\base\base.ecf"

::This latter method, while it works, is not recommended simply because it defeats some of the advantages of using the IRON repository in the first place.


4.

If the package has some other way of linking it with your Eiffel projects, e.g. to a .LIB file or to an external .DLL, then instructions for this should be provided within the package.


==How to Get Information About IRON Packages==

At the website provided by a particular IRON server, you can get information about available packages in a number of ways.  You can start by simply visiting the server’s base address:

:http://iron.eiffel.com/

This page lists the repository versions available.  Select the version that matches the version of EiffelStudio you have installed.  Example:  clicking on version 13.11 takes you to

:http://iron.eiffel.com/repository/13.11/

where you can list existing packages, or add a new package if you have an account on the server.  If you click the “Package list” or “All packages” link, it takes you to a list of packages available under that version.  To filter this list, you can use the search window.  You can specify search criteria in this format:

:criterion:search_string

Criteria available:


:{| class="wikitable"
|-
! Criterion
! Meaning
|-
| name
| string is contained in package name (wildcards are supported)
|-
| title
| string is contained in title
|-
| tag
| package contains search_string in its tags (i.e. keywords)
|-
| downloads
| has at least N downloads, e.g. downloads:25
|}


If a criterion is omitted, “name” is used by default.

Operators available:  or, and, not  (example:  name:er and not name:parser)

Finally, when you have found the package you want, click on its title, and the page displayed will contain detailed information about the package.  One of the important bits of information is a portion of the URI which you can use to define the path to the package.  For the “base” library (title: EiffelBase), these URIs look like this:

:'''Associated URIs'''
::* /13.11/com.eiffel/library/base
::* /13.11/com.eiffel/library/data_structure/adt/base

Given that the server’s HTTP address is (in this example)  <nowiki>http://iron.eiffel.com</nowiki>,  you can compose full paths from this, and use them in your Eiffel project.  In this case, you can include the EiffelBase library in your project by specifying either:

:<nowiki>http://iron.eiffel.com/13.11/com.eiffel/library/base/base.ecf</nowiki>

or

:<nowiki>http://iron.eiffel.com/13.11/com.eiffel/library/data_structure/adt/base/base.ecf</nowiki>

Both will cause your project to compile with the same EiffelBase library provided by this IRON repository, provided you previously issued the command

:> iron  install  base

or

:> iron  install  <nowiki>http://iron.eiffel.com/13.11/com.eiffel/library/base</nowiki>

on your system.


==Using IRON from the Command Line==


The “iron” executable is used to perform various operations such as search, install, remove, update and share.  This executable is installed with EiffelStudio in $ISE_EIFFEL/tools/spec/$ISE_PLATFORM/bin/.

 
===Quick Help from the Command Line===
 
:> iron help
 
lists the actions that are available.
 
:> iron <action>  --help
 
displays detailed usage syntax for the action specified.  Note that most of the actions have a -v (verbose) option that will display additional helpful information about the action performed, including (when relevant) the local path to the package.


===Action Summary===

:{| class="wikitable"
|-
! Action
! Meaning
|-
| update
| updates cached package information
|-
| list
| displays a list of available packages, and whether they are installed
|-
| search
| searches for a specified packages
|-
| info
| displays information about a specified packages
|-
| install
| installs specified packages
|-
| remove
| removes specified packages
|-
| repository
| manages repository list
|-
| share
| share and manage your packages (an account on the IRON server is required)
|}


===Examples===

Update cached iron repository information:
 
:> iron  update
 
Display information about the api_wrapper package:
 
:> iron  info  api_wrapper
 
:If the package is installed, the installation path will also be displayed.
 
Search for a package by name, ID or URI (package IDs and URIs are displayed by the "info" action) (future releases will enable searching by other criteria as well, such as by tags [i.e. keywords]):
 
:> iron  search  base
 
List available packages:
 
:> iron  list        
 
Install a package:
 
:> iron  install  base
 
:or
 
:> iron  install  <nowiki>http://iron.eiffel.com/13.11/com.eiffel/library/base</nowiki>

:(This latter form is useful in resolving name conflicts when, for instance, you have multiple IRON repositories registered on your system, and two or more contain a packaged called “base”.)

List installed packages:
 
:> iron  list  --installed
 
Uninstall a package:
 
:> iron  remove  base
 

===Advanced Usage===


====Managing Multiple Repositories====
 
It is possible to have more than one IRON repository server registered.  Examples:
 
:> iron  repository  --list
:> iron  repository  --add &nbsp;&nbsp;iron73 &nbsp;&nbsp;<nowiki>http://iron.eiffel.com/7.3</nowiki>
:> iron  repository  --add &nbsp;&nbsp;custom &nbsp;&nbsp;<nowiki>http://custom.example.com/13.11</nowiki>
:> iron  repository  --remove &nbsp;&nbsp;iron73

Note:  upon the release of EiffelStudio 14.05, the <respository_name>  argument will be removed.  Thus, the syntax for these examples will become:

:> iron  repository  --list
:> iron  repository  --add &nbsp;&nbsp;<nowiki>http://iron.eiffel.com/7.3</nowiki>
:> iron  repository  --add &nbsp;&nbsp;<nowiki>http://custom.example.com/13.11</nowiki>
:> iron  repository  --remove &nbsp;&nbsp;<nowiki>http://iron.eiffel.com/7.3</nowiki>


=====Multiple-Repository Name Conflict Resolution=====

If you have more than one IRON repository registered on your system, it is possible that the same package name may exist on more than one repository.  If this is the case, and you attempt to perform operations using that name only, the repository that will be used will be the first repository in the list that contains a package with that name.  If you need the package with that name from a different repository, then use the “id” or “uri” form of the identifying the package you want.

If the sequence of repositories is not to your liking, you can change it in three ways:

:* use the iron executable to remove and add repositories to re-sequence them, or

:* delete the repositories.conf file and use the iron executable to add them again in the sequence you want them.

:* edit the file repositories.conf with a plain text editor such as NOTEPAD in the directory indicated by your ISE_IRON_PATH (or IRON_PATH) environment variable (or <My_Documents>\Eiffel User Files\<EiffelStudio_Version>\iron\ if one of these environment variables are not defined on your system).  (Note that this latter method, while possible, is not recommended, since the syntax of that file can change with new releases.)


====Sharing Your Packages====

To build and share your own packages, you will need a user account on the IRON server which will host your packages.  Please visit http://iron.eiffel.com/repository/account/?register  to create a new account.
 
As usual, use
 
:>  iron  share  --help
 
to see the options available.
 
Example:
 
To build the “gps_nmea” package from your library c:\eiffel\library\gps_nmea\ :
 
:> iron  share  create  --username <your_id> --password <your_password>  --repository <nowiki>http://iron.eiffel.com/13.11</nowiki>  --package-archive-source “c:\eiffel\library\gps_nmea”  --name “gps_nmea” --description “GPS library that parses NMEA strings (a common GPS output format)” --index “/library/gps/nmea”

This command will:
 
:* create a new package named “gps_nmea” on iron repository “<nowiki>http://iron.eiffel.com/13.11</nowiki>”,
:* using the local folder “c:\eiffel\library\gps_nmea\” as the source code for the package, then
:* associate this package with URI “<nowiki>http://iron.eiffel.com/13.11/library/gps/nmea</nowiki>”.
 
With the release of EiffelStudio 14.05, there will additionally be a --title option to enable you to attach a formal title to the package.  Example:  --title  “GPS NMEA Parsing Library”.

After adding such a package to the library, it is recommended that you go to the website, double check that the package was created they way you wanted it to be, and edit its information, such as adding tags (keywords to help others find your library), a link to documentation, a link to applicable source code, etc.  Then, using the iron executable, install the package on your system, and go through the steps of using it in an Eiffel project, and correct any problems discovered, to verify that end users will be able to productively use your package.

It is also '''''strongly''''' encouraged to include (or provide a link to) documentation that orients the user to its use, and answers basic questions such as:  What is the package? What motivated you to create it?  What problem(s) does it address?  Under what circumstances can the package be productively used?  Under what circumstances should it ''not'' be used (if applicable)?  And some basic examples of its use.  If the package is complex, it can be very helpful to include a well-commented  application that demonstrates intended reuse of the package in software.

Important note:  having clear documentation that enables end users to easily learn how to use your package is a VITAL link in the ability to reuse software components as is so aptly described in ''[[uuid:496983ef-b86e-772e-16b9-39b37ef80e37|Object-Oriented Software Construction, 2nd Edition]]'', in the Modular Understandability criterion:

:'''''“A method favors Modular Understandability if it helps produce software in which a human reader can understand each module without having to know the others, or, at worst, by having to examine only a few of the others.”'''''

and the Self-Documentation Principle:

:'''''“The designer of a module should strive to make all information about the module part of the module itself.”'''''

The point:  reuse is only possible when end users can easily and quickly learn how to reuse software components available to them.


==Planned Enhancements==
 
The version of iron published at the release of EiffelStudio 7.3 was a first implementation, it covers the basic operations, but more features are planned or are already under development:
 
:* additional metadata to describe the package
:* the ability to analyze the contents of the package, to extract information related to its .ECF file(s)
:* improved search facilities
:* a way of ensuring that the package compiles under the specified version of EiffelStudio
:* detection and actions related to package dependencies
:* package versioning
:* ability to upgrade of packages already installed
:* post-installation operations
:* support for test suite
:* stronger iron support in compiler  (e.g. auto installation)
:* more features that users may request or suggest.