Static Library/Cleanup

[lcarcaramo]

💡 Issue Reference

Issue: fixes #24

💻 What does this address?

• Build CBXP library distribution as a static library rather than a dynamic library. This makes makes it easier to call the C interface since all of the boilerplate for dealing with a dynamic library is not needed, and statically linking with CBXP means that CBXP does not need to be installed on each system a C/C++ application that uses CBXP is installed on since the static library is statically linked. And since CBXP is licensed under Apache 2.0, which is very permissive, only a copyright notice needs to be provided when statically linking.
• Compile with -fstack-protector-strong. Compiling with this argument helps protect the stack form stack corruption.
  • https://www.ibm.com/docs/en/open-xl-c-cpp-zos/2.2.0?topic=options-qstackprotect
• Make sure cbxp_free() does not attempt to free NULL pointers.
• Move cbxp_result_t to cbxp.h and delete cbxp_result.h.
• Use std::memcpy() instead of std::strncpy() to copy CBXP result JSON to the C string buffer returned to the user and don't use 0 initialization when allocating the target C string buffer. Since we know the exact size of the string and that it is going to fill the entire buffer, there is no reason to use strncpy() and deal with it's nuances. It is also a waste of clock cycles to use zero initialization when allocating the target C string buffer since the entire buffer will be filled. To ensure the buffer is null terminated, just set the last bytes in the buffer to null since the buffer is allocated one byte longer than the source C++ string.
• ASCBASCB is technically not a programming interface so support for that field has been removed from ascb.cpp.
  • https://www.ibm.com/docs/en/zos/3.2.0?topic=iar-ascb-information
• Cleanup main.cpp.
• Minor Jenkinsfile updates.
• When creating the Shell/C/C++ PAX use -x pax to use the 'pax interchange format'. I believe this may result in slightly better compression along with a handful of other benefits.
  • https://www.ibm.com/docs/en/zos/3.2.0?topic=descriptions-pax-interchange-portable-archives
• Update copyright year in LICENSE file.

📋 Is there a test case?

All unit tests are passing.

⚠️ Note that static library cannot be used with xlc. I am not sure if xlc compiled code would work with a dynamic library distribution either based on the Binary Compatibility doc.

C Test:

#include <cbxp.h>
#include <stdbool.h>
#include <stdio.h>

int main() {
  // Call CBXP
  puts("Calling CBXP from C...");
  cbxp_result_t* cbxp_result = cbxp("psa", "", "", false);

  // Make sure call was successful
  if (cbxp_result->return_code != 0) {
    fprintf(stderr, "Error: CBXP return with RC=%d\n", cbxp_result->return_code);
  // Print Result JSON
  } else {
    puts(cbxp_result->result_json);
  }

  // Cleanup
  cbxp_free(cbxp_result, false);

  return 0;
}

# Compile
ibm-clang64 -c -fzos-le-char-mode=ascii -I./cbxp-0.0.3/include -o main.o main.c
# Link
ibm-clang++64 -fzos-le-char-mode=ascii -o main ./cbxp-0.0.3/lib/libcbxp.a main.o
# Run
./main

C++ Test:

#include <iostream>

#include <cbxp.h>

int main() {
  // Call CBXP
  std::cout << "Calling CBXP from C++..." << std::endl;
  cbxp_result_t * cbxp_result = cbxp("psa", "", "", false);

  // Make sure call was successful
  if (cbxp_result->return_code != 0) {
    std::cerr << "Error: CBXP returned with RC=" << cbxp_result->return_code << std::endl;
  // Print result JSON
  } else {
    std::cout << cbxp_result->result_json << std::endl;
  }

  // Cleanup
  cbxp_free(cbxp_result, false);

  return 0;
}

# Compile
ibm-clang++64 -c -fzos-le-char-mode=ascii -I./cbxp-0.0.3/include -o main.o main.cpp
# Link
ibm-clang++64 -fzos-le-char-mode=ascii -o main ./cbxp-0.0.3/lib/libcbxp.a main.o
# Run
./main

[ElijahSwiftIBM]

Adding steps to build and extract the package to the PR conversation for those who may need them documented:

To build the pax run gmake package. The pax will get generated in the ./dist directory.

You need to extract the pax somewhere and point the include path accordingly.

You can extract the contents of the pax using pax -rf cbxp-0.0.3.pax.Z

$ tree
.
|-- cbxp-0.0.3
|   |-- LICENSE
|   |-- NOTICES
|   |-- bin
|   |   `-- cbxp
|   |-- include
|   |   `-- cbxp.h
|   `-- lib
|       `-- libcbxp.a
|-- cbxp-0.0.3-cp312-none-any.whl
|-- cbxp-0.0.3-cp313-none-any.whl
|-- cbxp-0.0.3.pax.Z
|-- cbxp-0.0.3.tar.gz
|-- main
|-- main.c
|-- main.cpp
`-- main.o

[ElijahSwiftIBM]

Looks good