s_ranjbar/summer_course_2024
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
915170e60f
summer_course_2024/hub/MACOS_INSTALL.md
guille 9700e5ce21 packaging version
2023-01-24 10:51:50 -05:00

8.1 KiB
Raw Blame History

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
  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, an excellent open-source python editor.
  2. Open the downloaded .dmg file and then drag the PyCharm CE app into your Applications folder.

pycharm ce

Get the CERC Hub source code

  1. Run PyCharmCE
  2. Click on the Get from VCS button in the top right of the window.

get_vc_1

  1. Select Git as the Version control. For the URL use the link to the Hub repository, as seen below.

get_vc_2

(You can also copy this URL by going to the Hub repository in Gitlab and clicking on the Copy URL button next to Clone with HTTPS)

git_lab

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.

  1. 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.)

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.

hub_readme

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...

new_branch

  1. 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.

name_branch

  1. 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.

branch_in_local

  1. 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.

push_branch_1

  1. Then click on the Push button at the bottom-right of the Push Commits window.

push_branch_2

Note - at this point you may need to login to Gitlab using you Concordia credentials.

gitlab_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.

branch_pushed

Configure Pycharm

When integrating your model with the Platform, it is important that you follow CERC’s coding style guidelines. One of the rules is that we use two spaces as a tab instead of the standard pep8 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.

configure_pycharm

Set up a new project on Gitlab

  1. Open a browser and to the CERC Git. Click on the blue New project button.

git_new_project

  1. Choose the Create blank project option from the three options seen below.

blank_project

  1. Type in a name (remember to follow the CERC naming conventions described in the Coding Style). Check the option Initialize repository with a README, and ideally, check the Visibility Level to be Public. Then click on the Create project button.

project_created

You should then see a confirmation screen with all the information about your new project.

confirmation_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.

copy_https

  1. Switch back to PyCharm and close the Hub project by choosing File->Close Project. You will then see the Welcome To PyCharm window again.

  2. 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.

  3. Select Pycharm->Preferences to open the Preferences window. From the panel on the left click on Project: -> Project Structure.

new_project_in_pychaem

  1. 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', path='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.