Skip to content

docs: update README with comprehensive install steps #74

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
liammulh wants to merge 2 commits into from
Closed

docs: update README with comprehensive install steps #74

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1972d03
docs: add list of steps for installing deps
liammulh May 3, 2023
220b45e
docs: add headers and long-form deps install steps
liammulh May 3, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
300 changes: 197 additions & 103 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,12 +14,92 @@ of Integer Sequences](https://oeis.org).

## Set up backscope

All of these instructions assume you have already cloned the backscope
repository from `https://github.com/numberscope/backscope` and are in
the top-level directory of your clone (the directory that contains this
`README.md` file).
These instructions are for Ubuntu, a Linux distribution. If you are trying to
run backscope on a different Linux distribution or on a different operating
system, you will need to modify the commands.

### Install Python
### Install Git

First, check if Git is installed:

```
which git
```

If you don't see any output:

```
sudo apt install git
```

### Clone backscope

If you are using HTTP:

```
git clone https://github.com/numberscope/backscope.git
```

If you are using SSH:

```
git clone git@github.com:numberscope/backscope.git
```

### Install pari-gp, required for cypari2

This is the actual PARI/GP package.

```
sudo apt install pari-gp
```

To verify that it was installed correctly, try to check the version of
`gp`:

```
gp --version
```

If you see some output about the version number, then you have likely
installed the package correctly.

### Install libpari-dev, which contains a file needed to install cypari2

This is the PARI library development package. It contains a `pari.desc`
file which is crucial for cypari2.

```
sudo apt install libpari-dev
```

Ensure the file exists:

```
ls -al /usr/share/pari
```

You should see a `pari.desc` file in that directory.

### Install libgmp-dev, required for cypari2

This is the package for the GNU multi-precision arithmetic library
developer tools.

```
sudo apt install libgmp-dev
```

### Install essential build tools, required for cypari2.

Essential build tools are used when we compile cypari2. The tools that
are installed are gcc, g++, gdb, etc. — the generic C/C++ toolkit.

```
sudo apt install build-essential
```

### Install Python 3

You need a version of Python at least equal to 3.5. (If you don't have
Python, install the latest stable version.) By installing a version of
Expand Down Expand Up @@ -56,113 +136,127 @@ command:

You should see help for the `venv` module.

Note that since you will (likely) be compiling the cypari Python package, you
will (likely) need a _full_ Python3 installation, including the
"development header files." To check if these files are installed, you can
execute the following (very long) command:
Note that since you will (likely) be compiling the cypari2 Python
package, you will (likely) need a _full_ Python 3 installation, including
the "development header files." To check if these files are installed,
you can execute the following (very long) command:

```shell
[PYEXEC] -c "from distutils import sysconfig as s; from os.path import isfile; print(isfile(s.get_config_vars()['INCLUDEPY']+'/Python.h') and 'OK')"
```

If this command displays anything other than `OK` (such as `False` or an error
message) then your distribution is lacking these header files. You likely
will need to install the "Python development" package for your operating
system (the details of doing so are beyond the scope of these instructions).
message) then your distribution is lacking these header files.
Copy link
Member

@katestange katestange May 3, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just to make sure I understand; this phrasing has been removed because it went from "beyond the scope" to being included below, right?


### Other prerequisites
### Install python3-dev, required for cypari2

For a successfull installation of backscope, you will (likely) need a
_full_ Pari/GP installation already present on your computer, including the
documentation files. To test if the installation is present, try
executing:
This is the Python development package. We need it to compile cypari2.

```shell
gphelp -detex factorial
```

You should see a description of Pari/GP's factorial function. If not, you
may need to install Pari/GP and/or additional packages related to it,
depending on your operating system.

### Create a virtual environment and install dependencies

1. Create your virtual environment and activate it:

```bash
[PYEXEC] -m venv .venv # create a new virtual env called .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install --force cypari2
```

All remaining instructions assume that you have this virtual environment
activated. So if, for example, you stop and log out and come back later
and pick up the process, make sure to re-activate the virtual environment
by re-issuing the `source .venv/bin/activate` command in the top-level
directory of your backscope clone. Note also that once the virtual
environment is activated, the `python` command will invoke the proper
version of `python`, so you no longer need to worry about whether you
need to call `python3` or `python`. Hence, the remaining instructions
all just use `python`.

2. Install and configure PostgreSQL and create an empty database:

Specific instructions for PostgreSQL installation are unfortunately beyond
the current scope of this README, as they depend greatly on the particulars
of your operating system. You need to end up with a running
Postgres server on your machine that will accept localhost connections.

