Merge pull request #3427 from caitlinross/update-docs-readme

update docs/README.md for using conda env

docs/README.md

@@ -4,7 +4,7 @@
 
 This user guide is hosted in readthedocs: https://adios2.readthedocs.io/en/latest/
 
-To generate the User Guide under docs/user_guide/build/html format from the Sphinx source files:
+To generate the User Guide under docs/user_guide/build/html format from the Sphinx source files, using pip:
 
 ```bash
 $ cd ADIOS2/docs
@@ -14,3 +14,23 @@ docs$ pip3 install -r requirements.txt
 user_guide$ cd user_guide
 user_guide$ make html
 ```
+
+Or using conda:
+
+```bash
+$ cd ADIOS2/docs
+docs$ conda env create -f environment.yml
+docs$ conda activate adios2-python-docs
+user_guide$ cd user_guide
+user_guide$ make html
+```
+
+# Updating dependencies
+
+Read the Docs uses only the environment.yml file, so if you make changes to dependencies in requirements.txt, they will not take effect in RTD.
+The requirements.txt is provided only for building locally for those who don't have conda installed.
+If you make changes to the conda environment, you should update requirements.txt as well, either manually, or by running the following command (with the conda adios2-python-docs environment activated):
+
+```bash
+docs$ pip list --format=freeze > requirements.txt
+```

docs/requirements.txt

@@ -0,0 +1,44 @@
+alabaster==0.7.12
+Babel==2.11.0
+blockdiag==3.0.0
+breathe==4.33.0
+brotlipy==0.7.0
+certifi==2022.12.7
+cffi==1.15.1
+charset-normalizer==2.1.1
+colorama==0.4.6
+cryptography==38.0.2
+docutils==0.17
+funcparserlib==1.0.1
+idna==3.4
+imagesize==1.4.1
+importlib-metadata==4.11.4
+Jinja2==3.1.2
+MarkupSafe==2.1.1
+mpi4py==3.1.3
+numpy==1.21.6
+packaging==22.0
+Pillow==9.4.0
+pip==22.3.1
+pycparser==2.21
+Pygments==2.14.0
+pyOpenSSL==23.0.0
+PySocks==1.7.1
+pytz==2022.7
+requests==2.28.1
+setuptools==65.6.3
+snowballstemmer==2.2.0
+Sphinx==4.5.0
+sphinx-rtd-theme==1.0.0
+sphinxcontrib-applehelp==1.0.2
+sphinxcontrib-blockdiag==3.0.0
+sphinxcontrib-devhelp==1.0.2
+sphinxcontrib-htmlhelp==2.0.0
+sphinxcontrib-jsmath==1.0.1
+sphinxcontrib-qthelp==1.0.3
+sphinxcontrib-serializinghtml==1.1.5
+typing_extensions==4.4.0
+urllib3==1.26.13
+webcolors==1.12
+wheel==0.38.4
+zipp==3.11.0

docs/user_guide/source/advanced/plugins.rst

@@ -131,6 +131,35 @@ If ``ADIOS2_PLUGIN_PATH`` is not set, and a path is not specified when loading y
 .. note::
     The ``ADIOS2_PLUGIN_PATH`` environment variable can contain multiple paths, which must be separated with a ``:``.
 
+
+When building on Windows, you will likely need to explicitly export the Create and Destroy symbols for your plugin, as symbols are invisible by default on Windows.
+To do this in a portable way across platforms, you can add something similar to the following lines to your CMakeLists.txt:
+
+.. code-block:: cmake
+
+    include(GenerateExportHeader)
+    generate_export_header(PluginEngineWrite BASE_NAME plugin_engine_write)
+    target_include_directories(PluginEngineWrite PUBLIC
+        $<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}>
+        $<INSTALL_INTERFACE:include>)
+
+
+Then in your plugin header, you'll need to ``#include "plugin_engine_write_export.h"``. Then edit your function defintions as follows:
+
+.. code-block:: c++
+
+    extern "C" {
+
+    PLUGIN_ENGINE_WRITE_EXPORT adios2::plugin::ExampleWritePlugin *
+        EngineCreate(adios2::core::IO &io, const std::string &name,
+                 const adios2::Mode mode, adios2::helper::Comm comm);
+
+    PLUGIN_ENGINE_WRITE_EXPORT void
+        EngineDestroy(adios2::plugin::ExampleWritePlugin * obj);
+
+    }
+
+
 ***********************************
 Using Your Plugin in an Application
 ***********************************

examples/plugins/engine/CMakeLists.txt

@@ -3,15 +3,26 @@
 # accompanying file Copyright.txt for details.
 #------------------------------------------------------------------------------#
 
+include(GenerateExportHeader)
 add_library(PluginEngineWrite
   ExampleWritePlugin.cpp
 )
 target_link_libraries(PluginEngineWrite adios2::cxx11 adios2_core)
