diff --git a/GNUmakefile b/GNUmakefile index ca19e3fe..63185168 100644 --- a/GNUmakefile +++ b/GNUmakefile @@ -204,12 +204,22 @@ all: build #------------------------------------------------------------------------------ # target "install" +# Users can specify make variables INSDIR, INSDIR_LICENSE, and INSDIR_DOC to +# control the install locations. Instead of INSDIR, users may specify DESTDIR +# and/or PREFIX to automatically set up these variables. + +ifneq ($(USE_DOC),no) + insdir_license_subdir := /doc +else + insdir_license_subdir := +endif + ifneq ($(INSDIR),) ifeq ($(INSDIR_DOC),) INSDIR_DOC := $(INSDIR)/doc endif ifeq ($(INSDIR_LICENSE),) - INSDIR_LICENSE := $(INSDIR)/doc + INSDIR_LICENSE := $(INSDIR)$(insdir_license_subdir) endif else ifneq ($(filter-out %/,$(DESTDIR)),) @@ -226,7 +236,7 @@ else INSDIR = $(DATA_HOME)/blesh INSDIR_DOC = $(DATA_HOME)/doc/blesh - INSDIR_LICENSE = $(DATA_HOME)/doc/blesh + INSDIR_LICENSE = $(DATA_HOME)$(insdir_license_subdir)/blesh endif ifneq ($(strip_comment),) diff --git a/README-ja_JP.md b/README-ja_JP.md index 27d2fbf3..20e6f57d 100644 --- a/README-ja_JP.md +++ b/README-ja_JP.md @@ -26,8 +26,7 @@ `~/.bashrc` の設定に関しては [節1.3](#set-up-bashrc) を御覧ください。 > [!NOTE] -> `fzf` を `ble.sh` と組み合わせてお使いの場合は [節2.8](#set-up-bashrc) を必ず -> 御覧ください。 +> `fzf` を `ble.sh` と組み合わせてお使いの場合は [節2.8](#fzf-integration) を必ず御覧ください。
git を用いてソースを取得し ble.sh を生成 @@ -130,26 +129,12 @@ git clone --recursive --depth 1 --shallow-submodules https://github.com/akinomyo make -C ble.sh install DESTDIR=/tmp/blesh-package PREFIX=/usr/local ``` -パッケージ管理システムを用いたパッケージ更新方法を指定すると `ble-update` でそれが呼び出されます。 -更新方法を指定するにはスクリプトファイルを `${prefix}/share/blesh/lib/_package.bash` に配置します。 -スクリプトは次の様な変数と関数を定義します。但し `XXX` はパッケージ管理システムの名前に置き換えてください。 +スクリプトファイル、ライセンスファイル。ドキュメントファイルのインストール場所を詳細に指定する方法については、 +後ろの節 [インストール](#install) and [パッケージ作成](#package) を御参照ください。 -```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) も参考にしていただければ幸いです。 +スクリプトファイル `_package.bash` を `${prefix}/share/blesh/lib/_package.bash` に配置することで、 +`ble-update` で用いるパッケージ更新方法を指定することができます。 +詳細については節 [`_package.bash`](#_packagebash) を御参照ください。
## 機能概要 @@ -241,7 +226,7 @@ Vimモードの実装は2017年9月に始まり2018年3月に一先ず完成と [wiki](https://github.com/akinomyoga/ble.sh/wiki/Internals#internal-and-external) (英語) に情報があります。 -## 免責事項 +## 批判 - †1Q. "ble.sh の読み方が分からない"--- A. `ble.sh` はお好きな様に読んでいただいて問題ありませんが、一番短いのは標記の /blɛʃ/ になりましょう。 @@ -262,7 +247,7 @@ Vimモードの実装は2017年9月に始まり2018年3月に一先ず完成と # 1 使い方 -## 1.1 最新の git repository のソースから生成して試す (バージョン ble-0.4)† +## 1.1 ソースからのビルド方法† ### ble.sh 生成 @@ -284,7 +269,7 @@ $ make $ source out/ble.sh ``` -### インストール +### インストール† 指定したディレクトリにインストールするには `make install` コマンドを使用します。 @@ -294,8 +279,29 @@ make install # 指定したディレクトリにインストール make install INSDIR=/path/to/blesh +``` + +メインファイル `ble.sh` 及び関連スクリプトファイルのインストール先ディレクトリは Make 変数 `INSDIR` を用いて指定できます。 +ライセンス及びドキュメントのインストール先は Make 変数 `INSDIR_LICENSE` と `INSDIR_DOC` を用いて指定できます。 +`INSDIR` が指定されている時、`INSDIR_LICENSE` の `INSDIR_DOC` の既定値は `$INSDIR/doc` です。 +`INSDIR` および後述の `DESTDIR`/`PREFIX` が指定されていない時、`INSDIR` の値は `${XDG_DATA_HOME:-$HOME/.local/share}/blesh` になり、 +`INSDIR_LICENSE` と `INSDIR_DOC` の規定値は `${XDG_DATA_HOME:-$HOME/.local/share}/doc/blesh` になります。 + +Make 変数 `USE_DOC=no` が指定されている時、ドキュメントファイルの処理が無効化されます。 +また、ライセンスの既定のインストール先 `INSDIR_LICENSE` は `$INSDIR` に変更されます。 + +既定ではコード中のコメント行や空行はインストール時に自動で削除されます。 +コメントや空行を保持したい場合は `strip_comment=no` を `make` の引数に指定して下さい。 + +`.bashrc` の設定に関しては[節1.3](#set-up-bashrc)を御覧ください。 + +### パッケージ作成† + +パッケージ作成者は Make 変数 `DESTDIR` 及び `PREFIX` を用いて `INSDIR`, +`INSDIR_LICENSE`, `INSDIR_DOC` の既定値を一括で設定することができます。 -# パッケージ作成 (パッケージ管理者用) - 例1 +``` +# パッケージ作成 - 例1 make install DESTDIR=/tmp/blesh-package PREFIX=/usr/local # パッケージ作成 - 例2 @@ -312,34 +318,46 @@ make install USE_DOC=no DESTDIR="$build" PREFIX="$prefix" \ INSDIR_LICENSE="$build/$prefix/share/blesh" ``` -Make 変数 `DESTDIR` または `PREFIX` が指定されている時、 -`ble.sh` 及び関連ファイルは `$DESTDIR/$PREFIX/share/blesh` に、 -ライセンス及びドキュメントは `$DESTDIR/$PREFIX/share/doc/blesh` にコピーされます。 -それ以外で Make 変数 `INSDIR` が指定されている時、 -`ble.sh` 及び関連ファイルは直接 `$INSDIR` に配置され、 -ライセンス及びドキュメントは `$INSDIR/doc` にコピーされます。 -以上の Make 変数が指定されていない時は、 -`ble.sh` 及び関連ファイルは `${XDG_DATA_HOME:-$HOME/.local/share}/blesh` に、 -ライセンス及びドキュメントは `${XDG_DATA_HOME:-$HOME/.local/share}/doc/blesh` にインストールされます。 +`INSDIR` の代わりに Make 変数 `DESTDIR` または `PREFIX` が指定されている時、 +`INSDIR` の値は `$DESTDIR/$PREFIX/share/blesh` に設定され、 +ライセンス及びドキュメントファイルの場所 `INSDIR_LICENSE` と `INSDIR_DOC` の既定値は `$DESTDIR/$PREFIX/share/doc/blesh` になります。 -ライセンス及びドキュメントのインストール先は Make 変数 `INSDIR_LICENSE` と `INSDIR_DOC` を用いて上書きできます。 -Make 変数 `USE_DOC=no` が指定されている場合は、ドキュメントファイルの処理が無効化されます。 +#### `_package.bash` -インストール時にコード中のコメントは自動で削除されますが、コメントを保持したい場合は `strip_comment=no` を `make` の引数に指定して下さい。 +スクリプトファイル `_package.bash` を `${prefix}/share/blesh/lib/_package.bash` に配置することで、 +`ble-update` で用いるパッケージ更新方法を指定することができます。 +スクリプトファイル `_package.bash` では、次で示すような変数と関数を定義します。 +但し `XXX` はパッケージ管理システムの名前に置き換えてください。 -`.bashrc` の設定に関しては[節1.3](#set-up-bashrc)を御覧ください。 +```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) も参考にしていただければ幸いです。 -## 1.2 GitHub Releases から tar をダウンロードして使う† +## 1.2 tar ボールのダウンロード† +GitHub Releases から `ble.sh` の tar ボールをダウンロードすることもできます。 ダウンロード・試用・インストールの方法については各リリースページの説明を御覧ください。 -現在、安定版は開発版に比べてかなり古いので様々な機能が欠けている事にご注意下さい。 +現在、安定版は開発版に比べてかなり古いので様々な機能が欠けていることにご注意下さい。 -- 開発版 [v0.4.0-devel3](https://github.com/akinomyoga/ble.sh/releases/tag/v0.4.0-devel3) (2020-12), [nightly build](https://github.com/akinomyoga/ble.sh/releases/tag/nightly) +- 開発版 [v0.4.0-devel3](https://github.com/akinomyoga/ble.sh/releases/tag/v0.4.0-devel3) (2023-04), [nightly build](https://github.com/akinomyoga/ble.sh/releases/tag/nightly) - 安定版 [v0.3.4](https://github.com/akinomyoga/ble.sh/releases/tag/v0.3.4) (2019-02 fork) 拡張補完 - 安定版 [v0.2.7](https://github.com/akinomyoga/ble.sh/releases/tag/v0.2.7) (2018-03 fork) Vim モード - 安定版 [v0.1.15](https://github.com/akinomyoga/ble.sh/releases/tag/v0.1.15) (2015-12 fork) 構文着色 -## 1.3 `.bashrc` に設定する† +## 1.3 `.bashrc` の設定† 対話シェルで常用する場合には `.bashrc` に設定を行います。 単に `ble.sh` を `source` して頂くだけでも大抵の場合動作しますが、 @@ -361,7 +379,7 @@ Make 変数 `USE_DOC=no` が指定されている場合は、ドキュメント `source /path/to/ble.sh` をシェル関数の中から実行するのは避けて下さい。 この「より確実な設定」が必要になる詳細な条件については [Discussion #254 への回答 (英語)](https://github.com/akinomyoga/ble.sh/discussions/254#discussioncomment-4284757) で説明されています。 -## 1.4 初期化スクリプト `~/.blerc` について +## 1.4 初期化スクリプト `~/.blerc` ユーザー設定は初期化スクリプト `~/.blerc` (またはもし `~/.blerc` が見つからなければ `${XDG_CONFIG_HOME:-$HOME/.config}/blesh/init.sh`) に記述します。 テンプレートとしてリポジトリの [`blerc.template`](https://github.com/akinomyoga/ble.sh/blob/master/blerc.template) というファイルを利用できます。 diff --git a/README.md b/README.md index ca10b35f..fee1ca7a 100644 --- a/README.md +++ b/README.md @@ -127,27 +127,13 @@ 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 -} -``` +For a detailed control of the install locations of the main files, the license +files, and the documentation files, please also check the later sections +[Install](#install) and [Package](#package). -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). +If you want 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`. +Please check [`_package.bash`](#_packagebash) for the details. ## Features @@ -243,7 +229,7 @@ For example, Some of them are summarized on [a wiki page](https://github.com/akinomyoga/ble.sh/wiki/Internals#internal-and-external). -## Disclaimer +## Criticism - †1Q. *It is hard to pronounce "ble-sh". How should I pronounce it?* --- A. The easiest @@ -266,7 +252,7 @@ For example, implementation by external commands are more efficient in specific parts, `ble.sh` will use the external commands there. - †3Q. *Why does `ble.sh` - use `make` to generate the script file? You should not use `make` for a + use `make` to generate the script files? You should not use `make` for a script framework.* --- A. Because it is not a good idea to directly edit a large script file of tens of thousands of lines. I split the codebase of `ble.sh` into source files of reasonable sizes and edit the source files. In @@ -296,7 +282,7 @@ For example, # 1 Usage -## 1.1 Try `ble.sh` generated from source (version ble-0.4 devel)† +## 1.1 Build from source† ### Generate @@ -322,14 +308,41 @@ source out/ble.sh To install `ble.sh` in a specified directory, use `make install`. -```bash -# INSTALL to ~/.local/share/blesh +``` +# INSTALL to ~/.local/share/blesh and ~/.local/share/doc/blesh make install -# INSTALL to a specified directory +# INSTALL into a specified directory make install INSDIR=/path/to/blesh +``` + +The install locations of `ble.sh` and related script files can be specified by +make variable `INSDIR`. The locations of the license files and the +documentation files can be specified by make variables `INSDIR_LICENSE` and +`INSDIR_DOC`, respectively. When `INSDIR` is specified, the default values of +`INSDIR_LICENSE` and `INSDIR_DOC` is `$INSDIR/doc`. When `INSDIR` and later +mentioned `DESTDIR`/`PREFIX` are not specified, the value of `INSDIR` is +`${XDG_DATA_HOME:-$HOME/.local/share}/blesh`, and the default values of +`INSDIR_LICENSE` and `INSDIR_DOC` are +`${XDG_DATA_HOME:-$HOME/.local/share}/doc/blesh`. + +When `USE_DOC=no` is specified, the documentation files are disabled. Also, +the default install location of the license files `INSDIR_LICENSE` is changed +to `$INSDIR`. + +By default, the comment lines and blank lines in the script files are stripped +in the installation process. If you would like to keep these lines in the +script files, please specify the argument `strip_comment=no` to `make`. -# PACKAGE (for package maintainers) - Example 1 +To set up `.bashrc` see [Sec. 1.3](#set-up-bashrc). + +### Package + +Package maintainers may use make variables `DESTDIR` and `PREFIX` to quickly +set up the default values for `INSDIR`, `INSDIR_LICENSE`, and `INSDIR_DOC`. + +```bash +# PACKAGE - Example 1 make install DESTDIR=/tmp/blesh-package PREFIX=/usr/local # PACKAGE - Example 2 @@ -346,31 +359,43 @@ make install USE_DOC=no DESTDIR="$build" PREFIX="$prefix" \ INSDIR_LICENSE="$build/$prefix/share/blesh" ``` -If make variable `DESTDIR` or `PREFIX` is supplied, `ble.sh` and related files -will be copied into `$DESTDIR/$PREFIX/share/blesh`, and the license and -documentation files will be copied into `$DESTDIR/$PREFIX/share/doc/blesh`. -Otherwise, if make variable `INSDIR` is specified, `ble.sh` and related files -will be installed directly in `$INSDIR`, and the license and documentation -files will be copied into `$INSDIR/doc`. If none of these make variables are -defined, `ble.sh` and related files are installed in -`${XDG_DATA_HOME:-$HOME/.local/share}/blesh`, and the license and document -files are installed in `${XDG_DATA_HOME:-$HOME/.local/share}/doc/blesh`. +If make variable `DESTDIR` or `PREFIX` is specified instead of `INSDIR`, the +value of `INSDIR` is set to `$DESTDIR/$PREFIX/share/blesh`, and the default +install locations of the license and documentation files, `INSDIR_LICENSE` and +`INSDIR_DOC`, will be `$DESTDIR/$PREFIX/share/doc/blesh`. -The install locations of the license and documentation files can be overridden -by make variables `INSDIR_LICENSE` and `INSDIR_DOC`. If `USE_DOC=no` is -specified, the documentation files are disabled. +#### `_package.bash` -The comment lines and blank lines in the script files are stripped in the installation process. -If you would like to keep these lines in the script files, please specify the argument `strip_comment=no` to `make`. +When you want 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 a +name representing the package management system): -To set up `.bashrc` see [Sec. 1.3](#set-up-bashrc). +```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 completed, and `ble.sh` will be reloaded automatically. +When the shell function returns exit status 6, the timestamp of `ble.sh` will be checked so `ble.sh` is reloaded only when `ble.sh` is actually updated. +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). -## 1.2 Or, use a tar ball of `ble.sh` obtained from GitHub releases† +## 1.2 Download a tar ball† -For download, trial and install, see the description at each release page. -The stable versions are significantly old compared to the devel version, so many features are unavailable. +You can also download a tar ball of `ble.sh` from GitHub releases. +See each release page for the description of downloading, trial and installation. +Many features are unavailable in the stable versions since they are significantly old compared to the devel version. -- Devel [v0.4.0-devel3](https://github.com/akinomyoga/ble.sh/releases/tag/v0.4.0-devel3) (2020-12), [nightly build](https://github.com/akinomyoga/ble.sh/releases/tag/nightly) +- Devel [v0.4.0-devel3](https://github.com/akinomyoga/ble.sh/releases/tag/v0.4.0-devel3) (2023-04), [nightly build](https://github.com/akinomyoga/ble.sh/releases/tag/nightly) - Stable [v0.3.4](https://github.com/akinomyoga/ble.sh/releases/tag/v0.3.4) (2019-02 fork) Enhanced completions - Stable [v0.2.7](https://github.com/akinomyoga/ble.sh/releases/tag/v0.2.7) (2018-03 fork) Vim mode - Stable [v0.1.15](https://github.com/akinomyoga/ble.sh/releases/tag/v0.1.15) (2015-12 fork) Syntax highlighting diff --git a/docs/ChangeLog.md b/docs/ChangeLog.md index a4a83a0a..85a9e97b 100644 --- a/docs/ChangeLog.md +++ b/docs/ChangeLog.md @@ -55,7 +55,7 @@ - color: adjust default fg values in faces and add `bleopt color_scheme` (requested by mattmc3) `#D2248` e4cce0ea 5f5554a8 `#D2258` d6a38c43 - highlight: add `bleopt highlight_eval_word_limit` (motivated by orionalves) `#D2256` 6833bdf8 - progcomp: support `complete -E` `#D2257` ffac4205 -- make: support make variable `USE_DOC=no` (requested by blackteahamburger) `#D2260` 40fe9c95 +- make: support make variable `USE_DOC=no` (requested by blackteahamburger) `#D2260` 40fe9c95 xxxxxxxx - make: fix condition for the INSDIR_LICENSE rule (reported by Jai-JAP) `#D2260` 5a8dcb4b - edit (`ble/widget/display-shell-version`): print shell options `#D2261` 70b89e5e xxxxxxxx diff --git a/note.txt b/note.txt index cbee07e4..d5569a69 100644 --- a/note.txt +++ b/note.txt @@ -7402,6 +7402,13 @@ bash_tips $(INSDIR_LICENSE)/% に対するルールを独立に定義するかどうかの条件が反転して いた。修正する。 + 2024-08-24 USE_DOC=doc で licence を INSDIR と同じ場所に入れる (requested by blackteahamburger) + https://github.com/akinomyoga/ble.sh/issues/485#issuecomment-2308148791 + うーん。既にインストール先決定が複雑になっていてもっと複雑化して大丈夫なの + か。ユーザー的には色々のオプションを設定した結果としてどうなるのかが予測不 + 能になるのではないか。それだったら明示的に指定する様にするべきなのではない + か。 + * contrib: fzf-menu 修正 (reported by pallaswept) [#D2259] https://github.com/akinomyoga/ble.sh/issues/479#issuecomment-2305871596 Ref: #D2251