Skip to content

Commit b66f60d

Browse files
mckaygerhardmckaygerhard
committed
handle the documentations of the manual and technology
* Minimize the INSTALL.md file to quick commands ... * move all the installation documentation to doc/Installation.md * Provide a better format of consice redaction on README * Fix link of doc in the main README * Create the terminologi and stage documentation base * Create the FAQ document base * Create the Manual of usage document base * Populate and document the technology on use
1 parent 4bf72cb commit b66f60d

7 files changed

+271
-92
lines changed

‎doc/FAQ-and-notes.md

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
Teaiso FAQ and Notes
2+
=======
3+
4+
**The ISO generation tool for GNU/Linux**
5+
6+
## Notes
7+
8+
#### Social networks
9+
10+
This project has a active telegram group: https://t.me/iso_calismalari Main language is Turkish but allowed English too.
11+
12+
* Açıklama ve kurallar https://t.me/kurallartr
13+
* GNU/Linux gurubumuz: https://t.me/gnulinuxtr
14+
15+
## FAQ
16+
17+
#### My iso do not have networking
18+
19+
Some cases are special, by example alpine init system is complete overriden, so the normal
20+
init process is not the same, that's the reason `teaiso` created images of alpine linux
21+
only has networking if you included `networkmanager` package in the live iso creation.
22+
23+
#### Usage of DESTDIR at install
24+
25+
Please understand that although you can set `$DESTDIR` at installation procedure,
26+
the developer has set paths to the root, and this variable is only used to manage
27+
the destination of files when performed the install, not the execution of the program.
28+
29+
## See also:
30+
31+
* [Teaiso-technology.md](Teaiso-technology.md)

