From 082556e591fb84ce8fd523c1c25f773e97e77adf Mon Sep 17 00:00:00 2001 From: Edouard DUPIN Date: Fri, 9 Sep 2016 21:30:25 +0200 Subject: [PATCH] [DOC] better documentation --- README.rst | 2 +- doc/010_basic_concept.md | 25 ++++++---- doc/020_Compile_a_module.md | 84 ++++++++++++++++++++++------------ doc/030_Create_a_new_module.md | 61 +++++++++++++++--------- doc/{readme.md => mainpage.md} | 58 ++++++++++++++++------- 5 files changed, 154 insertions(+), 76 deletions(-) rename doc/{readme.md => mainpage.md} (63%) diff --git a/README.rst b/README.rst index 660bead..d9e511a 100644 --- a/README.rst +++ b/README.rst @@ -43,7 +43,7 @@ http://github.com/HeeroYui/lutin/ Documentation ------------- -http://github.com/HeeroYui/lutin/tree/master/doc/ +http://HeeroYui.github.io/lutin/ Installation ------------ diff --git a/doc/010_basic_concept.md b/doc/010_basic_concept.md index b45ad6b..c3720d0 100644 --- a/doc/010_basic_concept.md +++ b/doc/010_basic_concept.md @@ -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 + diff --git a/doc/020_Compile_a_module.md b/doc/020_Compile_a_module.md index 729bb07..37b3434 100644 --- a/doc/020_Compile_a_module.md +++ b/doc/020_Compile_a_module.md @@ -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 + diff --git a/doc/030_Create_a_new_module.md b/doc/030_Create_a_new_module.md index 5a8477a..e21d7b6 100644 --- a/doc/030_Create_a_new_module.md +++ b/doc/030_Create_a_new_module.md @@ -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 + diff --git a/doc/readme.md b/doc/mainpage.md similarity index 63% rename from doc/readme.md rename to doc/mainpage.md index b5368d0..cda9379 100644 --- a/doc/readme.md +++ b/doc/mainpage.md @@ -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.