Skip to content

Commit a279b7e

Browse files
asmaloneyasmaloney
committed
{doc} Update README & CONTRIBUTING
[skip ci]
1 parent 937fa3a commit a279b7e

File tree

2 files changed

+102
-17
lines changed

2 files changed

+102
-17
lines changed

‎CONTRIBUTING.md

+22-6
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,37 @@
11
# How To Contribute
22

3-
## Code Changes
3+
These are some of the things you can do to contribute to the project:
4+
5+
## ✍ Write About The Project
6+
7+
If you find the project useful, spread the word! Articles, mastodon posts, tweets, blog posts, instagram photos - whatever you're into. Please include a referral back to the repository page: https://github.com/asmaloney/libE57Format
8+
9+
## ⭐️ Add a Star
10+
11+
If you found this project useful, please consider starring it! It helps me gauge how useful this project is.
12+
13+
## ☝ Raise Issues
14+
15+
If you run into something which doesn't work as expected, raising [an issue](https://github.com/asmaloney/libE57Format/issues) with all the relevant information to reproduce it would be helpful.
16+
17+
## 🐞 Bug Fixes & 🧪 New Things
418

519
I am happy to review any [pull requests](https://github.com/asmaloney/libE57Format/pulls). Please keep them as short as possible. Each pull request should be atomic and only address one issue. This helps with the review process.
620

21+
Note that I will not accept everything, but I welcome discussion. If you are proposing a big change, please raise it as [an issue](https://github.com/asmaloney/libE57Format/issues) first for discussion.
22+
723
### Formatting
824

9-
This project uses [clang-format](https://clang.llvm.org/docs/ClangFormat.html) to format the code. There is a cmake target (_format_) - which runs _clang-format_ on the source files. After changes have been made, and before you submit your pull request, please run the following:
25+
This project uses [clang-format](https://clang.llvm.org/docs/ClangFormat.html) to format the code. There is a cmake target (_e57-clang-format_) - which runs _clang-format_ on the source files. After changes have been made, and before you submit your pull request, please run the following:
1026

1127
```sh
12-
cmake --build . --target format
28+
cmake --build . --target e57-clang-format
1329
```
1430

15-
## Documentation
31+
## 📖 Documentation
1632

1733
The [documentation](https://github.com/asmaloney/libE57Format) is a bit old and could use some lovin'. You can submit changes over in the [libE57Format-docs](https://github.com/asmaloney/libE57Format-docs) repository.
1834

19-
## Financial
35+
## 💰 Financial
2036

21-
If you would like to support the project financially, you can use the **Sponsor** button at the top of the [libE57Format](https://github.com/asmaloney/libE57Format) repository page.
37+
Given that I'm an independent developer without funding, financial support is always appreciated. If you would like to support the project financially (especially if you sell a product which uses this library), you can use the [sponsors page](https://github.com/sponsors/asmaloney) for one-off or recurring support. Thank you!

‎README.md

+80-11
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
[![GitHub release (latest by date)](https://img.shields.io/github/v/release/asmaloney/libE57Format)](https://github.com/asmaloney/libE57Format/releases/latest) [![Docs](https://img.shields.io/badge/docs-online-orange)](https://asmaloney.github.io/libE57Format-docs/) [![GitHub](https://img.shields.io/github/license/asmaloney/libE57Format)](LICENSE) ![Build](https://github.com/asmaloney/libE57Format/actions/workflows/build.yml/badge.svg)
44

5-
A library to provide read & write support for the E57 file format.
5+
libE57Format is a library which provides read & write support for the E57 file format.
66

77
This is a fork of [E57RefImpl](https://sourceforge.net/projects/e57-3d-imgfmt/) v1.1.332. The original source is from [E57RefImpl 1.1.332](https://sourceforge.net/projects/e57-3d-imgfmt/files/E57Refimpl-src/) and then everything was stripped out except the main implementation for reading and writing E57.
88

@@ -22,13 +22,59 @@ I plan to let 3.0 sit in the master branch until the end of 2022. If I don't hea
2222

2323
The doxygen-generated documentation may be [found here](https://asmaloney.github.io/libE57Format-docs/). These docs are generated and saved in the [libE57Format-docs](https://github.com/asmaloney/libE57Format-docs) repo.
2424

25-
## Contributing
25+
## Build, Install, & Test
2626

27-
Please see [CONTRIBUTING](CONTRIBUTING.md).
27+
Here's how you build & install a release version with the defaults:
28+
29+
```
30+
$ cmake -B E57-build -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=E57-install libE57Format
31+
$ cmake --build E57-build --parallel
32+
$ cmake --install E57-build
33+
```
34+
35+
If it can't find the xerces-c library, you can set [CMAKE_PREFIX_PATH](https://cmake.org/cmake/help/latest/variable/CMAKE_PREFIX_PATH.html) to point at it.
36+
37+
```
38+
$ cmake -B E57-build \
39+
-DCMAKE_BUILD_TYPE=Release \
40+
-DCMAKE_INSTALL_PREFIX=E57-install \
41+
-DCMAKE_PREFIX_PATH=/path/to/xerces-c \
42+
libE57Format
43+
```
44+
45+
Once the library is built, you can run the tests like this:
46+
47+
```
48+
$ cd E57-build
49+
$ ./test/testE57
50+
[==========] Running 36 tests from 8 test suites.
51+
[----------] Global test environment set-up.
52+
[----------] 1 test from TestData
53+
[ RUN ] TestData.RepoExists
54+
...
55+
```
56+
57+
### Dependencies
58+
59+
- [ccache](https://ccache.dev/) (optional): speed up rebuilds using caching
60+
- [clang-format](https://clang.llvm.org/docs/ClangFormat.html): for code formatting
61+
- [Xerces-C++](https://xerces.apache.org/xerces-c/): a validating XML parser
62+
63+
#### Installing Dependencies On Linux (Ubuntu)
64+
65+
```sh
66+
$ sudo apt install libxerces-c-dev clang-format
67+
```
68+
69+
#### Installing Dependencies On macOS (homebrew)
70+
71+
```sh
72+
$ brew install ccache clang-format xerces-c
73+
```
2874

2975
## Why Fork?
3076

31-
The E57RefImpl code hasn't been touched in years and I wanted to make changes to compile this library with macOS. Forking it gives me a bit more freedom to update the code and make changes as required.
77+
The E57RefImpl code hadn't been touched in years and I wanted to make changes to compile it with macOS. Forking it gave me a bit more freedom to update the code and make changes as required.
3278

3379
I changed the name of the project so that it is not confused with the **E57RefImpl** project.
3480

@@ -46,21 +92,44 @@ This `Simple API` has evolved since this original port to fix some problems and
4692

4793
[Ryan Baumann](https://github.com/ryanfb) has updated the `e57unpack` and `e57validate` tools to work with **libE57Format**. You can find them in the [e57tools](https://github.com/ryanfb/e57tools) repo.
4894

49-
## Building
95+
## How To Contribute
5096

51-
`$ mkdir -p build && cmake -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build --parallel`
97+
These are some of the things you can do to contribute to the project:
5298

53-
### Dependencies
99+
### ✍ Write About The Project
54100

55-
- [Xerces-C++](https://xerces.apache.org/xerces-c/) validating XML parser for building libE57Format
56-
- [clang-format](https://clang.llvm.org/docs/ClangFormat.html) for C++ formatting
101+
If you find the project useful, spread the word! Articles, mastodon posts, tweets, blog posts, instagram photos - whatever you're into. Please include a referral back to the repository page: https://github.com/asmaloney/libE57Format
57102

58-
#### Installing Dependencies On Linux (Ubuntu)
103+
### ⭐️ Add a Star
104+
105+
If you found this project useful, please consider starring it! It helps me gauge how useful this project is.
106+
107+
### ☝ Raise Issues
108+
109+
If you run into something which doesn't work as expected, raising [an issue](https://github.com/asmaloney/libE57Format/issues) with all the relevant information to reproduce it would be helpful.
110+
111+
### 🐞 Bug Fixes & 🧪 New Things
112+
113+
I am happy to review any [pull requests](https://github.com/asmaloney/libE57Format/pulls). Please keep them as short as possible. Each pull request should be atomic and only address one issue. This helps with the review process.
114+
115+
Note that I will not accept everything, but I welcome discussion. If you are proposing a big change, please raise it as [an issue](https://github.com/asmaloney/libE57Format/issues) first for discussion.
116+
117+
#### Formatting
118+
119+
This project uses [clang-format](https://clang.llvm.org/docs/ClangFormat.html) to format the code. There is a cmake target (_e57-clang-format_) - which runs _clang-format_ on the source files. After changes have been made, and before you submit your pull request, please run the following:
59120

60121
```sh
61-
$ sudo apt install libxerces-c-dev clang-format
122+
cmake --build . --target e57-clang-format
62123
```
63124

125+
### 📖 Documentation
126+
127+
The [documentation](https://github.com/asmaloney/libE57Format) is a bit old and could use some lovin'. You can submit changes over in the [libE57Format-docs](https://github.com/asmaloney/libE57Format-docs) repository.
128+
129+
### 💰 Financial
130+
131+
Given that I'm an independent developer without funding, financial support is always appreciated. If you would like to support the project financially (especially if you sell a product which uses this library), you can use the [sponsors page](https://github.com/sponsors/asmaloney) for one-off or recurring support. Thank you!
132+
64133
## License
65134

66135
This project as a whole is licensed under the [**BSL-1.0**](https://opensource.org/licenses/BSL-1.0) license - see the [LICENSE](LICENSE.md) file for details.

0 commit comments

Comments
 (0)