174 lines
8.1 KiB
Markdown
174 lines
8.1 KiB
Markdown
# MACOS_INSTALL
|
||
|
||
This is an installation guide for macOS, covering all the steps needed to begin developing code for the Urban Simulation
|
||
Platform 'Hub'. At the end of this process you will have installed and configured all the necessary applications,
|
||
set up your own project on CERC's Gitlab and created your first python file.
|
||
|
||
## Prepare your environment
|
||
|
||
To develop any new code for the Urban Simulation Platform you must have the right software applications installed and configured.
|
||
The Platform is written in python and so the applications you need are:
|
||
* Python Interpreter
|
||
* Python Editor
|
||
* @Chris: Miniconda??
|
||
|
||
You also need to register a user account with the CERC's code repository on Gitlab and have the necessary permissions for
|
||
creating new code. For that purpose, please, contact Guillermo (guillermo.gutierrezmorote@concordia.ca) or
|
||
Koa (kekoa.wells@concordia.ca) as soon as possible.
|
||
|
||
### Get a Python interpreter
|
||
|
||
1. Download the latest version of python for macOS: [Python environment](https://www.python.org/downloads/)
|
||
2. Open the downloaded .pkg file and follow the instructions to install.
|
||
|
||
### Get a Python editor
|
||
|
||
1. You will need a python editor in order to import the existing Hub source code and to write your own python code.
|
||
Whilst this is a personal choice we would like to recommend [PyCharm Community Edition](https://www.jetbrains.com/pycharm/download/#section=mac),
|
||
an excellent open-source python editor.
|
||
2. Open the downloaded .dmg file and then drag the PyCharm CE app into your Applications folder.
|
||
|
||
|
||
|
||
## Get the CERC Hub source code
|
||
|
||
1. Run PyCharmCE
|
||
2. Click on the **Get from VCS** button in the top right of the window.
|
||
|
||
|
||
|
||
3. Select **Git** as the **Version control**. For the URL use the link to the Hub repository, as seen below.
|
||
|
||
|
||
|
||
(You can also copy this URL by going to the Hub repository in [Gitlab](https://rs-loy-gitlab.concordia.ca/Guille/hub.git)
|
||
and clicking on the Copy URL button next to **Clone with HTTPS**)
|
||
|
||
|
||
|
||
The Directory to store the Hub source code locally is automatically created for you. Edit this if you prefer it to be stored somewhere else.
|
||
|
||
Note: If you see a message saying Git is not installed, click on the **Download and install** and follow instructions.
|
||
|
||
4. Click the **Clone** button to download CERC Hub source code.
|
||
|
||
(If the macOS security asks if you trust executing this source code, you can click **Trust Project**.)
|
||
|
||
|
||
|
||
You will then see the project directories and files below, with the hub readme document displayed.
|
||
You have successfully cloned a copy of the CERC hub onto your computer.
|
||
|
||
|
||
|
||
|
||
## Create Your Own Branch of the Hub
|
||
|
||
You now need to create a new **Branch** of the Hub source code. This is like your own special version of the Hub,
|
||
where you can safely integrate your model, without affecting the smooth running of the Main Branch Hub and the Platform.
|
||
|
||
To create your working branch you need rights to edit the project. Please, contact Guillermo (guillermo.gutierrezmorote@concordia.ca)
|
||
or Koa (kekoa.wells@concordia.ca) to get those rights and then follow the instructions.
|
||
|
||
1. Create your working branch by right-clicking on the project folder (hub) and then selecting **Git->New Branch...**
|
||
|
||
|
||
|
||
2. Give a name to your branch that has some sense of what will be done with it, _updating_documentation_,
|
||
_lca_classes_,... And, click on the **Create** button.
|
||
|
||
|
||
|
||
3. Click on the **Git** button in the bottom-left corner to pop-up the window showing the Git information.
|
||
See your new branch has been created under _Local_.
|
||
|
||
|
||
|
||
4. Now we need to let the CERC Gitlab repository know about this new branch. You do this by right-clicking on
|
||
your branch and selecting **Push...** from the drop-down menu.
|
||
|
||
|
||
|
||
5. Then click on the **Push** button at the bottom-right of the **Push Commits** window.
|
||
|
||
|
||
|
||
Note - at this point you may need to login to Gitlab using you Concordia credentials.
|
||
|
||
|
||
|
||
Check that your branch now appears in the _Remote_ branch hierarchy, in the bottom-left corner. If it does not appear,
|
||
contact Guille (guillermo.gutierrezmorote@concordia.ca) or Koa (kekoa.wells@concordia.ca), to find the reason of the error.
|
||
|
||
|
||
|
||
## Configure Pycharm
|
||
|
||
When integrating your model with the Platform, it is important that you follow [CERC’s coding style guidelines](PYGUIDE.md).
|
||
One of the rules is that we use two spaces as a tab instead of the standard [pep8](https://www.python.org/dev/peps/pep-0008/)
|
||
four spaces indentation. This option can be configured in PyCharm at the settings screen.
|
||
|
||
To access the settings screen, click on the gear icon in the top right corner, and select **Preferences** from
|
||
the drop-down menu. The Preferences window will appear. From the panel on the left, select
|
||
**Editor->Code Style->Python** and you will see where tab size can be changed. Change it to 2.
|
||
See the picture below.
|
||
|
||
|
||
|
||
## Set up a new project on Gitlab
|
||
|
||
1. Open a browser and to the [CERC Git](https://rs-loy-gitlab.concordia.ca/). Click on the blue **New project** button.
|
||
|
||
|
||
|
||
2. Choose the **Create blank project** option from the three options seen below.
|
||
|
||
|
||
|
||
3. Type in a name (remember to follow the CERC naming conventions described in the ).
|
||
Check the option **Initialize repository with a README**, and ideally, check the **Visibility Level** to be **Public**.
|
||
Then click on the **Create project** button.
|
||
|
||
|
||
|
||
You should then see a confirmation screen with all the information about your new project.
|
||
|
||
|
||
|
||
## Get your project into Pycharm
|
||
|
||
1. Now you can make a clone of this project, within PyCharm. First, copy the URL by clicking on the blue **Clone** button
|
||
and then click on the **Copy URL** button next to the **Clone with HTTPS** link.
|
||
|
||
|
||
|
||
2. Switch back to PyCharm and close the Hub project by choosing **File->Close Project**. You will then see the
|
||
**Welcome To PyCharm** window again.
|
||
|
||
3. Clone a copy of your Project into PyCharm, following the steps 2-6 of the _GET THE CERC HUB SOURCE CODE_
|
||
section above, but using the URL link that you just copied for your gitlab project.
|
||
|
||
4. Select **Pycharm->Preferences** to open the **Preferences** window. From the panel on the left click on
|
||
**Project:<project name> -> Project Structure**.
|
||
|
||
|
||
|
||
5. Add the Hub project to your own, by clicking on Add Content Root: (Pilar, this is where it all went wrong for me :-) )
|
||
|
||
## Create your first Python file
|
||
|
||
Add your first file to your project and click on install requirements to automatically download all the dependencies
|
||
(in blue at top-right corner).
|
||
|
||
When all the dependencies are satisfied, you are all set to start importing your first city model.
|
||
Add the following code to your main.py
|
||
from imports.geometry_factory import GeometryFactory
|
||
|
||
city = GeometryFactory('citygml', 'myfile.gml').city
|
||
|
||
Always remember to push your own project changes as the last thing you do before ending your working day!
|
||
First, commit your changes by clicking on the green check in the top-right corner of Pycharm. Add a comment
|
||
that explains briefly your changes. Then, pull by clicking on the blue arrow to be sure that there are no
|
||
conflicts between your version (local) and the remote one (gitlab). Once the conflicts are solved and the merge in
|
||
local is done, push the changes by clicking on the green arrow.
|