{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "button": false,
    "new_sheet": false,
    "run_control": {
     "read_only": false
    },
    "slideshow": {
     "slide_type": "slide"
    },
    "tags": []
   },
   "source": [
    "# Downloads and Installation\n",
    "\n",
    "This notebook has instructions on how to use the `debuggingbook` code in your own programs."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "In short, there are three ways:\n",
    "\n",
    "1. Simply run the notebooks in your browser, using the \"mybinder\" environment. Choose \"Binder\" in any of the `debuggingbook.org` pages; this will lead you to a preconfigured Jupyter Notebook environment where you can toy around at your leisure.\n",
    "2. Import the code for your own Python programs. Using `pip install debuggingbook`, you can install all code and start using it from your own code. See \"Installing Debuggingbook Code for your own Python projects\", below.\n",
    "3. Download or check out the code and/or the notebooks from the project site. This allows you to edit and run all things locally. However, be sure to also install the required packages; see below for details."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Installing Debuggingbook Code for your own Python projects\n",
    "\n",
    "We provide a `debuggingbook` Python package that you can install using the `pip` package manager:\n",
    "\n",
    "```shell\n",
    "$ pip install debuggingbook\n",
    "```\n",
    "\n",
    "This is set up such that additional required Python packages are also installed.\n",
    "However, also see \"Install Additional Non-Python Packages\" below.\n",
    "\n",
    "Note that after installation via `pip`, you may have to install our updated `showast` module:\n",
    "\n",
    "```shell\n",
    "$ pip install 'showast@git+https://github.com/andreas-zeller/show_ast.git@andreas'\n",
    "```\n",
    "\n",
    "Once `pip` is complete, you can import individual classes, constants, or functions from each notebook using\n",
    "\n",
    "```python\n",
    ">>> from debuggingbook.<notebook> import <identifier>\n",
    "```\n",
    "\n",
    "where `<identifier>` is the name of the class, constant, or function to use, and `<notebook>` is the name of the respective notebook.  (If you read this at debuggingbook.org, then the notebook name is the identifier preceding `\".html\"` in the URL).\n",
    "\n",
    "Here is an example importing `Tracer` from [the chapter on tracing](Tracer.ipynb), whose notebook name is `Tracer`:\n",
    "\n",
    "```python\n",
    ">>> from debuggingbook.Tracer import Tracer\n",
    ">>> with Tracer():\n",
    "    function_to_be_observed()\n",
    "```\n",
    "\n",
    "The \"Synopsis\" section at the beginning of a chapter gives a short survey on useful code features you can use."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    },
    "vscode": {
     "languageId": "plaintext"
    }
   },
   "source": [
    "## Downloading the Notebooks\n",
    "\n",
    "Another way to use the code is to _import the notebooks directly_.  Download the notebooks using this link:\n",
    "\n",
    "[https://www.debuggingbook.org/dist/debuggingbook-notebooks.zip](https://www.debuggingbook.org/dist/debuggingbook-notebooks.zip)\n",
    "\n",
    "Then, add your own notebooks _into the same folder_.  After importing `bookutils.setup`, you can then simply import the code from other notebooks, just as our own notebooks do.\n",
    "\n",
    "Here is again the above example, importing `RandomFuzzer` from [the chapter on fuzzers](Fuzzer.ipynb) – but now from a notebook:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-10-26T18:04:00.485961Z",
     "iopub.status.busy": "2025-10-26T18:04:00.485602Z",
     "iopub.status.idle": "2025-10-26T18:04:00.489387Z",
     "shell.execute_reply": "2025-10-26T18:04:00.488796Z"
    },
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "outputs": [],
   "source": [
    "def function_to_be_observed():\n",
    "    pass"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-10-26T18:04:00.494780Z",
     "iopub.status.busy": "2025-10-26T18:04:00.494598Z",
     "iopub.status.idle": "2025-10-26T18:04:01.422463Z",
     "shell.execute_reply": "2025-10-26T18:04:01.419647Z"
    },
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [],
   "source": [
    "import bookutils.setup"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-10-26T18:04:01.440972Z",
     "iopub.status.busy": "2025-10-26T18:04:01.440635Z",
     "iopub.status.idle": "2025-10-26T18:04:01.487210Z",
     "shell.execute_reply": "2025-10-26T18:04:01.486536Z"
    },
    "slideshow": {
     "slide_type": "skip"
    }
   },
   "outputs": [],
   "source": [
    "from debuggingbook.Tracer import Tracer"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "execution": {
     "iopub.execute_input": "2025-10-26T18:04:01.511646Z",
     "iopub.status.busy": "2025-10-26T18:04:01.504332Z",
     "iopub.status.idle": "2025-10-26T18:04:01.630701Z",
     "shell.execute_reply": "2025-10-26T18:04:01.629282Z"
    },
    "slideshow": {
     "slide_type": "fragment"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Calling function_to_be_observed()\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "2     pass\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "function_to_be_observed() returns None\n"
     ]
    }
   ],
   "source": [
    "with Tracer():\n",
    "    function_to_be_observed()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Downloading the Code\n",
    "\n",
    "If you want to work with code samples, you can download all the Python code here:\n",
    "\n",
    "[https://www.debuggingbook.org/dist/debuggingbook-code.zip](https://www.debuggingbook.org/dist/debuggingbook-code.zip)\n",
    "\n",
    "The code files can also be edited if you wish, but (a) they are very obviously generated from notebooks, (b) therefore not much fun to work with, and (c) if you fix any errors, you'll have to back-propagate them to the notebook before you can make a pull request.\n",
    "\n",
    "If you only want to **use** the Python code, install the code package (see above)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Getting the Code from GitHub\n",
    "\n",
    "You can also check out the latest and greatest from GitHub. After cloning the repository from [the project page](https://github.com/uds-se/debuggingbook/) and installing the additional packages (see below), you can `cd` into `notebooks` and start `jupyter` right away!\n",
    "\n",
    "There also is a `Makefile` provided with literally hundreds of targets; most important are the ones we also use in continuous integration:\n",
    "\n",
    "* `make check-imports` checks whether your code is free of syntax errors\n",
    "* `make check-style` checks whether your code is free of type errors\n",
    "* `make check-code` runs all derived code, testing it\n",
    "* `make check-notebooks` runs all notebooks, testing them\n",
    "\n",
    "If you want to contribute to the project, ensure that the above tests run through.\n",
    "\n",
    "The `Makefile` has many more, often experimental, targets. `make markdown` creates a `.md` variant in `markdown/`, and there's also `make word` and `make epub`, which are set to create Word and EPUB variants (with mixed results). Try `make help` for commonly used targets."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Installing Supplemental Packages\n",
    "\n",
    "We have attempted to limit the dependencies to a minimum (sometimes using ugly hacks).  Generally speaking, if you encounter that a module `X` is not found, just do `pip install X`.  Most notebooks only need modules that are part of the standard Python library.\n",
    "\n",
    "For a full list of dependencies, there are two sources."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "### Step 1: Install Required Python Packages\n",
    "\n",
    "The [`pyproject.toml` file within the project root folder](https://github.com/uds-se/debuggingbook/tree/master/) lists all _Python packages required_.\n",
    "\n",
    "You can do\n",
    "\n",
    "```sh\n",
    "$ pip install .\n",
    "```\n",
    "\n",
    "to install all required packages (but using `pipenv` is preferred; see below)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    },
    "tags": []
   },
   "source": [
    "### Step 2: Install Additional Non-Python Packages\n",
    "\n",
    "The [`apt.txt` file in the `binder/` folder](https://github.com/uds-se/debuggingbook/tree/master/binder) lists all _Linux_ packages required.\n",
    "\n",
    "In most cases, however, it suffices to install the `dot` graph drawing program (part of the `graphviz` package). Here are some instructions:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "#### Installing Graphviz on Linux\n",
    "\n",
    "Use\n",
    "\n",
    "```sh\n",
    "$ sudo apt-get install graphviz libgraphviz-dev\n",
    "```\n",
    "\n",
    "to install it."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "#### Installing Graphviz on macOS\n",
    "\n",
    "On macOS, if you use `conda`, run\n",
    "\n",
    "```sh\n",
    "$ conda install graphviz\n",
    "```\n",
    "\n",
    "If you use HomeBrew, run\n",
    "\n",
    "```sh\n",
    "$ brew install graphviz\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Installing Debuggingbook code in an Isolated Environment\n",
    "\n",
    "If you wish to install the `debuggingbook` code in an environment that is isolated from your system interpreter,\n",
    "we recommend using [Pipenv](https://pipenv.pypa.io/), which can automatically create a so called *virtual environment* hosting all required packages.\n",
    "\n",
    "To accomplish this, please follow these steps:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "### Step 1: Install PyEnv\n",
    "\n",
    "Optionally install `pyenv` following the [official instructions](https://github.com/pyenv/pyenv#installation) if you are on a Unix operating system.\n",
    "If you are on Windows, consider using [pyenv-win](https://github.com/pyenv-win/pyenv-win) instead.\n",
    "This will allow you to seamlessly install any version of Python."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "### Step 2: Install PipEnv\n",
    "\n",
    "Install Pipenv following the official [installation instructions](https://pypi.org/project/pipenv/).\n",
    "If you have `pyenv` installed, Pipenv can automatically download and install the appropriate version of the Python distribution.\n",
    "Otherwise, Pipenv will use your system interpreter, which may or may not be the right version."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "### Step 3: Install Python Packages\n",
    "\n",
    "Run\n",
    "\n",
    "```sh\n",
    "$ pipenv install .\n",
    "```\n",
    "\n",
    "in the `debuggingbook` root directory."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "### Step 4: Install Additional Non-Python Packages\n",
    "\n",
    "See above for instructions on how to install additional non-python packages."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": [
    "### Step 5: Enter the Environment\n",
    "\n",
    "Enter the environment with \n",
    "\n",
    "```sh\n",
    "$ pipenv shell\n",
    "```\n",
    "\n",
    "where you can now execute\n",
    "\n",
    "```sh\n",
    "$ make -k check-code\n",
    "```\n",
    "\n",
    "to run the tests."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Using Docker\n",
    "\n",
    "As another alternative, you can also **use our Docker images** (experimental). [Install Docker](https://docs.docker.com/get-docker/) and then run\n",
    "```\n",
    "    $ docker pull zeller24/debuggingbook\n",
    "    $ docker run -it --rm -p 8888:8888 zeller24/debuggingbook\n",
    "```\n",
    "and then in your Web browser, open the URL (`http://127.0.0.1/...` or `http://localhost/...`) given in the console output.\n",
    "This should kick off the same Jupyter environment as in mybinder.org.\n",
    "\n",
    "If you want to create your own Docker images, use our [Dockerfile](https://github.com/uds-se/debuggingbook/blob/master/binder/Dockerfile) as a starting point."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "subslide"
    }
   },
   "source": []
  }
 ],
 "metadata": {
  "ipub": {
   "bibliography": "fuzzingbook.bib",
   "toc": true
  },
  "kernelspec": {
   "display_name": "python3.12",
   "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.13.4"
  },
  "toc": {
   "base_numbering": 1,
   "nav_menu": {},
   "number_sections": true,
   "sideBar": true,
   "skip_h1_title": true,
   "title_cell": "",
   "title_sidebar": "Contents",
   "toc_cell": false,
   "toc_position": {},
   "toc_section_display": true,
   "toc_window_display": true
  },
  "toc-autonumbering": false
 },
 "nbformat": 4,
 "nbformat_minor": 4
}