Difference between revisions of "Make software executable by others"
From Geoscience Paper of the Future
(→Training Materials) |
|||
| Line 2: | Line 2: | ||
== What This Task Involves == | == What This Task Involves == | ||
| + | |||
| + | The training materials show how to prepare code so that it is more portable and it can be more easily used by others. | ||
| + | |||
| + | == Training Materials == | ||
| + | |||
| + | This training session was held on April 17, 2015: | ||
| + | |||
| + | * '''[https://www.dropbox.com/s/7fd53wr292x2w83/MakingSoftwareExecutableByOthers.pdf?dl=0 Presentation: Making your software executable by others]''' | ||
| + | * '''[https://www.dropbox.com/s/65vdkac54vepia4/BestPracticesForMATLABCoding.pdf?dl=0 Presentation: Best practices for MATLAB coding]''' | ||
| + | |||
| + | == What to Do == | ||
There are a few simple things that you can do to make your code more usable by others. Here are a few suggestions: | There are a few simple things that you can do to make your code more usable by others. Here are a few suggestions: | ||
| Line 11: | Line 22: | ||
* Scan your code for hardcoded paths, or paths specified in a format that is dependent on the underlying OS. For example, a path that is specified as Users/JohnSmith/mycode/main.py will make the code dependent on that directory existing in the file system. Change those to make them parameters. | * Scan your code for hardcoded paths, or paths specified in a format that is dependent on the underlying OS. For example, a path that is specified as Users/JohnSmith/mycode/main.py will make the code dependent on that directory existing in the file system. Change those to make them parameters. | ||
| − | * If your code has runtime dependencies make notes about them. For example, if your code depends on a | + | * If your code has runtime dependencies make notes about them. For example, if your code depends on a certain R library make sure you specify what it is and how to find it. |
| − | * | + | * Use ''build automation software'' (e.g., make, maven, etc) to compile your code, so that dependencies are tracked |
| − | + | * Write your code so that it gives informative messages to users when an error occurs and returns a proper failure exit code | |
| + | |||
| + | * Write some documentation describing how the code should be invoked, its function, what assumptions it makes, any limitations of its use. | ||
| + | |||
| + | * Create test datasets and describe what the output should be, so that others can be sure they are running your code correctly. | ||
| − | |||
| − | |||
| − | |||
<!-- Add any wiki Text above this Line --> | <!-- Add any wiki Text above this Line --> | ||
Latest revision as of 21:13, 7 May 2015
What This Task Involves
The training materials show how to prepare code so that it is more portable and it can be more easily used by others.
Training Materials
This training session was held on April 17, 2015:
- Presentation: Making your software executable by others
- Presentation: Best practices for MATLAB coding
What to Do
There are a few simple things that you can do to make your code more usable by others. Here are a few suggestions:
- Locate the software that you used to generate the results. Make sure it is modular and it is clear what the data flow across the different modules is.
- If you have variables whose values are set in the code, think about making those values a parameter to the code. This will expose to others the ability to change that value, and will make it easy for others to do so without reloading the code.
- Scan your code for hardcoded paths, or paths specified in a format that is dependent on the underlying OS. For example, a path that is specified as Users/JohnSmith/mycode/main.py will make the code dependent on that directory existing in the file system. Change those to make them parameters.
- If your code has runtime dependencies make notes about them. For example, if your code depends on a certain R library make sure you specify what it is and how to find it.
- Use build automation software (e.g., make, maven, etc) to compile your code, so that dependencies are tracked
- Write your code so that it gives informative messages to users when an error occurs and returns a proper failure exit code
- Write some documentation describing how the code should be invoked, its function, what assumptions it makes, any limitations of its use.
- Create test datasets and describe what the output should be, so that others can be sure they are running your code correctly.
