[REVIEW]: CMakePPLang: An object-oriented extension to CMake

[editorialbot]

Submitting author: !--author-handle-->@ryanmrichard<!--end-author-handle-- (Ryan M. Richard) Repository: https://github.com/CMakePP/CMakePPLang/ Branch with paper.md (empty if default branch): joss_paper Version: v1.0.3 Editor: !--editor-->@diehlpk<!--end-editor-- Reviewers: @bast, @tianyi93 Archive: 10.5281/zenodo.8339121

Status

Status badge code:

HTML: <a href="https://joss.theoj.org/papers/3cc2bc54aa95fc4c57aed8ccab049cae"><img src="https://joss.theoj.org/papers/3cc2bc54aa95fc4c57aed8ccab049cae/status.svg"></a>
Markdown: [![status](https://joss.theoj.org/papers/3cc2bc54aa95fc4c57aed8ccab049cae/status.svg)](https://joss.theoj.org/papers/3cc2bc54aa95fc4c57aed8ccab049cae)

Reviewers and authors:

Please avoid lengthy details of difficulties in the review thread. Instead, please create a new issue in the target repository and link to those issues (especially acceptance-blockers) by leaving comments in the review thread below. (For completists: if the target issue tracker is also on GitHub, linking the review thread in the issue or vice versa will create corresponding breadcrumb trails in the link target.)

Reviewer instructions & questions

@bast & @tianyi93, your review will be checklist based. Each of you will have a separate checklist that you should update when carrying out your review. First of all you need to run this command in a separate comment to create the checklist:

@editorialbot generate my checklist

The reviewer guidelines are available here: https://joss.readthedocs.io/en/latest/reviewer_guidelines.html. Any questions/concerns please let @diehlpk know.

✨ Please start on your review when you are able, and be sure to complete your review in the next six weeks, at the very latest ✨

Checklists

📝 Checklist for @tianyi93

[editorialbot]

Hello humans, I'm @editorialbot, a robot that can help you with some common editorial tasks.

For a list of things I can do to help you, just type:

@editorialbot commands

For example, to regenerate the paper pdf after making changes in the paper's md or bib files, type:

@editorialbot generate pdf

[editorialbot]

Software report:

github.com/AlDanial/cloc v 1.88  T=0.08 s (2856.9 files/s, 223586.4 lines/s)
-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
CMake                          192           2269           4595           7572
reStructuredText                25            719           1011           1248
Markdown                         3             37              0            168
YAML                             8             32            138            136
TeX                              1             12              0            134
Python                           1              8             17             32
make                             1              4              6             10
Bourne Shell                     1              2              0              7
-------------------------------------------------------------------------------
SUM:                           232           3083           5767           9307
-------------------------------------------------------------------------------

gitinspector failed to run statistical information for the repository

[editorialbot]

Wordcount for paper.md is 1172

[editorialbot]

Reference check summary (note 'MISSING' DOIs are suggestions that need verification):

OK DOIs

- 10.1063/5.0147903 is OK
- 10.1109/MC.2006.20 is OK

MISSING DOIs

- None

INVALID DOIs

- None

[editorialbot]

:warning: An error happened when generating the pdf.

[ryanmrichard]

@editorialbot generate pdf

[editorialbot]

:point_right::page_facing_up: Download article proof :page_facing_up: View article proof on GitHub :page_facing_up: :point_left:

[diehlpk]

Reminder set for @tianyi93 in 1 weeks

[diehlpk]

@editorialbot commands

[editorialbot]

Hello @diehlpk, here are the things you can ask me to do:

# List all available commands
@editorialbot commands

# Add to this issue's reviewers list
@editorialbot add @username as reviewer

# Remove from this issue's reviewers list
@editorialbot remove @username from reviewers

# Get a list of all editors's GitHub handles
@editorialbot list editors

# Assign a user as the editor of this submission
@editorialbot assign @username as editor

# Remove the editor assigned to this submission
@editorialbot remove editor

# Remind an author, a reviewer or the editor to return to a review after a 
# certain period of time (supported units days and weeks)
@editorialbot remind @reviewer in 2 weeks

# Check the references of the paper for missing DOIs
@editorialbot check references

# Perform checks on the repository
@editorialbot check repository

# Adds a checklist for the reviewer using this command
@editorialbot generate my checklist

# Set a value for version
@editorialbot set v1.0.0 as version

# Set a value for branch
@editorialbot set joss-paper as branch

# Set a value for repository
@editorialbot set https://github.com/organization/repo as repository

# Set a value for the archive DOI
@editorialbot set set 10.5281/zenodo.6861996 as archive

# Mention the EiCs for the correct track
@editorialbot ping track-eic

# Generates the pdf paper
@editorialbot generate pdf

# Recommends the submission for acceptance
@editorialbot recommend-accept

# Generates a LaTeX preprint file
@editorialbot generate preprint

# Flag submission with questionable scope
@editorialbot query scope

# Get a link to the complete list of reviewers
@editorialbot list reviewers

# Creates a post-review checklist with editor and authors tasks
@editorialbot create post-review checklist

# Open the review issue
@editorialbot start review

[diehlpk]

@editorialbot remind @bast in 1 weeks

[editorialbot]

Reminder set for @bast in 1 weeks

[bast]

@editorialbot remind @bast in 1 weeks

Thanks! I plan to do the review work coming week after Wednesday.

[editorialbot]

:wave: @bast, please update us on how your review is going (this is an automated reminder).

[tianyizhangcs]

Review checklist for @tianyi93

Conflict of interest

• [x] I confirm that I have read the JOSS conflict of interest (COI) policy and that: I have no COIs with reviewing this work or that any perceived COIs have been waived by JOSS for the purpose of this review.

Code of Conduct

• [x] I confirm that I read and will adhere to the JOSS code of conduct.

General checks

• [x] Repository: Is the source code for this software available at the https://github.com/CMakePP/CMakePPLang/?
• [x] License: Does the repository contain a plain-text LICENSE file with the contents of an OSI approved software license?
• [x] Contribution and authorship: Has the submitting author (@ryanmrichard) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?
• [x] Substantial scholarly effort: Does this submission meet the scope eligibility described in the JOSS guidelines
• [x] Data sharing: If the paper contains original data, data are accessible to the reviewers. If the paper contains no original data, please check this item.
• [x] Reproducibility: If the paper contains original results, results are entirely reproducible by reviewers. If the paper contains no original results, please check this item.
• [x] Human and animal research: If the paper contains original data research on humans subjects or animals, does it comply with JOSS's human participants research policy and/or animal research policy? If the paper contains no such data, please check this item.

Functionality

• [x] Installation: Does installation proceed as outlined in the documentation?
• [x] Functionality: Have the functional claims of the software been confirmed?
• [x] Performance: If there are any performance claims of the software, have they been confirmed? (If there are no claims, please check off this item.)

Documentation

• [x] A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• [x] Installation instructions: Is there a clearly-stated list of dependencies? Ideally these should be handled with an automated package management solution.
• [x] Example usage: Do the authors include examples of how to use the software (ideally to solve real-world analysis problems).
• [x] Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g., API method documentation)?
• [x] Automated tests: Are there automated tests or manual steps described so that the functionality of the software can be verified?
• [x] Community guidelines: Are there clear guidelines for third parties wishing to 1) Contribute to the software 2) Report issues or problems with the software 3) Seek support

