Difference between revisions of "Developing"

From Gestinux Wiki
Jump to navigation Jump to search
 
(changed 1.4 to <version>)
 
(131 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 
= Developing Gestinux =
 
= Developing Gestinux =
  
 +
Gestinux is an open source software and anyone can help to its development.
  
−
You are welcome to help making Gestinux better.
+
Some guidelines for project maintenance follow, which can be discussed in the [http://forum.gestinux.net/viewforum.php?f=10 development forum].
  
−
Here are some rules to maintain the project. We can discuss about it in the [https://sourceforge.net/apps/phpbb/gestinux/viewforum.php?f=10 development forum].
+
== Tests ==
  
−
Gestinux is developed with '''Lazarus''' and '''FreePascal'''.
+
Gestinux must work in various combinations of environments, databases, and languages. It would be useful to have referent testers in each of these different possible combinations, particularly during release-candidates publishing.
  
−
== Get the sources ==
 
  
−
Sources are managed with subversion. You must use a SVN Client and connect to it as [https://sourceforge.net/scm/?type=svn&group_id=320994 explained by SourceForge].
+
To test safely, especially non stable versions, it is better to [[copyfortest|make a copy]] of a production database.
  
−
Version 0.5 with only a small accounting is now stable. Download it only to fix bugs.
+
== Translation ==
  
−
Version 1.0 is not finished and currently released as a beta version. The svn branch is "trunk".
+
You can easily [[Translating|translate]] gestinux into your mother language, and existing translations can definitely be improved.
  
−
== Packages used ==
+
== Documentation ==
  
−
Releases 0.5 and trunk should compile with the following packages.
+
The documentation, this Wiki, is made with MediaWiki and you can improve it. Read [[Help:Contents|this page]] for more information.
−
You can use more recent versions of the packages, but at your own risks !
 
  
−
*  Zeos DBO 6.6.6
+
For any question or remark, it is necessary to use only the [http://forum.gestinux.net/viewforum.php?f=10 forum] and not the wiki.
−
** [https://sourceforge.net/projects/zeoslib/files/Zeos%20Database%20Objects/zeosdbo-6.6.6-stable/ZEOSDBO-6.6.6-stable.zip/download Download] the package and unzip to any directory.
+
 
−
** [http://gestinux.svn.sourceforge.net/viewvc/gestinux/trunk/util/zeos/ZClasses.pas Download a patch for src/core/ZClasses.pas] and replace the file, to work with FPC >= 2.6 (See [http://zeos.firmos.at/viewtopic.php?t=3073 this discussion] - I hope Zeos team will make this patch available)
+
== Programmation ==
−
** [http://zeos.firmos.at/download.php?id=475&sid=fed7369335a69e6135e823dfeaec3700 Download a patch for src/plain/ZPlainMySql5.pas] and replace the file to make installation easier with MySql 5.1 on Linux Ubuntu >= 09.10 (See [http://zeos.firmos.at/viewtopic.php?p=12439 this discussion])
+
 
−
** For 64 bits compilers : another patch or ZEOS 7 is requested.
+
=== Lazarus versions and sources ===
−
** Then, open packages/lazarus/zcomponent.lpk and click Install
+
 
−
* Power PDF 0.9.7.1
+
The last stable version of Gestinux 1.5 (stable-3) is built using Lazarus 2.0.12 and FreePascal 3.2.0
−
** [https://sourceforge.net/projects/lazarus-ccr/files/PowerPDF/PowerPDF%20v0.9.7/powerpdf_0.9.7.1_20111207.tar.gz/download Download] the package and unzip to any directory.
+
 
 +
To develop the trunk version (Gestinux 1.6) we should use Lazarus 2.0.12 and FPC '''3.2.2''' (required to support Zeos 7.2.14, see below)
 +
 
 +
=== Obtaining Gestinux sources ===
 +
 
 +
Gestinux source code is managed using SVN.
 +
 
 +
It is easier if you install some GUI SVN Client program : [http://rapidsvn.tigris.org/ RapidSvn] for Linux and [http://tortoisesvn.net/ TortoiseSVN] for Windows are working fine.
 +
 
 +
You must also have a SourceForge account and will need to enter your SourceForge password, or set up a SSL secured connection to SourceForge.
 +
 
 +
The svn command line is :
 +
 
 +
  svn checkout --username=your_sourceforge_account svn+ssh://your_sourceforge_account@svn.code.sf.net/p/gestinux/code <your_local_source_directory>
 +
 
 +
Read [https://sourceforge.net/p/forge/documentation/SSH%20Keys/ this documentation] to avoid entering your password every time.
 +
 
 +
* You should improve or create new sources and/or new functionalities in the '''trunk''' branch only, after having obtained a developer profile in the sourceforge project (ask in the development forum).
 +
 
 +
* In the last stable branch, only fix important and well identified bugs.
 +
 
 +
* Do not change anything in older branches which are available for history only.
 +
 
 +
 
 +
You should lock the files before changing anything. For this and to commit, ask in the [http://forum.gestinux.net/viewforum.php?f=7 forum] to be granted a "developer" privilege for Gestinux SourceForge project.
 +
 
 +
=== Packages which are required ===
 +
 
 +
Releases 1.x or trunk should compile with the following packages.
 +
 
 +
You can use more recent versions of the packages, but at your own risk ! Let us know if using a newer version of any of these packages works sucessfully.
 +
 
 +
*  Zeos DBO 7.2.14 for trunk and 7.2.6 for 1.5-stable
 +
** [https://sourceforge.net/projects/zeoslib/files/Zeos%20Database%20Objects/zeosdbo-7.2.6-stable/zeosdbo-7.2.6-stable.zip/download Download sources] and unzip in any folder [7.2.14 requires FPC 3.2.2, see [http://forum.gestinux.net/viewtopic.php?f=4&t=153 this post in french]
 +
** Open packages/lazarus/zcomponent.lpk
 +
** Install  (click Use, Install)
 +
** It is not required to rebuild the EDI before all packages are installed
 +
* Power PDF 0.9.15
 +
** [http://sourceforge.net/projects/lazarus-ccr/files/PowerPDF/powerpdf_0.9.15_20170215.tar.gz/download Download] the package and unzip to any directory.
 
** Open pack_powerpdf.lpk
 
** Open pack_powerpdf.lpk
 
** Install.
 
** Install.
−
* LazReport 0.9.8
+
* LazReport 0.9.9 and LazReportPDFExport 0.9
−
** Open components/lazreport/source/lazreport.lpk
+
** Click Menu ''Packages'' > ''Install/Uninstall packages''
−
** In Options, IDE integration, select "automatically rebuild as needed"
+
** Select these packages (lazreport and lazreportpdfexport) in the right pane, and move them to the left one.
−
** Install.
+
* [[Gestinux_util|Gestinux_util 1.5 or 1.6]] : package containing the components Gestinux uses, located in the util subdirectory of 1.5 or trunk branch.
−
* LazReportPDFExport 0.7
+
** Open gestinux_util.lpk  
−
** Open components/lazreport/source/addons/pdfexport/lazreportpdfexport.lpk in Lazarus installed files.
 
−
** In Options, IDE integration, select "automatically rebuild as needed"
 
 
** Install
 
** Install
−
* [[Gestinux_util]] : package containing components used by gestinux
+
** Click the button ''Save and rebuild EDI''
−
** Open util/gestinux_util.dpk in the gestinux sources
+
 
−
** Install.
+
=== Gestinux development Rules ===
−
** This will create a Tab named Gestinux in the objects palette.
+
 
 +
* Use the right Lazarus version (see above)
 +
* Only use English for identifiers and comments.
 +
* Use the Code Formatter (CTRL+D) to indent modified sources, with default options.
 +
* Read the [[gestinux_util]] documentation, and do not use a Txxxx component when there is a TGxxxx component in this package
 +
 
 +
=== What to do ===
 +
 
 +
Everyone can help !
 +
If you are a beginner, there are some simple things you can do, and this would save time.
 +
From gurus, we do need better components.
 +
 
 +
Before starting anything, you are advised to discuss your proposal a bit in the [http://forum.gestinux.net/viewforum.php?f=10 development  forum].
 +
 
 +
== Packaging and OS specific informations ==
  
−
== Rules for development ==
+
=== Linux ===
  
−
* Source must be compilable with : Lazarus 0.9.30.4, FPC 2.4.6
+
You can build a Debian package using scripts located in trunk/install/debian
−
* Do not use features available only in Lazarus or other SVN.
 
−
* Use only English for variable names, comments and of course outputs.
 
−
* Use Jedi Code formater to indent your sources, with default options.
 
−
* Read [[gestinux_util]] documentation, and do not use component Txxxx when there is a TGxxxx in this package
 
  
−
Ask to be granted a developer profile in SourceForge.
+
Source are exported from the repository and recompiled before building the package, to ensure everything is in the repository. The SVN revision will be included automatically in the binary to be visible in the "About" form.
−
Don't forget to lock the files before any change.
 
  
−
== What to do ==
+
If you want to build and install a package run (e.g with trunk and Lazarus 64 bits). Replace ''<svn local repository>'' and ''<your sourceforge account>'' by your specific values.
  
−
Everyone can help !
+
  <svn local repository>/gestinux/<version>/install/debian/build_pkg.sh SYSTEM="Debian" TARGET="x86_64" SVNUSER="<your sourceforge user>" BRANCH="trunk"
−
If you are a beginner, there are some simple things to do, and this would save time.
 
−
For gurus, we do need better components.
 
  
−
You can [https://sourceforge.net/tracker/?limit=25&group_id=320994&atid=1349209&status=1submit=Filter look at Tracker] to see what is the most useful to do. But some coordination with the [https://sourceforge.net/sendmessage.php?touser=2907309 project manager] is better before you start anything !
+
This should build a lintian valid Debian package, reading some translations for man and desktop in available translation files.
  
−
= Translation system =
+
You are welcome if you can make the same for other Linux distributions !
  
−
Refer to the [[translation documentation page]] to learn how you can use it and make translations,
+
=== Windows ===
  
−
= Database =
+
You can build an installer for Windows 32 bits with InnoSetup 5 and the command file trunk/install/windows/build_i386_win32.bat.  Windows PowerShell is used to extract and include the SVN revision in the binary.
  
−
== Supported DBMS ==
+
It can be installed and works on Windows 64 bits. It is also possible to use build_x86_win64.bat, with Lazarus 64 bits, to make a 64 bits installer. Since this is not very useful and not used currently, check if the script is up to date against the 32 bits one.
  
−
MySql 5 and PostgreSQL are supported.
+
We include MySql 5.0 client drivers, installed only on the target system if no more recent MySql driver is present .  
−
My Sql because it is common and administration is simpler.
 
−
PostgreSql because it is a true free software.
 
−
In the future, we may try other DBMS, but it requires a larger team to go forward.
 
  
−
In the main sources, avoid SQL statements specific to MySQL or Postgres.
+
=== Mac OS/X ===
−
When there is no alternative, compatibility procedures should be made. They are all centralized in one unit (unitdatamodule.pas for now).
 
  
−
== Table and fields definitions and properties ==
+
Currently gestinux.app can be built for Intel 32 bits with the script trunk/install/osx/build_osx_i386_32.sh.The SVN revision must be included manually. There is a gestinux.pmdoc to make manually a gestinux.pkg which can be installed and works on 32 or 64 bits Macs.
  
−
In [[Gestinux_util]] there is a [[TGTable]] component used to store metadata of tables used in Gestinux. With this component, there is no need to store table definitions elsewhere, and no sql script is required to initialize or upgrade the database.  
+
Since I have only an old Macintosh with OS/X 10.6, I can't use up-to-date tools to build installers and add certificates.
  
−
The database and tables are created by the main executable, as specified in unitdatamodule.pas
+
You are welcome if you can help in this area.
−
properties of TGTable and TFields objects.
 
  
−
Index and constraints are stored in the "properties" property of TGTable, with special processing depending on the DBMS.
+
== Database ==
  
−
== To create a new table ==
+
=== Supported DBMS ===
  
−
This is for a new functionnality in the application, and only in trunk version.
+
MySql 5.7, MariaDb 10.3, and PostgreSQL 9 are supported.
  
−
* Create the table and all it's index and constraints with MySql Query Browser or any other MySql client (not PostgreSQL).
+
* MySql because administration is quite simple.
−
**The following types can be used only. If other types are necessary, some development must be made in datamodule.
+
* PostgreSql because it is completely free software.
−
*** Integer Autoinc
+
* MariaDb for both reasons. It is the recommended DBMS to use.
−
*** Integer, smallint
 
−
*** Varchar
 
−
*** Timestamp
 
−
*** Date, Datetime
 
−
*** Blob
 
−
**Always start with an '''Id''' field, Autoinc and Primary key
 
−
**Always end with an '''UpdateDate''' field, ''TimeStamp default current_timestamp on update current_timestamp''
 
−
* Create a TGTable object in Datamodule, with connexion set to open the previous database.
 
−
** Create a new computed field AutoInc, correct it's Name (bug), set it Required and set the field to fkData.
 
−
** Add '''all''' other fields.
 
−
** Write the index and constraint instructions in the property ''Properties'' of the TGTable.
 
−
** In DataModule1.DbAfterConnect event, add to TGTable.Check.
 
−
* Test it and check the structure and data created in the query browser !
 
  
−
== To add a new field or index or constraint ==
+
In the future, we may try other DBMS, but that would require a bigger development team.
  
−
To add a new data field to an existing table :
+
In the main sources, avoid SQL statements specific to some DBMS.
−
* Create the new field using any MySql client, with the required and default properties as expected.
+
When there is no alternative, compatibility procedures should be made. They are all centralized in one unit (util/gconnection.pas).
−
* Add the field in the TGTable object
 
−
* If needed add a line in the property Table.Properties to define index and/or constraint.
 
−
* After that, on a new database, the missing field will be added by TGTable.Check. Test it with old databases, and check in MySql.
 
  
−
== Other changes ==
+
=== Table and fields definitions and properties ===
  
−
Some changes of datatype, required and default properties are possible, if really necessary. They must be compatible with older release.
+
In [[Gestinux_util]] there is a [[TGTable]] component used to store all the metadata of tables used in Gestinux. With this component, there is no need to store table definitions elsewhere, and no SQL script is required to initialize or upgrade the database.  
  
−
No field or index deletion is possible.
+
The database and table structures are created by the main executable, as specified in unitdatamodule.pas, in [[TGTable]] properties. See the component [[TGTable]] for more details.

Latest revision as of 21:24, 9 August 2022

 Français

Developing Gestinux

Gestinux is an open source software and anyone can help to its development.

Some guidelines for project maintenance follow, which can be discussed in the development forum.

Tests

Gestinux must work in various combinations of environments, databases, and languages. It would be useful to have referent testers in each of these different possible combinations, particularly during release-candidates publishing.


To test safely, especially non stable versions, it is better to make a copy of a production database.

Translation

You can easily translate gestinux into your mother language, and existing translations can definitely be improved.

Documentation

The documentation, this Wiki, is made with MediaWiki and you can improve it. Read this page for more information.

For any question or remark, it is necessary to use only the forum and not the wiki.

Programmation

Lazarus versions and sources

The last stable version of Gestinux 1.5 (stable-3) is built using Lazarus 2.0.12 and FreePascal 3.2.0

To develop the trunk version (Gestinux 1.6) we should use Lazarus 2.0.12 and FPC 3.2.2 (required to support Zeos 7.2.14, see below)

Obtaining Gestinux sources

Gestinux source code is managed using SVN.

It is easier if you install some GUI SVN Client program : RapidSvn for Linux and TortoiseSVN for Windows are working fine.

You must also have a SourceForge account and will need to enter your SourceForge password, or set up a SSL secured connection to SourceForge.

The svn command line is : 

 svn checkout --username=your_sourceforge_account svn+ssh://your_sourceforge_account@svn.code.sf.net/p/gestinux/code <your_local_source_directory>

Read this documentation to avoid entering your password every time.

  • You should improve or create new sources and/or new functionalities in the trunk branch only, after having obtained a developer profile in the sourceforge project (ask in the development forum).
  • In the last stable branch, only fix important and well identified bugs.
  • Do not change anything in older branches which are available for history only.


You should lock the files before changing anything. For this and to commit, ask in the forum to be granted a "developer" privilege for Gestinux SourceForge project.

Packages which are required

Releases 1.x or trunk should compile with the following packages.

You can use more recent versions of the packages, but at your own risk ! Let us know if using a newer version of any of these packages works sucessfully.

  • Zeos DBO 7.2.14 for trunk and 7.2.6 for 1.5-stable
    • Download sources and unzip in any folder [7.2.14 requires FPC 3.2.2, see this post in french
    • Open packages/lazarus/zcomponent.lpk
    • Install (click Use, Install)
    • It is not required to rebuild the EDI before all packages are installed
  • Power PDF 0.9.15
    • Download the package and unzip to any directory.
    • Open pack_powerpdf.lpk
    • Install.
  • LazReport 0.9.9 and LazReportPDFExport 0.9
    • Click Menu Packages > Install/Uninstall packages
    • Select these packages (lazreport and lazreportpdfexport) in the right pane, and move them to the left one.
  • Gestinux_util 1.5 or 1.6 : package containing the components Gestinux uses, located in the util subdirectory of 1.5 or trunk branch.
    • Open gestinux_util.lpk
    • Install
    • Click the button Save and rebuild EDI

Gestinux development Rules

  • Use the right Lazarus version (see above)
  • Only use English for identifiers and comments.
  • Use the Code Formatter (CTRL+D) to indent modified sources, with default options.
  • Read the gestinux_util documentation, and do not use a Txxxx component when there is a TGxxxx component in this package

What to do

Everyone can help ! If you are a beginner, there are some simple things you can do, and this would save time. From gurus, we do need better components.

Before starting anything, you are advised to discuss your proposal a bit in the development forum.

Packaging and OS specific informations

Linux

You can build a Debian package using scripts located in trunk/install/debian

Source are exported from the repository and recompiled before building the package, to ensure everything is in the repository. The SVN revision will be included automatically in the binary to be visible in the "About" form.

If you want to build and install a package run (e.g with trunk and Lazarus 64 bits). Replace <svn local repository> and <your sourceforge account> by your specific values. 

 <svn local repository>/gestinux/<version>/install/debian/build_pkg.sh SYSTEM="Debian" TARGET="x86_64" SVNUSER="<your sourceforge user>" BRANCH="trunk"

This should build a lintian valid Debian package, reading some translations for man and desktop in available translation files.

You are welcome if you can make the same for other Linux distributions !

Windows

You can build an installer for Windows 32 bits with InnoSetup 5 and the command file trunk/install/windows/build_i386_win32.bat. Windows PowerShell is used to extract and include the SVN revision in the binary.

It can be installed and works on Windows 64 bits. It is also possible to use build_x86_win64.bat, with Lazarus 64 bits, to make a 64 bits installer. Since this is not very useful and not used currently, check if the script is up to date against the 32 bits one.

We include MySql 5.0 client drivers, installed only on the target system if no more recent MySql driver is present .

Mac OS/X

Currently gestinux.app can be built for Intel 32 bits with the script trunk/install/osx/build_osx_i386_32.sh.The SVN revision must be included manually. There is a gestinux.pmdoc to make manually a gestinux.pkg which can be installed and works on 32 or 64 bits Macs.

Since I have only an old Macintosh with OS/X 10.6, I can't use up-to-date tools to build installers and add certificates.

You are welcome if you can help in this area.

Database

Supported DBMS

MySql 5.7, MariaDb 10.3, and PostgreSQL 9 are supported.

  • MySql because administration is quite simple.
  • PostgreSql because it is completely free software.
  • MariaDb for both reasons. It is the recommended DBMS to use.

In the future, we may try other DBMS, but that would require a bigger development team.

In the main sources, avoid SQL statements specific to some DBMS. When there is no alternative, compatibility procedures should be made. They are all centralized in one unit (util/gconnection.pas).

Table and fields definitions and properties

In Gestinux_util there is a TGTable component used to store all the metadata of tables used in Gestinux. With this component, there is no need to store table definitions elsewhere, and no SQL script is required to initialize or upgrade the database.

The database and table structures are created by the main executable, as specified in unitdatamodule.pas, in TGTable properties. See the component TGTable for more details.

Retrieved from "https://gestinux.net/mediawiki/index.php?title=Developing&oldid=4363"