How to Share a ModusToolbox Project via GitHub - KBA230107

Version 5

    Author: JamesT_21     Version: *A


    I’m having trouble sharing my project via GitHub. What do I do?


    Follow the best practices and tips outlined in this article.



    This KBA covers how to share a ModusToolbox project with other developers. It introduces you to the issues you may encounter and presents a series of solutions, best practices, and tips for how to avoid or solve the issue.

    A version control system (VCS) tracks changes in files over time. How you commit and revert changes varies for each VCS. In addition, each IDE or development flow creates unique user- or environment-specific files that typically should not be tracked.

    The principles discussed in this KBA apply in general to any VCS. The details are specific to git and GitHub, which Cypress uses to deliver code. In addition, some of these issues involve the interaction between git and an IDE. In this case, we use the Eclipse IDE for ModusToolbox. The details of how you solve an issue with your VCS and IDE will vary.

    A shared location for a project is called a repository, or a repo for short. This KBA uses the terms “remote repo” and “local repo.” A remote repo is a repository someone else can use. It is typically on a server (e.g. GitHub), hence “remote” from your computer. The local repo is the clone or copy of the remote repo on each person’s computer. In this model, the remote repo becomes the source of truth. When any collaborator makes local changes, they are pushed to the remote repo for others to use. This KBA is about how to set up and interact with a remote repo. It does not discuss branching, forking, or other strategies for review and approval of changes.

    GitHub has a desktop UI tool. Where appropriate, the best practices and tips cover both the desktop UI and working with GitHub from the git command line. If you are using the desktop tool, make sure you are logged in. Use the File > Options command.


    What files should I not commit to my repository?


    It is common practice to exclude unnecessary files from a VCS. Project directories often have files that are irrelevant to sharing the project. For example, a typical project has all the object files created by the compiler. Typically you do not share these. The IDE’s build system recreates the object files whenever you build. Every IDE has unique files that are specific to you as a user. You don’t want to share those with other users because you might corrupt their workspace or override their preferences. You should commit only files specific to the project. A VCS typically has some way to exclude files or folders. In git, this is the .gitignore file.



    After you create a project, and before you share it, add a .gitignore file to the project folder. Cypress provides a default .gitignore file in many of our code examples. This file excludes common user- and environment-specific files that are typically not committed. This file is a superset that covers multiple tools and IDEs. You can edit the file to remove those that do not apply to you, as well as add other files and folders unique to your environment that you want to exclude.


    How do I create a shared repository based on my project?


    An IDE typically maintains all your project’s files in a folder. You want the contents of this folder in the remote repo, except for files you exclude. Many IDEs also have the concept of a workspace, which may contain multiple projects and user-specific environment settings. What you want to share is just the project, not the entire workspace. There is more than one way to do this. Which way you choose is really a workflow preference.

    One way is that you create the remote repo directly from the project folder in your IDE workspace. This ties your local work environment directly to the remote repo. In effect, your project becomes a local repo for the shared remote repo. The remote repo becomes the single source of truth, and your project depends upon it. When collaborators modify the remote repo, your local repo can get those changes.

    Another way is to create an empty remote repo, and then populate it with the contents of your project folder.

    A VCS tracks the history of all changes. In git, there is a .git folder that has all the files that git uses for this purpose. If your application started from a Cypress code example, your project folder may already have a .git folder that represents the original example from which your project was created. When you are starting fresh to share your own project, you do not want the original .git folder. You are creating a new repository with its own URL, files, and history.


    Solution 1: Create the remote repo directly from your project folder

    Make sure you have a .gitignore file, and that you have deleted any existing .git directory.

    Using the GitHub Desktop tool, use the File > New Repository command.


    Name the repo the same as your project folder. When the name of the repo and the name of the project folder match, GitHub Desktop sets up the project folder to be your local repo. Otherwise, it creates a new folder that does not contain your project.

    Browse to the folder that contains the project folder — not into the actual project folder. Typically this is an IDE workspace, but it could be anywhere you put your project.

    In the GitHub Desktop UI, set other fields as appropriate. For example, if you already have a README file, leave that option unchecked or your file will be replaced. Similarly, leave Git ignore set to none. That’s a widget to pick a .gitignore file. The project already has one.

    When done, your project folder has a .git folder and a .gitattributes file. The desktop tool may make the initial commit automatically, and it will not commit any file excluded by the .gitignore file.

    To create the remote repo, in the desktop tool, click Publish repository. You must be logged in to do this.

    You have now created a remote repo you can share with others.

    You can do the same from the git command line. See Adding an existing project to GitHub using the command line.


    Solution 2: Create an empty remote repo and fill it

    Go directly to GitHub and create a new repo. Give it a name and description, decide if it’s public or private, and create a ReadMe file (you can always replace it later). You can add a default .gitignore file, or identify an open source license if you want.

    Then clone the remote repo. See How do I Clone a Remote Repo. You now have a local repo.

    What you do with the local clone depends on your workflow preferences. For example, you can move your project files into here, and repoint your IDE to this project to make it your development folder. Perhaps you prefer to keep your IDE project entirely local. When you achieve some stable point, you can copy files into the local repo to push to the remote repo.


    I want to collaborate on a shared project. How do I import a project from a remote repo into my IDE?

    There are subtleties that can trip up someone not familiar with git or GitHub. There are really three steps to this process. There is a question and answer focused on each. To work on a shared remote repo, the collaborator:

    When you have done these steps, you can work in the IDE and make changes. Those changes are noted and tracked by the VCS, and can be pushed back to the remote repo. Others can pull those changes into their local copy of the project, so collaboration is enabled.


    How do I clone a remote repo?

    You can do this using either the GitHub Desktop tool, or the command line.

    To use the GitHub Desktop tool, use File > Clone Repository. First, set the Local path to the folder where you want the clone to appear. Then provide the URL to the remote repo, or the user name and repo name. Either works. The tool creates a new folder that matches the name of the remote repo. The names must be the same for this process to work correctly.

    That new folder is now the local repo and has all the files from the remote repo.

    To use the command line, open a Git Bash command line in the Eclipse workspace, or wherever you want the new local repo to appear. Then issue a git clone command, using the URL from GitHub.


    How do I update the local repo to get other required resources?


    ModusToolbox implements a make-based build system. That build infrastructure is distributed on GitHub as a library. It is not part of the application project’s remote repository. Neither are any of the libraries on which the project depends. These other resources must be brought into the application so that it can build.

    Because of these dependencies, if you import or build the project before getting these required resources, you will encounter errors. You can avoid the errors by getting these resources first. Or you can resolve the errors by getting resources after you import the project into the IDE.

    The ModusToolbox build system implements a make getlibs command that gets all necessary resources. There are a variety of ways you can execute this command, but you must execute this command for the project to build correctly. The IDE does not automatically execute the make getlibs command.


    Solution 1: From the command line

    Open a command window and navigate into the project directory. Then execute a make getlibs command. The screenshot shows a Cygwin terminal in the Windows OS. A ModusToolbox makefile must exist in the project directory.


    Solution 2: Use the ModusToolbox Library Manager

    Launch the ModusToolbox Library Manager and browse to the local repo. If you have already imported the project into the Eclipse IDE for ModusToolbox, you can launch the Library Manager from the IDE.

    Change the version of the BSP library used. That invokes make getlibs. You can change back to the original version tag afterwards if you wish.


    Solution 3: Add a build target to the Eclipse IDE project.

    This solution requires that you import the project before updating the resources, so you may see an error. However, it has the additional advantage of making it easy to execute make getlibs at any time from within the project in the IDE. For example, during the development of your project, available libraries may update. If the library manager is set so that it points to the “latest” version of a library, you can get the latest code for any such library simply by running the make getlibs build target.

    First, import the project from the local repo. You may see an error, but you can ignore that for the moment.


    Create a new Build Target. Right click the project, then choose Build Targets > Create.

    Name the target getlibs and click OK.

    The new build target appears in the project explorer. When invoked it executes make getlibs.

    To invoke the command, just double-click the build target.

    After running getlibs, you can build your project successfully.


    How do I import the project in the local repo into the Eclipse IDE for ModusToolbox?


    The key point is that the IDE project must point to the local repo, and not some copy of that repo.

    This use case assumes that collaborators use the same IDE, and that the necessary IDE project files are in the remote repo. The principles are the same for any IDE. The details of how you import a project vary per IDE. It is certainly possible to not include project files in the remote repo, in which case collaborators must create their own IDE project. You could also include project files for multiple IDEs.



    In Eclipse, use File > Import > Other > ModusToolbox Application Import. Browse to the local repo directory and click Finish.

    When you’re done, the project exists in the Eclipse project explorer.

    Note that experienced Eclipse IDE users may be familiar with File > Import > General > Existing Projects into Workspace. That command works, but it doesn’t work as well. The ModusToolbox Application Import command recognizes that the application is intended for ModusToolbox. It sets up Eclipse auto-completion correctly, and then runs the make eclipse command. If the project does not have launch configurations, this will create them automatically.


    Note: If you have not updated the local repo to get all required resources, the project will not build.


    I get an error that says “Build support for the target device not found. Run make getlibs.”

    You need to update the local repo so it has all required resources.


    How do I control the name of the imported project?


    Typically, you want the project name to remain the same as what it is in the remote repo. In that case, you mostly need to do nothing. In some IDEs you set the name of the project when you import it. Just name it whatever you want. In other IDEs, like Eclipse, the IDE names the project for you. It helps to understand how that automatic process works to avoid unexpected name changes.



    If you want or need to change the project name, the simple solution is to do so in the IDE itself after you import it. Right click the project and choose Rename. Note that launch configurations may disappear from the QuickPanel.

    How an Eclipse IDE automatically names a project depends upon where the project is.

    When you import a project from outside the Eclipse workspace, the IDE uses the name embedded in the Eclipse IDE .project file. The only way you can change this is to edit the contents of the .project file before importing the project.

    When you import a project from within the Eclipse workspace, the IDE uses the name of the folder that contains the project. To change the name of the project, you can change the name of the folder containing the project before importing the project. Note that in this case the contents of the .project file remain unchanged and are no longer consistent with the project name displayed in the IDE.

    In all cases, if you change the name of the project, existing launch configurations in the Eclipse IDE disappear from the Quick Panel.


    Solution for IAR Embedded Workbench

    IAR Embedded Workbench does not explicitly support renaming a project. If the repo does not have a project file, you create a new empty project and name it whatever you wish. You can then point the project at the .ipcf file to populate your new project.


    Solution for Keil uVision5

    Keil uVision5 does not explicitly support renaming a project. Set the APPNAME variable in the Makefile to the new project name you wish and then run make uvision5 TOOLCHAIN=ARM in the command window. Double-click the <new_project_name>.cpdsc file to populate your new project.


    I changed the name of my project and launch configurations disappeared. What do I do?


    This happens when a project gets a new name, either when importing or by renaming. When you change the name of the project, the link to the launch configurations is broken, and they disappear from the Quick Panel in the IDE. The files continue to exist, they just are no longer found by the IDE.



    There are two ways to solve this problem.

    The easy way: in the Quick Panel, click the Generate Launches command to regenerate launch configurations. This creates a new set of default launch configurations linked to your project. This is unique to the Eclipse IDE for ModusToolbox.

    However, if you have custom launch configurations, you will want to re-establish the connection to them rather than recreate them. This solution is not intuitive., but it is how an Eclipse IDE reconnects an application to launch configurations.

    In the screenshots that follow, we renamed MyCoolApp to MyHelloWorld, so launch configurations disappeared.

    In the Run menu, choose Debug Configurations. In the dialog, open the Filter menu and uncheck Filter Deleted/Unavailable Projects. This allows you to see the original launch configurations.


    Then open one of the folders in the left column that now contains the formerly-filtered configurations. Select the launch configuration you want to associate with the renamed project. On the right side of the window, click Browse, and then select the project you want to use.

    When you are done, the launch configuration appears in the Quick Panel and is available to your project. It still has the original name, but is now once again linked to the project.