@@ -350,3 +350,179 @@ typedef struct foo_init_t {
int num_control;
int other_items;
----
+== API & ABI difference tools
+=== API difference tool
+The API doxygen documentation can be compared with a previous
+release to get the basic summary of changes, as shown below between 1.10.1.0 and
+1.11.0.0
+[source,bash]
+----
+GIT_BRANCH=master COMPARE_BRANCH=v1.10.1.0 ./diff-api.sh
+...
+...
+diff --suppress-common-lines --recursive -t -s -d --unified odp_diff-git___git_linaro_org_lng_odp_git_master-v1.12.0.0module/a_summary.txt odp_diff_2-git___git_linaro_org_lng_odp_git_v1_10_1_0-v1.10.1.0module/a_summary.txt
+--- odp_diff-git___git_linaro_org_lng_odp_git_master-v1.12.0.0module/a_summary.txt 2016-12-05 10:10:51.126723616 -0500
++++ odp_diff_2-git___git_linaro_org_lng_odp_git_v1_10_1_0-v1.10.1.0module/a_summary.txt 2016-12-05 10:10:51.318727901 -0500
+@@ -1,34 +1,36 @@
+
+-Generated from /home/mike/git/check-odp/build/odp_diff a details directory called odp_diff-git___git_linaro_org_lng_odp_git_master-v1.12.0.0module
++Generated from /home/mike/git/check-odp/build/odp_diff_2 a details directory called odp_diff_2-git___git_linaro_org_lng_odp_git_v1_10_1_0-v1.10.1.0module
+
+ MODULE FUNCTION TYPEDEF DEFINE
+- odp_atomic 45 1 0
+- odp_barrier 5 0 0
+- odp_buffer 12 0 0
+- odp_classification 17 1 0
+- odp_compiler_optim 12 0 13
++ odp_atomic 44 1 0
++ odp_barrier 4 1 0
++ odp_buffer 13 1 1
++ odp_classification 17 1 3
++ odp_compiler_optim 11 1 18
+ odp_cpu 13 0 0
+- odp_cpumask 19 0 0
+- odp_crypto 10 1 0
++ odp_cpumask 19 1 2
++ odp_crypto 10 1 1
+ odp_errno 4 0 0
+- odp_event 3 0 0
++ odp_event 3 1 1
+ odp_hash 3 1 0
+ odp_initialization 6 1 0
+- odp_locks 29 0 0
+- odp_packet 124 0 0
+- odp_packet_io 40 1 0
+- odp_pool 8 1 4
+- odp_queue 18 1 0
++ odp_locks 29 1 0
++ odp_packet 124 1 4
++ odp_packet_io 40 1 4
++ odp_pool 8 1 5
++ odp_queue 18 1 3
+ odp_random 1 0 0
+- odp_scheduler 18 1 0
+- odp_shared_memory 8 1 3
++ odp_scheduler 18 1 14
++ odp_shared_memory 8 1 5
+ odp_std_clib 3 0 0
+- odp_system 3 0 0
+- odp_thread 22 1 0
+- odp_time 13 0 3
+- odp_timer 23 0 1
+- odp_traffic_mngr 69 1 3
++ odp_system 3 1 0
++ odp_thread 22 1 2
++ odp_time 13 1 4
++ odp_timer 23 1 4
++ odp_traffic_mngr 70 1 18
+ odp_version 3 0 3
+- TOTAL 531 12 30
+....
+diff --suppress-common-lines --recursive -t -s -d --unified odp_diff-git___git_linaro_org_lng_odp_git_master-v1.12.0.0module/odp_atomic.txt odp_diff_2-git___git_linaro_org_lng_odp_git_v1_10_1_0-v1.10.1.0module/odp_atomic.txt
+--- odp_diff-git___git_linaro_org_lng_odp_git_master-v1.12.0.0module/odp_atomic.txt 2016-12-05 10:13:57.551084481 -0500
++++ odp_diff_2-git___git_linaro_org_lng_odp_git_v1_10_1_0-v1.10.1.0module/odp_atomic.txt 2016-12-05 10:13:57.723088576 -0500
+@@ -1,4 +1,3 @@
+- void odp_atomic_init_u32(odp_atomic_u32_t * atom, uint32_t val)
+ uint32_t odp_atomic_load_u32(odp_atomic_u32_t * atom)
+ void odp_atomic_store_u32(odp_atomic_u32_t * atom, uint32_t val)
+ uint32_t odp_atomic_fetch_add_u32(odp_atomic_u32_t * atom, uint32_t val)
+@@ -44,4 +43,6 @@
+ int odp_atomic_cas_acq_rel_u64(odp_atomic_u64_t * atom, uint64_t * old_val, uint64_t new_val)
+ int odp_atomic_lock_free_u64(odp_atomic_op_t * atomic_op)
+ union odp_atomic_op_t odp_atomic_op_t
++ struct odp_atomic_u64_s odp_atomic_u64_t
++ struct odp_atomic_u32_s odp_atomic_u32_t
+...
+Addtional detailed results follow for each summarized difference.
+...
+----
+If the summary is examined it can be seen that the odp_atomic module lost a function in its API
+
+ MODULE FUNCTION TYPEDEF DEFINE
+- odp_atomic 45 1 0
+...
++ odp_atomic 44 1 0
+
+
+If this tool shows a difference then it is likely that the API version number
+must be changed in the configure.ac.
+[source,automake]
+----
+##########################################################################
+# Set correct API version
+##########################################################################
+m4_define([odpapi_generation_version], [1])
+m4_define([odpapi_major_version], [12])
+m4_define([odpapi_minor_version], [0])
+m4_define([odpapi_point_version], [0])
+----
+
+=== ABI difference tool
+ABI and source code differences can be discovered using the ABI diff tool.
+The tool is is based on the Debian abi-compliance-checker tool.
+This tool generates a html detailed analysis and a short text summary as shown
+below. In this case between master and the monarch LTS release.
+
+[source,bash]
+----
+COMPARE_BRANCH=v1.11.0.0_monarch ./diff-api.sh
+...
+comparing ABIs ...
+comparing APIs ...
+creating compatibility report ...
+result: COMPATIBLE
+total "Binary" compatibility problems: 0, warnings: 0
+total "Source" compatibility problems: 0, warnings: 0
+see detailed report:
+ compat_reports/git.linaro.org_lng_odp-git.linaro.org_lng_odp/master_to_v1.11.0.0_monarch/compat_report.html
+preparation, please wait ...
+comparing ABIs ...
+comparing APIs ...
+creating compatibility report ...
+result: INCOMPATIBLE (Binary: 12%, Source: 12%)
+total "Binary" compatibility problems: 62, warnings: 4
+total "Source" compatibility problems: 62, warnings: 0
+see detailed report:
+ compat_reports/git.linaro.org_lng_odp-git.linaro.org_lng_odp/master_to_v1.11.0.0_monarch/compat_report.html
+moved report to ~/git/check-odp/publishing/diff-abi/libodp-compat_report.html
+
+----
+The html output is quite detailed as seen below
+
+.An example of the diff-abi html output
+image::Screenshot_diff-abi.png[align="center"]
+
+When it comes to the library version this tool makes things very clear listing
+added, changed and removed APIs
+[source,bash]
+----
+Removed Symbols 62
+atomic_inlines.h, libodp-linux.so.112.0.0
+odp_atomic_add_rel_u32 ( odp_atomic_u32_t* atom, uint32_t val )
+odp_atomic_add_rel_u64 ( odp_atomic_u64_t* atom, uint64_t val )
+odp_atomic_add_u32 ( odp_atomic_u32_t* atom, uint32_t val )
+odp_atomic_add_u64 ( odp_atomic_u64_t* atom, uint64_t val )
+odp_atomic_cas_acq_rel_u32 ( odp_atomic_u32_t* atom, uint32_t* old_val, uint32_t new_val )
+----
+
+If this tool shows a difference in the odp or helper library then the library
+version number must be changed in the configure.ac
+[source,bash]
+----
+##########################################################################
+# Set platform library version
+#
+# Follow version rules described here:
+# https://www.gnu.org/software/libtool/manual/html_node/Updating-version-info.html
+# Version is Current:Revision:Age
+# 1. if there are only source changes, use C:R+1:A
+# 2. if interfaces were added use C+1:0:A+1
+# 3. if interfaces were removed, then use C+1:0:0
+##########################################################################
+
+ODP_LIBSO_VERSION=112:0:0
+AC_SUBST(ODP_LIBSO_VERSION)
+
+ODPHELPER_LIBSO_VERSION=110:1:1
+AC_SUBST(ODPHELPER_LIBSO_VERSION)
+----
Signed-off-by: Mike Holmes <mike.holmes@linaro.org> --- doc/process-guide/release-guide.adoc | 176 +++++++++++++++++++++++++++++++++++ 1 file changed, 176 insertions(+) -- 2.9.3