From 14ca1e50715abc179c455f885711223a2ac393c0 Mon Sep 17 00:00:00 2001 From: Koichi Murase Date: Mon, 13 Feb 2023 19:09:33 +0900 Subject: [PATCH] README: explain the build process --- README-ja_JP.md | 37 ++++++++++++++++++++++++++++--- README.md | 55 ++++++++++++++++++++++++++++++++++++++++++++--- docs/ChangeLog.md | 1 + make/README.md | 10 +++++++++ note.txt | 13 +++++++++-- 5 files changed, 108 insertions(+), 8 deletions(-) create mode 100644 make/README.md diff --git a/README-ja_JP.md b/README-ja_JP.md index 59102dfd..8b5805fe 100644 --- a/README-ja_JP.md +++ b/README-ja_JP.md @@ -21,7 +21,7 @@ 巨大なデータの処理 (補完、貼り付けなど) の局面でPOSIX 標準コマンドを利用しています。 呼称: `ble.sh` はお好きな様に読んでいただいて問題ありませんが、一番短いのは標記の /blɛʃ/ になりましょう。 -しかし個人的には脳裡で /biːɛliː dɑt ɛseɪtʃ/ と読んでいるものですから、標記の読み方は飽くまで参考と受け止めていただければ幸いです。 +しかし個人的には脳裡で /biːɛliː/ または /biːɛliː dɑt ɛseɪtʃ/ と読んでいるものですから、標記の読み方は飽くまで参考と受け止めていただければ幸いです。 ## 簡単設定 @@ -49,6 +49,11 @@ make -C ble.sh install PREFIX=~/.local echo 'source ~/.local/share/blesh/ble.sh' >> ~/.bashrc ``` +生成過程では、複数のBashスクリプトファイルを結合することで `ble.sh` を生成し、 +他の関連ファイルを正しく配置し、またソースコード中のコードコメントを削除してロードを最適化します。 +生成過程は、C/C++ のコンパイルも伴わずバイナリも生成しませんので、コンパイラを準備していただく必要はありません。 + +
curl を用いて nightly ビルドをダウンロード この方法では `curl`, `tar` (オプション `J` に対応), 及び `xz` (XZ Utils) が必要です。 @@ -95,7 +100,7 @@ echo 'source ~/.local/share/blesh/ble.sh' >> ~/.bashrc - [AUR (Arch Linux)](https://github.com/akinomyoga/ble.sh/wiki/Manual-A1-Installation#user-content-AUR) `blesh-git` (devel), `blesh` (stable 0.3.3) - [NixOS (nixpkgs)](https://github.com/akinomyoga/ble.sh/wiki/Manual-A1-Installation#user-content-nixpkgs) `blesh` (devel) -- [Guix](https://guix.gnu.org/ja/packages/blesh-0.4.0-devel2/) `blesh` (0.4.0-devel2) +- [Guix](https://packages.guix.gnu.org/packages/blesh/0.4.0-devel2/) `blesh` (0.4.0-devel2)
既存の ble.sh を更新 @@ -113,12 +118,38 @@ bash /path/to/ble.sh --update
ble.sh のパッケージ作成 +`ble.sh` は単にシェルスクリプトの集合ですので環境に依存せずにお使いいただけます (いわゆる "`noarch`") ので、 +単にリリースページからビルド済みの tar ボールをダウンロードし中身を `/tmp/blesh-package/usr/local` など所定の位置に配置するだけで問題ありません。 +それでも何らかの理由により自前でビルドする必要がある場合には以下のコマンドをお使いください。 +ビルドの為には git リポジトリ (`.git`) が必要になることにご注意ください。 + ```bash -# パッケージ作成用コマンド +# ビルド & パッケージ作成用コマンド git clone --recursive https://github.com/akinomyoga/ble.sh.git make -C ble.sh install DESTDIR=/tmp/blesh-package PREFIX=/usr/local ``` + +パッケージ管理システムを用いたパッケージ更新方法を指定すると `ble-update` でそれが呼び出されます。 +更新方法を指定するにはスクリプトファイルを `${prefix}/share/blesh/lib/_package.bash` に配置します。 +スクリプトは次の様な変数と関数を定義します。但し `XXX` はパッケージ管理システムの名前に置き換えてください。 + +```bash +# ${prefix}/share/blesh/lib/_package.bash + +_ble_base_package_type=XXX + +function ble/base/package:XXX/update { + update-the-package-in-a-proper-way + return 0 +} +``` + +シェル関数がステータス 0 で終了した場合、更新が成功した事を表し `ble.sh` のリロードが自動的に行われます。 +シェル関数がステータス 6 で終了した場合、`ble.sh` のタイムスタンプが確認され、`ble.sh` が現セッションの開始時刻よりも新しい時に限りリロードが行われます。 +シェル関数がステータス 125 で終了した場合、`ble.sh` に組み込みの更新処理が試みられます。 +それ以外の場合には更新処理が中断されます。この場合、シェル関数が状況を説明するメッセージを出力するようにして下さい。 +具体例として `AUR` パッケージの [`_package.bash`](https://aur.archlinux.org/cgit/aur.git/tree/blesh-update.sh?h=blesh-git) も参考にしていただければ幸いです。
## 機能概要 diff --git a/README.md b/README.md index 1f6f75a6..fcf255a0 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ processing of large data in completions, paste of large data, etc. Pronunciation: The easiest pronunciation of `ble.sh` that users use is /blɛʃ/, but you can actually pronounce it as you like. I do not specify the canonical way of pronoucing `ble.sh`. -In fact, I personally read it verbosely as /biːɛliː dɑt ɛseɪtʃ/ in my head. +In fact, I personally call it simply /biːɛliː/ or verbosely read it as /biːɛliː dɑt ɛseɪtʃ/ in my head. ## Quick instructions @@ -50,6 +50,28 @@ git clone --recursive https://github.com/akinomyoga/ble.sh.git make -C ble.sh install PREFIX=~/.local echo 'source ~/.local/share/blesh/ble.sh' >> ~/.bashrc ``` + +The build process integrates multiple Bash script files into a single Bash script `ble.sh`, +place other module files in appropriate places, and strip code comments for shorter initialization time. +This does not involve any C/C++/Fortran compilations and generating binaries, so C/C++/Fortran compilers are not needed. + + +[ Some people seem to bilindly believe that one always need to use `make` with C/C++/Fortran compilers to generate binaries. +They complain about `ble.sh`'s make process, which comes from the lack of knowledge on `make`. +One should learn the general principle of `make`. + +C/C++ programs in the repository is used to update the Unicode character table from the Unicode database when a new Unicode standard appears. +The generated table is included in the repository: +[`canvas.GraphemeClusterBreak.sh`](https://github.com/akinomyoga/ble.sh/blob/master/src/canvas.GraphemeClusterBreak.sh), +[`canvas.c2w.musl.sh`](https://github.com/akinomyoga/ble.sh/blob/master/src/canvas.c2w.musl.sh), +[`canvas.c2w.sh`](https://github.com/akinomyoga/ble.sh/blob/master/src/canvas.c2w.sh), +and [`canvas.emoji.sh`](https://github.com/akinomyoga/ble.sh/blob/master/src/canvas.emoji.sh), +so there is no need to run these C/C++ programs in the build process. +Another C file is used as an adapter in a old system MSYS1, +which is used with an old compiler toolchain in Windows, but it will never be used in Unix-like systems. + +Each file used in the build process is explained in [make/README.md](make/README.md). ] +
Download the nightly build with curl @@ -98,7 +120,7 @@ This only requires the corresponding package manager. - [AUR (Arch Linux)](https://github.com/akinomyoga/ble.sh/wiki/Manual-A1-Installation#user-content-AUR) `blesh-git` (devel), `blesh` (stable 0.3.3) - [NixOS (nixpkgs)](https://github.com/akinomyoga/ble.sh/wiki/Manual-A1-Installation#user-content-nixpkgs) `blesh` (devel) -- [Guix](https://guix.gnu.org/en/packages/blesh-0.4.0-devel2/) `blesh` (0.4.0-devel2) +- [Guix](https://packages.guix.gnu.org/packages/blesh/0.4.0-devel2/) `blesh` (0.4.0-devel2)
Update an existing copy of ble.sh @@ -116,12 +138,39 @@ bash /path/to/ble.sh --update
Create a package of ble.sh +Since `ble.sh` is just a set of shell scripts and do not contain any binary (i.e., "`noarch`"), +you may just download the pre-built tarball from release pages and put the extracted contents in e.g. `/tmp/blesh-package/usr/local`. +Nevertheless, if you need to build the package from the source, please use the following commands. +Note that the git repository (`.git`) is required for the build. + ```bash -# PACKAGE (for package maintainers) +# BUILD & PACKAGE (for package maintainers) git clone --recursive https://github.com/akinomyoga/ble.sh.git make -C ble.sh install DESTDIR=/tmp/blesh-package PREFIX=/usr/local ``` + +When you would like to tell `ble.sh` the way to update the package for `ble-update`, +you can place `_package.bash` at `${prefix}/share/blesh/lib/_package.bash`. +The file `_package.bash` is supposed to define a shell variable and a shell function +as illustrated in the following example (please replace `XXX` with the package management system): + +```bash +# ${prefix}/share/blesh/lib/_package.bash + +_ble_base_package_type=XXX + +function ble/base/package:XXX/update { + update-the-package-in-a-proper-way + return 0 +} +``` + +When the shell function returns exit status 0, it means that the update has been successfully done, and the reload of `ble.sh` will be automatically happen. +When the shell function returns exit status 6, the timestamp of `ble.sh` is checked, and the reload of `ble.sh` only happens when `ble.sh` is actually update. +When the shell function returns exit status 125, the default `ble.sh` update procedure is attempted. +Otherwise, the updating procedure is canceled, where any message explaining situation should be output by the shell function. +An example `_package.bash` for `AUR` can be found [here](https://aur.archlinux.org/cgit/aur.git/tree/blesh-update.sh?h=blesh-git).
## Features diff --git a/docs/ChangeLog.md b/docs/ChangeLog.md index de1f517f..615b60ec 100644 --- a/docs/ChangeLog.md +++ b/docs/ChangeLog.md @@ -361,6 +361,7 @@ - README: add a link to the explanation on the "more reliable setup" of bashrc (motivated by telometto) `#D1905` 09bb4d3 - README: describe `contrib/fzf` integration (reported by SuperSandro2000, tbagrel1) `#D1907` 3bc3bea b568ade - README: add links to Manual pages for *kspec* and `modifyOtherKeys` `#D1917` fb7bd0b1 b568ade +- README: explain the build process `#D1964` `#D1965` xxxxxxx ## Optimization diff --git a/make/README.md b/make/README.md new file mode 100644 index 00000000..6797f610 --- /dev/null +++ b/make/README.md @@ -0,0 +1,10 @@ +# make scripts and programs + +- `canvas.c2w.wcwidth*.cpp` ... These C++ codes are used to generate the character-width table by the C-library implementations and different terminal implementations. + [`src/canvas.c2w.musl.sh`](../src/canvas.c2w.musl.sh) is generated by this program. +- `canvas.c2w.list-ucsver-detection-codes.sh` ... This script is used to analyze the character-width table based on Unicode database. + The character codes used by the test for [`bleopt char_width_{mode,version}=auto`] are determined based on the result of this script. +- `canvas.emoji.sh` ... This script is used to test the emoji supports of different terminals. +- `mwg_pp.awk` ... This is a preprocessor program written in AWK, which is used to preprocess and combine multiple shell scripts into a single file `ble.sh`. + The source repository is [`akinomyoga/mwg_pp`](https://github.com/akinomyoga/mwg_pp). +- `debug.leakvar.exclude-list.txt` ... This is a white list for the global variables. diff --git a/note.txt b/note.txt index 1fc9a53b..e0369887 100644 --- a/note.txt +++ b/note.txt @@ -1936,8 +1936,6 @@ bash_tips * blerc.template: update unicode versions - * README: Guix package の位置が変わっている。 - * syntax: 5.0 以降では関数名として function `xxx` 等も実は許されている。5.3 以降では更に <(...) も関数名として使える。しかもこれらは `xxx`() や <(...)() の形式でも定義できる。 @@ -6678,6 +6676,17 @@ bash_tips Done (実装ログ) ------------------------------------------------------------------------------- +2023-02-13 + + * README: ビルド過程に対する説明 [#D1965] + + 勘違いする人が沢山いるし勝手に馬鹿にしている人がいるので README の make の + 部分に色々書いておく。 + + * make/README にも各ファイルの説明を書いている。 + + * README: Guix package の位置が変わっている [#D1964] + 2023-02-12 * prompt: \g{} は ble/color/setface/.spec2g を使う? [#D1963]