Difference between revisions of "Void-Safe Library Status"

Revision as of 21:26, 2 February 2009

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.

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

• First compile with the `full_class_checking' option on. Then enable the void-safe option.
• Compile libraries on all of Windows/.NET/Unix to ensure it is sound.

• Minimize modifications; types should be attached by default if it makes sense, otherwise it has to be detachable by default.
• Use the convention library-safe.ecf for naming void-safe libraries for now. All library references should be using the -safe.ecf variants.
• Use the same UUIDs for void-safe and non-void-safe libraries.
• 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.
• Update all samples to use the void-safe ecfs and update them.

Rules

• DO NOT USE ! (attached mark).
• MINIMIZE USE OF OBJECT TEST; ideally, don't use object test unless there was an assignment attempt in the original library.
• When a precondition expects a Void argument, use ? if attached by default.
• When a precondition expects a non-Void argument, use ! if detachable by default.
• Libraries should compile in both void-safe and non-void-safe mode.
• Only use the attribute keyword when it is impossible to initialize an attribute in the creation procedure. Never use it for lazy evaluation.
• 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.