|
|
# GNUKhata core developers guide
|
|
|
Welcome to GNUKhata core manual.
|
|
|
This is the guide on programming GNUKhata. As you are aware, GNUKhata is a core set of APIs containing all the business logic for book keeping, inventory and generating related reports. As a result, programmers can write different type of front-ends by utilizing the same core logic.
|
|
|
This guide provides you details on the source code, layout and architecture of the most important part of GNUKhata, namely it's core logic.
|
|
|
GNUKhata as a software is a package of APIs for managing books of accounts and inventory.
|
|
|
The logic is written on the CRUD concepts in REST.
|
|
|
|
|
|
We are very happy to help you help us and the free software community for creating this free,(as in freedom ) professional quality and industry level accounting software. To participate in the development of this web front end, you should first fulfill the prerequisites. This will save your time and avoid any confusion on getting started or on certain aspect of the development/ programming. Note that you can always join the [GNUKhata developers mailing list](http://freelists.org/list/gnukhata-devel) and discuss with us any difficulty or suggestion you have.
|
|
|
|
|
|
|
|
|
## Prerequisites
|
|
|
If you wish to write new functionality or modify existing one, we are more than happy to welcome you.
|
|
|
Here's the list of concepts and technologies you should know.
|
|
|
|
|
|
### GNU/Linux OS
|
|
|
Needless to say we exclusively use GNU/Linux operating system for our daily work and professional programming. We are free software advocates and urge every one to use it, not just for the superior, faster and professional performance but also because it is a freedom technology. GNU/Linux is the free (as in freedom ) OS and we recommend Ubuntu, Mint, or if you like the hacker stuff, Debian brands. Note that GNUKhata works on Windows but all our programming and designing happens on the said OS.
|
|
|
### Gitlab account
|
|
|
|
|
|
One major aspect of a free and open source project is that it's source code is open and freely available to all. You can copy, study, modify and share it with any one for any purpose. However for professional management and quality assurance every project needs a core team in charge of the main source code. Any one can then make an exact copy of the original source code and make any changes to that copy. Then such changes are submitted to the main repository (meaning the code base ). a merge request can be then sent where the core team members screen the submitted code for quality and see if the said task is properly done. If all is well then the contribution is merged into the main repository. There are several such free project management and collaboration tools. One such is [Git Lab](http://gitlab.com) and that's what we use for GNUKhata. You should make an account there and then follow the instructions in this guide for forking and cloning a copy of the source code for yourself.
|
|
|
You can also visit [Gitlab basics ](https://gitlab.com/help/gitlab-basics/README.md) to get started.
|
|
|
We have two projects under the GNUKhata group.
|
|
|
You need to forke the project for core logic from [here](http://www.gitlab.com/gnukhata/gkcore) after creating an account.
|
|
|
You will then need to clone your personal copy on to your machine.
|
|
|
You may consider this as your entry into collaborative free software development in general and GNUKhata in particular.
|
|
|
### SQL basics
|
|
|
GNUKhata uses Relational Database Management System (RDBMS ) for the data.
|
|
|
You might be already aware that Structured Query Language (SQL) is used to define, manage and access data from such RDBMS.
|
|
|
We use [Postgresql](http://www.postgresql.org) for GNUKhata.
|
|
|
You can read the manuals on that site to get a basic grasp of SQL syntax.
|
|
|
Read this [beginners guide ](https://www.postgresql.org/docs/9.6/static/tutorial.html) to get an overview of the RDBMS.
|
|
|
Details on SQL are in [This manual](https://www.postgresql.org/docs/9.6/static/sql.html)
|
|
|
|
|
|
You must specially look at the json datatype which is new in the SQL based databases. Syntax for queries in general and json in particular must be understood at the basic level.
|
|
|
[This chapter ](https://www.postgresql.org/docs/9.6/static/datatype.html) will give you an overview of all datatypes.
|
|
|
**Note: You need not go in great details for a deep understanding of SQL. A basic understanding of how to select, update and insert data is sufficient.**
|
|
|
### Python programming language
|
|
|
For getting started with programming any existing project, we first need to know which is the base programming language for it.
|
|
|
[Python](http://www.python.org) is a free, powerful, robust and scalable programming language. Given all this power and richness it is extremely easy as well.
|
|
|
That's the reason why it is favored by the likes of Google, NASA and many huge organisations. You can actually learn this language in a week's time at the maximum, given it's straight forward clean and very short syntax.
|
|
|
You can enjoy learning this amazing programming language from [this easy book](http://openbookproject.net/thinkcs/python/english2e/index.html)
|
|
|
**Note: you need not go in great details of every aspect. Learning about how variables, lists, dictionaries, basic classes and functions work, is more than sufficient.**
|
|
|
### REST API concepts
|
|
|
REpresentational State Transfer or (REST) for short has now become the most widely used method of writing modern software, specially web services.
|
|
|
It's wide spread acceptance is mostly attributed to it's way of using CRUD (Create Read Update Delete ) methods for a given resource. Every resource is an entity and thus can possess these four methods to manipulate the data.
|
|
|
HTTP protocol has defined 4 verbs for these 4 actions.
|
|
|
GET for Read, POST for create, PUT for Update and DELETE for delete.
|
|
|
So let's say you have an entity called student in a institute management system, you can create a new student by using POST, get the details by GET, update record by PUT and delete that record using DELETE.
|
|
|
Of course your web based service must be running on a certain IP:port and for every resource there will be a url, e.g. /student for the student resource.
|
|
|
So student/get will get the record and so on.
|
|
|
For more detailed understanding of REST based applications read [this tutorial](http://www.ibm.com/developerworks/webservices/library/ws-restful/).
|
|
|
|
|
|
|
|
|
One data format which goes hand in hand with RESTfull services is Javascript Object Notation or (JSON) for short.
|
|
|
You can read about the concept on [JSON home page](www.json.org).
|
|
|
Basically REST clients and servers send and receive data using JSON packets.
|
|
|
So you will be dealing with JSON Objects a lot in GNUKhata.
|
|
|
**Python has the dictionary datatype which is interchangeable with JSON.**
|
|
|
### Pyramid Web Framework
|
|
|
Writing every component by yourself all in great details takes a lot of time.
|
|
|
In addition if you were to write every little repeatable code and commonly used components like connectivity logic, data dynamics etc then no project can ever finish in time.
|
|
|
Web frameworks come to our rescue here.
|
|
|
A framework not just helps by providing skeleton code for most common tasks, but also ready to use infrastructure for connectivity database access etc.
|
|
|
We use [Pyramid web framework](http://docs.pylonsproject.org/projects/pyramid/en/latest/quick_tutorial) for both our back-end and front-end.
|
|
|
Look at chapter 1,2,7,8,9.
|
|
|
|
|
|
### SQLAlchemy
|
|
|
If you are already aware of SQL then you will immediately realise that putting or embedding SQL queries inside a program is a tedious and confusing task.
|
|
|
May it be Python, Java or PHP or any language, inserting such sql queries and concatenating them with variables is a nightmare for any programmer.
|
|
|
Object Relational Mapper or (ORM) is a comprehensive answer to this issue.
|
|
|
Imagine writing sql queries as if they were Python statements?
|
|
|
Imagine treating tables as instances of classes?
|
|
|
ORM does exactly this for you.
|
|
|
It helps you define tables as objects using a certain library in your favorite programming language.
|
|
|
it also helps you write queries such as select, Insert, Update etc. as program code.
|
|
|
In Python the most powerful and professional quality ORM is [SQLAlchemy](http://www.sqlalchemy.org/)
|
|
|
It's expression language is what we use in GNUKhata for defining tables and queries for getting, inserting, updating and deleting data.
|
|
|
Read this [tutorial](http://docs.sqlalchemy.org/en/latest/core/tutorial.html) for learning the exact module we use in GNUKhata.
|
|
|
You will absolutely need to know this if you are going to write any core logic in GNUKhata.
|
|
|
**Note: little knowledge of relational databases, Primary key and Foreign key constraints and queries is very useful.**
|
|
|
### Integrated Development environment (IDE) tool
|
|
|
In order to write code faster, get comforts such as auto code completion during programming and better management, we need Rapid Application Development tools (RAD) like an IDE.
|
|
|
This will not just help you program faster but also reduce bugs.
|
|
|
We recommend either Emacs 25, Eclipse or Atom.
|
|
|
|
|
|
For having an ideal Emacs25 set up read Krishnakant Mane's blog [Emacs the Modern old workhorse](https://digitallyfreeblog.wordpress.com/2017/05/22/emacs-the-modern-old-work-horse/).
|
|
|
You can download a ready to use Eclipse version with Python support from [here](https://cloud.disroot.org/s/y9WqyZpYWQPdb0e)
|
|
|
If you prefer atom download it from [here](https://atom.io/download/deb)
|
|
|
You can use any other IDE of your choice, but we have used these two extensively, so can provide you help if you get stuck.
|
|
|
you can now move on to [Project structure overview](projectStructure) |
|
|
\ No newline at end of file |