.. highlight:: shell ***************************** C/C++ Development Environment ***************************** Summary ======= Under Windows Install the toolchain under WSL; Use any code editor; Compile and run in WSL bash window; Transfer to the SSH server for an optional final test. **Avoid MinGW (including git bash) or use it at your own risk!** For more detail, read `Windows 1x Local`_ section. In the classrooms, you can install WSL, VS Code and Windows Terminal in the Microsoft Store. Do not install in the Power Shell or use installers, which may require an administrator account. Under Mac OS Install **X-Code command line tool** as your toolchain; Use any code editor; Compile and run in your terminal; Transfer to the SSH server for an optional final test. For more detail, read `Mac OS Local`_ section. Under Linux Install the toolchain; Use any code editor; Compile and run in your terminal; Transfer to the SSH server for an optional final test. For more detail, read `Linux Local`_ section. In Browser Use Codespaces for programming project. No installation is required. Your project should be hosted on GitHub.com as a repository first. Launch it directly from GitHub. SSH Server (CS department) The SSH server offered by the Department of Computer Science is intended for testing purposes when your local environment is not trustworthy (e.g. MinGW or CygWin). Single-Click-Run Feature Single-click-run features in certain text editors such as jGrasp, onlineGDB, and the VS Code run/debug feature may not support make, making them unsuitable for multi-file projects. While these editors can still be used for editing, avoid using them to run your project with a single mouse click. Unless you are willing to invest time into configuring them correctly, this is likely to lead to errors. Furthermore, this approach can be inconvenient, as you may need to reconfigure the settings for each new project. Concepts ======== .. glossary:: Command-line Interface (CLI) The Command-line interface (CLI) let user to process commands (computer applications) as lines of texts. Almost all operating systems provide CLIs. It has many advantages for programmers and are exclusively used to control remote computer through networks. Among the many CLI environments available, we stick to **bash** as our CLI shell. Command-line Command A command-line command is an executable that can be invoked in the CLI environment (a terminal/console). A typical command contains the path to the executable followed by with arguments and options. Command Arguments and Options (g++) Given an example command: ``g++ -g -o main main.cpp``. An argument is a positional parameter provided in a command like ``main.cpp`` in the example. An option is a parameter in the form like either ``-o main`` (with an option argument) or ``-g`` (without option argument). Options can also start with ``--`` such as ``--help``. Bash Bash is a unix shell to support the usage of CLI commands. It is also a language to allow shell programming. It is the default shell in most Linux distributions and some versions of Mac OS. Executable It is also know as "executable file", or "binary". An executable refers to a file that can be invoked to perform certain tasks on a computer. It can be hard-coded in machine language but are mostly compiled from the source code in high-level programming languages such as C++. Source Code Source code files of high-level programming languages are mostly just plain text files. They are human-readable files that can be translated to executables in machine language. As plain text files, you can used any text editor to work with them. Toolchain The tools required to generate executables from source code files are known as **toolchain**. Minimal System Requirements =========================== To work on a C++ programming project, the minimal requirements of the development environment are: 1. An editor to edit the source code files 2. A toolchain to build executables or libraries from the source code files The two parts are independent of each other. They can even exist on different computers. For instance, you can edit source codes on your laptop, transfer file to the remote Linux server, build and run your code there. SSH Linux Server ================ The Computer Science department provides every student the access to the Linux server through SSH. All tools required to compile and build C++ projects are pre-installed. Students can connect to the server and use the toolchain without any local installation. Read the :doc:`document` for more details. It is optional when you have a good local environment. .. important:: **MinGW user should always test your code on the SSH server before submitting your work for grading.** Local Development Environment ============================= Installing your own local development environment is **highly recommended** for the following reasons: #. Convenience: no need to transfer files to the SSH server every time to compile and run. #. Learning purpose: gain better understanding of the environment though the installation, configuration and execution processes. The following list of tools applies to the courses using C or C++ as the main programming language. .. glossary:: GCC (GNU Compiler Collection) A collection of compilers from GNU to compile many languages including C, C++, Objective-C, Fortran, Ada and Go. gcc The GNU C compiler invocation command. Usually used to compile pure C or C/C++ hybrid projects. Not required for courses focusing on C++. g++ The GNU C++ compiler invocation command. Employed to compile pure C++ projects. make The GNU building tool to produce executables and libraries. Also used in task automation. ssh The secure shell command to access remote computer system through a command-line interface. Linux The open-source operating system. Many Linux distributions are available. Ubuntu 22.04 is employed for demonstration in most courses. WSL The Windows Subsystem for Linux. It allows students to use Linux environment under the Windows operating system. Editor/IDE Any tool to be used to edit text files. Choose your preferred one. Visual Studio Code is used for demonstration in the classroom. git The distributed version control system to manage source code or other files. Optional to classes not using GitHub Classroom. valgrind A CLI tool for profiling and diagnosis of C/C++ programs. It is usually used to check memory problem in the courses. It has known installation problem under Mac OS. Editor vs IDE ============= A pure editor has no knowledge of the toolchain. It makes the setup easier. A programmer's editor can provide many functionalities but will not be as feature-rich as a professional IDE. On the contrast, an IDE can be more powerful than an editor. However, to use the full power of an IDE, you must let the IDE know where to find your toolchain. The configuration step can be challenging for beginners. It is less flexible for this reason. It is also hard to use in grading as the mandatory creation of project structures is redundant in a typical grading process. .. warning:: Be aware of the compatibility issues! Some IDEs use headers or compilers that are not compatible to the GNU toolchain we use in the course. You will experience huge problem if you do not handle it correctly. In classroom demonstration will use **Visual Studio Code** as editor and **g++/make under WSL/Linux/Mac OS** as the toolchain. .. warning:: For VS Code user, you only need the C/C++ plugin from Microsoft. Install other plugins at your own risk. They need some learning to work. Toolchain Installation ====================== The setups are tightly coupled to the workflow you follow. They can be categorized by the location of the toolchain and the operating system you use. Remote ------ A remote toolchain exists on a remote computer that you can access through internet. The SSH server from the CS department is one example. Windows remote desktop is another example. To work with a remote toolchain. You need a software to manipulate the remote computer. It can be either text based, like the SSH connection to the Linux server, or GUI based, like remote desktop or TeamViewer. **No installation of toolchain is necessary** because they are pre-installed on the server. Students need to learning how to access the server and work remotely. We will focus on the Linux server from the CS department accessible through SSH in this document because it is employed as the **final/official** environment in our courses. A separate tutorial discussing the usage of the Linux server using SSH is available: :doc:`/course/cs-ssh-server` The major drawback using a remote toolchain is that all your files are compiled on the remote server. You will need either edit it remotely using a command-line based editors like ``vim`` or constantly transfer file back and forth whenever any changes are made on your local computer. Some editors/IDEs support the edition of remote files in the same way as local files. It is very convenient. However, the setup and configuration are not always working and can be challenging to most students. .. note:: Ever since WSL was added to Windows and used in my courses, the SSH server become less important. You can finish projects without the server as long as you have a working local environment. Online ------ There are online development environments that allow you to write and run code in your web browser. The zyLib used on zyBooks.com is one example. The onlinegdb.com is another example. You can input code in the text area input box in a webpage or upload your source code and your code will be compiled and executed on the server. It is a special type of remote server. This method has minimal requirement from students as they just need a web browser to use it. The drawbacks are: 1. the management of multi-file projects can be complicated or impossible; 2. do not have functionalities like git and make. However, Codespaces as a powerful online development environment is capable of handling multi-file projects. It is recommended in this course for students who have problem using their local environment. Windows 1x Local ---------------- To have the most compatible toolchain working on Windows, the **Windows Subsystem for Linux (WSL)** is preferred over MinGW or CygWin. To set up WSL and related tools: 1. Install WSL (e.g. Ubuntu 22.04 LTS) from the **Microsoft Store** 2. Run for the first time: Setup username and password 3. Update the software management system:: sudo apt update 4. Install common building tools including g++, and make:: sudo apt install build-essential 5. If git is required (DSA 1, 2 for example), install git:: sudo apt install git .. warning:: MinGW (include Git Bash) or Cygwin will cause many compatibility issues. Use them only if you are confident to be able to solve all the compatibility problems by yourself. It usually not worth the effort. To use WSL, open a shell/terminal/console window. Several options to do that. + Install the new ``Windows Terminal`` in the Microsoft Store and use it with WSL. This is by far the best terminal you can get on Windows. + Find ``Ubuntu 22.04`` app in the start menu to start a Ubuntu bash shell. + Open the built-in terminal of the editor you use Known problems: + ``WslRegisterDistribution failed with error:`` * Reason 1: Home edition of Windows 10/11 may not have that feature. * Reason 2: You may need to enable hardware virtualization on Windows. Google "enable hyper-v" topic for solutions Mac OS Local ------------ The easiest way to install the toolchain on Mac OS is to install the **XCode Command line tool** in the Terminal:: sudo xcode-select --install The ``git`` command line tool is usually pre-installed on Mac OS. .. note:: You will be asked for your password and then you may see a popup dialog to confirm. To use the command-line environment, use the default ``Terminal`` app. Type the command ``bash`` to switch to bash if your default shell is zsh. The ``valgrind`` tool has no Mac OS native version available. You may use Homebrew to install a third-party version but the installation is not always working. You may need to use the SSH server to run valgrind in this case. Linux Local ----------- 1. Update the software management system:: sudo apt update 2. Install common building tools including g++, and make:: sudo apt install build-essential 3. If git is required (DSA 1, 2 for example), install git:: sudo apt install git To use the command-line environment, use the default ``Terminal`` app. Extended reading ================ + :doc:`/cpp/building/gpp` + :doc:`/tools/make`