Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document how to add new custom supplements for third-party developers #3127

Open
seisman opened this issue Apr 17, 2020 · 10 comments
Open

Document how to add new custom supplements for third-party developers #3127

seisman opened this issue Apr 17, 2020 · 10 comments
Labels
discussion Topics for longer discussion documentation Improve documentation

Comments

@seisman
Copy link
Member

seisman commented Apr 17, 2020

For any developers who want to develop custom supplements, they need to have a src subdirectory, some C codes, and most importantly, a CMakeLists.txt file.

Here is a full list of all CMake settings that can be included in the CMakeLists.txt:

# SUPPL_NAME [required]
#	name of the supplement package. It can be different from the directory name.
set (SUPPL_NAME newsuppl1)

# SUPPL_PROGS_SRCS [required]
#	list of C source codes for supplemental modules
set (SUPPL_PROGS_SRCS psmeca.c pspolar.c pscoupe.c pssac.c)

# SUPPL_LIB_SRCS [required]
#	list of C source codes for supplemental library
set (SUPPL_LIB_SRCS ${SUPPL_PROGS_SRCS} utilmeca.c sacio.c)

# SUPPL_HEADERS [optional]
#	header files. Will be installed if BUILD_DEVELOPER is TRUE
set (SUPPL_HEADERS meca.h utilmeca.h sacio.h)

# SUPPL_EXAMPLE_FILES [optional]
#	README and other example files
set (SUPPL_EXAMPLE_FILES README.seis)

# SUPPL_EXAMPLE_PROGS [optional]
#	example scripts
set (SUPPL_EXAMPLE_PROGS test1.sh test2.sh)

# SUPPL_EXTRA_INCLUDES [optional]
#	list of extra include directories
set (SUPPL_EXTRA_INCLUDES /usr/local/xxx1/include /usr/local/xxx2/include)

# SUPPL_EXTRA_LIBRARIES [optional]
#	list of extra libraries to link. Can be absolute paths or library names
set (SUPPL_EXTRA_LIBS /usr/local/xxx1/lib/libxxx1.so xxx2)

# SUPPL_LIB_NAME [optional]
#	name of the supplement library.
#	If not set, the supplement package will be built into GMT's supplements.so.
set (SUPPL_LIB_NAME newsuppl1)

# SUPPL_DLL_RENAME [optional, Windows only]
#   rename the supplement library on Windows
set (SUPPL_DLL_RENAME "newsuppl1_w32")

We need to document it somewhere. Maybe in the cmake/ConfigUserAdvanced.cmake or a standalone file listed in the the "Developer Resources" of the GMT documentation.

@seisman seisman added the discussion Topics for longer discussion label Apr 17, 2020
@PaulWessel
Copy link
Member

Agree it needs to be documented. It seems like the above could be called cmake/CMakeLists-Supp-Template.txt and a reference made to it in the AdvancedTemplate. I wonder if we should stick a statement at the end of all the supplement README files to say something like "To explore adding a new supplement by taking advantage of the GMT build system, see CMakeLists-Supp-Template.txt and the discussion in the Advanced Template for custom supplements".

@seisman
Copy link
Member Author

seisman commented Apr 17, 2020

It seems like the above could be called cmake/CMakeLists-Supp-Template.txt and a reference made to it in the AdvancedTemplate. I wonder if we should stick a statement at the end of all the supplement README files to say something like "To explore adding a new supplement by taking advantage of the GMT build system, see CMakeLists-Supp-Template.txt and the discussion in the Advanced Template for custom supplements".

Looks good to me.

Is it required to run the script src/gmt_make_module_src.sh and have the gmt_TAG_module.h and gmt_TAG_module.c files when creating a custom supplement?

@PaulWessel
Copy link
Member

Ah, well there is a need for more documentation on that front. In fact, I think we had that script in the tools folder until recently?
Let me play with this tonight after regular work hours and I will take my gsfml supplement through this trip and take notes.

@seisman seisman added this to the 6.1.0 milestone Apr 17, 2020
@joa-quim
Copy link
Member

I don't like it so much the idea of a .sh script to create the *.ch codes needed to make the new supp functions found-able. I have always did that manually. Basically, they need to follow the gmt_supplements_module.ch example or a simpler template based on them.

@PaulWessel
Copy link
Member

We need to make this simpler. Again I will play with this after work.

@PaulWessel
Copy link
Member

Question. My gsfml CmakeLists.txt did a bit of configuration. I have a few *.in files. Can these be handled at all? One is a C include file and one is a shell script include file...
I can always avoid this but the use was to insert @GSFML_PACKAGE_VERSION@ into the codes. Might it be possible to set GSFML_PACKAGE_VERSION in the CMakeLists.txt and have the cmake automagicallly process the .in files?

@PaulWessel
Copy link
Member

E.g., I could let my Cmakelist file set

set (GSFML_PACKAGE_VERSION "1.1.4")

and ideally leave the rest as is?

@PaulWessel
Copy link
Member

Sorry, answering myself. I would add

configure_file (gsfml_config.h.in gsfml_config.h)
configure_file (fz_funcs.sh.in fz_funcs.sh)

Oh, and I need to add some shell scripts to be installed as well. gsfml is a mix of scripts and C codes... How to handle that?

@PaulWessel
Copy link
Member

Yikes, there is more. I have a data file with magnetic reversal times from various references. These values do sometimes change and new reference models are published. I have a GNUmakefile to turns this table into a bunch of C include files. I think I will do that outside of the GMT configuration. Not worth the trouble.

@PaulWessel
Copy link
Member

Got it to work just fine. here is trailing output from gmt --help:

x2sys_solve      Determine least-squares systematic correction from crossovers

=== GMT gsfml: Tools for the GSFML project ===

Module name:     Purpose of gsfml module:
----------------------------------------------------------------
fzanalyzer       Analysis of fracture zones using crossing profiles
fzblender        Produce a smooth blended fracture zone trace
mlconverter      Convert chrons to ages using selected magnetic timescale

@seisman seisman added the documentation Improve documentation label May 7, 2020
@seisman seisman modified the milestones: 6.1.0, 6.1.1 Jul 5, 2020
@seisman seisman modified the milestones: 6.1.1, 6.2.0 Sep 3, 2020
@seisman seisman removed this from the 6.2.0 milestone Apr 19, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
discussion Topics for longer discussion documentation Improve documentation
Projects
None yet
Development

No branches or pull requests

3 participants