Flexync Files

 Flexync SDK - Readme File
===========================

Contents:

1.  What is the Flexync SDK?
2.  THIS IS JUST A PREVIEW RELEASE !!!
3.  What is Flexync?
4.  Contents of this SDK
5.  What will you need to use this SDK (prerequisites)
6.  Quick start on how to use this SDK (create your Flexync plugin)
7.  License
8.  Author
9.  Flexync source code
10. Website and more information

===========================



1. What is the Flexync SDK?
------------------------------------------

The Flexync SDK allows easy C++ development of plugins for Flexync.

But what is Flexync? Please see chapter 3. below for an answer.

WARNING: THIS SDK PACKAGE IS INTENDED FOR WINDOWS DEVELOPMENT (WITH QT 4.7.0 MINGW)!

If you need to develop a plugin on some other platform please look for an SDK package for this platform
(June 2010: currently none available!) or just download Flexync sources (see chapter 8.)
and compile QOMA and FlexyncApi libraries on your platform, which then you can use like this SDK.

NOTE: Flexync is a project based on the Qt framework (http://qt.nokia.com).
Thus this SDK is also based on Qt and any Flexync plugin which you would like to develop
will also have to be using Qt. Have no fear however, as Qt is a brilliant
and easy to use framework, which allows comfortable C++ development of
nice cross-platform applications. So Qt is what Flexync needs :)

So what will you need then to develop your own plugin? Please see chapter 5. below.

Anyway read through this file for more answers to your questions (like license,
website, author information etc. etc.).



2. THIS IS JUST A PREVIEW RELEASE !!!
------------------------------------------

WARNING: This is a code preview (=not fully working!) of
how (more or less!) will the Flexync SDK look like.

THIS MEANS THAT YOU CANNOT ACTUALLY DEVELOP ANY FLEXYNC PLUGIN YET!

So you should treat this SDK as a demonstration of an interesting concept
that probably will be available in the future.

I hope you are not disappointed. I hope you didn't expect to be actually
a true SDK as the name of this package implies that it's a preview.
In fact you should feel the opposite than disappointment.
I have made some effort to provide you with this demonstrational package
so that you can have something interesting to look at :)
So now instead of disappointed I hope you feel happy about it :D

NOTE: There ARE libraries in this package, which you can link
into your plugin. However these are not fully implemented yet,
that's why you cannot actually develop Flexync plugins with this SDK yet!



3. What is Flexync?
------------------------------------------

Actually at the moment (June 2010) the question is "What will Flexync be?"

Flexync (Flexible synchronization) adjusts flexibly to your synchronization needs:
it is always simple in use and lightweight, runs on many platforms,
on single PC or in a network of stationary/mobile agents, and allows you to use advanced options!

Please note: The description above tells us about the future.
Currently The Flexync Project is under development. Let us hope that it will accomplish its goals.



4. Contents of this SDK
------------------------------------------

This SDK contains include headers and static library files for Flexync plugin development.
(Please not that - as explained in chapter 2. above - this is only a demonstrational
package and does not actually allow to develop plugins yet!)


The SDK contains two libraries:

a) Flexync API (FlexyncApi) library:
 - This library provides C++ classes for:
    * Creating your own plugin classes (not implemented yet!)
    * Manipulating Flexync data (partially implemented)

b) QOMA (Qt-based Object Model API) library:
 - A seperate library developed by author of Flexync
 - Flexync (so FlexyncApi library too) uses QOMA library as a data model implementation
 - QOMA library provides:
   * a simple model for hierarchical representation of data as objects and attributes
   * storage of data model in different ways (currently supported two: XML, QSettings module in Qt)
   * the model can be compared to LDAP data model or very simplified DOM data model
   * the data is organized as a hierarchy of objects, and each object can have attribute
   * the data in attributes can have many different formats - thanks to the QVariant class in Qt


The files in this SDK are organized in the following way:

a) Include header files for QOMA and FlexyncApi libraries
 - Please include both include/qoma and include/FlexyncApi in your compiler's include path!

b) Static library files containing QOMA and FlexyncApi libraries
 - WARNING!!! Please keep in mind that:
   * These libraries are for Windows plugin development!
   * These libraries have been compiled with Qt 4.7.0 (beta) MinGW,
     so you also have to compile your plugin this way.
   * If you would like to develop plugin on some other platform please look at chapter 1. for info.
 - Please use compiler's library path with the following directories:
   * lib/debug     - contains libraries with debugging symbols
   * lib/release   - contains libraries for release versions
 - WARNING!!! These libraries are not fully implemented yet!
   * So you cannot develop Flexync plugins with this SDK yet!
   * You will have to wait for the working release of this SDK
   * For more information about this, please read chapter 2.



5. What will you need to use this SDK (prerequisites)
------------------------------------------

To develop plugins with this SDK you will need:

a) C++ programming skills

b) At least some basic knowledge in programming with Qt framework
 - Qt is not so hard to learn, especially if you are experienced in C++
 - For a quick start with Qt visit this page: http://doc.trolltech.com/4.7-snapshot/
   * You will find there many tutorials and examples
   * Apart from that The Internet is full of easy materials about getting started with Qt

