Deprecate legacy API [AP-643] (#1373)

# Description

@swift-nav/devinfra

Follow through on legacy API deprecation plan as previously agreed upon.
The goals of this PR are:

- Keep the legacy API in place but make it much more difficult to access
  - Any usage of the legacy API must be explicit on behalf of the user
- Legacy API no longer implicitly available by including `libsbp/sbp.h`
- legacy headers must be explicitly included
- All header files in the legacy API generate a compile time message at
the point of inclusion warning that they will be removed in version 6
- All symbols in the legacy API are marked with the `deprecated`
attribute
- All mentions of `v4` (ie, the modern replacement API) removed from
headers, source files, etc. Moving forwards there will be no such thing
as the "v4" API, there will just be the libsbp API
- Shuffle files around in the source and include directories to better
reflect the transition from legacy to modern APIs
- The correct way to include a package worth of message types is by
including (eg) `libsbp/observation.h`
- v4 "package" header files (eg `libsbp/v4/observation.h`) are still
available but are deprecated. They generate a compile time message
warning that they will be removed in version 6 and then include
`libsbp/<package>.h` (the new header file) automatically
- The end goal of all of this is that there is the libsbp API
(previously know as the v4 API), plus a legacy API which is hanging
around but very much a second class citizen.
- The legacy code is sufficiently separated so that removing it in
version 6 should be a fairly trivial task consisting mostly of deleting
some source/header files and templates

# API compatibility

Does this change introduce a API compatibility risk?

Nothing significant. The vast majority of symbols are present and have
the same meaning as before. Users of the legacy API may find that they
need to alter some include directives, but the warnings should be
obnoxious enough that they have no excuse for not transitioning to the
modern API immediately.

The one piece which has changed is the C++ state wrapper (`sbp::State`)
which previously was capable of handling both the legacy and modern
APIs. This has been broken up so that `sbp::State` now only handles the
modern API, and a new class `sbp::LegacyState` inherits from
`sbp::State` and adds a coupld of functions to deal with the legacy API.
This class is immediately deprecated and marked for deletion in version
6

The modern API is untouched by this PR

## API compatibility plan

If the above is "Yes", please detail the compatibility (or migration)
plan:

All users must transition to the modern API immediately if they haven't
already done so.

# JIRA Reference

https://swift-nav.atlassian.net/browse/AP-643

Author: woodfell

.github/workflows/c.yaml

@@ -126,7 +126,7 @@ jobs:
           sudo apt-get -qq install gcc-multilib-mips-linux-gnu gcc-mips-linux-gnu qemu-user g++-mips-linux-gnu
 
       - name: Run big endian tests
-        run: make test-c-v4
+        run: make test-c-modern
         env:
           CC: mips-linux-gnu-gcc
           CXX: mips-linux-gnu-g++

Makefile

@@ -382,13 +382,13 @@ test-c:
 	$(MAKE) do-all-tests
 	$(call announce-end,"Finished running C tests")
 
-test-c-v4:
+test-c-modern:
 	$(call announce-begin,"Running C tests")
 	cd $(SWIFTNAV_ROOT)/c; \
 	mkdir -p build/ && cd build/; \
 	cmake $(CMAKEFLAGS) ../; \
-	$(MAKE) -j4 test-libsbp-v4 test-libsbp-cpp-v4; \
-	$(MAKE) do-test-libsbp-v4 do-test-libsbp-cpp-v4
+	$(MAKE) -j4 test-libsbp test-libsbp-cpp; \
+	$(MAKE) do-test-libsbp do-test-libsbp-cpp
 	$(call announce-end,"Finished running C tests")
 
 test-python:

c/BUILD.bazel

@@ -15,38 +15,38 @@ swift_c_library(
     srcs = [
         "src/edc.c",
         "src/sbp.c",
-        "src/v4/string/sbp_string.c",
-        "src/v4/string/multipart.c",
-        "src/v4/string/null_terminated.c",
-        "src/v4/string/double_null_terminated.c",
-        "src/v4/string/unterminated.c",
+        "src/string/sbp_string.c",
+        "src/string/multipart.c",
+        "src/string/null_terminated.c",
+        "src/string/double_null_terminated.c",
+        "src/string/unterminated.c",
         # generated files
-        "src/v4/acquisition.c",
-        "src/v4/bootload.c",
-        "src/v4/ext_events.c",
-        "src/v4/file_io.c",
-        "src/v4/flash.c",
-        "src/v4/gnss.c",
-        "src/v4/imu.c",
-        "src/v4/integrity.c",
-        "src/v4/linux.c",
-        "src/v4/logging.c",
-        "src/v4/mag.c",
-        "src/v4/navigation.c",
-        "src/v4/ndb.c",
-        "src/v4/observation.c",
-        "src/v4/orientation.c",
-        "src/v4/piksi.c",
-        "src/v4/sbas.c",
-        "src/v4/settings.c",
-        "src/v4/signing.c",
-        "src/v4/solution_meta.c",
-        "src/v4/ssr.c",
-        "src/v4/system.c",
-        "src/v4/telemetry.c",
-        "src/v4/tracking.c",
-        "src/v4/user.c",
-        "src/v4/vehicle.c",
+        "src/acquisition.c",
+        "src/bootload.c",
+        "src/ext_events.c",
+        "src/file_io.c",
+        "src/flash.c",
+        "src/gnss.c",
+        "src/imu.c",
+        "src/integrity.c",
+        "src/linux.c",
+        "src/logging.c",
+        "src/mag.c",
+        "src/navigation.c",
+        "src/ndb.c",
+        "src/observation.c",
+        "src/orientation.c",
+        "src/piksi.c",
+        "src/sbas.c",
+        "src/settings.c",
+        "src/signing.c",
+        "src/solution_meta.c",
+        "src/ssr.c",
+        "src/system.c",
+        "src/telemetry.c",
+        "src/tracking.c",
+        "src/user.c",
+        "src/vehicle.c",
     ],
     hdrs = SBP_INCLUDE + SBP_INCLUDE_INTERNAL,
     copts = [
@@ -80,24 +80,27 @@ swift_cc_test(
     includes = [
         "include/libsbp",
     ],
+    copts = [
+      "-Wno-deprecated-declarations",
+    ],
     type = UNIT,
     deps = [
         ":sbp",
         "@check",
     ],
 )
 
-SBP_V4_C_SOURCES = glob(["test/auto*.c"])
+SBP_C_SOURCES = glob(["test/auto*.c"])
 
 swift_cc_test(
-    name = "sbp-v4-test",
+    name = "sbp-test",
     srcs = [
         "test/check_main.c",
         "test/check_edc.c",
         "test/check_sbp.c",
         "test/check_bitfield_macros.c",
         "test/check_suites.h",
-    ] + SBP_V4_C_SOURCES,
+    ] + SBP_C_SOURCES,
     includes = ["include/libsbp"],
     type = UNIT,
     deps = [
@@ -106,11 +109,11 @@ swift_cc_test(
     ],
 )
 
-SBP_CPP_V4_C_SOURCES = glob(["test/cpp/auto*.cc"])
+SBP_CPP_C_SOURCES = glob(["test/cpp/auto*.cc"])
 
 swift_cc_test(
-    name = "sbp-cpp-v4-test",
-    srcs = SBP_CPP_V4_C_SOURCES,
+    name = "sbp-cpp-test",
+    srcs = SBP_CPP_C_SOURCES,
     type = UNIT,
     deps = [
         ":sbp",
@@ -146,6 +149,9 @@ swift_cc_test(
     data = [
         "test/legacy/cpp/sbp_data/gnss_data.sbp",
     ],
+    copts = [
+      "-Wno-deprecated-declarations",
+    ],
     type = UNIT,
     deps = [
         ":sbp",

c/examples/CMakeLists.txt

@@ -3,5 +3,5 @@ option(BUILD_EXAMPLES "" OFF)
 if(BUILD_EXAMPLES)
   add_custom_target(examples)
   add_subdirectory(legacy)
-  add_subdirectory(v4)
+  add_subdirectory(libsbp)
 endif()

c/examples/legacy/CMakeLists.txt

@@ -1,4 +1,4 @@
 foreach(target example cpp_example tcp_example tcp_2sigma_example)
   add_subdirectory(${target})
-  add_dependencies(examples libsbp_${target})
-endforeach()
+  add_dependencies(examples libsbp_legacy_${target})
+endforeach()

c/examples/legacy/cpp_example/CMakeLists.txt

@@ -1,5 +1,5 @@
 cmake_minimum_required(VERSION 2.8.9)
-project(libsbp_cpp_example)
+project(libsbp_legacy_cpp_example)
 
 set(CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/cmake")
 
@@ -11,5 +11,5 @@ find_package(PkgConfig)
 link_directories("/usr/local/lib/")
 include_directories("/usr/local/include/")
 
-add_executable(libsbp_cpp_example cpp_example.cc)
-target_link_libraries(libsbp_cpp_example sbp)
+add_executable(libsbp_legacy_cpp_example cpp_example.cc)
+target_link_libraries(libsbp_legacy_cpp_example sbp)

c/examples/legacy/cpp_example/cpp_example.cc

@@ -1,7 +1,7 @@
 #include <iostream>
 #include <fstream>
 
-#include <libsbp/cpp/state.h>
+#include <libsbp/legacy/cpp/legacy_state.h>
 #include <libsbp/legacy/cpp/payload_handler.h>
 #include <libsbp/legacy/cpp/frame_handler.h>
 
@@ -36,7 +36,7 @@ class SbpFileReader : public sbp::IReader {
 
 class ECEFHandler : private sbp::PayloadHandler<msg_gps_time_t, msg_pos_ecef_t> {
   public:
-    ECEFHandler(sbp::State *state) : sbp::PayloadHandler<msg_gps_time_t, msg_pos_ecef_t>(state) {
+    ECEFHandler(sbp::LegacyState *state) : sbp::PayloadHandler<msg_gps_time_t, msg_pos_ecef_t>(state) {
     }
 
     void handle_sbp_msg(uint16_t sender_id, uint8_t message_length, const msg_gps_time_t& msg) {
@@ -55,7 +55,7 @@ class ECEFHandler : private sbp::PayloadHandler<msg_gps_time_t, msg_pos_ecef_t>
 
 class LLHFrameHandler : private sbp::FrameHandler<msg_gps_time_t, msg_pos_llh_t> {
   public:
-    LLHFrameHandler(sbp::State *state) : sbp::FrameHandler<msg_gps_time_t, msg_pos_llh_t>(state) {
+    LLHFrameHandler(sbp::LegacyState *state) : sbp::FrameHandler<msg_gps_time_t, msg_pos_llh_t>(state) {
     }
 
     void handle_sbp_frame(uint16_t sender_id, uint16_t msg_type,
@@ -74,7 +74,7 @@ class LLHFrameHandler : private sbp::FrameHandler<msg_gps_time_t, msg_pos_llh_t>
 
 class EverythingHandler : private sbp::AllFrameHandler {
   public:
-    EverythingHandler(sbp::State *state) : sbp::AllFrameHandler(state) {
+    EverythingHandler(sbp::LegacyState *state) : sbp::AllFrameHandler(state) {
     }
 
     void handle_sbp_frame(uint16_t sender_id, uint16_t msg_type,
@@ -102,7 +102,7 @@ int main(int argc, char **argv)
     exit(EXIT_FAILURE);
   }
 
-  sbp::State s;
+  sbp::LegacyState s;
   ECEFHandler ecef_handler(&s);
   LLHFrameHandler llh_handler(&s);
   EverythingHandler everything_handler(&s);

c/examples/legacy/example/CMakeLists.txt

@@ -1,11 +1,11 @@
 cmake_minimum_required(VERSION 2.8.9)
-project(libsbp_example)
+project(libsbp_legacy_example)
 
 set(CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/cmake")
 
 set(CMAKE_C_FLAGS "-Wall -Werror -Wno-error=deprecated-declarations -std=gnu99")
 
-add_executable(libsbp_example example.c)
+add_executable(libsbp_legacy_example example.c)
 
 find_package(PkgConfig)
 pkg_check_modules(LIBSERIALPORT libserialport)
@@ -15,4 +15,4 @@ include_directories(${LIBSERIALPORT_INCLUDE_DIRS})
 link_directories("/usr/local/lib/")
 include_directories("/usr/local/include/")
 
-target_link_libraries(libsbp_example serialport sbp)
+target_link_libraries(libsbp_legacy_example serialport sbp)

c/examples/legacy/example/example.c

@@ -7,6 +7,7 @@
 
 #include <libsbp/sbp.h>
 #include <libsbp/legacy/system.h>
+#include <libsbp/legacy/compat.h>
 
 char *serial_port_name = NULL;
 struct sp_port *piksi_port = NULL;

c/examples/legacy/tcp_2sigma_example/CMakeLists.txt

@@ -1,11 +1,11 @@
 cmake_minimum_required(VERSION 2.8.9)
-project(libsbp_tcp_2sigma_example)
+project(libsbp_legacy_tcp_2sigma_example)
 
 set(CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/cmake")
 
 set(CMAKE_CXX_FLAGS "-Wall -Wextra -Werror -Wno-error=deprecated-declarations -std=c++14")
 
-add_executable(libsbp_tcp_2sigma_example tcp_2sigma_example.cc)
+add_executable(libsbp_legacy_tcp_2sigma_example tcp_2sigma_example.cc)
 
 find_package(PkgConfig)
 find_package(Eigen3)
@@ -15,10 +15,10 @@ option(SHOW_PLOT "" OFF)
 link_directories("/usr/local/lib/")
 include_directories("/usr/local/include/")
 
-target_link_libraries(libsbp_tcp_2sigma_example sbp)
+target_link_libraries(libsbp_legacy_tcp_2sigma_example sbp)
 
 if (SHOW_PLOT)
   find_package(OpenCV)
   set(CMAKE_CXX_FLAGS "-DSHOW_PLOT ${CMAKE_CXX_FLAGS}")
-  target_link_libraries(libsbp_tcp_2sigma_example opencv_core opencv_imgproc opencv_highgui)
+  target_link_libraries(libsbp_legacy_tcp_2sigma_example opencv_core opencv_imgproc opencv_highgui)
 endif()

c/examples/legacy/tcp_2sigma_example/tcp_2sigma_example.cc

@@ -41,6 +41,7 @@
 
 #include <libsbp/sbp.h>
 #include <libsbp/legacy/navigation.h>
+#include <libsbp/legacy/compat.h>
 
 // width and height of the plot window in pixels
 #define SIZE_PIXELS 300

c/examples/legacy/tcp_example/CMakeLists.txt

@@ -1,15 +1,15 @@
 cmake_minimum_required(VERSION 2.8.9)
-project(libsbp_tcp_example)
+project(libsbp_legacy_tcp_example)
 
 set(CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/cmake")
 
 set(CMAKE_C_FLAGS "-Wall -Wextra -Wno-strict-prototypes -Werror -Wno-error=deprecated-declarations -std=gnu99 ${CMAKE_C_FLAGS}")
 
-add_executable(libsbp_tcp_example tcp_example.c)
+add_executable(libsbp_legacy_tcp_example tcp_example.c)
 
 find_package(PkgConfig)
 
 link_directories("/usr/local/lib/")
 include_directories("/usr/local/include/")
 
-target_link_libraries(libsbp_tcp_example sbp)
+target_link_libraries(libsbp_legacy_tcp_example sbp)

c/examples/legacy/tcp_example/tcp_example.c

@@ -7,6 +7,7 @@
 
 #include <libsbp/sbp.h>
 #include <libsbp/legacy/system.h>
+#include <libsbp/legacy/compat.h>
 
 char *tcp_ip_addr = NULL;
 char *tcp_ip_port = NULL;

c/examples/libsbp/CMakeLists.txt

@@ -0,0 +1,4 @@
+foreach(target example cpp_example cpp_traits_example tcp_example tcp_2sigma_example)
+    add_subdirectory(${target})
+    add_dependencies(examples libsbp_${target})
+endforeach()

c/examples/v4/cpp_example/CMakeLists.txt renamed to c/examples/libsbp/cpp_example/CMakeLists.txt

@@ -1,5 +1,5 @@
 cmake_minimum_required(VERSION 2.8.9)
-project(libsbp_v4_cpp_example)
+project(libsbp_cpp_example)
 
 set(CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/cmake")
 
@@ -11,5 +11,5 @@ find_package(PkgConfig)
 link_directories("/usr/local/lib/")
 include_directories("/usr/local/include/")
 
-add_executable(libsbp_v4_cpp_example cpp_example.cc)
-target_link_libraries(libsbp_v4_cpp_example sbp)
+add_executable(libsbp_cpp_example cpp_example.cc)
+target_link_libraries(libsbp_cpp_example sbp)

c/examples/v4/cpp_example/README.md renamed to c/examples/libsbp/cpp_example/README.md

@@ -1,5 +1,5 @@
 cmake_minimum_required(VERSION 2.8.9)
-project(libsbp_v4_cpp_traits_example)
+project(libsbp_cpp_traits_example)
 
 set(CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/cmake")
 
@@ -11,5 +11,5 @@ find_package(PkgConfig)
 link_directories("/usr/local/lib/")
 include_directories("/usr/local/include/")
 
-add_executable(libsbp_v4_cpp_traits_example cpp_example.cc)
-target_link_libraries(libsbp_v4_cpp_traits_example sbp)
+add_executable(libsbp_cpp_traits_example cpp_example.cc)
+target_link_libraries(libsbp_cpp_traits_example sbp)