Difference between revisions of "Void-Safe Library Status"
Peter gummer (Talk | contribs) m (→Overall process) |
Peter gummer (Talk | contribs) m (→Rules) |
||
Line 144: | Line 144: | ||
=== Rules === | === Rules === | ||
− | * DO NOT USE '''!''' (attached mark) | + | * 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. | |
− | * MINIMIZE USE OF OBJECT TEST; ideally, | + | * 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. | |
− | * When precondition | + | * Libraries should compile in both void-safe and non-void-safe mode. |
− | * When precondition | + | * 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). |
− | * Only use attribute keyword when it is | + | |
− | + | ||
− | * | + | |
=== General cleanup === | === General cleanup === |
Revision as of 17:54, 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.
Contents
Completion Status
Library Name | Status | Credits |
---|---|---|
EiffelBase | Done | Eiffel Software |
EiffelBase extension | ||
EiffelTime | ||
EiffelThread | Done (classic) | Eiffel Software |
EiffelUUID | Done | Eiffel Software |
Eiffel2Java | ||
WEL | ||
EiffelVision2 | ||
EiffelVision2 extension | ||
EiffelProcess | ||
Argument parser | Partial | Eiffel Software |
EiffelLex | ||
EiffelParse | ||
EiffelNet | ||
EiffelNet IPv6 | ||
EiffelCurl | ||
Encoding | ||
EiffelCOM | ||
EiffelStore | ||
EiffelTesting | ||
EiffelWeb | ||
Gobo | ||
Docking | ||
Gobo extension | ||
EiffelGraph | ||
Memory Analyzer | ||
EiffelPreferences |
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 the 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, 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 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.