commit 0c6e919bdd1475b1488ef2799c5d4e90f68a7e10 Author: Eric Furst Date: Thu May 28 10:09:13 2026 -0400 Initial commit: computing-setup A two-module standalone guide for setting up a new machine for scientific computing work: - 01-know-your-machine: hardware and OS inspection. Reads the physical machine first via macOS/Linux terminals or Windows PowerShell; a separate section walks through the WSL VM and how its allocations differ from the host hardware. - 02-git-basics: pull-focused git workflow. Install, configure identity, clone a public repo, pull updates. Authentication and pushing are deferred to a future collaboration module. Includes top-level WSL.md (copied from cli-walkthrough) for Windows users who need the Linux environment. Co-Authored-By: Claude Opus 4.7 diff --git a/01-know-your-machine/README.md b/01-know-your-machine/README.md new file mode 100644 index 0000000..dbf2134 --- /dev/null +++ b/01-know-your-machine/README.md @@ -0,0 +1,313 @@ +# Know Your Machine + +## Key idea + +Understand the basic hardware and software of the computer you are working on. + +## Key goals + +- Identify your operating system, CPU, RAM, storage, and GPU +- Understand what these components do and why they matter for computing tasks +- Learn commands to query your system on macOS, Linux, and Windows + +> **Read your *physical* machine first.** Sections 1–6 walk through inspecting the actual hardware you own. On macOS and Linux, the terminal reports directly from the hardware. On Windows, use **PowerShell** (or the Settings GUI) — those readings come straight from the real machine. +> +> **Then visit the WSL VM separately (Section 7).** If you are on Windows and have WSL installed, your Linux environment is a *virtual machine* that sees only what it has been allocated. Section 7 covers how to inspect that and why it differs from the physical machine. If you do not yet have WSL installed, see [../WSL.md](../WSL.md). + +--- + +As engineers, we should know our tools. You would not run a reactor without knowing its volume, pressure rating, and materials of construction. The same principle applies to computing: before we write code, train models, or analyze data, we should understand the machine we are working on. + +This module is a hands-on survey. Run the commands below on your own machine and record what you find. By the end, you should be able to answer: *What is my computer, and what can it do?* + + +## 1. Operating system + +Your operating system (OS) manages the hardware and provides the environment where all your programs run. The three major OS families are: + +- **macOS** -- Apple's OS, based on Unix (Darwin kernel). Runs on Intel and Apple Silicon (M1/M2/M3/M4) hardware. Closely related to iOS, watchOS, and other Apple systems. (These are all, in fact, computers!) +- **Linux** -- Open-source Unix-like OS. Many distributions exist (Ubuntu, Fedora, etc.). Common on servers, clusters, and in WSL. +- **Windows** -- Microsoft's OS. For terminal-based work, we recommend the Windows Subsystem for Linux (WSL) to access a Unix environment. + +### Find your OS version + +**macOS:** +In the terminal, use the command +```bash +sw_vers +``` + +**macOS (GUI):** Apple menu > About This Mac. Shows the macOS version, chip (e.g., Apple M3), and memory. + +**Linux:** +```bash +cat /etc/os-release +uname -a +``` + +The `uname -a` command shows the kernel version and architecture. You will see something like `x86_64` (Intel/AMD) or `aarch64`/`arm64` (ARM). + +**Windows (PowerShell):** +```powershell +Get-ComputerInfo | Select-Object OsName, OsVersion, OsArchitecture +``` + +This tells you the Windows version and architecture of the physical machine. + +**Windows (GUI):** Settings > System > About. Shows the edition (Home, Pro), version, and processor. + +> **Exercise 1:** Run the commands above. What OS and version are you running? What architecture? + + +## 2. CPU (processor) + +The CPU (Central Processing Unit) executes your code. Key properties: + +- **Architecture**: `x86_64` (Intel/AMD) or `arm64` (Apple Silicon, some Windows laptops). This affects which software binaries you can run. +- **Cores**: Modern CPUs have multiple cores that can work in parallel. More cores help with parallel tasks (compiling, running simulations, some ML training). +- **Clock speed**: Measured in GHz. Higher is faster for single-threaded tasks, but clock speed alone does not tell the whole story. + +### Find your CPU + +**macOS:** +```bash +sysctl -n machdep.cpu.brand_string +sysctl -n hw.ncpu +``` + +The first command shows the CPU model. The second shows the total number of cores (including efficiency and performance cores on Apple Silicon). + +**macOS (GUI):** Apple menu > About This Mac shows the chip (e.g., "Apple M3 Pro"). For core count, open Activity Monitor > CPU tab or run the command above. + +**Linux:** +```bash +lscpu +``` + +This shows the CPU model, architecture, number of cores, and clock speed. + +**Windows (PowerShell):** +```powershell +Get-CimInstance Win32_Processor | Select-Object Name, NumberOfCores, NumberOfLogicalProcessors, MaxClockSpeed +``` + +**Windows (GUI):** Settings > System > About shows the processor name. For more detail, open Task Manager (Ctrl+Shift+Esc) > Performance > CPU. This shows cores, logical processors, and clock speed. + +### Why it matters + +Heavy numerical work — simulations, data processing, training machine-learning models — runs faster with more cores and higher clock speed. Even so, CPUs are orders of magnitude slower than GPUs for highly parallel tasks like neural network training, which is why we also look at GPUs below. + +> **Exercise 2:** What CPU does your machine have? How many cores? What architecture? + + +## 3. RAM (memory) + +RAM (Random Access Memory) is your computer's short-term working space. When you open a program, load a dataset, or run a model, the data lives in RAM. Key things to know: + +- RAM is **volatile**: it is erased when you shut down. +- RAM is **fast**: much faster than reading from disk. +- RAM is **limited**: if you run out, the OS will start using disk as overflow ("swap"), which is extremely slow. + +### Find your RAM + +**macOS:** +```bash +sysctl -n hw.memsize | awk '{printf "%.0f GB\n", $1/1024/1024/1024}' +``` + +**macOS (GUI):** Apple menu > About This Mac shows memory (e.g., "18 GB"). For current usage, open Activity Monitor > Memory tab. + +**Linux:** +```bash +free -h +``` + +This shows total, used, and available memory. The `-h` flag makes the output human-readable (GB instead of bytes). + +**Windows (PowerShell):** +```powershell +[math]::Round((Get-CimInstance Win32_ComputerSystem).TotalPhysicalMemory / 1GB, 1) +``` + +This returns the **physical** RAM installed on the machine. WSL users: this is the number you want — running `free -h` inside WSL would only show the VM's allocation. See Section 7. + +**Windows (GUI):** Settings > System > About shows "Installed RAM". For current usage, open Task Manager (Ctrl+Shift+Esc) > Performance > Memory. + +### Why it matters + +Loading a large dataset or model weights means everything in active use has to fit in RAM. A modern large language model can be 4–8 GB or more; if you load one on an 8 GB machine alongside your OS, editor, and a browser, you may run out. When that happens the system swaps to disk and *everything* slows down dramatically. Knowing your RAM ceiling helps you plan what is realistic to run. + +> **Exercise 3:** How much physical RAM does your machine have? Use the appropriate command for your OS above. How much is currently in use? + + +## 4. Storage (disk) + +Storage is where your files, programs, and OS live permanently. Unlike RAM, it persists when you shut down. The two main types: + +- **SSD (Solid State Drive)**: Fast, no moving parts. Standard on modern laptops. +- **HDD (Hard Disk Drive)**: Slower, mechanical. Sometimes used for bulk storage. + +### Find your storage + +**macOS:** +```bash +df -h / +``` + +**macOS (GUI):** Apple menu > About This Mac > More Info > Storage. Shows total capacity, used space, and a breakdown by category. + +**Linux:** +```bash +df -h / +``` + +**Windows (PowerShell):** +```powershell +Get-Volume | Where-Object DriveLetter -eq 'C' | Select-Object DriveLetter, @{N='Size(GB)';E={[math]::Round($_.Size/1GB)}}, @{N='Free(GB)';E={[math]::Round($_.SizeRemaining/1GB)}} +``` + +This is the physical C: drive's total size, used, and available space. WSL users: this is your real disk; the WSL VM has its own virtual disk that we look at in Section 7. + +**Windows (GUI):** Settings > System > Storage. Shows total capacity and usage per drive. You can also open File Explorer, right-click the C: drive, and select Properties. + +### Why it matters + +Software adds up fast. A rough sense of common items: + +| Item | Approximate size | +|------|-----------------| +| A Python environment with scientific libraries | 1–3 GB | +| A local large language model | 1–20 GB each | +| A course or project repository | 50–500 MB | +| Datasets | varies widely (MB to TB) | + +If you are low on storage, be selective about what you install, and clean up environments and downloaded models you no longer need. + +> **Exercise 4:** How much total storage does your machine have? How much is free? Is it an SSD or HDD? (On macOS, check Apple menu > About This Mac > More Info. On Linux, `lsblk` shows disk devices.) + + +## 5. GPU (graphics processor) + +A GPU (Graphics Processing Unit) was originally designed for rendering graphics, but its architecture (thousands of small cores optimized for parallel math) makes it excellent for machine learning. There are three common situations: + +- **NVIDIA GPU (discrete)**: Found in gaming laptops and workstations. Supports CUDA, which PyTorch uses for fast training. This is the best case for ML work. +- **Apple Silicon GPU (integrated)**: The M1/M2/M3/M4 chips include a GPU that PyTorch can use via MPS (Metal Performance Shaders). Faster than CPU, slower than a dedicated NVIDIA GPU. +- **Intel/AMD integrated GPU**: Built into the CPU. Not usable by PyTorch. Use `--device=cpu`. + +### Find your GPU + +**macOS (Apple Silicon):** +```bash +system_profiler SPDisplaysDataType +``` + +If you see "Apple M1" (or M2, M3, M4), you have an integrated GPU that supports MPS. + +**macOS (GUI):** Apple menu > About This Mac shows the chip. Apple Silicon chips (M1/M2/M3/M4) all include a GPU. + +**Linux (NVIDIA):** +```bash +nvidia-smi +``` + +If this command works, you have an NVIDIA GPU and the drivers are installed. It shows the GPU model, driver version, and memory. If the command is not found, you either do not have an NVIDIA GPU or the drivers are not installed. + +**Windows (PowerShell):** +```powershell +Get-CimInstance Win32_VideoController | Select-Object Name, AdapterRAM, DriverVersion +``` + +This lists every GPU Windows sees on the physical machine — useful on laptops that have both an integrated GPU (Intel/AMD) and a discrete one (NVIDIA). + +**Windows (GUI):** Task Manager (Ctrl+Shift+Esc) > Performance > GPU. This shows the GPU name (e.g., "NVIDIA GeForce RTX 4060" or "Intel UHD Graphics"), memory, and utilization. + +**No GPU or unsure:** + +If you have PyTorch installed, you can ask it directly: + +```bash +python -c "import torch; print('CUDA:', torch.cuda.is_available()); print('MPS:', torch.backends.mps.is_available())" +``` + +This tells you what PyTorch can use on your machine. + +### Why it matters + +Training a small neural network on CPU takes minutes; on a GPU, seconds. The difference grows dramatically with model size — this is why large language models are trained on clusters of thousands of GPUs. For most introductory computing work, a CPU is sufficient. GPU acceleration is a bonus, not a requirement. + +> **Exercise 5:** What GPU (if any) does your machine have? Can PyTorch use it? Run the Python check above (if you have PyTorch installed). + + +## 6. Putting it all together + +Fill in this table for your machine: + +| Component | Your machine | +|-----------|-------------| +| Operating system | | +| OS version | | +| Architecture (x86_64 / arm64) | | +| CPU model | | +| CPU cores | | +| RAM (total) | | +| Storage (total / free) | | +| GPU | | +| PyTorch device (cpu / mps / cuda) | | + +### One-line system summary + +**macOS:** +```bash +echo "$(sw_vers -productName) $(sw_vers -productVersion), $(sysctl -n machdep.cpu.brand_string), $(sysctl -n hw.ncpu) cores, $(sysctl -n hw.memsize | awk '{printf "%.0f GB", $1/1024/1024/1024}') RAM" +``` + +**Linux:** +```bash +echo "$(uname -o) $(uname -r), $(lscpu | grep 'Model name' | sed 's/.*: *//' ), $(nproc) cores, $(free -h | awk '/Mem:/ {print $2}') RAM" +``` + +> **Exercise 6:** Fill in the table above. If you are working alongside others, compare with a classmate or colleague. How are your machines different? How might those differences affect the kinds of work each of you can do comfortably? + + +## 7. Inspecting your WSL environment (Windows + WSL users) + +If you are on Windows and use the Windows Subsystem for Linux (WSL), your Linux environment runs inside a **virtual machine** managed by Windows. The Linux commands from sections 1–5 will all work inside WSL, but the answers they give are about *the VM*, not the physical machine you already inspected. Some readings match the host; others are very different. Understanding which is which is the goal of this section. + +| Reading | Inside WSL you see... | Notes | +|---------|----------------------|-------| +| OS (`uname -a`, `cat /etc/os-release`) | The Linux distribution and kernel running in the VM | Has nothing to do with your Windows version | +| CPU (`lscpu`) | The host CPU model, architecture, and core count | Passed through from the physical machine — should match what PowerShell told you | +| RAM (`free -h`) | The RAM allocated to the VM | By default, about half your physical RAM, capped at 8 GB. Configurable in a `.wslconfig` file — see the [Microsoft docs](https://learn.microsoft.com/en-us/windows/wsl/wsl-config) | +| Disk (`df -h /`) | A virtual disk (`ext4.vhdx`) stored on your Windows drive | Not the same as the C: drive. The VM grows the file on demand up to a configured maximum | +| GPU (`nvidia-smi`) | An NVIDIA GPU, *if* the Windows-side driver supports WSL | Recent NVIDIA Windows drivers include WSL support. No separate Linux driver is installed inside WSL. See [NVIDIA's CUDA on WSL guide](https://docs.nvidia.com/cuda/wsl-user-guide/) | + +### Why this matters + +When you install Python, run a model, or train something *inside WSL*, you are constrained by the VM's allocation, not the machine's full capacity. An 8 GB RAM cap inside WSL can mean a model loads fine on the Windows side but fails inside WSL. Knowing both numbers — physical and VM — lets you predict what will actually run where. + +> **Exercise 7 (WSL users):** Run `free -h` and `df -h /` inside WSL. Compare the results to the PowerShell readings you recorded in Section 6. How much physical RAM does your VM actually see? How much of your physical disk is the VM using right now? + + +## 8. Keeping a machine log + +Engineers keep logs for lab equipment, process equipment, and instruments. Your computer deserves the same treatment. Create a document called `machine_log` in your personal files and start it with the spec table from section 6. It should be a simple format — a text, rich text, or markdown file. + +While you are at it, *give your machine a name* if you have not already. (On macOS: System Settings > General > About > Name. On Linux: `hostnamectl set-hostname yourname`. On Windows: Settings > System > About > Rename this PC.) A named machine is easier to reference in logs, SSH configs, and conversation, especially once you have more than one. Put the name at the top of your log. + +After that, add a dated entry whenever you: + +- **Install or upgrade the OS** or major software +- **Change system configuration** (environment variables, shell settings, drivers, WSL setup) +- **Encounter a problem and solve it** (the error, what you tried, what worked) +- **Upgrade hardware** (new RAM, new drive, etc.) + +Keep entries short. Date, what changed, and the outcome. When something breaks months later, you will be glad you wrote down what you changed and when. This is especially valuable when troubleshooting: knowing what was different before the problem started is often the fastest path to a fix. + +> **Exercise 8:** Start your machine log. Put the spec table at the top and add an entry for today. + + +## Additional resources + +- [Crash Course Computer Science](https://www.youtube.com/playlist?list=PL8dPuuaLjXtNlUrzyH5r6jN9ulIgZBpdo) — episodes 1-10 cover hardware fundamentals (transistors, ALU, registers, RAM, CPU, instructions) at a reasonable pace +- J. Clark Scott, *But How Do It Know?* — a short, readable book that builds a computer from logic gates up. Good for understanding what is actually happening inside the machine. +- `top` and `htop` — interactive process viewers that show CPU, memory, and process usage in real time. `top` is the classic Unix tool and ships built-in on macOS and Linux, so it's always available. `htop` is a more modern third-party rewrite: colored CPU/memory bars, a scrollable process list, click-to-sort columns, F-keys (or mouse) to kill/renice/filter processes, an F5 tree view, and the same behavior everywhere (macOS `top` and Linux `top` differ in flags and output; `htop` does not). Install with `brew install htop` (macOS) or `sudo apt install htop` (Linux/WSL). Worth knowing both — `top` for "wherever I land," `htop` for daily use on your own machine. diff --git a/02-git-basics/README.md b/02-git-basics/README.md new file mode 100644 index 0000000..715af79 --- /dev/null +++ b/02-git-basics/README.md @@ -0,0 +1,235 @@ +# Git Basics + +## Key idea + +Install git, configure your identity, and use it to download and stay current with materials published in a public repository. + +## Key goals + +- Install git on macOS, Linux, or WSL +- Set your git identity (`user.name`, `user.email`) +- Clone a public repository +- Check repository state with `git status` +- Pull updates with `git pull` +- Know which commands to avoid until you understand them + +This module is **pull-focused**. Authentication, pushing your own commits, branching, and merging belong in a later module on git collaboration. For now, the goal is to *receive* updates reliably. + +> **Windows users:** install WSL before starting this module — see [../WSL.md](../WSL.md). All commands below assume a Unix-style terminal (macOS, Linux, or WSL). + +--- + +## What is git? + +Git is a **version control** system. It tracks changes to files over time, lets you go back to earlier states, and lets many people work on the same files without overwriting each other. + +A **repository** (often "repo") is a folder that git is tracking. Public repositories on hosting services like [Gitea](https://about.gitea.com/), GitHub, or GitLab can be downloaded ("cloned") by anyone — no account needed. + +For now we will use git only to *download* materials and *keep them up to date*. You will not need to push anything back, and you do not need an account on any hosting service. + + +## 1. Install git + +### macOS + +The easiest path is [Homebrew](https://brew.sh/): + +```bash +brew install git +``` + +If you don't have Homebrew, install the Xcode Command Line Tools (which include git): + +```bash +xcode-select --install +``` + +### Linux / WSL (Ubuntu/Debian) + +```bash +sudo apt update +sudo apt install -y git +``` + +For other Linux distributions, use the appropriate package manager (`dnf install git`, `pacman -S git`, etc.). + +### Verify + +```bash +git --version +``` + +You should see something like `git version 2.40.1`. If the command is not found, the install did not finish — try again. + +> **Tip (WSL users):** Run all git commands from inside your Linux home directory (e.g., `~/repos`), not from `/mnt/c/...`. Mixing Windows-side and WSL-side git on the same folder leads to permission and line-ending headaches. + + +## 2. Configure your identity + +Git stamps every commit with a name and email. Set yours once — these are labels on your local commits and do not need to match any account on a hosting service. + +```bash +git config --global user.name "Your Name" +git config --global user.email "you@example.com" +``` + +Use your real name and a real email so future-you (and any collaborators) can identify your work. + +Verify: + +```bash +git config --global --list +``` + +You should see `user.name` and `user.email` in the output. + + +## 3. Clone a public repository + +To download a repository, copy its clone URL from the hosting service (usually a button labeled "Clone" or shown prominently on the project page) and run: + +```bash +git clone +``` + +For example: + +```bash +git clone https://lem.che.udel.edu/git/furst/cli-walkthrough.git +``` + +This creates a folder named `cli-walkthrough` in your current directory. Move into it: + +```bash +cd cli-walkthrough +``` + +> **Tip:** Be intentional about *where* you clone. Many people keep all their repos under one directory, e.g., `~/repos` or `~/code`. Avoid cloning into folders synced by Dropbox, iCloud, or OneDrive — sync conflicts and git history do not mix well. + + +## 4. Check the state of a repository + +Inside any cloned repo, you can always ask git what is going on: + +```bash +git status +``` + +If you have not edited anything, you will see "nothing to commit, working tree clean." If you have edited files, git lists them. + +`git status` is non-destructive. Run it whenever you are unsure what state things are in. It is the single most useful git command. + + +## 5. Pull updates + +When the maintainer of the repository publishes changes, get them with: + +```bash +git pull +``` + +Run this from inside the repo (the folder you `cd`'d into after cloning). + +**`git pull` does not silently overwrite your work.** + +- If you have made no local changes → files update normally. +- If you have local changes that don't conflict with incoming changes → git merges them automatically. +- If there is a conflict → git **stops** and tells you exactly which files need attention. Your work is preserved. + +Get in the habit of running `git pull` before you start working in a shared repo, so you start from the latest version. + + +## 6. Saving your work locally + +Even when you are not pushing anywhere, committing locally is a good habit. A commit is a labeled snapshot you can return to later. + +```bash +git add . +git commit -m "short description of what you changed" +``` + +`git add .` stages every changed file in the current folder; `git commit` saves the snapshot with your message. + +This is also useful right before pulling updates — see section 7. + + +## 7. If `git pull` refuses to run + +Sometimes git declines to pull because you have uncommitted changes that overlap with incoming updates. Two safe ways out: + +### Option A — Commit your work first + +```bash +git add . +git commit -m "save before pull" +git pull +``` + +### Option B — Temporarily set work aside + +```bash +git stash +git pull +git stash pop +``` + +`git stash` puts your uncommitted changes on a shelf; `git stash pop` restores them after the pull. Useful when you want to grab updates without committing half-finished work. + + +## 8. Commands you should NOT use (yet) + +These commands can permanently delete uncommitted work: + +```bash +git reset --hard +git clean -fd +git checkout -- . +``` + +Do not run them unless you understand exactly what they do and have intentionally chosen the consequences. When in doubt, ask first. + + +## 9. If something looks wrong + +First, do not panic. Git is conservative — it does not overwrite committed work without a clear instruction. Most "something is wrong" situations are recoverable. + +Run: + +```bash +git status +``` + +and read what it says. Git is unusually good at explaining the current state and suggesting next steps in its output. If you are still stuck, ask for help **before** running any of the destructive commands from section 8. + + +## 10. When you eventually need authentication + +Anonymous cloning and pulling work for **public** repositories. You will need authentication when you want to: + +- Push your own commits back to a remote repo +- Clone or pull from a **private** repository +- Use collaboration features (branches, pull requests, etc.) + +Those topics — personal access tokens, SSH keys, branching, merging, pushing — are the subject of a follow-on module on git collaboration. For now, pull is enough. + + +## Exercises + +> **Exercise 1:** Install git on your machine and run `git --version`. Record the version in your machine log. + +> **Exercise 2:** Set your `user.name` and `user.email` with `git config --global`. Verify with `git config --global --list`. + +> **Exercise 3:** Clone a public repository of your choosing (the cli-walkthrough URL above works as a default). Where did you clone it to? + +> **Exercise 4:** Run `git status` inside the cloned repo. What does it report? + +> **Exercise 5:** Run `git pull` inside the same repo. What does it report? (If nothing has changed upstream, that is fine — record what you see.) + + +## Key takeaway + +- Git is a tool for tracking changes and synchronizing work +- Public repositories can be cloned and pulled without an account +- `git pull` is safe — it will not silently destroy your work +- `git status` is your friend; run it whenever you are unsure +- Authentication, pushing, and branching come later diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..1a4f640 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Eric M. Furst, University of Delaware + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..081b65b --- /dev/null +++ b/README.md @@ -0,0 +1,38 @@ +# Computing Setup + +A short, hands-on guide to getting your machine ready for scientific computing work. There are two modules: + +1. [**Know your machine**](01-know-your-machine/) — identify your OS, CPU, RAM, storage, and GPU, and learn what each does. +2. [**Git basics**](02-git-basics/) — install git, configure it, and use it to download and update course (or any public) materials. + +This repo is designed for students starting a computing course, but should be useful for anyone setting up a new machine or getting acquainted with one they already own. + +A follow-on module on git collaboration (authentication, branching, merging, pushing) is planned. For now, this guide is pull-only. + +## Prerequisites + +- A terminal — Terminal or iTerm on macOS, any terminal emulator on Linux, or PowerShell on Windows +- No prior command line or git experience required + +**Windows users — no extra setup to start.** You can work through most of module 01 using PowerShell alone. You will, however, want the Windows Subsystem for Linux (WSL) before tackling module 02 (git) and the optional WSL section at the end of module 01. See [WSL.md](WSL.md) when you get there. + +## How to use this guide + +You can read each module right here on the web — no setup needed to start. Each module is self-contained and tells you exactly which commands to run on your own machine. + +Once you have completed module 02 (git), you can optionally clone this repository for offline access: + +```bash +git clone https://lem.che.udel.edu/git/furst/computing-setup.git +cd computing-setup +``` + +Each module has its own `README.md` with a walkthrough and exercises. + +## License + +MIT + +## Author + +Eric M. Furst, University of Delaware diff --git a/WSL.md b/WSL.md new file mode 100644 index 0000000..8400153 --- /dev/null +++ b/WSL.md @@ -0,0 +1,162 @@ +# Installing WSL (Windows Subsystem for Linux) + +This guide walks you through installing WSL on Windows 10 or 11. macOS and Linux users can skip this entirely. + +--- + +## Step-by-step installation + +### 1. Check your Windows version + +Press `Win+R`, type `winver`, and press Enter. You need **Windows 10 build 19041 or later**, or **Windows 11**. + +### 2. Open PowerShell as Administrator + +This is important — a normal PowerShell window will not work. + +- Click the **Start** button, type **PowerShell** +- Right-click **Windows PowerShell** and select **Run as administrator** +- Click **Yes** when prompted by User Account Control + +Alternatively, right-click the Start button and choose **Terminal (Admin)**. + +### 3. Install WSL + +In the administrator PowerShell window, type: + +```powershell +wsl --install +``` + +This single command does several things: + +- Enables the WSL and Virtual Machine Platform features +- Downloads the latest Linux kernel +- Sets WSL 2 as the default version +- Downloads and installs Ubuntu + +You should see progress output as it downloads and installs. + +### 4. Restart your computer + +When the install finishes, **restart your computer**. This is required — the features enabled in step 3 won't be active until you reboot. + +### 5. Launch Ubuntu + +After restarting, open the **Start** menu and search for **Ubuntu**. Click it to launch. + +The first time you open Ubuntu, it will spend a minute or two decompressing files. This is normal — just wait. + +### 6. Create your Linux username and password + +Ubuntu will prompt you to create a new account: + +``` +Enter new UNIX username: +``` + +Pick a simple lowercase name with no spaces (e.g., `jsmith` or your UDel login). + +Next, it will ask for a password. **Nothing will appear on screen while you type your password.** This is normal Linux behavior — it's not broken, it's just hiding your input for security. Type your password and press Enter. You'll be asked to confirm it. + +### 7. Verify it's working + +You should now see a Linux prompt that looks something like: + +``` +jsmith@DESKTOP-ABC123:~$ +``` + +Try a few commands to confirm everything is working: + +```bash +pwd +ls +whoami +``` + +### 8. Update your packages + +It's good practice to update Ubuntu right after installing: + +```bash +sudo apt update && sudo apt upgrade -y +``` + +You'll be prompted for the password you just created. + +You're all set! + +--- + +## Troubleshooting + +### `wsl --install` just shows help text + +This means WSL was already partially enabled on your machine (perhaps from a previous attempt). Instead, run: + +```powershell +wsl --install -d Ubuntu +``` + +### The install hangs or stalls at 0% + +Try downloading the distribution from the web instead: + +```powershell +wsl --install --web-download -d Ubuntu +``` + +### "The virtual machine could not be started" (error 0x80370102) + +Your computer's hardware virtualization may be disabled. You need to enable it in your BIOS/UEFI settings: + +1. Restart your computer and enter the BIOS (usually by pressing `F2`, `F10`, `Del`, or `Esc` during boot — it varies by manufacturer) +2. Look for a setting called **Intel VT-x**, **Intel Virtualization Technology**, or **AMD-V** (usually under CPU or Advanced settings) +3. Enable it, save, and restart + +### "WslRegisterDistribution failed" (error 0x8007019e) + +The WSL feature itself isn't enabled. Open PowerShell as Administrator and run: + +```powershell +Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux +``` + +Then restart and try again. + +### `wsl` is not recognized as a command + +Make sure you're using a 64-bit PowerShell. Try typing `wsl.exe` instead of `wsl`. + +### I forgot my Linux password + +From PowerShell (not inside Ubuntu), run: + +```powershell +wsl -u root +``` + +Then reset your password: + +```bash +passwd your_username +``` + +--- + +## Launching WSL after installation + +Once installed, you can open your Linux terminal in any of these ways: + +- **Start menu**: Search for **Ubuntu** +- **PowerShell or Command Prompt**: Type `wsl` +- **Windows Terminal** (recommended): Ubuntu appears as an option in the dropdown tab menu. Windows Terminal supports multiple tabs and is a nicer experience overall. + +--- + +## References + +- [Install WSL (Microsoft docs)](https://learn.microsoft.com/en-us/windows/wsl/install) +- [Set up a WSL development environment](https://learn.microsoft.com/en-us/windows/wsl/setup/environment) +- [WSL troubleshooting (Microsoft docs)](https://learn.microsoft.com/en-us/windows/wsl/troubleshooting)