mirror of
https://gitlab.ewi.tudelft.nl/ee2l1/2025-2026/A.K.03.git
synced 2025-12-12 16:00:56 +01:00
362 lines
12 KiB
Plaintext
362 lines
12 KiB
Plaintext
{
|
|
"cells": [
|
|
{
|
|
"cell_type": "markdown",
|
|
"metadata": {},
|
|
"source": [
|
|
""
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"metadata": {},
|
|
"source": [
|
|
"# Installation Guide for macOS\n",
|
|
"\n",
|
|
"This guide will walk you through installing Python, Visual Studio Code, and all the necessary dependencies for your project.\n",
|
|
"\n",
|
|
"At the bottom of this guide, you will find a section on common problems and solutions. If you encounter any issues during the installation process, please refer to that section for troubleshooting tips.\n",
|
|
"\n",
|
|
"## Installing Homebrew\n",
|
|
"\n",
|
|
"Homebrew is a package manager for macOS that simplifies the installation of software. We will use Homebrew to install Python and other dependencies.\n",
|
|
"\n",
|
|
"1. **Install Homebrew**:\n",
|
|
"\n",
|
|
" - Searche **\"Terminal\"** in Spotlight.\n",
|
|
" - Run the following command:\n",
|
|
"\n",
|
|
" ```bash\n",
|
|
" /bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)\"\n",
|
|
" ```\n",
|
|
"\n",
|
|
" - You will be prompted for your password. Enter it to proceed with the installation.\n",
|
|
" - If prompted with follow-up commands, run them as instructed.\n",
|
|
"\n",
|
|
"2. **Verify Homebrew Installation**:\n",
|
|
"\n",
|
|
" - After installation, verify that Homebrew is installed correctly:\n",
|
|
"\n",
|
|
" ```bash\n",
|
|
" brew --version\n",
|
|
" ```\n",
|
|
"\n",
|
|
" - This should display the installed Homebrew version.\n",
|
|
"\n",
|
|
"## Installing Python\n",
|
|
"\n",
|
|
"With Homebrew installed, we can now install Python **3.12** using Homebrew.\n",
|
|
"\n",
|
|
"1. **Install Python 3.12**:\n",
|
|
"\n",
|
|
" - In the Terminal, run:\n",
|
|
"\n",
|
|
" ```bash\n",
|
|
" brew install python@3.12\n",
|
|
" ```\n",
|
|
"\n",
|
|
" - This will install Python 3.12 and make it available as `python3`.\n",
|
|
"\n",
|
|
"2. **Verify the Installation**:\n",
|
|
"\n",
|
|
" ```bash\n",
|
|
" python3 --version\n",
|
|
" ```\n",
|
|
"\n",
|
|
" - This should display the installed Python version, e.g., `Python 3.12.0`.\n",
|
|
" - **Note**: On macOS, `python` may point to Python 2.x. Always use `python3` and `pip3` to invoke Python 3.\n",
|
|
"\n",
|
|
"3. **Update PATH (if necessary)**:\n",
|
|
"\n",
|
|
" - If you encounter issues with the `python3` command, you may need to update your PATH.\n",
|
|
" - Follow Homebrew's post-installation messages, which may prompt you to add the following to your shell profile (`~/.zprofile` or `~/.bash_profile`):\n",
|
|
"\n",
|
|
" ```bash\n",
|
|
" echo 'export PATH=\"/usr/local/opt/python@3.12/bin:$PATH\"' >> ~/.zprofile\n",
|
|
" ```\n",
|
|
"\n",
|
|
" - Reload your shell configuration:\n",
|
|
"\n",
|
|
" ```bash\n",
|
|
" source ~/.zprofile\n",
|
|
" ```\n",
|
|
"\n",
|
|
"## Installing Visual Studio Code\n",
|
|
"\n",
|
|
"It is recommended that you use Visual Studio Code (VSCode) as your Integrated Development Environment (IDE). VSCode is a free, open-source code editor developed by Microsoft with a wide range of extensions and excellent Python support.\n",
|
|
"\n",
|
|
"1. **Download VSCode**:\n",
|
|
"\n",
|
|
" - Open your web browser and navigate to the official VSCode website at [https://code.visualstudio.com/](https://code.visualstudio.com/).\n",
|
|
"\n",
|
|
" - Click on the \"**Download**\" button to download the installer suitable for your operating system.\n",
|
|
"\n",
|
|
"2. **Install VSCode**:\n",
|
|
"\n",
|
|
" - Once the installer is downloaded, run it to start the installation process.\n",
|
|
"\n",
|
|
"3. **Launch VSCode**:\n",
|
|
"\n",
|
|
" - After the installation is complete, open Visual Studio Code.\n",
|
|
"\n",
|
|
"### Installing Python Extension for VSCode\n",
|
|
"\n",
|
|
"1. **Open VSCode**.\n",
|
|
"\n",
|
|
"2. **Access the Extensions View**:\n",
|
|
"\n",
|
|
" - Click on the Extensions icon in the Activity Bar on the side of the window.\n",
|
|
" - Or press **Command+Shift+X**.\n",
|
|
"\n",
|
|
"3. **Install the Python Extension**:\n",
|
|
"\n",
|
|
" - In the Extensions search bar, type **\"Python\"**.\n",
|
|
" - Look for the official Python extension by Microsoft and click **\"Install\"**.\n",
|
|
" - This extension provides enhanced support for Python development.\n",
|
|
"\n",
|
|
"4. **Install the Jupyter Extension**:\n",
|
|
"\n",
|
|
" - In the same way, search for **\"Jupyter\"**.\n",
|
|
" - Install the official Jupyter extension by Microsoft.\n",
|
|
"\n",
|
|
"5. **Reload VSCode**:\n",
|
|
"\n",
|
|
" - After installation, you may need to reload VSCode to activate the extensions fully.\n",
|
|
" - If prompted, click on the **\"Reload\"** button.\n",
|
|
"\n",
|
|
"6. **Select the Python Interpreter**:\n",
|
|
"\n",
|
|
" - Open the Command Palette by pressing **Command+Shift+P**.\n",
|
|
" - Type **\"Python: Select Interpreter\"** and select the Python 3.12 interpreter from the list.\n",
|
|
" - If you don't see it, click on **\"Enter interpreter path...\"** and navigate to `/usr/local/bin/python3`.\n",
|
|
"\n",
|
|
"## Cloning the Git Repository\n",
|
|
"\n",
|
|
"If you already have a way to work with Git repositories, you can skip to step 3. If you don't, follow these steps to clone the repository to your computer using VSCode's built-in Git support.\n",
|
|
"\n",
|
|
"1. **Open the Source Control View in VSCode**:\n",
|
|
"\n",
|
|
" - Click on the **Source Control** icon in the Activity Bar.\n",
|
|
"\n",
|
|
" - Or press **Control+Shift+G**.\n",
|
|
"\n",
|
|
"2. **Install Git (if not already installed)**:\n",
|
|
"\n",
|
|
" - If you don't have Git installed, VSCode will display a message and a **\"Download Git\"** button.\n",
|
|
"\n",
|
|
" - Click the button or in the Terminal, run:\n",
|
|
"\n",
|
|
" ```bash\n",
|
|
" brew install git\n",
|
|
" ```\n",
|
|
"\n",
|
|
"3. **Configure Git (First-Time Setup)**:\n",
|
|
"\n",
|
|
" - Set your Git user name and email:\n",
|
|
"\n",
|
|
" ```bash\n",
|
|
" git config --global user.name \"Your Name\"\n",
|
|
" git config --global user.email \"you@example.com\"\n",
|
|
" ```\n",
|
|
"\n",
|
|
"4. **Clone the Repository**:\n",
|
|
"\n",
|
|
" - Go to your assigned GitLab repository from the [EWI GitLab](https://gitlab.ewi.tudelft.nl/).\n",
|
|
" - Click the blue **\"Clone\"** or **\"Code\"** button and copy the HTTPS URL.\n",
|
|
"\n",
|
|
"5. **Clone Using VSCode**:\n",
|
|
"\n",
|
|
" - In VSCode, go to the **Source Control** view by clicking on the Source Control icon in the Activity Bar or by pressing **Command+Shift+G**.\n",
|
|
" - Click the **\"Clone Repository\"** button.\n",
|
|
" - Paste the URL you just copied and press **Enter**.\n",
|
|
" - Choose a folder to download the project to; make it something memorable.\n",
|
|
" - When prompted, open the newly cloned repository.\n",
|
|
" - If asked to trust the authors, please do so.\n",
|
|
"\n",
|
|
"## Installing Required Packages\n",
|
|
"\n",
|
|
"1. **Install PortAudio**:\n",
|
|
"\n",
|
|
" - In the Terminal, run:\n",
|
|
"\n",
|
|
" ```bash\n",
|
|
" brew install portaudio\n",
|
|
" ```\n",
|
|
"\n",
|
|
" - This installs PortAudio, a prerequisite for Sounddevice, which is used for audio input/output.\n",
|
|
"\n",
|
|
"2. **Install the Required Python Packages**:\n",
|
|
"\n",
|
|
" - Open a Terminal in your project directory (the cloned repository).\n",
|
|
" - Run the following command:\n",
|
|
"\n",
|
|
" ```bash\n",
|
|
" pip3 install -r requirements.txt\n",
|
|
" ```\n",
|
|
"\n",
|
|
" - **Note**: Always use `pip3` and `python3` on macOS to ensure you're using the correct version.\n",
|
|
"\n",
|
|
"---\n",
|
|
"\n",
|
|
"## Common Problems and Solutions\n",
|
|
"\n",
|
|
"### Problem 1: `'python3' command not found`\n",
|
|
"\n",
|
|
"**Solution**:\n",
|
|
"\n",
|
|
"- **Cause**: The `python3` command is not in your PATH.\n",
|
|
"- **Fix**:\n",
|
|
" - Ensure that Python 3.12 is installed via Homebrew.\n",
|
|
" - Update your PATH environment variable by adding the following to your shell profile (`~/.zprofile`, `~/.bash_profile`, or `~/.bashrc`):\n",
|
|
"\n",
|
|
" ```bash\n",
|
|
" echo 'export PATH=\"/usr/local/opt/python@3.12/bin:$PATH\"' >> ~/.zprofile\n",
|
|
" ```\n",
|
|
"\n",
|
|
" - Reload your shell configuration:\n",
|
|
"\n",
|
|
" ```bash\n",
|
|
" source ~/.zprofile\n",
|
|
" ```\n",
|
|
"\n",
|
|
"### Problem 2: `'pip3' command not found`\n",
|
|
"\n",
|
|
"**Solution**:\n",
|
|
"\n",
|
|
"- **Cause**: `pip3` may not be linked correctly.\n",
|
|
"- **Fix**:\n",
|
|
" - Use `python3 -m pip` instead of `pip3`:\n",
|
|
"\n",
|
|
" ```bash\n",
|
|
" python3 -m pip install -r requirements.txt\n",
|
|
" ```\n",
|
|
"\n",
|
|
"- **Ensure `pip` is up to date**:\n",
|
|
"\n",
|
|
" ```bash\n",
|
|
" python3 -m pip install --upgrade pip\n",
|
|
" ```\n",
|
|
"\n",
|
|
"### Problem 3: Homebrew Installation Issues\n",
|
|
"\n",
|
|
"**Solution**:\n",
|
|
"\n",
|
|
"- **Cause**: Homebrew may not install correctly due to existing installations or permissions.\n",
|
|
"- **Fix**:\n",
|
|
" - Uninstall any existing Homebrew installations:\n",
|
|
"\n",
|
|
" ```bash\n",
|
|
" /bin/bash -c \"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/uninstall.sh)\"\n",
|
|
" ```\n",
|
|
"\n",
|
|
" - Reinstall Homebrew.\n",
|
|
"\n",
|
|
"### Problem 4: Permission Denied Errors When Installing Packages\n",
|
|
"\n",
|
|
"**Solution**:\n",
|
|
"\n",
|
|
"- **Cause**: Lack of permissions to write to certain directories.\n",
|
|
"- **Fix**:\n",
|
|
" - Install packages with the `--user` flag:\n",
|
|
"\n",
|
|
" ```bash\n",
|
|
" pip3 install --user -r requirements.txt\n",
|
|
" ```\n",
|
|
"\n",
|
|
" - Alternatively, use a virtual environment:\n",
|
|
"\n",
|
|
" ```bash\n",
|
|
" pip3 install virtualenv\n",
|
|
" python3 -m venv venv\n",
|
|
" source venv/bin/activate\n",
|
|
" pip install -r requirements.txt\n",
|
|
" ```\n",
|
|
"\n",
|
|
"\n",
|
|
"### Problem 5: Git Command Not Found\n",
|
|
"\n",
|
|
"**Solution**:\n",
|
|
"\n",
|
|
"- **Cause**: Git is not installed or not in your PATH.\n",
|
|
"- **Fix**:\n",
|
|
" - Install Git using Homebrew:\n",
|
|
"\n",
|
|
" ```bash\n",
|
|
" brew install git\n",
|
|
" ```\n",
|
|
"\n",
|
|
" - Verify the installation:\n",
|
|
"\n",
|
|
" ```bash\n",
|
|
" git --version\n",
|
|
" ```\n",
|
|
"\n",
|
|
" - If Git is still not found, update your PATH:\n",
|
|
"\n",
|
|
" ```bash\n",
|
|
" echo 'export PATH=\"/usr/local/opt/git/bin:$PATH\"' >> ~/.zprofile\n",
|
|
" source ~/.zprofile\n",
|
|
" ```\n",
|
|
"\n",
|
|
"### Problem 6: Authentication Issues When Cloning the Repository\n",
|
|
"\n",
|
|
"**Solution**:\n",
|
|
"\n",
|
|
"- **Cause**: Incorrect credentials or two-factor authentication.\n",
|
|
"- **Fix**:\n",
|
|
" - Ensure you're using the correct username and password.\n",
|
|
" - If using two-factor authentication, generate a Personal Access Token on GitLab and use it as your password.\n",
|
|
" - Consider setting up SSH keys for authentication.\n",
|
|
"\n",
|
|
"### Problem 7: Permission Denied When Running Scripts\n",
|
|
"\n",
|
|
"**Solution**:\n",
|
|
"\n",
|
|
"- **Cause**: Script files may not have execute permissions.\n",
|
|
"- **Fix**:\n",
|
|
" - Modify the file permissions:\n",
|
|
"\n",
|
|
" ```bash\n",
|
|
" chmod +x script.py\n",
|
|
" ```\n",
|
|
"\n",
|
|
" - Run the script using `python3`:\n",
|
|
"\n",
|
|
" ```bash\n",
|
|
" python3 script.py\n",
|
|
" ```\n",
|
|
"\n",
|
|
"---\n",
|
|
"\n",
|
|
"**Note**: If you encounter issues not covered in this guide, please reach out to a TA for assistance. Providing detailed error messages and the steps you've taken can help diagnose problems more quickly."
|
|
]
|
|
},
|
|
{
|
|
"cell_type": "markdown",
|
|
"metadata": {},
|
|
"source": []
|
|
}
|
|
],
|
|
"metadata": {
|
|
"kernelspec": {
|
|
"display_name": "OpenEdVenv",
|
|
"language": "python",
|
|
"name": "python3"
|
|
},
|
|
"language_info": {
|
|
"codemirror_mode": {
|
|
"name": "ipython",
|
|
"version": 3
|
|
},
|
|
"file_extension": ".py",
|
|
"mimetype": "text/x-python",
|
|
"name": "python",
|
|
"nbconvert_exporter": "python",
|
|
"pygments_lexer": "ipython3",
|
|
"version": "3.12.6"
|
|
}
|
|
},
|
|
"nbformat": 4,
|
|
"nbformat_minor": 2
|
|
}
|