I don't think we can disable it by default without bumping the SONAME number. This would affect a lot of users.

I don't think we can disable it by default without bumping the SONAME number.

Technically speaking, yes we can. The API is still there but returns CURL_FORMADD_DISABLED.

Now, for users needing it, they still can build with --enable-form-api. At least this will force them to take conscience it's deprecated for 5 years.

Considering #9116, it seems obvious that deprecation in the documentation only is not enough: the solution implemented in this PR may seem to come abrubtly because you just read the PR. If it had been submitted (with forms enabled) together with the mime api introduction, it would appear more natural to disable it by default now.

After all, we already suppressed (not only disabled) features like Kerberos4 and char code conversion. They were less used, I admit.

That said, we can still have the form api enabled by default for some months or until a big change (version 8?), but I don't feel stretching the delay for disabling it by default will help.

A change in SONAME, although not needed, will emphasize a theoric incompatibility that can even exist between 2 different builds today (using --disable-mime).

Technically speaking, yes we can. The API is still there but returns CURL_FORMADD_DISABLED.

I disagree. SONAME implies ABI compatibility, and ABI includes behavior.

This is functionality that is still very much in use by people. Having the option there is good, but disabling it by default is not.

After all, we already suppressed (not only disabled) features like Kerberos4 and char code conversion. They were less used, I admit.

It becomes an exercise in philosophy at times: when nobody uses a feature then it actually doesn't change behavior when it is removed. A tough balance and call to make.

A change in SONAME, although not needed, will emphasize a theoretic incompatibility that can even exist between 2 different builds today (using --disable-mime).

A user can destroy the compatibility in many ways, but we maintain it for the same build options, and in particular when you do not disable features in a new way.

Updated to enable by default.
A configure time warning message is issued when enabled.

I don't quite understand the warning. What is that going to do for users? The form API will be provided for as long as we remain using this SONAME, which very well may be another decade or two.

I don't quite understand the warning. What is that going to do for users?

This PR is not only another nth + 1 disabling conditional, but a push for users to use mime instead of form api by emphasizing deprecation.
I'm sure a lot of coders are'nt even aware that form api is deprecated and continue to develop around it. As we have seen, there had even been a request to upgrade it!
I don't want to break existing or binary applications, but IMO, if something has to be changed in an existing formadd calling sequence, this is time to migrate it to the mime api.
The goal of the warning message is to raise awareness of this deprecation by "advertising" it a little bit more than in documentation only, at least for those who build libcurl themselves.
I tried to make some kind of symetry with experimental features, that do issue a message when enabled: they are emerging, deprecated ones are diluting,

I think the doc warning is enough. We could put it in bold,

diff --git a/docs/libcurl/curl_formadd.3 b/docs/libcurl/curl_formadd.3
index 92135bf..04e10b3 100644
--- a/docs/libcurl/curl_formadd.3
+++ b/docs/libcurl/curl_formadd.3
@@ -32,7 +32,7 @@ CURLFORMcode curl_formadd(struct curl_httppost **firstitem,
                           struct curl_httppost **lastitem, ...);
 .fi
 .SH DESCRIPTION
-This function is deprecated. Do not use. See \fIcurl_mime_init(3)\fP instead.
+\fBThis function is deprecated.\fP Use \fIcurl_mime_init(3)\fP instead.
 
 curl_formadd() is used to append sections when building a multipart form
 post. Append one section at a time until you have added all the sections you

I think the doc warning is enough. We could put it in bold,

Good idea. But I fear a lot of people do cut n' paste old programs and do not read the doc :-(

Now that the deprecation patch has been applied, I've removed the compilation-time warning.

it would be very nice to give some examples of how to convert curl_formadd to curl_mime_init .... as the logic is completely different. thanks

it would be very nice to give some examples of how to convert curl_formadd to curl_mime_init .... as the logic is completely different. thanks

Well... this is a doc request and should be set in a separate issue, as it is not related to introducing conditional compilation for form api.

FYI, there are files docs/examples/postit2.c and docs/examples(postit2-formadd.c that both implement the same form filling using mime and form api respectively. Similarly you can compare docs/examples/multi-post.c and docs/examples/multi-formadd.c.

@bagder: what about this PR? this is essentially the introduction of form api conditional compilation like 860ca31 did for mime and does not affect builds with default options.

Thanks, and sorry for taking so long.