From 342926356049dbc6a5ac5a9427e2877c4196738b Mon Sep 17 00:00:00 2001 From: Brad House Date: Wed, 5 Jun 2024 17:39:22 -0400 Subject: [PATCH] update base README --- CONTRIBUTING.md | 10 ++---- DEVELOPER-NOTES.md | 47 +++++++++++++++++++++++++++ Makefile.am | 2 +- README.md | 80 ++++++++++++++++++++++++---------------------- 4 files changed, 92 insertions(+), 47 deletions(-) create mode 100644 DEVELOPER-NOTES.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a3b5194c..a984e430 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,12 +4,6 @@ Contributing to c-ares To contribute patches to c-ares, please generate a GitHub pull request and follow these guidelines: - - Check that the Travis builds are green for your pull request. + - Check that the CI/CD builds are green for your pull request. - Please update the test suite to add a test case for any new functionality. - - Build the library with `./configure --enable-debug --enable-maintainer-mode` and - ensure there are no new warnings. - -To improve the chances of the c-ares maintainers responding to your request: - - - Also send an email to the mailing list at `c-ares@lists.haxx.se` describing your change. - - To follow any associated discussion, please subscribe to the [mailing list](http://lists.haxx.se/listinfo/c-ares). + - Build the library on your own machine and ensure there are no new warnings. diff --git a/DEVELOPER-NOTES.md b/DEVELOPER-NOTES.md new file mode 100644 index 00000000..c8a2f0b7 --- /dev/null +++ b/DEVELOPER-NOTES.md @@ -0,0 +1,47 @@ +Developer Notes +=============== + +* The distributed `ares_build.h` in the official release tarballs is only + intended to be used on systems which can also not run the also distributed + `configure` or `CMake` scripts. It is generated as a copy of + `ares_build.h.dist` as can be seen in the code repository. + +* If you check out from git on a non-`configure` or `CMake` platform, you must run + the appropriate `buildconf*` script to set up `ares_build.h` and other local + files before being able to compile the library. There are pre-made makefiles + for a subset of such systems such as Watcom, NMake, and MinGW Makefiles. + +* On systems capable of running the `configure` or `CMake` scripts, the process + will overwrite the distributed `ares_build.h` file with one that is suitable + and specific to the library being configured and built, this new file is + generated from the `ares_build.h.in` and `ares_build.h.cmake` template files. + +* If you intend to distribute an already compiled c-ares library you **MUST** + also distribute along with it the generated `ares_build.h` which has been + used to compile it. Otherwise, the library will be of no use for the users of + the library that you have built. It is **your** responsibility to provide this + file. No one at the c-ares project can know how you have built the library. + The generated file includes platform and configuration dependent info, + and must not be modified by anyone. + +* We support both the AutoTools `configure` based build system as well as the + `CMake` build system. Any new code changes must work with both. + +* The files that get compiled and are present in the distribution are referenced + in the `Makefile.inc` in the current directory. This file gets included in + every build system supported by c-ares so that the list of files doesn't need + to be maintained per build system. Don't forget to reference new header files + otherwise they won't be included in the official release tarballs. + +* We cannot assume anything else but very basic C89 compiler features being + present. The lone exception is the requirement for 64bit integers which is + not a requirement for C89 compilers to support. Please do not use any extended + features released by later standards. + +* Newlines must remain unix-style for older compilers' sake. + +* Comments must be written in the old-style `/* unnested C-fashion */` + +* Try to keep line lengths below 80 columns and formatted as the existing code. + There is a `.clang-format` in the repository that can be used to run the + automated code formatter as such: `clang-format -i */*.c */*.h */*/*.c */*/*.h` diff --git a/Makefile.am b/Makefile.am index a545f8e3..22b02cd8 100644 --- a/Makefile.am +++ b/Makefile.am @@ -30,7 +30,7 @@ EXTRA_DIST = AUTHORS CHANGES README.cares $(man_MANS) RELEASE-NOTES.md \ c-ares-config.cmake.in libcares.pc.cmake libcares.pc.in buildconf get_ver.awk \ maketgz TODO README.msvc $(MSVCFILES) INSTALL.md README.md LICENSE.md \ CMakeLists.txt Makefile.dj Makefile.m32 Makefile.netware Makefile.msvc \ - Makefile.Watcom AUTHORS CONTRIBUTING.md SECURITY.md TODO \ + Makefile.Watcom AUTHORS CONTRIBUTING.md SECURITY.md DEVELOPER-NOTES.md TODO \ cmake/EnableWarnings.cmake CLEANFILES = $(PDFPAGES) $(HTMLPAGES) diff --git a/README.md b/README.md index c5bc1270..faf26eab 100644 --- a/README.md +++ b/README.md @@ -8,58 +8,62 @@ [![Bugs](https://sonarcloud.io/api/project_badges/measure?project=c-ares_c-ares&metric=bugs)](https://sonarcloud.io/summary/new_code?id=c-ares_c-ares) [![Coverity Scan Status](https://scan.coverity.com/projects/c-ares/badge.svg)](https://scan.coverity.com/projects/c-ares) -This is c-ares, an asynchronous resolver library. It is intended for +## Overview +[c-ares](https://c-ares.org) is a modern DNS (stub) resolver library, written in +C. It provides interfaces for asynchronous queries while trying to abstract the +intricacies of the underlying DNS protocol. It was originally intended for applications which need to perform DNS queries without blocking, or need to -perform multiple DNS queries in parallel. The primary examples of such -applications are servers which communicate with multiple clients and programs -with graphical user interfaces. +perform multiple DNS queries in parallel. -The full source code is available in the ['c-ares' release archives](https://c-ares.org/download/), -and in a git repository: https://github.com/c-ares/c-ares. See the -[INSTALL.md](INSTALL.md) file for build information. +One of the goals of c-ares is to be a better DNS resolver than is provided by +your system, regardless of which system you use. We recommend using +the c-ares library in all network applications even if the initial goal of +asynchronous resolution is not necessary to your application. -If you find bugs, correct flaws, have questions or have comments in general in -regard to c-ares (or by all means the original ares too), get in touch with us -on the c-ares mailing list: https://lists.haxx.se/listinfo/c-ares +c-ares will build with any C89 compiler, is [MIT licensed](LICENSE.md), +which makes it suitable for both free and commercial software. c-ares runs on +Linux, FreeBSD, OpenBSD, MacOS, Solaris, AIX, Windows, Android, iOS and many +more operating systems. -c-ares is distributed under the MIT license. +c-ares has a strong focus on security, implementing safe parsers and data +builders used throughout the code, thus avoiding many of the common pitfalls +of other C libraries. Through automated testing with our extensive testing +framework, c-ares is constantly validated with a range of static and dynamic +analyzers, as well as being constantly fuzzed by [OSS Fuzz](https://github.com/google/oss-fuzz). -You'll find all c-ares details and news here: - https://c-ares.org/ +While c-ares has been around for over 20 years, it has been actively maintained +both in regards to the latest DNS RFCs as well as updated to follow the latest +best practices in regards to C coding standards. +This is c-ares, an asynchronous resolver library. It is intended for +applications which need to perform DNS queries without blocking, or need to +perform multiple DNS queries in parallel. The primary examples of such +applications are servers which communicate with multiple clients and programs +with graphical user interfaces. -## Notes for c-ares hackers +## Code -* The distributed `ares_build.h` file is only intended to be used on systems - which can not run the also distributed configure script. +The full source code and revision history is available in our +[GitHub repository](https://github.com/c-ares/c-ares). Our signed releases +are available in the ['c-ares' release archives](https://c-ares.org/download/). -* The distributed `ares_build.h` file is generated as a copy of `ares_build.h.dist` - when the c-ares source code distribution archive file is originally created. -* If you check out from git on a non-configure platform, you must run the - appropriate `buildconf*` script to set up `ares_build.h` and other local files - before being able to compile the library. +See the [INSTALL.md](INSTALL.md) file for build information. -* On systems capable of running the `configure` script, the `configure` process - will overwrite the distributed `ares_build.h` file with one that is suitable - and specific to the library being configured and built, this new file is - generated from the `ares_build.h.in` template file. +## Communication -* If you intend to distribute an already compiled c-ares library you **MUST** - also distribute along with it the generated `ares_build.h` which has been - used to compile it. Otherwise, the library will be of no use for the users of - the library that you have built. It is **your** responsibility to provide this - file. No one at the c-ares project can know how you have built the library. +**Issues** and **Feature Requests** should be reported to our +[GitHub Issues](https://github.com/c-ares/c-ares/issues) page. -* File `ares_build.h` includes platform and configuration dependent info, - and must not be modified by anyone. Configure script generates it for you. +**Discussions** around c-ares and its use, are held on +[GitHub Discussions](https://github.com/c-ares/c-ares/discussions/categories/q-a) +or the [Mailing List](https://lists.haxx.se/mailman/listinfo/c-ares). Mailing +List archive [here](https://lists.haxx.se/pipermail/c-ares/). +Please, do not mail volunteers privately about c-ares. -* We cannot assume anything else but very basic compiler features being - present. While c-ares requires an ANSI C compiler to build, some of the - earlier ANSI compilers clearly can't deal with some preprocessor operators. +**Security vulnerabilities** are treated according to our +[Security Procedure](SECURITY.md), please email c-ares-security at + haxx.se if you suspect one. -* Newlines must remain unix-style for older compilers' sake. -* Comments must be written in the old-style /* unnested C-fashion */ -* Try to keep line lengths below 80 columns.