├── .gitignore ├── LICENSE ├── Makefile ├── README.md ├── _static ├── analytics.js ├── clion.png ├── editors.jpg ├── git-tutorial.zip ├── linux-tutorial-files.zip ├── sublime.png └── vscode.png ├── about ├── acknowledgements.rst ├── getting-help.rst ├── github_issue.png └── issue.rst ├── conf.py ├── environment ├── environment.rst ├── ssh-img │ ├── install-ssh-mac-1.png │ ├── install-ssh-mac-2.png │ ├── install-ssh-win10-1.png │ ├── install-ssh-win10-10.png │ ├── install-ssh-win10-2.png │ ├── install-ssh-win10-3.png │ ├── install-ssh-win10-4.png │ ├── install-ssh-win10-5.png │ ├── install-ssh-win10-6.png │ ├── install-ssh-win10-7.png │ ├── install-ssh-win10-8.png │ ├── install-ssh-win10-9.png │ ├── linux-terminal.png │ ├── macos-terminal.png │ └── windows-command-prompt.png └── ssh.rst ├── getting-help ├── office-hours.rst └── questions.rst ├── index.rst ├── requirements.txt ├── style-guide ├── c.rst └── python.rst ├── teams.rst ├── tutorials ├── .gitignore ├── acknowledgements.rst ├── files │ ├── git-tutorial │ │ ├── hello.py │ │ └── hola.py │ └── linux-tutorial-files │ │ ├── .heythere │ │ ├── Hello.java │ │ ├── hello.c │ │ ├── hello.cpp │ │ ├── hello.py │ │ ├── my-input.txt │ │ ├── my_echo.py │ │ └── test.txt ├── filesystem.username.svg ├── git-advanced.rst ├── git-basics.rst ├── git-branches-2.png ├── git-branches-3.png ├── git-branches.png ├── git-branches.rst ├── git-commit-log.rst ├── git-discarding-changes.rst ├── git-intro.rst ├── git-local.rst ├── git-multiple-locations.rst ├── git-prepare-github.rst ├── git-remote.rst ├── img │ ├── git-local-1.png │ ├── git-local-2.png │ ├── git-local-3.png │ ├── git-local-4.png │ ├── git-local-5.png │ ├── github-git-tutorial-1.png │ ├── github-git-tutorial-2.png │ ├── github-git-tutorial-3.png │ ├── github-git-tutorial-4.png │ ├── github-git-tutorial-5.png │ ├── github-git-tutorial-6.png │ ├── github-git-tutorial-7.png │ ├── github-ssh-key.png │ └── new-repository.png ├── linux-advanced.rst ├── linux-basics.rst ├── linux-compile-and-run.rst ├── linux-filesystem.rst ├── linux-input-output.rst ├── linux-intro.rst ├── linux-man.rst ├── linux-permissions.rst ├── linux-sequence.rst ├── linux-tip-tricks.rst ├── nano.png ├── ubuntu-3x3.png └── ubuntu-vscode-1.png └── vscode ├── about.rst ├── code-img ├── connect-1.png ├── connect-10.png ├── connect-11.png ├── connect-2.png ├── connect-3.png ├── connect-4.png ├── connect-5.png ├── connect-5a.png ├── connect-6.png ├── connect-7.png ├── connect-8.png ├── connect-9.png ├── detect-indentation.png ├── four-spaces.png ├── git-disable-1.png ├── git-disable-2.png ├── install-code-deb-1.png ├── install-code-deb-2.png ├── install-code-mac-1.png ├── install-code-mac-2.png ├── install-code-win-1.png ├── install-code-win-2.png ├── install-ext-1.png ├── install-ext-2.png ├── install-ext-3.png ├── install-ext-4.png ├── ruler-1.png ├── ruler-2.png ├── setup-1.png ├── setup-2.png ├── setup-3.png ├── setup-4.png ├── spaces-for-tab.png ├── ssh-1.png ├── ssh-2.png └── vscode-settings.png ├── config.rst ├── install.rst ├── ssh.rst └── tips.rst /.gitignore: -------------------------------------------------------------------------------- 1 | _build 2 | .idea 3 | .DS_Store 4 | venv -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Copyright (c) 2022-2023, The University of Chicago 2 | All rights reserved. 3 | 4 | Redistribution and use in source and binary forms, with or without 5 | modification, are permitted provided that the following conditions are met: 6 | 7 | - Redistributions of source code must retain the above copyright notice, 8 | this list of conditions and the following disclaimer. 9 | 10 | - Redistributions in binary form must reproduce the above copyright notice, 11 | this list of conditions and the following disclaimer in the documentation 12 | and/or other materials provided with the distribution. 13 | 14 | - Neither the name of The University of Chicago nor the names of its 15 | contributors may be used to endorse or promote products derived from this 16 | software without specific prior written permission. 17 | 18 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 19 | AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20 | IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21 | ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 22 | LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23 | CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24 | SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25 | INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26 | CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27 | ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28 | POSSIBILITY OF SUCH DAMAGE. 29 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | # Minimal makefile for Sphinx documentation 2 | # 3 | 4 | # You can set these variables from the command line, and also 5 | # from the environment for the first two. 6 | SPHINXOPTS ?= 7 | SPHINXBUILD ?= sphinx-build 8 | SOURCEDIR = . 9 | BUILDDIR = _build 10 | 11 | # Put it first so that "make" without argument is like "make help". 12 | help: 13 | @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 14 | 15 | .PHONY: help Makefile 16 | 17 | _static/linux-tutorial-files.zip: tutorials/files/linux-tutorial-files/* 18 | (cd tutorials/files/; zip -r ../../_static/linux-tutorial-files.zip linux-tutorial-files/;) 19 | 20 | tutorials/files/linux-tutorial-files/*: 21 | @: 22 | 23 | _static/git-tutorial.zip: tutorials/files/git-tutorial/* 24 | (cd tutorials/files/; zip -r ../../_static/git-tutorial.zip git-tutorial/;) 25 | 26 | tutorials/files/git-tutorial/*: 27 | @: 28 | 29 | # For the deploy target to work, a worktree must be created 30 | # in _build/html that tracks the gh-pages branch. You can do 31 | # so by running this from a freshly cloned version of the repo: 32 | # 33 | # git worktree add -B gh-pages _build/html origin/gh-pages 34 | 35 | deploy: _static/linux-tutorial-files.zip _static/git-tutorial.zip 36 | echo gitdir: $(shell pwd)/.git/worktrees/html > $(BUILDDIR)/html/.git 37 | touch $(BUILDDIR)/html/.nojekyll 38 | git --work-tree=$(BUILDDIR)/html/ --git-dir=$(BUILDDIR)/html/.git stash --include-untracked 39 | git --work-tree=$(BUILDDIR)/html/ --git-dir=$(BUILDDIR)/html/.git pull 40 | git --work-tree=$(BUILDDIR)/html/ --git-dir=$(BUILDDIR)/html/.git checkout stash -- . 41 | git --work-tree=$(BUILDDIR)/html/ --git-dir=$(BUILDDIR)/html/.git add -A . 42 | git --work-tree=$(BUILDDIR)/html/ --git-dir=$(BUILDDIR)/html/.git commit -m"Updated website" 43 | git --work-tree=$(BUILDDIR)/html/ --git-dir=$(BUILDDIR)/html/.git push origin gh-pages 44 | 45 | # Catch-all target: route all unknown targets to Sphinx using the new 46 | # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). 47 | %: Makefile 48 | @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 49 | 50 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | ## Building 2 | 3 | First, install the dependencies: 4 | 5 | pip3 install -r requirements.txt 6 | 7 | Next, build like this: 8 | 9 | make html 10 | 11 | The HTML version of the guide will be in `_build/html/` -------------------------------------------------------------------------------- /_static/analytics.js: -------------------------------------------------------------------------------- 1 | window.dataLayer = window.dataLayer || []; 2 | function gtag(){dataLayer.push(arguments);} 3 | gtag('js', new Date()); 4 | 5 | gtag('config', 'G-MRE434GGPY'); -------------------------------------------------------------------------------- /_static/clion.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/_static/clion.png -------------------------------------------------------------------------------- /_static/editors.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/_static/editors.jpg -------------------------------------------------------------------------------- /_static/git-tutorial.zip: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/_static/git-tutorial.zip -------------------------------------------------------------------------------- /_static/linux-tutorial-files.zip: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/_static/linux-tutorial-files.zip -------------------------------------------------------------------------------- /_static/sublime.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/_static/sublime.png -------------------------------------------------------------------------------- /_static/vscode.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/_static/vscode.png -------------------------------------------------------------------------------- /about/acknowledgements.rst: -------------------------------------------------------------------------------- 1 | .. _about_acknowledgements: 2 | 3 | Acknowledgements 4 | ================ 5 | 6 | While this guide includes plenty of original content, it 7 | also incorporates documentation that was originally written 8 | for several Computer Science courses at the University of 9 | Chicago, and has been edited and improved over the course 10 | of many years by instructors, TAs, and students. 11 | 12 | The following people have directly or indirectly 13 | contributed to this guide: 14 | 15 | .. hlist:: 16 | :columns: 2 17 | 18 | * Víctor Almaraz Argueta 19 | * Tim Black 20 | * Gustav Larsson 21 | * Isha Mehrotra 22 | * Hannah Morgan 23 | * Anne Rogers 24 | * Borja Sotomayor 25 | -------------------------------------------------------------------------------- /about/getting-help.rst: -------------------------------------------------------------------------------- 1 | .. _about_help: 2 | 3 | Getting Help 4 | ============ 5 | 6 | If you need any assistance with any of the instructions or tutorials in this guide, 7 | please use one of the following support mechanisms: 8 | 9 | - **If you were referred to this guide by the course staff of a class you are taking**: 10 | Please use the support mechanisms provided in that class. For example, if the instructor 11 | for a class you're taking has instructed you to work through the Git tutorial, 12 | and you run into any issues while doing so, so should use whatever support mechanisms 13 | are available in that class (online discussion board, office hours, etc.) to get assistance 14 | with that issue. 15 | 16 | - **If you are working through this guide on your own**: You are welcome to seek support through 17 | the following channels: 18 | 19 | - **UChicago CS Slack**: You can ask questions about the guide on the ``#student-resource-guide`` channel. If 20 | you are not on the UChicago CS Slack, you can join using this link: https://cs-uchicago.slack.com/signup 21 | The sign up form will ask you to provide a ``@cs.uchicago.edu`` address. If you have ever registered 22 | for a CS class, you actually have a ``CNETID@cs.uchicago.edu`` e-mail address that, by default, 23 | will forward to your UChicago e-mail. If you have never registered for a CS account, but you 24 | have a UChicago CNetID, please `request a CS account `__ first. 25 | - **UChicago CS Discord**: You can ask questions about the guide on the ``#student-resource-guide`` channel. 26 | If you are not on the UChicago CS Discord, you can use the following invite link: https://discord.gg/ZVjX8Gv 27 | Please note that, when you join the Discord server, you will have limited access to the server 28 | until you perform an authentication step with your CNetID (when you join the server, a bot will 29 | provide further instructions on how to do so). Once you have authenticated, you must go to the 30 | ``#roles`` channel to obtain the "Student Resource Guide" role (so you can have 31 | access to the ``#student-resource-guide`` channel) 32 | 33 | Please note that all of the above support mechanisms are **for University of Chicago students, staff, 34 | and faculty only**. If you are unaffiliated with the University of Chicago, you will not be able 35 | to access our Slack or Discord server. -------------------------------------------------------------------------------- /about/github_issue.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/about/github_issue.png -------------------------------------------------------------------------------- /about/issue.rst: -------------------------------------------------------------------------------- 1 | .. _about_issue: 2 | 3 | Reporting an Issue 4 | ================== 5 | 6 | If you spot an issue while reading this guide, such as a typo or an example that doesn't work, 7 | you can report it to us using **GitHub Issues**. 8 | 9 | .. note:: 10 | 11 | In general, you should only report an issue if you spot something in the guide that 12 | needs to be fixed or added. If you need assistance with any of the instructions in the 13 | guide *do not file an issue using GitHub Issues*. Instead, please use the support mechanisms 14 | described in our :ref:`Getting Help ` page. 15 | 16 | To do so, go to our GitHub repository (https://github.com/uchicago-cs/student-resource-guide/) 17 | and click on the "Issues" tab (or use this `direct link `__). 18 | 19 | Once on that page, click on the green **New Issue** button (if you do not have a GitHub account, 20 | you will be prompted to create one at this time). You will be shown a form like this: 21 | 22 | .. figure:: github_issue.png 23 | 24 | Then, fill out the form as follows, depending on the kind of issue you are reporting: 25 | 26 | Typos 27 | ----- 28 | 29 | A typo refers to a minor error in the guide's text (e.g., spelling mistakes, 30 | incorrectly formatted code blocks, etc.). To report a typo, fill out the 31 | following fields: 32 | 33 | - Click on "Labels" (on the right sidebar) and select "typo". 34 | - In the title, enter "Typo in " (e.g., "Typo in Remote SSH Access page"). 35 | - In the description field (i.e., under "Write") please provide the following information: 36 | 37 | - The URL of the page where you found the typo. 38 | - The location of the typo (e.g., "In section 'Installing SSH Client", "In the second paragraph 39 | of the page", etc.) 40 | - The current text, and the suggested correction (if possible, please use bold formatting to 41 | highlight the exact correctly. For example: 42 | 43 | "The first step wall be to" should be "The first step **will** be to" 44 | 45 | 46 | Outdated Information 47 | -------------------- 48 | 49 | Outdated information can refer to one of the following: 50 | 51 | - An example that essentially works as expected, but where the output is substantially 52 | different from the one shown in the guide. 53 | - Tools that print out messages recommending that the tool be run in a different way 54 | (e.g., if we ask you to use option ``--foo``, but the tool says "Option ``--foo`` 55 | will be deprecated in future versions. Please use option ``--bar`` instead") 56 | - Screenshots that are substantially different from what you are seeing in your own 57 | system. For example, if a screenshots shows a configuration window with a couple 58 | of fields to fill in, but some of those fields are missing (or have different names) 59 | when you open them) 60 | 61 | If you encounter outdated information, please fill out the fields as follows: 62 | 63 | - Click on "Labels" (on the right sidebar) and select "update needed". 64 | - In the title, please provide a concise summary of the outdated information 65 | you have encountered. e.g., "Outdated screenshot in VSCode SSH page", 66 | "Example in Advanced Git Tutorial warns of deprecated feature", etc. 67 | - In the description field (i.e., under "Write") please provide the following information: 68 | 69 | - The URL of the page where you encountered the outdated information. 70 | - The system you are using (Mac, Windows, Linux, etc.). Please make sure to 71 | include the operating system version you are using. 72 | - In general, please tell us what information appears to be outdated, and what 73 | you are seeing when you work through that part of the guide. For example: 74 | 75 | - If the output of a command appears to be outdated, please provide the output 76 | you are seeing. 77 | - If a screenshot is outdated, please provide a screenshot of what you are 78 | seeing on your computer. 79 | 80 | Suggesting New Content 81 | ---------------------- 82 | 83 | If you'd like to suggest that we add some additional content, or that we expand on a given 84 | section to make it clearer or easier to read, please fill out the form as follows: 85 | 86 | - Click on "Labels" (on the right sidebar) and select "enhancement". 87 | - In the title, please provide a concise summary of the suggested enhancement. For example: 88 | 89 | - "Include screenshots in section X of page Y" 90 | - "Add a Java style guide" 91 | - "Explain X in more detail in page Y" 92 | 93 | - In the description field (i.e., under "Write") please provide the following information: 94 | 95 | - If you are suggesting an enhancement to a specific page, please provide the 96 | URL of that page. 97 | - Please explain the additions/changes you are suggesting, and how they could 98 | benefit the readers of the guide. 99 | 100 | Other Issues 101 | ------------ 102 | 103 | If you encounter an issue that doesn't fall into any of the above categories, please 104 | leave the "Labels" blank, and fill out the title and description, taking care to 105 | include as much information as possible about the issue (including any suggested 106 | fixes you may have). -------------------------------------------------------------------------------- /conf.py: -------------------------------------------------------------------------------- 1 | # Configuration file for the Sphinx documentation builder. 2 | # 3 | # This file only contains a selection of the most common options. For a full 4 | # list see the documentation: 5 | # https://www.sphinx-doc.org/en/master/usage/configuration.html 6 | 7 | # -- Path setup -------------------------------------------------------------- 8 | 9 | # If extensions (or modules to document with autodoc) are in another directory, 10 | # add these directories to sys.path here. If the directory is relative to the 11 | # documentation root, use os.path.abspath to make it absolute, like shown here. 12 | # 13 | # import os 14 | # import sys 15 | # sys.path.insert(0, os.path.abspath('.')) 16 | 17 | 18 | # -- Project information ----------------------------------------------------- 19 | 20 | project = 'UChicago CS Student Resource Guide' 21 | copyright = '2022, University of Chicago - Department of Computer Science' 22 | author = 'University of Chicago - Department of Computer Science' 23 | 24 | 25 | # -- General configuration --------------------------------------------------- 26 | 27 | # Add any Sphinx extension module names here, as strings. They can be 28 | # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom 29 | # ones. 30 | extensions = [ 31 | ] 32 | 33 | # Add any paths that contain templates here, relative to this directory. 34 | templates_path = ['_templates'] 35 | 36 | # List of patterns, relative to source directory, that match files and 37 | # directories to ignore when looking for source files. 38 | # This pattern also affects html_static_path and html_extra_path. 39 | exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'venv'] 40 | 41 | 42 | # -- Options for HTML output ------------------------------------------------- 43 | 44 | # Add any paths that contain custom static files (such as style sheets) here, 45 | # relative to this directory. They are copied after the builtin static files, 46 | # so a file named "default.css" will overwrite the builtin "default.css". 47 | html_static_path = ['_static'] 48 | 49 | import sphinx_rtd_theme 50 | 51 | extensions.append("sphinx_rtd_theme") 52 | 53 | html_theme = "sphinx_rtd_theme" 54 | 55 | html_context = { 56 | "display_github": True, 57 | "github_user": "uchicago-cs", 58 | "github_repo": "student-resource-guide", 59 | "github_version": "main", 60 | "conf_py_path": "/", 61 | } 62 | 63 | html_theme_options = { 64 | "prev_next_buttons_location": "both" 65 | } 66 | 67 | html_js_files = [ 68 | 'https://www.googletagmanager.com/gtag/js?id=G-MRE434GGPY', 69 | 'analytics.js', 70 | ] 71 | 72 | html_title = 'UChicago CS Student Resource Guide' 73 | 74 | extensions.append("sphinx.ext.todo") 75 | 76 | todo_include_todos = False 77 | -------------------------------------------------------------------------------- /environment/environment.rst: -------------------------------------------------------------------------------- 1 | .. _software-environment: 2 | 3 | The UChicago CS Software Environment 4 | ==================================== 5 | 6 | This page describes the software environment provided by UChicago's CS department, 7 | and which you will be using in most of your classes. This page also describes 8 | how to access this software environment, as well as some recommended development tools. 9 | 10 | The officially supported software environment in UChicago's CS department is 11 | `Ubuntu `__ 20.04, a type of Linux/UNIX system, that has 12 | most of the tools and software libraries required to complete your 13 | CS coursework. However, this does not mean that you need to install Ubuntu on your personal computer: 14 | instead, the CS department provides this environment both in our computer 15 | labs and through a series of "login servers" that will allow you to access 16 | a Linux environment remotely. 17 | 18 | .. admonition:: Completely new to Linux/UNIX? 19 | 20 | If you're completely new to Linux/UNIX systems, we recommend that you plan 21 | to stop by the CSIL computer lab (see below), and work through the Linux Basics Tutorial starting with 22 | :ref:`Introduction to Linux ` on a CSIL Linux computer. 23 | Once you're 24 | comfortable with the basics of using a Linux system, make sure you 25 | are able to remotely access the UChicago CS Linux environment 26 | from your own computer using SSH (see below). 27 | 28 | Accessing a UChicago CS Software Environment 29 | -------------------------------------------- 30 | 31 | There are several ways of accessing the UChicago CS Linux environment, 32 | which we describe below: 33 | 34 | CS Instructional Laboratory (CSIL) 35 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 36 | 37 | The `Computer Science Instructional Laboratory (CSIL) `__, 38 | located in the first floor of the `John Crerar Library `__, 39 | includes two computer labs (CSIL 3 and 4) with Linux machines in them. If there 40 | are no classes in progress in those labs, you can sit at any available 41 | computer to access the UChicago CS Linux environment (there are also Linux 42 | computers outside the labs, which you can use if the labs are occupied by a class). 43 | 44 | You can log into these machines using your CNetID and password. If you 45 | encounter any issues, you can speak to a CSIL tutor at the tutor desk. 46 | 47 | Remote SSH Access 48 | ~~~~~~~~~~~~~~~~~ 49 | 50 | While the CSIL labs provide a convenient way to access a ready-to-use 51 | Linux environment, it is also possible to access this same environment 52 | remotely (i.e., without having to be physically sitting in an on-campus 53 | computer lab). 54 | 55 | A common way to do this is with **SSH**, a system that will allow 56 | you to access a Linux terminal from your computer. This means that 57 | you will only have access to the text-only command-line terminal 58 | of the UChicago CS Linux environment, and won't be able to launch 59 | any graphical programs (like you would if you were physically 60 | sitting at a Linux machine in a CSIL lab). 61 | 62 | While this may seem like a big constraint, you can still do a lot 63 | from a Linux terminal, and most student get by just with SSH 64 | access to the UChicago CS Linux environment. 65 | 66 | We explain how to use SSH to connect to our Linux servers in the 67 | :ref:`ssh` page. There you will find instructions on how to 68 | set up SSH access from Windows, Mac, or another Linux system. 69 | 70 | SSH can also be used to seamlessly edit files that are stored 71 | on the UChicago CS Linux systems, while using an editor 72 | that is running on your own computer. The exact mechanism 73 | for doing this varies from one editor to another, but we 74 | provide instructions on how to set this up with one particular 75 | editor, Visual Studio Code, in :ref:`vscode-ssh`. 76 | 77 | Virtual Desktop 78 | ~~~~~~~~~~~~~~~ 79 | 80 | Another option for working remotely on a CS software environment is to use a `Virtual Desktop `__. This will allow you to connect to a CS server that will give you access to a desktop environment similar to the one you would encounter if you were sitting at a Linux machine in a CSIL lab. This approach, however, requires more bandwidth than using SSH, and can feel sluggish depending on the latency of your connection. We recommend this option only if you are first getting started with Linux, or in cases when you need to use a specific graphical tool in the UChicago CS Linux environment. 81 | 82 | The CS Virtual Machine 83 | ~~~~~~~~~~~~~~~~~~~~~~ 84 | 85 | The CS department also provides a virtual machine (VM) that approximates the software environment found in the CS machines. You can find the latest version of the CS virtual machine on `this page `__, which also includes instructions on how to install and run the VM. Make sure to also check out the `VM FAQ `__, which covers a number of common issues when running the VM (including how to deal with a slow/sluggish VM). 86 | 87 | Running the VM will effectively run a full Linux operating system from inside your current operating system, and will feel as if you were logging into one of the Linux machines in the CSIL labs. However, take into account that the virtual machine is a completely standalone machine, and will not have access to the CS filesystem that is available when you SSH into a CS Linux server or log into a CSIL machine. 88 | 89 | 90 | Recommended code editors 91 | ------------------------ 92 | 93 | This section provides a few recommendations on code editors you may want to consider. Some of them are included in the CS machines, but you can also install them on your own computer to write your code there (and then follow the steps found in the :ref:`ssh` page to compile and run your code on a CS machine). All of these tools are available on Windows, Mac, and Linux. 94 | 95 | You may find that some people are very opinionated about their choice of editor, and will sometimes `argue passionately `__ about why their editor is right and yours is wrong. You should ignore these people and ultimately use whatever editor works best for *you* (and don't judge other people for their choice of editor!) 96 | 97 | .. figure:: ../_static/editors.jpg 98 | :align: center 99 | :alt: Use whatever editor works for you 100 | 101 | *Design by Borja Sotomayor, artwork by Sarah Becan* 102 | 103 | Terminal-based editors 104 | ~~~~~~~~~~~~~~~~~~~~~~ 105 | 106 | Terminal-based editors, like `vim `__, `Emacs `__, and `nano `__ have the advantage of being found on practically every UNIX system and not requiring a graphical desktop, which means they can be used when logging into a machine remotely via SSH, or on older machines that may feel sluggish when running some of the graphical editors we discuss below. They can also be extremely powerful, and can be customized to work with pretty much any programming language under the sun. 107 | 108 | Even if you don't use a terminal-based editor as your primary development environment, we recommend building at least some basic familiarity with vim, Emacs, or nano in case you are ever in a situation where you can only edit a file through a terminal (and can't launch a graphical editor). 109 | 110 | 111 | Visual Studio Code 112 | ~~~~~~~~~~~~~~~~~~ 113 | 114 | If you want to use a graphical text editor (i.e., one that uses a graphical user interface from the Linux desktop), a popular option is `Visual Studio Code `__ (not to be confused with its older sibling, `Visual Studio `__). It is more powerful than a regular text editor, with features like syntax highlighting, auto completion, Git integration, plugins that integrate with other tools, etc. but it is not a full-fledged `Integrated Development Environment `__ (and, as such, is a more lightweight piece of software requiring fewer resources). 115 | 116 | Visual Studio Code is open source software and is available for free. Since it is a popular option 117 | for many students, particular beginner students, this guide includes an :ref:`entire section ` 118 | on how to set up and use Visual Studio Code. 119 | 120 | .. figure:: ../_static/vscode.png 121 | :align: center 122 | :alt: Screenshot of Visual Studio Code 123 | 124 | *Source:* https://code.visualstudio.com/ 125 | 126 | 127 | Sublime Text 128 | ~~~~~~~~~~~~ 129 | 130 | Another popular graphical text editor is `Sublime Text `__, which tends to be a bit more lightweight than Visual Studio Code. Please note that Sublime Text is not free: while you can download it and use it for a period free of charge, you will be nagged frequently about paying for a license. 131 | 132 | .. figure:: ../_static/sublime.png 133 | :align: center 134 | :alt: Screenshot of Sublime Text 135 | 136 | *Source:* https://commons.wikimedia.org/wiki/File:Sublime_text_mxunit.png 137 | 138 | JetBrains IDEs 139 | ~~~~~~~~~~~~~~ 140 | 141 | The next step up from code editors like Visual Studio Code and Sublime Text is to use a full-fledged Integrated Development Environment (IDE). Besides allowing you to edit code, IDEs usually include build automation tools and integrated debuggers. We recommend checking out the `suite of IDEs `__ provided by `JetBrains `__, including `CLion `__ for C/C++ development, `PyCharm `__ for Python development, and `IntelliJ IDEA `__ for Java development. 142 | 143 | The JetBrains IDEs are commercial software, but they provide free licenses for students and educators, and some of their IDEs also have community editions that are free to use (but less powerful than the paid version). 144 | 145 | .. figure:: ../_static/clion.png 146 | :align: center 147 | :alt: Screenshot of CLion 148 | 149 | *Source:* https://www.jetbrains.com/clion/ 150 | 151 | -------------------------------------------------------------------------------- /environment/ssh-img/install-ssh-mac-1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/environment/ssh-img/install-ssh-mac-1.png -------------------------------------------------------------------------------- /environment/ssh-img/install-ssh-mac-2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/environment/ssh-img/install-ssh-mac-2.png -------------------------------------------------------------------------------- /environment/ssh-img/install-ssh-win10-1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/environment/ssh-img/install-ssh-win10-1.png -------------------------------------------------------------------------------- /environment/ssh-img/install-ssh-win10-10.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/environment/ssh-img/install-ssh-win10-10.png -------------------------------------------------------------------------------- /environment/ssh-img/install-ssh-win10-2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/environment/ssh-img/install-ssh-win10-2.png -------------------------------------------------------------------------------- /environment/ssh-img/install-ssh-win10-3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/environment/ssh-img/install-ssh-win10-3.png -------------------------------------------------------------------------------- /environment/ssh-img/install-ssh-win10-4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/environment/ssh-img/install-ssh-win10-4.png -------------------------------------------------------------------------------- /environment/ssh-img/install-ssh-win10-5.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/environment/ssh-img/install-ssh-win10-5.png -------------------------------------------------------------------------------- /environment/ssh-img/install-ssh-win10-6.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/environment/ssh-img/install-ssh-win10-6.png -------------------------------------------------------------------------------- /environment/ssh-img/install-ssh-win10-7.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/environment/ssh-img/install-ssh-win10-7.png -------------------------------------------------------------------------------- /environment/ssh-img/install-ssh-win10-8.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/environment/ssh-img/install-ssh-win10-8.png -------------------------------------------------------------------------------- /environment/ssh-img/install-ssh-win10-9.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/environment/ssh-img/install-ssh-win10-9.png -------------------------------------------------------------------------------- /environment/ssh-img/linux-terminal.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/environment/ssh-img/linux-terminal.png -------------------------------------------------------------------------------- /environment/ssh-img/macos-terminal.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/environment/ssh-img/macos-terminal.png -------------------------------------------------------------------------------- /environment/ssh-img/windows-command-prompt.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/environment/ssh-img/windows-command-prompt.png -------------------------------------------------------------------------------- /environment/ssh.rst: -------------------------------------------------------------------------------- 1 | .. _ssh: 2 | 3 | Remote SSH Access 4 | ================= 5 | 6 | A common way of interacting with the CS Linux environment is via **SSH**, which 7 | will allow you to connect to a Linux server from your own personal computer 8 | (which doesn't have to run Linux). 9 | 10 | Nowadays, most operating systems include an *SSH client*, so you will likely not 11 | have to install any additional software. We'll start by checking that you can 12 | run the SSH client on your computer (if not, we provide installation 13 | instructions further below in this page). 14 | 15 | The first step will be to open one of the following: 16 | 17 | - **Windows**: "Command Prompt" or PowerShell 18 | - **MacOS**: Terminal 19 | - **Linux**: Terminal 20 | 21 | Try searching for these tools on your operating system (e.g., by using the Start 22 | menu on Windows, or the search icon on MacOS). If you can't find them, try 23 | following one of these instructions: 24 | 25 | - **Windows**: `How to Open Command Prompt (Windows 11, 10, 8, 7, etc.) 26 | `__ 27 | - **MacOS**: `Open or quit Terminal on Mac 28 | `__ 29 | - **Linux**: In most Linux distributions, pressing ``Ctrl-Alt-T`` will open a 30 | terminal. 31 | 32 | On Windows, the command prompt should look something like this (if you're using 33 | the PowerShell, it will look basically the same, except it will say "PowerShell" 34 | at the top): 35 | 36 | .. figure:: ssh-img/windows-command-prompt.png 37 | 38 | On MacOS, the terminal should look something like this: 39 | 40 | .. figure:: ssh-img/macos-terminal.png 41 | 42 | On Linux, the terminal should look something like this: 43 | 44 | .. figure:: ssh-img/linux-terminal.png 45 | 46 | Regardless of the operating system you're using, the command prompt or terminal 47 | will allow you to enter text-based commands. To use SSH to connect to one of the 48 | UChicago CS Linux servers, you will need to type the following, taking care to 49 | replace ``CNETID`` with your CNetID in all lowercase:: 50 | 51 | ssh CNETID@linux.cs.uchicago.edu 52 | 53 | Press Enter. If you get any sort of error message telling you that there is no 54 | ``ssh`` command available on your computer, that means you will need to install 55 | SSH on your computer. You can find instructions on how to do this in the 56 | "Installing an SSH Client" section below. 57 | 58 | If SSH is installed on your computer, the command may first print out a message 59 | like this:: 60 | 61 | The authenticity of host 'linuxX.cs.uchicago.edu (128.135.XXX.XXX)' can't be established. 62 | ECDSA key fingerprint is SHA256:... 63 | Are you sure you want to continue connecting (yes/no/[fingerprint])? 64 | 65 | If so, just type ``yes``. 66 | 67 | Then, when prompted for a password, just enter your CNetID password. Here are 68 | two troubleshooting hints: 69 | 70 | - passwords are case-sensitive, that is, upper-case ``S`` is different from 71 | lower-case ``s``. Make sure you type your CNetID password exactly as you 72 | created it. 73 | 74 | - ``ssh`` will *not* echo your password back to you as you type it. 75 | 76 | If your connection is successful, you may see a series of messages, ending with 77 | this:: 78 | 79 | CNETID@linuxN:~$ 80 | 81 | Where ``CNETID`` will be your CNetID, and ``N`` will be a number between 1 and 82 | 7. 83 | 84 | If you see the above, you've connected successfully to a UChicago CS Linux 85 | server! If you came to this page from the :ref:`Linux Basics Tutorial - Introduction to Linux 86 | `, you should continue working on the tutorial through 87 | the SSH connection you just opened. 88 | 89 | When you are finished using your SSH connection, close it by typing ``Ctrl-D`` 90 | or ``exit`` at the Linux prompt. 91 | 92 | .. note:: Troubleshooting UChicago Campus Network Issues 93 | 94 | There are at two wireless networks on campus: ``eduroam`` and ``uchicago``. (You may see a network named ``uchicago-secure``; it is in the process of being decommissioned.) 95 | 96 | The first, ``eduroam``, can be used with ``ssh``. The second, ``uchicago``, DOES NOT support ``ssh`` connections. 97 | 98 | If you are on campus and have trouble logging into one of the servers, please 99 | verify that you are using ``eduroam`` as your 100 | wireless network. The following is a common error message that occurs when 101 | trying to use a network that does not support ``ssh`` connections : ``Could 102 | not establish connection to "linuxX.cs.uchicago.edu": The operation timed 103 | out.`` 104 | 105 | 106 | Installing an SSH Client 107 | ------------------------ 108 | 109 | If your operating system does not have an SSH client installed, please following 110 | the instructions below to install it. Please note that MacOS systems always 111 | include an SSH client, so we have not included instructions on how to install 112 | SSH on MacOS. 113 | 114 | 115 | Windows 10 116 | ~~~~~~~~~~ 117 | 118 | In these instructions, you will open various applications and settings by 119 | searching for them. To do this, open the Start menu by pressing the Windows key 120 | on the keyboard, or clicking the Windows icon in the corner of your screen. 121 | Begin typing the name of the application or setting, like *About your PC* (even 122 | though there is no visible search bar, one will appear when you begin typing). 123 | When the *About your PC* option appears, click on it. 124 | 125 | **Checking your version of Windows 10** 126 | 127 | You need to be running a recent version of Windows 10. To check your current 128 | version, open the Start menu, begin typing *About your PC*, and click on the 129 | option when it appears. 130 | 131 | .. figure:: ssh-img/install-ssh-win10-1.png 132 | 133 | Scroll down to the heading *Windows specifications*. Next to *Edition*, you 134 | should see *Windows 10 Home* or *Windows 10 Pro* (or similar). 135 | 136 | .. figure:: ssh-img/install-ssh-win10-2.png 137 | 138 | Below that you should see *Version* and a number like 2004. If this number is 139 | less than 1803, then you need to update Windows 10. 140 | 141 | **Updating Windows 10** 142 | 143 | To update Windows 10, open the Start menu, begin typing *Check for updates*, and 144 | click on the option when it appears. 145 | 146 | .. figure:: ssh-img/install-ssh-win10-3.png 147 | 148 | The window that opens should have the heading *Windows Update*. It may tell you 149 | that you have updates available; otherwise, click the button that says *Check 150 | for updates*. 151 | 152 | .. figure:: ssh-img/install-ssh-win10-4.png 153 | 154 | Follow the instructions to install the available updates. This may take a few 155 | minutes, and your computer may restart. When the update completes, check your 156 | version of Windows 10 again, and verify that it now reads as 1803 or greater. 157 | 158 | **Installing Windows OpenSSH Client** 159 | 160 | Open the Start menu, begin typing *Manage Optional Features*, and click the 161 | option when it appears. 162 | 163 | .. figure:: ssh-img/install-ssh-win10-5.png 164 | 165 | You should see a window that looks like this, with the heading *Optional 166 | features*. 167 | 168 | .. figure:: ssh-img/install-ssh-win10-6.png 169 | 170 | Scroll through the list of *Installed features*. If *OpenSSH Client* appears in 171 | the list, you are done with this step. Otherwise, click on *+ Add a feature* at 172 | the top of the page. You will get a pop-up window with the heading *Add an 173 | optional feature*. Start typing *OpenSSH Client*. When the option appears, click 174 | on the checkbox next to it. 175 | 176 | .. figure:: ssh-img/install-ssh-win10-7.png 177 | 178 | Then click on the button labeled *Install (1)*. Wait for the progress bar to 179 | fill. 180 | 181 | .. figure:: ssh-img/install-ssh-win10-8.png 182 | 183 | The installation is complete. You should now re-try the instructions at the top 184 | of this page. 185 | 186 | 187 | Linux 188 | ~~~~~ 189 | 190 | Linux systems typically include an SSH client but may occasionally not include 191 | one. The exact process to install the client may vary from one Linux 192 | distribution to another, but the following commands should allow you to install 193 | SSH in some of the most popular Linux distributions: 194 | 195 | - **Debian/Ubuntu**: Run ``sudo apt-get install openssh-client`` 196 | - **RHEL/Fedora/CentOS**: Run ``sudo yum install openssh-clients`` 197 | 198 | Once you've installed SSH, you should re-try the instructions at the top of the 199 | page. 200 | 201 | 202 | .. _passwordless-ssh: 203 | 204 | Setting up Passwordless SSH 205 | --------------------------- 206 | 207 | You may have noticed that every time you connect to the Linux server with SSH, 208 | either in a terminal window or with VSCode, you are prompted for your password. 209 | 210 | These instructions will allow you to configure your computer to connect to the 211 | Linux server without being prompted for your password each time, which is much 212 | more convenient. 213 | 214 | You only need to follow these instructions once on your personal 215 | computer/laptop. 216 | 217 | .. warning :: 218 | 219 | If you have already completed the GitHub SSH setup instructions 220 | (from the `Git Tutorial `_), you 221 | already have an SSH key pair on your computer. Please read and follow the 222 | instructions carefully to avoid overwriting your existing SSH key pair and 223 | losing access to GitHub. 224 | 225 | 226 | **Step 1**: Open a terminal window on your local computer. On Windows, open a 227 | Powershell terminal by pressing the Windows button and searching for 228 | “Powershell”. This terminal should be on your **local machine**; that is, **do 229 | not connect with SSH to the Linux server**. The following commands (steps 2-5) 230 | should be run on your local machine. 231 | 232 | 233 | **Step 2**: Run ``cd`` 234 | 235 | This command will take you to your home directory. 236 | 237 | **Step 3**: Run ``ssh-keygen -t ed25519`` 238 | 239 | You will see the following prompt: :: 240 | 241 | Generating public/private ed25519 key pair. 242 | Enter file in which to save the key (/home/username/.ssh/id_ed25519): 243 | 244 | Press Enter to accept the default location. Check the output of this command to 245 | decide whether you need to generate a new SSH key pair (see the warning below). 246 | 247 | .. warning :: 248 | If you have already completed generated an SSH key pair for (possibly for 249 | GitHub) , you will see a prompt like this: 250 | :: 251 | 252 | /home/username/.ssh/id_ed25519 already exists. Overwrite (y/n)? 253 | 254 | If you see this prompt, **do not overwrite your existing SSH key pair**. You 255 | can re-use this key pair. **Skip ahead to Step 4**. 256 | 257 | You will then see the following prompt: 258 | 259 | :: 260 | 261 | Enter passphrase (empty for no passphrase): 262 | 263 | In order to use SSH without a password, you must leave this passphrase empty. 264 | Press Enter to accept the default (empty passphrase). You will then see a 265 | message like this: 266 | 267 | :: 268 | 269 | Your identification has been saved in /home/username/.ssh/id_ed25519. 270 | Your public key has been saved in /home/username/.ssh/id_ed25519.pub. 271 | The key fingerprint is: 272 | SHA256:cBUUs2FeMCIrBlTyv/PGpBtNz0v235zvLykpoWIOS9I username@machine 273 | 274 | The key’s randomart image is: 275 | +--[ED25519 256]--+ 276 | | .+.. . ..@+. | 277 | | + o = * | 278 | | + o . o | 279 | | . o o | 280 | | . S | 281 | | . +.o. | 282 | | . E ++..=. . . | 283 | | o o+++o.oo oo. | 284 | | .oo+. ...o.+O | 285 | +----[SHA256]-----+ 286 | 287 | This message indicates that your SSH key pair has been generated successfully. 288 | 289 | **Step 4**: Time to copy your public key to the Linux server. This command will 290 | differ depending on whether you are using a Mac or Windows computer. 291 | 292 | - **Mac/Linux**: Run the following command: 293 | 294 | :: 295 | 296 | ssh-copy-id CNETID@.cs.uchicago.edu`` 297 | 298 | Replace ``CNETID`` with your CNetID, and ```` with the name of 299 | the server you want to connect to. For example, if you want to connect to 300 | such as ``linux1.cs.uchicago.edu`` or ``cs141-4.cs.uchicago.edu``. 301 | 302 | You will be prompted for your password. Enter your CNetID password. 303 | 304 | - **Windows**: Run the following commands from the Window's **Powershell** command-line prompt: 305 | 306 | :: 307 | 308 | $publicKeyPath = "$env:USERPROFILE\.ssh\id_ed25519.pub" 309 | $remoteCommand = "{ 310 | mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys 311 | }" 312 | Get-Content $publicKeyPath | ssh @ $remoteCommand 313 | 314 | Replace ```` with your CNetID, and ```` with the name of the 315 | server you want to connect to, such as ``linux1.cs.uchicago.edu`` or 316 | ``cs141-4.cs.uchicago.edu``. 317 | 318 | Please note that the curly braces (``{`` and ``}``) in the second command need to be on their own lines. 319 | 320 | You will be prompted for your password. Enter your CNetID password. 321 | 322 | **Step 5**: Test your connection. Run the following command: 323 | 324 | ``ssh CNETID@.cs.uchicago.edu`` 325 | 326 | You should now be able to connect to the Linux server without being prompted for 327 | a password. 328 | 329 | 330 | 331 | 332 | 333 | 334 | 335 | 336 | 337 | -------------------------------------------------------------------------------- /getting-help/office-hours.rst: -------------------------------------------------------------------------------- 1 | .. _getting-help_office-hours: 2 | 3 | Office Hours 4 | ============ 5 | 6 | Most CS classes will have office hours where you can get assistance 7 | with your coursework, or have broader-ranging conversations about 8 | the material covered in the class. In this page, we provide 9 | a few tips on how to get the most out of office hours. 10 | 11 | - First and foremost, some words of encouragement. Know that the course staff 12 | is there to help you, and they cannot help you if you do not 13 | ask questions. Quite simply, the point is to learn, not to 14 | know everything already. 15 | - Sometimes, office hours are run as a sort of "Q&A session" where 16 | multiple students are in the room at the same time, and an instructor 17 | or TA takes questions from the students. In these kind of office hours, 18 | chances are someone else has a similar 19 | question to the one you want to ask. In attending office hours, 20 | you may get an answer to your question without having to ask it yourself. 21 | - Prepare questions ahead of time. Time in office hours can be 22 | limited–particularly near assignments deadlines and exams–and so knowing what you need help 23 | with beforehand will let you make the most of your time. 24 | - Make a list of known unknowns. Along the lines of the previous point, 25 | knowing what you do not fully understand is a time saver. 26 | - When formulating your questions try to make them specific and clear. 27 | The course staff cannot help you if they do not understand your question. 28 | - On days when there are not a lot of pressing questions during office 29 | hours, you can just talk to the course staff and faculty about what you 30 | find interesting about the material. It can be outside the scope of what 31 | was covered in class. 32 | -------------------------------------------------------------------------------- /getting-help/questions.rst: -------------------------------------------------------------------------------- 1 | .. _getting-help_questions: 2 | 3 | Asking Questions 4 | ================ 5 | 6 | .. note:: 7 | 8 | This page provides some useful guidelines on how to ask questions 9 | in your classes (and more specifically on an online discussion board). 10 | If you have questions about this guide (e.g., if you need help working 11 | through any of the instructions provided in this guide), please see the 12 | :ref:`Getting Help ` page in the "About This Guide" section. 13 | 14 | As you work through your coursework, many of you will probably have 15 | questions or will encounter issues that you are not sure how to 16 | handle. Your course staff will typically set up some form of online 17 | discussion board for this very purpose, usually through Canvas or Ed 18 | Discussion. 19 | 20 | Online discussion boards provide a 21 | convenient mechanism to ask questions, but it can sometimes be 22 | challenging for course staff to help you if you do not provide the right 23 | information when asking a question. Here are a few suggestions that may 24 | help you ask questions more effectively on an online discussion board: 25 | 26 | - Before you post a question... 27 | 28 | - **Search before asking**. Before posting a question on the 29 | discussion board, check whether it has already been answered in a 30 | previous post. We realize the volume of posts can be overwhelming, 31 | but you should start by using the discussion board’s search 32 | functionality to see if it brings up any relevant posts. For 33 | example, suppose you are failing a specific test in a programming assignment; 34 | you could search just for that test’s name to see if any 35 | other students have encountered that same error (and, if you’re 36 | lucky, an instructor/TA will have already answered it). 37 | - **Make sure to formulate an actual question to ask**. Make sure 38 | you are describing a specific issue you’re encountering, and why you’re 39 | stuck on it (e.g., you are not getting the expected result, the 40 | tests are failing in a way you do not understand, etc.). Writing a 41 | post that says “I can’t get Task 4 to work, I’ve pushed my code. 42 | Please look at it.” is not a question: it is a request for someone 43 | to debug your code for you. Try instead to describe the exact 44 | reason why you're stuck (we provide concrete suggestions on how to 45 | do this below). If you're struggling to do so, you may want to 46 | go to :ref:`office hours ` to get help 47 | more interactively. 48 | 49 | - **Public vs private questions**. Discussion boards often have 50 | mechanisms that allow you to ask private questions, which will be 51 | seen only by the instructors and teaching assistants. Typically, this 52 | mechanism should be used only for truly private matters that relate 53 | uniquely to you (e.g., you need to notify the course staff of a family/medical 54 | emergency, etc.). 55 | 56 | Of course, when you run into an issue on an assignment, it may seem like 57 | "it applies only to you" because it relates to your code. However, 58 | it's possible that other students will run into the exact same issue 59 | you ran into. So, questions about coursework, course logistics, etc. 60 | do not qualify as "private matters", and should typically be 61 | asked publicly. This way, everyone can benefit from the 62 | answer to the question and, if someone runs into the same issue you 63 | do, course staff can refer them to the answer they provided in your post. 64 | 65 | - **The more information, the better**. We know that, in some 66 | classes, you may feel the need to be brief and concise when asking 67 | for help to “avoid wasting the professor’s time” or because 68 | “professors don’t have time to read long e-mails”. The absolute 69 | opposite is true in most CS classes: when asking for help, we prefer 70 | that you *overwhelm* us with information. 71 | 72 | In particular, it will be much easier for course staff to help you if they are 73 | able to reproduce the exact issue you are encountering (i.e., when 74 | they run your code, they must be able to observe the exact same issue 75 | you’re encountering). And to do so, they need as much information as 76 | possible from you: 77 | 78 | - If your question relates to your code, and your class is using a 79 | version-control system (e.g. git, svn, etc), make 80 | sure you push your code to the server (e.g. GitHub, GitLab, PhoenixForge) before asking for help. 81 | - Make sure you’re running your code on a :ref:`UChicago CS software environment `. 82 | Course staff will not be able to provide 83 | assistance if you are running your code on your personal machine, 84 | as this will make it harder for them to reproduce the exact issue 85 | you are encountering. 86 | - Include a detailed description of the exact chain of events that 87 | lead to the issue you’re encountering (Are you testing a specific 88 | function? If so, with what inputs? Does the issue come up when you 89 | run a test? Etc.). 90 | - If you encounter an error message (or any other unexpected output) 91 | when running a command or a specific test, please make sure you 92 | include the command that you ran and the **full and unabridged** error message (or unexpected 93 | output). Summarizing the message (e.g., “The tests says it was 94 | expecting value 42, and I’m pretty sure that’s what I’m 95 | returning”) makes it harder for course staff to identify the issue. 96 | - If something is “wrong”, please describe in what way it seems 97 | wrong to you. For example, were you expecting a particular output 98 | but got a different one? Is a piece of code behaving in a way you 99 | were not expecting? Etc. It can be useful to describe what you were 100 | expecting the code to do, and what you encountered instead. 101 | 102 | - What *not* to include in your question: 103 | 104 | - **Never post your code on an online discussion board**. If 105 | you need the course staff to look at your code, and your class 106 | uses a version control system, just push it to the server 107 | (e.g. GitHub, GitLab, PhoenixForge) and the course staff 108 | will look at it there. Please note that, if a test prints out a 109 | few lines of code as part of its output, that is typically acceptable. 110 | - **No screenshots**. Do not post screenshots of the command or the output. 111 | Screenshots are not searchable, and may pose readability issues 112 | for some people. Instructors/TAs may also want to copy-paste your 113 | command elsewhere, which is not possible if you post a 114 | screenshot. 115 | 116 | If you need to share some output from the terminal, copy-paste from the 117 | terminal onto the discussion board, and use the discussion board’s 118 | “code block” or "verbatim" formatting. To copy something on the terminal, just 119 | select it (the same way you would do in a word processor: click, 120 | and then drag until the end of the output) and press 121 | Control-Shift-C (Command-C on MacOS). 122 | 123 | - **One question, one post**. Avoid posts that have multiple unrelated 124 | questions. Instead, write a separate post for each question. Please 125 | note that it is ok to ask multiple questions in one post if they all 126 | relate to the same issue. 127 | 128 | - **Comments vs Answers**. Some discussion board distinguish between 129 | "answering" a question and adding a "comment" on an existing question. 130 | In those cases, you should use the "comment" functionality if you'd like 131 | to provide additional information on a question, or have a follow-up question. 132 | You should use the "answer" functionality only if you are providing an 133 | actual answer to the question (including if you've resolved the issue 134 | on your own, so the question is flagged as "answered"). 135 | -------------------------------------------------------------------------------- /index.rst: -------------------------------------------------------------------------------- 1 | UChicago CS Student Resource Guide 2 | ================================== 3 | 4 | This resource guide is intended for students taking Computer Science classes at the University of Chicago. 5 | Please note that it is not meant to be a normative guide for all CS classes (unless your instructor has 6 | explicitly pointed you to this guide). 7 | 8 | This guide is divided into the following sections: 9 | 10 | - **Software Environment**: Information about the Linux software environment provided by the CS department, 11 | and which you will be using in most of your classes. This section includes instructions on how to access 12 | this environment, including when working off-campus. 13 | - **Visual Studio Code**: Instructions on how to use Visual Studio Code, a popular code editor. 14 | - **Tutorials**: A couple of useful tutorials covering certain tools and skills you may need in your classes. 15 | - **Getting Help in Your Classes**: Tips and suggestions on how to get help in your classes. 16 | - **Style Guides**: Style guides you may be required to follow in your programming assignments. 17 | - **Other Resources**: Other useful resources. 18 | - **About This Guide**: Information about the guide itself, including how to get assistance or suggest 19 | changes/improvements. 20 | 21 | .. toctree:: 22 | :maxdepth: 2 23 | :hidden: 24 | :caption: Software Environment 25 | 26 | environment/environment.rst 27 | environment/ssh.rst 28 | 29 | .. toctree:: 30 | :maxdepth: 2 31 | :hidden: 32 | :caption: Visual Studio Code 33 | 34 | About VS Code 35 | Installation 36 | Using VS Code and SSH 37 | Configuration 38 | Tips & Tricks 39 | 40 | .. toctree:: 41 | :maxdepth: 2 42 | :hidden: 43 | :caption: Linux Tutorials 44 | 45 | Introduction 46 | Navigating the Filesystem 47 | Editing, Compiling, and Running a Program 48 | Getting Help 49 | Tips and Tricks 50 | Running Commands Sequentially 51 | Working with Input/Output Streams 52 | Understanding File Permissions 53 | 54 | .. toctree:: 55 | :maxdepth: 2 56 | :hidden: 57 | :caption: Git Tutorials 58 | 59 | Introduction 60 | Local Repositories 61 | Preparing to use GitHub 62 | Remote Repositories 63 | Discarding Changes and Unstaging 64 | Viewing the Commit Log 65 | Working from Multiple Locations 66 | Working with Branches 67 | 68 | .. toctree:: 69 | :maxdepth: 2 70 | :hidden: 71 | :caption: Getting Help in Your Classes 72 | 73 | Asking Questions 74 | Office Hours 75 | 76 | .. toctree:: 77 | :maxdepth: 2 78 | :hidden: 79 | :caption: Style Guides 80 | 81 | C 82 | Python 83 | 84 | .. toctree:: 85 | :maxdepth: 2 86 | :hidden: 87 | :caption: Other Resources 88 | 89 | teams.rst 90 | The Debugging Guide 🔗 91 | 92 | .. toctree:: 93 | :maxdepth: 2 94 | :hidden: 95 | :caption: About This Guide 96 | 97 | Getting Help 98 | Report an Issue 99 | Acknowledgements 100 | Tutorial Acknowledgements 101 | -------------------------------------------------------------------------------- /requirements.txt: -------------------------------------------------------------------------------- 1 | Sphinx>=2.4.4 2 | sphinx-rtd-theme>=0.4.3 -------------------------------------------------------------------------------- /tutorials/.gitignore: -------------------------------------------------------------------------------- 1 | linux-tutorial-files/hello 2 | linux-tutorial-files/hello++ 3 | linux-tutorial-files/Hello.class -------------------------------------------------------------------------------- /tutorials/acknowledgements.rst: -------------------------------------------------------------------------------- 1 | Acknowledgements 2 | ---------------- 3 | 4 | Parts of this tutorial are based on a Linux lab originally written for CMSC 12100 5 | by Prof. Anne Rogers and Prof. Borja Sotomayor, and edited by numerous instructors 6 | and TAs over the years. 7 | -------------------------------------------------------------------------------- /tutorials/files/git-tutorial/hello.py: -------------------------------------------------------------------------------- 1 | print("Hello!") 2 | print("Hello, world!") 3 | print("Hello, universe!") 4 | 5 | -------------------------------------------------------------------------------- /tutorials/files/git-tutorial/hola.py: -------------------------------------------------------------------------------- 1 | print("hola!") 2 | print("hola, mundo!") 3 | print("hola, universo!") 4 | 5 | -------------------------------------------------------------------------------- /tutorials/files/linux-tutorial-files/.heythere: -------------------------------------------------------------------------------- 1 | Hello from .heythere. 2 | 3 | -------------------------------------------------------------------------------- /tutorials/files/linux-tutorial-files/Hello.java: -------------------------------------------------------------------------------- 1 | class Hello { 2 | public static void main(String[] args) { 3 | System.out.println("Hello, world!"); 4 | } 5 | } -------------------------------------------------------------------------------- /tutorials/files/linux-tutorial-files/hello.c: -------------------------------------------------------------------------------- 1 | #include 2 | 3 | int main() 4 | { 5 | printf("Hello, world!\n"); 6 | 7 | return 0; 8 | } -------------------------------------------------------------------------------- /tutorials/files/linux-tutorial-files/hello.cpp: -------------------------------------------------------------------------------- 1 | #include 2 | 3 | int main() 4 | { 5 | std::cout << "Hello, world!" << std::endl; 6 | return 0; 7 | } -------------------------------------------------------------------------------- /tutorials/files/linux-tutorial-files/hello.py: -------------------------------------------------------------------------------- 1 | print("Hello, world!") 2 | -------------------------------------------------------------------------------- /tutorials/files/linux-tutorial-files/my-input.txt: -------------------------------------------------------------------------------- 1 | Hello world! 2 | Hello sports fans! 3 | -------------------------------------------------------------------------------- /tutorials/files/linux-tutorial-files/my_echo.py: -------------------------------------------------------------------------------- 1 | import sys 2 | 3 | if __name__=="__main__": 4 | for line in sys.stdin: 5 | print(line) 6 | -------------------------------------------------------------------------------- /tutorials/files/linux-tutorial-files/test.txt: -------------------------------------------------------------------------------- 1 | Linux Tutorial - Test file 2 | ========================== 3 | 4 | Name: Firstname Lastname 5 | -------------------------------------------------------------------------------- /tutorials/filesystem.username.svg: -------------------------------------------------------------------------------- 1 | 2 | 4 | 6 | 7 | 9 | 10 | _anonymous_0 11 | 12 | 13 | /home/username 14 | 15 | /home/username 16 | 17 | 18 | /home/username/Desktop 19 | 20 | /home/username/Desktop 21 | 22 | 23 | /home/username->/home/username/Desktop 24 | 25 | 26 | 27 | 28 | /home/username/Documents 29 | 30 | /home/username/Documents 31 | 32 | 33 | /home/username->/home/username/Documents 34 | 35 | 36 | 37 | 38 | / 39 | 40 | / 41 | 42 | 43 | /home 44 | 45 | /home 46 | 47 | 48 | /->/home 49 | 50 | 51 | 52 | 53 | /bin 54 | 55 | /bin 56 | 57 | 58 | /->/bin 59 | 60 | 61 | 62 | 63 | /stage 64 | 65 | /stage 66 | 67 | 68 | /->/stage 69 | 70 | 71 | 72 | 73 | /home->/home/username 74 | 75 | 76 | 77 | 78 | /home/beu 79 | 80 | /home/beu 81 | 82 | 83 | /home->/home/beu 84 | 85 | 86 | 87 | 88 | /home/borja 89 | 90 | /home/borja 91 | 92 | 93 | /home->/home/borja 94 | 95 | 96 | 97 | 98 | 99 | -------------------------------------------------------------------------------- /tutorials/git-advanced.rst: -------------------------------------------------------------------------------- 1 | .. _tutorial-git-advanced: 2 | 3 | Tutorial - Advanced Git 4 | ======================= 5 | 6 | The Advanced Git tutorial has been reorganized into smaller sections. 7 | Please see the left sidebar for links to specific sections (under "Git Tutorials") -------------------------------------------------------------------------------- /tutorials/git-basics.rst: -------------------------------------------------------------------------------- 1 | .. _tutorial-git-basics: 2 | 3 | Tutorial - Git Basics 4 | ===================== 5 | 6 | The Git Basics tutorial has been reorganized into smaller sections. 7 | Please start the tutorial at :ref:`tutorial-git-intro`. -------------------------------------------------------------------------------- /tutorials/git-branches-2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/tutorials/git-branches-2.png -------------------------------------------------------------------------------- /tutorials/git-branches-3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/tutorials/git-branches-3.png -------------------------------------------------------------------------------- /tutorials/git-branches.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/tutorials/git-branches.png -------------------------------------------------------------------------------- /tutorials/git-commit-log.rst: -------------------------------------------------------------------------------- 1 | .. _tutorial-git-commit-log: 2 | 3 | Git Tutorial - Viewing the Commit Log 4 | ===================================== 5 | 6 | .. note:: 7 | 8 | This section assumes you have: 9 | 10 | - completed the :ref:`tutorial-git-discarding-changes` section of the tutorial, 11 | - opened a terminal window that is connected to one of the CS Linux servers, and 12 | - navigated to your ``git-tutorial`` directory. 13 | 14 | 15 | Once you have made multiple commits, you can see these commits, their 16 | dates, commit messages, author, etc. using the ``git log`` 17 | command. This command will open a scrollable interface (using the 18 | up/down arrow keys) that you can get out of by pressing the ``q`` 19 | key:: 20 | 21 | 22 | commit 91ee425d4091f1c3d69accea84000a34ad14c856 (HEAD -> main, origin/main) 23 | Author: Anne Rogers 24 | Date: Wed May 15 15:05:54 2024 -0500 25 | 26 | Wrapping up the restore section of the tutorial 27 | 28 | commit 55e4745ef93c457649703c44909d63a3a06f0096 29 | Author: NAME 30 | Date: Wed May 15 14:51:16 2024 -0500 31 | 32 | Added README file 33 | 34 | commit f81ceb9561bc80c6e4983b57e222c92fbd94b4c7 35 | Author: NAME 36 | Date: Wed May 15 14:47:42 2024 -0500 37 | 38 | Added Danish version 39 | 40 | commit 982d639fbc872ff407e2894ae457e87363a6942d 41 | Author: NAME 42 | Date: Mon May 13 18:15:58 2024 -0500 43 | 44 | Added French version 45 | 46 | commit e8029ada15807dddf116a59f922093cae2c57cc1 47 | Author: NAME 48 | Date: Mon May 13 18:15:08 2024 -0500 49 | 50 | Added more salutations 51 | 52 | commit 76d83bbd9fafa033f9fbffddfafabd04e3cb8cbe 53 | Author: NAME 54 | Date: Mon May 13 18:13:52 2024 -0500 55 | 56 | Forgot to capitalize in Spanish version 57 | 58 | : 59 | 60 | 61 | 62 | As we saw earlier, you can also see the history of commits 63 | through on GitHub’s web interface, but it is also useful to be able to 64 | access the commit log directly from the terminal, without having to 65 | open a browser. 66 | 67 | Each commit will have a *commit hash* (usually referred to as the 68 | *commit SHA*) that looks something like this: 69 | 70 | :: 71 | 72 | 76d83bbd9fafa033f9fbffddfafabd04e3cb8cbe 73 | 74 | This is a unique identifier that we can use to refer to that commit 75 | elsewhere. For example, choose any commit from the commit log and run 76 | the following: 77 | 78 | :: 79 | 80 | $ git show COMMIT_SHA 81 | 82 | Make sure to replace ``COMMIT_SHA`` with a commit SHA that appears in 83 | your commit log. 84 | 85 | This will show you the changes that were included in that commit. The 86 | output of ``git show`` can be a bit hard to parse at first but the 87 | most important thing to take into account is that any line starting 88 | with a ``+`` denotes a line that was added, and any line starting with 89 | a ``-`` denotes a line that was removed. For example, if we want to 90 | looked at the committed with the message ``"Forgot to capitalize in 91 | Spanish version"``, we would run: 92 | 93 | :: 94 | 95 | $ git show 76d83bbd9fafa033f9fbffddfafabd04e3cb8cbe 96 | commit 76d83bbd9fafa033f9fbffddfafabd04e3cb8cbe 97 | Author: NAME 98 | Date: Mon May 13 18:13:52 2024 -0500 99 | 100 | Forgot to capitalize in Spanish version 101 | 102 | diff --git a/hola.py b/hola.py 103 | index 5cbad67..e4c0f4e 100644 104 | --- a/hola.py 105 | +++ b/hola.py 106 | @@ -1,4 +1,4 @@ 107 | -print("hola!") 108 | -print("hola, mundo!") 109 | -print("hola, universo!") 110 | +print("Hola!") 111 | +print("Hola, mundo!") 112 | +print("Hola, universo!") 113 | 114 | Pro tip: in any place where you have to refer to a commit SHA, you can 115 | just write the first few characters of the commit SHA. For example, for 116 | commit ``76d83bbd9fafa033f9fbffddfafabd04e3cb8cbe`` we could write just 117 | this: 118 | 119 | :: 120 | 121 | $ git show 76d8 122 | 123 | Git will only complain if there is more than one commit that starts with 124 | that same prefix. 125 | 126 | In the next section, you will learning about working from multiple places. 127 | 128 | 129 | -------------------------------------------------------------------------------- /tutorials/git-discarding-changes.rst: -------------------------------------------------------------------------------- 1 | .. _tutorial-git-discarding-changes: 2 | 3 | Git Tutorial - Discarding Changes and Unstaging 4 | ================================================ 5 | 6 | .. note:: 7 | 8 | This section assumes you have: 9 | 10 | - completed the :ref:`tutorial-git-remote` section of the tutorial, 11 | - opened a terminal window that is connected to one of the CS Linux servers, and 12 | - navigated to your ``git-tutorial`` directory. 13 | 14 | 15 | In the :ref:`tutorial-git-remote` section, we covered how to link a 16 | local repository to a remote repository on GitHub. In this section, 17 | you will learn how to discard changes. 18 | 19 | 20 | One of the benefits of using a version control system is that it is very 21 | easy to inspect the history of changes to a given file, as well as to 22 | undo changes we did not intend to make. 23 | 24 | For example, edit ``README.md`` to remove all its contents. 25 | 26 | ``git status`` will tell us this: 27 | 28 | :: 29 | 30 | On branch main 31 | Your branch is up to date with 'origin/main'. 32 | 33 | Changes not staged for commit: 34 | (use "git add ..." to update what will be committed) 35 | (use "git restore ..." to discard changes in working directory) 36 | modified: README.md 37 | 38 | no changes added to commit (use "git add" and/or "git commit -a") 39 | 40 | If we want to discard the changes we made to ``README.md``, all we have 41 | to do is follow the helpful advice provided by the above output: 42 | 43 | :: 44 | 45 | $ git restore README.md 46 | 47 | 48 | If you look at ``README.md``, you’ll see that its contents have been 49 | magically restored! 50 | 51 | Now, edit ``README.md`` to add an additional line with 52 | the text ``UChicago Student Resource Guide``. Run ``git add -u`` but don’t 53 | commit it just yet. The git status will show this: 54 | 55 | :: 56 | 57 | On branch main 58 | Your branch is up to date with 'origin/main'. 59 | 60 | Changes to be committed: 61 | (use "git restore --staged ..." to unstage) 62 | modified: README.md 63 | 64 | Now, let’s say we realized do not want to commit the changes to 65 | ``README.md``, but we’ve already told git that we want to include 66 | ``README.md`` in the commit. Fortunately, we can “un-include” it (or 67 | “unstage” it, in Git lingo) by running this command: 68 | 69 | :: 70 | 71 | $ git restore --staged README.md 72 | 73 | 74 | Now, git status will show the following: 75 | 76 | :: 77 | 78 | On branch main 79 | Your branch is up to date with 'origin/main'. 80 | 81 | Changes not staged for commit: 82 | (use "git add ..." to update what will be committed) 83 | (use "git restore ..." to discard changes in working directory) 84 | modified: README.md 85 | 86 | no changes added to commit (use "git add" and/or "git commit -a") 87 | 88 | 89 | We can either commit the changes or restore the file back 90 | to the last commit (using ``git restore``). Let's commit and push the 91 | changes: 92 | 93 | :: 94 | 95 | $ git add -u 96 | $ git commit -m"Wrapping up the restore section of the tutorial" 97 | $ git push 98 | 99 | Before continuing, make sure git status shows this:: 100 | 101 | On branch main 102 | Your branch is up to date with 'origin/main'. 103 | 104 | nothing to commit, working tree clean 105 | 106 | 107 | In the next section, you will learn how to view your commit log. 108 | -------------------------------------------------------------------------------- /tutorials/git-intro.rst: -------------------------------------------------------------------------------- 1 | .. _tutorial-git-intro: 2 | 3 | Git Tutorial - Introduction to Git 4 | ================================== 5 | 6 | In many of your CS classes, you will use a system called Git to manage code. 7 | In a nutshell, you can think of Git as a system for tracking changes to your code, storing your code on a remote server, 8 | sharing your code with the course staff, and, eventually, in later courses, internships, and jobs, for working collaboratively with others. 9 | 10 | More specifically, Git is a version control system that tracks your 11 | files as well as changes that you made to those files. While you may 12 | already be familiar with software, such as Microsoft Word, that allows 13 | you to revert to earlier versions, Git is a tool that lets you group a 14 | set of related changes-- adding a feature, fixing a bug, etc.-- into a 15 | single *commit*. A commit is a checkpoint that represents all of the 16 | changes made since the previous checkpoint. This mechanism makes it 17 | possible to look at and even revert to older versions of a file (or 18 | collection of files) by going back to your code as it was when you 19 | “checkpointed” it with a commit. These commits, along with your 20 | actual files make up a *repository*. 21 | 22 | In this tutorial, you will learn how to: 23 | 24 | #. set up your local Git configuration, 25 | #. create and work with a local Git repository, 26 | #. set up your account on GitHub, a web-based hosting service, 27 | #. link a local repository with a remote repository on GitHub, 28 | #. work from multiple locations, 29 | #. use Git to work collaboratively, 30 | #. work with multiple branches, 31 | #. merge different branches, and 32 | #. handle the kinds of conflicts that arise when multiple people work on the same repository. 33 | 34 | The different sections build upon each other, so please plan to 35 | complete them in the order listed. The last few topics are fairly 36 | advanced and are not relevant to all students. Please check the 37 | instructions you received from your instructor(s) to determine which 38 | sections you need to complete. 39 | 40 | Where to Run This Tutorial 41 | -------------------------- 42 | 43 | This tutorial needs to be completed on a CS Linux server. If you are 44 | not already logged in, open a terminal window and log into one of CS 45 | Linux servers using SSH. (If your course has a bank of servers 46 | assigned to it, make sure to use your assigned server.) More 47 | information on SSH can be found in the `Remote SSH Access `__ tutorial. 48 | 49 | Once you are logged in to your CS Linux server run:: 50 | 51 | $ cd 52 | 53 | to ensure that you are in your home directory. (Recall that we use 54 | ``$`` to indicate work to be done at the Linux command line.) 55 | 56 | Configuring Git 57 | --------------- 58 | 59 | Before creating your first repository, it is a good idea to register 60 | your name and email address with Git using the following commands:: 61 | 62 | $ git config --global user.name "YOUR NAME" 63 | $ git config --global user.email "YOUR UCHICAGO EMAIL ADDRESS" 64 | 65 | Replace ``"YOUR NAME"`` with your name in quotes in the first command 66 | and ``"YOUR UCHICAGO EMAIL ADDRESS"`` with your UChicago email address 67 | in quotes in the second command. 68 | 69 | Git stores this information in a hidden file named ``.gitconfig`` in your 70 | home directory. You can see the contents of this file using the command:: 71 | 72 | $ cat .gitconfig 73 | 74 | or you can run the command:: 75 | 76 | $ git config --list 77 | 78 | The output from this command may include a few other values. You can 79 | ignore them. 80 | 81 | Verify that your name (``user.name``) and email address 82 | (``user.email``) are correct. If you mistyped your name or email 83 | address, you can rerun the appropriate ``git config`` command with the 84 | correct information. 85 | 86 | Once the values are set correctly, you will not need to run these 87 | commands again on the CS Linux machines. 88 | 89 | 90 | .. _tutorial-git-materials: 91 | 92 | Getting The Tutorial Materials 93 | ------------------------------ 94 | 95 | To get the materials you will use for this tutorial, run:: 96 | 97 | $ wget -nv https://uchicago-cs.github.io/student-resource-guide/_static/git-tutorial.zip 98 | $ unzip git-tutorial.zip 99 | 100 | The first command, ``wget``, downloads a compressed directory (aka, 101 | folder) from the web. The second, ``unzip``, decompresses it. 102 | 103 | Once you have completed these commands, you should have a directory 104 | named ``git-tutorial``. In your terminal window, navigate to the 105 | ``git-tutorial`` directory using ``cd``:: 106 | 107 | $ cd git-tutorial 108 | 109 | and run ``ls`` to view the contents of the directory. It should 110 | contain two files: ``hello.py``, and ``hola.py``. The first is a 111 | simple Python program to print a few greetings in English. The second 112 | is a simple Python program to print the same greetings in Spanish. 113 | 114 | The `next section of the tutorial `_ covers 115 | creating and working with a local Git repository. 116 | 117 | **Acknowledgments**: This tutorial is based, in part, on lecture notes 118 | prepared by Borja Sotomayor, and in part, based on a Git lab 119 | originally written for CMSC 12100 by Anne Rogers, and improved by 120 | numerous TAs over the years. The content in 121 | :ref:`tutorial-git-branches` section is based on materials 122 | originally written by Isha Mehrotra (SB'19) for CMSC 22000. 123 | -------------------------------------------------------------------------------- /tutorials/git-local.rst: -------------------------------------------------------------------------------- 1 | .. _tutorial-git-local: 2 | 3 | Git Tutorial - Working Locally 4 | ============================== 5 | 6 | .. note:: 7 | 8 | This section assumes you have: 9 | 10 | - picked up the :ref:`tutorial materials `, 11 | - opened a terminal window and connected to one of the CS Linux servers, and 12 | - navigated to your ``git-tutorial`` directory. 13 | 14 | 15 | This section explains how to convert an existing directory into a Git 16 | repository and how to package up changes into a commit. 17 | 18 | Converting an existing directory into a repository 19 | -------------------------------------------------- 20 | 21 | The first step when placing a directory under version control using Git 22 | is to run the git initialization command from within the directory. 23 | Use ``pwd`` to make sure that you are in your 24 | ``/home/CNETID/git-tutorial`` directory. Once you are in the 25 | right directory, run:: 26 | 27 | $ git init 28 | 29 | The result should be:: 30 | 31 | Initialized empty Git repository in /home/CNETID/git-tutorial/.git/ 32 | 33 | (If the directory listed in the result is something other than 34 | ``/home/CNETID/git-tutorial/.git/``, please ask for help.) 35 | 36 | This command creates a hidden folder, named ``.git``, used by Git to 37 | track the state of the repository. Notice that the message indicates 38 | that the repository is empty, which may be surprising given that the 39 | directory holds two files. This seeming anomaly illustrates a 40 | fundamental aspect of working with Git: Git's understanding of the 41 | state of the repository and the actual state of the files in the file 42 | system are not always the same. This section explains the commands needed 43 | to bring Git's view of the files up to date. 44 | 45 | Here is a figure that shows the contents of the files in the file 46 | system and Git's view of those files. 47 | 48 | .. figure:: img/git-local-1.png 49 | :align: center 50 | :width: 100% 51 | 52 | The Git repository side of the figure has four areas: 53 | 54 | - the list of commits, 55 | - the latest version of the files (from Git's perspective), 56 | - a list of files that are staged to be part of the next commit, and 57 | - a list of untracked files. 58 | 59 | The first three are empty, since we have not committed anything to the 60 | repository yet. The untracked files section lists files that exist in 61 | the directory, but that have not been placed under Git's control. In 62 | this case, the "Untracked files" section includes ``hello.py`` and 63 | ``hola.py`` because they exist in the directory and have not been 64 | placed under Git's control. 65 | 66 | The ``git status`` command will allow you view to some of the 67 | information shown in this figure. Here is the result of running this 68 | command immediately after initializing the repository:: 69 | 70 | $ git status 71 | On branch master 72 | 73 | No commits yet 74 | 75 | Untracked files: 76 | (use "git add ..." to include in what will be committed) 77 | hello.py 78 | hola.py 79 | 80 | nothing added to commit but untracked files present (use "git add" to track) 81 | 82 | The first line contains the name of the branch: 83 | ``master``. We'll change this name to the more commonly used name 84 | ``main``, in a few steps. 85 | 86 | The next line tells us that no commits have been added to this 87 | repository yet and that there are two files in the directory that Git 88 | is not tracking yet. Notice that Git provides a helpful hint about how to 89 | add the files to the list of files that will be part of the next 90 | commit. 91 | 92 | We'll take advantage of this hint in a minute. First, it is important 93 | to understand that creating a commit is a two step process. 94 | 95 | First, you need to *stage* the files that you want to be part of the commit 96 | and then, once you have staged the right set of files, you need to 97 | create the actual commit. 98 | 99 | The command for staging a file for the next commit is ``git add``. 100 | (Yes, it is somewhat confusing that the add command does not directly 101 | add files to the repository.) 102 | 103 | We can stage files for a commit one at a time or in a batch. Here is 104 | the command to add (stage) both of our files at once:: 105 | 106 | $ git add hello.py hola.py 107 | 108 | This command is silent, meaning it does not generate any output when 109 | it runs successfully. 110 | 111 | We can run ``git status`` to verify that Git's view of the files has 112 | changed:: 113 | 114 | $ git status 115 | On branch master 116 | 117 | No commits yet 118 | 119 | Changes to be committed: 120 | (use "git rm --cached ..." to unstage) 121 | new file: hello.py [text is green in actual output] 122 | new file: hola.py [text is green in actual output] 123 | 124 | Notice that ``hello.py`` and ``hola.py`` have moved from the 125 | "Untracked files" section to the new section "Changes to be committed", 126 | which holds the files that have been staged to be part of the next 127 | commit. 128 | 129 | Here is a figure that shows Git's updated view of the repository: 130 | 131 | .. figure:: img/git-local-2.png 132 | :align: center 133 | :width: 100% 134 | 135 | 136 | Now that the files are staged, we can package them into a commit using 137 | the ``git commit`` command. Each commit has an associated commit 138 | message. These messages should be descriptive enough to help you (and 139 | your collaborators) find specific versions as needed. Short commit 140 | message can be provided as part of the commit command using the ``-m`` 141 | flag. 142 | 143 | .. warning:: 144 | 145 | If you forget the ``-m`` parameter, Git will think that you forgot 146 | to specify a commit message. It will graciously open up a default 147 | editor so that you can enter such a message. This behavior can be 148 | useful if you want to enter a longer commit message (including 149 | multi-line messages), but is irritating most of the time. 150 | 151 | Here is the result of committing our staged files:: 152 | 153 | $ git commit -m"Added Python files" 154 | [master (root-commit) e1d3a0f] Add Python files 155 | 2 files changed, 6 insertions(+) 156 | create mode 100644 hello.py 157 | create mode 100644 hola.py 158 | 159 | If you run this command, your result will look slightly different. In 160 | particular, your result will have a different value in place of 161 | ``e1d3a0f``. 162 | 163 | Here is the result of running ``git status`` after the commit:: 164 | 165 | $ git status 166 | On branch master 167 | nothing to commit, working tree clean 168 | 169 | This message tells us that Git's view of the files and the actual 170 | files in the file system are in sync. 171 | 172 | Here's a figure that provides a more complete view of Git's updated 173 | view of the repository: 174 | 175 | .. figure:: img/git-local-3.png 176 | :align: center 177 | :width: 100% 178 | 179 | 180 | Notice as expected: 181 | 182 | - a commit has been created, 183 | - the files are the same in Git and on the file system, and 184 | - there are no untracked files and no files staged for commit. 185 | 186 | The file system and Git are now in sync. 187 | 188 | Now that we have created a commit, we can rename the branch to 189 | ``main`` using the following command:: 190 | 191 | $ git branch -M main 192 | 193 | This command does not generate any output and only needs to be run 194 | *once* per repository. We can verify that it ran successfully using 195 | ``git status``:: 196 | 197 | $ git status 198 | On branch main 199 | nothing to commit, working tree clean 200 | 201 | Notice that the branch name has changed from ``master`` to ``main``, 202 | which is the name that is now commonly used for the primary branch. 203 | 204 | In the first few sections of this tutorial, you will be working with 205 | the ``main`` branch. We introduce branches more generally in a later 206 | section. 207 | 208 | 209 | Changing tracked files 210 | ---------------------- 211 | 212 | Let's make a change to the files to fix the capitalization in 213 | ``hola.py``. Using an editor, change ``h`` to ``H`` in all three 214 | print statements. (Make sure to save your changes.) 215 | 216 | As this figure illustrates, once you modify the file on disk, Git's 217 | view of the file becomes out-of-date: 218 | 219 | 220 | .. figure:: img/git-local-4.png 221 | :align: center 222 | :width: 100% 223 | 224 | Notice that the file system version of ``hola.py`` and Git's view are 225 | different. This difference is highlighted in the figure with an 226 | exclamation point. Using ``git status`` this change is reflected 227 | in a new section named "Changes not staged for commit":: 228 | 229 | 230 | $ git status 231 | On branch main 232 | Changes not staged for commit: 233 | (use "git add ..." to update what will be committed) 234 | (use "git restore ..." to discard changes in working directory) 235 | modified: hola.py 236 | 237 | no changes added to commit (use "git add" and/or "git commit -a") 238 | 239 | To get the repository back up to date, we need to stage the changed 240 | file (again) and we need to create the commit. There are two ways to 241 | stage the file. We can explicitly add the file using:: 242 | 243 | $ git add hola.py 244 | 245 | or we can use a git shortcut:: 246 | 247 | $ git add --update . 248 | 249 | The ``--update`` flag for the ``git add`` command tells Git to stage 250 | files that it is tracking *and* that have changed since the last 251 | commit. The period tells Git to add only 252 | files in the current directory (and its subdirectories). Technically, 253 | the period is optional, but it is good practice to be thoughtful about 254 | adding files to your repository. In this case, being thoughtful means 255 | limiting the scope of the ``add`` command to the current directory. 256 | 257 | You can also use the ``-u`` as the short form of the ``--update`` flag:: 258 | 259 | $ git add -u . 260 | 261 | On a related note, **never** use either of the following two commands:: 262 | 263 | $ git add * # NEVER DO THIS 264 | $ git add . # OR THIS 265 | 266 | These commands add *everything* in the current directory (including 267 | files in subdirectories), which will likely add files, such as, editor 268 | backup files, large data files, etc, that should not be stored in a 269 | repository. Again, you should also be thoughtful about the files that 270 | you choose to include in your repository. 271 | 272 | Let's package this change into a commit:: 273 | 274 | $ git add --update . 275 | $ git commit -m"Forgot to capitalize in Spanish version" 276 | [master 94be5be] Forgot to capitalize in Spanish version 277 | 1 file changed, 3 insertions(+), 3 deletions(-) 278 | 279 | 280 | Now the two views of the files are in sync: 281 | 282 | .. figure:: img/git-local-5.png 283 | :align: center 284 | :width: 100% 285 | 286 | and the status is clean:: 287 | 288 | $ git status . 289 | On branch main 290 | nothing to commit, working tree clean 291 | 292 | Notice that we added a space and a period to the ``git status`` 293 | command to indicate that we are only interested in looking at the 294 | status of the files in the current directory (including any 295 | subdirectories). In a large repository, it can be useful to focus 296 | your attention on the current directory. 297 | 298 | 299 | Exercises 300 | --------- 301 | 302 | Modifying Existing Files 303 | ~~~~~~~~~~~~~~~~~~~~~~~~ 304 | 305 | In this exercise, you will make some changes to the files and 306 | package them up into a commit. 307 | 308 | **Step 1**: 309 | 310 | Add the line:: 311 | 312 | print("Hello, multiverse!") 313 | 314 | to the end of ``hello.py`` and the line:: 315 | 316 | print("Hola, multiverso!") 317 | 318 | to the end of ``hola.py``. Make sure to save the files after you make the necessary changes. 319 | 320 | **Step 2** 321 | 322 | Run ``git status .`` to see the current state of the files. Both 323 | ``hello.py`` and ``hola.py`` should appear in the "Changes not staged 324 | for commit" section of the output. If one or both are missing, verify that 325 | you saved the files. 326 | 327 | An aside: the Linux `cat` command is useful for looking at small 328 | files. For example, we could check the changes to ``hello.py`` by 329 | running:: 330 | 331 | $ cat hello.py 332 | print("Hello!") 333 | print("Hello, world!") 334 | print("Hello, universe!") 335 | print("Hello, multiverse!") 336 | 337 | Getting in the habit of frequently running ``git status .`` and 338 | verifying that the results match your expectations will reduce 339 | the likelihood that you run into problems with Git. 340 | 341 | **Step 3** 342 | 343 | Stage the files for commit using ``git add -u .``. 344 | 345 | Then use ``git status .`` to verify that the changed files are now staged. 346 | 347 | **Step 4** 348 | 349 | Commit the files using ``git commit``. Don't forget to include the 350 | ``-m`` flag and a commit message in double quotes (such as, ``"Added more 351 | salutations"``). 352 | 353 | Again, use ``git status .`` to verify that the commit has been 354 | completed. Does the result say ``"nothing to commit, working tree 355 | clean"`` or does it show one or more changes not staged for commit? 356 | 357 | 358 | Adding a New File 359 | ~~~~~~~~~~~~~~~~~ 360 | 361 | In this exercise, you will create a new file and add it to the 362 | repository: 363 | 364 | **Step 1** 365 | 366 | Create a new file named ``bonjour.py`` with the contents:: 367 | 368 | print("Bonjour!") 369 | print("Bonjour le monde!") 370 | print("Bonjour l’univers!") 371 | print("Bonjour multivers!") 372 | 373 | Make sure to save your changes! 374 | 375 | **Step 2** 376 | 377 | Run ``git status .`` to verify that there is now a new untracked file 378 | named ``bonjour.py`` in the directory. 379 | 380 | **Step 3** 381 | 382 | Use ``git add bonjour.py`` to add the file to the repository. 383 | 384 | **Step 4** 385 | 386 | Use ``git status .`` to verify that the file has been staged for the next commit. 387 | 388 | **Step 5** 389 | 390 | Create a new commit. Don't forget the ``-m`` option and the commit 391 | message in double quotes, such as ``"Added French version"``. 392 | 393 | **Step 6** 394 | 395 | Use ``git status .`` to verify that your working tree is now clean. 396 | 397 | 398 | Summary 399 | ------- 400 | 401 | This section of the tutorial introduced you to the commands needed to 402 | create and manage a git repository locally. The next section will 403 | explain how to setup your GitHub account. 404 | 405 | -------------------------------------------------------------------------------- /tutorials/git-multiple-locations.rst: -------------------------------------------------------------------------------- 1 | .. _tutorial-git-multiple-locations: 2 | 3 | Git Tutorial - Working from Multiple Locations 4 | ============================================== 5 | 6 | .. note:: 7 | 8 | This section assumes you have: 9 | 10 | - completed the :ref:`tutorial-git-discarding-changes` section of the tutorial, 11 | - opened a terminal window and connected to one of the CS Linux servers, and 12 | - navigated to your ``git-tutorial`` directory. 13 | 14 | 15 | Thus far, you have a local repository in your CS home directory and a 16 | remote copy on GitHub. And you have learned that you can keep these 17 | up to date using add, commit, and push and how to restore and unstage 18 | files. 19 | 20 | 21 | If you wanted work from multiple locations (e.g., on a CS machine but 22 | also from your laptop), you would need to to create a copy of the 23 | repository in those locations as well. You can do this by running the 24 | ``git clone`` command (don’t run this command just yet): 25 | 26 | :: 27 | 28 | $ git clone git@github.com:GITHUB_USERNAME/git-tutorial.git # Do NOT run yet 29 | 30 | This command will create a local "clone" of the repository that is 31 | currently stored on GitHub. For the purposes of this tutorial, we'll 32 | create this second copy in a separate directory of the same machine 33 | where you've been running Git commands so far. 34 | 35 | Open a second terminal window and connect to the same Linux server, 36 | and run the following: 37 | 38 | :: 39 | 40 | $ mkdir -p /tmp/$USER 41 | $ cd /tmp/$USER 42 | $ git clone git@github.com:GITHUB_USERNAME/git-tutorial.git 43 | 44 | Make sure to replace ``GITHUB_USERNAME`` with your GitHub username! 45 | (The string ``$USER`` will be automatically replaced with your 46 | username (that is, your CNetID)). 47 | 48 | When you run ``git clone``, the repository is not cloned *into* the 49 | current directory. Instead, a *new* directory (with the same name as 50 | the repository) will be created in the current directory, and you will 51 | need to ``cd`` into it to use Git commands for that repository: 52 | 53 | :: 54 | 55 | $ cd git-tutorial 56 | 57 | You now have two local copies of the repository: one in your home 58 | directory (``/home/CNETID/git-tutorial``), which we will refer to 59 | as your *home* repository for now and one in ``/tmp`` 60 | (``/tmp/CNETID/git-tutorial``) which we will refer to as your 61 | *temp* repository. 62 | 63 | Switch to the window that is open to your home repository, create a 64 | file name ``text.txt`` using ``echo``:: 65 | 66 | $ echo "A test file" > test.txt 67 | 68 | (Don't know what ``echo`` does? Run ``man echo`` at the Linux command 69 | line to learn more about it.) 70 | 71 | 72 | Now create a commit with this new file and push the commit to GitHub. 73 | If you are unsure how to create or push the commit look back through 74 | the earlier sections or ask for help. 75 | 76 | Next, switch to the window that is open to your temp repository, check 77 | to see if ``test.txt`` appears when you do an ``ls``. It will not, 78 | because you have not yet downloaded the latest commits from the 79 | repository. You can do this by running this command: 80 | 81 | :: 82 | 83 | $ git pull 84 | 85 | The output of this command should look something like this: 86 | 87 | :: 88 | 89 | 90 | remote: Enumerating objects: 4, done. 91 | remote: Counting objects: 100% (4/4), done. 92 | remote: Compressing objects: 100% (1/1), done. 93 | remote: Total 3 (delta 1), reused 3 (delta 1), pack-reused 0 94 | Unpacking objects: 100% (3/3), 265 bytes | 265.00 KiB/s, done. 95 | From github.com:ar0r-student/git-tutorial 96 | 0864622..58651e3 main -> origin/main 97 | Updating 0864622..58651e3 98 | Fast-forward 99 | test.txt | 1 + 100 | 1 file changed, 1 insertion(+) 101 | create mode 100644 test.txt 102 | 103 | Now when you do an ``ls`` the file ``test.txt`` will appear. 104 | 105 | 106 | -------------------------------------------------------------------------------- /tutorials/git-prepare-github.rst: -------------------------------------------------------------------------------- 1 | .. _tutorial-git-prepare-github: 2 | 3 | Git Tutorial - Preparing to use GitHub 4 | ====================================== 5 | 6 | .. note:: 7 | 8 | This section assumes you have opened you have an open terminal window connected to one of the CS Linux servers. 9 | 10 | 11 | In this section, you will do the work necessary to use GitHub. Specifically, you will: 12 | 13 | - Create a GitHub account (if needed), 14 | - Create an SSH key using one the CS Linux servers, and 15 | - Upload that key to GitHub. 16 | 17 | 18 | Creating a GitHub Account 19 | ------------------------- 20 | 21 | If you do not yet have one, you can get a GitHub account here: 22 | https://github.com/join. We encourage you to use your CNetID as your 23 | GitHub account name, if possible. If that name is already taken, try 24 | using your CNetID as a prefix in your Github username. 25 | 26 | 27 | Setting up SSH Access 28 | --------------------- 29 | 30 | The next step is to create an SSH key and upload it to GitHub, which 31 | will allow you to access your GitHub repositories from the terminal. 32 | 33 | While these steps may seem a bit intricate, you only need to do them 34 | once for the CS Linux machines. If at some later date, you want to 35 | access your repository from a different computer (e.g. your personal 36 | computer), you will have to create a new SSH key and upload it to 37 | GitHub. 38 | 39 | As in the previous sections, these commands should be run in a 40 | terminal window that is connected to one of the CS Linux servers. It 41 | is best to do the next few steps in your home directory, so run:: 42 | 43 | $ cd 44 | 45 | to ensure that you are in your home directory rather than in your 46 | ``git-tutorial`` directory. 47 | 48 | Creating an SSH Key 49 | ~~~~~~~~~~~~~~~~~~~ 50 | 51 | When you log into the GitHub website, you will use the username and 52 | password associated with your GitHub account. When using 53 | Git commands from the terminal, however, things are a bit different. 54 | In particular, GitHub uses two mechanisms for authenticating yourself 55 | from the terminal: Personal Access Tokens and SSH Keys. We will 56 | be using SSH keys. 57 | 58 | In a nutshell, an SSH key is a file that resides in your home directory, 59 | which you can think of as a file that stores a secure password. 60 | (SSH keys are a bit more complex than that but, for our purposes, 61 | we can just think of them as extra-secure passwords.) 62 | 63 | To create an SSH key, run the following command from the terminal:: 64 | 65 | $ ssh-keygen -t ed25519 -C "CS Linux Server SSH Key" 66 | 67 | (As an aside, Ed25519 is a public-key signature system. It is more 68 | secure than RSA, which may be more familiar to some of you.) 69 | 70 | You will see the following prompt:: 71 | 72 | Generating public/private ed25519 key pair. 73 | Enter file in which to save the key (/home/ar0r/.ssh/id_ed25519): 74 | 75 | Press Enter. This will select the default file path shown in the prompt: ``/home/CNETID/.ssh/id_ed25519``. 76 | 77 | .. note:: 78 | 79 | If, after pressing Enter, you see the following message:: 80 | 81 | /home/CNETID/.ssh/id_ed25519 already exists. 82 | Overwrite (y/n)? 83 | 84 | This means there is already an Ed25519 SSH key in your home directory. 85 | You should proceed as follows: 86 | 87 | 1. If you are already familiar with SSH keys, and know for certain 88 | that you'd like to use your existing Ed25519 SSH key, type "n" and 89 | skip ahead to the :ref:`Uploading your SSH key to GitHub ` section below. 90 | 2. If you do not know why you have an Ed25519 SSH key in your directory, 91 | it's possible it was created for you if you've taken another 92 | CS class in the past. Type "n" and then run the following commands 93 | to create a backup of your existing key:: 94 | 95 | $ mv ~/.ssh/id_ed25519 ~/.ssh/id_ed25519.bak 96 | $ mv ~/.ssh/id_ed25519.pub ~/.ssh/id_ed25519.pub.bak 97 | 98 | Then, re-run the ``ssh-keygen`` command and press Enter when prompted 99 | for the file name, and follow the rest of the 100 | instructions in this section. 101 | 102 | Next, you will see this prompt:: 103 | 104 | Enter passphrase (empty for no passphrase): 105 | 106 | Just press Enter here. You will be asked to confirm (just press Enter again):: 107 | 108 | Enter same passphrase again: 109 | 110 | .. note:: 111 | 112 | While it may seem counterintuitive, we don't want our SSH 113 | key to have a passphrase (this is an added layer of security that we don't 114 | need here; your GitHub account will still be secure even if your 115 | SSH key doesn't have a password). 116 | 117 | If all goes well, you should see something like this:: 118 | 119 | Your identification has been saved in /home/ar0r/.ssh/id_ed25519 120 | Your public key has been saved in /home/ar0r/.ssh/id_ed25519.pub 121 | The key fingerprint is: 122 | SHA256:CvLPtFFx70iR3Fas2o0pmbnWwQ8gJSVke8FmWzzPmhU CS Linux Server SSH Key 123 | The key's randomart image is: 124 | +--[ED25519 256]--+ 125 | | .+oo. .. | 126 | | ..+=++.E | 127 | | o=*oo= . | 128 | | .+o+. + | 129 | | . . S..O.B | 130 | | o . o .*oX . | 131 | | . + .+.+ | 132 | | + o o . . | 133 | | + . | 134 | +----[SHA256]-----+ 135 | 136 | This means your key was created correctly. 137 | 138 | 139 | .. _uploading: 140 | 141 | Uploading Your SSH Key to GitHub 142 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 143 | 144 | Now, you need to instruct GitHub to accept your SSH key. To do this, log into https://github.com/ 145 | and go to your Settings page by clicking on the top-right account icon, and then selecting "Settings" 146 | in the drop-down menu. Then, click on "SSH and GPG keys". 147 | 148 | Now, click on the green "New SSH key" button. This will take you to a page where you can upload your 149 | SSH key: 150 | 151 | .. figure:: img/github-ssh-key.png 152 | :alt: "SSH keys / Add new" page on GitHub 153 | 154 | You will be asked for three values: a title, a key type, and the key 155 | itself. The title can be anything you want, but we suggest something 156 | like "CS Linux Server SSH Key". Choose ``Authentication Key`` from 157 | the drop down menu for the key type. 158 | 159 | The value of the key is contained in the ``.ssh/id_ed25519.pub`` file in your home directory. To print 160 | out the contents of that file, we can just use the ``cat`` command:: 161 | 162 | $ cat ~/.ssh/id_ed25519.pub 163 | 164 | This will print a few lines of output starting with ``ssh-ed25519`` and 165 | ending with ``CS Linux Server SSH Key``. Copy the whole output 166 | to the clipboard; you can do this by clicking and dragging the mouse 167 | from the first character to the last character, and then pressing 168 | ``Ctrl-Shift-C`` (``Cmd-C`` for MacOS users). 169 | 170 | Then, paste the key into the "Key" field on the GitHub page. Then click on the green "Add SSH Key" 171 | button. 172 | 173 | To verify that you correctly uploaded the key, try running the following command:: 174 | 175 | $ ssh -T git@github.com 176 | 177 | You may see a message like this:: 178 | 179 | The authenticity of host 'github.com (140.82.114.4)' can't be established. 180 | ECDSA key fingerprint is SHA256:p2QAMXNIC1TJYWeIOttrVc98/R1BUFWu3/LiyKgUfQM. 181 | Are you sure you want to continue connecting (yes/no/[fingerprint])? 182 | 183 | You can safely enter "yes" here. You should then see a message like this:: 184 | 185 | Hi username! You've successfully authenticated, but GitHub does 186 | not provide shell access. 187 | 188 | This means your SSH key is properly set up. Don't worry about the "does not provide shell access," that is 189 | normal. 190 | 191 | If you are unable to set up your SSH key, please make sure to ask for help. You will not 192 | be able to complete the rest of the tutorial until you've set up your SSH key. 193 | 194 | 195 | 196 | Summary 197 | ------- 198 | 199 | In this section, you set up your GitHub account for use from the CS 200 | Linux servers. In the next section, you will create a repository on 201 | Git and link it to the local repository (``git-tutorial``) that you 202 | created in the previous section. 203 | -------------------------------------------------------------------------------- /tutorials/git-remote.rst: -------------------------------------------------------------------------------- 1 | .. _tutorial-git-remote: 2 | 3 | Git Tutorial - Working with Remote Repositories 4 | ================================================ 5 | 6 | .. note:: 7 | 8 | This section assumes you have: 9 | 10 | - completed the :ref:`tutorial-git-local` and :ref:`tutorial-git-prepare-github` sections of the tutorial and 11 | - opened a terminal window that is connected to one of the CS Linux servers. 12 | 13 | 14 | In the :ref:`tutorial-git-local` section, we covered how to convert an 15 | existing directory into a repository and how to create commits. In 16 | this part, you will learn how to link up your repository with GitHub. 17 | 18 | 19 | Creating a Repository on GitHub 20 | ------------------------------- 21 | 22 | To link our local repository to a repository on GitHub, we need to 23 | first create an empty repository on GitHub. To do this, log into 24 | GitHub, and click on the "+" icon on the top-right of the page, and 25 | then on "New Repository": 26 | 27 | .. image:: img/new-repository.png 28 | :align: center 29 | 30 | Then, under "Repository name" enter ``git-tutorial``. Do not 31 | change any other setting, and click on the green "Create repository" 32 | button. 33 | 34 | .. image:: img/github-git-tutorial-1.png 35 | :align: center 36 | :width: 100% 37 | 38 | 39 | Note that you will see your GitHub username rather than 40 | ``ar0r-student`` underneath ``Owner``. 41 | 42 | Once you complete this step, you will be taken to a page where you can 43 | browse your repository through GitHub’s web interface. To start, this 44 | page will include instructions for setting up a new repository and for 45 | connecting an existing repository (our case). 46 | 47 | .. image:: img/github-git-tutorial-2.png 48 | :align: center 49 | :width: 100% 50 | 51 | Since we want to link an existing local repository to this new remote 52 | repository on GitHub, we fall into the second case. 53 | 54 | In your terminal window, verify that you are in your ``git-tutorial`` 55 | directory using ``pwd`` and if, not navigate to it. 56 | 57 | The first step is to set the URL (that is, the Uniform Resource 58 | Locator) for the remote repository. To do so, copy and run the first 59 | line in the "..or push an existing repository from the command line" 60 | section of the setup page. The command will have the form:: 61 | 62 | $ git remote add origin URL 63 | 64 | where URL is the URL for your repository. Copy-and-paste the line from 65 | your browser instead of retyping it to reduce the likelihood that you 66 | make a mistake when entering it. This command does not generate any 67 | output. 68 | 69 | The URL should start with ``git@github.com:``. If the URL starts with 70 | ``http://`` instead, please ask for help. 71 | 72 | You can verify that you did this step correctly by running:: 73 | 74 | $ git config --get remote.origin.url 75 | 76 | It should show the actual URL for your repository: 77 | :: 78 | 79 | git@github.com:GITHUB_USERNAME/git-tutorial.git 80 | 81 | where ``GITHUB_USERNAME`` is your actual GitHub username. If the 82 | result of this command does not look right, please ask for help. 83 | 84 | We have already set the branch name for ``git-tutorial``, so we 85 | can skip the next step in the instructions. 86 | 87 | Next, you need to push your local commits to the repository on GitHub using ``git push``:: 88 | 89 | $ git push -u origin main 90 | Enumerating objects: 14, done. 91 | Counting objects: 100% (14/14), done. 92 | Delta compression using up to 16 threads 93 | Compressing objects: 100% (14/14), done. 94 | Writing objects: 100% (14/14), 1.22 KiB | 1.22 MiB/s, done. 95 | Total 14 (delta 2), reused 0 (delta 0) 96 | remote: Resolving deltas: 100% (2/2), done. 97 | To github.com:GITHUB_USERNAME/git-tutorial.git 98 | * [new branch] main -> main 99 | Branch 'main' set up to track remote branch 'main' from 'origin'. 100 | 101 | You may be asked some variant of the following question:: 102 | 103 | Warning: the ECDSA host key for 'github.com' differs from the key for the IP address '140.82.114.3' 104 | Offending key for IP in /home/CNETID/.ssh/known_hosts:1 105 | Matching host key in /home/CNETID/.ssh/known_hosts:10 106 | Are you sure you want to continue connecting (yes/no)? 107 | 108 | If so, respond ``yes``. Unfortunately, you may get asked this 109 | question the next few times you use a command to interact with GitHub. 110 | It is safe to say yes. 111 | 112 | If you run ``git status`` in your terminal window after you have 113 | completed the push, you will see something like:: 114 | 115 | $ git status 116 | On branch main 117 | Your branch is up to date with 'origin/main'. 118 | 119 | nothing to commit, working tree clean 120 | 121 | which tells you that the local and remote copies of your repository 122 | are in sync. 123 | 124 | If you switch back to your browser and click on ``Code``, you should 125 | see something like this: 126 | 127 | .. image:: img/github-git-tutorial-3.png 128 | :align: center 129 | :width: 100% 130 | 131 | If you click on the names of the files, you will see that the contents of 132 | the files on GitHub is the same as the files in the copy of your 133 | repository on the CS Linux servers. 134 | 135 | If you click on ``commits``, you will be taken to a page that shows 136 | the commit log in reverse chronological order (that is, the most 137 | recent commit is shown first). 138 | 139 | 140 | .. image:: img/github-git-tutorial-4.png 141 | :align: center 142 | :width: 100% 143 | 144 | If you click on a specific commit, GitHub will show you the 145 | exact changes that were made. For example, clicking on 146 | the commit with the message ``"Forgot to capitalize in Spanish version"`` 147 | yields: 148 | 149 | .. image:: img/github-git-tutorial-5.png 150 | :align: center 151 | :width: 100% 152 | 153 | Lines starting with a ``-`` (shown with a red background) were 154 | removed. Lines starting with a ``+`` (shown with a green background) 155 | were added. 156 | 157 | 158 | Making Changes and Re-Synchronizing 159 | ----------------------------------- 160 | 161 | You now have two copies of your repository: one on the CS Linux 162 | servers and one on GitHub. Anyone who has permission to access your 163 | GitHub repository will be able to see the repository as it exists on 164 | GitHub. They will **not** be able to see changes that you have made 165 | locally until you push them. 166 | 167 | We'll explore this behavior in this section. Create a new 168 | file ``hej.py`` with the following contents:: 169 | 170 | print("Hej") 171 | print("Hej Verden") 172 | print("Hej Univers") 173 | print("Hej Multivers") 174 | 175 | 176 | and then create a commit for this file:: 177 | 178 | $ git add hej.py 179 | $ git commit -m"Added Danish version" 180 | 181 | If you run ``git status``, you will see a message that tells you that 182 | your local copy of the repository is "ahead" of the remote copy on 183 | GitHub by one commit:: 184 | 185 | $ git status . 186 | On branch main 187 | Your branch is ahead of 'origin/main' by 1 commit. 188 | (use "git push" to publish your local commits) 189 | 190 | 191 | If you switch to your browser and click on ``Code`` to get back to the 192 | code page, you will see that the repository on GitHub does not include 193 | ``hej.py``. To bring GitHub up to date, you need to push your work by 194 | running:: 195 | 196 | $ git push 197 | 198 | The output will be something like:: 199 | 200 | Enumerating objects: 4, done. 201 | Counting objects: 100% (4/4), done. 202 | Delta compression using up to 16 threads 203 | Compressing objects: 100% (3/3), done. 204 | Writing objects: 100% (3/3), 378 bytes | 378.00 KiB/s, done. 205 | Total 3 (delta 0), reused 0 (delta 0) 206 | To github.com:GITHUB_USERNAME/git-tutorial.git 207 | 208 | Now if you run ``git status`` it will show you that the two 209 | versions are in sync:: 210 | 211 | $ git status 212 | On branch main 213 | Your branch is up to date with 'origin/main'. 214 | 215 | nothing to commit, working tree clean 216 | 217 | If you refresh the browser page that is open to your 218 | ``git-tutorial`` repository on GitHub, you should now see 219 | ``hej.py``. 220 | 221 | .. image:: img/github-git-tutorial-6.png 222 | :align: center 223 | :width: 100% 224 | 225 | In general, synchronizing (aka, syncing) your local and remote 226 | repositories is a three step process: 227 | 228 | #. add/stage the new/changed files, 229 | #. create a commit, and then 230 | #. push the new commit to the server. 231 | 232 | **When you are first working with git, it is good practice to end 233 | every work session by syncing your local and remote repositories. 234 | Similarly, before you ask a question about your code in a class, you should sync your 235 | repository with GitHub to ensure that the course staff can see the 236 | most recent version of your code.** 237 | 238 | The more disciplined you are about frequently syncing your repository 239 | and verifying that your repository is in a clean state, the less 240 | likely it is that you will run into a difficult-to-fix Git problem. 241 | 242 | Exercise: Syncing a change with a remote repository 243 | --------------------------------------------------- 244 | 245 | Create a file named ``README.md`` that contains ``Git Tutorial`` 246 | and your name. Add this file to your local repository, create a 247 | commit, and sync it with GitHub. 248 | 249 | When you are finished, ``git status`` should show that your working 250 | tree is clean and up to date with ``origin/main`` and ``README.md`` 251 | should appear when you refresh the browser page that is open to your 252 | ``git-tutorial`` repository on GitHub. 253 | 254 | 255 | .. image:: img/github-git-tutorial-7.png 256 | :align: center 257 | :width: 100% 258 | 259 | If you need to take a break, this would be a good time to stop. 260 | 261 | 262 | Summary 263 | ------- 264 | 265 | In this section, you learned how to connect a local repository to a 266 | remote server, and learned how to push local changes to that server. 267 | The next section explains how to view the commit log. 268 | 269 | 270 | 271 | 272 | 273 | 274 | 275 | 276 | 277 | 278 | 279 | 280 | 281 | 282 | 283 | 284 | 285 | 286 | 287 | 288 | 289 | 290 | 291 | 292 | 293 | 294 | 295 | 296 | 297 | 298 | 299 | 300 | 301 | 302 | 303 | 304 | 305 | 306 | 307 | 308 | 309 | 310 | 311 | 312 | 313 | 314 | 315 | 316 | 317 | 318 | 319 | 320 | 321 | 322 | 323 | 324 | 325 | 326 | 327 | 328 | 329 | 330 | 331 | 332 | 333 | 334 | 335 | 336 | 337 | 338 | 339 | 340 | 341 | 342 | 343 | 344 | 345 | 346 | 347 | -------------------------------------------------------------------------------- /tutorials/img/git-local-1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/tutorials/img/git-local-1.png -------------------------------------------------------------------------------- /tutorials/img/git-local-2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/tutorials/img/git-local-2.png -------------------------------------------------------------------------------- /tutorials/img/git-local-3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/tutorials/img/git-local-3.png -------------------------------------------------------------------------------- /tutorials/img/git-local-4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/tutorials/img/git-local-4.png -------------------------------------------------------------------------------- /tutorials/img/git-local-5.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/tutorials/img/git-local-5.png -------------------------------------------------------------------------------- /tutorials/img/github-git-tutorial-1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/tutorials/img/github-git-tutorial-1.png -------------------------------------------------------------------------------- /tutorials/img/github-git-tutorial-2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/tutorials/img/github-git-tutorial-2.png -------------------------------------------------------------------------------- /tutorials/img/github-git-tutorial-3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/tutorials/img/github-git-tutorial-3.png -------------------------------------------------------------------------------- /tutorials/img/github-git-tutorial-4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/tutorials/img/github-git-tutorial-4.png -------------------------------------------------------------------------------- /tutorials/img/github-git-tutorial-5.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/tutorials/img/github-git-tutorial-5.png -------------------------------------------------------------------------------- /tutorials/img/github-git-tutorial-6.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/tutorials/img/github-git-tutorial-6.png -------------------------------------------------------------------------------- /tutorials/img/github-git-tutorial-7.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/tutorials/img/github-git-tutorial-7.png -------------------------------------------------------------------------------- /tutorials/img/github-ssh-key.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/tutorials/img/github-ssh-key.png -------------------------------------------------------------------------------- /tutorials/img/new-repository.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/tutorials/img/new-repository.png -------------------------------------------------------------------------------- /tutorials/linux-advanced.rst: -------------------------------------------------------------------------------- 1 | .. _tutorial-linux-advanced: 2 | 3 | Tutorial - Advanced Linux 4 | ========================= 5 | 6 | The Advanced Linux tutorial has been reorganized into smaller sections. 7 | Please see the left sidebar for links to specific sections (under "Linux Tutorials") -------------------------------------------------------------------------------- /tutorials/linux-basics.rst: -------------------------------------------------------------------------------- 1 | .. _tutorial-linux-basics: 2 | 3 | Tutorial - Linux Basics 4 | ======================= 5 | 6 | The Linux Basics tutorial has been reorganized into smaller sections. 7 | Please start the tutorial at :ref:`tutorial-linux-intro`. -------------------------------------------------------------------------------- /tutorials/linux-compile-and-run.rst: -------------------------------------------------------------------------------- 1 | .. _linux-compile-and-run: 2 | 3 | Linux Tutorial - Edit, Compile, and Run a Program 4 | ======================================================== 5 | 6 | .. note:: 7 | 8 | This section assumes you have :ref:`picked up the tutorial 9 | materials ` and that you have a :ref:`terminal 10 | window open ` to your ``linux-tutorial-files`` directory. 11 | 12 | 13 | In this section of the tutorial you will learn how to use 14 | the terminal to perform some basic operations in Linux, including how to: 15 | 16 | #. Use a terminal editor 17 | #. Use a graphical editor 18 | #. Edit/compile/run in the terminal 19 | 20 | Editing files 21 | ------------- 22 | 23 | In many of your classes, you will have to edit text files containing programming code. 24 | While there are many graphical editors you could use (either on a CS Linux environment, 25 | or on your own computer), it is also important to be familiar with *terminal editors* 26 | that run exclusively from a terminal and don't require a desktop environment. 27 | These editors can be particularly useful if you *only* have access to a terminal 28 | (e.g., if you're logging into a CS Linux server using SSH). 29 | 30 | Using a terminal editor 31 | ~~~~~~~~~~~~~~~~~~~~~~~ 32 | 33 | List the files in the ``linux-tutorial-files`` directory. You should see the following:: 34 | 35 | backups hello.c hello.cpp Hello.java hello.py my_echo.py my-input.txt test.txt 36 | 37 | If you do not see these files make sure you have grabbed materials from :ref:`Introduction to Linux `. 38 | 39 | Let's say we wanted to edit the file ``test.txt``. There are many different terminal 40 | editors we could use, but we will start with a simple and fairly intuitive one: ``nano``. 41 | To edit the file, run the following:: 42 | 43 | $ nano test.txt 44 | 45 | This will open the ``test.txt`` file in the nano editor, which will look something like this: 46 | 47 | .. image:: nano.png 48 | :align: center 49 | 50 | The way you interact with this editor will be very similar to how you use a text editor or 51 | a word processor in a graphical desktop environment: you can use the arrow keys to move 52 | around the text, and typing text will insert that text at the location of the cursor. 53 | You can also use the Backspace key to delete text. 54 | 55 | Try removing the text ``Firstname Lastname`` and replacing it with your name. Then, 56 | save the file by pressing Ctrl-O (i.e., the Control key and the O key at the same time). 57 | You will see the following prompt at the bottom of the screen:: 58 | 59 | File Name to Write: test.txt 60 | 61 | You can just press Enter to confirm you'd like to save the changes to the same file 62 | (however, you could also specify a different file). 63 | 64 | The bottom of the screen actually specifies some of the most common commands you 65 | can run in the editor. For example, ``^O Write Out`` refers to what we just did: 66 | Pressing Ctrl-O allows your "write out" (i.e., save) the file (a common abbreviation 67 | for the Control key is ``^``). 68 | 69 | Another common command is ``^X Exit``. Just press Control-X to exit the editor. 70 | 71 | While ``nano`` is a simple and intuitive editor, there are many other editors 72 | out there. If you're interested in a more powerful terminal editor, you 73 | may want to check out `Vim `__ or `Emacs `__. 74 | 75 | Using a graphical editor 76 | ~~~~~~~~~~~~~~~~~~~~~~~~ 77 | 78 | Visual Studio Code is a commonly utilized graphical editor. You can 79 | use Visual Studio Code if you are using a desktop environment like Windows 80 | or MacOS, or if you are logged into a CSIL computer. If you are using 81 | your personal computer, Visual Studio Code will also allow you to 82 | connect to the CS Linux servers using SSH. 83 | 84 | If you'd like to set up Visual Studio Code, please see the Visual Studio 85 | Code pages linked from the left sidebar, starting with :ref:`About VS Code ` 86 | 87 | 88 | The edit/compile/run cycle in the terminal 89 | ------------------------------------------ 90 | 91 | When writing code, you will very often go through several cycles 92 | of the edit/compile/run cycle: 93 | 94 | 1. Edit: You edit the source code file to add or modify some code. 95 | 2. Compile: You compile the code into a runnable executable (only in compiled 96 | languages; e.g., this step doesn't apply in Python). 97 | 3. Run: You run the executable to verify that the code you added/modified 98 | works as expected. 99 | 100 | We have previously covered how to edit files from the terminal, but 101 | now we'll see the basic commands to compile and run your code from the terminal. 102 | We have included four example programs in the tutorial files which you 103 | can use for this purpose: 104 | 105 | - ``hello.py`` (Python) 106 | - ``hello.c`` (C) 107 | - ``hello.cpp`` (C++) 108 | - ``Hello.java`` (Java) 109 | 110 | Compiling and Running Code Examples 111 | ----------------------------------- 112 | 113 | Work through the following subsections relevant to your course. 114 | You do not need to complete all subsections unless specified by your course. 115 | 116 | Python 117 | ~~~~~~ 118 | 119 | In Python, given a ``.py`` file, such as our ``hello.py`` file, we can run it from the terminal like this:: 120 | 121 | $ python3 hello.py 122 | Hello, world! 123 | 124 | 125 | **Exercise:** Try editing the file (e.g., change the message from ``Hello, world!`` to ``Hello, universe!``) 126 | and running the program again. You should now see the updated message. 127 | 128 | C 129 | ~ 130 | 131 | C is a *compiled* language, which means that we first need to compile our program 132 | to produce an executable file. For example, we can compile our ``hello.c`` program 133 | like this:: 134 | 135 | $ gcc hello.c -o hello 136 | 137 | We are using the ``gcc`` compiler, but some classes may use the ``clang`` compiler. 138 | The first parameter (``hello.c``) specifies the C file we want to compile, and 139 | the ``-o`` option specifies the executable file we want to produce. 140 | 141 | Running the above command will produce a ``hello`` file that you can run like this:: 142 | 143 | $ ./hello 144 | Hello, world! 145 | 146 | **Exercise:** Try editing ``hello.c`` (e.g., change the message from ``Hello, world!`` to ``Hello, universe!``). 147 | If you re-run ``./hello``, you'll see that the old message is still being printed out: 148 | this is because you need to compile the ``hello.c`` file to produce an updated executable. 149 | Once you do so, you should see the updated message when you run ``./hello`` 150 | 151 | C++ 152 | ~~~ 153 | 154 | The process for compiling/running programs in C++ is basically the same 155 | as in C, except we will use the ``g++`` compiler:: 156 | 157 | $ g++ hello.cpp -o hello++ 158 | $ ./hello++ 159 | Hello, world! 160 | 161 | 162 | Java 163 | ~~~~ 164 | 165 | Like C/C++, Java is a compiled language, although the Java compiler 166 | doesn't produce an executable in the same way that the C/C++ compiler 167 | does (we'll see why momentarily). 168 | 169 | To compile a Java file, you need to run this:: 170 | 171 | $ javac Hello.java 172 | 173 | Unlike the C/C++ example we just saw, this will actually produce a 174 | file called ``Hello.class`` that is not directly runnable from the terminal 175 | (i.e., running ``./Hello.class`` like we did in the C/C++ example won't 176 | work). Instead, we need to use the ``java`` command to run it:: 177 | 178 | $ java Hello 179 | Hello, world! 180 | 181 | Notice how we don't have to include the ``.class`` extension. 182 | 183 | **Exercise:** Try editing ``Hello.java`` (e.g., change the message from ``Hello, world!`` to ``Hello, universe!``). 184 | If you re-compile the file and run it again, you should see the updated message. 185 | 186 | You have finished the section on editing, compiling, and running 187 | programs. 188 | 189 | If you have been referred to this tutorial as part of a class you 190 | are taking, please move on to the next section required by your instructor. -------------------------------------------------------------------------------- /tutorials/linux-filesystem.rst: -------------------------------------------------------------------------------- 1 | .. _linux-file-system: 2 | 3 | Linux Tutorial - Navigating the filesystem 4 | ========================================== 5 | 6 | .. note:: 7 | 8 | This section assumes you have :ref:`picked up the tutorial 9 | materials ` and have a :ref:`terminal window 10 | open ` to your home directory. 11 | 12 | Files in Linux are stored in directories/folders, just like in 13 | macOS/Windows. Directories can hold files or other subdirectories and 14 | there is a special directory---your home directory---for your personal 15 | files: 16 | 17 | +------------------+------------------+-------------------+----------------------------------------+ 18 | | Name | Linux | Mac | Windows | 19 | +==================+==================+===================+========================================+ 20 | | Root directory | / | / | C:\\ | 21 | +------------------+------------------+-------------------+----------------------------------------+ 22 | | Home directory | /home/username | /Users/username | C:\\Documents and Settings\\username | 23 | +------------------+------------------+-------------------+----------------------------------------+ 24 | 25 | .. image:: filesystem.username.svg 26 | :align: center 27 | :width: 650 28 | :height: 250 29 | 30 | The figure above illustrates how Linux organizes the file system. Your 31 | own computer might have a slightly different organization 32 | (e.g., you might replace ``/`` with ``C:``), but the idea is the 33 | same. 34 | 35 | We think of the file system as a tree. It is traditional to draw 36 | the tree with the root of the file system at the top. We can also think of 37 | each directory and the files and subdirectories that it contains as a 38 | tree. 39 | 40 | For the above and from this point forward, consider that the text 41 | "username" is replaced with your own actual username, which is just 42 | your CNetID. 43 | 44 | .. note:: 45 | 46 | If you are connected to a CS machine, either because you're 47 | physically sitting at a CSIL machine or have logged in remotely 48 | via SSH, that machine is connected to a *network file system*. 49 | 50 | A network filesystem is logically one very large hard drive shared 51 | by all the CS machines. As a result, you will have access to your 52 | home directory and its contents regardless of what machine you 53 | use. 54 | 55 | For example, if you create some files while logged into a CSIL machine, 56 | and then sit at a different CSIL machine the next day (or SSH into the CS Linux servers), 57 | you will have acess to the exact same files on the new machine. 58 | 59 | 60 | Show Files 61 | ~~~~~~~~~~ 62 | 63 | As noted in the section on :ref:`opening a terminal window 64 | `, you will be in your home directory when you open a 65 | terminal window. 66 | 67 | Two very useful commands are ``pwd`` and ``ls``: 68 | 69 | +---------+--------------------------------------------------------------+ 70 | | ``pwd`` | Prints your current working directory - tells you where you | 71 | | | are in your directory tree. | 72 | +---------+--------------------------------------------------------------+ 73 | | ``ls`` | Lists all of the files in the current directory. | 74 | +---------+--------------------------------------------------------------+ 75 | 76 | The following is an example using these two commands in a terminal window:: 77 | 78 | username@computer:~$ pwd 79 | /home/username/ 80 | username@computer:~$ ls 81 | cs html linux-tutorial-files 82 | username@computer:~$ 83 | 84 | Try these commands yourself to verify that everything looks similar. 85 | 86 | The directory path and the list of files that you would see if you opened 87 | your home folder graphically are identical to those provided by 88 | ``pwd`` and ``ls``, respectively. The only difference is how you get 89 | the information, how the information is displayed, and how easy it is 90 | to write a script that, say, processes all the Python files in a 91 | directory. 92 | 93 | Change Directory 94 | ~~~~~~~~~~~~~~~~ 95 | 96 | +-------------------+--------------------------------------------------------------+ 97 | |``cd `` | change to the directory path-name | 98 | +-------------------+--------------------------------------------------------------+ 99 | | ``cd ..`` | move up/back one directory | 100 | +-------------------+--------------------------------------------------------------+ 101 | | ``cd`` | move to your home directory | 102 | +-------------------+--------------------------------------------------------------+ 103 | | ``cd -`` | move to the previous directory you were in | 104 | +-------------------+--------------------------------------------------------------+ 105 | 106 | How can we move around in the file system? If we were using a 107 | graphical system, we would double click on folders and occasionally 108 | click the "back" arrow. In order to change directories in 109 | the terminal, we use ``cd`` (change directory) followed by the name of 110 | the destination directory. (A note about notation: we will use text 111 | inside angle brackets, such as ```` as a place holder. The 112 | text informally describes the type of value that should be supplied. 113 | In the case of ````, the desired value is the path-name for 114 | a file or directory. More about path-names later.) For example if we want to 115 | change to the ``html`` directory, we type the following in the 116 | terminal:: 117 | 118 | username@computer:~$ cd html 119 | 120 | Here is an example of changing to the ``html`` directory in the terminal. 121 | We use ``pwd`` and ``ls`` to verify where we are and where we can go:: 122 | 123 | username@computer:~$ pwd 124 | /home/username/ 125 | username@computer:~$ ls 126 | cs html linux-tutorial-files 127 | username@computer:~$ cd html 128 | username@computer:~/html$ pwd 129 | /home/username/html/ 130 | username@computer:~/html$ ls 131 | 132 | username@computer:~/html$ 133 | 134 | Notice that after we ``cd`` into the ``html`` the command ``pwd`` now 135 | prints out:: 136 | 137 | /home/username/html/ 138 | 139 | rather than:: 140 | 141 | /home/username/ 142 | 143 | In the beginning, there are no files in the ``html`` directory, which is 144 | why the output of ``ls`` in this directory is empty. 145 | 146 | We can move up one step in the directory tree (e.g., from 147 | ``/home/username/html`` to ``/home/username`` or from 148 | ``/home/username`` to ``/home``) by typing ``cd ..`` Here "up" is 149 | represented by "``..``" In this context, this command will move us up 150 | one level back to our home directory:: 151 | 152 | username@computer:~/html$ pwd 153 | /home/username/html/ 154 | username@computer:~/html$ cd .. 155 | username@computer:~$ pwd 156 | /home/username/ 157 | 158 | Notice that the current working directory is also shown in the prompt string. 159 | 160 | +-------------------+--------------------------------------------------------------+ 161 | | ``~`` | shortcut for your home directory | 162 | +-------------------+--------------------------------------------------------------+ 163 | | ``.`` | shortcut for the current working directory | 164 | +-------------------+--------------------------------------------------------------+ 165 | | ``..`` |shortcut for one level up from your current working directory | 166 | +-------------------+--------------------------------------------------------------+ 167 | 168 | The tilde (~) directory is the same as your home directory: that is, ``~`` is shorthand for ``/home/username``. Here's another useful shorthand: a single dot (``.``) refers to the current directory. 169 | 170 | Usually when you use ``cd``, you will specify what is called a 171 | *relative* path, that is, you are telling the computer to take you to 172 | a directory where the location of the directory is described relative 173 | to the current directory. The only reason that the computer knows that 174 | we can ``cd`` to ``html`` is because ``html`` is a folder within 175 | the ``/home/username`` directory. But, if we use a ``/`` at the 176 | *beginning* of our path, we are specifying an absolute path or one 177 | that is relative to the the "root" or top of the file system. For 178 | example:: 179 | 180 | username@computer:~$ pwd 181 | /home/username/ 182 | username@computer:~$ cd /home/username/html 183 | username@computer:~/html$ pwd 184 | /home/username/html 185 | username@computer:~/html$ cd /home/username 186 | username@computer:~$ pwd 187 | /home/username 188 | 189 | These commands achieve the same thing as the ones above: we ``cd`` 190 | into ``html``, a folder within our home directory, and then back to 191 | our home directory. Paths that start with a ``/`` are known as 192 | *absolute paths* because they always lead to the same place, 193 | regardless of your current working directory. 194 | 195 | Running ``cd`` without an argument will take you back to your home 196 | directory without regard to your current location in the file system. 197 | For example:: 198 | 199 | username@computer:~/html$ cd 200 | username@computer:~$ pwd 201 | /home/username 202 | 203 | Finally, running ``cd -`` will take you to the previous directory you 204 | were in. For example, suppose we go into the ``html`` directory and, 205 | from there, switch to the ``linux-tutorial-files`` directory. If we wanted to 206 | go back to the ``html`` directory, we can just write ``cd -``:: 207 | 208 | username@computer:~$ cd html 209 | username@computer:~/html$ cd ../linux-tutorial-files 210 | username@computer:~/linux-tutorial-files$ cd - 211 | username@computer:~/html$ pwd 212 | /home/username/html 213 | 214 | 215 | To improve the readability of our examples, we will use ``$`` as the 216 | prompt rather than the full text ``username@computer:~$`` in the rest 217 | of this tutorial. Keep in mind, though, that the prompt shows your 218 | current working directory. 219 | 220 | Exercises 221 | ^^^^^^^^^ 222 | 223 | Use ``pwd``, ``ls``, and ``cd`` to navigate to your 224 | ``linux-tutorial-files`` directory and explore the tutorial files. Subsequent 225 | examples will assume that your current directory is the ``linux-tutorial-files`` directory. 226 | 227 | 228 | .. _useful_commands: 229 | 230 | Useful commands 231 | ~~~~~~~~~~~~~~~ 232 | 233 | +---------------------------------+----------------------------------------------+ 234 | | ``cp`` | copy the source file to the new destination | 235 | +---------------------------------+----------------------------------------------+ 236 | | ``mv`` | move the source file to the new destination | 237 | +---------------------------------+----------------------------------------------+ 238 | | ``rm`` | remove or delete a file | 239 | +---------------------------------+----------------------------------------------+ 240 | | ``mkdir`` | make a new empty directory | 241 | +---------------------------------+----------------------------------------------+ 242 | | ``cat`` | print the contents of a file to the terminal | 243 | +---------------------------------+----------------------------------------------+ 244 | 245 | Sometimes it is useful to make a copy of a file. To copy a file, use 246 | the command:: 247 | 248 | cp 249 | 250 | where ```` is replaced by the name of the file you want to 251 | copy and ```` is replaced by the desired name for the 252 | copy. An example of copying the file ``test.txt`` to ``copy.txt`` is 253 | below:: 254 | 255 | $ cp test.txt copy.txt 256 | 257 | ```` can also be replaced with a path to a directory. In 258 | this case, the copy will be stored in the specified directory and will 259 | have the same name as the source. 260 | 261 | Move (``mv``) has exactly the same syntax, but does not keep the 262 | original file. Remove (``rm``) will delete the file from your 263 | directory. 264 | 265 | If you want to copy or remove an entire directory along with its 266 | files, the normal ``cp`` and ``rm`` commands will not work. Use ``cp -r`` instead of ``cp`` or ``rm -r`` instead of ``rm`` to copy or remove directories (the ``r`` stands for "recursive"). 267 | 268 | .. warning:: 269 | 270 | Running ``rm`` cannot be undone. If you want to remove the entire contents 271 | of a directory, make sure you're certain *before* you use ``rm -r`` that you want to remove 272 | *everything* in the named directory. 273 | 274 | Some useful terminology: the ``-r`` argument in ``cp -r`` or ``rm -r`` is known as a *flag*. Flags help determine the behavior of a program. In this case, the flag allows ``cp`` and ``rm`` to work with a directory tree, rather than just a single file. Most commands can accept a number 275 | of different flags; the :ref:`Getting Help ` section explains how to look up the documentation for 276 | specific commands, including the list of supported flags in each command. 277 | 278 | You can make a new directory with ``mkdir ``, where 279 | the placeholder ```` is replaced with the desired name for the new directory. 280 | 281 | Sometimes, we may want to take a look at the contents of a file from the terminal, without 282 | opening the file in an editor. We can do this task with the ``cat`` command. For example:: 283 | 284 | $ cat test.txt 285 | Linux Tutorial - Test file 286 | ========================== 287 | 288 | Name: Firstname Lastname 289 | 290 | For larger files, you may want to use the ``less`` command, which 291 | allows you to look at a file one screen-full at a time. 292 | 293 | In :ref:`Edit, Compile, and Run `, you will see a couple of ways to edit files. 294 | 295 | Exercises 296 | ^^^^^^^^^ 297 | 298 | Try the following tasks to practice and check your understanding of 299 | these terminal commands. 300 | 301 | 1. Copy ``test.txt`` to ``copy.txt`` and use ``ls`` to ensure that both files exist. 302 | 303 | 2. Move the file ``copy.txt`` to the name ``copy2.txt``. Use ``ls`` to 304 | verify that this command worked. 305 | 306 | 3. Make a new directory named ``backups`` using the ``mkdir`` command. 307 | 308 | 4. Copy the file ``copy2.txt`` to the ``backups`` directory. 309 | 310 | 5. Verify that step (4) was successful by listing the files in the 311 | ``backups`` directory. 312 | 313 | 6. Now that we have a copy of ``test.txt`` in the file named ``copy2.txt`` in the ``backups`` directory we 314 | no longer need ``copy2.txt`` in ``linux-tutorial-files``. Remove the file ``copy2.txt`` from the ``linux-tutorial-files`` 315 | directory. 316 | 317 | 7. Print the contents of the ``hello.py`` file. 318 | 319 | 320 | It can be tedious (and, when you are tired, challenging) to spell 321 | directory or file names exactly, so the terminal provides an 322 | auto-complete mechanism to guide you through your folder 323 | explorations. To access this functionality simply start typing 324 | whatever name you are interested in the context of a command and then 325 | hit tab. If there is only one way to finish that term hitting tab will 326 | fill in the rest of the term, for instance, if we typed ``ls b`` and 327 | then hit tab it would automatically finish the word ``ls backups`` and 328 | then await our hitting enter. If there is MORE than one way to finish 329 | a term, like if we had another folder called ``backups-old``, then 330 | hitting tab twice will cause the terminal to display all of the 331 | options available. 332 | 333 | Training yourself to use auto-completion (aka tab completion) will save 334 | you time and reduce the inevitable frustration that arises from 335 | mistyping filenames when you are tired or distracted. 336 | 337 | Wild Cards (using an asterisk) 338 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 339 | 340 | Sometimes when we enter a string, we want part of it to be variable, or a wildcard. For example, listing all files that end with a given extension, such as ``.txt``, is a common task. The wildcard functionality, through an asterisk, allows us to simply say:: 341 | 342 | $ ls *.txt 343 | 344 | The wildcard can represent a string of any length consisting of any characters, including the empty string. 345 | 346 | It is important to be **careful** using wildcards, especially for commands like ``rm`` that cannot be undone. A command like:: 347 | 348 | $ rm * ### DO NOT RUN THIS COMMAND! 349 | 350 | will delete **all** of the files in your working directory! 351 | 352 | Note that text following a ``#`` on the linux command-line is 353 | treated as a comment and is ignored. 354 | 355 | Exercises 356 | ^^^^^^^^^ 357 | 358 | #. Navigate to your home directory. What do you see when you run ``ls linux-tutorial*``? What about ``ls linux-tutorial*/*.py``? 359 | 360 | You have finished the section on navigating the file system. 361 | 362 | If you have been referred to this tutorial as part of a class you 363 | are taking, please move on to the next section required by your instructor. 364 | -------------------------------------------------------------------------------- /tutorials/linux-input-output.rst: -------------------------------------------------------------------------------- 1 | .. _linux-input-output: 2 | 3 | Linux Tutorial - Working with Input/Output Streams 4 | ================================================== 5 | 6 | .. note:: 7 | 8 | This section assumes you have :ref:`picked up the tutorial 9 | materials ` and that you have a :ref:`terminal 10 | window open ` to your ``linux-tutorial-files`` directory. 11 | 12 | 13 | In this section of the tutorial you will learn how to use 14 | the terminal to perform some more advanced operations in Linux, including: 15 | #. Redirection 16 | #. Piping 17 | 18 | Working with Input/Output Streams 19 | --------------------------------- 20 | 21 | When you run a program (at the command-line or by clicking), the Linux 22 | operating system creates a new *process* for running the program. 23 | Every Linux process has an input stream (known as *standard in*) for 24 | providing input to a program and two output streams, one for regular 25 | output (known as *standard out*) and one for providing information 26 | about errors (known as *standard error*). In this section, you will 27 | learn how to use these streams to provide input to a program and to 28 | capture the output. 29 | 30 | 31 | Redirection 32 | ~~~~~~~~~~~ 33 | 34 | The examples in this section will use commands that we've not yet 35 | discussed. Refer to the man pages for information about unfamiliar 36 | commands. 37 | 38 | As we already know, commands like ``pwd`` and ``ls``, and ``cat`` will 39 | print output to screen by default. Sometimes, however, we may prefer 40 | to write the output of these commands to a file. In Linux, we can 41 | redirect the output of a program to a file of our choosing. This 42 | operation is done with the ``>`` operator. 43 | 44 | Try the following example and compare your output with ours:: 45 | 46 | $ cd 47 | $ touch test-0.txt 48 | $ ls > test-1.txt 49 | $ cat test-1.txt 50 | Desktop 51 | Documents 52 | Downloads 53 | Music 54 | Pictures 55 | Public 56 | Templates 57 | test-0.txt 58 | test-1.txt 59 | Videos 60 | $ echo "Hello World!" > test-2.txt 61 | $ cat test-2.txt 62 | Hello World! 63 | $ cat test-2.txt > test-1.txt; cat test-1.txt 64 | Hello World! 65 | $ rm test-* 66 | 67 | Two important things to note: 68 | 69 | #. If you redirect to a file that does not exist, that file will be created. 70 | #. If you redirect to a file that already exists, the contents of that file will be **overwritten**. 71 | 72 | You can use the append operator (``>>``) to append the output of 73 | command to the end of an existing file rather than overwrite the 74 | contents of that file. 75 | 76 | Not only can we redirect the output of a program to a file, we can 77 | also have a program receive its input from a file. This operation is 78 | done with the ``<`` operator. For example:: 79 | 80 | $ python3 my_echo.py < my-input.txt 81 | 82 | (Change back to your ``linux-tutorial-files`` directory before you try this command.) 83 | 84 | In general, all Linux processes can perform input/output operations 85 | through, at least, the keyboard and the screen. More specifically, 86 | there are three 'input/output streams': standard input (or ``stdin``), 87 | standard output (or ``stdout``), and standard error (or ``stderr``). 88 | The code in ``my_echo.py`` simply reads information from ``stdin`` and 89 | writes it back out to ``stdout``. The redirection operators change 90 | the bindings of these streams from the keyboard and/or screen to files. 91 | For the purposes of this tutorial, we will only care about standard 92 | input and standard output. 93 | 94 | Exercises 95 | ~~~~~~~~~ 96 | 97 | #. Run ``my_echo.py`` as shown above. 98 | #. Run ``my_echo.py`` again, but this time redirect the output to a file named ``output.txt``. Check the contents of ``output.txt`` using an editor or by using the ``cat`` or ``more`` commands. 99 | #. Run ``my_echo.py`` redirecting the input from ``test.txt`` and the output to ``output2.txt``. Check the contents of ``output2.txt``. 100 | #. When you are done, remove ``output.txt`` and ``output2.txt``. 101 | 102 | .. note:: 103 | 104 | Notice how, if you run ``python3 my_echo.py`` without redirecting the input, it will patiently wait for you to type some input for it to echo. Once you type some input and hit return, the program will echo your input, and then resume waiting for input. It will continue to do so until you exit by typing ``Ctrl-d``. Give it a try! 105 | 106 | 107 | Piping 108 | ~~~~~~ 109 | 110 | In addition to the ability to direct output to and receive input from files, 111 | Linux provides a very powerful capability called piping. Piping allows one program 112 | to receive as input the output of another program, like so:: 113 | 114 | $ program1 | program2 115 | 116 | In this example, the output of program1 is used as the input of 117 | program2. Or to put it more technically, the ``stdout`` of 118 | ``program1`` is connected to the ``stdin`` of ``program2``. 119 | 120 | As another more concrete example, consider the ``man`` command with the ``-k`` option that we've 121 | previously discussed in the :ref:`Getting Help ` section of 122 | the :ref:`Linux Basics Tutorial `. Let's assume that you hadn't yet been introduced to the ``mkdir`` command. 123 | How would you look for the command to create a directory? First attempts:: 124 | 125 | $ man -k "create directory" 126 | create directory: nothing appropriate 127 | $ man -k "directory" 128 | (a bunch of mostly irrelevant output) 129 | 130 | As we can see, neither of these options is particularly helpful. However, with 131 | piping, we can combine ``man -k`` with a powerful command line utility called 132 | ``grep`` to find what we need:: 133 | 134 | $ man -k "directory" | grep "create" 135 | mkdir (2) - create a directory 136 | mkdirat (2) - create a directory 137 | mkdtemp (3) - create a unique temporary directory 138 | mkfontdir (1) - create an index of X font files in a directory 139 | mklost+found (8) - create a lost+found directory on a mounted Linux second extended fil... 140 | mktemp (1) - create a temporary file or directory 141 | pam_mkhomedir (8) - PAM module to create users home directory 142 | update-info-dir (8) - update or create index file from all installed info files in directory 143 | vgmknodes (8) - recreate volume group directory and logical volume special files 144 | 145 | Nice. 146 | 147 | Exercises 148 | ~~~~~~~~~ 149 | 150 | #. Learn about the ``printenv`` command by looking at its manual page (``man printenv``) and then giving it a try. 151 | #. Use piping to chain together the ``printenv`` and ``tail`` commands to display the last 10 lines of output from ``printenv``. 152 | #. Replicate the above functionality without using the ``|`` operator. (hint: Use a temporary file.) 153 | 154 | You have finished the section on working with input and output. 155 | 156 | If you have been referred to this tutorial as part of a class you 157 | are taking, please move on to the next section required by your instructor. 158 | -------------------------------------------------------------------------------- /tutorials/linux-intro.rst: -------------------------------------------------------------------------------- 1 | .. _tutorial-linux-intro: 2 | 3 | Linux Tutorial - Introduction To Linux 4 | ====================================== 5 | 6 | Linux is an operating system, just like Windows and MacOS. It allows 7 | you (the user) to interact with your computer, and provides many 8 | of the same tools you're accustomed to in Windows and MacOS (web 9 | browsers, word processors, etc.). 10 | 11 | In almost all CS classes, instructors will assume that you know your 12 | way around a Linux environment, and may require that you compile and 13 | run code in a Linux system. Being comfortable using the *terminal*, a command-line 14 | interface for interacting with the filesystem, running programs, etc, is an 15 | important part knowing your way around Linux. 16 | 17 | In this tutorial you will learn how to: 18 | 19 | #. :ref:`Open a Terminal Window ` 20 | #. :ref:`Navigate the Filesystem ` 21 | #. :ref:`Edit, Compile, and Run a Program ` 22 | #. :ref:`Get Help from the Command-line ` 23 | #. :ref:`Use Keyboard Shortcuts ` 24 | #. :ref:`Run Commands Sequentially ` 25 | #. :ref:`Work with Input/Output Streams ` 26 | #. :ref:`Understand and Set File Permissions ` 27 | 28 | Everyone should work through the first part, even students with prior 29 | experience with Linux, since it explains how to pick up the materials 30 | you will need to complete subsequent parts. 31 | 32 | As for the rest of the tutorial, you are welcome to complete all the 33 | sections, but only some will be relevant for your current course(s). 34 | Check the instructions you received from your instructor(s) to 35 | determine which sections you need to complete. 36 | 37 | 38 | Where should you do this tutorial? 39 | ---------------------------------- 40 | 41 | Since one of the goals of this tutorial is for you to be able to use 42 | the CS department's Linux environment, we strongly suggest you work 43 | through this tutorial on a :ref:`UChicago CS software environment `. 44 | While you can work through the tutorial in one of our computer labs, 45 | we recommend :ref:`using SSH ` to log into a CS Linux server from 46 | your personal computer, as this will likely be the primary way you'll 47 | be interacting with the CS department's Linux systems. 48 | 49 | Many of the steps in this tutorial can be replicated on a MacOS system 50 | or using `Ubuntu WSL `__ on Windows. 51 | While eventually you'll be able to reuse these skills in those 52 | environments, for now, we **strongly** recommend that you use the 53 | Linux environment provided by the CS department. 54 | 55 | .. _terminal: 56 | 57 | Opening a Terminal Window 58 | ------------------------- 59 | 60 | On your personal computer, you probably navigate your hard drive by 61 | double clicking on icons. While convenient for simple tasks, this 62 | approach is limited. For example, imagine that you want to delete all of 63 | the music files over 5 MB that you haven't listened to in over a 64 | year. This task is very hard to do with the standard double-click 65 | interface but is relatively simple using the terminal. 66 | 67 | If you are using SSH, connecting to a CS Linux server will directly 68 | open a terminal for you. 69 | 70 | If you are using a desktop environment (e.g., you are sitting in 71 | CSIL), you can start a terminal by clicking on the Application icon 72 | (3x3 grid of dots) at the bottom left of the screen: 73 | 74 | .. figure:: ubuntu-3x3.png 75 | :alt: Application icon in Ubuntu 76 | 77 | Then, type "terminal" in the input box. Click the "terminal" 78 | icon to open a terminal window. You can also use the keyboard shortcut: ``Ctrl+Alt+t.`` 79 | 80 | Regardless of how you open the terminal, you will see something 81 | like this:: 82 | 83 | username@computer:~$ 84 | 85 | where ``username`` has been replaced by your CNetID and ``computer`` 86 | is the name of the machine you happen to be using. This string is 87 | called the *prompt*. When you start typing, the characters you type 88 | will appear to the right of the ``$``. 89 | 90 | The program that runs within a terminal window and processes the 91 | commands the you type is called a *shell*. We use ``bash``, which is 92 | the default shell on most Linux distributions, but there are other 93 | popular shells, such as ``tcsh``, ``zsh``, etc. 94 | 95 | The terminal will start in your *home directory*, ``/home/username/``, 96 | which is a special directory (*i.e.*, folder) assigned to your user 97 | account. 98 | 99 | In each part of the tutorial, we will introduce a new concept or 100 | skill, and will provide a few simple examples. This includes 101 | examples of sample output throughout the tutorial. Bear in mind that 102 | the output you see when you run through our examples may vary a bit; 103 | this is normal. We have also included a few exercises in each section 104 | so you can practice these skills. 105 | 106 | 107 | .. _tutorial-materials: 108 | 109 | Pick Up the Tutorial Materials 110 | ------------------------------ 111 | 112 | To complete this tutorial, you will need a series of files to use with 113 | for the examples and exercises. 114 | 115 | To fetch these files, run the following commands one at a time:: 116 | 117 | $ cd 118 | $ wget -nv https://uchicago-cs.github.io/student-resource-guide/_static/linux-tutorial-files.zip 119 | $ unzip linux-tutorial-files.zip 120 | 121 | Note that we use ``$`` to represent the Linux command-line prompt. Do not include it 122 | when you run the commands. 123 | 124 | The first command (``cd``), which we explain in the :ref:`Navigating 125 | the File System ` section, ensures that you are in 126 | your home directory. The second downloads up a compressed file from our 127 | GitHub site. And finally, the third command decompresses that file. 128 | 129 | As an aside, be very careful when running ``wget`` commands that you 130 | find in instructions on the internet. You should always verify that the 131 | download site is legitimate. 132 | 133 | After you run these commands, your home directory will contain a 134 | ``linux-tutorial-files`` directory that has some files 135 | for us to play with. 136 | 137 | The next section of the tutorial covers :ref:`Navigating the Filesystem `. 138 | 139 | -------------------------------------------------------------------------------- /tutorials/linux-man.rst: -------------------------------------------------------------------------------- 1 | .. _linux-getting-help: 2 | 3 | Linux Tutorial - Getting Help 4 | ============================= 5 | 6 | There are a number of ways to get help using command-line applications from within the terminal itself: 7 | 8 | * ``--help`` flag 9 | * ``tldr`` command 10 | * ``man`` pages 11 | 12 | ``--help`` 13 | ~~~~~~~~~~ 14 | 15 | Many commands have a ``--help`` flag that can be passed after the command name. ``pwd`` for example:: 16 | 17 | $ pwd --help 18 | pwd: pwd [-LP] 19 | Print the name of the current working directory. 20 | 21 | Options: 22 | -L print the value of $PWD if it names the current working 23 | directory 24 | -P print the physical directory, without any symbolic links 25 | 26 | By default, `pwd' behaves as if `-L' were specified. 27 | 28 | Exit Status: 29 | Returns 0 unless an invalid option is given or the current directory 30 | cannot be read. 31 | 32 | 33 | 34 | This will often give helpful reminders about flags and options. 35 | 36 | tldr 37 | ~~~~ 38 | 39 | The CS Linux servers also have a program called ``tldr`` installed. 40 | 41 | This program gives a selection of examples of common behaviors. It isn't comprehensive, but can often give a quick answer when you are trying to remember how to perform a particular task. 42 | 43 | To get the tldr page for a Linux command, you can type:: 44 | 45 | tldr 46 | 47 | For example:: 48 | 49 | $ tldr ls 50 | 51 | List directory contents. 52 | More information: . 53 | 54 | List files one per line: 55 | 56 | ls -1 57 | 58 | List all files, including hidden files: 59 | 60 | ls -a 61 | 62 | List all files, with trailing `/` added to directory names: 63 | 64 | ls -F 65 | 66 | Long format list (permissions, ownership, size, and modification date) of all files: 67 | 68 | ls -la 69 | 70 | Long format list with size displayed using human-readable units (KiB, MiB, GiB): 71 | 72 | ls -lh 73 | 74 | Long format list sorted by size (descending) recursively: 75 | 76 | ls -lSR 77 | 78 | Long format list of all files, sorted by modification date (oldest first): 79 | 80 | ls -ltr 81 | 82 | Only list directories: 83 | 84 | ls -d */ 85 | 86 | man pages 87 | ~~~~~~~~~ 88 | 89 | A man page (short for manual page) documents or describes topics related to working with Linux. 90 | These topics include specific Linux programs, certain programming functions, standards, and conventions, and abstract concepts. Information provided by a man page can include what flags and arguments can be utilized with a command (we discussed flags and arguments when learning how to :ref:`navigate the filesystem `). 91 | 92 | Man pages are the most comprehensive form of help, but also the most verbose. In this section of the tutorial you will learn how to access and read man pages. Learning how to read a man page takes time and is a skill you will develop with practice. 93 | 94 | To get the man page for a Linux command, you can type:: 95 | 96 | man 97 | 98 | So in order to get the man page for ``ls``, you would type:: 99 | 100 | $ man ls 101 | 102 | This command displays a man page that gives information on the ``ls`` command, including a description of the command, a list of the flags it supports, instructions on how to use it, and other information. 103 | 104 | Each man page has a description. The ``-k`` flag for ``man`` allows you to search these descriptions using a keyword. For example:: 105 | 106 | $ man -k printf 107 | 108 | This searches all the descriptions for the keyword ``printf`` and prints the names of the man pages with matches. 109 | 110 | Learning how to read man pages is an important skill. 111 | 112 | Exercise 113 | ~~~~~~~~ 114 | 115 | By default, the ``ls`` command does not include files with names that start with a dot (``.``). 116 | The ``linux-tutorial-files`` directory contains a file that starts with a dot. Use ``man`` to identify the flag to use with ``ls`` to include this file when listing the contents of ``linux-tutorial-files``. 117 | 118 | 119 | You have finished the section on getting help. 120 | 121 | If you have been referred to this tutorial as part of a class you 122 | are taking, please move on to the next section required by your instructor. 123 | -------------------------------------------------------------------------------- /tutorials/linux-permissions.rst: -------------------------------------------------------------------------------- 1 | .. _linux-permissions: 2 | 3 | Linux Tutorial - File Permissions 4 | ================================= 5 | 6 | .. note:: 7 | 8 | This section assumes you have :ref:`picked up the tutorial 9 | materials ` and that you have a :ref:`terminal 10 | window open ` to your ``linux-tutorial-files`` directory. 11 | 12 | In this section of the tutorial you will learn how to use 13 | the terminal to perform some more advanced operations in Linux, including: 14 | 15 | #. File permissions 16 | #. Changing ownership and group 17 | 18 | 19 | File Permissions 20 | ---------------- 21 | 22 | Your personal laptop is likely set up with a login and password 23 | even though it is likely to be a single-user computer. Why? This 24 | simple mechanism helps to limit others' ability to access to your 25 | files. Since you are likely the only user of your machine, it is 26 | not necessary to limit access to individual files. 27 | 28 | On a networked filesystem, however, you may want to share some files 29 | with everyone, while restricting access to other files to yourself or 30 | a select group of users. 31 | 32 | Most file systems assign 'File Permissions' (or just permissions) to specific users and groups of users. Linux is no different. File permissions dictate who can read (view), write (create/edit), and execute (run) files on a file system. 33 | 34 | All directories and files are owned by a user. Each user can be a member of one or more groups. To see your groups, enter the command ``groups`` into the command line. 35 | 36 | File permissions in Linux systems are managed in three distinct scopes. Each scope has a distinct set of permissions. 37 | 38 | **User** - The owner of a file or directory makes up the *user* scope. 39 | 40 | **Group** - Each file and directory has a group assigned to it. The members of this group make up the *group* scope. 41 | 42 | **Others** - Every user who does not fall into the previous two scopes make up the *others* scope. 43 | 44 | If a user falls into more than one of these scopes, their effective permissions are determined based on the first scope the user falls within in the order of user, group, and others. 45 | 46 | Each scope has three specific permissions for each file or directory: 47 | 48 | **read** - The read permission allows a user to view a file's contents. When set for a directory, this permission allows a user to view the names of files in the directory, but no further information about the files in the directory. ``r`` is shorthand for read permissions. 49 | 50 | **write** - The write permission allows a user to modify the contents of a file. When set for a directory, this permission allows a user to create, delete, or rename files. ``w`` is shorthand for write permissions. 51 | 52 | **execute** - The execute permission allows a user to execute a file (or program) using the operating system. When set for a directory, this permission allows a user to access file contents and other information about files within the directory (given that the user has the proper permissions to access the file). The execute permission does not allow the user to list the files inside the directory unless the read permission is also set. ``x`` is shorthand for execute permissions. 53 | 54 | To list information about a file, including its permissions, type:: 55 | 56 | ls -l 57 | 58 | You'll get output of the form:: 59 | 60 | 1 owner group 61 | 62 | For example, if we want information on ``/usr/bin/python3.8``:: 63 | 64 | $ ls -l /usr/bin/python3.8 65 | -rwxr-xr-x 1 root root 5486384 Jan 27 2021 /usr/bin/python3.8 66 | 67 | 68 | First thing we can notice is that the owner of the file is a user 69 | named ``root``. The file's group is also ``root``. 70 | 71 | .. note:: 72 | 73 | ``root`` is a name for an account that has access 74 | to *all* commands and files on a Linux system. Other accounts may 75 | also have "root" privileges. 76 | 77 | The permissions are ``-rwxr-xr-x``. The initial dash (``-``) 78 | indicates that ``/usr/bin/python3.8`` is a file, not a directory. 79 | Directories have a ``d`` instead of a dash. Then the permissions are 80 | listed in user, group, and others order. In this example, the owner, 81 | ``root``, can read (``r``), write (``w``), and execute (``x``) the 82 | file. Users in the ``root`` group and all other users can read and 83 | execute the files. 84 | 85 | 86 | By default, any files or directories that you create will have your 87 | username as both the user and the group. (If you run ``groups``, 88 | you'll notice that there is a group with the same name as your 89 | username. You are the only member of this group.) On our Linux 90 | machines, by default, new files are give read and write 91 | permissions to user and group and no permissions to other. New 92 | directories will be set to have read, write and execute permissions 93 | for user and group. 94 | 95 | Exercise 96 | ~~~~~~~~ 97 | 98 | .. note:: 99 | 100 | If you have not completed the :ref:`Linux Basics Tutorial `, 101 | create a new directory and file by running the following in your 102 | ``linux-tutorial-files`` directory:: 103 | 104 | $ mkdir backups 105 | $ cp test.txt backups/copy2.txt 106 | 107 | Verify that the permissions in your directories and files were set 108 | correctly by running ``ls -l backups/copy2.txt`` and ``ls -ld backups`` in your ``linux-tutorial-files`` directory. 109 | 110 | The ``-d`` flag tells ``ls`` to list the directory, instead of its 111 | contents. Notice that that the first letter in the permissions string 112 | for ``backups`` is a `d`, while it is a ``-`` for 113 | ``backups/copy2.txt``. 114 | 115 | Once you have verified the claim, go ahead and remove the ``backups`` 116 | directory. 117 | 118 | 119 | 120 | Changing Permissions, Owner, & Group 121 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 122 | 123 | +-----------------------------------------+----------------------------------------------+ 124 | | ``chmod`` | set the permissions for a file/directory | 125 | +-----------------------------------------+----------------------------------------------+ 126 | | ``chmod`` | update the permissions for a file/directory | 127 | +-----------------------------------------+----------------------------------------------+ 128 | | ``chown`` | change the owner of a file to username | 129 | +-----------------------------------------+----------------------------------------------+ 130 | | ``chgrp`` | change the group of a file | 131 | +-----------------------------------------+----------------------------------------------+ 132 | 133 | 134 | 135 | To change permissions, we use the ``chmod`` command. There are two 136 | ways to specify the permissions. We'll describe the more accessible 137 | one first: to set the permissions you specify the scope using a 138 | combination of ``u``, ``g``, and ``o``, the permission using ``r``, 139 | ``w``, and ``x``, and either ``+`` or ``-`` to indicate that you want 140 | to add or remove a permission. For example ``uo+rw`` indicates that 141 | you want to add read and write permissions for the user and others 142 | groups. 143 | 144 | We can demonstrate this using the ``cat`` command:: 145 | 146 | $ echo "Hello!" > testfile 147 | $ ls -l testfile 148 | -rw-rw---- 1 username username 7 Aug 23 11:22 testfile 149 | $ cat testfile 150 | Hello! 151 | $ chmod ug-r testfile #remove read and permissions from user and group 152 | $ ls -l testfile 153 | --w--w---- 1 username username 7 Aug 23 11:22 testfile 154 | $ cat testfile 155 | cat: testfile: Permission denied 156 | $ chmod u+r testfile #give user scope read permissions 157 | 158 | 159 | In this last example, we have added user read permissions to 160 | ``testfile``. 161 | 162 | In addition to the symbolic method for setting permissions, you can 163 | also use a numeric method: each permission has a unique value: read = 164 | 4, write = 2, execute = 1. As a result, you can describe the 165 | permissions of each scope using the sum of its permissions' 166 | values. For example, if a file has read and write permissions for the 167 | user scope, its permissions can be described as 6 (4 + 2 = 6). 168 | 169 | You can describe the permissions of a file overall using these values 170 | for each scope. For example, 761 describes the permissions for a file 171 | with read, write, and execute permissions for the user scope, read and 172 | write permissions for the group scope, and only execute permissions 173 | for the others scope. 174 | 175 | The symbolic approach is relative: it allows you to add and remove 176 | permissions relative the the current file permissions. The numeric 177 | method is absolute: it sets the permissions to a specific 178 | configuration. We recommend starting the symbolic approach. It is 179 | easier to get right. As you get more comfortable with setting 180 | permissions, it is useful to learn how to use the numeric method. 181 | 182 | To change the owner of a file or directory (if you are the owner or root), use the command:: 183 | 184 | chown 185 | 186 | To change a file's group (if you are the owner or root), use the command:: 187 | 188 | chgrp 189 | 190 | 191 | 192 | Exercises 193 | ~~~~~~~~~ 194 | 195 | #. Run ``echo "Hello!" > testfile`` to construct ``testfile``. Look at the permissions using ``ls -l``. 196 | #. Change the permissions on ``testfile`` to allow write and read access for others. Run ``ls -l testfile`` to check the new permissions. 197 | #. Remove group write access from ``testfile``. Check the corrected permissions. 198 | #. Remove ``testfile`` using ``rm``. 199 | 200 | You have finished the section on understanding and changing file 201 | permissions. This is the last section of the tutorial. 202 | 203 | 204 | -------------------------------------------------------------------------------- /tutorials/linux-sequence.rst: -------------------------------------------------------------------------------- 1 | .. _linux-sequence: 2 | 3 | Linux Tutorial - Running Commands Sequentially 4 | =============================================== 5 | 6 | .. note:: 7 | 8 | This section assumes you have :ref:`picked up the tutorial 9 | materials ` and that you have a :ref:`terminal 10 | window open ` to your ``linux-tutorial-files`` directory. 11 | 12 | In this section of the tutorial you will learn how to run commands 13 | sequentially. 14 | 15 | It is often convenient to chain together commands that you want to run in sequence. 16 | For example, recall that to print the working directory and list all of 17 | the files and directories contained inside, you would use the following commands:: 18 | 19 | $ pwd 20 | /home/username/ 21 | $ ls 22 | Desktop Documents Downloads Music Pictures Public Templates Videos 23 | 24 | You could also run them together by separating them with a semicolon, like so:: 25 | 26 | $ pwd ; ls 27 | /home/username/ 28 | Desktop Documents Downloads Music Pictures Public Templates Videos 29 | 30 | First, ``pwd`` is executed and run to completion, and then ``ls`` is executed and 31 | run to completion. The two examples above are thus equivalent, but the ability to 32 | run multiple commands together is a small convenience that could save you some time 33 | if there is a group of commands that you want to execute sequentially. 34 | 35 | 36 | .. note:: 37 | 38 | What actually acts as a separator between the comments is the semicolon, 39 | and the shell is generally pretty flexible about the amount of white space separating commands, 40 | arguments, etc., so it will run any of the following as well:: 41 | 42 | $ pwd;ls 43 | $ pwd ;ls 44 | $ pwd; ls 45 | $ pwd ; ls 46 | 47 | 48 | You have finished the section on running commands sequentially. 49 | 50 | If you have been referred to this tutorial as part of a class you 51 | are taking, please move on to the next section required by your instructor. 52 | -------------------------------------------------------------------------------- /tutorials/linux-tip-tricks.rst: -------------------------------------------------------------------------------- 1 | .. _linux-tip-tricks: 2 | 3 | Linux Tutorial - Tips and Tricks 4 | ======================================= 5 | 6 | In this section of the tutorial, you will learn some time saving 7 | keyboard shortcuts for Linux. Learning to use keyboard shortcuts will 8 | allow you to work **more efficiently and with less frustration**. 9 | 10 | Using the Control Key 11 | --------------------- 12 | 13 | In the text below, when we write ``Ctrl-X`` for some letter ``X``, we 14 | mean press the control key and the key for the specified letter at the 15 | same time. For example, to type ``Ctrl-C``, you will press the 16 | control key and the ``c`` key at the same time. By convention, the 17 | letter is usually written as a capital letter (e.g., ``C``) for 18 | clarity, but you do not need to press the shift key in addition to the 19 | control key. 20 | 21 | 22 | Terminating a program 23 | --------------------- 24 | 25 | Sometimes, a program will run indefinitely or misbehave. When this 26 | happens, you can type ``Ctrl-C`` to send an interrupt signal to the 27 | running program, which usually causes it to terminate. On occasion, 28 | you may need to type ``Ctrl-C`` a few times. 29 | 30 | Typing ``Ctrl-D`` sends an end of input signal, which tells the program that 31 | no more information is coming. Typing ``Ctrl-D`` does not terminate the program. 32 | This can be helpful if you call ``cat`` with no input as the command will continue to wait for an input. 33 | 34 | Keyboard shortcuts 35 | ------------------ 36 | 37 | Used in the terminal, the keyboard shortcut ``Ctrl-P`` will roll 38 | back to the previous command. If you type ``Ctrl-P`` twice, you will 39 | roll back by two commands. If you type ``Ctrl-P`` too many times, you 40 | can use ``Ctrl-N`` to move forward. You can also use the arrow keys: 41 | up for previous (backward), down for next (forward). 42 | 43 | Here are some useful shortcuts for editing the current text on the command-line: 44 | 45 | - ``Ctrl-A`` will move you to the beginning of a line. 46 | - ``Ctrl-E`` will move you to the end of a line. 47 | - ``Ctrl-U`` will erase everything from where you are in a line back to the beginning. 48 | - ``Ctrl-K`` will erase everything from where you are to the end of the line. 49 | - ``Ctrl-L`` will clear the text from current terminal 50 | 51 | 52 | Play around with these commands. Being able to scroll back to, edit, 53 | and then rerun previously used commands saves time and typing! And 54 | like auto-completion, getting in the habit of using keyboard shortcuts 55 | will reduce frustration as well save time. 56 | 57 | Summary 58 | ------- 59 | 60 | Here is a complete list of the commands discussed in this section: 61 | 62 | - ``Ctrl-C`` will send an interrupt signal to a running program, which will usually terminate it. 63 | - ``Ctrl-D`` will send an end-of-input signal to a program. 64 | - ``Ctrl-P`` will roll back to the previous command in the command history. 65 | - ``Ctrl-N`` will move forward one command in the command history. 66 | - ``Ctrl-A`` will move you to the beginning of a line. 67 | - ``Ctrl-E`` will move you to the end of a line. 68 | - ``Ctrl-U`` will erase everything from where you are in a line back to the beginning. 69 | - ``Ctrl-K`` will erase everything from where you are to the end of the line. 70 | - ``Ctrl-L`` will clear the text from current terminal 71 | 72 | 73 | You have finished the tips and tricks section. 74 | 75 | If you have been referred to this tutorial as part of a class you 76 | are taking, please move on to the next section required by your instructor. 77 | 78 | -------------------------------------------------------------------------------- /tutorials/nano.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/tutorials/nano.png -------------------------------------------------------------------------------- /tutorials/ubuntu-3x3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/tutorials/ubuntu-3x3.png -------------------------------------------------------------------------------- /tutorials/ubuntu-vscode-1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/tutorials/ubuntu-vscode-1.png -------------------------------------------------------------------------------- /vscode/about.rst: -------------------------------------------------------------------------------- 1 | .. _vscode-about: 2 | 3 | Visual Studio Code 4 | ================== 5 | 6 | In many of your classes, an indispensable tool will be your 7 | `code editor `__: 8 | a text editor specifically designed for editing programming code. 9 | While you are welcome to use whatever code editor works best 10 | for you, `Visual Studio Code `__ (or "VS Code") is a popular option 11 | because it is fairly beginner-friendly, but still a very powerful 12 | tool once you familiarize itself with all its bells and whistles. 13 | 14 | Most notably, it is well suited for a variety of programming languages, 15 | which means that, if you become fluent in using VS Code with Python, 16 | and then need to edit some C or Java code, you won't have to learn 17 | how to use a new editor from scratch. 18 | 19 | Additionally, it makes it fairly easy to connect to a remote server via SSH, which means 20 | you can run VS Code on your personal computer 21 | to edit files that live in the CS Linux servers, as well as interact 22 | with those files from a terminal built into VSCode (e.g., to run your 23 | code). 24 | 25 | Finally, VS Code is free! You won't have to pay anything to use it. 26 | 27 | In this section, we provide instructions on how to :ref:`install VS Code `, 28 | how to :ref:`set up some common configuration options `, and how to 29 | :ref:`set up VS Code to connect to the CS Linux servers with SSH `. 30 | -------------------------------------------------------------------------------- /vscode/code-img/connect-1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/vscode/code-img/connect-1.png -------------------------------------------------------------------------------- /vscode/code-img/connect-10.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/vscode/code-img/connect-10.png -------------------------------------------------------------------------------- /vscode/code-img/connect-11.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/vscode/code-img/connect-11.png -------------------------------------------------------------------------------- /vscode/code-img/connect-2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/vscode/code-img/connect-2.png -------------------------------------------------------------------------------- /vscode/code-img/connect-3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/vscode/code-img/connect-3.png -------------------------------------------------------------------------------- /vscode/code-img/connect-4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/vscode/code-img/connect-4.png -------------------------------------------------------------------------------- /vscode/code-img/connect-5.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/vscode/code-img/connect-5.png -------------------------------------------------------------------------------- /vscode/code-img/connect-5a.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/vscode/code-img/connect-5a.png -------------------------------------------------------------------------------- /vscode/code-img/connect-6.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/vscode/code-img/connect-6.png -------------------------------------------------------------------------------- /vscode/code-img/connect-7.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/vscode/code-img/connect-7.png -------------------------------------------------------------------------------- /vscode/code-img/connect-8.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/vscode/code-img/connect-8.png -------------------------------------------------------------------------------- /vscode/code-img/connect-9.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/vscode/code-img/connect-9.png -------------------------------------------------------------------------------- /vscode/code-img/detect-indentation.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/vscode/code-img/detect-indentation.png -------------------------------------------------------------------------------- /vscode/code-img/four-spaces.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/vscode/code-img/four-spaces.png -------------------------------------------------------------------------------- /vscode/code-img/git-disable-1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/vscode/code-img/git-disable-1.png -------------------------------------------------------------------------------- /vscode/code-img/git-disable-2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/vscode/code-img/git-disable-2.png -------------------------------------------------------------------------------- /vscode/code-img/install-code-deb-1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/vscode/code-img/install-code-deb-1.png -------------------------------------------------------------------------------- /vscode/code-img/install-code-deb-2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/vscode/code-img/install-code-deb-2.png -------------------------------------------------------------------------------- /vscode/code-img/install-code-mac-1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/vscode/code-img/install-code-mac-1.png -------------------------------------------------------------------------------- /vscode/code-img/install-code-mac-2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/vscode/code-img/install-code-mac-2.png -------------------------------------------------------------------------------- /vscode/code-img/install-code-win-1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/vscode/code-img/install-code-win-1.png -------------------------------------------------------------------------------- /vscode/code-img/install-code-win-2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/vscode/code-img/install-code-win-2.png -------------------------------------------------------------------------------- /vscode/code-img/install-ext-1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/vscode/code-img/install-ext-1.png -------------------------------------------------------------------------------- /vscode/code-img/install-ext-2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/vscode/code-img/install-ext-2.png -------------------------------------------------------------------------------- /vscode/code-img/install-ext-3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/vscode/code-img/install-ext-3.png -------------------------------------------------------------------------------- /vscode/code-img/install-ext-4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/vscode/code-img/install-ext-4.png -------------------------------------------------------------------------------- /vscode/code-img/ruler-1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/vscode/code-img/ruler-1.png -------------------------------------------------------------------------------- /vscode/code-img/ruler-2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/vscode/code-img/ruler-2.png -------------------------------------------------------------------------------- /vscode/code-img/setup-1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/vscode/code-img/setup-1.png -------------------------------------------------------------------------------- /vscode/code-img/setup-2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/vscode/code-img/setup-2.png -------------------------------------------------------------------------------- /vscode/code-img/setup-3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/vscode/code-img/setup-3.png -------------------------------------------------------------------------------- /vscode/code-img/setup-4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/vscode/code-img/setup-4.png -------------------------------------------------------------------------------- /vscode/code-img/spaces-for-tab.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/vscode/code-img/spaces-for-tab.png -------------------------------------------------------------------------------- /vscode/code-img/ssh-1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/vscode/code-img/ssh-1.png -------------------------------------------------------------------------------- /vscode/code-img/ssh-2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/vscode/code-img/ssh-2.png -------------------------------------------------------------------------------- /vscode/code-img/vscode-settings.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/uchicago-cs/student-resource-guide/67d8d020887e2d61ea7b2f213c94f54a91803d2f/vscode/code-img/vscode-settings.png -------------------------------------------------------------------------------- /vscode/config.rst: -------------------------------------------------------------------------------- 1 | .. _vscode-config: 2 | 3 | Configuring Visual Studio Code 4 | ============================== 5 | 6 | In this page, you will find instructions on how to set some common configuration 7 | options. Many of these will make it easier to conform to our style guides. 8 | 9 | If you are planning to primarily use VS Code with SSH, please make sure you 10 | connect to a CS Linux Server (as described in :ref:`vscode-ssh`) before 11 | following these instructions. 12 | 13 | .. _vscode-install-extensions: 14 | 15 | Install Language Extensions for VS Code 16 | --------------------------------------- 17 | 18 | In the left sidebar of VS Code, there is an icon 19 | consisting of four squares, with one square separated off from the 20 | other three. This is the icon for VSCode extensions. Click it 21 | (alternatively, you can press Ctrl-Shift-X, or Command-Shift-X on 22 | macOS). 23 | 24 | .. figure:: code-img/install-ext-1.png 25 | 26 | This opens the *Extensions* panel. From here, you can search for and install extensions. You should install the extensions for the language(s) you intend to use: 27 | 28 | - **Python** 29 | 30 | - Python 31 | 32 | - **C/C++** 33 | 34 | - C/C++ 35 | - C/C++ Extension Pack 36 | 37 | - **Java** 38 | 39 | - Extension Pack for Java 40 | 41 | Please note that all of these extensions should list "Microsoft" as the publisher of the extension. 42 | 43 | To install an extension, click in the search bar ("Search Extensions in Marketplace") and start typing the name of the extension. When it appears, make sure the name and publisher matches exactly, and click *Install*. 44 | 45 | .. figure:: code-img/install-ext-4.png 46 | 47 | 48 | 49 | Space Indentation 50 | ----------------- 51 | 52 | Your editor should be set such that tabs are equivalent to four spaces. This guide focuses on how to configure indentation in VS Code. First, set the tab size to four spaces. Go to *Settings...*, *Settings*, and select *Commonly Used*. 53 | 54 | .. figure:: code-img/vscode-settings.png 55 | 56 | Under *Commonly Used* find *Editor: Tab Size* and set it to four. 57 | 58 | .. figure:: code-img/four-spaces.png 59 | 60 | Next, set tabs as spaces. Go to *Commonly Used* again, and set *Editor: Insert Spaces* to true. 61 | 62 | .. figure:: code-img/spaces-for-tab.png 63 | 64 | Lastly, turn off detect indentation. Go to *Editor: Detect Indentation* and set it to false. 65 | 66 | .. figure:: code-img/detect-indentation.png 67 | 68 | Rulers 69 | ------ 70 | 71 | Your code should, generally, not have lines longer than 80 characters. To make sure you do not go over that line limit, you should configure VS Code to render line rulers. Go to *Preferences*, *Settings*, and look up *Editor: Rulers*. 72 | 73 | .. figure:: code-img/ruler-1.png 74 | 75 | Open the *settings.json* file and copy the following to the file. 76 | 77 | 78 | .. code-block:: 79 | 80 | "editor.rulers": [80,120], 81 | 82 | "workbench.colorCustomizations": { 83 | "editorRuler.foreground": "#ff4081" 84 | } 85 | 86 | 87 | Add the code after the last item within the curly braces. The result should look like this: 88 | 89 | .. figure:: code-img/ruler-2.png 90 | 91 | (If you have set other settings, you may see additional information in the file.) 92 | 93 | Make sure to save the file using ``Ctrl-s``, if you are using a 94 | Windows or Linux Machine or ``Command-s``, if you are using a MacOS 95 | machine. If your changes worked properly, you will see a vertical 96 | red-line at 80 characters. If your VSCode window is wide enough, you 97 | will see a second vertical line at 120 characters. 98 | 99 | Turning off Git Integration 100 | --------------------------- 101 | 102 | Git is a version control system used in many CS courses at 103 | UChicago. 104 | 105 | By default, VSCode has tools for working with Git installed. While 106 | this integration can be helpful for programmers who have a good 107 | understanding of Git, it can cause problems for new programmers. As a 108 | result, some instructors will ask you to disable VSCode + Git 109 | integration. This section explains how to do so. 110 | 111 | To turn off Git integration, open the VSCode settings panel by 112 | using the menu as you did in the previous section or using the 113 | keyboard shortcut ``Control+,`` (``Command+,`` for MacOS users). 114 | 115 | In the settings search bar, type ``git: enabled`` as shown below: 116 | 117 | .. figure:: code-img/git-disable-1.png 118 | :align: center 119 | :width: 6in 120 | 121 | Scroll through the results to find the ``Git: Enabled`` option and 122 | click to remove the checkmark. The result should be: 123 | 124 | .. figure:: code-img/git-disable-2.png 125 | :align: center 126 | :width: 6in 127 | 128 | You can then close the settings panel by clicking the ``X`` in the 129 | ``Settings`` tab. 130 | 131 | Once are you comfortable with using Git for solo projects and 132 | group projects, you can reverse this process to turn Git integration 133 | back on. 134 | 135 | 136 | Terminal 137 | -------- 138 | 139 | When you open a terminal in a CS Linux system (whether it be on a 140 | desktop environment or via SSH), the exact type of terminal that will 141 | be running is a `Bash 142 | `__ shell. So, we 143 | recommend that you set up VS Code to run a Bash shell in the built-in 144 | terminal. You can skip this step if you are using VSCode with SSH 145 | integration. 146 | 147 | If you are running on a Windows machine, you should install `Git for Windows `__, 148 | which provides a Bash emulation layer called "Git Bash". While this is not a full-featured Bash shell, 149 | it will allow you to run Git commands as if you were in a Bash shell. 150 | 151 | If you are on a Linux or Mac, Bash is already pre-installed. 152 | 153 | Regardless of what operating system you use, you should make sure that Bash is set up as your 154 | default shell in VS Code: 155 | 156 | #. Open the integrated terminal by pressing :code:`Ctrl-Shift-`` 157 | #. Click on the drop down next to the plus sign. 158 | #. Click *Select Profile* 159 | #. Select bash or Git Bash. 160 | 161 | -------------------------------------------------------------------------------- /vscode/install.rst: -------------------------------------------------------------------------------- 1 | .. _vscode-install: 2 | 3 | 4 | Installing Visual Studio Code 5 | ============================= 6 | 7 | .. Todo:: 8 | Linux: how to pick matching installer -- Add Annotations 9 | 10 | Follow the instructions for your operating system: 11 | 12 | Windows 13 | ~~~~~~~ 14 | 15 | Go to https://code.visualstudio.com/. You should see a blue button labeled *Download for Windows, Universal Build*. 16 | 17 | .. figure:: code-img/install-code-win-1.png 18 | 19 | Click this button to download. Once it is downloaded, run the installer (``VSCodeUserSetup-.exe``). 20 | 21 | After you accept the license agreement, click *Next >*. On the page titled *Select Additional Tasks*, we recommend you check all the boxes (but it is up to you). 22 | 23 | .. figure:: code-img/install-code-win-2.png 24 | 25 | Click *Next >*, then click *Install*. When the progress bar fills, click *Finish*. 26 | 27 | macOS 28 | ~~~~~ 29 | 30 | Go to https://code.visualstudio.com/. You should see a blue button labeled *Download for Mac Universal, Stable Build*. 31 | 32 | .. figure:: code-img/install-code-mac-1.png 33 | 34 | Click on this button to download. When the download is complete, you will have a new application file called *Visual Studio Code*. You might instead have zip file, with a name like ``VSCode-darwin-universal.zip``; in this case, open the file to unzip it, and the *Visual Studio Code* application file should appear. Open a *Finder* window and navigate to *Downloads* (it will likely be listed under "Favorites" in the left sidebar). Locate the file named *Visual Studio Code*, and drag it on top of *Applications* in the left side bar. 35 | 36 | .. figure:: code-img/install-code-mac-2.png 37 | 38 | Now, you can find VSCode in your Applications folder, and can open it with a click. 39 | 40 | 41 | Linux 42 | ~~~~~ 43 | 44 | Go to https://code.visualstudio.com/. You should see two blue buttons labeled *.deb* and *.rpm*. Since most of you will be using Ubuntu, click on the *.deb* button. 45 | 46 | .. figure:: code-img/install-code-deb-1.png 47 | 48 | Open the directory where you downloaded the .deb file and right click on it. Click on *open with* and select *Software Install*. Follow the prompts on the installer to install the package. 49 | 50 | .. figure:: code-img/install-code-deb-2.png 51 | 52 | -------------------------------------------------------------------------------- /vscode/ssh.rst: -------------------------------------------------------------------------------- 1 | .. _vscode-ssh: 2 | 3 | Using Visual Studio Code and SSH 4 | ================================ 5 | 6 | VS Code provides a convenient mechanism to connect remotely to the CS Linux servers 7 | from inside VS Code, using SSH. This means you can run VSCode on your personal computer 8 | to edit files that live in the CS Linux servers, as well as interact 9 | with those files from a terminal built into VSCode (e.g., to run your 10 | code). 11 | 12 | In this page, we will specifically explain how to connect 13 | to the CS Linux servers. We assume that you are already familiar 14 | with SSH; if you are not, please make sure to read the :ref:`ssh` page. 15 | 16 | 17 | Server assignments 18 | ------------------ 19 | 20 | **Some classes, like CMSC 14100, use a different set of servers than the ones listed here. If you are in such a class, you should skip this section, and follow the instructions provided by your instructor(s).** 21 | 22 | 23 | In the instructions below, you will be asked to connect to a Linux 24 | server. The main linux server (``linux.cs.uchicago.edu``) acts as a front 25 | end for specific linux machines (named ``linux1.cs.uchicago.edu`` 26 | through ``linux7.cs.uchicago.edu``). VS Code works best when connected 27 | with a specific machine rather than to the front end. 28 | 29 | We would like to avoid having everyone using 30 | ``linux1.cs.uchicago.edu``, so we suggest you connect 31 | to one of the following servers, based on the first 32 | letter of your CNetID: 33 | 34 | +------------+--------------------------------+ 35 | | A,B | linux1.cs.uchicago.edu | 36 | +------------+--------------------------------+ 37 | | C,D,E,F | linux2.cs.uchicago.edu | 38 | +------------+--------------------------------+ 39 | | G,H,I,J | linux3.cs.uchicago.edu | 40 | +------------+--------------------------------+ 41 | | K,L,M | linux4.cs.uchicago.edu | 42 | +------------+--------------------------------+ 43 | | N,O,P,Q,R | linux5.cs.uchicago.edu | 44 | +------------+--------------------------------+ 45 | | S,T,U,V | linux6.cs.uchicago.edu | 46 | +------------+--------------------------------+ 47 | | W, X, Y, Z | linux7.cs.uchicago.edu | 48 | +------------+--------------------------------+ 49 | 50 | For example, Anne Rogers would use ``linux1.cs.uchicago.edu``, because 51 | her CNetID (``ar0r``) starts with an ``A``, while Hannah Morgan would 52 | use ``linux3.cs.uchicago.edu`` because her CNetID (``hmmorgan``) 53 | starts with an ``H``. 54 | 55 | In the instructions below, you will be asked to replace ``username`` 56 | with your CNetID and ``LINUX_SERVER`` with your assigned linux server. 57 | For example, if the text says run the command: 58 | 59 | :: 60 | 61 | ssh username@LINUX_SERVER 62 | 63 | Anne Rogers would run: 64 | 65 | :: 66 | 67 | ssh ar0r@linux1.cs.uchicago.edu 68 | 69 | because her CNetID (username) is ``ar0r`` and her assigned linux 70 | server is ``linux1.cs.uchicago,edu``. 71 | 72 | 73 | Remotely connecting to the CS Linux servers 74 | ------------------------------------------- 75 | 76 | You will be able to use Visual Studio Code to connect remotely to the 77 | Linux computers on campus to (1) use the terminal (to execute shell 78 | commands, compile and run code, run automated tests, etc.), 79 | and (2) to edit text files (usually code). 80 | 81 | Open Visual Studio Code now. 82 | 83 | Initial setup 84 | ~~~~~~~~~~~~~ 85 | 86 | You only need to follow the steps in this section once (or more accurately, once per computer that you will use to connect remotely). If you've already done this part, you can continue to "Connecting". 87 | 88 | First, you will need to install an extension that will allow VS Code 89 | to use SSH. In the left sidebar of VS Code, there is an icon 90 | consisting of four squares, with one square separated off from the 91 | other three. This is the icon for VSCode extensions. Click it 92 | (alternatively, you can press Ctrl-Shift-X, or Command-Shift-X on 93 | macOS). 94 | 95 | .. figure:: code-img/install-ext-1.png 96 | 97 | This opens the *Extensions* panel. From here, you can search for and install extensions. Search for the "Remote - SSH" entry and click "Install". Below you can find images of the search and of the extension. 98 | 99 | .. figure:: code-img/ssh-1.png 100 | 101 | .. figure:: code-img/ssh-2.png 102 | 103 | Once you do so, there should be a green rectangle with an icon that looks like *><*, but skewed in the lower-left corner of VSCode. Click on this icon. 104 | 105 | .. figure:: code-img/connect-1.png 106 | 107 | In the menu that appears, click *Remote-SSH: Connect to Host...*. 108 | 109 | .. figure:: code-img/connect-2.png 110 | 111 | You should see the heading *Select configured SSH host or enter user@host*. 112 | 113 | Click *+ Add New SSH Host...*. 114 | 115 | .. figure:: code-img/connect-3.png 116 | 117 | A text box will appear with the heading *Enter SSH Connection Command*. In the box, type 118 | 119 | .. code-block:: bash 120 | 121 | ssh username@LINUX_SERVER 122 | 123 | with ``username`` replaced by your CNetID and ``LINUX_SERVER`` is replaced with your assigned Linux server, and press enter. This example uses Anne Rogers' CNetID and assigned Linux server. Make sure to use **your** CNetID and assigned Linux server. 124 | 125 | .. figure:: code-img/connect-4.png 126 | 127 | Next, you will see the heading *Select SSH configuration file to update*. Press enter to select the first option (which should contain the string "User" or "home" and the username you use on your laptop). 128 | 129 | .. figure:: code-img/connect-5.png 130 | 131 | If you see a a pop-up that looks like this: 132 | 133 | .. figure:: code-img/connect-5a.png 134 | 135 | click the ``x`` to make it go away. (Don't connect just yet.) 136 | 137 | You are ready to connect. 138 | 139 | Connecting 140 | ~~~~~~~~~~ 141 | 142 | Click the green rectangle in the lower-left corner with the *><* icon. Click *Remote-SSH: Connect to Host...*. You should see the heading *Select configured SSH host or enter user@host*. This time, you should see the option ``LINUX_SERVER`` (where ``LINUX_SERVER`` is your assigned linux server) (if not, you should retry "Initial Setup"). Click on this option. 143 | 144 | .. figure:: code-img/connect-6.png 145 | 146 | A new VSCode Window will open. After a moment, you will see a pop-up. 147 | 148 | You may see a pop-up prompting *Select the platform of the remote host*; if so, click *Linux*. You will then see a box with the heading *Enter password for username@LINUX_SERVER* (with *username* replaced by your CNetID and ``LINUX_SERVER`` is replaced with your assigned linux server). Enter the password corresponding to your CNetID, and press enter. 149 | 150 | .. figure:: code-img/connect-7.png 151 | 152 | If the connection is not successful, you may be given an option to try again; click *Retry*. 153 | 154 | If you succeed at connecting, there will be a green box in the lower-left corner of the window with the text *SSH: LINUX_SERVER*. 155 | 156 | .. figure:: code-img/connect-8.png 157 | 158 | 159 | Getting Disconnected 160 | ~~~~~~~~~~~~~~~~~~~~ 161 | 162 | If at any point you get disconnected from the server unintentionally, this will be indicated in the green box in the lower-left corner (with text such as "Disconnected from SSH"). 163 | 164 | .. figure:: code-img/connect-9.png 165 | 166 | VSCode may show a pop-up asking if you want to reconnect. You can follow the prompts to reconnect. If that does not work, go back and follow the steps under *Connecting* again. 167 | 168 | If you would like to disconnect from the server intentionally, click the green box in the lower-left corner with the text *SSH: LINUX_SERVER*, then click *Close Remote Connection*. 169 | 170 | 171 | Using the terminal 172 | ------------------ 173 | 174 | .. todo:: 175 | Installing and setting up gitbash and default for Windows 176 | Setting bash as default for Mac 177 | 178 | Have your VSCode window open, and check that you are connected to SSH. Open the *View* menu from the menu bar and click *Terminal* (as a shortcut, you can instead press Ctrl-Backtick, even on macOS). This will split the window into two panes. The top pane will be empty for now (or may have some "welcome" text). The bottom pane has the terminal. 179 | 180 | .. figure:: code-img/connect-10.png 181 | 182 | You will see the bottom pane has several tabs: *Terminal*, *Debug Console*, *Problems*, and *Output* (if your window is narrow, some of these may be hidden under a three-dots menu icon). We only care about *Terminal* for now, so make sure that is selected. To the right of these tabs, you will see a dropdown menu and some additional icons. You will use these later, but you won't need them for now. 183 | 184 | In the body of the bottom pane, you will see a Linux prompt of the form 185 | 186 | .. code-block:: bash 187 | 188 | username@computer:~$ 189 | 190 | 191 | Editing text files 192 | ------------------ 193 | 194 | You can open a file to edit using the file menu on VSCode or by 195 | running the ``code`` command in the VSCode terminal window. For 196 | example, to open a file called ``hello.c``, you would run: 197 | 198 | .. code-block:: bash 199 | 200 | code hello.c 201 | 202 | If you already have a file in your CS home directory named ``hello.c``, you will see the file open in the top pane of your VSCode window. If you don't already have a file named ``hello.c``, you will see a new file in the top pane. 203 | 204 | When you save a file (using the menu or ``Ctrl-s``) while using with 205 | VSCode via ssh, you are saving to the CS Linux servers on campus (it may 206 | take a few moments). Make sure to save often! 207 | 208 | .. admonition:: Hint 209 | 210 | The ``code`` terminal command works from within VSCode when you are connected to the campus Linux computers by SSH. In this case, you are opening files stored on the CS Linux severs on campus, not files stored locally on your own computer. While not necessary for this class, it is also possible to use the ``code`` command in your computer's own terminal to open files on your own computer (or just to launch VSCode). 211 | 212 | To enable this feature... 213 | 214 | - *...on Windows:* This feature is enabled by default. If you are familiar with Windows PowerShell or Command Prompt, you can open VSCode by typing ``code`` at the prompt. If you are not familiar with Windows PowerShell or Command Prompt, you do not need to learn them for this class; while they look a bit like the Linux terminal, they use different commands. 215 | 216 | - *...on macOS:* Open VSCode, then press Command-Shift-P to open the Command Palette. Begin typing *Shell Command: Install 'code' command in PATH*, and click on the option when it appears. From this point on, you will be able to open VSCode from the macOS terminal by typing ``code``. 217 | 218 | 219 | Troubleshooting 220 | --------------- 221 | 222 | If you run into issues with VSCode and SSH, please make sure to check out 223 | the troubleshooting guide prepared by the CS Techstaff: https://howto.cs.uchicago.edu/techstaff:vscode 224 | 225 | Passwordless SSH 226 | ---------------- 227 | You will be prompted for your password in VSCode every time you connect 228 | (or reconnect) to the CS Linux servers. If you would like to avoid this, 229 | you can set up passwordless SSH. See the instructions in :ref:`passwordless-ssh` 230 | section. 231 | 232 | -------------------------------------------------------------------------------- /vscode/tips.rst: -------------------------------------------------------------------------------- 1 | .. _vscode-tips: 2 | 3 | Tips & Tricks 4 | ============= 5 | 6 | This page contains a few tips and tricks that may make it easier 7 | for you to use VS Code. 8 | 9 | 10 | Shortcuts 11 | ~~~~~~~~~ 12 | 13 | VS Code includes a number of keyboard shortcuts that can come in handy. Linux and Windows use Control (``Ctrl``) and Alt (``Alt``), while MacOS uses Command (``Cmd``) and Option (``Opt``). 14 | 15 | .. list-table:: Common Shortcuts 16 | :header-rows: 1 17 | 18 | * - Shortcuts for Linux and Windows 19 | - Shortcuts for MacOS 20 | - Action 21 | * - Ctrl + S 22 | - Cmd + S 23 | - Save the current file 24 | * - Ctrl + X 25 | - Cmd + X 26 | - Cut line (or selection) 27 | * - Ctrl + C 28 | - Cmd + C 29 | - Copy line (or selection) 30 | * - Ctrl + V 31 | - Cmd + V 32 | - Paste 33 | * - Ctrl + ] 34 | - Cmd + ] 35 | - Indent line 36 | * - Ctrl + [ 37 | - Cmd + [ 38 | - Outdent line 39 | * - Ctrl + / 40 | - Cmd + / 41 | - Toggle line comment 42 | * - Shift + Alt + A 43 | - Shift + Opt + A 44 | - Toggle block comment 45 | * - Alt + Z 46 | - Option + Z 47 | - Toggle word wrap 48 | 49 | For a full list of shortcuts see the following links: 50 | 51 | - `On Windows `__ 52 | - `On macOS `__ 53 | - `On Linux `__ 54 | 55 | --------------------------------------------------------------------------------