c) Qt 4.7.0 SDK (download from http://qt.nokia.com)
 - You have to create a Qt project which is a "Qt4 plugin" library.
 - I recommend using the QtCreator IDE (also download from http://qt.nokia.com)
 - NOTE: Qt SDK and QtCreator _may_ require from you additional things:
   * Please check exactly at Qt's website, e.g. at http://qt.nokia.com/downloads
   * There is also a detailed webpage, which I find a bit complicated however:
     http://doc.trolltech.com/4.7-snapshot/installation.html
	 Please do not worry too much if you find it confusing, just go to the
	 Qt download page (http://qt.nokia.com/downloads) and try to follow
	 some simpler instructions there.

d) C++ compiler
 - Information on compilers supported by Qt can be found at:
   * http://doc.qt.nokia.com/4.7-snapshot/compiler-notes.html
 - For development on the Windows platform:
   * a ready-to-work compiler is provided  QtCreator IDE package and/or with Qt SDK
   * Qt should also support some modern versions of Microsoft Visual C++ compiler
   * These are only my hints. If you are interested, please verify this information
     by visiting http://qt.nokia.com and looking around on The Internet.

e) Finally you will have to learn about the Flexync API and how to use it
   (in the future there should be some tutorial)
 
f) Unfortunately you also will need to wait some time, because currently (June 2010)
   this SDK is a demonstrational package and DOES NOT allow you to develop plugins yet!
   For more info about this please read chapter 2. above.

Hey, for a central place to get all the information you need about Qt
(including how to start and what to download with all links), please visit:
http://qt.nokia.com/developer

Also the Qt FAQ is very useful if you have any doubts or if you run into any problem:
http://developer.qt.nokia.com/faq



6. Quick start on how to use this SDK (create your Flexync plugin)
------------------------------------------

WARNING: These instructions would allow you to create a Flexync plugin
if this was implemented in the SDK. Currently this is a demonstration SDK
package and you cannot actually create your plugin yet.
(For more information about this read chapter 2. above).
So the instructions below are only a demonstration of how creating 
your plugin will look like, once it is implemented in the SDK!

OK, YOU HAVE BEEN WARNED.


Follow these steps:

a) Create your Qt plugin project

You can do it by manually creating a .pro file (if you are an advanced Qt developer),
or you use QtCreator, which is convenient (even for advanced Qt developers).

We will show you how to create a Qt plugin project using QtCreator

 - Start QtCreator
 - From menu select "File" -> "New File or Project..."
 - A window appears to choose project type
 - In "Other Project" choose "C++ Library" and click OK
 - Enter basic project information
   * Type: must be "Qt 4 plugin" !!!
   * Name: for example "MyFxPlugin"
   * Create in: choose where your project will be created
   * When done, click Next
 - Choose compilation targets
   * These are only stored your QtCreator session (in the .pro.user file)
   * Remember that you can always add them later, so you don't have to select all
   * When done, click Next
 - Enter main C++ class information
   * Class name: e.g. "MyFxPluginCire"
   * Base class: FxPlugin::PluginCore (not available yet! so now skip it)
   * [TODO: this information is incorrect]

b) Add library and include paths to your project (.pro) file

 - For example using the following lines:

	CONFIG(debug, debug|release) {
		LIBS += -Lpath-to-flexyncsdk/lib/debug -lqomad -lFlexyncApid
	} else {
		LIBS += -Lpath-to-flexyncsdk/lib/release -lqoma -lFlexyncApi
	}

	INCLUDEPATH += path-to-flexyncsdk/include/qoma-include path-to-flexyncsdk/include/FlexyncApi-include

c) include <FxPlugin/FxPlugin.h> (not implemented yet!) and use Flexync API accordingly (tutorials in the future)



7. License
------------------------------------------

The Flexync Project (so also this SDK) is released under LGPL license.

This allows you to develop your plugins as proprietary closed source projects/products
if you want to! :)

WARNING:
I stil have NOT decided if I want to use LGPLv2.1 or LGPLv3.
I will decide by the time there is a working release of Flexync and/or Flexync SDK :)

Here are links to the licences - for both LGPLv2.1 and LGPLv3:
LGPLv2.1  http://www.gnu.org/licenses/lgpl-2.1.html
LGPLv3    http://www.gnu.org/licenses/lgpl-3.0.html

QT WARNING:
Please note that the Qt Framework (which is used by The Flexync Project) provides
different licensing models, but fortunately it includes LGPL, namely LGPL 2.1.
For more information about this please visit http://qt.nokia.com/products/licensing

Please pay attention to "Nokia Qt LGPL Exception", which is rather useful.
You can find it for example at the end of this LGPL page:
http://doc.trolltech.com/4.7-snapshot/lgpl.html



8. Author
------------------------------------------

The author of The Flexync Project (and the QOMA library used by Flexync) is:

Tomasz Lasko (£aœko in Polish) (tomeg [@] users [.] sourceforge [.] net)

and he holds all copyrights for the mentioned projects.

Copyright (C) 2010 by Tomasz Lasko



9. Flexync source code
------------------------------------------

The Flexync Project's sourcecode is stored in a Mercurial repository.

Also the sources of this SDK (which actually means the sources o
QOMA and FlexyncApi libraries) are also stored in this Flexync repository.

To gain read-only access to this repository, please use your Mercurial client
with the following repository address:

http://flexync.hg.sourceforge.net:8000/hgroot/flexync/flexync


COMPILING THE SOURCES:

As mentioned many times in this readme document, The Flexync Project is based
on the Qt framework, version 4.7.0 (beta).

Thus to compile the sources you will need the Qt 4.7.0. SDK
with a compatible C++ compiler (for more info see chapter 5.).

When you have it, then for each Flexync subproject (with a .pro file)
you will have to run qmake and then make.

For more information on how to compile a Qt project with qmake
look around on The Internet or in Qt tutorials
(which are linked in chapter 5. above).



10. Website and more information
------------------------------------------

For more info please visit:

http://flexync.sourceforge.net/

http://sourceforge.net/projects/flexync/