+generate_export_header(PluginEngineWrite BASE_NAME plugin_engine_write)
+target_include_directories(PluginEngineWrite PUBLIC
+  $<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}>
+  $<INSTALL_INTERFACE:include>
+)
 
 add_library(PluginEngineRead
   ExampleReadPlugin.cpp
 )
 target_link_libraries(PluginEngineRead adios2::cxx11 adios2_core)
+generate_export_header(PluginEngineRead BASE_NAME plugin_engine_read)
+target_include_directories(PluginEngineRead PUBLIC
+  $<BUILD_INTERFACE:${CMAKE_CURRENT_BINARY_DIR}>
+  $<INSTALL_INTERFACE:include>
+)
 
 add_executable(examplePluginEngine_write
   examplePluginEngine_write.cpp

examples/plugins/engine/ExampleReadPlugin.h

@@ -15,6 +15,8 @@
 #ifndef EXAMPLEREADPLUGIN_H_
 #define EXAMPLEREADPLUGIN_H_
 
+#include "plugin_engine_read_export.h"
+
 #include <fstream>
 #include <string>
 
@@ -80,11 +82,11 @@ class ExampleReadPlugin : public PluginEngineInterface
 
 extern "C" {
 
-adios2::plugin::ExampleReadPlugin *EngineCreate(adios2::core::IO &io,
-                                                const std::string &name,
-                                                const adios2::Mode mode,
-                                                adios2::helper::Comm comm);
-void EngineDestroy(adios2::plugin::ExampleReadPlugin *obj);
+PLUGIN_ENGINE_READ_EXPORT adios2::plugin::ExampleReadPlugin *
+EngineCreate(adios2::core::IO &io, const std::string &name,
+             const adios2::Mode mode, adios2::helper::Comm comm);
+PLUGIN_ENGINE_READ_EXPORT void
+EngineDestroy(adios2::plugin::ExampleReadPlugin *obj);
 }
 
 #endif /* EXAMPLEREADPLUGIN_H_ */

examples/plugins/engine/ExampleWritePlugin.h

@@ -14,6 +14,8 @@
 #ifndef EXAMPLEWRITEPLUGIN_H_
 #define EXAMPLEWRITEPLUGIN_H_
 
+#include "plugin_engine_write_export.h"
+
 #include <fstream>
 #include <memory>
 #include <string>
@@ -81,11 +83,11 @@ class ExampleWritePlugin : public PluginEngineInterface
 
 extern "C" {
 
-adios2::plugin::ExampleWritePlugin *EngineCreate(adios2::core::IO &io,
-                                                 const std::string &name,
-                                                 const adios2::Mode mode,
-                                                 adios2::helper::Comm comm);
-void EngineDestroy(adios2::plugin::ExampleWritePlugin *obj);
+PLUGIN_ENGINE_WRITE_EXPORT adios2::plugin::ExampleWritePlugin *
+EngineCreate(adios2::core::IO &io, const std::string &name,
+             const adios2::Mode mode, adios2::helper::Comm comm);
+PLUGIN_ENGINE_WRITE_EXPORT void
+EngineDestroy(adios2::plugin::ExampleWritePlugin *obj);
 }
 
 #endif /* EXAMPLEWRITEPLUGIN_H_ */

examples/plugins/engine/examplePluginEngine_read.cpp

@@ -61,6 +61,7 @@ int main(int argc, char *argv[])
 
     std::vector<float> myFloats = {0, 1, 2, 3, 4, 5, 6, 7, 8, 9};
 
+    bool success = false;
     try
     {
         /** ADIOS class factory of IO class objects */
@@ -76,6 +77,7 @@ int main(int argc, char *argv[])
             adios2::Params params;
             params["PluginName"] = "ReadPlugin";
             params["PluginLibrary"] = "PluginEngineRead";
+            params["verbose"] = "5";
             io.SetParameters(params);
         }
         adios2::Engine reader = io.Open("TestPlugin", adios2::Mode::Read);
@@ -108,6 +110,7 @@ int main(int argc, char *argv[])
 
         /** Engine becomes unreachable after this*/
         reader.Close();
+        success = true;
     }
     catch (std::invalid_argument &e)
     {
@@ -125,5 +128,5 @@ int main(int argc, char *argv[])
         std::cout << e.what() << "\n";
     }
 
-    return 0;
+    return success ? EXIT_SUCCESS : EXIT_FAILURE;
 }

examples/plugins/engine/examplePluginEngine_write.cpp

@@ -52,6 +52,7 @@ int main(int argc, char *argv[])
     std::vector<float> myFloats = {0, 1, 2, 3, 4, 5, 6, 7, 8, 9};
     const std::size_t Nx = myFloats.size();
 
+    bool success = false;
     try
     {
         /** ADIOS class factory of IO class objects */
@@ -72,6 +73,7 @@ int main(int argc, char *argv[])
             adios2::Params params;
             params["PluginName"] = "WritePlugin";
             params["PluginLibrary"] = "PluginEngineWrite";
+            params["verbose"] = "5";
             io.SetParameters(params);
         }
         adios2::Engine writer = io.Open("TestPlugin", adios2::Mode::Write);
