Added installation guide

Author: ifTNT

README.md

@@ -1,10 +1,10 @@
 # arduino-cscope-ctags
 
-Generating tags of arduino sketch in one command for code tracing.
+Generating database of cscope/ctags from Arduino sketch in one command for code tracing.
 
 ## Introduction
 
-Arduino is a convenient environment for developing embedding application. Sometimes tracing the code of Arduino core can help us to realize how the lower-level function was implemented and futher assist debugging. However, it's a tough work that tracing code with vanilla Arduino IDE, especially with third party core variants like ESP32.  
+Arduino is a convenient environment for developing embedding application. On the other hand, tracing the code of Arduino core can help us to realize how the lower-level function was implemented and futher assist us in debugging. However, it's a tough work that tracing code with vanilla Arduino IDE, especially with third party core variants like ESP32.  
 Thus, the purpose of this tool is to simplify the work to generate the symbol database of cscope and ctags from Arduino sketch. Once the database is generated, you can begin tracing the code use cscope/ctags with other text editor like vim, emacs, vscode or sublime text.
 
 ## How to use
@@ -13,11 +13,26 @@ clear the cache /tmp/arduino-core-cache
 
 ## How to install
 
-1. Install python3.6, arduino-cli, cscope and ctags via the package manage of your distrubution.
+### Dependencies
+
+This tool depends on python, [arduino-cli](https://github.com/arduino/arduino-cli), [cscope](http://cscope.sourceforge.net/) and [ctags](https://github.com/universal-ctags/ctags).  
+Specifically, this tool was developed and be tested on the following platform.
+
+- ArchLinux 5.11.16-arch1-1
+- Python 3.6
+- Arduino-cli 0.18.3
+- Cscope 15.9
+- Universal Ctags 5.9.0
+
+It shouldn't be any problem if you are using Linux based operating system and python 3.6~3.9. But working on other platform is not guaranteed. If you are encounting any problem to get this tool work, please kindly let me know. The contacting informations are listed below.
+
+### Installing instruction
+
+1. Install python3.6, arduino-cli, cscope and ctags via the package manager of your distrubution.
 2. Download the source code of this project.
 
 ```bash
-git clone https://github.io/ifTNT/arduino-cscope-ctags/arduino-cscope-ctags.git
+git clone https://github.com/ifTNT/arduino-cscope-ctags.git
 cd arduino-cscope-ctags/
 ```
 
@@ -27,19 +42,43 @@ cd arduino-cscope-ctags/
 sudo pip install -r requirements.txt
 ```
 
-4. Copy the executable to the system directory.
+4. Enable executing flag of the main program.
+
+```bash
+chmod +x arduino-cscope-ctags
+```
+
+5. Copy the executable to the system directory.
 
 ```bash
 sudo cp arduino-cscope-ctags /usr/local/bin/
 ```
 
-5. Enjoy hacking!
+6. Enjoy hacking!
 
-### Dependencies
+## Command-line arguments
+
+Usage:
+
+```bash
+arduino-cscope-ctags [-h] [-o DB_OUTPUT] fqbn sketch_path
+```
 
-python 3.6
-arduino-cli 0.18.3
-Universal Ctags 5.9.0
-cscope 15.9
+### Positional arguments
+
+- fqbn : The Fully Qualified Board Name (FQBN) of your target board. It can be obtained by command `arduino-cli board listall`. e.g.: arduino:avr:uno
+- sketch_path : The path to your Arduino sketch. Must containing at least one '.ino' file.
+
+### Optional arguments
+
+- -h, --help : show this help message and exit
+- -o DB_OUTPUT, --db-output DB_OUTPUT
+  - The base output folder related to your sketch directory. Default is the '.tags' folder in your sketch directory.
 
 ## How to contribute
+
+Any contribution are welcomed.  
+If you encounterd some problem, make a issue on GitHub and we will help you as soon as possible.  
+If you have any idea to improve this tool, please let us know through the issue or pull request functionality on GitHub.  
+Cause the tested platforms are limited. If this tool works fine on your platform, please create an issue on GitHub with the detailed version of your platform.  
+You can also contact us via the e-mail _iftnt1999 [at] gmail.com_. We will apprciate if hearing any feedback from you.

arduino-cscope-ctags

@@ -6,6 +6,7 @@ import json
 from pathlib import Path
 import re
 import itertools
+import argparse
 
 # The location to storage intermediate data
 build_temp_dir = Path("/tmp/arduino-cscope-ctags")
@@ -20,15 +21,15 @@ def get_header_list(path):
   files = list(Path(path).rglob(target_file_regex))
   return [get_abs_path(path) for path in files]
 
-def main(board_fqbn, sketch_path):
+def main(board_fqbn, sketch_path, db_output_path):
   # Ensure sketch_path is a path object
   sketch_path = Path(sketch_path)
   # The path of compile commands file generated by arduino-cli
   compile_command_path= build_temp_dir/"compile_commands.json"
   # The intermediate file that storages the list of included files
   including_list_path = build_temp_dir/"includes.list"
   # The target path of tag databases
-  database_path = sketch_path/".tags"
+  database_path = sketch_path/db_output_path
   cscope_database_path = database_path/"cscope.out"
   ctags_database_path = database_path/"ctags"
 
@@ -118,6 +119,14 @@ def main(board_fqbn, sketch_path):
   print("\nAll done successfully\n")
 
 if __name__ == "__main__":
-  board_fqbn = sys.argv[1]
-  sketch_path = sys.argv[2]
-  main(board_fqbn, sketch_path)
+  # Parse the command-line argument
+  parser = argparse.ArgumentParser()
+  parser.add_argument("-o", "--db-output", help="The base output folder related to your sketch directory. Default is the '.tags' folder in your sketch directory.", default=".tags")
+  parser.add_argument("fqbn", help="The Fully Qualified Board Name (FQBN) of your target board. It can be obtained by command `arduino-cli board listall`. e.g.: arduino:avr:uno")
+  parser.add_argument("sketch_path", help="The path to your Arduino sketch. Must containing at least one '.ino' file.")
+  args = parser.parse_args()
+
+  if not Path(args.sketch_path).is_dir():
+    print(f"{args.sketch_path} is not a directory. Please check whether it had been existed.")
+  else:
+    main(args.fqbn, args.sketch_path, args.db_output)