Software paper

• [x] Summary: Has a clear description of the high-level functionality and purpose of the software for a diverse, non-specialist audience been provided?
• [x] A statement of need: Does the paper have a section titled 'Statement of need' that clearly states what problems the software is designed to solve, who the target audience is, and its relation to other work?
• [x] State of the field: Do the authors describe how this software compares to other commonly-used packages?
• [x] Quality of writing: Is the paper well written (i.e., it does not require editing for structure, language, or writing quality)?
• [x] References: Is the list of references complete, and is everything cited appropriately that should be cited (e.g., papers, datasets, software)? Do references in the text use the proper citation syntax?

[tianyizhangcs]

The document is about CMakePPLang, an object-oriented extension to the CMake language. It aims to simplify the creation and maintenance of projects built on CMake. The author has provided a clear description of the high-level functionality and purpose of the software for a diverse, non-specialist audience. It also compared with CMake++ and explained the need for CMakePPLang.

Few comments are listed below:

• [x] Do the authors clearly state what problems the software is designed to solve and who the target audience is? The level of detail in the Statement of Need within the Documentation is currently not as comprehensive as that found in the paper. It is advisable to enhance the Statement of Need in the Documentation by incorporating the rationale behind the necessity for CMakePPLang. This will provide a clearer understanding of why CMakePPLang is required and how it contributes to the overall objectives.

