+ In any VSCode window, click the Copilot icon near the bottom left corner of the bottom status bar and select "Use AI Features", + then follow the prompts to sign in using GitHub. +
+
+ 
+
+ This will give you access to the [Copilot free plan](https://docs.github.com/en/copilot/concepts/billing/individual-plans) in VSCode. +
+ ++ To open the Copilot chat, go to **View > Chat**. +
+ ++ Reference: https://code.visualstudio.com/docs/copilot/setup +
+If you have never used Git on your computer, you may have to configure it. - The following instructions assume you have already created a GitHub account. + The following instructions assume you have already created a GitHub account following the main Setup page.
- Type the following commands in a terminal. Make sure to use the email associated with your GitHub account.
- The user.name can be any name you want to appear as the author of your commits, but we recommend using the name associated with your GitHub profile.
+ Type the following commands in a terminal.
Notes:
+user.email, use the email associated with your GitHub account.user.name can be any name you want to use to author your commits, but we recommend using the display name on your GitHub profile.
-git config --global user.name "Jane Doe" -git config --global user.email "janedoe@example.com" -git config --global core.autocrlf true +git config --global user.name "Jane Doe" # Set the author name for your commits +git config --global user.email "janedoe@example.com" # Set the email linked to your commits +git config --global core.autocrlf true # Auto-handle line endings correctly across different OSes +git config --global init.defaultBranch main # Make new repos use "main" as the default branch name +git config --global pull.rebase false # Make "git pull" combine changes using merge by default
- Tip: You can review your configuration at any time with: git config --list
+ Tip: You can check your Git configuration at any time with: git config --list
id_ALGORITHM and id_ALGORITHM.pub.
- If you have existing key files, use a custom name for your SSH key pair in step 2.
+ If you have existing key files, use a different, custom name for your SSH key pair in step 2.
id_ALGORITHM (e.g., id_ed25519) part of the file location with an informative keyname like id_ed25519_githubid_ALGORITHM (e.g., id_ed25519) part of the file location with an informative keyname like id_ed25519_githubid_ed25519 with your private key's filename if you used a custom key name):
+ Run the following command (if you used a custom key name, replace id_ed25519 with your private key's filename):
printf 'Host github.com\n User git\n IdentityFile ~/.ssh/id_ed25519\n IdentitiesOnly yes\n' >> ~/.ssh/configHost github.com
User git
IdentityFile ~/.ssh/id_ed25519
- IdentitiesOnly yes
-
-conda config --append channels conda-forge -conda config --set channel_priority strict -conda create -n qlsc612 -y python=3.12 flake8 jupyterlab jupyter nilearn matplotlib seaborn bokeh statsmodels plotly wordcloud +conda config --append channels conda-forge # add conda-forge as a source for packages (channel) +conda config --set channel_priority strict # prioritize packages based on channel order +conda create -n qlsc612 -y python=3.12 flake8 jupyter nilearn matplotlib seaborn bokeh statsmodels plotly wordcloud conda activate qlsc612@@ -16,3 +16,8 @@ The last line,
conda activate qlsc612,
will activate this Python environment (the default environment is base).
+
++Once the commands have finished running, you should see `(qlsc612)` at the beginning of your terminal prompt +to indicate that the new environment is active. +
diff --git a/_includes/vs-code-workspace-trust-popup.html b/_includes/vs-code-workspace-trust-popup.html new file mode 100644 index 0000000..82c929f --- /dev/null +++ b/_includes/vs-code-workspace-trust-popup.html @@ -0,0 +1,12 @@ ++diff --git a/assets/images/setup-copilot-status-bar.png b/assets/images/setup-copilot-status-bar.png new file mode 100644 index 0000000..7bf0424 Binary files /dev/null and b/assets/images/setup-copilot-status-bar.png differ diff --git a/setup/linux.md b/setup/linux.md index ef54e7a..3b48bb6 100644 --- a/setup/linux.md +++ b/setup/linux.md @@ -6,7 +6,7 @@ description: Instructions for setting up on Linux ### Bash shell -You already have it! Depending on which version of Linux you’re running you may +You already have it! Depending on which version of Linux you're running you may need to type `bash` inside the terminal to access it. To check whether this is necessary, follow these steps: @@ -25,9 +25,9 @@ If you are prompted to install it follow the instructions on-screen to do so. {% include extra-git-setup.html %} -#### Creating an SSH key for GitHub +#### Create an SSH key for GitHub -When following the GitHub docs below, make sure to select the **Linux** instructions. +When following the GitHub docs in the steps below, make sure to select the **Linux** instructions at the top of the page. {% include gh-ssh-key-setup.html %} @@ -35,18 +35,24 @@ When following the GitHub docs below, make sure to select the **Linux** instruct 1. Go to [this page](https://code.visualstudio.com/) and click the download button for either the `.deb` (Ubuntu, Debian) or the `.rpm` (Fedora, CentOS) file. -1. Double-click the downloaded file to install VSCode +2. Double-click the downloaded file to install VSCode (you may be prompted to type your administrator password during the install). +3. To confirm that everything worked, open a terminal and type `code .` (include the period). + This should open the current directory in a VSCode window. + +{% include vs-code-workspace-trust-popup.html %} #### VSCode extensions 1. Open the Visual Studio Code application. -1. Open the Extension side panel by pressing `Ctrl+Shift+X`. +2. Open the Extension side panel by pressing `Ctrl+Shift+X`. In the search bar at the top of this panel search for each of the following extensions and press `Install` for the first entry that appears. {% include vs-code-extensions.html %} +{% include copilot-setup.html %} + ### Python 1. Open a new terminal and type the following lines (separately) into the @@ -57,23 +63,23 @@ When following the GitHub docs below, make sure to select the **Linux** instruct bash Miniconda3-latest-Linux-x86_64.sh ``` -1. A license agreement will be displayed and the bottom of the terminal will read `--More--`. +2. A license agreement will be displayed and the bottom of the terminal will read `--More--`. Press `Enter` or the space bar until you are prompted with - "Do you accept the license terms? [yes|no]." - Type `yes` and then press `Enter` -1. The installation script will inform you that it is going to install into a default directory (e.g., `/home/$USER/miniconda3`). + `Do you accept the license terms? [yes|no]`. + Type `yes` and then press `Enter`. +3. The installation script will inform you that it is going to install into a default directory (e.g., `/home/$USER/miniconda3`). Leave this default and press `Enter`. -1. When you are asked - "Do you wish the installer to initialize Miniconda3 by running conda init? [yes|no]," +4. When you are asked + `Do you wish the installer to initialize Miniconda3 by running conda init? [yes|no]`, type `yes` and press `Enter`. Exit the terminal once the installation has finished. -1. Re-open a new terminal. - Type `which python` into the terminal and it should return a path (e.g., `/home/$USER/miniconda3/bin/python`). - - If you do not see a path like this then please try typing `conda init`, +5. Re-open a new terminal. + Type `which python` into the terminal and check that it returns a path like `/home/$USER/miniconda3/bin/python`. + - If you do not see a path like this, try typing `conda init`, closing your terminal, and repeating this step. If your issue is still not resolved skip the following step and contact an instructor on the `#help-installation` channel of the Slack workspace. -1. Type the following to remove the installation script that was downloaded: +6. Type the following to remove the installation script that was downloaded: ```bash rm ./Miniconda3-latest-Linux-x86_64.sh @@ -90,13 +96,24 @@ When following the GitHub docs below, make sure to select the **Linux** instruct [Debian](https://docs.docker.com/engine/install/debian/), [Fedora](https://docs.docker.com/engine/install/fedora/), [CentOS](https://docs.docker.com/engine/install/centos/)). Make sure to - follow the “Install using the repository” method! -1. Once you’ve installed Docker make sure to follow the + follow the "Install using the repository" method! +2. Once you've installed Docker make sure to follow the [post-install instructions](https://docs.docker.com/engine/install/linux-postinstall/) - as well. You only need to do the “Manage Docker as a non-root user” and - “Configure Docker to start on boot” steps. -1. Open a new terminal and type `docker run hello-world`. A brief introductory - message should be printed to the screen. + as well. You only need to do the "Manage Docker as a non-root user" and + "Configure Docker to start on boot" steps. +3. Open a new terminal and type `docker run hello-world`. + If the installation worked, a brief introductory message should be printed to the screen. + +### Install the `tree` command + +`tree` is a helpful command for viewing directory structures, and is strongly recommended. + +1. Open a terminal, and check if you have `tree` already installed by running `tree --version`. + - If you see a version number, you're all set! + - If you see a message like `tree: command not found`, install it by running: + ```bash + sudo apt-get update && sudo apt-get install -y tree + ``` --- diff --git a/setup/mac.md b/setup/mac.md index 5dca138..07460b6 100644 --- a/setup/mac.md +++ b/setup/mac.md @@ -6,17 +6,26 @@ description: Instructions for setting up on Mac ### Bash shell -You already have it! Depending on which version of Mac OS you’re running you may -need to type `bash` inside the terminal to access it. To check whether this is -necessary, follow these steps: +On Mac OS, you already have a `bash` shell installed! +However, depending on your OS version, you may have a different _default_ shell (e.g., `zsh`). -1. Open a terminal and type `echo $SHELL`. If it reads `/bin/bash` then you are - all set! +To check your default shell, open a terminal and type `echo $SHELL`. +If the output reads `/bin/bash`, you are all set! -Note: If you are using Mac Catalina (10.15.X) or later, then it is possible your default -shell is NOT CORRECT. To set the default to bash, type `chsh -s /bin/bash` in -the terminal, enter your password when prompted, and then close + re-open the -terminal. +If the output is something else (e.g., `/bin/zsh`), we strongly recommend changing your default shell to `bash` for this course. +To do so, + +1. Run: + ```bash + chsh -s /bin/bash + ``` +2. Enter your password when prompted. +3. Close and re-open the terminal. +4. Run `echo $SHELL` again to confirm it now shows `/bin/bash`. + +All instructions in the course will assume you are using `bash`. + +> **Note**: After the course, you can switch back to your original shell using `chsh -s /bin/zsh` (or whatever your original shell was). ### Homebrew @@ -41,40 +50,48 @@ In the terminal, run: brew install git ``` -(If you already installed `git` through the Xcode Command Line Tools, that is fine, so you don't need to worry.) +(If you already installed `git` through the Xcode Command Line Tools, don't worry, that is fine.) Verify the installation by running `git --version`: this time you should see something like `git version X.XX.X`. {% include extra-git-setup.html %} -#### Creating an SSH key for GitHub +#### Create an SSH key for GitHub -When following the GitHub docs below, make sure to select the **Mac** instructions. +When following the GitHub docs in the steps below, make sure to select the **Mac** instructions at the top of the page. {% include gh-ssh-key-setup.html %} ### VSCode -1. Go to [this page](https://code.visualstudio.com/) and click the download button. -1. Unzip the downloaded file (for example, `VSCode-darwin-universal.zip`) and move the resulting `Visual Studio Code` file to your Applications directory. +1. On this [page](https://code.visualstudio.com/docs/setup/mac#_install-vs-code-on-macos), follow all steps in the following two sections **only**: + - [Install VS Code on MacOS](https://code.visualstudio.com/docs/setup/mac#_install-vs-code-on-macos) + - To begin the download, click on the "Download Visual Studio Code" link + - [Launch VS Code from the command line](https://code.visualstudio.com/docs/setup/mac#_launch-vs-code-from-the-command-line) + - Use the method "Configure the path with VS Code" to set up the `code` command in your terminal + + You can skip all other sections on that page. + +2. To confirm that everything worked, open a terminal and type `code .` (include the period). +This should open the current directory in a VSCode window. + +{% include vs-code-workspace-trust-popup.html %} #### VSCode extensions -1. Open the Visual Studio Code application -1. Type `Cmd+Shift+P` to open the "command palette" at the top of the screen and then enter - `Shell command: Install 'code' command in PATH`. - Select the highlighted entry. - A notification box should appear in the bottom-right corner indicating that the command was installed successfully. -1. Open the Extension side panel by pressing `Cmd+Shift+X`. +1. Open the Visual Studio Code application. +2. Open the Extension side panel by pressing `Cmd+Shift+X`. In the search bar at the top of this panel search for each of the following extensions and press `Install` for the first entry that appears. {% include vs-code-extensions.html %} +{% include copilot-setup.html %} + ### Python 1. Open a new terminal and type the following command, then press `Enter`. - - If you are on an Apple Silicon Mac (upper left corner Apple menu -> `About This Mac` says something like "Chip: Apple M1" (or M2, etc.)): + - If you are on an Apple Silicon Mac (upper left corner Apple menu -> `About This Mac` says something like "Chip: Apple M1" (or M2, etc.)): ```bash curl -O https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-arm64.sh ``` @@ -83,22 +100,22 @@ When following the GitHub docs below, make sure to select the **Mac** instructio curl -O https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-x86_64.sh ``` -1. Run the installation script: +2. Run the installation script: ```bash bash Miniconda3-latest-MacOSX-x86_64.sh ``` - A license agreement will be displayed and the bottom of the terminal will read `--More--`. - Press `Enter` or the space bar until you are prompted with "Do you accept the license terms? [yes|no]." - Type `yes` and then press `Enter` - - The installation script will inform you that it is going to install into a default directory (e.g., `/Users/$USER/miniconda3`). + Press `Enter` or the space bar until you are prompted with `Do you accept the license terms? [yes|no]`. + Type `yes` and then press `Enter`. + - The installer will show a default installation directory (e.g., `/Users/$USER/miniconda3`). Leave this default and press `Enter`. - - When you are asked "Do you wish the installer to initialize Miniconda3 by running conda init? [yes|no]," type `yes` and press `Enter`. + - When you are asked `Do you wish the installer to initialize Miniconda3 by running conda init? [yes|no]`, type `yes` and press `Enter`. - Exit the terminal once the installation has finished. -1. Re-open a terminal. - Type `which python` into the terminal and it should return a path (e.g., `/Users/$USER/miniconda3/bin/python`). - - If you do not see a path like this then please try typing `conda init`, closing your terminal, and repeating this step. - If your issue is still not resolved. skip the following step and contact an instructor on the #help-installation channel of the QLS612-BHS Slack. -1. Type the following to remove the installation script that was downloaded: +3. Re-open a terminal. + Type `which python` into the terminal and check that it returns a path like: `/Users/$USER/miniconda3/bin/python`. + - If you do not see a path like this, try typing `conda init`, closing your terminal, and repeating this step. + If your issue is still not resolved, skip the following step and contact an instructor on the #help-installation channel of the QLS612-BHS Slack. +4. Type the following to remove the installation script that was downloaded: ```bash rm ./Miniconda3-latest-MacOSX-x86_64.sh @@ -123,12 +140,23 @@ When following the GitHub docs below, make sure to select the **Mac** instructio Wait until it reads `Docker Desktop is now up and running!` 1. Open a new terminal and type `docker run hello-world`. - A brief introductory message should be printed to the screen. + If the installation worked, a brief introductory message should be printed to the screen. The above step-by-step Docker instructions are distilled from [here](https://docs.docker.com/desktop/setup/install/mac-install/). If you have questions during the installation procedure please check that link for potential answers! +### Install the `tree` command + +`tree` is a helpful command for viewing directory structures, and is strongly recommended. + +1. Open a terminal, and check if you have `tree` already installed by running `tree --version`. + - If you see a version number, you're all set! + - If you see a message like `tree: command not found`, install it by running: + ```bash + brew install tree + ``` + --- diff --git a/setup/setup.md b/setup/setup.md index a4fc295..0ce2d10 100644 --- a/setup/setup.md +++ b/setup/setup.md @@ -25,8 +25,8 @@ steps you can take to ensure you are ready for the lectures. ## Required software -To get the most out of our course, please arrive with the -software listed below **already installed** (or to the best of your ability). +To get the most out of our course, **please arrive with the +software listed below already installed** (or to the best of your ability). The rest of this page provides installation procedures for each of the above programs, including specific instructions for each of the three major operating systems (Windows, Mac OS, and Linux). @@ -38,7 +38,6 @@ operating systems (Windows, Mac OS, and Linux). - A virtualization system: Docker - A GitHub account - Slack -- Zoom - A modern browser ### Some quick general notes on instructions @@ -56,12 +55,12 @@ operating systems (Windows, Mac OS, and Linux). ### GitHub account -Go to [https://github.com/join/](https://github.com/join/) and follow the -on-screen instructions to create an account. -We recommend associating this -with your university e-mail (if you have one) as this will entitle you to sign -up for the [GitHub Student Developer Pack](https://education.github.com/pack) -which comes with some nice free bonuses. +1. Follow the instructions at [https://github.com/join/](https://github.com/join/) to create an account. +We recommend using your university e-mail for the account if you have one (you can always change it later or add a secondary e-mail). + +2. We strongly recommend also signing up for [GitHub Education Student](https://github.com/education/students), +which provides free access to perks and tools including the [GitHub Student Developer Pack](https://education.github.com/pack). +The application process is very quick, and verification typically takes no more than a couple days at most. ### Slack @@ -69,18 +68,15 @@ Go to [https://slack.com/downloads/](https://slack.com/downloads/) and download -### Zoom - -Go to [https://zoom.us/download](https://zoom.us/download) and download and install the Zoom client. - ### Modern web browser Install Firefox, Chrome, or Safari. ### OS-specific installation instructions -Select the link that corresponds to your operating system and follow the -instructions provided. Please direct any questions to the `#help-installation` +Once you have completed the above general setup, select the link that corresponds to your operating system and follow the +instructions provided. +Please direct any questions to the `#help-installation` channel in the QLS612 Slack. - [Linux]({{ site.url }}/setup/linux.html) diff --git a/setup/windows.md b/setup/windows.md index 878d242..fb06aa9 100644 --- a/setup/windows.md +++ b/setup/windows.md @@ -6,7 +6,7 @@ description: Instructions for setting up on Windows ### WSL2 (Windows Subsystem for Linux version 2) -WSL (Windows Subsystem for Linux) allows you to use Linux on top of Windows +WSL (Windows Subsystem for Linux) lets you use Linux on top of Windows natively. WSL2 is the latest version of WSL and is more stable with improved performance and compatibility. If you already have WSL(1), it is easy to convert to WSL2 (see [Instructions to convert WSL(1) to WSL2](https://learn.microsoft.com/en-us/windows/wsl/install#upgrade-version-from-wsl-1-to-wsl-2)). @@ -29,7 +29,7 @@ see the "Install WSL2 on Windows 10 (older versions)" section on this [page](htt Select `Yes` on the prompt that appears asking if you want to allow the app to make changes to your device. 5. At this point, if you are on a newer version of Windows 10 or Windows 11, the command from Step 2 should have installed, in addition to WSL, - the latest LTS version of Ubuntu (24.04 LTS at time of writing) as the default distribution. + the latest LTS version of Ubuntu (26.04 LTS at time of writing) as the default distribution. If this is the case, an Ubuntu terminal will open to resume automatic setup, and afterwards will ask you set up a username and password. **If this applies to you, skip to Step 9. @@ -41,7 +41,7 @@ see the "Install WSL2 on Windows 10 (older versions)" section on this [page](htt wsl --list --online ``` -7. Type the following command to install a specific distro (Ubuntu-22.04 +7. Type the following command to install a specific distro (Ubuntu-26.04 recommended) in WSL and press `Enter` (it will start the distro if it has already been installed): @@ -51,18 +51,19 @@ see the "Install WSL2 on Windows 10 (older versions)" section on this [page](htt 8. Restart your computer, open **Start (Win key)** and search for **Ubuntu**, and click on the app called **Ubuntu** or **Ubuntu \+ NOTE: + The first time you run
+code .in a folder, + you may see a popup asking "Do you trust the authors of the files in that folder?" ++ Select "Yes, I trust the authors", and if available, also check the box that says + "Trust the authors of all files in the parent folder". + This will enable full features and extensions in your VSCode workspace. +
+