diff --git a/Changes.txt b/Changes.txt index 67d32b9c..d4d1e45e 100644 --- a/Changes.txt +++ b/Changes.txt @@ -11,7 +11,7 @@ # 0.3.9 July 2 2016 -- Added support for MinGW, MinGW-w64, Gygwin, MSYS and MSYS2. +- Added support for MinGW, MinGW-w64, Cygwin, MSYS and MSYS2. See @ref gsg_ming. diff --git a/docs/src/getting_started.dox b/docs/src/getting_started.dox index c45b6bf9..5f5a213e 100644 --- a/docs/src/getting_started.dox +++ b/docs/src/getting_started.dox @@ -240,6 +240,26 @@ libxlsxwriter example programs by copying the code from one of the `libxlsxwriter\example\*.c` programs. +@subsection gsg_tmpdir Specifying a TEMP directory for libxlsxwriter + +The libxlsxwriter library creates temporary files in the system `TEMP` +directory during assembly of an xlsx file. On Windows this directory may not +be writeable by a libxlsxwriter application (although it will try several +`TEMP` locations before returning an error). To work around this you can set +the `tmpdir` parameter of the #lxw_workbook_options struct and pass it to +`workbook_new_opt()`: + +@code + lxw_workbook_options options = {.constant_memory = LXW_FALSE, + .tmpdir = "C:\\Temp"}; + + lxw_workbook *workbook = workbook_new_opt("filename.xlsx", &options); +@endcode + +This can also be used on Unix systems where the `TEMP` directory isn't +writeable. + + @section gsg_ming Installation on Windows using Mingw-w64 and MSYS2 The libxlsxwriter library can also be compiled on Windows using the @@ -267,17 +287,11 @@ link against the zlib library using `-lz`: gcc myexcel.c -o myexcel -lxlsxwriter -lz -It is also possible to use the older [MinGW and MSYS](http://mingw.org) and -with [Cygwin](https://cygwin.com). Libxlsxwriter has been confirmed to compile -and work in all of these environments. +It is also possible to use [Cygwin](https://cygwin.com) and the older [MinGW +and MSYS](http://mingw.org). Libxlsxwriter has been confirmed to compile and +work in all of these environments. -@note The libxlsxwriter library uses files in the system TEMP directory during -assembly of a xlsx file. On Windows this directory may not be writeable by a -libxlsxwriter application. To work around this you can make the Windows TEMP -directory writeable or if you are using MSYS/MSYS2 you can change the `/tmp` -directory using the system fstab file. Or alternatively you can define your -own TEMP directory in libxlsxwriter using the `USE_TMPFILE2` workaround in -`src/utility.c` +See also @ref gsg_tmpdir. @section gsg_next Next steps diff --git a/examples/constant_memory.c b/examples/constant_memory.c index 2e743912..313a3b6f 100644 --- a/examples/constant_memory.c +++ b/examples/constant_memory.c @@ -16,7 +16,8 @@ int main() { lxw_col_t max_col = 50; /* Set the worksheet options. */ - lxw_workbook_options options = {LXW_TRUE, NULL}; + lxw_workbook_options options = {.constant_memory = LXW_TRUE, + .tmpdir = NULL}; /* Create a new workbook with options. */ lxw_workbook *workbook = workbook_new_opt("constant_memory.xlsx", &options); diff --git a/include/xlsxwriter/common.h b/include/xlsxwriter/common.h index bf662099..54ce7115 100644 --- a/include/xlsxwriter/common.h +++ b/include/xlsxwriter/common.h @@ -233,7 +233,7 @@ enum lxw_custom_property_types { #define lxw_snprintf __builtin_snprintf #endif -/* Define a snprintf for MCVC 2010. */ +/* Define a snprintf for MSVC 2010. */ #if defined(_MSC_VER) && _MSC_VER < 1900 #include diff --git a/include/xlsxwriter/workbook.h b/include/xlsxwriter/workbook.h index d276108f..cbcbdc2b 100644 --- a/include/xlsxwriter/workbook.h +++ b/include/xlsxwriter/workbook.h @@ -171,7 +171,7 @@ typedef struct lxw_doc_properties { * - `constant_memory`: Reduces the amount of data stored in memory so that * large files can be written efficiently. * - * Note, in this mode a row of data is written and then discarded when a + * @note In this mode a row of data is written and then discarded when a * cell in a new row is added via one of the `worksheet_write_*()` * methods. Therefore, once this option is active, data should be written in * sequential row order. For this reason the `worksheet_merge_range()` @@ -187,7 +187,7 @@ typedef struct lxw_workbook_options { /** Optimize the workbook to use constant memory for worksheets */ uint8_t constant_memory; - /** Directory to use for temporary files used by libxlsxwriter. */ + /** Directory to use for the temporary files created by libxlsxwriter. */ char *tmpdir; } lxw_workbook_options; @@ -273,15 +273,28 @@ lxw_workbook *workbook_new(const char *filename); * additional options to be set. * * @code - * lxw_workbook_options options = {.constant_memory = 1}; + * lxw_workbook_options options = {.constant_memory = 1, + * .tmpdir = "C:\\Temp"}; * * lxw_workbook *workbook = workbook_new_opt("filename.xlsx", &options); * @endcode * - * Note, in this mode a row of data is written and then discarded when a cell - * in a new row is added via one of the worksheet `worksheet_write_*()` - * methods. Therefore, once this mode is active, data should be written in - * sequential row order. + * The options that can be set via #lxw_workbook_options are: + * + * - `constant_memory`: Reduces the amount of data stored in memory so that + * large files can be written efficiently. + * + * @note In this mode a row of data is written and then discarded when a + * cell in a new row is added via one of the `worksheet_write_*()` + * methods. Therefore, once this option is active, data should be written in + * sequential row order. For this reason the `worksheet_merge_range()` + * doesn't work in this mode. See also @ref ww_mem_constant. + * + * - `tmpdir`: libxlsxwriter stores workbook data in temporary files prior + * to assembling the final XLSX file. The temporary files are created in the + * system's temp directory. If the default temporary directory isn't + * accessible to your application, or doesn't contain enough space, you can + * specify an alternative location using the `tempdir` option.* * * See @ref working_with_memory for more details. *