From ea1b4de4332153d145d5c7597a49aa2818b18fe7 Mon Sep 17 00:00:00 2001 From: Fiona La Date: Tue, 8 Feb 2022 11:37:06 -0500 Subject: [PATCH 1/8] Add Install section to README.md --- matlab/README.md | 26 +++++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/matlab/README.md b/matlab/README.md index edf991e87eb..d4aefb3b453 100644 --- a/matlab/README.md +++ b/matlab/README.md @@ -76,8 +76,32 @@ Run the `test` function to execute the unit tests: >> test ``` -## Try it out +### Install MATLAB Interface to Arrow using CMake +After building the MATLAB Interface to Arrow, install the library by running the following command: +``` CMake +cmake --build build --config Release --target install +``` +The installation process includes + +Once installed, the interface's source files and libraries are relocatable, on all platforms. If the interface is relocated, then the user must manually add the new location to the [MATLAB Search Path](https://uk.mathworks.com/help/matlab/matlab_env/what-is-the-matlab-search-path.html). + +The following flags can be passed to the CMake generation command to configure the installation step: +| CMake Flag | Default Value | Values accepted | Description | +| ---------------------------------------- | ------------------- | ---------------------------------------------- | ------------- | +| `CMAKE_INSTALL_PREFIX` | platform dependent | A path to any directory with write permissions | The location that the MATLAB Interface to Arrow will be installed. +| `MATLAB_ADD_INSTALL_DIR_TO_SEARCH_PATH` | `ON` | `ON` or `OFF` | Whether the path to the install directory should be added directly added to the MATLAB Search Path. +| `MATLAB_ADD_INSTALL_DIR_TO_STARTUP_FILE` | `ON` | `ON` or `OFF` | Whether a command to add the path to the install directory should be added to the `startup.m` file located at the MATLAB `userpath`. +###### `CMAKE_INSTALL_PREFIX` +The install command will install the interface to the location pointed to by `CMAKE_INSTALL_PREFIX`. The default value for this CMake variable is platform dependent. Default values for the location on different platforms can be found here: [`CMAKE_INSTALL_PREFIX`](https://cmake.org/cmake/help/v3.0/variable/CMAKE_INSTALL_PREFIX.html). + +###### `MATLAB_ADD_INSTALL_DIR_TO_SEARCH_PATH` +Call `addpath` and `savepath` to modify the default `pathdef.m` file that MATLAB uses on startup. This option is on by default. However, it can only be used if CMake has the appropriate permissions to modify `pathdef.m`. + +###### `MATLAB_ADD_INSTALL_DIR_TO_STARTUP_FILE` +Add an `addpath` command to the `startup.m` file located at the [`userpath`](https://uk.mathworks.com/help/matlab/matlab_env/what-is-the-matlab-search-path.html#:~:text=on%20Search%20Path.-,userpath%20Folder%20on%20the%20Search%20Path,-The%20userpath%20folder). This option can be used if a user does not have the permissions to modify the default `pathdef.m` file. + +## Try it out ### Add the src and build directories to your MATLAB path ``` matlab From c40861ff32e19a489544014ed3d6a976aa7f05b7 Mon Sep 17 00:00:00 2001 From: Fiona La Date: Tue, 8 Feb 2022 11:54:14 -0500 Subject: [PATCH 2/8] Remove CMake flags for Install step, add to a separate INSTALL.md file in the future --- matlab/README.md | 16 ---------------- 1 file changed, 16 deletions(-) diff --git a/matlab/README.md b/matlab/README.md index d4aefb3b453..b38ca713388 100644 --- a/matlab/README.md +++ b/matlab/README.md @@ -85,22 +85,6 @@ The installation process includes Once installed, the interface's source files and libraries are relocatable, on all platforms. If the interface is relocated, then the user must manually add the new location to the [MATLAB Search Path](https://uk.mathworks.com/help/matlab/matlab_env/what-is-the-matlab-search-path.html). -The following flags can be passed to the CMake generation command to configure the installation step: -| CMake Flag | Default Value | Values accepted | Description | -| ---------------------------------------- | ------------------- | ---------------------------------------------- | ------------- | -| `CMAKE_INSTALL_PREFIX` | platform dependent | A path to any directory with write permissions | The location that the MATLAB Interface to Arrow will be installed. -| `MATLAB_ADD_INSTALL_DIR_TO_SEARCH_PATH` | `ON` | `ON` or `OFF` | Whether the path to the install directory should be added directly added to the MATLAB Search Path. -| `MATLAB_ADD_INSTALL_DIR_TO_STARTUP_FILE` | `ON` | `ON` or `OFF` | Whether a command to add the path to the install directory should be added to the `startup.m` file located at the MATLAB `userpath`. - -###### `CMAKE_INSTALL_PREFIX` -The install command will install the interface to the location pointed to by `CMAKE_INSTALL_PREFIX`. The default value for this CMake variable is platform dependent. Default values for the location on different platforms can be found here: [`CMAKE_INSTALL_PREFIX`](https://cmake.org/cmake/help/v3.0/variable/CMAKE_INSTALL_PREFIX.html). - -###### `MATLAB_ADD_INSTALL_DIR_TO_SEARCH_PATH` -Call `addpath` and `savepath` to modify the default `pathdef.m` file that MATLAB uses on startup. This option is on by default. However, it can only be used if CMake has the appropriate permissions to modify `pathdef.m`. - -###### `MATLAB_ADD_INSTALL_DIR_TO_STARTUP_FILE` -Add an `addpath` command to the `startup.m` file located at the [`userpath`](https://uk.mathworks.com/help/matlab/matlab_env/what-is-the-matlab-search-path.html#:~:text=on%20Search%20Path.-,userpath%20Folder%20on%20the%20Search%20Path,-The%20userpath%20folder). This option can be used if a user does not have the permissions to modify the default `pathdef.m` file. - ## Try it out ### Add the src and build directories to your MATLAB path From 5072800b99ecef8043d5ed7bb4d788ca87815db2 Mon Sep 17 00:00:00 2001 From: Kevin Gurney Date: Tue, 8 Feb 2022 12:00:10 -0500 Subject: [PATCH 3/8] 1. Lay out basic structure of updated documentation. 2. Remove information about non-standard workflows from main README.md file. --- matlab/README.md | 95 ++++++++++++++---------------------------------- 1 file changed, 28 insertions(+), 67 deletions(-) diff --git a/matlab/README.md b/matlab/README.md index b38ca713388..a632fb99dcc 100644 --- a/matlab/README.md +++ b/matlab/README.md @@ -17,84 +17,41 @@ under the License. --> -## MATLAB Library for Apache Arrow +# MATLAB Interface to Apache Arrow ## Status This is a very early stage MATLAB interface to the Apache Arrow C++ libraries. -The current code only supports reading/writing numeric types from/to Feather files. +The current code only supports reading/writing numeric types from/to Feather v1 files. -## Building from source +## Build -### Get Arrow and build Arrow CPP +## Install -See: [Arrow CPP README](../cpp/README.md) - -### Build MATLAB interface to Apache Arrow using MATLAB R2018a: - - cd arrow/matlab - mkdir build - cd build - cmake .. - make - -#### Non-standard MATLAB and Arrow installations - -To specify a non-standard MATLAB install location, use the Matlab_ROOT_DIR CMake flag: - - cmake .. -DMatlab_ROOT_DIR=/ - -To specify a non-standard Arrow install location, use the ARROW_HOME CMake flag: - - cmake .. -DARROW_HOME=/ - -### Build MATLAB interface to Arrow using MATLAB R2018b or later: - -This may be preferred if you are using MATLAB R2018b or later and have encountered [linker errors](https://gitlab.kitware.com/cmake/cmake/issues/18391) when using CMake. - -Prerequisite: Ensure that the Arrow C++ library is already installed and the `ARROW_HOME` environment variable is set to the installation root. - -To verify this, you can run: - -``` matlab ->> getenv ARROW_HOME -``` - -This should print a path that contains `include` and `lib` directories with Arrow C++ headers and libraries. - -Navigate to the `build_support` subfolder and run the `compile` function to build the necessary MEX files: - -``` matlab ->> cd build_support ->> compile -``` - -Run the `test` function to execute the unit tests: - -``` matlab ->> test -``` - -### Install MATLAB Interface to Arrow using CMake After building the MATLAB Interface to Arrow, install the library by running the following command: + ``` CMake cmake --build build --config Release --target install ``` + The installation process includes Once installed, the interface's source files and libraries are relocatable, on all platforms. If the interface is relocated, then the user must manually add the new location to the [MATLAB Search Path](https://uk.mathworks.com/help/matlab/matlab_env/what-is-the-matlab-search-path.html). -## Try it out -### Add the src and build directories to your MATLAB path +## Test + +### C++ + +### MATLAB ``` matlab ->> cd(fullfile('arrow', 'matlab')); ->> addpath src; ->> addpath build; +>> runtests test; ``` -### Write a MATLAB table to a Feather file +## Usage + +### Write a MATLAB table to a Feather v1 file ``` matlab >> t = array2table(rand(10, 10)); @@ -102,19 +59,23 @@ Once installed, the interface's source files and libraries are relocatable, on a >> featherwrite(filename,t); ``` -### Read a Feather file into a MATLAB table +### Read a Feather v1 file into a MATLAB table ``` matlab >> filename = 'table.feather'; >> t = featherread(filename); ``` -## Running the tests +## Troubleshooting + +### Non-standard MATLAB and Arrow installations + +To specify a non-standard MATLAB install location, use the Matlab_ROOT_DIR CMake flag: + + cmake .. -DMatlab_ROOT_DIR=/ + +To specify a non-standard Arrow install location, use the ARROW_HOME CMake flag: + + cmake .. -DARROW_HOME=/ + -``` matlab ->> cd(fullfile('arrow', 'matlab')); ->> addpath src; ->> addpath build; ->> cd test; ->> runtests .; -``` From 9393df313ca88506a0260c286e1cc2f5ac525aff Mon Sep 17 00:00:00 2001 From: Fiona La Date: Wed, 9 Feb 2022 16:11:24 -0500 Subject: [PATCH 4/8] Fill out basic steps required to set up MATLAB Interface to Arrow --- matlab/README.md | 57 ++++++++++++++++++++++++++++++------------------ 1 file changed, 36 insertions(+), 21 deletions(-) diff --git a/matlab/README.md b/matlab/README.md index a632fb99dcc..3d09faf5dba 100644 --- a/matlab/README.md +++ b/matlab/README.md @@ -25,31 +25,59 @@ This is a very early stage MATLAB interface to the Apache Arrow C++ libraries. The current code only supports reading/writing numeric types from/to Feather v1 files. -## Build +## Prerequisites -## Install +## Setup +To set up a local working copy of the source code, start by cloning the repository: +```bash +$ git clone https://github.com/apache/arrow.git +``` + +Change the working directory to the `matlab` subdirectory: +```bash +$ cd arrow/matlab +``` -After building the MATLAB Interface to Arrow, install the library by running the following command: +## Build +To build the project: +```bash +$ cmake -S . -B build +$ cmake --build build --config Release +``` -``` CMake -cmake --build build --config Release --target install +## Install +To install the MATLAB interface to the default software location (e.g. `/usr/local` or `C:\Program Files`): +```bash +$ cmake --build build --config Release --target install ``` -The installation process includes +As part of the install step, the install directory is added to the [MATLAB Search Path](https://mathworks.com/help/matlab/matlab_env/what-is-the-matlab-search-path.html). -Once installed, the interface's source files and libraries are relocatable, on all platforms. If the interface is relocated, then the user must manually add the new location to the [MATLAB Search Path](https://uk.mathworks.com/help/matlab/matlab_env/what-is-the-matlab-search-path.html). +Note: this step may fail if the current user is lacking the necessary filesystem permissions. Please see Troubleshooting for more information. ## Test +There are two kinds of tests for the MATLAB Interface to Arrow: C++ and MATLAB. ### C++ +To enable the C++ tests, the `MATLAB_BUILD_TESTS` flag must enabled at build time: +```bash +$ cmake -S . -B build -D MATLAB_BUILD_TESTS=ON +$ cmake --build build --config Release +``` -### MATLAB +After building with the `MATLAB_BUILD_TESTS` flag enabled, the C++ tests can be run using [`ctest`](https://cmake.org/cmake/help/v3.22/manual/ctest.1.html): +```bash +$ ctest --test-dir build +``` +### MATLAB +To run the MATLAB tests, start MATLAB in the `arrow/matlab` directory and call the [`runtests`](https://mathworks.com/help/matlab/ref/runtests.html) command on the `test` directory: ``` matlab >> runtests test; ``` ## Usage +Included below are some example code snippets that illustrate how to use the MATLAB Interface To Arrow. ### Write a MATLAB table to a Feather v1 file @@ -66,16 +94,3 @@ Once installed, the interface's source files and libraries are relocatable, on a >> t = featherread(filename); ``` -## Troubleshooting - -### Non-standard MATLAB and Arrow installations - -To specify a non-standard MATLAB install location, use the Matlab_ROOT_DIR CMake flag: - - cmake .. -DMatlab_ROOT_DIR=/ - -To specify a non-standard Arrow install location, use the ARROW_HOME CMake flag: - - cmake .. -DARROW_HOME=/ - - From 3e4394a32ecb7e767a83de130f5b8e84b56a0c57 Mon Sep 17 00:00:00 2001 From: Kevin Gurney Date: Wed, 9 Feb 2022 16:53:26 -0500 Subject: [PATCH 5/8] 1. Clean up formatting. 2. Add softare Prerequisites. 3. Tweak wording. --- matlab/README.md | 53 +++++++++++++++++++++++++++++++++--------------- 1 file changed, 37 insertions(+), 16 deletions(-) diff --git a/matlab/README.md b/matlab/README.md index 3d09faf5dba..045bec674f3 100644 --- a/matlab/README.md +++ b/matlab/README.md @@ -27,57 +27,78 @@ The current code only supports reading/writing numeric types from/to Feather v1 ## Prerequisites +To build the MATLAB Interface to Apache Arrow from source, the following software must be installed on the target machine: + +1. [MATLAB](https://www.mathworks.com/products/get-matlab.html) +2. [CMake](https://cmake.org/cmake/help/latest/) +3. C++ compiler which supports C++11 (e.g. [`gcc`](https://gcc.gnu.org/) on Linux, [`Xcode`](https://developer.apple.com/xcode/) on macOS, or [`Visual Studio`](https://visualstudio.microsoft.com/) on Windows) +4. [Git](https://git-scm.com/) + ## Setup -To set up a local working copy of the source code, start by cloning the repository: + +To set up a local working copy of the source code, start by cloning the [`apache/arrow`](https://github.com/apache/arrow) GitHub repository using [Git](https://git-scm.com/): + ```bash $ git clone https://github.com/apache/arrow.git ``` -Change the working directory to the `matlab` subdirectory: +After cloning, change the working directory to the `matlab` subdirectory: + ```bash $ cd arrow/matlab ``` ## Build -To build the project: + +To build the MATLAB interface, use [CMake](https://cmake.org/cmake/help/latest/): + ```bash $ cmake -S . -B build $ cmake --build build --config Release ``` ## Install -To install the MATLAB interface to the default software location (e.g. `/usr/local` or `C:\Program Files`): + +To install the MATLAB interface to the default software installation location for the target machine (e.g. `/usr/local` on Linux or `C:\Program Files` on Windows), pass the `--taget install` flag to CMake. + ```bash $ cmake --build build --config Release --target install ``` -As part of the install step, the install directory is added to the [MATLAB Search Path](https://mathworks.com/help/matlab/matlab_env/what-is-the-matlab-search-path.html). +As part of the install step, the installation directory is added to the [MATLAB Search Path](https://mathworks.com/help/matlab/matlab_env/what-is-the-matlab-search-path.html). -Note: this step may fail if the current user is lacking the necessary filesystem permissions. Please see Troubleshooting for more information. +**Note**: This step may fail if the current user is lacking necessary filesystem permissions. If the install step fails, the installation directory can be manually added to the MATLAB Search Path using the [`addpath`](https://www.mathworks.com/help/matlab/ref/addpath.html) command. ## Test -There are two kinds of tests for the MATLAB Interface to Arrow: C++ and MATLAB. + +There are two kinds of tests for the MATLAB Interface: MATLAB and C++. + +### MATLAB + +To run the MATLAB tests, start MATLAB in the `arrow/matlab` directory and call the [`runtests`](https://mathworks.com/help/matlab/ref/runtests.html) command on the `test` directory: + +``` matlab +>> runtests test; +``` ### C++ -To enable the C++ tests, the `MATLAB_BUILD_TESTS` flag must enabled at build time: + +To enable the C++ tests, set the `MATLAB_BUILD_TESTS` to `ON` at build time: + ```bash $ cmake -S . -B build -D MATLAB_BUILD_TESTS=ON $ cmake --build build --config Release ``` -After building with the `MATLAB_BUILD_TESTS` flag enabled, the C++ tests can be run using [`ctest`](https://cmake.org/cmake/help/v3.22/manual/ctest.1.html): +After building with the `MATLAB_BUILD_TESTS` flag enabled, the C++ tests can be run using [CTest](https://cmake.org/cmake/help/latest/manual/ctest.1.html): + ```bash $ ctest --test-dir build ``` -### MATLAB -To run the MATLAB tests, start MATLAB in the `arrow/matlab` directory and call the [`runtests`](https://mathworks.com/help/matlab/ref/runtests.html) command on the `test` directory: -``` matlab ->> runtests test; -``` - ## Usage -Included below are some example code snippets that illustrate how to use the MATLAB Interface To Arrow. + +Included below are some example code snippets that illustrate how to use the MATLAB interface. ### Write a MATLAB table to a Feather v1 file From 3062bf18ebd164e5418d36edcc6f9bed9203171d Mon Sep 17 00:00:00 2001 From: Kevin Gurney <5904145+kevingurney@users.noreply.github.com> Date: Wed, 9 Feb 2022 20:29:24 -0500 Subject: [PATCH 6/8] Apply suggestions from code review Use "console" instead of "bash" as the language for syntax highlighting inside of fenced code blocks containing command line operations. Co-authored-by: Sutou Kouhei --- matlab/README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/matlab/README.md b/matlab/README.md index 045bec674f3..da0ce2b2ea3 100644 --- a/matlab/README.md +++ b/matlab/README.md @@ -38,13 +38,13 @@ To build the MATLAB Interface to Apache Arrow from source, the following softwar To set up a local working copy of the source code, start by cloning the [`apache/arrow`](https://github.com/apache/arrow) GitHub repository using [Git](https://git-scm.com/): -```bash +```console $ git clone https://github.com/apache/arrow.git ``` After cloning, change the working directory to the `matlab` subdirectory: -```bash +```console $ cd arrow/matlab ``` @@ -52,7 +52,7 @@ $ cd arrow/matlab To build the MATLAB interface, use [CMake](https://cmake.org/cmake/help/latest/): -```bash +```console $ cmake -S . -B build $ cmake --build build --config Release ``` @@ -61,7 +61,7 @@ $ cmake --build build --config Release To install the MATLAB interface to the default software installation location for the target machine (e.g. `/usr/local` on Linux or `C:\Program Files` on Windows), pass the `--taget install` flag to CMake. -```bash +```console $ cmake --build build --config Release --target install ``` @@ -85,14 +85,14 @@ To run the MATLAB tests, start MATLAB in the `arrow/matlab` directory and call t To enable the C++ tests, set the `MATLAB_BUILD_TESTS` to `ON` at build time: -```bash +```console $ cmake -S . -B build -D MATLAB_BUILD_TESTS=ON $ cmake --build build --config Release ``` After building with the `MATLAB_BUILD_TESTS` flag enabled, the C++ tests can be run using [CTest](https://cmake.org/cmake/help/latest/manual/ctest.1.html): -```bash +```console $ ctest --test-dir build ``` From 5f50126e4840f6efe5b008fb8b65b3f47d5b4cf7 Mon Sep 17 00:00:00 2001 From: Kevin Gurney <5904145+kevingurney@users.noreply.github.com> Date: Wed, 9 Feb 2022 20:33:42 -0500 Subject: [PATCH 7/8] Fix typo for CMake "--target" flag. --- matlab/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/matlab/README.md b/matlab/README.md index da0ce2b2ea3..81ab0e5eca1 100644 --- a/matlab/README.md +++ b/matlab/README.md @@ -59,7 +59,7 @@ $ cmake --build build --config Release ## Install -To install the MATLAB interface to the default software installation location for the target machine (e.g. `/usr/local` on Linux or `C:\Program Files` on Windows), pass the `--taget install` flag to CMake. +To install the MATLAB interface to the default software installation location for the target machine (e.g. `/usr/local` on Linux or `C:\Program Files` on Windows), pass the `--target install` flag to CMake. ```console $ cmake --build build --config Release --target install From 69a2ac720e278e77954be562100e7b93802600b4 Mon Sep 17 00:00:00 2001 From: Kevin Gurney <5904145+kevingurney@users.noreply.github.com> Date: Wed, 9 Feb 2022 20:35:35 -0500 Subject: [PATCH 8/8] Add the word "flag" after `MATLAB_BUILD_TESTS`. --- matlab/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/matlab/README.md b/matlab/README.md index 81ab0e5eca1..6f99fc4f5f9 100644 --- a/matlab/README.md +++ b/matlab/README.md @@ -83,7 +83,7 @@ To run the MATLAB tests, start MATLAB in the `arrow/matlab` directory and call t ### C++ -To enable the C++ tests, set the `MATLAB_BUILD_TESTS` to `ON` at build time: +To enable the C++ tests, set the `MATLAB_BUILD_TESTS` flag to `ON` at build time: ```console $ cmake -S . -B build -D MATLAB_BUILD_TESTS=ON