From 9fc5e5493382c71cef04dbec49b32a942fc62581 Mon Sep 17 00:00:00 2001 From: Jasem Mutlaq Date: Tue, 17 Sep 2024 21:02:23 +0300 Subject: [PATCH] Add vscode instructions --- README.md | 102 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 60 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index 2bde161620..80c53e1ad7 100644 --- a/README.md +++ b/README.md @@ -14,16 +14,18 @@ INDI core library is composed of the following components: 1. INDI Server. 2. INDI Core Drivers: Hardware drivers that communicate with the equipment. Many devices are supported including: -+ Mounts -+ CCDs, CMOS, Webcams, DSLRs (Canon, Nikon, Sony, Pentax..etc). -+ Focusers. -+ Filter Wheels. -+ Adaptive Optics. -+ Domes. -+ GPS. -+ Weather Stations. -+ Controllers. -+ Auxiliary Devices (switches, watchdog, relays, light sources, measurement devices..etc). + +- Mounts +- CCDs, CMOS, Webcams, DSLRs (Canon, Nikon, Sony, Pentax..etc). +- Focusers. +- Filter Wheels. +- Adaptive Optics. +- Domes. +- GPS. +- Weather Stations. +- Controllers. +- Auxiliary Devices (switches, watchdog, relays, light sources, measurement devices..etc). + 3. Client Library: Cross-platform POSIX and Qt5-based client libraries. The client libraries can be embedded in 3rd party applications to communicate with INDI server and devices. INDI core device drivers are shipped with INDI library by default. @@ -31,10 +33,11 @@ INDI core device drivers are shipped with INDI library by default. INDI 3rd party drivers are available in a [dedicated 3rdparty repository](https://github.com/indilib/indi-3rdparty) and maintained by their respective owners. Learn more about INDI: -+ [Features](http://indilib.org/about/features.html) -+ [Discover INDI](http://indilib.org/about/discover-indi.html) -+ [Supported Devices](http://indilib.org/devices/) -+ [Clients](http://indilib.org/about/clients.html) + +- [Features](http://indilib.org/about/features.html) +- [Discover INDI](http://indilib.org/about/discover-indi.html) +- [Supported Devices](http://indilib.org/devices/) +- [Clients](http://indilib.org/about/clients.html) # Building @@ -75,27 +78,33 @@ sudo apt-get install -y \ ## XISF Support To enable [XISF format](https://pixinsight.com/xisf/) support in INDI, you need to build or install [libxisf](https://gitea.nouspiro.space/nou/libXISF) package. + ```bash sudo apt-add-repository ppa:mutlaqja/ppa sudo apt-get -y install libxisf-dev ``` ## Create Project Directory + ```bash mkdir -p ~/Projects cd ~/Projects ``` ## Get the code + To build INDI in order to run drivers, then it is recommended to perform a quick shallow clone that will save lots of bandwidth and space: + ```bash git clone --depth 1 https://github.com/indilib/indi.git ``` On the other hand, if you plan to submit a PR or engage in INDI driver development, then getting a full clone is recommended: + ```bash git clone https://github.com/indilib/indi.git ``` + It is worth making your own fork of indi in your own personal repository and cloning from that rather than cloning directly from the root indi. ## Build indi-core (cmake) @@ -131,7 +140,7 @@ You can force skip this test with the `-f` option: ./developer-build.bash -f ``` -Furthermore, this script executes `make` in *parallel* by default. +Furthermore, this script executes `make` in _parallel_ by default. If you are having problems or need to use fewer CPU cores, please adjust using the `-j` option. For example, to disable parallel execution: @@ -156,18 +165,27 @@ cd ~/Projects/indi ## Build indi-core (Qt Creator) -If your are planning to develop using Qt Creator then still follow this process and do a manual build first. Then in QT Creator: -+ Open the project using File - Open File or Project. -+ Navigate to Projects/indi and selec the CMakeLists.txt file. -+ Qt Creator will open your project but will probably configure it incorrectly, select the Projects tab and change to the Projects/build/indi-core directory that you used to do the initial build. The project display may be blank but click on the build button (the geological hammer) anyway. The project should build. +If your are planning to develop using Qt Creator then still follow this process and do a manual build first. Then in QT Creator: + +- Open the project using File - Open File or Project. +- Navigate to Projects/indi and selec the CMakeLists.txt file. +- Qt Creator will open your project but will probably configure it incorrectly, select the Projects tab and change to the Projects/build/indi-core directory that you used to do the initial build. The project display may be blank but click on the build button (the geological hammer) anyway. The project should build. It is very easy to get this process wrong and all sorts of subtle things can happen, such as everything appearing to build but your new functionality not being present. -# Architecture +## Build indi-core (VS Code) +INDI includes a default .vscode directory with default settings for building and launching the project. After opening the project for the first time in VS Code, install all the recommended extensions. You need to also install the following packages: -Typical INDI Client / Server / Driver / Device connectivity: +```bash +sudo apt-get -y install astyle clangd +``` +Enable clangd extension in settings. The default launch script debugs INDI simulator telescope driver. The first driver is also the one that can be debugged. + +# Architecture + +Typical INDI Client / Server / Driver / Device connectivity: INDI Client 1 ----| |---- INDI Driver A ---- Dev X | | @@ -182,8 +200,6 @@ Typical INDI Client / Server / Driver / Device connectivity: Client INET Server UNIX Driver Hardware processes sockets process pipes processes devices - - INDI server is the public network access point where one or more INDI Clients may contact one or more INDI Drivers. indiserver launches each driver process and arranges for it to receive the INDI protocol from clients on its stdin and expects to find commands destined for clients on the driver's stdout. Anything arriving from a driver process' stderr is copied to indiserver's stderr. @@ -191,22 +207,23 @@ INDI server only provides convenient port, fork and data steering services. If d # Support -+ [FAQ](http://indilib.org/support/faq.html) -+ [Forum](http://indilib.org/forum.html) -+ [Tutorials](http://indilib.org/support/tutorials.html) +- [FAQ](http://indilib.org/support/faq.html) +- [Forum](http://indilib.org/forum.html) +- [Tutorials](http://indilib.org/support/tutorials.html) # Development -+ [INDI API](http://www.indilib.org/api/index.html) -+ [INDI Developer Manual](https://docs.indilib.org/) -+ [Tutorials](http://indilib.org/develop/tutorials.html) -+ [Developers Forum](http://indilib.org/forum/development.html) -+ [Developers Chat](https://riot.im/app/#/room/#kstars:matrix.org) -+ Sample drivers are available under examples and drivers/skeleton directories. They can be used as a starting point for your driver development. +- [INDI API](http://www.indilib.org/api/index.html) +- [INDI Developer Manual](https://docs.indilib.org/) +- [Tutorials](http://indilib.org/develop/tutorials.html) +- [Developers Forum](http://indilib.org/forum/development.html) +- [Developers Chat](https://riot.im/app/#/room/#kstars:matrix.org) +- Sample drivers are available under examples and drivers/skeleton directories. They can be used as a starting point for your driver development. ### Code Style -INDI uses [Artistic Style](http://astyle.sourceforge.net) to format all the C++ source files. Please make sure to apply the following astyle rules to any code that is submitted to INDI. On Linux, you can create ***~/.astylerc*** file containing the following rules: +INDI uses [Artistic Style](http://astyle.sourceforge.net) to format all the C++ source files. Please make sure to apply the following astyle rules to any code that is submitted to INDI. On Linux, you can create **_~/.astylerc_** file containing the following rules: + ``` --style=allman --align-reference=name @@ -226,6 +243,7 @@ Some IDEs (e.g. QtCreator) support automatic formatting for the code everytime y [How to contribute to INDI full guide](http://indilib.org/develop/tutorials/181-how-to-contribute-to-indi-github-development.html) Here is the short version on how to submit a PR: + 1. Login with a Github account and fork the official INDI repository. 2. Clone the official INDI repository and add the forked INDI repository as a remote (git remote add ...). 3. Create a local Git branch (git checkout -b my_branch). @@ -234,21 +252,21 @@ Here is the short version on how to submit a PR: 6. Go to the official repo's github website in a browser, it will popup a message to create a PR. Create it. 7. Pushing updates to the PR: just update your branch (git push -f my_fork my_branch:my_branch).. -If you would like to make cleaner PR (recommended!) please read this [tutorial](https://blog.adamspiers.org/2015/03/24/why-and-how-to-correctly-amend-github-pull-requests/) and follow it. The best way is to keep *one logical change per commit* and not pollute the history by multiple small fixes to the PR. +If you would like to make cleaner PR (recommended!) please read this [tutorial](https://blog.adamspiers.org/2015/03/24/why-and-how-to-correctly-amend-github-pull-requests/) and follow it. The best way is to keep _one logical change per commit_ and not pollute the history by multiple small fixes to the PR. ### Driver Documentation When submitting a new driver, the driver user **documentation** is required as part of the submission process. -* Installation: Driver name, executable name, version, required INDI version. -* Features: What features does it support exactly? -* Operation: How to operate the driver? Each sub section should come with a screen shot of the various tabs..etc. +- Installation: Driver name, executable name, version, required INDI version. +- Features: What features does it support exactly? +- Operation: How to operate the driver? Each sub section should come with a screen shot of the various tabs..etc. Preferably annotated to make it easier for new users to follow. - * Connecting: How to establish connection? How to set port if any? - * Main Control: Primary control tab and its functions. - * Options: Explanation for the various options available. - * Etc: Any other tabs created by the driver. -* Issues: Any problems or issues or warnings the users should be aware about when using this driver. + - Connecting: How to establish connection? How to set port if any? + - Main Control: Primary control tab and its functions. + - Options: Explanation for the various options available. + - Etc: Any other tabs created by the driver. +- Issues: Any problems or issues or warnings the users should be aware about when using this driver. ### Sample Drivers