atria-tools/lutin
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

[DOC] better documentation

Browse Source
This commit is contained in:
Edouard DUPIN 2016-09-09 21:30:25 +02:00
parent 604078f1c0
commit 082556e591
5 changed files with 154 additions and 76 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
README.rst
View File

@ -43,7 +43,7 @@ http://github.com/HeeroYui/lutin/
Documentation
-------------
http://github.com/HeeroYui/lutin/tree/master/doc/
http://HeeroYui.github.io/lutin/
Installation
------------

25
doc/010_basic_concept.md
View File

@ -1,11 +1,13 @@
Basic concept
Basic concept {#lutin_concept}
=============
@tableofcontents
Lutin is a compleate builder system. It is designed to answers all the application problems.
The library and the distribution problem are partially manage (no real use-case)
Technologie:
------------
============
Lutin is designed in Python 2.X or 3.X to answers at the multiplatform problems.
On Linux or MacOs, it is really easy to compile with Makefile, cmake, but on Windows it is an other problem.
@ -14,7 +16,7 @@ The first version of Lutin has been designed in Makefile, but we need to wait 20
Lutin is not based over an other builder, but compile code itself.
Features:
---------
=========
Lutin is designed to:
- support many hardware platform (X86/X64/ARM...);
@ -25,7 +27,7 @@ Lutin is designed to:
global overview:
----------------
================
Every build system is based on multiple concept depending of their own designed.
@ -36,7 +38,7 @@ For lutin we can différentiate 4 basics concepts:
- System: Many OS manage basic element contain in the OS, This part permit to find generic module availlable in the system.
Module:
-------
=======
When you use lutin, you migth first create a module, This is the basis of the framework. It permit to describe your "module", all it contain, and the deendency.
@ -49,7 +51,7 @@ We can separate a module in some part:
Target:
-------
=======
A target represent the "board" to build the module, we can separate MacOs, IOs, Linux ... and all platform that exist
@ -57,17 +59,22 @@ You can generate a new one or use satandard that are provided
Builder:
--------
========
By default lustin manage many methode to build element like cpp, java, asm files ...
System:
-------
=======
This element provide all elements availlable in the Linux distribution.
[next doc:Generate a delivery](020_Compile_a_module.md)
**Index:**
- @ref mainpage
- @ref lutin_concept
- @ref lutin_use
- @ref lutin_module

84
doc/020_Compile_a_module.md
View File

@ -1,5 +1,7 @@
How to compile
==============
How to use lutin {#lutin_use}
================
@tableofcontents
Lutin permit simply to compile applications and library.
@ -10,8 +12,8 @@ To simply understand the use, we will use a simple library:
```
compile a module:
-----------------
compile a module: {#lutin_use_compile}
=================
It is really simple:
@ -23,7 +25,7 @@ It is really simple:
Option working:
Option working: {#lutin_use_options}
===============
Lutin have a complex option methodologie. We can consider 3 part of the option:
@ -32,11 +34,16 @@ Lutin have a complex option methodologie. We can consider 3 part of the option:
- modules
Global options:
Global options: {#lutin_use_options_global}
---------------
Display help:
*************
Globals option is parse first and manage global setting of the build (not specific of a target)
this keep the last value config set
Display help: {#lutin_use_options_help}
-------------
Availlable everywhere ...
@ -51,16 +58,16 @@ But the system(OS) keep the data in cash, then the next time it is faster.
At the end of the help you an see an help about the etk librery with the associated help.
Build in color:
***************
Build in color: {#lutin_use_options_color}
---------------
```bash
lutin -C
lutin --color
```
Display build line in pretty print mode:
****************************************
Display build line in pretty print mode: {#lutin_use_options_pretty}
----------------------------------------
when an error apear, the gcc or clang compile line can be really unreadable:
```bash
@ -103,8 +110,8 @@ result:
/home/XXX/dev/etk/etk/Color.cpp
```
lutin log:
**********
lutin log: {#lutin_use_options_log}
----------
Lutin have an internal log system. To enable or disable it just select your debug level with the option:
@ -122,8 +129,8 @@ The level availlables are:
- 5: verbose
- 6: extreme_verbose
Select the number of CPU core used:
***********************************
Select the number of CPU core used: {#lutin_use_options_cpu}
-----------------------------------
By default lutin manage only 1 CPU core (faster to debug) but for speed requirement you can use use multiple core:
@ -133,18 +140,20 @@ By default lutin manage only 1 CPU core (faster to debug) but for speed requirem
lutin --jobs 5
```
Force rebuild all:
******************
Force rebuild all: {#lutin_use_options_rebuild_force}
------------------
Sometime it is needed to rebuild all the program, just do :
Sometime it is needed to rebuild all the program, just do:
```bash
lutin -B
lutin --force-build
# or remove the build directory
rm -rf out/
```
Force strip all library and programs:
*************************************
Force strip all library and programs: {#lutin_use_options_strip}
-------------------------------------
Force strip of output binary (remove symboles)
@ -153,8 +162,8 @@ Force strip of output binary (remove symboles)
lutin --force-strip
```
Manage Cross compilation:
-------------------------
Manage Cross compilation: {#lutin_use_options_cross_compile}
=========================
The main objective of lutin is managing the cross compilation to build from linux to other platform:
@ -165,8 +174,8 @@ For android you can use:
lutin -t Windows your-module
```
Build in debug mode:
--------------------
Build in debug mode: {#lutin_use_options_debug_release}
====================
To developp it is fasted with debug tools
@ -181,8 +190,8 @@ You can desire to have compilation optimisation when you build in debug mode:
lutin -m debug --force-optimisation your-module
```
Execute yout program after building it:
---------------------------------------
Execute your program after building it: {#lutin_use_options_execute}
=======================================
You can execute some action in a single line for a module:
@ -198,4 +207,23 @@ Note that the path is distinct for gcc/clang, debug/release, Linux/windows/Andro
Then it is really easy to run the wrong binary.
[next doc:Create a new module](030_Create_a_new_module.md)
Install your program after building it: {#lutin_use_options_install}
=======================================
You can install your build module:
```bash
lutin -m debug your-module?build?install
```
This option is not availlablke on all platform ...
**Index:**
- @ref mainpage
- @ref lutin_concept
- @ref lutin_use
- @ref lutin_module

61
doc/030_Create_a_new_module.md
View File

@ -1,6 +1,12 @@
Create a new Module:
Create a new Module: {#lutin_module}
====================
@tableofcontents
Base of the module file: {#lutin_module_base_file}
========================
To create a new module you will use a generic naming:
```
@ -85,8 +91,8 @@ def create(target, module_name):
Thes it is simple to specify build for:
Create a new Module (LIBRARY):
-----------------------------
Create a new Module (LIBRARY): {#lutin_module_library}
==============================
What to change:
```python
@ -99,11 +105,11 @@ By default the library is compile in shared and static. The binary select the mo
You can force the library to be compile as a dll/so: ```LIBRARY_DYNAMIC``` or a basic include lib: .a ```LIBRARY_STATIC```
Create a new Module (BINARY):
-----------------------------
Create a new Module (BINARY): {#lutin_module_binary}
=============================
Generic Binary:
***************
Generic Binary: {#lutin_module_binary_base}
---------------
What to change:
```python
@ -114,8 +120,8 @@ The Binay is compile by default target mode (note that the IOs target generate a
You can force the Binary to be use dynamic library when possible: ```BINARY_SHARED``` or create a single binary with no .so depenency: ```BINARY_STAND_ALONE```
Create a new Module (TEST-BINARY / TOOL-BINARY):
************************************************
Create a new Module (TEST-BINARY / TOOL-BINARY): {#lutin_module_binary_tools}
------------------------------------------------
Two binary are really usefull in developpement, the tools and the test-unit, This is the reason why we specify for this 2 cases.
@ -137,8 +143,8 @@ def get_sub_type():
```
Create a new Module (DATA):
---------------------------
Create a new Module (DATA): {#lutin_module_data}
===========================
This pode permit to only copy data and no dependency with compilling system
@ -149,10 +155,10 @@ def get_type():
```
Module internal specifications:
Module internal specifications: {#lutin_module_internal}
===============================
Add file to compile:
Add file to compile: {#lutin_module_internal_compile}
--------------------
This is simple: (you just need to specify all the file to compile)
@ -171,7 +177,7 @@ def create(target, module_name):
...
```
Include directory & install header:
Include directory & install header: {#lutin_module_internal_header}
-----------------------------------
A big point to understand is that your library will be used by an other module, then it need to use headers.
@ -203,7 +209,7 @@ def create(target, module_name):
```
Add Sub-dependency:
Add Sub-dependency: {#lutin_module_internal_depend}
-------------------
All library need to add at minimum of a simple library (C lib) and other if needed. To do it jus call:
@ -237,7 +243,7 @@ def create(target, module_name):
...
```
Compilation adn link flags/libs:
Compilation adn link flags/libs: {#lutin_module_internal_flag}
--------------------------------
It is possible to define local and external flags (external are set internal too):
@ -248,13 +254,13 @@ def create(target, module_name):
my_module.add_flag('link-lib', "pthread", export=True)
my_module.add_flag('c++', "-DHELLO_FLAG=\"kljlkj\"", export=True)
# internal flags:
my_module.add_flags('c', "-DMODE_RELEASE")
my_module.add_flag('c', "-DMODE_RELEASE")
...
```
build dependency mode and/or target:
------------------------------------
build mode (release/debug): {#lutin_module_internal_target_mode}
---------------------------
To add somes element dependent of the build mode:
```python
@ -269,6 +275,9 @@ def create(target, module_name):
...
```
build type target: {#lutin_module_internal_target_type}
------------------
To add somes element dependent of the target type:
```python
@ -294,7 +303,7 @@ A "Debian" herited of a "Linux" then it will return ["Linux", "Debian"]
Add some data in the install path (share path):
Add some data in the install path (share path): {#lutin_module_internal_data}
-----------------------------------------------
You can install a simple file:
@ -320,7 +329,7 @@ def create(target, module_name):
...
```
display some debug to help writing code:
display some debug to help writing code: {#lutin_module_internal_write_log}
----------------------------------------
@ -337,13 +346,15 @@ def function(...):
```
A Full template:
A Full template: {#lutin_module_full_template}
================
Create the file:
```
lutin_module-name.py
```
With:
```python
#!/usr/bin/python
import lutin.module as module
@ -478,3 +489,9 @@ def create(target, module_name):
```
**Index:**
- @ref mainpage
- @ref lutin_concept
- @ref lutin_use
- @ref lutin_module

58
doc/readme.md → doc/mainpage.md
View File

@ -1,9 +1,28 @@
Lutin Build system
Lutin Build system {#mainpage}
==================
@tableofcontents
What is Lutin, and how can I use it?
------------------------------------
`lutin` is a generic builder and package maker is a FREE software tool.
![Py package](https://badge.fury.io/py/lutin.png) https://pypi.python.org/pypi/lutin
Release (master) {#lutin_mainpage_build_master}
================
![Build Status](https://travis-ci.org/HeeroYui/lutin.svg?branch=master) https://travis-ci.org/HeeroYui/lutin
Developement (dev) {#lutin_mainpage_build_dev}
==================
![Build Status](https://travis-ci.org/HeeroYui/lutin.svg?branch=dev) https://travis-ci.org/HeeroYui/lutin
What is Lutin? {#lutin_mainpage_intro}
==============
Lutin is an application/library builder, it is designed to concurence CMake, Makefile, Ant, graddle ...
@ -32,16 +51,16 @@ Compilation is availlable for:
- gcc/g++;
- clang/clang++.
Manage [b]workspace build[/b] (in oposition of CMake/make/...)
Manage **workspace build** (in oposition of CMake/make/...)
Install:
--------
Install: {#lutin_mainpage_installation}
========
Requirements: ``Python >= 2.7`` and ``pip``
Install lutin:
**************
--------------
Just run:
```bash
@ -49,7 +68,7 @@ Just run:
```
Install pip:
************
------------
Install pip on debian/ubuntu:
```bash
@ -67,7 +86,7 @@ Install pip on MacOs:
```
Install from sources:
*********************
---------------------
```bash
git clone http://github.com/HeeroYui/lutin.git
@ -75,14 +94,21 @@ Install from sources:
sudo ./setup.py install
```
Tutoral entry point:
--------------------
git repository {#lutin_mainpage_repository}
==============
[tutorial](000_basic_concept.md)
http://github.com/HeeroYui/lutin/
Tutorals: {#lutin_mainpage_tutorial}
=========
- @ref lutin_concept
- @ref lutin_use
- @ref lutin_module
License (APACHE v2.0)
---------------------
License (APACHE v2.0) {#lutin_mainpage_licence}
=====================
Copyright lutin Edouard DUPIN
@ -99,8 +125,8 @@ See the License for the specific language governing permissions and
limitations under the License.
History:
--------
History: {#lutin_mainpage_history}
========
I work with some builder, Every one have theire own adventages, and their problems.
The main point I see, is that the polimorphisme of the worktree is really hard.