*** Introduction ***
You can find here detailed instructions how to add a custom datasource to Kst 
(version 2.x), i.e. make it read a new file format.

Kst offers a plugin-based framework for datasources, allowing you to add support 
for your own datasource (or file format) fairly easily.
You basically need to implement 3 classes derived from classes provided by Kst. 
A good starting point is to copy the sampledatasource/ directory and start 
implementing the functions. It is advisable to have some 
understanding of C++, and to have a look at other implementations, particularly 
the initial svn commit for this file which shows more or less 
all the bits required to add complete support for a new file type, in that case 
Matlab's .mat using the matio/ library.

The use of the excellent QtCreator tool can make your life much easier, with 
code-completion, code navigation and integrated documentation.
If you have plans to develop for Kst, we recommend contacting us on the 
kst@kde.org mailing list to announce your plans and discuss technical
issues as well as to get some support.


*** Outline ***
The way Kst accesses data is completely decoupled from the internal plotting and 
computation logics. Basically, you *have to* implement the following methods for 
your new datasource:
- Test if a file is supported (may be as simple as checking the file extension, 
or some magic number in the header)
- Return the list of scalars, vectors, matrices and strings available. Don't 
worry if only some of the types are supported.
- For a given data item, return the number of samples available
- For a given data item, return a range of values (i.e. samples #100 to #199)
When this is done, just add the new datasource to the build (details below) and 
start debugging (unless you're a code guru and got it right directly)!

On top of that basic functionality, you *may* also add the following optional 
features:
- Support for file or data item metadata, e.g. scalars or strings adding some 
information to the data item like units or experiment conditions.  If you want 
to support metadata, you may want to look at the netCDF datasource which 
currently has a quite extensive support for metadata.  Metadata can be browsed 
via the View->Scalars/Vectors/Strings/Matrices menus.
- Support for real-time (streaming) data, i.e. files which are being written to 
and read/plotted from simultaneously. ASCII and dirfilesource implement such a 
feature (check the internalDataSourceUpdate() method)
- Support for time-based access (warning: this feature is not really used right 
now and probably still has some rough edges)


*** Step-by-step instructions (minimal datasource), based on the matlab example 
*** replace "matlab" with your file type ***
** Step 1: Create the source directory and do the initial configuration **
- Copy the sampledatasource directory (warning: don't copy the .svn 
subfolder!!!): "mkdir matlab; cp sampledatasource/* matlab/"
- Change the names of all files to something more relevant (sampledatasource -> 
matio)
- Edit the contents of the .desktop file, especially the X-KDE-Library entry
- Edit the .pro file (if you are using qmake, which is being deprecated) or the 
[root]/src/datasources/CMakeList.txt file to activate the build.
  If needed, look at other examples to see how to detect the presence of the 
required librqries to make it conditional (check [root]/cmake/modules)
- Once the output of cmake is as wished, the data source will be compiled: start 
filling out the contents of the actual code files

**** UPDATE 2019 ****
Some further pointers on the build system from someone who has actually done this since this howto was written (I wrote the Hdf module):

- The current build system uses cmake, so ignore the qmake options 
- If your datasource has no library dependancies, (unlikely) this will be an easy process, otherwise I really hope you know cmake
- You will need to update both the root CMakeLists.txt to include a find_package line for your package (this is easy, just look at the existing code)
- You will then need to write a FindLibname.txt file in [root]/cmake/modules
- You will also need to include that module in [root]/src/datasources/CMakeLists.txt
- As far as I know, what happens is the FindLibname module is called first, and then the CMakeLists in datasources is run to actually include and link the library, which means that it can fail if your FindLibname module doesn't work. Libraries at the bottom of the CMakeLists file use a conditional to avoid this problem and still build kst in the absence of the require plugin
- The FindLibname.txt module is the hardest part of this process. Look at the others for a model. This file locates the required headers as well as the required libraries to link against, so if either of those cannot be found your datasource will not work
- The header files (and libraries) are found with find_path (or find_library), which is a cmake command. You need to specify a guess (HINTS or PATHS) as to where it should look, so most of the examples use environment variables to specify the library install path
- if the libraries or header files are not found, they are set to LIBNAME-NOTFOUND. The build system will complain if it tries to compile any NOTFOUND libraries, so make sure you check for this if that could happen
- cmake uses a local variable cache that persists between runs (CMakeCache.txt in your build directory). This means that if you re-run the build a second time, most variables will already be defined (so for instance if(NOT VARNAME) will likely not be executed). This means that if a variable gets badly defined because you didn't get the cmake files exactly right, you probably want to remove the CMakeCache before re-running to get output that makes any sense

** Step 2: Implement the important classes **
To get your datasource to work, you have to:
  1a) Implement the MatlabSourcePlugin::provides() (trivial)
  1b) Implement MatlabSourcePlugin::understands() 
     For that second function, the easiest is to check only the file extension. 
All plugins are queried to select the most appropriate one.  The plugin which
returns the highest number is chosen.  By convention 100 means the plugin can
certainly understand it, and 0 means it certainly cannot.  80 is a reasonable
number if you are reasonably sure this plugin is correct.
  2) Decide which kind of primitives you want to support. Primitives are scalars 
(1 value), strings, vectors (an array of values) and matrices (2-dimensional 
arrays). 
     The most usual type to support is vector, you will probably want to start 
with that. The interface between Kst core and the datasource plugins uses 
templates. 
     See the definition of DataInterfaceMatlabVector for an example, and note 
that since it uses templates the declaration and implementation have to be in 
the .cpp file.
     The classes you implement (as a minimum MatlabSourcePlugin, MatlabSource 
and DataInterfaceMatlabVector) can be all together in the same file, or one per 
file.
  3) Implement the most important functions: 
      -MatlabSource::MatlabSource 
      -MatlabSource::~MatlabSource
      -MatlabSource::init() - most of the interesting data is usually gathered 
                              and cached into member variables here
      -MatlabSource::readField() - returns a range of values for a given vector, 

  and possibly some others in MatlabSource. 

  4) Implement the interface for each primitive, which is mostly only a thin 
layer above the data source class. Start with DataInterfaceMatlabVector and add 
other types progressively.

Hints: you can use qDebug() as a stream to produce debug output, and the 
Help->Debug Dialog also provides some interesting information, in particular 
plugin loading errors.

**** UPDATE 2019 ****
As far as I can tell, the Plugin class contains a bunch of list functions that you do not need to implement. IDK what they are there for but I left them blank and everything seems to work fine. No one was adequately able to tell me what they were for, so it seems like this whole process could be made clearer by getting rid of them (or at least documenting them properly)

Kst also cannot determine where on disk a piece of data came from once it has been loaded into memory. This means that if you want to be able to plot your data against INDEX in some way (ie. the array index of the original data), you need to provide this index, either by making sure it is always stored in your data format, or by generating it when KST tries to read from it. 

** Step 3: Polish **
This step is important, don't neglect it! It is important to check:
- That your code is well documented/commented and easy to understand
- That you don't have crashes or memleaks. Beware the conversions to double, 
this can be tricky and Kst always expects double values!
- If you can add some metadata support. Each primitive supports meta-strings and 
meta-scalars. See netCDF for details.
- Whether you can improve your data source by adding a configuration widget. 
Currently only ASCII provides one, so look there for inspiration (warning: ASCII 
is complex!)
- If performance can be improved (performance is very important to Kst!!!)
- If some sample files can be added to the sample_data/ subdir so that others 
can perform some tests if required