@@ -83,10 +85,12 @@ int main(int argc, char *argv[])
         else
         {
             writer.Put<float>(var, myFloats.data());
+            writer.PerformPuts();
         }
 
         /** Engine becomes unreachable after this*/
         writer.Close();
+        success = true;
     }
     catch (std::invalid_argument &e)
     {
@@ -104,5 +108,5 @@ int main(int argc, char *argv[])
         std::cout << e.what() << "\n";
     }
 
-    return 0;
+    return success ? EXIT_SUCCESS : EXIT_FAILURE;
 }

examples/plugins/operator/examplePluginOperator_read.cpp

@@ -40,6 +40,7 @@ int main(int argc, char *argv[])
         0.0001,
     };
 
+    bool success = false;
     try
     {
         /** ADIOS class factory of IO class objects */
@@ -85,6 +86,7 @@ int main(int argc, char *argv[])
 
         /** Engine becomes unreachable after this*/
         reader.Close();
+        success = true;
     }
     catch (std::invalid_argument &e)
     {
@@ -102,5 +104,5 @@ int main(int argc, char *argv[])
         std::cout << e.what() << "\n";
     }
 
-    return 0;
+    return success ? EXIT_SUCCESS : EXIT_FAILURE;
 }

examples/plugins/operator/examplePluginOperator_write.cpp

@@ -41,6 +41,7 @@ int main(int argc, char *argv[])
     };
     const std::size_t Nx = myDoubles.size();
 
+    bool success = false;
     try
     {
         /** ADIOS class factory of IO class objects */
@@ -73,6 +74,7 @@ int main(int argc, char *argv[])
 
         /** Engine becomes unreachable after this*/
         writer.Close();
+        success = true;
     }
     catch (std::invalid_argument &e)
     {
@@ -90,5 +92,5 @@ int main(int argc, char *argv[])
         std::cout << e.what() << "\n";
     }
 
-    return 0;
+    return success ? EXIT_SUCCESS : EXIT_FAILURE;
 }

source/adios2/engine/plugin/PluginEngine.cpp

@@ -57,6 +57,7 @@ PluginEngine::PluginEngine(core::IO &io, const std::string &name,
     }
 
     auto &pluginManager = PluginManager::GetInstance();
+    pluginManager.SetParameters(m_IO.m_Parameters);
     pluginManager.LoadPlugin(pluginNameIt->second, pluginLibIt->second);
     m_Impl->m_HandleCreate =
         pluginManager.GetEngineCreateFun(pluginNameIt->second);

source/adios2/helper/adiosPluginManager.cpp

@@ -115,8 +115,15 @@ bool PluginManager::LoadPlugin(const std::string &pluginName,
     {
         return OpenPlugin(pluginName, pluginLibrary, "");
     }
-    auto pathsSplit =
-        adios2sys::SystemTools::SplitString(allPluginPaths, ':', false);
+
+#ifdef _WIN32
+    char platform_separator = ';';
+#else
+    char platform_separator = ':';
+#endif
+
+    auto pathsSplit = adios2sys::SystemTools::SplitString(
+        allPluginPaths, platform_separator, false);
 
     bool loaded = false;
     auto pathIt = pathsSplit.begin();
@@ -126,9 +133,13 @@ bool PluginManager::LoadPlugin(const std::string &pluginName,
         {
             loaded = OpenPlugin(pluginName, pluginLibrary, *pathIt);
         }
-        catch (...)
+        catch (std::exception &e)
         {
-            std::cout << "catch block\n";
+            // this is not necessarily an error, because you could have
+            // multiple paths in ADIOS2_PLUGIN_PATH variable
+            helper::Log("Plugins", "PluginManager", "LoadPlugin",
+                        std::string("OpenPlugin failed: ") + e.what(), 5,
+                        m_Impl->m_Verbosity, helper::LogMode::INFO);
             loaded = false;
         }
         ++pathIt;
@@ -224,6 +235,9 @@ bool PluginManager::OpenPlugin(const std::string &pluginName,
                     m_Impl->m_Verbosity, helper::LogMode::INFO);
         return true;
     }
+    helper::Throw<std::runtime_error>(
+        "Plugins", "PluginManager", "OpenPlugin",
+        "Unable to locate Create/Destroy symbols in library " + pluginLibrary);
     return false;
 }
 

source/adios2/operator/plugin/PluginOperator.cpp

@@ -72,6 +72,7 @@ void PluginOperator::PluginInit(const std::string &pluginName,
     }
 
     auto &pluginManager = PluginManager::GetInstance();
+    pluginManager.SetParameters(m_Parameters);
     pluginManager.LoadPlugin(pluginName, pluginLibrary);
 
     m_Impl->m_HandleCreate = pluginManager.GetOperatorCreateFun(pluginName);