Deprecate cr_plugin_load in favor of cr_plugin_open

Try to clarify the documentation about `CR_LOAD`/`CR_UNLOAD` and
`CR_CLOSE` as discussed in issue #49;

Issue #50 - Remove seemingly misplaced pragma causing warning on GCC/Clang.

README.md

@@ -36,7 +36,7 @@ int main(int argc, char *argv[]) {
     cr_plugin ctx;
 
     // the full path to the live-reloadable application
-    cr_plugin_load(ctx, "c:/path/to/build/game.dll");
+    cr_plugin_open(ctx, "c:/path/to/build/game.dll");
 
     // call the update function at any frequency matters to you, this will give
     // the real application a chance to run
@@ -56,8 +56,9 @@ While the guest (real application), would be like:
 CR_EXPORT int cr_main(struct cr_plugin *ctx, enum cr_op operation) {
     assert(ctx);
     switch (operation) {
-        case CR_LOAD:   return on_load(...);
-        case CR_UNLOAD: return on_unload(...);
+        case CR_LOAD:   return on_load(...); // loading back from a reload
+        case CR_UNLOAD: return on_unload(...); // preparing to a new reload
+        case CR_CLOSE: ...; // the plugin will close and not reload anymore
     }
     // CR_STEP
     return on_update(...);
@@ -66,6 +67,11 @@ CR_EXPORT int cr_main(struct cr_plugin *ctx, enum cr_op operation) {
 
 ### Changelog
 
+#### 2020-01-09
+
+- Deprecated `cr_plugin_load` in favor to `cr_plugin_open` for consistency with `cr_plugin_close`. See issue #49.
+- Minor documentation improvements.
+
 #### 2018-11-17
 
 - Support to OSX finished, thanks to MESH Consultants Inc.
@@ -116,7 +122,7 @@ Return
  being set to `CR_USER`. 0 or a positive value that will be passed to the
   `host` process.
 
-#### `bool cr_plugin_load(cr_plugin &ctx, const char *fullpath)`
+#### `bool cr_plugin_open(cr_plugin &ctx, const char *fullpath)`
 
 Loads and initialize the plugin.
 
@@ -133,7 +139,7 @@ Return
 #### `void cr_set_temporary_path(cr_plugin& ctx, const std::string &path)`
 
 Sets temporary path to which temporary copies of plugin will be placed. Should be called
-immediately after `cr_plugin_load()`. If `temporary` path is not set, temporary copies of
+immediately after `cr_plugin_open()`. If `temporary` path is not set, temporary copies of
 the file will be copied to the same directory where the original file is located.
 
 Arguments
@@ -169,12 +175,14 @@ Arguments
 
 Enum indicating the kind of step that is being executed by the `host`:
 
-- `CR_LOAD` A load is being executed, can be used to restore any saved internal
- state;
+- `CR_LOAD` A load caused by reload is being executed, can be used to restore any
+ saved internal state. This does not happen when a plugin is loaded for the first
+ time as there is no state to restore;
 - `CR_STEP` An application update, this is the normal and most frequent operation;
-- `CR_UNLOAD` An unload will be executed, giving the application one chance to
- store any required data.
-- `CR_CLOSE` Like `CR_UNLOAD` but no `CR_LOAD` should be expected;
+- `CR_UNLOAD` An unload for reloading the plugin will be executed, giving the 
+ application one chance to store any required data;
+- `CR_CLOSE` Used when closing the plugin, This works like `CR_UNLOAD` but no `CR_LOAD` 
+ should be expected afterwards;
 
 #### `cr_plugin`
 
@@ -463,7 +471,6 @@ struct cr_plugin {
 #define CR_STATE __attribute__((used, section("__DATA,__state")))
 #else
 #if defined(__GNUC__) // clang & gcc
-#pragma section(".state", read, write)
 #define CR_STATE __attribute__((section(".state")))
 #endif // defined(__GNUC__)
 #endif
@@ -647,7 +654,7 @@ static bool cr_plugin_changed(cr_plugin &ctx);
 static bool cr_plugin_rollback(cr_plugin &ctx);
 static int cr_plugin_main(cr_plugin &ctx, cr_op operation);
 
-static void cr_set_temporary_path(cr_plugin &ctx, const std::string &path) {
+void cr_set_temporary_path(cr_plugin &ctx, const std::string &path) {
     auto pimpl = (cr_internal *)ctx.p;
     pimpl->temppath = path;
 }
@@ -1904,7 +1911,7 @@ extern "C" int cr_plugin_update(cr_plugin &ctx, bool reloadCheck = true) {
 }
 
 // Loads a plugin from the specified full path (or current directory if NULL).
-extern "C" bool cr_plugin_load(cr_plugin &ctx, const char *fullpath) {
+extern "C" bool cr_plugin_open(cr_plugin &ctx, const char *fullpath) {
     CR_TRACE
     CR_ASSERT(fullpath);
     if (!cr_exists(fullpath)) {
@@ -1922,6 +1929,11 @@ extern "C" bool cr_plugin_load(cr_plugin &ctx, const char *fullpath) {
     return true;
 }
 
+// 20200109 [DEPRECATED] Use `cr_plugin_open` instead.
+extern "C" bool cr_plugin_load(cr_plugin &ctx, const char *fullpath) {
+    return cr_plugin_open(ctx, fullpath);
+}
+
 // Call to cleanup internal state once the plugin is not required anymore.
 extern "C" void cr_plugin_close(cr_plugin &ctx) {
     CR_TRACE

cr.h

@@ -37,7 +37,7 @@ int main(int argc, char *argv[]) {
     cr_plugin ctx;
 
     // the full path to the live-reloadable application
-    cr_plugin_load(ctx, "c:/path/to/build/game.dll");
+    cr_plugin_open(ctx, "c:/path/to/build/game.dll");
 
     // call the update function at any frequency matters to you, this will give
     // the real application a chance to run
@@ -57,8 +57,9 @@ While the guest (real application), would be like:
 CR_EXPORT int cr_main(struct cr_plugin *ctx, enum cr_op operation) {
     assert(ctx);
     switch (operation) {
-        case CR_LOAD:   return on_load(...);
-        case CR_UNLOAD: return on_unload(...);
+        case CR_LOAD:   return on_load(...); // loading back from a reload
+        case CR_UNLOAD: return on_unload(...); // preparing to a new reload
+        case CR_CLOSE: ...; // the plugin will close and not reload anymore
     }
     // CR_STEP
     return on_update(...);
@@ -67,6 +68,11 @@ CR_EXPORT int cr_main(struct cr_plugin *ctx, enum cr_op operation) {
 
 ### Changelog
 
+#### 2020-01-09
+
+- Deprecated `cr_plugin_load` in favor to `cr_plugin_open` for consistency with `cr_plugin_close`. See issue #49.
+- Minor documentation improvements.
+
 #### 2018-11-17
 
 - Support to OSX finished, thanks to MESH Consultants Inc.
@@ -117,7 +123,7 @@ Return
  being set to `CR_USER`. 0 or a positive value that will be passed to the
   `host` process.
 
-#### `bool cr_plugin_load(cr_plugin &ctx, const char *fullpath)`
+#### `bool cr_plugin_open(cr_plugin &ctx, const char *fullpath)`
 
 Loads and initialize the plugin.
 
@@ -134,7 +140,7 @@ Return
 #### `void cr_set_temporary_path(cr_plugin& ctx, const std::string &path)`
 
 Sets temporary path to which temporary copies of plugin will be placed. Should be called
-immediately after `cr_plugin_load()`. If `temporary` path is not set, temporary copies of
+immediately after `cr_plugin_open()`. If `temporary` path is not set, temporary copies of
 the file will be copied to the same directory where the original file is located.
 
 Arguments
@@ -170,12 +176,14 @@ Arguments
 
 Enum indicating the kind of step that is being executed by the `host`:
 
-- `CR_LOAD` A load is being executed, can be used to restore any saved internal
- state;
+- `CR_LOAD` A load caused by reload is being executed, can be used to restore any
+ saved internal state. This does not happen when a plugin is loaded for the first
+ time as there is no state to restore;
 - `CR_STEP` An application update, this is the normal and most frequent operation;
-- `CR_UNLOAD` An unload will be executed, giving the application one chance to
- store any required data.
-- `CR_CLOSE` Like `CR_UNLOAD` but no `CR_LOAD` should be expected;
+- `CR_UNLOAD` An unload for reloading the plugin will be executed, giving the 
+ application one chance to store any required data;
+- `CR_CLOSE` Used when closing the plugin, This works like `CR_UNLOAD` but no `CR_LOAD` 
+ should be expected afterwards;
 
 #### `cr_plugin`
 
@@ -464,7 +472,6 @@ struct cr_plugin {
 #define CR_STATE __attribute__((used, section("__DATA,__state")))
 #else
 #if defined(__GNUC__) // clang & gcc
-#pragma section(".state", read, write)
 #define CR_STATE __attribute__((section(".state")))
 #endif // defined(__GNUC__)
 #endif
@@ -648,7 +655,7 @@ static bool cr_plugin_changed(cr_plugin &ctx);
 static bool cr_plugin_rollback(cr_plugin &ctx);
 static int cr_plugin_main(cr_plugin &ctx, cr_op operation);
 
-static void cr_set_temporary_path(cr_plugin &ctx, const std::string &path) {
+void cr_set_temporary_path(cr_plugin &ctx, const std::string &path) {
     auto pimpl = (cr_internal *)ctx.p;
     pimpl->temppath = path;
 }
@@ -1905,7 +1912,7 @@ extern "C" int cr_plugin_update(cr_plugin &ctx, bool reloadCheck = true) {
 }
 
 // Loads a plugin from the specified full path (or current directory if NULL).
-extern "C" bool cr_plugin_load(cr_plugin &ctx, const char *fullpath) {
+extern "C" bool cr_plugin_open(cr_plugin &ctx, const char *fullpath) {
     CR_TRACE
     CR_ASSERT(fullpath);
     if (!cr_exists(fullpath)) {
@@ -1923,6 +1930,11 @@ extern "C" bool cr_plugin_load(cr_plugin &ctx, const char *fullpath) {
     return true;
 }
 
+// 20200109 [DEPRECATED] Use `cr_plugin_open` instead.
+extern "C" bool cr_plugin_load(cr_plugin &ctx, const char *fullpath) {
+    return cr_plugin_open(ctx, fullpath);
+}
+
 // Call to cleanup internal state once the plugin is not required anymore.
 extern "C" void cr_plugin_close(cr_plugin &ctx) {
     CR_TRACE

samples/basic_host.cpp

@@ -11,7 +11,7 @@ int main(int argc, char *argv[]) {
     cr_plugin ctx;
     // the host application should initalize a plugin with a context, a plugin
     // filename without extension and the full path to the plugin
-    cr_plugin_load(ctx, plugin);
+    cr_plugin_open(ctx, plugin);
 
     // call the plugin update function with the plugin context to execute it
     // at any frequency matters to you

samples/basic_host_b.cpp

@@ -14,8 +14,8 @@ int main(int argc, char *argv[]) {
     cr_plugin ctx, ctx2;
     // the host application should initalize a plugin with a context, a plugin
     // filename without extension and the full path to the plugin
-    cr_plugin_load(ctx, plugin);
-    cr_plugin_load(ctx2, plugin2);
+    cr_plugin_open(ctx, plugin);
+    cr_plugin_open(ctx2, plugin2);
 
     // call the plugin update function with the plugin context to execute it
     // at any frequency matters to you

samples/imgui_host.cpp

@@ -130,7 +130,7 @@ int main(int argc, char **argv) {
 
     cr_plugin ctx;
     ctx.userdata = &data;
-    cr_plugin_load(ctx, plugin);
+    cr_plugin_open(ctx, plugin);
 
     while (!glfwWindowShouldClose(window)) {
         glfwPollEvents();

tests/test.cpp

@@ -41,7 +41,7 @@ TEST(crTest, basic_flow) {
     test_data data;
     ctx.userdata = &data;
     // version 1
-    EXPECT_EQ(true, cr_plugin_load(ctx, bin));
+    EXPECT_EQ(true, cr_plugin_open(ctx, bin));
 
     data.test = test_id::return_version;
     EXPECT_EQ(1, cr_plugin_update(ctx));