Merged in RobotLocomotion#2621.

CHANGELOG.md

@@ -16,7 +16,9 @@ Unreleased: changes on master, not yet released
 [//]: # "New functionality or APIs."
 ### Added
 
- - None
+ - [#2602][] Added `DRAKE_ASSERT` and `DRAKE_ABORT_UNLESS` macros to replace
+ built-in `assert()` macro.
+ - [#2621][] Added `DRAKE_DEPRECATED` macro for portable deprecation.
 
 [//]: # "Altered functionality or APIs."
 ### Changed
@@ -73,3 +75,5 @@ Changes in version v0.9.11 and before are not provided.
 [#2325]: https://github.com/RobotLocomotion/drake/issues/2325
 [#2426]: https://github.com/RobotLocomotion/drake/issues/2426
 [#2597]: https://github.com/RobotLocomotion/drake/issues/2597
+[#2602]: https://github.com/RobotLocomotion/drake/issues/2602
+[#2621]: https://github.com/RobotLocomotion/drake/issues/2621

drake/common/CMakeLists.txt

@@ -12,6 +12,7 @@ set(sources
 # are available elsewhere via #include "drake/common/xxx.h".
 set(installed_headers
   drake_assert.h
+  drake_deprecated.h
   nice_type_name.h
   )
 

drake/common/drake_deprecated.h

@@ -0,0 +1,62 @@
+#pragma once
+
+/** @file
+Provides a portable macro for use in generating compile-time warnings for
+use of code that is permitted but discouraged. **/
+
+#ifdef DRAKE_DOXYGEN_CXX
+/** Use `DRAKE_DEPRECATED("message")` to discourage use of particular
+classes, typedefs, variables, non-static data members, functions, arguments,
+enumerations, and template specializations. A compile time warning will be
+issued displaying the given message, preceded by "DRAKE DEPRECATED: ".
+
+This is typically used for constructs that have been replaced by something
+better and it is good practice to suggest the appropriate replacement in the
+deprecation message. Deprecation warnings are conventionally used to convey to
+users that a feature they are depending on will be removed in a future release.
+
+Usage: @code
+  // Attribute comes *before* declaration of a deprecated function or variable;
+  // no semicolon is allowed.
+  DRAKE_DEPRECATED("f() is slow; use g() instead")
+  int f(int arg);
+
+  // Attribute comes *after* struct, class, enum keyword.
+  class DRAKE_DEPRECATED("use MyNewClass instead")
+  MyClass {
+  };
+@endcode
+
+This feature is standard in C++14 compilers via the `[[deprecated]]` attribute,
+and this macro will generate the standard attribute when compiled with a
+C++14-compliant compiler. **/
+#define DRAKE_DEPRECATED(message)
+
+#else  // DRAKE_DOXYGEN_CXX
+
+/* C++14 introduces a standard way to mark deprecated declarations. Before
+that we can use non-standard compiler hacks. */
+#ifndef SWIG
+  /* Make sure warnings are enabled in VC++; it is a common Windows hack for
+  programmers to turn them off due to much inconvenient deprecation of useful
+  things by Microsoft. */
+  #if _MSC_VER
+    #pragma warning(default:4996)
+  #endif
+  /* Figure out the best form of deprecation for this compiler. */
+  #if __cplusplus >= 201402L
+    /* C++14 */
+    #define DRAKE_DEPRECATED(MSG) [[deprecated("\nDRAKE DEPRECATED: " MSG)]]
+  #elif _MSC_VER
+    /* VC++ just says warning C4996 so add "DEPRECATED" to the message. */
+    #define DRAKE_DEPRECATED(MSG) \
+      __declspec(deprecated("\nDRAKE DEPRECATED: " MSG))
+  #else /* gcc or clang */
+    #define DRAKE_DEPRECATED(MSG) \
+      __attribute__((deprecated("\nDRAKE DEPRECATED: " MSG)))
+  #endif
+#else /* Swigging */
+  #define DRAKE_DEPRECATED(MSG)
+#endif
+
+#endif  // DRAKE_DOXYGEN_CXX

drake/common/test/CMakeLists.txt

@@ -18,6 +18,10 @@ if(GTEST_FOUND)
   target_compile_definitions(drake_assert_test_disabled PRIVATE DRAKE_DISABLE_ASSERTS)
   target_link_libraries(drake_assert_test_disabled drakeCommon ${GTEST_BOTH_LIBRARIES})
   add_test(NAME drake_assert_test_disabled COMMAND drake_assert_test_disabled)
+
+  add_executable(drake_deprecated_test drake_deprecated_test.cc)
+  target_link_libraries(drake_deprecated_test drakeCommon ${GTEST_BOTH_LIBRARIES})
+  add_test(NAME drake_deprecated_test COMMAND drake_deprecated_test)
 endif()
 
 # The entire block of CMake build rules and CTests exists to confirm that the

drake/common/test/drake_deprecated_test.cc

@@ -0,0 +1,39 @@
+#include "drake/common/drake_deprecated.h"
+
+#include <string>
+#include <vector>
+
+#include "gtest/gtest.h"
+
+/* This test only verifies that the Drake build can still succeed if a 
+deprecated class or function is in use. I do not know how to test whether
+the desired warnings are actually issued except by inspection. */
+
+namespace {
+
+class DRAKE_DEPRECATED("use MyNewClass instead") MyClass {
+};
+
+class MyNewClass {
+};
+
+DRAKE_DEPRECATED("don't use this function; use g() instead")
+int f(int arg) { return arg; }
+
+int g(int arg) { return arg; }
+
+GTEST_TEST(DrakeDeprecatedTest, ClassTest) {
+  MyClass this_is_obsolete;
+  MyNewClass this_is_not;
+  (void)this_is_obsolete;  // avoid "unused" warning
+  (void)this_is_not;
+}
+
+GTEST_TEST(DrakeAssertDeathTest, FunctionTest) {
+  int obsolete = f(1);
+  int not_obsolete = g(1);
+  (void)obsolete;
+  (void)not_obsolete;
+}
+
+}  // namespace