Void-Safe Library Status

Revision as of 23:37, 7 April 2009 by Bmeyer (Talk | contribs) (Rules)


During the EiffelStudio 6.4 development cycle Eiffel Software and any willing third-party contributors are updating the Eiffel stock libraries to be Void-Safe. The libraries will still compile in non-Void-Safe contexts so your code will not be broken. The status reflects work completed so you may start migrating your own code to ensure Void-safety.

Make sure to follow the general rules given below, and ask the community for guidance if you run into any problems or uncertainties.

Completion Status

To better hightlight the usefulness of the void-safety mechanism, we have put together a non-exhaustive list of bugs found during the conversion process.

Library Name Status Credits
EiffelBase Done Eiffel Software
EiffelBase extension Done Eiffel Software (Larry)
EiffelTime Done Eiffel Software (Ted, Ian)
EiffelThread Done (classic) Eiffel Software (Arno)
EiffelUUID Done Eiffel Software (Paul)
Eiffel2Java Done Eiffel Software (Ted, Ian)
WEL Done Eiffel Software (Manu)
EiffelVision2 In progress Eiffel Software (Ian)
EiffelVision2 extension
EiffelProcess Done (classic) Eiffel Software (Arno)
Argument parser Done Eiffel Software (Paul)
EiffelLex Done Eiffel Software (Paul)
EiffelParse Done Eiffel Software (Ted, Ian)
EiffelNet Done Eiffel Software (Manu)
EiffelNet IPv6 Done Eiffel Software (Manu)
EiffelCurl Done Eiffel Software (Manu)
Encoding Done Eiffel Software (Ted, Ian)
EiffelCOM
EiffelStore In progress Eiffel Software (Larry)
EiffelTesting Done Eiffel Software (Arno)
EiffelWeb Done Eiffel Software (Manu)
Gobo In progress
- kernel (done)
Eiffel Software (Jocelyn,Larry) + GoboSoft (Eric)
Docking
Gobo extension Done Eiffel Software (Jocelyn)
EiffelGraph
Memory Analyzer
EiffelPreferences Batch done, Remaining Graphical part. Eiffel Software (Jocelyn)
Diff Done Eiffel Software (Paul)

Contributing

EiffelStudio is open source and welcomes the Eiffel community contributions to speed up the adaptation process. If you are interested in participating please put a comment on the discussion board with your contact details.

Rules to be applied

Please observe the following guidelines carefully to guarantee a quality result.

Examples

For examples of libraries already adapted, see UUID (for a small example) and EiffelBase (for a larger one).

Overall process

  1. First compile with the `full_class_checking' option on. Then enable the void-safe option.
  2. Compile libraries on all of Windows/.NET/Unix to ensure it is sound.
  3. Minimize modifications; types should be attached by default if it makes sense, otherwise it has to be detachable by default.
  4. Use the convention library-safe.ecf for naming void-safe libraries for now. All library references should be using the -safe.ecf variants.
  5. Use the same UUIDs for void-safe and non-void-safe libraries.
  6. Before any modifications add a library.lic and library-safe.lic (replace library with the name of the ECF minus the .ecf extension) next to the ECFs of the same name containing only the single line reference:forum2.
  7. Update all samples to use the void-safe ecfs and update them.

Rules

  1. DO NOT USE the attached keyword (ex-"!" attached mark).
  2. MINIMIZE USE OF OBJECT TEST; ideally, don't use object test unless there was an assignment attempt in the original library.
  3. When a precondition expects a Void argument, use detachable if attached by default.
  4. When a precondition expects a non-Void argument, use attached if detachable by default.
  5. Libraries should compile in both void-safe and non-void-safe mode (i.e. there should only be one version of each library).
  6. Only use the attribute keyword when it is impossible to initialize an attribute in the creation procedure. Never use it for lazy evaluation.
  7. You may include preconditions x /= Void, but it will have to be removed in the end (helped by a compiler warning that says this is not needed for attached x).

General cleanup

The void-safe adaptation process should be accompanied by a general upgrade to ISO/ECMA Eiffel:

  • Remove uses of is_equal and equal to compare objects. (They can cause catcalls.) Replace them with the tilde operator, i.e. a ~ b instead of equal (a, b) or a.is_equal (b). Be careful to preserve the semantics (~ always returns false in the case of non-identical types).
  • Replace the indexing keyword with note.
  • Remove the is keyword in routines. Use the Replace tool with the regex \ is[ \t]*$. (Be careful not to use replace all, because comments and multi-line strings may have "is" text!)
  • Replace the is keyword in constants with =.

Test authoring

1. Create a cluster called 'tests' in the library root folder. E.g., for the UUID library the 'tests' folder exists at '$ISE_LIBRARY/uuid/tests'.

2. In the library ECFs, exclude the 'tests' cluster because it contains testing code and not library code.

3. Add a testing 'tests.ecf' in the 'tests' folder. (See the UUID library for an example ECF.) Be sure to create a library ECF and change the UUID. The library should also use the void-safe options found in the associated library's ECF.

4. Create test class names using the library name along with TEST as a prefix:

   EiffelBase = BASE_TEST_
   EiffelThread = THREAD_TEST_
   EiffelVision2 = EV_TEST_ or VISION2_TEST_

Improving this page

As you encounter problems and devise your solutions, please include the results of your experience here.