Ctrl+K

Development environment

Development environment#

If you develop for DF, you need to set up your development environment. This guide will help you to do that. Wether you are developing for the c++ or python part of the project, you will find the necessary information here.

Prepare your environment#

Before to start, especially if you used diffCheck as an end-user before you will need to:

  1. Make sure to have camke installed on your machine. You can download it here.

  2. Make sure to have git installed on your machine. You can download it here.

  3. We recommend to use Visual Studio Code as an IDE. You can download it here together with script-sync extension for Rhino/Grasshopper. You can download it from the Rhino’s PackageManager. It is particularly useful if you want to develop GHComponents in python.

  4. if you used diffCheck before as an end-user clean all the diffCheck folders in the following directory (the last name will change), beware that Rhino should be closed before this step:

    C:\Users\<user-name>\.rhinocode\py39-rh8\site-envs\default-wMh5LZL3

    Important

    if you drop an official released diffCheck component from yak, this one will have the #r : diffCheck==<version_number> notation at the top of the script. Get rid of all these release components before to start and be sur to erase again the previous folders (they recreated each time #r : diffCheck is called).

  5. Clone the repository on your machine. Open a terminal and run the following command:

    git clone https://github.com/diffCheckOrg/diffCheck

  6. Checkout the repo:

    cd diffCheck

  7. Run cmake utilities .bats files to config and build:

    ./cmake/config.bat
./cmake/build.bat

  8. Build the python df package from the py source code’s directory:

    cd src/gh/diffCheck
python setup.py sdist bdist_wheel

  9. Last, install the pip pacakge from the repository in editable mode. This way, all the modifications made to the source code of the repository will be reflected in the installed package. Open a terminal and run the following command (replace the path with where you download the repository):

    C:\Users\<your-username>\.rhinocode\py39-rh8\python.exe -m pip install -e "<path-to-repository-root>\src\gh\diffCheck"

    Note

    For your info the packages is installed in C:\Users\andre\.rhinocode\py39-rh8\Lib\site-packages.

That’s it you are now a contributor to the diffCheck! We raccomand to not download anymore from yak package but rather use the source code in the repository. If you want the latest diffCheck, checkout and pull the main.

C++ DF build#

We mainly code in C++ to have heavy-lifting operations accessible via a pybind11 interface. If you or someone else has modified one of two follow these steps:

  1. Checkout the repository:

    cd diffCheck

  2. Run cmake utilities .bats files to config and build:

    ./cmake/config.bat
./cmake/build.bat

  3. All the C++’s targets should be now built.

Python DF build#

There are 3 ways to develop in python in DF, often you will do both at the same time:

  • Develop GHComponents in python

  • Develop the pybind11 interface in c++

  • Develop the Python’s diffCheck API

a) Develop GHComponents in API#

We follow the Compas’s method to generate DF python components in Grasshopper, have a look at their guide. All the components are in src/gh/components. To develop a new component, you will need to follow these steps:

  1. Create a new folder in src/gh/components with the name of your component.

  2. Create 3 files with the following names in it:

    • a) code.py: this is where you code goes

    • b) icon.png: this is the icon of your component

    • c) metadata.json: this is the metadata of your component (for more info follow Compas guidelines)

    your code.py should look like this:

    DF_tester component#
     1#! python3
 2
 3
 4from ghpythonlib.componentbase import executingcomponent as component
 5
 6from Grasshopper.Kernel import GH_RuntimeMessageLevel as RML
 7
 8import diffCheck
 9import diffCheck.df_cvt_bindings
10from diffCheck import diffcheck_bindings
11
12class DFTester(component):
13    def RunScript(self):
14        # version
15        ghenv.Component.Message = f"diffCheck v: {diffCheck.__version__}"  # noqa: F821
16
17        # bindings
18        is_binding_imported = diffcheck_bindings.dfb_test.test()
19        if not is_binding_imported:
20            ghenv.Component.AddRuntimeMessage(RML.Warning, "Bindings not imported.")  # noqa: F821
21        else:
22            ghenv.Component.AddRuntimeMessage(RML.Remark, "Bindings imported.")  # noqa: F821
23        print(f"diffCheck test: {diffCheck.df_cvt_bindings.test_bindings()}")
24
25        # workspace unit
26        scalef = diffCheck.df_util.get_doc_2_meters_unitf()
27        if scalef != 1.0:
28            ghenv.Component.AddRuntimeMessage(RML.Warning, "Workspace unit is not in meters.")  # noqa: F821
29        else:
30            ghenv.Component.AddRuntimeMessage(RML.Remark, "Workspace unit is in meters.")  # noqa: F821
31
32        return is_binding_imported

  3. To test it in Grasshopper, drop a new script-sync component in Grasshopper, point it to the code.py file and add diffCheck to the packages to reload of the component.

  4. Finally, you will need to add the following on your last line of the code.py file:

    if __name__ == "__main__":
    comp = DF_tester()
    o_value : bool = comp.Run()

    Warning

    This is necessary to run the component in the Rhino’s python editor but it should be removed when done.

  5. Once you are satisfied you can componentize it by running:

    invoke ghcomponentize

    This will generate the component in the build/gh folder. Grab yours and drop it on the Grasshopper canvas, be sure that this is working as expected.

    Hint

    If you pull a new version of the source code with new components you will need to run this command to update the generate the components, erase the old ones in the ghuser folder and add the new ones.

  6. Done! You have now a new component in the ghuser tab of Grasshopper.

b) Develop the pybind11 interface in c++#

Have a look at C++ DF build to build the c++ project. The pybind11 interface is in the src/diffCheckBindings.cc file. Write your new functions or namespace in this file. This is basically a .dll so for Rhino/Grasshopper to be visible you need to first close Rhino and run cmake/build.bat to build the project. Once done, you can open Rhino and test your new wrap functions in the Rhino’s python editor.

c) Develop the Python’s diffCheck API#

All the source code is in the src/gh/diffCheck/diffCheck folder. If you add new modules or code to existing one and you are using script-sync to test your code in Grasshopper, your changes will be immediately reflected. Have a look at the diffCheck Python API for more info.

Note

If you want to test your code in the Rhino’s python editor, you will need to install the package in editable mode. Have a look at the Prepare your environment section for more info.

Contents