Add document for debug and tests.

README.md

@@ -9,7 +9,7 @@
 ![GitHub all releases](https://img.shields.io/github/downloads/nao1215/mimixbox/total)
 ![Lines of code](https://img.shields.io/tokei/lines/github/nao1215/mimixbox?style=plastic)
 
-[[日本語](docs/introduction/ja/README.ja.MD)]
+[[日本語](docs/introduction/ja/README.MD)]
 # MimixBox - mimic BusyBox on Linux
 MimixBox has many Unix commands in the single binary like BusyBox. However, MimixBox aim for the different uses from BusyBox. Specifically, it is supposed to be used in the desktop environment, not the embedded environment.  
 Also, the MimixBox project maintainer plan to have a wide range of built-in commands (applets) from basic command provided by Coreutils and others to experimental commands.
@@ -61,7 +61,7 @@ $ cd mimixbox
 $ make build
 ```
 
-# Debugging
+# [Debugging](docs/introduction/en/DebugAndTest.md)
 ## How to create docker environment
 ```
 $ make docker
@@ -88,7 +88,7 @@ Now, MimixBox has not implemented enough commands ([currently supported command
 
 Then increase the command options to the same level as Coreutils and other packages. Note that MimixBox does not aim to create commands equivalent to Coreutils. However, we think it's better to have the options that Linux users expect.
 
-Finally, it's the phase that makes the Mimix Box unique. Extend commands to high functionality, like bat and lsd, which are reimplementations of cat and ls.
+Finally, it's the phase that makes the Mimix Box unique. Extend commands to high functionality, like [bat](https://github.com/sharkdp/bat) and [lsd](https://github.com/Peltoche/lsd), which are reimplementations of cat and ls.
 
 # Original commands in MimixBox
 MimixBox has its own commands that don't exist in packages like Coreutils.
@@ -103,9 +103,7 @@ MimixBox has its own commands that don't exist in packages like Coreutils.
 If you would like to send comments such as "find a bug" or "request for additional features" to the developer, please use one of the following contacts.
 
 - [GitHub Issue](https://github.com/nao1215/mimixbox/issues)
-- [mail@Naohiro CHIKAMATSU]([email protected])
 - [Twitter@mimixbox156](https://twitter.com/mimixbox156) ※ MimixBox project information
-- [Twitter@ARC_AED](https://twitter.com/ARC_AED) ※ Author
 
 # LICENSE
 The MimixBox project is licensed under the terms of the MIT license and Apache License 2.0.  

docs/introduction/en/DebugAndTest.md

@@ -0,0 +1,110 @@
+# Purpose of this document
+This document describes how to safely debug MimixBox and add tests. As a prerequisite, you had better not fully install MimixBox in your development environment until Version 1.0.0. As of November 2021, MimixBox has not been fully tested.  
+
+If MimixBox is used with Coreutils or BusyBox on the system, the system does not work properly.
+
+# Debugging environment (Dog fooding environment)
+MimixBox is safe to execute commands within the Docker environment. In [Current Docker Preferences] (../../../Dockerfile), all MimixBox built-in commands are symbolically linked under /usr/local/bin. If you add any command, follow the procedure below to check the operation.
+```
+$ make docker
+$ (here, in Docker) 
+```
+Bash is used in Docker because the MimixBox shell is incomplete. You can also check which command has been replaced by MimixBox with the following command.
+```
+$ mimixbox --list
+```
+
+# Unit Test
+Unit tests are created according to the manners of the golang language. In other words, "target.go" and "target_test.go" exist in the same directory as shown in the directory structure below.
+```
+   └── lib
+       ├── file.go
+       ├── file_test.go
+```
+The MimixBox project does not aim for 100% unit test coverage. However, since the MimixBox library (mimixbox/internal/lib) has a lot of general-purpose code, I want to have 100% coverage as much as possible.
+
+Unit tests can be easily run with the make command.
+```
+$ make ut
+```
+In the MimixBox project, if "$ git push" is detected, GitHub Action is running the unit test. Therefore, we recommend that you run unit tests before pushing your code.
+
+# Integration Test
+In the integration test, check the behavior of each command in [ShellSpec] (https://github.com/shellspec/shellspec). The test code is stored under the test directory.
+```
+test/
+├── it
+│   └── shellutils
+│       └── echoTest.sh  ※ Definition of shell script function for unit test 
+├── spec
+│   ├── echo_spec.sh     ※ Unit test expectations
+│   └── spec_helper.sh
+└── ut
+```
+Like the unit test, the integration test can be easily executed with the make command (GitHub Action is also used).
+```
+$ make it
+```
+However, running the make command in an environment where MimixBox is not installed is only a Coreutils test. After confirming that the integration test works in the HOST environment, finally run it in the Docker environment.
+```
+$ make docker
+
+$ ls           ※ here, in docker
+do_integration_test.sh  integration_tests   ※ Test file copied from HOST environment
+
+$ ./do_integration_test.sh   ※ Integration test execution
+Running: /bin/sh [sh]
+......
+
+Finished in 0.07 seconds (user 0.05 seconds, sys 0.02 seconds)
+6 examples, 0 failures
+```
+
+# When installing MimixBox in the HOST environment
+## Proper use of installation options
+MimixBox has two options for creating symbolic links to built-in commands.   
+
+The first is the --install option. MimixBox does not create a symbolic link if a command with the same name exists on the system. --install was introduced as a safe install based on the experience of breaking the system in the past.
+```
+$ sudo mimixbox --install /usr/local/bin
+```
+The second is the --full-install option. Create symbolic links for all commands, regardless of system state. This option is deprecated at this stage.
+```
+$ sudo mimixbox --full-install /usr/local/bin
+```
+## If the system breaks (e.g. GUI does not start)
+You need to remove the MimixBox symlinks from your system. The specific procedure is as follows.  
+
+1. PC power off
+2. Start in rescue mode
+3. Execute "$ sudo mimixbox --remove $(directory where symbolic links exist)" 
+   e.g. sudo mimixbox --remove /usr/local/bin
+4. Reboot
+```
+$ sudo ./mimixbox --remove /usr/local/bin/
+Delete symbolic link: /usr/local/bin/fakemovie
+Delete symbolic link: /usr/local/bin/mbsh
+Delete symbolic link: /usr/local/bin/path
+Delete symbolic link: /usr/local/bin/serial
+Delete symbolic link: /usr/local/bin/sh
+Delete symbolic link: /usr/local/bin/true
+Delete symbolic link: /usr/local/bin/which
+Delete symbolic link: /usr/local/bin/cat
+Delete symbolic link: /usr/local/bin/echo
+Delete symbolic link: /usr/local/bin/false
+Delete symbolic link: /usr/local/bin/ghrdc
+Delete symbolic link: /usr/local/bin/mkdir
+```
+If possible, please report the bug to [MimixBox Issues] (https://github.com/nao1215/mimixbox/issues).
+
+# Logging in MimixBox (under consideration)
+Since the operation of MimixBox is unstable, we are considering the logging function.  
+
+If MimixBox operates stably in the future, it is possible that multiple users will execute MimixBox built-in commands at the same time. In that case, multiple processes (MimixBox) write to one log file at the same time. Due to the simultaneous writing, there is no guarantee that the logs will be written to the log file as expected.  
+
+Therefore, each process is considering the specification to write a log to the named pipe. Writes to named pipes are atomic if they are less than or equal to PIPE_BUF size and log messages do not conflict (do not mix).  
+
+The log size of MimixBox is assumed to be smaller than PIPE_BUF (minimum 512Byte), and it is guaranteed to be highly atomic. A dedicated logging daemon is responsible for reading logs and writing to log files.
+![MimixBox logging flow](/docs/images/debug_logging.jpg "MimixBox logging flow")
+
+It is a slightly exaggerated design, and there is a problem in recovery when the logging daemon suddenly dies. Therefore, we are also considering how to create a log file for each user.  

docs/introduction/ja/DebugAndTest.md

@@ -0,0 +1,111 @@
+# 本ドキュメントの目的
+本ドキュメントでは、MimixBoxを安全にデバッグし、どのようにテストを追加するかを説明します。前提として、Version1.0.0となるまでMimixBoxを開発環境にフルインストールしてはいけません。2021年11月現在では、MimixBoxはテストが不十分です。
+
+MimixBoxがシステム上のCoreutilsやBusyBoxを差し置いて使用された場合、システムが不安定な動作をする可能性があります。
+
+# デバッグ環境（ドッグフーディング環境）
+MimixBoxは、Docker環境内でコマンドを実行するのが安全です。[現在のDocker環境設定](../../../Dockerfile)では、MimixBox組み込みコマンドの全てが/usr/local/bin以下にシンボリックリンクされます。何らかのコマンドを追加した場合、以下の手順で動作確認してください。
+
+```
+$ make docker
+$ (ここからDocker環境) 
+```
+MimixBoxシェルが未完成のため、Docker内ではBashを使用しています。また、どのコマンドがMimixBoxによって置き換えられているかは、以下のコマンドで確認できます。
+```
+$ mimixbox --list
+```
+
+# 単体テスト
+単体テストは、golang言語の作法に則って作成しています。つまり、以下に示すディレクトリ構成のように、「テスト対象.go」と「テスト対象_test.go」が同じディレクトリ階層に存在します。
+```
+   └── lib
+           ├── file.go
+           ├── file_test.go
+```
+MimixBoxプロジェクトでは、単体テストカバレッジ100%を目指してはいません。ただし、MimixBoxライブラリ（mimixbox/internal/lib）は汎用的なコードが多いため、可能な限りカバレッジ100%にしたい気持ちがあります。  
+
+単体テストは、makeコマンドで簡単に実行できます。
+```
+$ make ut
+```
+MimixBoxプロジェクトでは、"$ git push"を検知した場合、GitHub Actionで単体テストを実行しています。そのため、コードをpushする前に、単体テストを実行する事をオススメします。
+
+# 結合テスト
+結合テストでは、[ShellSpec](https://github.com/shellspec/shellspec)で各コマンドの振る舞いを確認します。テストコードは、testディレクトリ以下に格納しています。
+```
+test/
+├── it
+│      └── shellutils
+│               └── echoTest.sh  ※ テスト用のシェルスクリプト関数定義
+├── spec
+│      ├── echo_spec.sh     ※ テスト期待値を定義
+│      └── spec_helper.sh
+└── ut
+```
+結合テストも単体テスト同様、makeコマンドで簡単に実行できます（GitHub Actionを使っている所も同様です）
+```
+$ make it
+```
+ただし、MimixBoxがインストールされていない環境でmakeコマンドを実行しても、Coreutilsのテストにしかなりません。統合テストがHOST環境で動作することが確認できたら、最後にDocker環境で実行してください。
+```
+$ make docker
+
+$ ls           ※ ここからDocker環境
+do_integration_test.sh  integration_tests   ※ HOST環境からコピーされたテストファイル
+
+$ ./do_integration_test.sh   ※ 統合テスト実行
+Running: /bin/sh [sh]
+......
+
+Finished in 0.07 seconds (user 0.05 seconds, sys 0.02 seconds)
+6 examples, 0 failures
+```
+
+# HOST環境にMimixBoxをインストールする場合
+## インストールオプションの使い分け
+MimixBoxは、組み込みコマンドに対するシンボリックリンクを作成するオプションを2つ提供します。  
+
+1つ目は、--installオプションです。同名のコマンドがシステムに存在する場合、MimixBoxはシンボリックリンクを作成しません。--installは、過去にシステムを壊した経験から、安全インストールとして導入しました。
+```
+$ sudo mimixbox --install /usr/local/bin
+```
+2つ目は、--full-installオプションです。システムの状態に関わらず、全コマンドのシンボリックリンクを作成します。現段階ではこちらのオプションは、非推奨です。
+```
+$ sudo mimixbox --full-install /usr/local/bin
+```
+## システムが壊れた場合（例：GUIが起動しない等）
+MimixBoxのシンボリックリンクをシステムから取り除く必要があります。具体的な手順は、以下の通りです。  
+
+1. PCの電源OFF
+2. レスキューモードで起動
+3. $ sudo mimixbox --remove $(シンボリックリンクが存在するディレクトリ)を実行。  
+   例：sudo mimixbox --remove /usr/local/bin
+4. 再起動
+```
+$ sudo ./mimixbox --remove /usr/local/bin/
+Delete symbolic link: /usr/local/bin/fakemovie
+Delete symbolic link: /usr/local/bin/mbsh
+Delete symbolic link: /usr/local/bin/path
+Delete symbolic link: /usr/local/bin/serial
+Delete symbolic link: /usr/local/bin/sh
+Delete symbolic link: /usr/local/bin/true
+Delete symbolic link: /usr/local/bin/which
+Delete symbolic link: /usr/local/bin/cat
+Delete symbolic link: /usr/local/bin/echo
+Delete symbolic link: /usr/local/bin/false
+Delete symbolic link: /usr/local/bin/ghrdc
+Delete symbolic link: /usr/local/bin/mkdir
+```
+余力があれば、[MimixBoxのIssues](https://github.com/nao1215/mimixbox/issues)にバグ報告をお願いします。
+
+# MimixBoxにおけるロギング（検討中）
+MimixBoxは動作が不安定な状態なので、ロギング機能を検討しています。  
+
+将来的にMimixBoxが安定動作すれば、複数ユーザがMimixBox組み込みコマンドをほぼ同時に実行する可能性が考えられます。その場合、複数プロセス（MimixBox）が、同時に一つのログファイルに対して書き込みを行います。同時書き込みであるため、ログファイルへログが期待通りに書き込まれるかどうかは保証されません。  
+
+そこで、各プロセスは名前付きパイプにログを書き込む仕様を検討しています。名前付きパイプへの書き込みは、PIPE_BUFサイズ以下の書き込みであればアトミックであり、ログメッセージが競合しません（混ざりません）。  
+
+MimixBoxのログサイズは、PIPE_BUF（最低512Byte）を下回る想定であり、アトミック性が高い確率で保証されます。ログ読み込みとログファイルへの書き込みは、ロギング専用のデーモンが行います。
+![MimixBoxロギングの流れ](/docs/images/debug_logging.jpg "MimixBoxロギングの流れ")
+
+やや大げさな設計であり、ロギングデーモンが突然死した場合などの復旧に課題があります。そのため、ログファイルをユーザ単位で作成する方法も検討しています。