From 50097bc6b567f302104228cb99318aa60fafeb30 Mon Sep 17 00:00:00 2001 From: Tully Foote Date: Mon, 30 Apr 2018 00:56:21 -0700 Subject: [PATCH 1/5] First draft of defining conflicts resolution. --- articles/150_message_field_names.md | 93 +++++++++++++++++++++++++++++ 1 file changed, 93 insertions(+) create mode 100644 articles/150_message_field_names.md diff --git a/articles/150_message_field_names.md b/articles/150_message_field_names.md new file mode 100644 index 000000000..4ea216dae --- /dev/null +++ b/articles/150_message_field_names.md @@ -0,0 +1,93 @@ +--- +layout: default +title: Message Field Name Conflicts +permalink: articles/message_field_conflicts.html +abstract: + As we move to support more platforms there are we are running into predefined fields and constants that conflict with languages or implementation keywords and macros. + This defines how to deal with existing and potential future conflicts. +published: true +author: '[Tully Foote](https://github.com/tfoote)' +categories: Interfaces +--- + +{:toc} + +# {{ page.title }} + +
+{{ page.abstract }} +
+ +Original Author: {{ page.author }} + +## Scope + +This article specifies how we will deal with conflicting fields and constants for different languages. +In the use of the IDL (TODO (tfoote) reference) there will inevitably be conflicting symbols, keywords, or definitions. + +## Background + +This has come up specifically as we're adding support for Windows for ROS2. +`winnt.h` defines several macros that conflict with existing enumerations. +It is also expected to happen as support for new languages are added. + +## New constants + +To avoid conflicts generally all constants should be prefixed with a `k`. This will avoid almost all conflicts. + +Google Style Guide: https://google.github.io/styleguide/cppguide.html#Constant_Names + +TODO(tfoote) Reference ROS2 style guide + +## Language Generator Requirements + +In the case that a new language is added and there is a detected existing symbol, the language specific generator is expected to implement a basic deconfliction mangling of the symbol to avoid the conflict. + +Each generator will define the mangling procedure and provide a list of symbols for which the procedure will be applied. +This list should be all known keywords or otherwise conflicting symbols. + +### Example Deconfliction Policy + +A example of a simple name mangling policy would be to append a trailing underscore for conflicting symbols. +So that would mean that `FOO` if declared as a conflicting symbol would be used in generated code as `FOO_`. + +A slightly more unique string is recommended for clarity. + +### Stability +Each language generator will provide a standard name deconfliction policy so that users can use the symbols in a stable manner. +If a change is needed the generated code should provide a full cycle of backwards compatibility to support changes. + +This table will remain stable so that codebases can rely on using the mangled symbols. +Appending to the table may be necessary if the first pass did not catch all the conflicting keywords. + +The removal of any protected keywords should be avoided if at all possible as it will require all code using that field or constant to be updated. + +### Table of deconfliction + +The language support package will provide a yaml file with a list of all the protected keywords and their mangled version in a dictionary as key and value respectively. + +For example if the language had conflicts for `FOO`, `new`, and `delete` it's yaml file would like like this: + +``` +FOO: FOO_ +new: new_ +delete: delete_ +``` + +This yaml file will be considered the authority for deconflicting and should be exported in a way that will allow downstream code generators to automatically apply the deconfliction policy. + +## Legacy Support + +There are a number of known conflicts with the existing ROS1 codebase. +In these few cases we will undefine the matching C/C++ preprocessor macros which are conflicting in the definition and define the old value. +This will be done only inside the declaration header and the definition will be restored before returning to the user's code. +If you are using the legacy defines it's required to use the namespaced reference instead of using a shorthand version as those are know to conflict. + +These values will also provide the new version with the deconfliction mangling applied. +It is recommended to move to the deconflicted version immediately. + +The backwards compatibility will be maintained for one year after Bouncy. + +* `NO_ERROR` +* `DELETE` +* `ERROR` From 88c02112fcdf276b7472a263c2ded1193391b1f6 Mon Sep 17 00:00:00 2001 From: Tully Foote Date: Mon, 30 Apr 2018 01:02:42 -0700 Subject: [PATCH 2/5] More info on background/motivation --- articles/150_message_field_names.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/articles/150_message_field_names.md b/articles/150_message_field_names.md index 4ea216dae..9e77edcc0 100644 --- a/articles/150_message_field_names.md +++ b/articles/150_message_field_names.md @@ -25,11 +25,12 @@ Original Author: {{ page.author }} This article specifies how we will deal with conflicting fields and constants for different languages. In the use of the IDL (TODO (tfoote) reference) there will inevitably be conflicting symbols, keywords, or definitions. -## Background +## Background and Motivation This has come up specifically as we're adding support for Windows for ROS2. `winnt.h` defines several macros that conflict with existing enumerations. It is also expected to happen as support for new languages are added. +We cannot know all the potential future keywords and restrictions from a language which is selected to add support for in the future so we must have a generic solution which will allow future languages to be added without disrupting the existing usages. ## New constants From 1ca37355b0f907f301580a54b7ea606a7ecf059e Mon Sep 17 00:00:00 2001 From: Tully Foote Date: Mon, 4 Jun 2018 17:06:39 -0700 Subject: [PATCH 3/5] refactoring the IDL field name specifications into the IDL article. --- articles/110_interface_definition.md | 81 +++++++++++++++++++++++- articles/150_message_field_names.md | 94 ---------------------------- 2 files changed, 79 insertions(+), 96 deletions(-) delete mode 100644 articles/150_message_field_names.md diff --git a/articles/110_interface_definition.md b/articles/110_interface_definition.md index 16803a291..d4a2dd254 100644 --- a/articles/110_interface_definition.md +++ b/articles/110_interface_definition.md @@ -126,11 +126,88 @@ Both file names must use an upper camel case name and only consist of alphanumer Field names must be lowercase alphanumeric characters with underscores for separating words. They must start with an alphabetic character, they must not end with an underscore and never have two consecutive underscores. -### Naming of constants +#### Naming Conflicts -Constant names must be uppercase alphanumeric characters with underscores for separating words. +When defining field names it has been recommended to avoid language keywords and other reserved symbols. +However since we cannot be guaranteed to know all conflicts of potential future languages or implementations we must have a way to systematically deal with these conflicts without disrupting existing code bases and implementations. +To that end we will require that language bindings provide a reproducable name mangling mapping that will prevent conflicts with reserved keywords or other conflicts. + +##### Background + +This has come up specifically as we're adding support for Windows for ROS2. +`winnt.h` defines several macros that conflict with existing enumerations. +It is also expected to happen as support for new languages are added. +We cannot know all the potential future keywords and restrictions from a language which is selected to add support for in the future so we must have a generic solution which will allow future languages to be added without disrupting the existing usages. + +##### Language Generator Requirements + +In the case that a new language is added and there is a detected conflicting name for a field, the language specific generator is expected to implement a basic deconfliction mangling of the symbol to avoid the conflict. + +Each generator will define the mangling procedure and provide a list of symbols for which the procedure will be applied. +This list should be all known keywords or otherwise conflicting symbols. + +##### Example Deconfliction Policy + +A example of a simple name mangling policy would be to append a trailing underscore for conflicting symbols. +So that would mean that `FOO` if declared as a conflicting symbol would be used in generated code as `FOO_`. + +Clearly this would collide if someone defined `class` and `class_`, so slightly more unique string is recommended for clarity and uniqueness. +The mangling should be designed so that accidental collisions between names and mangled names cannot happen. +One easy way to do this would be to a language specific valid character not valid in the standard field name specification. + + +##### Table of deconfliction + +The language support package will provide a yaml file with a list of all the protected keywords and their mangled version in a dictionary as key and value respectively. + +For example if the language had conflicts for `FOO`, `new`, and `delete` it's yaml file would like like this: + +``` +FOO: FOO_ +new: new_ +delete: delete_ +``` + +This yaml file will be considered the authority for deconflicting and should be exported in a way that will allow downstream code generators to automatically apply the deconfliction policy. + +##### Stability +Each language generator will provide a standard name deconfliction policy so that users can use the symbols in a stable manner. + +This table will remain stable so that codebases can rely on using the mangled symbols. +Appending to the table may be necessary if the first pass did not catch all the conflicting keywords. + +The removal of any protected keywords should be avoided if at all possible as it will require all code using that field or constant to be updated. + +##### Legacy Support + +There are a number of known conflicts with the existing ROS1 codebase. +In these few cases we will undefine the matching C/C++ preprocessor macros which are conflicting in the definition and define the old value. +This will be done only inside the declaration header and the definition will be restored before returning to the user's code. +If you are using the legacy defines it's required to use the namespaced reference instead of using a shorthand version as those are know to conflict. + +For an easy migration path. +The mangled version of the constants will be made available in ROS Melodic by manually defining them in parallel so that code can be ported and use the same constant values while the codebase is spanning ROS1 and ROS2 implementations. + +It is recommended to move to the deconflicted version immediately. + +Constants known to be at issue: + +* `NO_ERROR` +* `DELETE` +* `ERROR` + +#### Naming Constants + +Constant names must be uppercase alphanumeric characters with underscores for separating words except the first character which should be a lowercase k. They must start with an alphabetic character, they must not end with an underscore and never have two consecutive underscores. +To avoid conflicts generally all constants should be prefixed with a `k`. +This will avoid almost all conflicts in all languages. +This is designed to follow the Google Style Guide: [https://google.github.io/styleguide/cppguide.html#Constant_Names](https://google.github.io/styleguide/cppguide.html#Constant_Names) + +This should be used for newly defined constants. +When migrating messages from ROS1 if there are existing constants in use the new version should be defined side by side with the old name to provide backwards compatibility for a full deprecation cycle. + ## Syntax The message and service definitions are text files. diff --git a/articles/150_message_field_names.md b/articles/150_message_field_names.md deleted file mode 100644 index 9e77edcc0..000000000 --- a/articles/150_message_field_names.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -layout: default -title: Message Field Name Conflicts -permalink: articles/message_field_conflicts.html -abstract: - As we move to support more platforms there are we are running into predefined fields and constants that conflict with languages or implementation keywords and macros. - This defines how to deal with existing and potential future conflicts. -published: true -author: '[Tully Foote](https://github.com/tfoote)' -categories: Interfaces ---- - -{:toc} - -# {{ page.title }} - -
-{{ page.abstract }} -
- -Original Author: {{ page.author }} - -## Scope - -This article specifies how we will deal with conflicting fields and constants for different languages. -In the use of the IDL (TODO (tfoote) reference) there will inevitably be conflicting symbols, keywords, or definitions. - -## Background and Motivation - -This has come up specifically as we're adding support for Windows for ROS2. -`winnt.h` defines several macros that conflict with existing enumerations. -It is also expected to happen as support for new languages are added. -We cannot know all the potential future keywords and restrictions from a language which is selected to add support for in the future so we must have a generic solution which will allow future languages to be added without disrupting the existing usages. - -## New constants - -To avoid conflicts generally all constants should be prefixed with a `k`. This will avoid almost all conflicts. - -Google Style Guide: https://google.github.io/styleguide/cppguide.html#Constant_Names - -TODO(tfoote) Reference ROS2 style guide - -## Language Generator Requirements - -In the case that a new language is added and there is a detected existing symbol, the language specific generator is expected to implement a basic deconfliction mangling of the symbol to avoid the conflict. - -Each generator will define the mangling procedure and provide a list of symbols for which the procedure will be applied. -This list should be all known keywords or otherwise conflicting symbols. - -### Example Deconfliction Policy - -A example of a simple name mangling policy would be to append a trailing underscore for conflicting symbols. -So that would mean that `FOO` if declared as a conflicting symbol would be used in generated code as `FOO_`. - -A slightly more unique string is recommended for clarity. - -### Stability -Each language generator will provide a standard name deconfliction policy so that users can use the symbols in a stable manner. -If a change is needed the generated code should provide a full cycle of backwards compatibility to support changes. - -This table will remain stable so that codebases can rely on using the mangled symbols. -Appending to the table may be necessary if the first pass did not catch all the conflicting keywords. - -The removal of any protected keywords should be avoided if at all possible as it will require all code using that field or constant to be updated. - -### Table of deconfliction - -The language support package will provide a yaml file with a list of all the protected keywords and their mangled version in a dictionary as key and value respectively. - -For example if the language had conflicts for `FOO`, `new`, and `delete` it's yaml file would like like this: - -``` -FOO: FOO_ -new: new_ -delete: delete_ -``` - -This yaml file will be considered the authority for deconflicting and should be exported in a way that will allow downstream code generators to automatically apply the deconfliction policy. - -## Legacy Support - -There are a number of known conflicts with the existing ROS1 codebase. -In these few cases we will undefine the matching C/C++ preprocessor macros which are conflicting in the definition and define the old value. -This will be done only inside the declaration header and the definition will be restored before returning to the user's code. -If you are using the legacy defines it's required to use the namespaced reference instead of using a shorthand version as those are know to conflict. - -These values will also provide the new version with the deconfliction mangling applied. -It is recommended to move to the deconflicted version immediately. - -The backwards compatibility will be maintained for one year after Bouncy. - -* `NO_ERROR` -* `DELETE` -* `ERROR` From 3de83236bc6324b045aa6113c00c40a261478ff4 Mon Sep 17 00:00:00 2001 From: Tully Foote Date: Mon, 4 Jun 2018 17:15:01 -0700 Subject: [PATCH 4/5] Let build work by not using stripped jekyll environment. --- test_local_deploy.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/test_local_deploy.sh b/test_local_deploy.sh index 18c825d23..5ac609ab1 100755 --- a/test_local_deploy.sh +++ b/test_local_deploy.sh @@ -1,3 +1,3 @@ #!/bin/sh -docker run --rm -v `pwd`:/srv/jekyll -i -t -p 127.0.0.1:4000:4000 jekyll/jekyll:pages jekyll serve --watch +docker run --rm -v `pwd`:/srv/jekyll -i -t -p 127.0.0.1:4000:4000 jekyll/jekyll:builder jekyll serve --watch From 867860318fc9c4529e4fb16f9383b18855d6a326 Mon Sep 17 00:00:00 2001 From: Mikael Arguedas Date: Wed, 13 Jun 2018 08:10:45 +0200 Subject: [PATCH 5/5] typo --- articles/110_interface_definition.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/articles/110_interface_definition.md b/articles/110_interface_definition.md index d4a2dd254..09643b4bd 100644 --- a/articles/110_interface_definition.md +++ b/articles/110_interface_definition.md @@ -183,7 +183,7 @@ The removal of any protected keywords should be avoided if at all possible as it There are a number of known conflicts with the existing ROS1 codebase. In these few cases we will undefine the matching C/C++ preprocessor macros which are conflicting in the definition and define the old value. This will be done only inside the declaration header and the definition will be restored before returning to the user's code. -If you are using the legacy defines it's required to use the namespaced reference instead of using a shorthand version as those are know to conflict. +If you are using the legacy defines it's required to use the namespaced reference instead of using a shorthand version as those are known to conflict. For an easy migration path. The mangled version of the constants will be made available in ROS Melodic by manually defining them in parallel so that code can be ported and use the same constant values while the codebase is spanning ROS1 and ROS2 implementations.