• [x] Automated tests: Are there automated tests or manual steps described so that the functionality of the software can be verified? The documentation provided example usage, however, did not state how to run automated tests.

[ryanmrichard]

@tianyi93 when you get a chance please take a look at CMakePP/CMakePPLang#113. I believe it addresses your comments (and if it does not, please let me know).

[bast]

I am finally working on it - tracking my progress in this checklist:

Review checklist for @bast

Conflict of interest

• [x] I confirm that I have read the JOSS conflict of interest (COI) policy and that: I have no COIs with reviewing this work or that any perceived COIs have been waived by JOSS for the purpose of this review.

Code of Conduct

• [x] I confirm that I read and will adhere to the JOSS code of conduct.

General checks

• [x] Repository: Is the source code for this software available at the https://github.com/CMakePP/CMakePPLang/?
• [x] License: Does the repository contain a plain-text LICENSE file with the contents of an OSI approved software license?
• [x] Contribution and authorship: Has the submitting author (@ryanmrichard) made major contributions to the software? Does the full list of paper authors seem appropriate and complete?
• [x] Substantial scholarly effort: Does this submission meet the scope eligibility described in the JOSS guidelines
• [x] Data sharing: If the paper contains original data, data are accessible to the reviewers. If the paper contains no original data, please check this item.
• [x] Reproducibility: If the paper contains original results, results are entirely reproducible by reviewers. If the paper contains no original results, please check this item.
• [x] Human and animal research: If the paper contains original data research on humans subjects or animals, does it comply with JOSS's human participants research policy and/or animal research policy? If the paper contains no such data, please check this item.

Functionality

• [x] Installation: Does installation proceed as outlined in the documentation?
• [x] Functionality: Have the functional claims of the software been confirmed?
• [x] Performance: If there are any performance claims of the software, have they been confirmed? (If there are no claims, please check off this item.)

Documentation

• [x] A statement of need: Do the authors clearly state what problems the software is designed to solve and who the target audience is?
• [x] Installation instructions: Is there a clearly-stated list of dependencies? Ideally these should be handled with an automated package management solution.
• [x] Example usage: Do the authors include examples of how to use the software (ideally to solve real-world analysis problems).
• [x] Functionality documentation: Is the core functionality of the software documented to a satisfactory level (e.g., API method documentation)?
• [x] Automated tests: Are there automated tests or manual steps described so that the functionality of the software can be verified?
• [x] Community guidelines: Are there clear guidelines for third parties wishing to 1) Contribute to the software 2) Report issues or problems with the software 3) Seek support

Software paper

• [x] Summary: Has a clear description of the high-level functionality and purpose of the software for a diverse, non-specialist audience been provided?
• [x] A statement of need: Does the paper have a section titled 'Statement of need' that clearly states what problems the software is designed to solve, who the target audience is, and its relation to other work?
• [x] State of the field: Do the authors describe how this software compares to other commonly-used packages?
• [x] Quality of writing: Is the paper well written (i.e., it does not require editing for structure, language, or writing quality)?
• [x] References: Is the list of references complete, and is everything cited appropriately that should be cited (e.g., papers, datasets, software)? Do references in the text use the proper citation syntax?

[bast]

I still need to carefully go through my checklist above but for me the main question to address in the code documentation and in the paper is the question how the authors envision to manage versioning, compatibility, deprecation, and API changes in this tool. This tool is built on top of CMake language. The CMake language evolves (with its own versioning and deprectation mechanisms) and also CMakePPLang will evolve. How will it "move" with respect to an evolving CMake language underneath? If I as user had to decide whether to build my project on top of CMakePPLang, that would be a very important question for me. I would like to know what to expect 2-5 years down the line when CMake maybe has a new major version. Would my project stop working or would I have a way to pin a version? Do I need to anticipate lots of work updating my CMake code?

[bast]

When reading the paper alone and looking at Figures 2 and 3 I was asking myself what "CTOR" meant. In the code documentation this is clarified but the figures would be easier to read if "CTOR" was explained at least in the code comment inside the example code ("GET" and "SET" are on the other hand intuitively clear).

[bast]

A convincing argument to try this tool is its stronger typing. As a suggestion, it could be powerful to show in the paper a short example where because of weak typing a native CMake code could lead to an error that is difficult to catch whereas CMakePPLang catches the mistake with a clear error message since it is stricter about typing.

[bast]

