How to Create an ArmarX Package in a Git Repository

The easiest way to create an ArmarX package in a Git repository is like this:

1. Create the Git repository (e.g. by creating a project on a platform such as GitLab). If you are a student at H2T, your supervisor will probably set this up for you. Let's call the project "awesome_robotics".

2. Clone the (potentially empty) repository to a location of your choice, e.g. inside your ArmarX workspace:

   # Clone the git repository.
   git clone url/to/awesome_robotics.git  

   Assume this clones the project to the directory awesome_robotics.

3. Go into the directory and (either on the top-level or in a subdirectory) create the package using the package tool:

   # Go into the cloned Git repository.
   cd awesome_robotics  
   # Create the ArmarX package.
   armarx-package init awesome_robotics  

   Note that this creates another directory awesome_robotics containing the package files. That is, the file system structure now looks like this:

   awesome_robotics/     # The Git repository. 
     awesome_robotics/   # The ArmarX package.
       README.md
       CMakeLists.txt
        source/
       ...

4. If you want the repository to directly contain the package files (i.e. README.md and CMakeLists.txt in the top-level directory of the repository), move all files and directories (including hidden ones starting with a .) from the created package to the repository, then remove the directory:

   # In the Git repository:
   mv awesome_robotics/* awesome_robotics/.* .
   rmdir awesome_robotics

You may get these errors:

mv: cannot move 'awesome_robotics/.' to './.': Device or resource busy 
mv: cannot move 'awesome_robotics/..' to './..': Device or resource busy

That is ok. This is just a side effect of . and .. being part of .*.

Now the repository should look like this:

awesome_robotics/  # The Git repository AND the ArmarX package.
  README.md
  CMakeLists.txt
  source/
  ...

1. Commit the files to Git:

   git add .
   git commit -m "Create ArmarX package awesome_robotics"

2. Push the changes:

   git push

3. (Optional) Create an Axii module for your package in a suitable Axii module database. (For students at H²T, this is here.) You can start with this module definition file and add your module's requirements and other options as appropriate (start by replacing the TODO: ... parts):

   {
     "general": {
       "url": "TODO: https://full.link.to/your/project",
       "authors": "TODO: First Last <first.last@example.org>"
     },
    
     "update": {
       "git": {
         "h2t_gitlab_slug": "TODO: the/path/to/your/gitlab/project/after/git.h2t.iar.kit.edu/"
       }
     },
    
     "prepare": {
       "cmake": {
         "definitions": {
           "CMAKE_C_COMPILER": "$ARMARX_C_COMPILER",
           "CMAKE_CXX_COMPILER": "$ARMARX_CXX_COMPILER"
         }
       }
     },
    
     "build": "cmake",
    
     "required_modules": {
       "armarx/meta/compiler": {},
       "armarx/ArmarXCore": {}
     }
   }