docs/en/CHANNEL.md

   1 # What is a channel
   2 Channel is an AlterLinux original mechanism that is made so that you can easily switch the files (airootfs) to be included in the image file, the packages to install, the configuration files, etc.
   3 This mechanism allows you to easily create an AlterOS derivative OS.
   4 Initially it was only possible to switch packages, but now the specifications have changed significantly and various changes can be made for each channel.
   5
   6
   7 The following are channel specifications as of May 13, 2020.
   8
   9
  10 # Let the script recognize the channel
  11 The conditions for the script to recognize the channel are as follows.
  12
  13 - There is a channel name directory in `channels`
  14 - The directory is not empty
  15
  16 The script will not recognize it if you create an empty directory or create it somewhere else.
  17 You can check with `./build.sh -h` to see if the script recognized the channel.
  18 Channels that are not displayed in the Help channel list cannot be used.
  19
  20
  21 # About channel name
  22 The channel name is basically a directory name in `channels`.
  23 All the characters that can be used in the directory name can be used in the channel name, but if you use blank characters or double-byte characters, it may not work properly in some environments.
  24 In addition, it is desirable to keep the channel name within 18 characters because it is handled in the script. (If the number of characters is longer than this, the channel name will not be displayed correctly in the help.)
  25
  26 If the directory name ends in `.add`, the channel name will be the string before` .add`.
  27 This is to exclude it from Git management and add your own customized channel.
  28 Finally, run `./build -h` to check the channel name that can be used as an argument.
  29
  30 ## チャンネル名の重複について
  31 **チャンネル名が`.add`がついているものといないもので重複しないようにして下さい！**
  32 `.add`がついているものとついていないものが重複した場合、**`.add`が付いている方が優先**されます。
  33 `.add`がついていないチャンネルは一切使用不可能になりますのでご注意下さい。
  34 また、以下の特殊なチャンネルの名前も使用することができません。
  35
  36
  37 # 特殊なチャンネル
  38 いくつかの特殊なチャンネルがあります。これらのチャンネルはスクリプトに組み込まれているため、追加や削除は行なえません。
  39
  40 ## share
  41 `share`チャンネルは指定されたチャンネルに関わらず使用される共有チャンネルです。
  42 `share`はその他のチャンネルと同じ構造をしていますが、`share`単体をチャンネルとして指定してビルドすることはできません。
  43 全てのチャンネルでインストールされる基本パッケージや共通のファイルなどをここに追加します。
  44
  45 ## rebuild
  46 このチャンネルはヘルプには表示されていますがディレクトリの実体はありません。このチャンネルはスクリプトに組み込まれています。
  47 このチャンネルは作業ディレクトリに生成されたビルドオプションを保存したファイルを読み込み、再ビルドを行うチャンネルです。
  48 そのため作業ディレクトリが存在しない場合はエラーを出力し正常に機能しません。
  49
  50 # それぞれのチャンネルの仕様
  51 チャンネルを構成する主要なディレクトリは`airootfs`と`packages`です。
  52 `airootfs`ディレクトリはパッケージをインストールし`mksquashfs`を実行する直前に`/`を上書きします。
  53 `packages`ディレクトリはインストールするパッケージのリストを記述したテキストファイルを格納します。
  54 それ以外にも場合によって使用できるファイルがいくつか有ります。
  55
  56
  57 ## airootfsから始まるディレクトリ
  58 それぞれのディレクトリ内を`/`としてファイルを配置して下さい。全てのファイルの権限はなるべく引き継がれるようになっています。
  59
  60 ### airootfs.any
  61 アーキテクチャに関わらず最初にライブ環境を上書きします。
  62
  63 ### airootfs.i686 airootfs.x86_64
  64 `x86_64`アーキテクチャなら`airootfs.x86_64`が、`i686`なら`airootfs.i686`が使用されます。
  65
  66 ### ファイルの重複の優先順位
  67 各チャンネルと`share`チャンネルのファイルでは各チャンネルのファイルが優先されます。
  68 また、`airootfs.any`と各アーキテクチャ用のディレクトリでは各アーキテクチャ用のものが優先されます。
  69 以下は`airootfs`のコピーされる順番を示しています。要約すると左が一番優先されず、右が優先されます。
  70
  71 `share/airootfs.any` -> `share/airootfs.<architecture>` -> `<channel_name>/airootfs.any` -> `<channel_name>/airootfs.<architecture>`
  72
  73
  74 ## customize_airootfs.sh
  75 各チャンネルの`airootfs`で、`/root/customize_airootfs_<channel_name>.sh`というファイルが配置された場合、ビルドスクリプトは、`customize_airootfs.sh`が実行された後にそのスクリプトを実行します。
  76 （`customize_airootfs.sh`は`share`チャンネルの`airootfs.any`によって配置されるため、各チャンネルで自由に上書きすることができます。）
  77 もしrootfsの設定を変更したい場合、このファイルを作成して下さい。
  78
  79
  80 ## packagesから始まるディレクトリ
  81 このディレクトリ内に配置された、ファイル名が`.<architecture>`で終わるがパッケージリストとして読み込まれます。
  82 1行で1つのパッケージとして扱い、`#`から始まる行はコメントとして扱われます。
  83
  84 パッケージ名やパッケージリストのファイル名に空白文字や全角文字を含めると正常に動作しない可能性があります。
  85
  86
  87 ### ディレクトリの種類
  88 各アーキテクチャごとにパッケージリストを入れるディレクトリがあります。`airootfs`と違ってアーキテクチャの共有はありません。
  89 例えば`x86_64`アーキテクチャならば`packages.x86_64`が読み込まれます。
  90
  91
  92 ### 特殊なパッケージ
  93 一部、パッケージリストに記述してはいけないパッケージが有ります。
  94 詳細は[こちら](PACKAGE.md)を参照して下さい。
  95
  96
  97 ### 特殊なパッケージリスト
  98 特殊なパッケージリストとして、`jp.<architecture>`と`non-jp.<architecture>`があります。
  99 `-j`オプションによって日本語が有効化されている時、スクリプトは`jp.<architecture>`を読み込みます。
 100 反対に日本語が有効化されていない場合、スクリプトは`non-jp.<architecture>`を使用します。
 101
 102
 103 ### 除外リスト
 104 もしあなたが`share`チャンネルのパッケージでどうしてもインストールしたくないパッケージがある場合、各チャンネルの`packages`ディレクトリ内に`exclude`というファイルを作成し、その中にパッケージを記述することでパッケージを除外することができます。
 105 例えば`share`で必ずインストールされる`alterlinux-calamares`をインストールしたくない場合、そのチャンネルの`exclude`にパッケージ名を追加することでインストールされなくなります。
 106 （その場合は各チャンネルのcustomize_airootfsで不要なファイルを削除して下さい。）
 107 パッケージの記述方法はパッケージリストと同様で、1行で1つのパッケージとして扱い、`#`から始まる行はコメントとして扱われます。
 108
 109 除外できないパッケージも存在します。
 110 スクリプトによって強制的にインストールされるパッケージ（`efitools`など）は除外リストに関係なくインストールされます。
 111 例えば`exclude`に`plymouth`を記述しても`-b`オプションが有効化された場合は強制的にインストールされます。
 112 Plymouthを強制的に無効化したい場合は`exclude`ではなく各チャンネルの`config`より`boot_splash`を`false`に固定して下さい。
 113
 114 `channels/share/packages/exclude`は、スクリプトによって強制的にインストールされるパッケージの一覧が記述されています。
 115 これは作業ディレクトリに正確にログを記録し、チャンネルによって使用不可能なパッケージがインストールされるのを防ぐためです。
 116
 117 また、`exclude`はパッケージを削除するわけではないため依存関係によってインストールされるパッケージを除外することはできません。
 118
 119
 120 ### excludeの適用されるタイミング
 121 `exclude`はパッケージが全て読み込まれた後に適用されます。
 122
 123 パッケージが読み込まれる順番は以下のとおりです、
 124 `share/packages.<architecture>` -> `<channel_name>/packages.<architecture>`
 125
 126 その後に以下の順番でexcludeが読み込まれ、パッケージが除外されます。
 127 `share/packages.<architecture>/exclude` -> `<channel_name>/packages.<architecture>`
 128
 129
 130 ## description.txt
 131 これはチャンネルの説明を記述したテキストファイルです。`channels/<channel_name>/description.txt`に配置されます。
 132 このファイルは必須ではありません。このファイルが無い場合、ヘルプには`This channel does not have a description.txt.`と表示されます。
 133
 134 このファイルは1行で記述することが推奨されています。複数行を記述する必要がある場合、テキストのレイアウトを考えて2行目以降は先頭に19個の半角空白文字を入れたほうが良いでしょう。
 135
 136
 137 ## pacman.conf
 138 `channels/<channel_name>/pacman-<architecture>.conf`を配置すると、ビルド時にそのファイルを使用します。ただし、インストール後の設定ファイルは置き換えないので`airootfs`で`/etc/pacman.conf`を配置して下さい。
 139
 140
 141 ## splash.png
 142 `channels/<channel_name>/splash.png`を配置すると、SYSLINUXのブートローダの背景を変更することができます。
 143 PNG形式の画像で640x480の画像を配置してください。
 144
 145
 146 ## config
 147 既存のビルド設定を上書きするスクリプトです。かならずシェルスクリプトの構文で記述して下さい。
 148 雛形が`build.sh`と同じ階層に設置してあります。
 149 この設定ファイルは**引数による設定さえ**上書きしてしまうため、最小限の必須項目のみを記述するようしてください。（例えばPlymouthのテーマ名やパッケージ名など）
 150
 151 ## 警告
 152 スクリプト内ではローカル変数の定義以外を絶対に行わないで下さい。グローバル変数の定義やその他のコマンドの実効は思わぬ動作につながる危険性が有ります。
 153
 154 ### アーキテクチャごとの設定と優先順位
 155 `channels/<channel_name>/config.any`が読み込まれた後`channels/<channel_name>/config.<architecture>`が読み込まれます。
 156
 157
 158 ## architecture
 159 そのチャンネルで利用可能なアーキテクチャの一覧です。`#`はコメントとして扱われます。