Version on https://cmakepp.github.io/CMakePPLang/ seems to be 1.0.0 but I am not sure this matches the version of the code. But maybe it is the target version?

[diehlpk]

@ryanmrichard can you please have a look at bast's comments?

[ryanmrichard]

@diehlpk I have read his comments and @zachcran and I are working on addressing them. We're hoping to have addressed them by the end of the week.

[bast]

Thanks! I am working on the rest of the checklist so the missing checks do not mean that there is a problem.

[bast]

Install instructions here seem to point to a private or old repo:

- GIT_REPOSITORY https://github.com/CMakePP/cmakepp_lang
+ GIT_REPOSITORY https://github.com/CMakePP/cmakePPlang

[tianyizhangcs]

@tianyi93 when you get a chance please take a look at CMakePP/CMakePPLang#113. I believe it addresses your comments (and if it does not, please let me know).

LGTM, thanks!

[diehlpk]

@tianyi93 when you get a chance please take a look at CMakePP/CMakePPLang#113. I believe it addresses your comments (and if it does not, please let me know).

LGTM, thanks!

@tianyi93 can you please update the check list, if the author satisfied your comments.

[bast]

My comments have been addressed in https://github.com/CMakePP/CMakePPLang/pull/114 and https://github.com/CMakePP/CMakePPLang/pull/115 - thank you so much! After the changes are merged, can we build a new version of the manuscript for a final read-through? (If this is not the way how it usually works, I can also build it then locally)

[ryanmrichard]

@editorialbot generate pdf

[editorialbot]

:point_right::page_facing_up: Download article proof :page_facing_up: View article proof on GitHub :page_facing_up: :point_left:

[bast]

Thanks! All my points were carefully addressed.

[tianyizhangcs]

@tianyi93 when you get a chance please take a look at CMakePP/CMakePPLang#113. I believe it addresses your comments (and if it does not, please let me know).

LGTM, thanks!

@tianyi93 can you please update the check list, if the author satisfied your comments.

Updated, Thanks!

[diehlpk]

@editorialbot check references

[diehlpk]

@editorialbot generate paper

[editorialbot]

I'm sorry human, I don't understand that. You can see what commands I support by typing:

@editorialbot commands

[editorialbot]

Reference check summary (note 'MISSING' DOIs are suggestions that need verification):

OK DOIs

- 10.1063/5.0147903 is OK
- 10.1109/MC.2006.20 is OK

MISSING DOIs

- None

INVALID DOIs

- None

[diehlpk]

@editorialbot generate pdf

[editorialbot]

:point_right::page_facing_up: Download article proof :page_facing_up: View article proof on GitHub :page_facing_up: :point_left:

[diehlpk]

@ryanmrichard I read the paper, and the references are inconsistent. Sometimes there is a space word (reference) and sometimes there is no space word(reference). I think both are fine, but it should be consistent.

 (Richard et al., 2023) Better utilities and extensions in CMake can
26 help alleviate these issues, but these tools must be able to be designed in a maintainable and
27 testable way. 

Would it be possible to place the reference somewhere else? it is strange to start a sentence with the reference.

[diehlpk]

@ryanmrichard The C++ in the paper looks strange since the ++ are very big. One possible solution is to use C\texttt{++} to make it look nicer. This is not necessary, but I think the paper looks nicer.

[ryanmrichard]

@diehlpk Thanks for pointing those issues out. I agree with both of your comments. I looked into the C++ thing a bit and apparently ISO C++ has their own recommendation; I went with the ISO recommendation and think it looks nice.

@editorialbot generate pdf

[diehlpk]

@editorialbot generate pdf

[editorialbot]

:point_right::page_facing_up: Download article proof :page_facing_up: View article proof on GitHub :page_facing_up: :point_left:

[diehlpk]

@ryanmrichard Thanks, now I am OK with the paper.

Please generate the following:

• [x] A new release including all changes made during the JOSS review. Please post the new version number here.
• [ ] Upload that release to Zenodo or FigShare and post the DOI here. Note that authors and the title on the archive have to match with the paper.

[ryanmrichard]

The version number of CMakePPLang is v1.0.0

The Zenodo DOI is 10.5281/zenodo.8339016

[diehlpk]

@editorialbot set v1.0.0 as version

[editorialbot]

Done! version is now v1.0.0

[diehlpk]

@editorialbot set 10.5281/zenodo.8339016 as archive

[editorialbot]

Done! archive is now 10.5281/zenodo.8339016