Specifically, once you are set up, it should be possible to use the command
`psql` to connect to a Postgres shell where you can create a database for
backscope. You should be able to use the `-U` flag to specify a user who
has the correct permissions to access the Postgres shell and create a database.

```bash
psql -U <username for psql>
<username>=# CREATE DATABASE <database name>;
CREATE DATABASE
<username>=# \q
```

3. Set up your environment and initialize the database:

This project uses python-dotenv. In order to detect your database
username / password, you must create a file called `.env` in the root
of your directory containing:
```
export APP_ENVIRONMENT="development"
export DATABASE_URI="postgresql://localhost/<database name>"
export SECRET_KEY="Uneccessary for development"
export POSTGRES_USER="<username for psql>"
export POSTGRES_DB="<database name>"
export POSTGRES_PASSWORD="<password for psql>"
```
You can see other configuration options inside
[the config file](./flaskr/config.py).

4. Configure the database:

```bash
python manage.py db init # initializes tables inside database
```

The previous command will issue a message about editing
`alembic.ini`, which is safe to ignore. The default works fine.

```bash
python manage.py db migrate # migrate data models
python manage.py db upgrade # upgrade changes to database
psql -U <username for psql> -d <database name>
db=# \d
Schema | Name | Type | Owner
--------+-----------------+----------+--------------------
public | alembic_version | table | <username for psql>
public | sequences | table | <username for psql>
public | user | table | <username for psql>
public | user_id_seq | sequence | <username for psql>
db=# \q
```
```
sudo apt install python3-dev
```

### Install the package that makes it so you can create a virtual environment

```
sudo apt install python3.xy-venv
```

`xy` is a version number, e.g. `python3.10-venv`.

### Create the virtual environment.

```
python3 -m venv .venv
```

### Activate the virtual environment

If you are using Bash:

```
source .venv/bin/activate
```

(If you are using a shell other than Bash, there might be an activate
script in the `.venv/bin/` directory for your shell.)

All remaining instructions assume that you have this virtual environment
activated. So if, for example, you stop and log out and come back later
and pick up the process, make sure to re-activate the virtual environment
by re-issuing the `source .venv/bin/activate` command in the top-level
directory of your backscope clone. Note also that once the virtual
environment is activated, the `python` command will invoke the proper
version of `python`, so you no longer need to worry about whether you
need to call `python3` or `python`. Hence, the remaining instructions
all just use `python`.

### Install dependencies

This installs all of backscope's dependencies listed in
`requirements.txt`.

```
pip install -r requirements.txt
```

### Install and configure PostgreSQL and create an empty database

Specific instructions for PostgreSQL installation are unfortunately beyond
the current scope of this README, as they depend greatly on the particulars
of your operating system. You need to end up with a running
Postgres server on your machine that will accept localhost connections.

Specifically, once you are set up, it should be possible to use the command
`psql` to connect to a Postgres shell where you can create a database for
backscope. You should be able to use the `-U` flag to specify a user who
has the correct permissions to access the Postgres shell and create a database.

```
psql -U <username for psql>
<username>=# CREATE DATABASE <database name>;
CREATE DATABASE
<username>=# \q
```

### Set up your environment and initialize the database

This project uses python-dotenv. In order to detect your database
username / password, you must create a file called `.env` in the root
of your directory containing:
```
export APP_ENVIRONMENT="development"
export DATABASE_URI="postgresql://localhost/<database name>"
export SECRET_KEY="Uneccessary for development"
export POSTGRES_USER="<username for psql>"
export POSTGRES_DB="<database name>"
export POSTGRES_PASSWORD="<password for psql>"
```
You can see other configuration options inside
[the config file](./flaskr/config.py).

### Configure the database

```bash
python manage.py db init # initializes tables inside database
```

The previous command will issue a message about editing
`alembic.ini`, which is safe to ignore. The default works fine.

```bash
python manage.py db migrate # migrate data models
python manage.py db upgrade # upgrade changes to database
psql -U <username for psql> -d <database name>
db=# \d
Schema | Name | Type | Owner
--------+-----------------+----------+--------------------
public | alembic_version | table | <username for psql>
public | sequences | table | <username for psql>
public | user | table | <username for psql>
public | user_id_seq | sequence | <username for psql>
db=# \q
```
Copy link
Member

@katestange katestange May 3, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is the above commands or output or both?


## Run backscope

Expand Down