Difference between revisions of "Void-Safe Library Status"

Revision as of 16:45, 26 December 2008

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

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 `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 (Note please use template files from rev#76374. in Delivery/studio/templates/licenses and place in $ISE_EIFFEL/studio/templates/licenses)
• Use Transitional Syntax in both the void-safe and non-void-safe libraries.

Rules

• DO NOT USE ! (attached mark)

• MINIMIZE USE OF OBJECT TEST; ideally, no object test unless there was an assignment attempt in the original library

• When precondition expect a Void argument, then use ? if attached by default.
• When precondition expect a non-Void argument, then use ! if detachable by default.
• Librairies should compile in both void-safe and non-void-safe mode.
• Only use attribute keyword when it is not possible to initialize an attribute in the creation procedure. Never use it for lazy evaluation.

• May include preconditions x /= Void, will have to be removed in the end (helped by compiler warning that says this is not needed for attached x).

General cleanup

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

• Remove uses of is_equal and equal to compare objects (they can cause catcalls) and repalce them by the tilda 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 case of non-identical types).

• Replace the indexing keyword by note.
• Remove is keyword in routines - use replace tool with regex \ is[\ \t]*$ (be careful, do not use replace all because comments and multi-line string may have "is" text!)
• Replace is usage in constants by =

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 UUID library for 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