‎doc/Installation.md

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
Teaiso INSTALL
2+
==============
3+
4+
**The ISO generation tool for GNU/Linux**
5+
6+
## Requirements
7+
8+
Currently **Teaiso** is not packaged in any distro, but is distribution agnostic..
9+
so will work in any linux distro, including those with `muslc` library.
10+
11+
Just the program does not need RAM neither DISK so much.. but when performed runtime
12+
will need so much as you wants into each iso generation.
13+
14+
## Dependencies
15+
16+
#### Build
17+
18+
* git
19+
* wget
20+
* gcc
21+
* make
22+
23+
#### Runtime
24+
25+
* bash
26+
* chroot
27+
* coreutils
28+
* python3
29+
* busybox
30+
* mtools
31+
* xorriso
32+
* grub (check issue #3)
33+
* squashfs-tools
34+
35+
## Installation
36+
37+
The installation only places files in two places, for more information review [Teaiso technology paths](Teaiso-technology.md#paths)
38+
39+
Please read about the [usage of `$DESTDIR` variable at FAQ-and-notes.md](FAQ-and-notes.md#usage-of-destdir-at-install).
40+
41+
#### Local install
42+
43+
This is the recommended way for any kind of linux:
44+
45+
```
46+
git clone https://gitlab.com/tearch-linux/applications-and-tools/teaiso
47+
48+
cd teaiso
49+
50+
make build
51+
52+
make install
53+
```
54+
55+
#### Network install
56+
57+
This is only valid for Debian based distributions. Basically performs in automatic way the local install.
58+
59+
```
60+
wget https://gitlab.com/tearch-linux/applications-and-tools/teaiso/-/raw/master/netinstall -O - | bash
61+
```
62+
63+
## See also:
64+
65+
* [README.md](README.md)

‎doc/Manual-of-usage.md

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
Teaiso Manual
2+
======
3+
4+
**The ISO generation tool for GNU/Linux**
5+
6+
## About the program
7+
8+
The main program is `mkteaiso`, the program will produce an ISO boot image file and must be parse a default profile (linux flavour) to produce.
9+
-
10+
-The complete terminology and step by step documentation are into [teaiso-technology.md](teaiso-technology.md).
11+
-
12+
-For quick workflow, first lest check what profiles (linux flavours) we can produce:
13+
14+
## Help of the program
15+
-
16+
-```
17+
-Usage: mkteaiso -p=PROFILE [OPTION]...
18+
-ISO generation tool for GNU/Linux.
19+
-Example: mkteaiso -p=/usr/lib/teaiso/profiles/archlinux --interactive
20+
-Profile directory should contain profile.yaml.
21+
-
22+
-Base Arguments:
23+
- -p=PROFILE, --profile=PROFILE Profile directory or name (default: archlinux)
24+
- -o=OUTPUT, --output=OUTPUT ISO output directory (default: /var/lib/teaiso/output)
25+
- -w=WORK, --work=WORK ISO work directory (default: /var/lib/teaiso/work)
26+
- -c=BASE, --create=BASE Create profile by base profile
27+
- -g=KEY, --gpg=KEY Sign airootfs image by GPG
28+
-
29+
-Miscellaneous:
30+
- -h, --help Display this help text and exit
31+
- --version Display version and exit
32+
- --nocolor Disable colorized output
33+
- --simulate Enable simulation mode
34+
- --nocheck Skip all check
35+
- --interactive Interactive operations
36+
- --debug Enable debug mode
37+
-```
38+
39+
40+
41+
#### Profiles
42+
43+
-The profiles are the flavours of iso that will be created, the format is well described in the document [creating-profile.rst](creating-profile.rst).
44+
-
45+
-These are the available profiles and defaults for each one:

‎doc/README.rst

Lines changed: 16 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,12 @@ Teaiso
33

44
**The ISO generation tool for GNU/Linux**
55

6+
Welcome to Teaiso's official documentation. Here you can find probably anything you need to know about
7+
the configuration and usage of your installation, the usage and the contributing guidelines.
8+
9+
Are you ready to get into this boat? 🚢
10+
11+
612
About Teaiso
713
============
814

@@ -17,28 +23,22 @@ About the project
1723

1824
**Teaiso** is the iso generation tool of the **Tearch-linux** project at https://gitlab.com/tearch-linux, our goal is not being distro like `eos`, `arco`.
1925

20-
About the technology
21-
============
22-
23-
Our technology is made with `c`, `bash` and `python`, the work of the teaiso is using chroot by the moment, in the future we will reimplement in `vala` and maybe use docker containers to avoid touch system process.
24-
25-
The live system used the `squashfs-tools` to produce the rootfs we called `airootfs` where we put everything included for live stuffs like desktop sesion.
26-
27-
The project uses the concept of "profiles" as linux distributions to build, each profile are few files that determines what customizations are made in live mode and what stuffs are included in the squasfs file.
28-
29-
Where to starting
26+
Where to start
3027
============
3128

32-
Currently **Teaiso** is not packaged in any distro, but is distribution agnostic.. just clone the repository and install as described.
33-
34-
When you install the project, only two places are touch, the program binary (the script named `mkteaiso`) that wil be in `$(DESTDIR)/usr/bin/mkteaiso` and the scripts files that will be in `$(DESTDIR)/usr/lib/teaiso/` as default paths when installed. For more information check the INSTALL.md file of the root directorty of the project sources.
35-
36-
After that just call `mkteaiso` with a profile to build default linux distro. For more information of usage check [starting-use-case.md](starting-use-case.md)
29+
The program is distribution agnostic.. just clone the repository and install as described.
3730

31+
1. Install the project, check the [Installation.md](Installation.md) documentation.
32+
2. The manual usage is simple, check the [Manual-of-usage.md](Manual-of-usage.md)
33+
3. After understand basics, check:
34+
* About the technology: [Teaiso-technology.md](Teaiso-technology.md)
35+
* About profiles: [creating-profile](creating-profile.rst)
36+
* About made linux distros: [porting-distribution](porting-distribution.rst)
37+
4. We encourage you to read the [FAQ-and-notes.md](FAQ-and-notes.md)
3838

3939
See also
4040
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4141

42-
* [doc/starting-use-case.md](doc/starting-use-case.md)
42+
* [starting-use-case.md](starting-use-case.md)
4343
* [creating-profile](creating-profile.rst)
4444
* [porting-distribution](porting-distribution.rst)

‎doc/Teaiso-technology.md

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
Teaiso technology
2+
==================
3+
4+
**The ISO generation tool for GNU/Linux**
5+
6+
## General information
7+
8+
Our project is made with `c`, `bash` and `python`, the work of the teaiso is using chroot by the moment,
9+
in the future we will reimplement in `vala` and maybe use docker containers to avoid touch system process.
10+
11+
The live system used the `squashfs-tools` to produce the rootfs of the live disk.
12+
13+
The project uses the concept of "profiles" as linux distributions to build,
14+
each profile are few files that determines what customizations are made in live mode
15+
and what stuffs are included in the squasfs file; also each profile
16+
17+
#### Terminology
18+
19+
* `airootfs`: is the rootfs directory that willwork and from the squasfs will be created.
20+
* `profile`: are directories where customizations will be taken to apply over the `airootfs` check [creating-profile.rst](creating-profile.rst) for more information.
21+
* skeleton profiles: are template base from the teaiso profile directory, use it for creation of working profiles.
22+
* working profiles: are the real profiles created based on the skeleton ones. and will handle customizations to apply.
23+
* `distro`: each profile corresponds to a distro script for processing, to perform specific distro needs, check [porting-distribution.rst](porting-distribution.rst) for more information.
24+
* `funtion`: the distro format defined functions that will determine modifications and actions over the `airootfs`.
25+
* `variables`: are used in the performed funtions only for some distros, by example Debian based ones.
26+
* `shared`: this is a directory that will be common beetween the `airootfs` and the host real filesystem
27+
* `stage`: the runlevels controls to determine the creation progress of the iso generation, we have 10 stage runlevels where the profile customizations will be apply.
28+
* `mkteaiso`: is the main program to use, check the quick workflow at the [starting-use-case.md](starting-use-case.md) document.
29+
30+
#### Artifacts
31+
32+
| stuff | path | notes |
33+
| ---------- | ---------------------------- | ----- |
34+
| `mkteaiso` | `$(DESTDIR)/usr/bin` | Its the main program |
35+
| teaiso | `$(DESTDIR)/usr/lib/teaiso` | teaiso files artifacs |
36+
| outputs | `/var/lib/teaiso` | teaiso product outputs |
37+
| logs | `/var/log/teaiso.log` | teaiso trace outputs |
38+
39+
#### Paths
40+
41+
When you [install](Installation.md) the project, only two places are touch,
42+
the program binary named `mkteaiso` that will be in `$(DESTDIR)/usr/bin`
43+
and the program files that will be in `$(DESTDIR)/usr/lib/teaiso/` when installed.
44+
Please read about the [usage of `$DESTDIR` variable at FAQ-and-notes.md](FAQ-and-notes.md#usage-of-destdir-at-install).
45+
46+
When you [used]() the program, extra path will be used,
47+
the program works and outputs the iso images at `/var/lib/teaiso/`.
48+
the working dirs will be at `/var/lib/teaiso/work`. and
49+
the output iso files will be at `/var/lib/teaiso/output`.
50+
The logs will be performed also into `/var/log`.
51+
52+
The output and work paths are cutomizable, those are not auto cleaned by the program,
53+
neither managed by uninstal.
54+
55+
#### Stage runlevels
56+
57+
The stage runlevels controls to determine the creation progress of the iso generation,
58+
we have 10 stage runlevels where the profile customizations will be apply:
59+
60+
* 0 This performs the cofnigurations and check
61+
* 1 This performs the init from the distro definition, special case are handle by example in alpine and debian.
62+
* 2 This performs the population of the `airootfs` and the mount of the shared directory parsed to the `mkteaiso` command
63+
* 3 This performs the customizations of the `airootfs` by running `customize_airootfs_pre` script of `profile` definition
64+
* 4 This performs the installation of base rootfs packages of `distro` using "packages" file of `profile`
65+
* 5 This performs the preparation of the customized `airootfs` in the working dir for post customizations
66+
* 6 This performs the customizations of the `airootfs` by running the `customize_airootfs` script of `profile` definition
67+
* 7 This performs the list of the packages installed for information, and later umount the shared directory
68+
* 8 This performs the file permission by lines defined in `file_permission` field of `profile` definition, after that creates the `squashfs` file
69+
* 9 This performs the creation of the iso image after customizations made by the `customize_isowork` scripts, will handle the `squashfs` file
70+
71+
#### Variables
72+
73+
TODO
74+
75+
## Profiles definitions
76+
77+
Those are directories where customizations will be taken to apply over the `airootfs`
78+
check [creating-profile.rst](creating-profile.rst) for more information.
79+
80+
## Customizations scripts
81+
82+
The contents of the iso are manage on two filesystems, the root OS and the ISO file.
83+
Those scripts are just **pure bash format but limited in context by the nature of the running `stage` environment**.
84+
85+
* `customize_airootfs_pre` will perform all those command before put packages of `distro` using "packages" file of `profile`
86+
* `customize_airootfs` will perform all those command after put packages of `distro` using "packages" file of `profile`
87+
* `customize_isowork_pre` will perform all those command before creation of the ISO image
88+
* `customize_isowork` will perform all those command at the creation of the ISO image, but not before
89+
90+
## See also
91+
92+
* [starting-use-case.md](starting-use-case.md)
93+
* [creating-profile](creating-profile.rst)
94+
* [porting-distribution](porting-distribution.rst)

‎doc/starting-use-case.md

Lines changed: 20 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -5,17 +5,11 @@ Teaiso brief usage
55

66
## General usage
77

8-
The main program is `mkteaiso`, the program will produce an ISO boot image file and must be parse a default profile (linux flavour) to produce.
9-
10-
The complete terminology and step by step documentation are into [teaiso-technology.md](teaiso-technology.md).
11-
12-
For quick workflow, first lest check what profiles (linux flavours) we can produce:
8+
The main program is `mkteaiso`this document is a quick workflow (for more complete information consult the document [Manual-of-usage.md](Manual-of-usage.md)).
139

1410
#### Profiles
1511

16-
The profiles are the flavours of iso that will be created, the format is well described in the document [creating-profile.rst](creating-profile.rst).
17-
18-
These are the available profiles and defaults for each one:
12+
Firt we must create a profile, profiles are the template flavours of iso that will be created, these are the available profiles and defaults for each one:
1913

2014
| name | linux | observations |
2115
| ------------ | ---------------- | ---------------------------- |
@@ -27,20 +21,22 @@ These are the available profiles and defaults for each one:
2721
| tearch | Arch | intent to customize to newbie users 😒 |
2822
| ubuntu | Debian/Ubuntu | imagine live without casper file.. 😂 |
2923

30-
#### Working dir and space
3124

32-
Profiles will determine what flavour and the contents of the flavour of linux. Inside each profile there's two scripts: `packages.x86_64` and `customize-airootfs.sh` . Those determines the packages that will be installed and modifications to be made respectivelly.
25+
> This document is a quick review made for fast workflow, the format is well described in the document [creating-profile.rst](creating-profile.rst).
3326
34-
Due to the fact that an ISO file will be produced, a considerable space will be required, this will depend on modifying the file `customize-airootfs.sh` and `packages.x86_64`. If you use default profiles the sizes will be around 300Mb.
27+
#### Default Examples
3528

36-
For more information about `mkteaiso` terminology check [teaiso-technology.md](teaiso-technology.md).
29+
To produce a debian linux testing:
3730

38-
#### Default Examples
31+
```
32+
mkteaiso -c alpine
33+
cd alpine
34+
mkteaiso -p $(pwd)
35+
```
3936

40-
* To produce a alpine linux base just `mkteaiso -p=alpine`
41-
* To produce a debian linux testing `mkteaiso -p=debian`
37+
The ISO files will be produced to the `/var/lib/teaiso/output` directory, with date as part of the name.
4238

43-
The ISO files will be produced to the `/var/lib/teaiso/output` directory, with date as part of the name. For more information about `mkteaiso` workflow check [teaiso-technology.md](teaiso-technology.md)
39+
> This document is a quick way to carry out the workflow, for more complete information consult the document [Manual-of-usage.md](Manual-of-usage.md)
4440
4541
#### Customization Examples
4642

@@ -49,9 +45,12 @@ You can made your own customized iso:
4945
* Create a working directory of the profile and copy base profiles, in this case we will create a KDE based iso but from Alpine defualt profile:
5046

5147
```
52-
mkdir /usr/src/teaiso-alpine-kde-stable
48+
cd /usr/src
49+
50+
mkteaiso -c alpine
51+
52+
mv alpine teaiso-alpine-kde-stable
5353
54-
cp /usr/lib/teaiso/profiles/alpine/* /usr/src/teaiso-alpine-kde-stable/
5554
```
5655

5756
* Customize the defaults of the `airootfs` (the root of the installed live files), here we just add kde stuff and provide default password of users:
@@ -77,35 +76,10 @@ EOF
7776
mkteaiso --profile=/usr/src/teaiso-alpine-kde-stable
7877
```
7978

80-
For more information about `mkteaiso` check [teaiso-technology.md](teaiso-technology.md).
79+
> For more information about `mkteaiso` terminology check [Teaiso-technology.md](Teaiso-technology.md).
8180
82-
## Help of the program
83-
84-
```
85-
Usage: mkteaiso -p=PROFILE [OPTION]...
86-
ISO generation tool for GNU/Linux.
87-
Example: mkteaiso -p=/usr/lib/teaiso/profiles/archlinux --interactive
88-
Profile directory should contain profile.yaml.
89-
90-
Base Arguments:
91-
-p=PROFILE, --profile=PROFILE Profile directory or name (default: archlinux)
92-
-o=OUTPUT, --output=OUTPUT ISO output directory (default: /var/lib/teaiso/output)
93-
-w=WORK, --work=WORK ISO work directory (default: /var/lib/teaiso/work)
94-
-c=BASE, --create=BASE Create profile by base profile
95-
-g=KEY, --gpg=KEY Sign airootfs image by GPG
96-
97-
Miscellaneous:
98-
-h, --help Display this help text and exit
99-
--version Display version and exit
100-
--nocolor Disable colorized output
101-
--simulate Enable simulation mode
102-
--nocheck Skip all check
103-
--interactive Interactive operations
104-
--debug Enable debug mode
105-
```
10681

10782
## See also
10883

109-
* [teaiso-technology.md](teaiso-technology.md)
110-
* [creating-profile](creating-profile.rst)
111-
* [porting-distribution](porting-distribution.rst)
84+
* [Manual-of-usage.md](Manual-of-usage.md)
85+
* [Teaiso-technology.md](Teaiso-technology.md)

0 commit comments

Comments
 (0)