How to get help when something does not work as expected
If you are looking for help on how to install MeteoIO or encounter problems when installing it, please have a look at the Getting-started tutorial (before reporting any potential issue).
From now on, we consider that you successfully installed MeteoIO and your model. You're now ready to run your simulations, but the simulation crashes. What should you do?
trying to solve the problem by yourself
Before reporting the problem, please check if there is something that you can do about it. Most of the problems reported turn out to be because of a trivial error in the user own files.
Output error message
First, please read the FULL error message(s) that appears on screen. Sometimes, you might have multiple error messages one after another one. Since the software might try to recover from a previous error and fail later on, please read them all in order to understand what happened.
The following example shows 3 error messages. A file is not found (as seen in message 2), but this triggers two extra errors. Therefore, the message that is the key to understanding what happened is the second one:
./meteoio/IOHandler.cc:178: [E] failed while loading plugin with error: ./meteoio/libsmet.cc:653: Could not open file './/WAN2.smet' for reading. Please check file existence and permissions! terminate called after throwing an instance of 'mio::IOException' what(): ./meteoio/IOHandler.cc:196: Requesting to read/write data with plugin 'SMET', but plugin is not loaded
Error messages are followed (on Linux) by a dump of the call stack, similar to this:
**** backtrace **** at ../../lib/libmeteoio.so.2(_ZN3mio9IOHandler9getPluginERKSsS2_+0x4d0) [0xefd060] at ../../lib/libmeteoio.so.2(_ZN3mio9IOHandler13readMeteoDataERKNS_4DateES3_RSt6vectorIS4_INS_9MeteoDataESaIS5_EESaIS7_EERKj+0x7c) [0xefd82a]
This is not relevant for an end user but could help the developers tremendously. Please don't be confused by these weird looking lines (that usually show up in a different color) but simply ignore them when looking for an error message and copy them to the developers when reporting an issue.
Looking into the documentation
MeteoIO comes with an extensive online documentation (models like Snowpack too).
If you are using a package, you can find such documentation on your system (all the paths given below assume a default install location. On some platforms, a release number is appended to "meteoio" in paths):
- online, for the latest stable release
- on Linux, under /usr/share/doc/meteoio
- on osX, under /Applications/MeteoIO
- on MS Windows under C:\Program Files\Meteoio\doc
If you are using a binary package, then you can also download a documentation only package on the download page.
If you are using a source distribution, the documentation must be built (with doxygen) by typing "make doc" at the root of the software source. When it has been built, it is available under the doc subdirectory (with an HTML file redirecting to the proper index.html file in the html documentation).
The welcome page of the documentation contains end user documentation and links to the relevant pages, sorted by categories. For example, when using a specific input plugin, if the error has to do with an invalid/missing key whose name can be traced back to the said plugin, it is a good idea to read the documentation page of the plugin...
Looking into known issues
After examining the error messages and checking into the documentation, it might be that you found a true issue/bug. In this case, please first check if this issue has already been reported or even fixed in a later version:
- go to https://models.slf.ch
- select the relevant project(s)
- click on the "issues" tab
- search by keywords in the search box
- browse open as well as closed issues
- by clicking on an issue, you will see the full description as well as any potential discussion thread associated with it.
Reporting an issue
First, it is important to properly qualify the problem. This means gathering all relevant information about it:
- which version are you running?
- for a compilation problem:
- on which operating system?
- on which architecture?
- with which compiler?
- which model are you running?
- which plugin were you using (if the problem is related to a plugin)
- if not obvious: what were you trying to do, what were you expecting?
- what happened? Can you reproduce the bug?
- please keep the files and applications available for further debugging (it is much faster to login to your computer and figure out what goes wrong than having to setup a whole configuration similar to yours to try to reproduce the bug)
Then, on the issues page of the relevant software1, create a new issue. This will be visible to all, including other users and developers. You will receive an email whenever a new comment is added to this issue. Therefore, multiple users and developers might interact on this issue, but you will remain informed of what happens. And other users experiencing the same issue will see that this has already been reported.
which might not always be easy to figure out. If in doubt between an application and a library, please fill it on the application page. If necessary, a new issue linking to it from another software package would be created. ↩